Skip to content

Archived on 2026-10-24. The Godot rewrite is cancelled. Migration decisions and work checklists below are withdrawn. Original claims, code examples, file paths, and completion statements have not all been revalidated. Use the current documentation and issue register for maintenance decisions.

Save Data And Progression Analysis

Purpose

This system stores player progression, settings, unlocks, achievements, shop upgrades, run counters, and platform-related identity data.

Current Unity Implementation

Main scripts:

Path Script Role
Assets/Script/App/Core/AppInitiator.cs AppInitiator Starts service/save loading before main menu.
Assets/Script/App/Core/SaveManager.cs SaveManager Owns loaded PlayerData and GameConfig; handles new save, legacy migration, reset, backup.
Assets/Script/App/Data/Save.cs Save Static facade into SaveManager and Steam nickname.
Assets/Script/TinyChaos/Services/Save/SaveService.cs SaveService File IO, new/legacy paths, JSON/binary read, backup.
Assets/Script/TinyChaos/Services/Save/SavePathResolver.cs SavePathResolver, NewSavePathResolver Save path rules.
Assets/Script/TinyChaos/DataModels/PlayerData.cs PlayerData Progression save model.
Assets/Script/TinyChaos/DataModels/GameConfig.cs GameConfig Settings save model.
Assets/Script/Shared/GameDataCount.cs GameDataCount Run counters and achievement trigger conditions.
Assets/Script/App/Managers/AchievementManager.cs AchievementManager Loads/saves achievements, rewards unlocks, Steam sync.
Assets/Script/App/Managers/ShopManager.cs ShopManager Loads/saves shop upgrades and applies shop modifiers.
Assets/Script/Game/Resources/GameDataLoader.cs GameDataLoader Loads and saves unlock states to/from resources and save dictionaries.

Key Data

PlayerData:

  • version
  • soulPoint
  • chaosFragment
  • unlockedChar: Dictionary<string, bool>
  • unlockedAchievement: Dictionary<string, bool>
  • unlockedSpecialUpgrade: Dictionary<string, bool>
  • shopUpgrade: Dictionary<string, int>
  • unlockedStage: Dictionary<string, bool>
  • totalDataCounter: Dictionary<string, int>
  • legacyMigrated
  • isFirstLaunch

GameConfig:

  • volume: master, music, sfx, footstep
  • graphics: width, height, fullscreen, vsync
  • damage indicator enabled/limit
  • language selection
  • keybind preset list

Save static facade exposes:

  • currencies and dictionaries,
  • config fields,
  • save/reset calls,
  • Nickname from SteamFriends.GetPersonaName().

Runtime Flow

Startup

  1. AppInitiator.RunStartupFlow() reads Steam id if SteamManager.Initialized.
  2. ServicesRoot.InitializeServices(steamId) creates AudioService and SaveService.
  3. SaveManager.StartupAsync(betaVersion) loads/migrates player data and config.
  4. SaveManager.OnSaveReady notifies systems such as AchievementManager and ShopManager.
  5. GameSettings.Instance.LoadSettingsFirstTime() applies saved settings.

Player Data Loading

  1. If the new encrypted save exists, LoadNewEncryptedSave() reads encrypted text, decrypts, and deserializes PlayerData.
  2. If only legacy binary save exists, MigrateLegacySaveAsync() reads all legacy binary streams, merges data, saves into the new path.
  3. If no save exists, CreateNewPlayerData() initializes defaults from current data assets and saves.

Default Unlocks

PlayerData.InitializeDefaults():

  • unlocks SOLDIER, KNIGHT, and CELESTIAL by default unless beta mode unlocks all.
  • unlocks 1_EASY and 1_MEDIUM stages by default unless beta mode unlocks all.
  • unlocks special upgrades unless they require achievements.
  • creates empty counters and shop/achievement dictionaries.

Run End Progression

GameManager.GameOver():

  1. Adds soul and chaos fragment rewards.
  2. Adds run counters through GameEvents.OnDataCount.
  3. Calls GameDataCount.GameEndValueToSaveData().
  4. Calls GameDataCount.GameDataToCheckAchievement().
  5. Calls Save.SaveData().
  6. If boss defeated, UnlockStage() mutates level/character assets and calls GameDataLoader.SaveResources().

Achievements

  1. GameDataCount.GameDataToCheckAchievement() checks run and total thresholds.
  2. It emits GameEvents.OnAchievementTrigger(id).
  3. AchievementManager.UpdateAchievementProgress() unlocks the achievement, grants soul/upgrade rewards, queues popup, syncs Steam, and saves.

Shop

  1. ShopManager.LoadDataShop() copies saved levels into ShopUpgrade.currentUpgradeLevel.
  2. Buying/refunding updates Save.SoulPoint, shop levels, and saves.
  3. ShopManager.ApplyShopModifiers() converts shop levels into CharacterModifiers on GameSession.

Dependencies

  • Save data depends on GameDataLoader being initialized before default save creation.
  • Unlock state is duplicated between save dictionaries and mutable ScriptableObject fields.
  • Steam is used for nickname and achievements.
  • SaveService performs synchronous file IO for most reads/writes.
  • AchievementManager and ShopManager are static and subscribe to SaveManager.OnSaveReady.

Problems / Risks

  • Runtime resource mutation can drift from save data if not carefully loaded/saved.
  • Save.Nickname directly calls Steam. If Steam is unavailable, nickname behavior needs confirmation.
  • SaveService uses synchronous file operations; likely fine for small data, but avoid during gameplay hot paths.
  • Legacy migration uses BinaryFormatter, which should not be carried forward.
  • Achievement and shop managers are static and event subscriptions are not obviously unsubscribed.
  • GameDataCount.GameEndValueToSaveData() appears to call GameEndCheckBestValue(GameManager.instance.level, DataCountType.BestScore); this may be intended as best level but uses BestScore. Needs confirmation.
  • Save dictionaries rely on string ids; id migrations need explicit mapping.

Migration Notes for Godot

Preserve:

  • Save data shape and ids for compatibility where possible.
  • Currencies: soul points and chaos fragments.
  • Unlock dictionaries and counter ids.
  • Old shop upgrade levels and costs only as save-conversion/reference data.
  • Achievement ids and rewards.
  • Stage unlock behavior.

Redesign:

SaveService
- load/save JSON or encrypted JSON
- versioned migration pipeline
- no BinaryFormatter equivalent

ProgressionState
- authoritative runtime copy loaded from save
- no resource mutation as source of truth

AchievementService
- evaluates rules or receives trigger ids
- queues popup signals
- optional platform adapter

ShopSaveConverter
- reads old shop upgrade levels during legacy save migration
- refunds old shop values into soul points
- does not recreate the old shop UI/system

Do not copy:

  • Static Save facade as the only access path.
  • Steam calls inside generic save accessors.
  • Runtime ScriptableObject/resource mutation as save authority.

Open Questions

  • Exact legacy .dat player data and .json config schema to import.
  • Exact soul point refund value calculation for each old shop level.
  • Whether Steam nickname should remain mandatory.
  • Which counter ids are final and which are old/deprecated.