project_status.md

Project Status

Current Phase: Maintenance Last Update: 2026-04-21

Completed

• Core System: ScreenReader (Tolk), MelatoninAccess (MelonLoader Mod).
• Menu Accessibility: MenuHandler announces all menu options, titles, and toggles.
• Gameplay Accessibility: RhythmHandler provides audio cues for all rhythm inputs.
• Tutorial Accessibility: DialogueHandler reads all dialog boxes.
• Map Accessibility: MapHandler implements teleport navigation using Bracket keys.
• Level Editor: EditorHandler announces cursor position, tools, and placement.
• Achievements: AchievementsHandler reads the achievement list.
• Build & Install: Successfully compiled and deployed to Game Mods folder.
• v1.3.0 Released (2026-04-21): Committed the final feature-build changes, pushed master and tag v1.3.0, and published GitHub release v1.3.0 as the latest release with the verified MelatoninAccess-v1.3.0.zip package.
• v1.3.0 Final Feature Release Prep (2026-04-21): Bumped runtime/project/package version metadata to 1.3.0, added the 1.3.0 changelog entry, refreshed README release examples and F1 wording to mention stars/rings/perfects, built Release, verified localization + cutscene QA, rebuilt the release ZIP after catching a stale parallel-packaging DLL issue, confirmed the final package contains MelatoninAccess.dll 1.3.0.0 with the expected Mods, UserData, and root NVDA/Tolk layout, and deployed the matching Release build to the game Mods folder.
• v1.2.0 Release Prep (2026-04-16): Bumped version metadata to 1.2.0, added a short nontechnical changelog entry, aligned README/install wording with the wrapper scripts, and updated release packaging to preserve a copy-paste-ready layout with Mods\cutscene-ad, Mods\localization, root Tolk.dll, root nvdaControllerClient32.dll, and UserData\Loader.cfg.
• Environment Path Refresh (2026-04-16): Updated checked-in local defaults from the old D:\games\steam\steamapps\common\Melatonin install path to L:\SteamLibrary\steamapps\common\Melatonin across AGENTS.md, the project file, and helper scripts.
• v1.2.0 Released (2026-04-16): Built Release locally with scripts\Build-Mod.ps1, verified the scripts\Build-ReleasePackage.ps1 ZIP layout (Mods, UserData, root DLLs), pushed master and tag v1.2.0, and published the GitHub release with the verified copy-paste package.
• README Cleanup Pass (2026-04-16): Reorganized README.md into a player-first layout with quick install, controls, hotkeys, languages, and settings up top, then condensed maintainer-only build/package/QA notes into a separate lower section.
• Template Refresh Migration Completion + Re-Decompile (2026-04-08): Restored Melatonin-specific AGENTS.md values after the refreshed template update, re-applied repo-specific .gitignore safeguards, added scripts/Build-Mod.ps1 and scripts/Deploy-Mod.ps1 as the required build entry points, validated both wrapper scripts, and regenerated local ignored decompiled/ from the current Assembly-CSharp.dll with ilspycmd (249 .cs files).
• Template Refresh Migration Start (2026-03-04): Created branch migration-to-an-updated-template, merged legacy .gitignore protections into the refreshed template version ([Ll]atest.log, release/, artifacts/, MelonLoader DLL ignore with template/libs allowlist), and re-filled AGENTS.md project-specific setup/build values (Melatonin game path, x86 architecture, MelonLoader, concrete build/deploy paths) after template replacement.
• Setup Refresh (2026-02-09): Re-ran setup checks, filled environment placeholders in AGENTS.md, and added CopyToMods auto-deploy target to MelatoninAccess.csproj (validator: 16 OK, 0 warnings, 0 errors).
• Template Setup Sync (2026-02-23): Applied updated setup-template additions in AGENTS.md and filled project-specific environment/build values (game path, x86 architecture, MelonLoader, concrete build/deploy paths).
• Game API Heading Alignment (2026-02-23): Renamed core docs/game-api.md section headings to match the updated setup-template Phase 1 labels (1.1 structure, 1.2 input, 1.3 UI, 1.5 localization, 1.7 status/feedback, 1.8 events, 1.10 tutorial) without changing documented findings.
• README Terminology Consistency Pass (2026-02-23): Aligned README wording with current behavior (score mode started only; practice-start line removed), clarified AnnounceRhythmCues as a legacy key naming contextual cues, and switched build command code blocks to PowerShell examples.
• Template Docs + State Manager Assets Sync (2026-02-23): Synced updated template docs (setup-guide, ACCESSIBILITY_MODDING_GUIDE, state-management-guide, project_status template) and added templates/AccessStateManager.cs.template from the refreshed template pack.
• Localization JSON Externalization (2026-02-23): Migrated all mod translatable strings from hardcoded Loc.cs entries to external localization/loc.<lang>.json files (all 10 game languages), refactored Loc runtime loading/path resolution to JSON assets, updated localization/cutscene QA scripts to validate JSON sources, and updated build/release packaging to ship Mods/localization.
• Cutscene AD Multilingual Localization (2026-02-23): Localized all ad_* cutscene description lines into zh-Hans, zh-Hant, ja, ko, vi, fr, de, es, and pt JSON files so cutscene narration no longer falls back to English in non-English game languages.
• Localization Runtime Fallback Fix (2026-02-23): Fixed startup regression where JsonUtility returned empty localization arrays at runtime by adding UTF-8 BOM stripping and a deterministic fallback parser for localization/loc.*.json, restoring key loading and preventing spoken key IDs.
• Localization Startup Log Noise Reduction (2026-02-23): Replaced per-language fallback warnings with one startup summary line in Loc when fallback parsing is used, while keeping detailed fallback-language output gated behind debug logging.
• Chinese Localization Import + Local Log Ignore (2026-02-23): Imported tester-provided zh-Hans localization updates (localization/loc.zh-Hans.json) after QA validation, and added [Ll]atest.log to .gitignore to keep shared root log files out of commits.
• Tutorial Extraction (2026-02-09): Extracted tutorial/help text and flow context into docs/tutorial-texts.md; updated docs/game-api.md with tutorial start path, skip behavior, and text-source notes. Deep asset pass recovered additional gameplay instruction lines from Melatonin_Data\level0 (metronome, timing circle, score mode readiness, and auto-restart behavior).
• Duplicate Announcement Reduction (2026-02-09): Added targeted debounce for dialog text (DialogueHandler), language/start screen (StartScreenHandler), and map mode menu (MapHandler), plus stronger whitespace/time normalization in ScreenReader. Build succeeded and DLL auto-copied to game Mods folder.
• Duplicate Announcement Reduction Pass 2 (2026-02-09): Removed additional duplicate bursts in AchievementsHandler and ExtraMenusHandler (community next/prev page and calibration activation/description) with short cooldown-based dedupe. Build succeeded and deployed.
• Localization Framework (2026-02-09): Added Loc.cs, language auto-refresh via SaveManager.GetLang(), and routed mod-originated announcements through localization keys for all game-supported languages.
• Editor Completeness Pass (2026-02-09): Added narration for AdvancedMenu (activate, tab swap, row changes, value changes) and TimelineTabs (Show, NextTab, PrevTab).
• Lock-State & Map Input Completeness (2026-02-09): Added explicit spoken lock reasons for map mode and stage-end options, plus bracket-action conflict handling with F9/F10 teleport fallback.
• Debug Toggle Fix (2026-02-09): DebugMode now defaults OFF and is toggled at runtime with F12, with spoken on/off confirmation.
• Credits Accessibility (2026-02-09): Added credits sequence narration, including scrolling credit entries.
• README Added (2026-02-09): Wrote README.md with controls, navigation flow (including bracket/up-arrow usage), localization coverage, and install/build instructions.
• Menu Speech Unification + Welcome Prompt Update (2026-02-09): Combined predictable opening announcements into single utterances (menu title + first item where applicable), and replaced the title-screen welcome line with a localized controller-aware prompt (Press [Action] to begin, Press [Language Key] to change language).
• Playtest Follow-up Fixes (2026-02-09): Removed F1 behavior, added position announcements for language/mode menus, merged results + initial stage-end choice into one utterance, improved tutorial dialog capture in followers, changed tutorial start label to a localized skip prompt, and added gamepad snap-to-hotspot input (Action Left/Right, e.g. LB/RB).
• Followers Tutorial Graphic Text Fix (2026-02-09): Added DialogBox.ChangeToGraphic narration path for left/right graphic tutorial text blocks and reinforced practice-start wording as localized tutorial skip prompt.
• Graphic Dialog Punctuation Cleanup (2026-02-10): Adjusted dialog part joining to avoid duplicate punctuation when graphic tutorial lines already end with sentence punctuation.
• Map Hotspot Chatter Reduction (2026-02-10): Added same-landmark debounce in MapHandler so rapid collider re-entries no longer spam repeated hotspot arrival lines.
• Teleport Star Grammar Fix (2026-02-10): Added singular star localization key and switched teleport arrival speech to use singular/plural variants correctly.
• Optional Announcement Toggles (2026-02-10): Added ModConfig.cs using MelonPreferences with toggles for map hotspot speech, rhythm cues, tutorial/dialog narration, and credits narration.
• Speech Regression Checker Script (2026-02-10): Added scripts/Test-SpeechRegression.ps1 to scan MelonLoader logs for consecutive duplicate SR lines and known forbidden patterns.
• Localization Consistency Pass (2026-02-10): Improved non-English coverage for startup loaded message, results summary wording, and Vietnamese space cue label.
• README Release/Testing Update (2026-02-10): Expanded README.md with controller-aware navigation guidance, MelonPreferences toggle documentation, and speech regression script usage examples for post-playtest validation.
• Runtime Settings Hotkeys + Persistence (2026-02-10): Added F2 runtime toggle for rhythm cue announcements with immediate MelonPreferences save, and moved F12 debug toggle to persistent config-backed state restored at startup.
• Multilingual Smoke Audit (2026-02-10): Verified localization coverage for critical lines (intro_welcome, tutorial_skip_prompt, results_stats, lock reasons, credits_title) with placeholder consistency checks across all supported languages.
• Speech Regression Check Pass (2026-02-10): Ran scripts/Test-SpeechRegression.ps1 against current MelonLoader\Latest.log (8 speech lines, 0 errors, 0 warnings).
• Release Prep Artifacts (2026-02-10): Added CHANGELOG.md, bumped mod version to 1.1.6, and packaged release\MelatoninAccess-v1.1.6.zip (DLL + README + changelog + regression checker script).
• Release Tag Prepared (2026-02-10): Created local annotated tag v1.0 at commit 49d1505 per release naming request.
• Release Dependency Bundling (2026-02-10): Added tracked libs\x86\Tolk.dll and libs\x86\nvdaControllerClient32.dll, updated ignore rules to keep these DLLs in repo, and added scripts\Build-ReleasePackage.ps1 to generate v1.0 release ZIP with only Mods\MelatoninAccess.dll + required Tolk/NVDA client DLLs.
• README Install Instructions Expanded (2026-02-10): Added explicit step-by-step install guidance for release ZIP and source-build workflows, including exact destination paths for mod and dependency DLLs.
• README Support + Installer Link Update (2026-02-10): Added Buy Me a Coffee support message and direct MelonLoader installer link in release installation steps.
• Map Teleport Double-Trigger Fix (2026-02-10): Added teleport dispatch guard (same-frame + short cooldown) and edge-based gamepad action detection so one key/button press maps to one teleport step.
• Bugfix Release Published (2026-02-10): Released v1.0.1 on GitHub as latest with map teleport double-jump fix and updated install/readme notes; attached minimal package (Mods\MelatoninAccess.dll, Tolk.dll, nvdaControllerClient32.dll).
• Settings Value Timing + Results Comment Fix (2026-02-10): Adjusted option value-change speech to read after a short post-input delay (prevents stale pre-change value reads in display/calibration-style settings), and extended results narration to include WavesBox comment text in addition to score/stats/menu option.
• Settings/Calibration/Localization Polish (2026-02-10): Added resolution-specific post-refresh value announcement logic to avoid stale reads, combined calibration hint with calibration menu opening into one utterance, and localized map dream/level names through Loc.GetDreamName() keys across all supported game languages.
• Bugfix Release Published (2026-02-10): Released v1.0.2 on GitHub as latest with resolution value-timing fix, calibration menu utterance merge, and localized map level-name announcements; attached minimal package (Mods\MelatoninAccess.dll, Tolk.dll, nvdaControllerClient32.dll).
• Global Menu Position Toggle (2026-02-10): Added persistent F3 runtime toggle (AnnounceMenuPositions) that enables/disables position context (X of Y) across option menus, language/mode menus, achievements, stage-end options, and downloaded-level row/page narration; added localized toggle confirmations for all supported languages.
• Release Bundle Loader Config (2026-02-10): Added tracked UserData\Loader.cfg (copied unchanged from maintainer install) and updated scripts\Build-ReleasePackage.ps1 to always include it in release ZIPs under UserData\Loader.cfg.
• Release Published (2026-02-10): Released v1.0.3 on GitHub as latest with global F3 menu-position toggle and bundled UserData\Loader.cfg in the release package.
• Release Notes Formatting Fix (2026-02-10): Rewrote GitHub release bodies for v1.0, v1.0.1, v1.0.2, and v1.0.3 using proper multiline markdown so headings/lists render correctly (removed literal \n text artifacts).
• Map Progress Hotkey + Gamepad Input Source Fix (2026-02-11): Added map-only F1 announcement for current landmark progress (stars collected and stars still needed to pass), and removed ctrlType dependency from map teleport gamepad detection so Action Left/Right navigation assist keeps working after keyboard input.
• Map Progress Hotkey Refinement (2026-02-11): Updated F1 to announce map/chapter-level star totals (matching TotalBox behavior) instead of nearest-landmark stars; summary now reports total chapter stars and remaining stars to pass threshold.
• Release Published (2026-02-11): Released v1.0.4 on GitHub as latest with map-summary F1 behavior and map gamepad input-source handoff fix.
• v1.0.5 Local Prompt + Mode-Title Pass (2026-02-11): Rhythm tutorial cues now announce dynamic action prompts (Press {Action} / Hold {Action}) based on rebind/controller context instead of hardcoded Space, and mode-menu open narration now prepends the localized full dream title (Dream about {Level}. Mode menu...).
• Localization QA Automation (2026-02-11): Added scripts\Test-LocalizationQA.ps1 to validate full Loc.cs coverage and placeholder parity across all supported languages; integrated automatic execution into scripts\Build-ReleasePackage.ps1 (with -SkipLocalizationQa override) and documented usage in README.md.
• Context Help Hotkey (2026-02-11): Added global F11 context-aware control help (ContextHelpHandler) with localized prompts for title screen, generic menus, map navigation, mode menu, gameplay, results, and editor contexts.
• Tutorial/Dialog + Community Loader Follow-up (2026-02-11): Added delayed reads to DialogBox.SetDialogState to reliably capture initial tutorial text lines, and prevented editor_ready from announcing on downloaded/community-level loader path (LvlEditor with non-empty downloadFilePath).
• Per-Level Completion Briefing Reverted (2026-02-11): Removed mod-generated level-start briefing per user preference to keep startup narration limited to game-provided/tutorial text.
• Release QA Spot Check (2026-02-11): Ran pwsh -File .\scripts\Test-LocalizationQA.ps1 (116 localization keys parsed, 0 errors, 0 warnings).
• Packaging QA Gate Verification (2026-02-11): Ran pwsh -File .\scripts\Build-ReleasePackage.ps1; confirmed localization QA executes in packaging flow and Build-ReleasePackage.ps1 is configured to exit with the QA failure code on localization check failure.
• Cutscene AD Timing Pipeline (2026-02-11): Added data-driven intro/outro timing scaffold (cutscene-ad/manifest.json + per-cutscene JSON files), validator script (scripts\Test-CutsceneAdPipeline.ps1) for ordering/overlap/missing-entry checks, initial C# loader/validation models (CutsceneAdPipeline.cs), and workflow docs (docs/cutscene-ad-pipeline.md + README.md section).
• Runtime Startup Fix (2026-02-11): Removed System.Runtime.Serialization runtime dependency from CutsceneAdPipeline (startup FileNotFoundException in MelonLoader), switched to Unity JSON path with UnityEngine.JSONSerializeModule reference, and verified clean local build.
• Dialogue Coverage Pass (2026-02-11): Expanded DialogueHandler to cover DialogBox.Show() in addition to existing dialog hooks, added speaker-label prefixing when the in-game label is visible, and kept debounce-safe delayed reads for rapid dialog state changes.
• v1.0.5 Accessibility Bugfix Pass (2026-02-11): Reduced duplicate dialog narration bursts (especially tutorial Redo/state transitions), changed standalone tutorial chapter side label to Tutorial (no misleading skip prompt), blocked map snap assist while map input is disabled/cutscenes are active, added calibration timing callouts (early/late in milliseconds), improved action-key option speech to include current binding, expanded community level row speech with subtitle/tags context, fixed locked-achievement detection using checkmark state, and stopped credits roll narration when pause/title menus are active.
• v1.0.5 Tutorial + Community + Credits Follow-up (2026-02-11): Updated credits narration to pause/resume across pause menu without losing position, merged downloaded-level initial/page-change narration into one utterance with first playable row context, switched action-key option binding speech to keyboard mapping only, and added chapter-1 tutorial cue overrides (tech double-press callout, followers rhythm/stop guidance, food beat-target guidance, shopping pattern guidance). Added new localization keys, refreshed docs/game-api.md with row-layout and chapter-1 cue findings, and tracked completion in todo.md.
• v1.0.5 Log-Driven Fixes Pass 2 (2026-02-12): Fixed downloaded-level page-change utterance targeting by waiting for async row repopulation and summarizing from the highlighted row, prevented trailing credits narration when exiting to title by stopping narration on Creditor.ExitToTitle, added one-time tutorial-chapter metronome hint (Press {Action} on the second beat), moved shopping pattern guidance earlier to song start, refined followers guidance with section-specific vibration timing prompt (and removed premature double-press callouts), tightened tech double-press detection to rapid sections only, and added remaining-practice contextual-cue expansion to todo.md.
• Localization Polish Pass (2026-02-12): Updated Spanish dream-name accents (Tecnología, Presión, Meditación, Estrés), switched language/achievements menu title announcements to prefer live game UI title fragments over mod-owned title strings, and expanded README.md acknowledgements for localization/testing contributions (luyi, dreamburguer). Added corresponding API note in docs/game-api.md.
• Chinese Dream-Title Format Fix (2026-02-13): Updated dream_about_level localization format to use natural Chinese phrasing (梦见{0} / 夢見{0}) instead of literal about ... dream wording.
• Tech/Time Cue Clarification + Spanish Accent Pass (2026-02-14): Refined Dream_tech tutorial wording to key off the high cue (next beat / next 3 beats), added Dream_time scene-specific hold/release prompts for portal-gap and sixth/seventh-cue timing (cue_time_portal_gap_hold_release, cue_time_sixth_seventh_hold_release), and applied broad Spanish diacritic fixes (including ñ and accent marks) across menus, objectives, and cue lines.
• Practice Start Overlap Fix (2026-02-14): Removed practice_mode_started speech trigger from RhythmHandler so practice/tutorial cue instructions are not pre-empted by mode-start announcements.
• Unity Asset Extraction CLI (2026-02-14): Added scripts/extract_unity_assets.py for command-line extraction/indexing of Unity assets (AudioClip, AnimationClip, Sprite, Texture2D, TextAsset, optional MonoBehaviour typetree export), ran a full baseline extraction to artifacts/asset-extract, documented usage in README.md, and added extraction-limit notes to docs/game-api.md.
• v1.1 Release Published (2026-02-14): Updated version metadata (Main.cs MelonInfo + project version), added CHANGELOG.md 1.1 section, pushed master, and published GitHub release v1.1 (tag and release page).
• Cutscene Experiment Branch Created (2026-02-14): Created and pushed cutscene-audiodescription-experiments from updated master for cutscene audio-description R&D.
• v1.1 Release Asset Uploaded (2026-02-14): Built package via scripts/Build-ReleasePackage.ps1 workflow, adjusted staged config folder to UserConfig, repacked release/MelatoninAccess-v1.1.zip, and uploaded it to GitHub release v1.1 with expected layout (Mods/MelatoninAccess.dll, UserConfig/Loader.cfg, root Tolk.dll, root nvdaControllerClient32.dll).
• GitHub Auto-Release Packaging Workflow (2026-02-14): Added .github/workflows/release-package.yml to build and upload the release ZIP on v* tag pushes (Windows runner, Release build, existing Build-ReleasePackage.ps1), and updated local packaging script/docs to standardize UserConfig/Loader.cfg output.
• Cutscene AD First-Pass Authoring (2026-02-14): Filled all cutscene-ad/scripts/chapter_*_{intro,outro}.json with concise first-pass timestamp/text-key entries (including map transition events like map music start, control unlock, and mirrored-map start), added matching localization keys in Loc.cs, and verified with Test-CutsceneAdPipeline.ps1 -StrictCoverage -RequireEntries -ValidateLocKeys (0 errors, 0 warnings).
• Cutscene AD Runtime + Packaging Wiring (2026-02-15): Added CutsceneAdHandler runtime playback (scene/cutscene-state detection, timed cue dispatch through Loc/ScreenReader), initialized it from Main, updated build/package flows to ship Mods\cutscene-ad automatically, and documented runtime API hooks and package layout updates in docs/game-api.md and README.md.
• Local v1.2 Tester Packaging Flow (2026-02-15): Added scripts/Build-LocalV12Package.ps1 to generate/overwrite a single local release\MelatoninAccess-v1.2.zip artifact and clean prior v1.2* package leftovers before each tester build.
• Cutscene AD Loader Retry Fix (2026-02-15): Fixed one-shot startup load issue in CutsceneAdHandler by adding periodic runtime reload attempts, broader manifest path resolution candidates, and explicit failure-reason logging; this resolves sessions where intro/outro AD remained silent with scripts are not loaded.
• Cutscene JSON Fallback Parser (2026-02-15): Added non-Unity fallback parsing in CutsceneAdPipeline for manifest/scripts when runtime JsonUtility yields empty arrays, plus stricter runtime validation for empty cutscene/entry arrays.
• Cutscene AD Content Pass 2 (2026-02-15): Replaced generic first-pass cutscene lines with chapter-specific, event-anchored descriptions across all intro/outro script files and updated Loc.cs keys accordingly (including clearer map transition/transient lines like map unlock and mirrored start).
• Dream_time Sixth/Seventh Hint Timing Fix (2026-02-15): Moved cue_time_sixth_seventh_hold_release out of early teaching by gating the (hold 1, release 2, half-hold) signature to the final teaching section in RhythmHandler.
• Dream_time Final-Section Hint + Map Transient Runtime Announce (2026-02-15): Updated Dream_time sixth/seventh cue gating to trigger on the later repeated section match (instead of first match), and added runtime map transient announcements (map controls unlocked, including mirrored-map variant) from McMap enabled-state transitions.
• Dream_time Final-Section Sequence Gate + Map Transient AD Retime (2026-02-15): Replaced Dream_time sixth/seventh heuristic timing with sequence-index gating (Dream.sequences[3] final teaching segment) so the line no longer fires in phase 2; retimed chapter intro cutscene map cues to fire before isCutsceneIntro clears; replaced generic controls unlocked wording with map-transient phrasing in runtime/map cutscene AD keys.
• Dream_time Late-Break Hint Gate + Night 3 Outro Spacing (2026-02-16): Reworked Dream_time sixth/seventh hint timing to trigger only after repeated (hold 1, release 2, half-hold) sightings and then speak on a later portal-gap break (instead of early teaching), and spread Chapter_3 outro cutscene AD timings to reduce back-to-back speech overlap.
• Dream_time Final-Transition Sequence Code Gate (2026-02-16): Switched Night 3 sixth/seventh hint timing to a deterministic final-transition gate by tracking Dream.StartSequenceDown/Up(codeNum) and speaking the hint only when the portal-gap break occurs with codeNum == 4, to force placement right before the last phase.
• Dream_time Late Song-Progress Gate (2026-02-16): Replaced Night 3 sequence-code gating with a late GetSongProgress() threshold gate and now speaks sixth/seventh guidance only on portal-gap break after late-song progress, to move the line before the final phase and out of early sections.
• v1.1 Contextual Cues Pass 1 (2026-02-12): Added scene-specific Dream_dating swipe cue narration (left/right + long-countdown variants), added one-time Dream_dating intro guidance on song start, localized new cue keys for all supported languages, and documented cue timing patterns in docs/game-api.md.
• v1.1 Contextual Cues Pass 2 (2026-02-12): Added controller mirrors for utility hotkeys (View -> map stars/F1 equivalent, L3 -> rhythm cues/F2 equivalent, R3 -> menu positions/F3 equivalent), replaced noisy Dream_tech per-hit prompts with phase-level guidance and selective rapid-double callouts, added Dream_followers phase-3 pre-brief 2 beats early, and updated map dream-name formatting to prefer live UI text when available before localization fallback.
• v1.1 Contextual Cues Pass 3 (2026-02-12): Applied the melatonin tutorials.txt cue requirements to the listed dreams only (followers, dating, time, space, desires, nature, mind, past, future), including hold/release duration narration, camera-sound-specific Dream_past hold guidance, and Dream_future directional overrides (Press Up, short Left right). Added missing localization key coverage and documented decompiled mapping details in docs/game-api.md and todo.md.
• v1.1 Contextual Cues Pass 4 (2026-02-12): Applied log-driven wording/timing refinements: moved followers phase-3 cue later (after spring-stop transition), changed Dream_future up cue to short Up, added one-time Dream_future follow patterns intro line, switched Dream_space/Dream_desires hold guidance to release-beat phrasing, simplified Dream_past lines to plain hold durations and suppressed repeated repeats, renamed F2 toggle speech to contextual tutorial cues, and appended locked remix requirement guidance to map teleport arrival lines in one utterance. Updated docs/game-api.md, todo.md, and README.md.
• v1.1 Contextual Cues Pass 5 (2026-02-12): Fixed release-beat math for Dream_space and Dream_desires to use phase-relative counting (release - hold + 1) instead of absolute queue beat values, matching requested outputs like phase 1/2/3 -> beat 4/2/7 in Space and corrected Desires beat callouts.
• Level Editor Graduation (2026-02-12): Confirmed level editor accessibility is fully supported (no longer experimental), including cursor, tool, advanced menu, and timeline narration.
• v1.1 Release Polish Pack 1 (2026-02-12): Added missing Dream_food 7th-beat practice cue coverage, added gameplay-start announcements for Practice and Score modes (TriggerSong), and completed terminology cleanup for user-facing wording from "rhythm cues" to "contextual cues" in help/objective strings and config comments. Updated docs/game-api.md, README.md, and todo.md.
• Backlog Cleanup (2026-02-12): Simplified todo.md to keep only actionable v1.1 items, moved audio-description work explicitly under deferred v1.2, and removed stale template tasks that are already implemented or not applicable (for example Dream_food jump/shoot split at queue level).
• Repository History Sanitization (2026-03-02): Purged tracked decompiled/ game-source dumps and historical bin/obj/artifacts build outputs from all branches/tags using git filter-branch, deleted rewrite backup refs, ran aggressive object pruning, and force-pushed rewritten branches/tags to GitHub.

