Basic Achievement System

[mckinlee]

Achievement System

The design has evolved substantially from the initial draft and is now at a point where core architectural feedback is both welcome and needed.

---

Current Implementation Status

• Event-driven architecture:
  Achievements are defined via required game events.
• Integration layer:
  Hooks into existing game systems (flags, scene flags, vanilla behaviors) to minimize intrusive code changes.
• Save system integration:
  Achievement state is persisted using JSON serialization, fully compatible with the current save file structure.
• UI components:
  Dedicated achievements window and real-time notification system are implemented.
• Developer tools:
  Includes a comprehensive editor for testing, validation, and diagnostics.

---

Key Features Implemented

• Conditional hook registration:
  Hooks only activate when achievements are enabled; system is low-overhead when disabled.
• Event queuing and timing restrictions:
  Prevents notification spam by enforcing timing between achievement popups.
• Progress tracking:
  Supports multi-event achievements and partial progress.
• Category-based filtering:
  (General, Vanilla, Randomizer) for organization and future extensibility.
• Comprehensive validation and diagnostics:
  Developer tooling enables rapid iteration and validation.
• Save integration:
  Achievements are seamlessly integrated with existing save data.

---

Build Artifacts

• 2ship-windows.zip
• 2ship-linux.zip
• 2ship-mac.zip

[mckinlee]

Changelog for commit 2c3a8da

Refactors the achievement system to use an enum (AchievementId) for IDs instead of strings and integrates state directly with the save context (gSaveContext.save.shipSaveInfo.achievements).

Key Changes:

• Introduce AchievementTypes.h for AchievementId enum.
• Replace string-based achievement IDs with AchievementId enum across the system.
• Rework achievement unlock/queue logic to prevent queuing during save load/initialization using a new mIsLoadingOrInitializing flag.
• Remove internal mCurrentAchievementStates map; achievement state now reads directly from/writes directly to the save context struct.
• Update save structure (z64save.h) to use AID_MAX and AllAchievementsInfo.
• Implement OnSaveLoad and OnGameStateMainStart hooks to manage the loading flag and reset the queue appropriately.
• Remove LoadFromSaveData and ResetStatesForNewGame in favor of new hook-based logic.
• Rename UnlockAchievement to DebugUnlockAchievement.
• Add extensive debug logging (SPDLOG).
• Update Achievements window (AchievementsWindow.cpp) to filter progress calculation by relevant game mode and use names for ImGui IDs.
• Remove deleted save migration 7 and revert CURRENT_SAVE_VERSION to 6.
• Clean up unused includes and achievement icon loading in ShipUtils.cpp.

[mckinlee]

This has come a long way from the initial draft. The achievement system is now in a state where I'm comfortable getting feedback on the system design and implementation approach. The system is built to be extensible - adding new achievements just requires defining events and mapping them to game conditions.