Maintenance reference¶
Historical source snapshot: These notes describe the legacy input, menu and persistence paths inspected in October 2026. The approved input replacement is not reflected throughout this page. Use the roadmap, handoff and current source before changing a system. Save-format and path details remain reference evidence, not permission to modify user saves.
Source-checked 2026-10-24. These notes replace the overlapping active setup/implementation guides. For defects and suspected behavior, use the issue register.
Controller detection¶
The current UI component is JoystickRefreshPanel, backed by InputManager and GameSettings.
ShowPanel() opens the panel and displays detected controller count. Refresh calls InputManager.RefreshJoysticks(), updates the count and player joystick UI, then restarts auto-hide. Serialized references are the status/count labels, refresh/close buttons, and panel object. The default auto-hide delay is three real-time seconds, including while game time is paused; batch 02 verifies the timer in Play Mode. Player preset keys are P1_Joystick and P2_Joystick.
JoystickDetectionPage.cs, JoystickDetectionView.cs, and ControllerItem.cs contain the commented-out alternative. Do not follow the archived quick-start instructions to add an active controller list or layout override; that would be feature work. Physical-controller reconnection and player assignment still require testing.
Save/config ownership and paths¶
SaveManager owns Player, Config, IsReady, StartupAsync(bool), SavePlayerData(), SaveConfig(), reset/backup methods, and OnSaveReady. Save is the static facade; SaveService performs IO. FileConst defines filenames; SavePathResolver.cs defines both resolver classes.
| Data | Current filename / path policy |
|---|---|
| Player progression | player_v2.json.enc, encrypted JSON; JsonUtils uses Newtonsoft.Json. |
| Settings | config.json; current SaveService.ReadJson<T> uses Unity JsonUtility, while SaveConfig writes via JsonUtils. Do not assume both readers are interchangeable for arbitrary models. |
Modern Windows compile-target root (UNITY_STANDALONE_WIN) |
Documents / TinyChaos / Beta or Main / Steam ID or offline. |
| Modern other compile-target root | Application.persistentDataPath / TinyChaos / Beta or Main / Steam ID or offline. |
| Legacy Windows primary root | Documents / KatrGames / TinyChaos / Steam ID; player.dat. Additional no-ID discovery exists but has a gate problem (SAVE-02). |
| Legacy other-platform root | Application.persistentDataPath; supported migration behavior needs verification (SAVE-02). |
The modern resolver uses a compile-target guard; legacy and leaderboard-cache paths use a runtime WindowsPlayer/WindowsEditor guard. Windows Editor behavior must be checked under its actual target symbols. The modern folder is named Main, not Release. The bootloader currently serializes betaVersion: 0. SaveManager records Player.version = Application.version on save, so release metadata disagreement can affect save version fields too.
The persistence/UI/service contract now owns the proposed rebuild boundary and detailed source schema/preset/lifetime maps. It does not change the implementation described here.
Back up disposable copies before testing migration/reset/failure handling. Existing save-file presence selects the load path, not necessarily a valid schema. The legacy resolver now coalesces null Steam identity to the existing empty-ID path component (SAVE-01, batch 01); this path-construction fix does not validate legacy discovery or migration.
SaveDataDebugger is a static diagnostics helper, not an Editor window. Existing creation code calls RunFullDiagnostic; other diagnostic calls are commented out. It checks dictionaries and logs data. The old guides' SavePlayerDataWithoutEncryption and LoadPlayerDataWithoutEncryption methods are absent from SaveManager. Do not call or recreate them as part of routine setup. Use the current source as authority for available helpers.
Menu, transitions, and localization¶
The menu implementation uses MenuController, Page, view/controller components, and HyperspaceTransition. SplashUIController owns splash/startup scene coordination. Inspect serialized scene/prefab references and UnityEvent targets before changing navigation or transitions; old "add component" instructions are implementation history, not required setup on an existing scene.
MainMenuManager's scene references must point to its existing MenuController and CharacterManager; both are wired and player-menu initialization is verified in batch 06. CharacterSelectionUIController.cs still declares CharacterManager. Its enable-time initialization waits for GameDataLoader readiness, defers UI setup until scene lifecycle callbacks have begun, and cancels pending setup on disable. Re-enabling an initialized component refreshes current text without resetting player choices. A paired LocalizationSettings.SelectedLocaleChanged subscription refreshes the current active characters and mode label; it does not attach cleanup to a previous selection's LocalizedString. Full interaction/locale/co-op acceptance remains pending.
UnityEvent navigation requires a valid target, method, argument type/value, and call mode. TutorialButton now invokes the existing MainMenuManager.StartTutorial handler; the five difficulty buttons invoke MainMenuManager.PlayGame(int) with preserved values 0–4. RuntimeOnly events do not execute in Edit Mode: checks use a disposable preview with a temporary EditorAndRuntime override and an existing scene-transition guard, then close without saving. Binding/guarded-dispatch evidence and actual player coverage are separate; see batches 08 and 13.
For legacy component repairs, use Git history to establish GUID, serialized-field, enum, and event-argument identity. Preserve object IDs and migrate saved data with the script binding. Package layout GUIDs may resolve outside Assets. Batch 10 restores panel/tab bindings and verifies Tutorial pause/settings/tab navigation/Back/resume. That pass does not certify settings loaded values/Apply or migrate gameplay Pages in every arena.
Keep the loaded-Bootloader activation owner for cold preload. On direct MainMenu re-entry, SceneInitializer enables wired components and restores time scale 1 before UI Start, then starts the existing transition; batch 11 verifies two paused Tutorial returns. The logo-skip path lets its awaited iterator finish through a skip flag, retaining task readiness and scaled phase timing; batch 12 verifies this separately from other startup failure recovery and optional Discord failures.
GameInitialization now awaits reward reset, spawn/manager data, and player preparation before yielding GameManager.OpenGate. That routine configures the gameplay menu, resumes, starts timers, opens the entry gate, and shows HUD. The separate MenuController.GateAnimationOpen restores opening sound/music/motion and never calls the closing transition's scene-change callback. Batch 14 verifies early Meadow gameplay and movement. Batch 15 repairs and player-verifies live Meadow pause/resume: empty-stack Back delegates to the scene owner, that owner closes its root explicitly without redispatch, and UI animation/delay uses independent time. Batch 16 restores existing restart/return confirmation routes and verifies No/Escape cancellation, one Meadow retry, and two arena returns. Closing uses a fully constructed independent-time sequence, with owner checks preventing stale completion/overlay changes; GAME-23 is repaired and player-verified. Batch 20 completes and player-verifies Meadow game-over confirmations, No/Back/focus, retry, and MainMenu return; Page now disables hidden keyboard interaction. Batch 21 repairs MainMenu quit/corner Exit and focus ownership and verifies actual quits before/after arena entry. Controller page-pop notification lets the owner restore focus after parent input; configuration replaces its previous owner callbacks while preserving observers. GAME-24 still owns Settings/Database/focus and later-stage menus. Batch 17 guards Save.Nickname with Steam readiness and the existing NewPlayer fallback, allowing local result/save completion. An explicit client-availability gate excludes score preparation when Steam is unavailable; this does not verify backend authentication. Online/Windows acceptance remains open; Meadow result routes now have batch-20 evidence.
GameStateService separates menu pause, rewarding, game over, and boss-defeated state. GameMenuManager integrates in-run navigation. A declared blocking policy does not establish that every caller updates time scale consistently; verify GAME-02 before relying on reward/pause behavior.
LocalizedTextHandler, namespace TinyChaos.UI, holds pairs of TMP_Text and LocalizedString in textPairs. It subscribes to LocalizationManager.OnLocaleChanged on enable, unsubscribes on disable, and refreshes on enable by default. Existing public helpers include RefreshTexts, AddTextPair, and removal support. Edit existing text bindings; do not create a parallel localization controller for a static panel.
Editing discipline for stabilization¶
Preserve Unity asset GUIDs and .meta files when moving assets/scripts. Keep serialized fields and UnityEvent method bindings in mind when renaming. Follow the active rebuild plan for architectural changes; archived extraction/reorganization proposals are evidence, not automatically the chosen target. Planning is active before runtime implementation. The historical catalog/behavior maps are archived reference material, not feature commitments or proof that content is released.
Settings views now initialize after save/settings/input readiness and own their named slider listeners, removing them on disable/rebind. GameSettings has no scene-control references; its applied graphics state survives view/scene initialization. Use non-notifying control refresh plus explicit SwitchToggle presentation refresh; do not invoke edit callbacks merely to load values. Preserve recovered UI IDs and verify active Page destinations, actual contents, Back/focus, and reciprocal animation-speed units. See batch 23 for checks/player evidence and remaining startup/controller-route limitations.
Batch 24 verifies graphics preference restoration and explicit session overrides. Keep valid legacy resolution indices authoritative over stale dimension fields, preserve config while selecting launch overrides, and compare actual applied dimensions rather than nearest indices alone. Startup must await shared graphics completion before releasing input/menu loading. Scene preloading with activation disabled finishes preparation at progress 0.9; wait for actual activation before querying scene objects, and keep repeated preload callers on the same task. Frame-poll bounds do not interrupt native display calls or background suspension. Read the batch for real timing, excluded trials and Windows limits.
Tutorial menus use the shared MenuController/Page stack. TutorialMenuController owns pause, child navigation and transition admission; TutorialManager owns lessons and actual scene/gate operations. Keep player pause gates pointed at the menu owner rather than recreating flags in the lesson manager. Settings owns the Credits child: tests and player probes must expose that tab before invoking it. Preserve page object IDs and bind No to cancellation, with No as the return dialog's first focus. Batch 25 records the migration and its verification status.