Codebase Analysis Progress

GATE: Tier 1 MUST be complete before Phase 2 (Framework)!

• 1.1 Structure overview (namespaces, singletons) → documented in game-api.md
• 1.2 Input system — ALL game key bindings documented in game-api.md "Game Key Bindings"
• 1.2 Input system — Safe mod keys identified and listed in game-api.md "Safe Mod Keys"
• 1.3 UI system (base classes, text access patterns, Reflection needed?)
• 1.4 State management decision → documented in "Architecture Decisions" below
• 1.5 Localization: game's language system analyzed (multilingual project)

GATE: Relevant Tier 2 items MUST be done before implementing each feature!

• 1.6 Game mechanics (analyzed as needed per feature)
• 1.7 Status/feedback systems
• 1.8 Event system / Harmony patch points
• 1.9 Results documented in docs/game-api.md
• 1.10 Tutorial analysis (when relevant)

Game Key Bindings (Original)

• Arrow keys / WASD: movement and menu navigation (configurable)
• Space: Action/Select by default (rebindable)
• Escape or R: Cancel/Back (rebindable)
• Escape or controller Start: Pause
• Controller utility buttons (Unity Input System): View/Back, L3, R3
• Gameplay uses additional per-dream timing inputs (documented under docs/game-api.md)

