A detective game should remember evidence that a player earned without necessarily preserving every half-finished theory. Solved puzzles, collected clues, current deduction attempts, and case conclusions are different state. Treating them as one blob can create duplicate evidence or let a stale theory overwrite the story's source of truth.

This guide describes a fictional harbor mystery. No project, investigation, or save migration was tested. The goal is to add persistent puzzle progress while preserving the evidence and conclusion flow that already works.
Separate evidence, solved puzzles, attempts, and conclusions
List what the game tracks today. Evidence may have a stable ID and a source; a puzzle may have a solved flag; a deduction board may contain a temporary arrangement; a case may store a conclusion or chapter state. Decide which values survive leaving a room, closing the game, restarting a chapter, or starting a new case.
| State | Example | Persistence question |
|---|---|---|
| Evidence | Photograph, note, physical clue ID | Does it stay in the case inventory? |
| Puzzle result | Brass lock solved | Does return skip the puzzle or show it again? |
| Deduction attempt | Current clue arrangement | Should a partial theory resume? |
| Conclusion | Branch flag or case outcome | Which narrative system owns it? |
In the fictional Lantern Pier case, solving the lock records a stable puzzle ID and adds one clue to the evidence board. A temporary theory layout resets when the detective leaves the room. The final conclusion remains controlled by the existing case state. These are example rules, not a report about a real detective game.
Connect completion to the existing case system
Trace the path from interacting with a puzzle to collecting its clue and unlocking a dialogue or conclusion. Find who owns evidence IDs, chapter flags, and endings. Ask AI to map that path before it changes code. Keep one case-state owner rather than creating a separate puzzle inventory that can disagree with the evidence board.
When a puzzle succeeds, emit one completion event with the stable puzzle ID and the intended consequence. The case system can check whether the event is already recorded, add the clue once, and unlock the branch that depends on it. A repeated animation or scene reload should not award the same evidence again.
Use IDs instead of display text. A clue can be renamed or translated while its save key remains stable. If a clue or puzzle is removed from the next version, decide whether to migrate its ID, hide it, or retain the old record for completed cases.

Decide what replay means
A player might revisit a solved puzzle to see the animation, attempt it again, explore an alternate branch, or reset the chapter. Those are different actions. A replay of the animation can avoid touching evidence state; a new branch can create an explicit new conclusion record. Define which behavior the actual game supports.
Be careful with chapter restarts and New Game. If a chapter restart clears local puzzle progress but keeps the journal, state that rule. If a fresh case clears everything, ensure it does not also erase unrelated profile unlocks. Reuse the existing reset flow when possible instead of adding puzzle-only deletion rules.
For online or multi-device progress, conflict resolution would need a separate design. This article assumes the project's current local case-save model; do not imply cross-device synchronization unless the game already supports it and the behavior has been tested.
Version the save and preserve old cases
Use the storage path and serialization approach supported by the project. Godot's stable documentation describes user:// as a writable persistent-data path and includes file-based save examples. Check the target platform and the current engine version. A save format also needs schema versioning, defaults for missing fields, and a recovery behavior for malformed data.
Test migration on a duplicate of an older case. Compare evidence IDs, solved puzzle IDs, journal entries, and conclusion flags before and after load. Do not let the new field default to “solved” or “unsolved” without considering how that affects existing players' story state.
Keep a small event log during development: case ID, puzzle ID, event received, evidence added, conclusion flag changed, and save version. This makes it easier to see whether state stopped updating or the UI is simply displaying an old board.
Keep evidence provenance with the clue
When a puzzle unlocks evidence, record the source relationship if the case system uses one. A clue ID can point to the room, conversation, or object that introduced it. That helps the journal explain why the detective knows something and makes it easier to debug a branch that requires several clues.
Do not use the illustration or a generated evidence image as a substitute for a real clue record. The save should store the stable IDs and case consequences the game actually reads. If the player can discard or revisit evidence, follow the existing journal behavior and avoid inventing a second inventory.
Ask AI for a narrow, reversible change
Give the assistant a contract: preserve evidence collection, dialogue order, chapter resets, endings, and puzzle controls; persist only the defined solved IDs and consequences; keep partial attempts temporary; list changed files, migration behavior, and rollback steps. Ask for a patch plan before it edits.
Review the diff for duplicate evidence writes, display strings used as IDs, and conclusions stored both in the puzzle and the story manager. Keep one known case save as a regression fixture. If the AI changes the ending logic to make a puzzle pass, separate that from the persistence request and review it independently.

Verify collection, return, replay, and migration
The following are proposed tests, not results from Lantern Pier:
| Case | Action | What to verify |
|---|---|---|
| Fresh case | Start with a clean profile | No stale clues or conclusions appear |
| Solve puzzle | Complete one clue puzzle | Evidence is added once and branch state updates |
| Leave and return | Exit and re-enter the room | Solved status and case board follow the rule |
| Partial attempt | Leave before completion | Attempt resets or resumes as specified |
| Replay | Interact with a solved puzzle again | No duplicate evidence or unintended conclusion |
| Old case | Load a duplicate prior-version save | Clues and story flags remain consistent |
Record build version, case ID, puzzle ID, save version, steps, expected outcome, and observed outcome. Check both the visible journal and the underlying branch behavior. A mock evidence board is not proof that a saved clue unlocks the correct ending.
Frequently asked questions
What detective game progress should persist?
Persist collected evidence IDs, solved puzzle IDs, and case consequences the narrative depends on. Treat a partial deduction attempt, selected board layout, or temporary hint as separate state unless the game already supports resuming it. Use the project’s current case vocabulary and record format.
How should a solved puzzle affect the case board?
Send one completion event through the existing case-state owner. It can record the puzzle ID, unlock the intended clue or conclusion, and prevent a repeated interaction from granting the same evidence twice. Keep the board and case model pointed to the same state owner.
Should players be able to replay a detective puzzle?
Decide whether replay is for presentation, a fresh attempt, or a new case branch. Replaying an animation should not silently duplicate evidence or overwrite a prior conclusion. Document replay behavior so players know what resets. Keep the saved result distinct from a fresh branch attempt.
Where should detective evidence and puzzle state be saved?
Use the project's supported persistent-data path and versioned save model. Godot's stable docs describe user:// and file-based saving; confirm the current engine version and target platform before choosing a format. Check these fields against the real project and target platform.
What should I test after adding persistent deductions?
Test a fresh case, collected clue, solved puzzle, return to the evidence board, reload, replay, and an older save. Record the actual case and build; a fictional clue chain is not a test result. Include case ID and save version in the observed test record.
Keep the case state in one place
Persist stable puzzle results and evidence consequences through the system that already owns the investigation. Leave partial attempts temporary unless the game explicitly supports resuming them. Then verify return, replay, and old-save behavior in the real project before expanding the clue system.
For a separate browser-playable prototype idea, try SEELE AI Game Maker. This CTA is for a separate prototype, not for modifying an existing detective case system.


