A puzzle that changes a story should feel remembered when the player returns. That does not mean every keystroke needs to persist. In a branching narrative game, durable puzzle completion, a temporary attempt, and the story consequence are three different states. Keeping them distinct helps an AI-assisted change fit the existing dialogue and ending logic.

The lighthouse ledger below is an invented teaching example. It does not describe a real project, test, or player study. Use it to plan the shape of the change, then verify behavior in the actual project before making any implementation claim.
Separate solved state, attempt state, and story consequence
Start by listing what the game currently tracks. A puzzle may have an authored ID, completion status, reward, hint level, partial input, and one or more narrative flags. Mark which values survive a scene change, which survive a restart, and which are intentionally temporary. Avoid treating all puzzle-related data as one save object simply because it appears on one screen.
| State | Example | Decision to make |
|---|---|---|
| Puzzle definition | Clue order, solution rule, linked story beat | Authored content, versioned with the project |
| Completion | Stable ID for a solved ledger puzzle | Persist if completion should survive a return |
| Attempt | Partial code, current selection, active hint | Reset or resume deliberately |
| Consequence | Dialogue flag, opened route, ending prerequisite | Use the existing narrative state owner |
In the example, solving the ledger once records the puzzle ID and sets the existing clue-found story flag. If the character leaves the study, the completed clue remains. A half-entered keypad code resets on exit. Reopening the puzzle can replay its presentation, but it does not award the clue again. This single decision prevents duplicated rewards and inconsistent branch conditions.
Trace the story flow before asking AI to edit
Follow one existing puzzle from its interaction trigger to the next dialogue or branch. Identify the script or data record that decides completion, where the game stores narrative flags, how scenes reload, and how the ending reads those flags. Take a copy of the project and a sample save before changing anything.
Ask AI to map that flow and propose the smallest patch. Name the systems that must remain unchanged: dialogue ordering, choice availability, current endings, puzzle controls, and hint behavior. Request that it reuse the current story flag or event mechanism and report the files it plans to modify. Do not accept a second “puzzle progress” system until you understand how it stays consistent with the narrative state already in the project.
Use stable identifiers rather than display text. “ledger_solution” can stay the save key even if the puzzle title changes in a later edit or translation. A stable ID also helps the story system reference a completion without searching for a localized title.
Connect the puzzle through one completion event
Keep the interaction and narrative update behind one clear boundary. On a valid solution, the puzzle can emit its stable ID and intended consequence. The story-state owner checks whether that ID is already complete, grants the clue or reward once, and updates the existing branch flag. This is easier to inspect than letting a keypad, dialogue screen, journal, and ending each write separate copies of the same fact.
A conceptual record could look like this:
{
"schema_version": 1,
"solved_puzzle_ids": ["lighthouse_ledger"],
"story_flags": {
"keeper_clue_found": true,
"north_stairs_open": false
}
}
This is not a tested schema. Keep the content definition separate from the player's progress when the project already distinguishes authored data from runtime state. Treat missing or retired puzzle IDs explicitly; do not let a renamed puzzle silently erase every dependent story choice.

Choose storage using the engine's supported data path and the project's existing architecture. Godot's stable documentation recommends user:// for persistent user data and demonstrates simple JSON saving while noting data-type and encoding tradeoffs. Unity documents Application.persistentDataPath for data that remains between runs, with platform-dependent locations. Neither documentation page dictates how a branching story should be modeled; that is a project-level decision.
Define replay and reset behavior in plain language
“Replay the puzzle” can mean several things. The player might revisit the room, view the clue animation, solve the interaction again, reset the story flag, or earn the reward again. Decide which one is intended. A safe default for a narrative puzzle is that replaying the interaction does not repeat a one-time consequence unless the game explicitly supports alternate outcomes.
Also define the scope of reset. A chapter restart may reset chapter-local clues but retain permanent journal entries. A full new story may clear all progress. If the game already has New Game Plus or chapter selection, follow its existing reset rules rather than adding a special puzzle-only exception.
If the choice consequence changes later branches, test those branches, not only the solved state. A journal entry can show “found” while an ending still reads a stale flag. Keeping one authoritative story state and one completion event makes this easier to diagnose.
Ask AI for a narrow, reversible change
A bounded instruction could say: preserve the existing dialogue and ending system; add persistence only for solved puzzle IDs and the already-defined story consequences; let current partial inputs reset when the scene closes; never grant the clue twice; list the files changed and explain how an older save will load. Ask for a diff and the test cases before accepting the patch.
Review the code for writes that bypass the story-state owner. Check that a failed save does not falsely show a permanent completion, that scene re-entry does not trigger rewards twice, and that an old save without the new field receives a deliberate default. Keep a rollback copy and test migration against a duplicate save.
Verify return, replay, and branch cases
A useful verification matrix includes different points in the story. These are proposed checks for a real project, not results from the fictional example.
| Case | Action | Expected result to verify |
|---|---|---|
| Fresh profile | Start without a prior save | No stale solved puzzle IDs or branch flags |
| Solve and leave | Complete one puzzle, exit the scene, return | Completion and intended clue remain consistent |
| Partial attempt | Enter part of a code and leave | Attempt resets or resumes according to the stated design |
| Replay | Open a solved puzzle again | Presentation works and one-time reward is not duplicated |
| Story branch | Continue into dependent dialogue or ending | Branch reads the same authoritative consequence |
| Old save | Load a disposable copy from before the new field | Migration preserves known choices and sets a safe default |
Record build version, platform, save fixture, steps, expected and observed results. If a case fails, fix that state transition before extending the feature. Do not use the concept illustration or a simulated interface as proof of a successful save migration.

Frequently asked questions
Which puzzle details should persist in a branching narrative game?
Usually persist solved puzzle IDs and the story consequences the existing narrative system expects. Treat the current input sequence, partial code entry, and temporary hints separately unless the game already supports resuming an unfinished puzzle.
How should a puzzle connect to a story branch?
Use a stable puzzle ID and update the project's existing story flag or consequence through one clear completion event. Avoid creating a parallel branch system that can disagree with dialogue, quest state, or endings.
Should players be able to replay a solved puzzle?
Decide separately whether replay is visual, mechanical, or allowed to change story state. A replay can show the puzzle again without granting its reward twice; document the intended behavior before changing the completion flow.
How can I store persistent puzzle progress in Godot?
Godot's stable docs recommend user:// for persistent user data and include a saving tutorial that demonstrates JSON for simple state. Check the current target platform and data needs; JSON type and encoding limits still apply.
What should I test after adding puzzle persistence?
Test a fresh profile, one solved puzzle, return to the hub, reload, a branch that depends on the result, replay behavior, and an older save. Record the build and steps; a sample story flow is not proof of a real test.
Preserve the story's source of truth
The safest first increment is usually small: store stable solved IDs, route a completion through the story system that already exists, and state exactly what replay and reset mean. Once the real project passes return, branch, migration, and reward checks, expand the persistence model only where the narrative needs it.
For a separate browser-playable prototype idea, try SEELE AI Game Maker. This is a separate prototype route, not an existing-project repair claim.