Architecture Decisions

• State management approach: Scene-aware handler ownership and per-handler gating are used; AccessStateManager is not currently used in this project.
• Reasoning: Existing handlers are stable with localized responsibility, Harmony hook boundaries, and explicit scene/game-mode checks; no unresolved shared-input conflicts currently require a central state manager.

Next Steps

• GitHub Cache/GC Follow-up: Open a GitHub Support request to run server-side garbage collection/cache cleanup for removed copyrighted/sensitive history after force-push.
• Focused Playtest: Validate end-to-end flow for map mode locks, stage-end locks, advanced menu/timeline narration, and credits scrolling narration.
• Language Spot Check: Switch each in-game language and verify key mod-only lines (debug toggles, map lock reasons, teleport conflict hint, results summary) are spoken correctly.
• Config Spot Check: Toggle each new MelonPreferences setting and verify the targeted announcement group turns on/off without side effects.
• Hotkey Spot Check: Verify F2, F3, and F12 update behavior immediately and remain in the same state after restarting the game.
• New Feature Spot Check: On map scenes, press F1 and verify it announces chapter/map stars, rings, and perfect-run totals; on chapters 1-4 it should also append the remaining stars needed to pass. Verify F1 is silent in non-map scenes.
• Ring Progress Spot Check: On map scenes, move onto landmarks normally and with bracket/F9/F10 teleport. Verify dream announcements include both stars and rings whenever the game shows a score bubble, omit counts on untouched dreams, and still append the locked remix requirement when applicable.
• Gamepad Resilience Spot Check: Use map gamepad teleport (Action Left/Right), press any keyboard key, then confirm gamepad teleport still works without needing to open/close pause menu.
• v1.0.5 Prompt Spot Check: In tutorial/practice gameplay, rebind Action (for example to Enter, Period, Slash, and a letter key) and verify rhythm cues announce the new action prompt correctly; with controller active, verify prompts use controller action naming.
• v1.0.5 Mode Menu Spot Check: From map navigation, open multiple levels and confirm the opening line says the full dream title before mode menu/options (for example Dream about Money. Mode menu. Practice...). Verify Score/Hard entries also announce the visible star/ring values when the menu shows them.
• Context Help Spot Check: Press F11 on title screen, in regular menus, on map, in map mode menu, during gameplay, on results, and in editor; verify each context speaks relevant controls and uses current action/cancel prompts.
• Tutorial Intro Spot Check: Enter tutorial from chapter menu and verify the first instruction block (including multi-line startup warning text) is announced without hardcoded text dependencies.
• Community Loader Spot Check: Start downloaded/community level flow and verify Level editor ready is no longer announced before gameplay.
• v1.0.5 Community Summary Spot Check: Enter Downloaded Levels and verify one utterance on load (total/page + first level row + position) and one utterance on next/previous page (page action + first level row + position) without immediate duplicate row readback.
• v1.0.5 Credits Resume Spot Check: During credits, open pause menu, wait, then resume and verify narration continues from the next unread credit entry; verify narration state resets cleanly after credits finish/exit.
• v1.0.5 Tutorial Cue Spot Check: In Tech/Followers/Food/Shopping practice, verify reduced spam and scene-specific guidance lines (double-press, rhythm stop cue, beat-target lines, repeat-pattern line).
• v1.0.5 Tutorial Chapter Cue Spot Check: Start standalone tutorial chapter and confirm one-time hint is spoken when metronome gameplay starts (Press {Action} on the second beat).
• v1.0.5 Credits Exit Spot Check: From rolling credits, choose Exit to menu and verify no additional credits-entry lines are spoken after exit is selected.
• v1.1 Dream_dating Cue Spot Check: In Dream_dating practice, verify one-time intro guidance (follow swipes) and directional prompts:
  • short countdown windows (Queue*HitWindow(3)) should say Swipe left / Swipe right
  • long countdown windows (Queue*HitWindow(6)) should say Swipe left/right after the long cue
  • prompts should remain directional (not generic press action) during dating practice
• v1.1 Controller Utility Hotkey Spot Check:
  • On map scenes, press controller View and confirm it speaks the same chapter progress summary as F1 (stars, rings, perfects, plus remaining stars on chapters 1-4).
  • Outside map scenes/menus/gameplay, press controller View and confirm no map-stars line is spoken.
  • Press L3/R3 and confirm they toggle rhythm/menu-position announcements exactly like F2/F3, including persistence after restart.
• v1.1 Tech/Followers Cue Spot Check:
  • Dream_tech practice phase 1 should announce one-time Press {Action} every 2 beats.
  • Dream_tech practice phase 2 should announce one-time Press {Action} on the next 3 beats (earlier, not overlapping first target).
  • Rapid-double sections should only call out Press {Action} twice without mixed duplicate Press {Action} lines.
  • Dream_followers phase 3 should announce one pre-brief 2 beats before section start (to the beat, then press twice after vibration).
• v1.1 Dream Name Source Spot Check: In non-English map language, confirm landmark/mode-menu dream names prefer live in-game text when present and otherwise fall back cleanly (no empty/broken names).
• Calibration Validation: Confirm early/late ms values feel directionally correct against intentional early/late taps and note any offset formula tuning needed.
• Cutscene AD Timing/Wording Spot Check: Play each chapter intro/outro with first-pass scripts, validate timing against real visuals (including map transitions), and tighten any lines that overlap key SFX or important gameplay cues.
• Post-Release Validation: Monitor issues/feedback from v1.0.4 and collect any remaining edge cases from real-world play sessions.
• Release Workflow Follow-up: Fix or replace the hosted GitHub Actions release build; the current windows-latest runner cannot compile this project from a clean checkout because MelonLoader/game reference DLLs are not available there.

Session Notes

• [2026-04-21] Published v1.3.0 as the latest GitHub release using the verified release\MelatoninAccess-v1.3.0.zip package after pushing master and tag v1.3.0.
• [2026-04-21] Prepared the final feature-build package as v1.3.0: updated Main.cs/MelatoninAccess.csproj version metadata, added the CHANGELOG.md 1.3.0 entry, refreshed README release examples and map-summary wording, built Release, passed scripts\Test-LocalizationQA.ps1 and cutscene AD QA through scripts\Build-ReleasePackage.ps1, verified release\MelatoninAccess-v1.3.0.zip layout, and deployed the Release DLL to L:\SteamLibrary\steamapps\common\Melatonin\Mods.
• [2026-04-21] User-tested the new ring-aware map announcements and reported that they read correctly in-game.
• [2026-04-21] Implemented ring-aware map progress narration. F1/controller View now read the visible chapter totals (stars, rings, perfects) and still append remaining stars to pass on chapters 1-4; landmark arrival, bracket/F9/F10 teleport, and mode-menu Score/Hard entries now announce the same star/ring values that sighted players see on the map UI. Added new localization keys in all supported languages and verified both localization QA and scripts\Build-Mod.ps1.
• [2026-04-21] Researched ring progress in the decompiled game code. Rings are not hidden collectibles; they are the hard-mode (Alt) score track for each dream, with visible UI on landmarks, the mode menu, the chapter TotalBox, hard-mode results (PlanetRings), and Steam achievements. Chapter/passage unlocks still depend on stars, not rings. Added the detailed API notes to docs/game-api.md.
• [2026-04-16] Prepared the 1.2.0 release: updated version metadata and changelog, aligned README examples to scripts\Build-Mod.ps1 / scripts\Deploy-Mod.ps1, and corrected release packaging to keep UserData\Loader.cfg in the ZIP so users can copy the full archive contents straight into the Melatonin folder.
• [2026-04-16] Refreshed local path defaults to the current Melatonin install on L:\SteamLibrary\steamapps\common\Melatonin so the build, deploy, log-check, and asset-extraction helpers use the right game folder out of the box.
• [2026-04-16] Local Release build and packaging both passed (Build-Mod.ps1, localization QA, cutscene AD QA). The tag-triggered GitHub Actions release workflow failed on the hosted runner during compile because the project references MelonLoader/game DLLs from a local install path, so v1.2.0 was published manually with gh release create using the locally verified ZIP.
• [2026-04-16] Cleaned up README.md after release to remove mixed audiences and repetition: install steps are now front-loaded for players, while build, packaging, QA, and research tooling live under a dedicated maintainer section.
• [2026-04-08] Completed the refreshed template migration: filled AGENTS.md placeholders with Melatonin-specific values, added scripts/Build-Mod.ps1 and scripts/Deploy-Mod.ps1, restored .gitignore protections for logs/artifacts/game DLLs, validated both wrapper scripts (including a local smoke deploy to artifacts\deploy-smoke\Mods), and re-decompiled the current game Assembly-CSharp.dll into local ignored decompiled/ via ilspycmd (249 .cs files).
• [2026-03-04] Started template migration on branch migration-to-an-updated-template; preserved prior ignore safeguards by merging old .gitignore entries into the new template file and restored project-specific AGENTS.md setup/build values while removing setup-only placeholders/reminder section.
• [2026-03-02] Legal/risk cleanup: confirmed decompiled/ and historical game DLL/build outputs were committed in early history; rewrote all branch/tag history, removed refs/original backups, expired reflogs, ran aggressive git gc --prune=now, force-pushed cleaned master/cutscene-audiodescription-experiments plus release tags, and removed temporary remote tag pre-scrub-2026-03-02.
• [2026-02-23] Cleaned todo.md backlog: removed stale v1.1-era items and archived notes, keeping only current active and deferred tasks.
• [2026-02-23] Reviewed tester-provided Latest.log: it reflects an older pre-fallback DLL build where localization loaded 0 entries; current branch has fallback loader fix and quiet fallback summary logging. Imported tester zh-Hans strings and validated localization/cutscene QA.
• [2026-02-23] Reduced localization startup log spam: fallback parser now reports one concise summary line instead of one warning per language file.
• [2026-02-23] Investigated log regression showing Loc loading zero JSON entries; added BOM-safe file read and fallback key/value parser in Loc.cs, rebuilt, and regenerated local v1.2 package.
• [2026-02-23] Completed non-English localization pass for all cutscene AD keys (ad_*) in JSON localization assets; localization QA and cutscene pipeline validation both pass.
• [2026-02-23] Replaced hardcoded localization tables in Loc.cs with JSON-backed data files under localization/; release packaging and QA now validate/copy Mods/localization assets directly.
• [2026-02-13] Reviewed Loc.cs zh-Hans/zh-Hant localization entries for naturalness; documented awkward contextual-cue wording, key-labels, the map progress summary, and duplicate dream names for follow-up with the user.
• [2026-02-13] Reviewed Loc.cs FR/DE/ES/PT strings for naturalness, highlighted missing accents and garbled phrases, and captured a focused list of keys to clean up.
• [2026-02-13] Reviewed JA/KO Loc.cs strings; only results_stats still reads in English/romanization so it needs localized words before release.