Skip to content

AutoStory: one story engine over a backend, save mode from checkpoint metadata - #332

Merged
dayfine merged 219 commits into
nav/sharedfrom
autostory/engine
Nov 14, 2026
Merged

dayfine merged 219 commits into
nav/sharedfrom
autostory/engine

Conversation

@dayfine

@dayfine dayfine commented Nov 10, 2026 •

Copy link
Copy Markdown
Owner

Base: nav/screen-state (#313), with #329 merged in; #391's shared retry loop comes in through #114. The diff shows #329's commit plus this change.

Adds the shared story engine from the agreed spec (2026-11-10), so FRLG, BDSP and PLZA can drop their own executors and run the same code on the console and in the sim.

  • Pokemon/AutoStory/Engine/: StoryBackend<Pose> (press, tap, hold, wait, observe, battle), StoryGame<Pose> (actions, readers, save, reload as data plus functions), StoryActionRegistry (built-ins with the game's actions on top, lint, dispatch), StoryStepRunner (skip_if from flags or readers, pose_after, [Step] line) and StoryEngine (event layer, then postconditions, then the save mode). Templates on a StoryPose concept, instantiated once for GridPose.
  • Built-in actions written against the backend: legs, face, answer, talk (fails when no text box opens), mash, fight, save. route, ready, train and shop fail as unsupported_step naming the hook until a game registers its own.
  • Checkpoint JSON metadata: phase, verified (steps_hash, build, date, runs), source, postconditions. The save mode comes from the phase; a steps_hash that no longer matches the steps is treated as testing and logged. A SAVE step saves only in reproduction.
  • ScreenState::matches_observation beside the image matches (CommonTools, existing users unchanged), on a new ScreenObservation.
  • FakeStoryBackend for tests; Engine/MIGRATION.md lists what each game must do to move.

Gaps the PLZA move (#335) found, closed in the engine: the fake backend and ZonePose for any pose type (StoryPoseTraits: tile actions only for tile games; a checkpoint's declared poses read as the game's pose), StoryBackend::stick() and the "heading" reading, choice and interact events, run_screen_machine_on_observations() with a video-less StepTrace, the step in each handler's StoryActionCall, the checkpoint in StoryGame::save, StoryEngine::run_segment() / verify_checkpoint() (retries only from a start save, #329), and console_only actions refused off a console.

Not migrated here: FRLG, BDSP and PLZA, and the old StoryStepExecutor stays until the last game moves.

Testing: new Pokemon::StoryEngine suites (registry, runner, take_warp with the 00.31 black_without_warp script returning warp_no_fade, save decision from phase and hash, postconditions passed/failed/not checked, pinned steps_hash, metadata, screen observation, and the gap cases on GridPose and ZonePose fakes) plus the existing story suites all pass in the headless runner (164 passed); code health 0 failures.

Update 2026-11-10 (b305df5, core split): base is now nav/screen-state (#313); #122's 2D files were removed here and come back in #362, so PLZA (#354) builds on the engine without them. The PLZA tip (19c7c19) built; Pokemon:: 208 passed, 0 failed in test mode.

Update 2026-11-13 (a76f816): run_with_retries() runs through #391's shared run_checkpoint_attempts(), so SV, the story segments and the engine retry in one loop; the reload and pass lines and the attempt counts are unchanged, pinned by new Pokemon::StoryEngine retry cases. Pokemon:: suites pass in test mode.

Update 2026-11-13 (33fccf1): the leg planner's optional open_stop_risk() and tap_stop_risk() on the step model, moved here from FRLG game PRs (3fc6917, 9411b93); a model without them plans as before.

Update 2026-11-13 (91c12d2, one screen-event vocabulary): ScreenObservation now uses #313's ScreenEvent/ScreenEvents from CommonTools/ScreenEvents/ScreenEventTypes.h instead of its own copy (TEXT_BOX is DIALOG_BOX, BATTLE is BATTLE_STARTED, CAN_MOVE is PLAYER_CAN_MOVE, STILL is SCREEN_STILL), and the shared describe() takes the engine's separator. screen_observation() keeps its mapping (a choice box also counts as a dialog box). Pokemon:: and CommonTools::ScreenEvents suites pass in test mode; code health 0 failures.

🤖 Generated with Claude Code

https://claude.ai/code/session_013VUubhHeYSMGSSDXZkKZss

dayfine and others added 30 commits November 1, 2026 09:53
A story checkpoint as a list of StorySteps (route, legs, step onto a
trigger, talk, YES/NO, scene, battle, train, heal, shop, save, ready for
a boss, and a game-only step), plain data, built into engine events by
build_story_checkpoint(). Each event asks the game's StoryStepExecutor
to do its step: one virtual per kind, failing as unsupported unless the
game overrides it. Poses are the game's (TilePose); skip_if names
conditions the executor answers.

Tests run tables against a fake executor: event order, skip_if, pose
propagation, failure naming, unsupported kinds, a segment with a reload,
and lint.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01AKYzhrMnPK61XHWEch4a6E
SegmentPolicy is now where retries are set: attempts per checkpoint
(default 3), stop at the first failure (no reload; the game stays where
it failed), and in-place recoveries per event (SegmentHooks::recover,
then the event again) before a checkpoint is reloaded, default 0.
run_segment reports each checkpoint's attempts and recoveries and logs
"[Checkpoint] 00.07: passed on attempt 2 (1 reset)" and "[Segment] 00:
2 of 3 checkpoints one-shot", so the one-shot rate can be tracked.

StoryRunOptions is the program-option group both AutoStory programs
embed: "Attempts per checkpoint" and "Stop at the first failure". A
story step's skip_if condition is a run flag unless the game overrides
holds(). Tests: the policy against the fake executor (attempts then
fail, stop at first failure, recover in place, one-shot report).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01AKYzhrMnPK61XHWEch4a6E
build_story_checkpoint() calls StoryStepExecutor::begin_attempt() before
building, once per attempt, so a game can start the attempt afresh (BDSP:
the trainers who can see us again; the row's failure mode).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01AKYzhrMnPK61XHWEch4a6E
…r Fast)

StoryChecks: THOROUGH steps read the screen to confirm what they did
(purchases, the Bag, status after battles, position); FAST trusts counts
and timings. Each game decides what its steps check at each level. The
executor carries it (checks(), set_checks(); THOROUGH by default), and
StoryRunOptions gains a "Checks" dropdown, Thorough by default, read with
checks(). Tests: the level reaches a step; the option group's defaults.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01AKYzhrMnPK61XHWEch4a6E
…eed it

StoryRunOptions gains "Game language" (any language the games have,
English by default, never refused for lacking a reader), and the executor
carries it (language(), set_language()) for the few reads that need text:
item names in a shop or the Bag. The header states the rule: steps never
match dialogue or menu text, and a game with no reader for the language
falls back to language-free checks. Tests: the option's choices and the
executor's language.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01AKYzhrMnPK61XHWEch4a6E
…d AutoStory stats, for story runs

StoryRunOptions (now "Story Run") takes the game's checkpoint database
and shows Start and End checkpoint dropdowns, labeled as SV labels its
segments ("00.09 Pewter Gym: Camper Liam, then Brock") and built with
#43's make_story_select_database(); a story in sections passes them joined,
so a section's entry is at #44's story_index(). A start after the end is
refused. record_story_stats() adds a segment's run to #45's
AutoStoryStats: the segment, each passed checkpoint, each reload.

Tests: the dropdowns' labels, slugs and defaults, the start/end check,
and the stats.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01AKYzhrMnPK61XHWEch4a6E
…y) into nav/story-steps

# Conflicts:
#	SerialPrograms/Source/Pokemon/Navigation/Pokemon_Navigation_Tests.h
#	SerialPrograms/cmake/SourceFiles.cmake
StorySteps and its tests move unchanged to Pokemon/AutoStory, next to the
events and segments they build on (#114), and register from
Pokemon_AutoStory_Tests.h. The story run options include them from there.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01AKYzhrMnPK61XHWEch4a6E
Code health limits a class's public methods: the methods a game overrides
for each step kind are now protected, reached through
dispatch_story_step(), so an executor's public face is the attempt, the
checks and language, run() and holds(). The test fake follows, and the
segment-of-tables test moves its setup into a helper.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01AKYzhrMnPK61XHWEch4a6E
…/story-steps

# Conflicts:
#	SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StorySegments.cpp
#	SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StorySegments.h
…into nav/story-steps

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01AKYzhrMnPK61XHWEch4a6E
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01AKYzhrMnPK61XHWEch4a6E
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01AKYzhrMnPK61XHWEch4a6E
Verify mode, a toggle group in the story run options, runs the start
checkpoint, which must also be the end, a set number of times from its
save without saving at its end, and needs a set number of them to pass
(3 and 2 by default). VERIFY.policy() gives the policy for
verify_checkpoint(), unset when the mode is off.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01AKYzhrMnPK61XHWEch4a6E
# Conflicts:
#	SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StorySegments.h
- Add descriptive header symbol comments and matching namespace close comments
- Forward-declare public function templates before their definitions
- Convert native unit tests to input/expectation table-driven cases
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01AKYzhrMnPK61XHWEch4a6E
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01AKYzhrMnPK61XHWEch4a6E
* Add shared story checkpoint JSON codec and portable tests

* Avoid shadowing pose input in facing decoder

* Initialize rejection-case canonical value for Clang
Lands the shared story-engine additions the FRLG AutoStory stack carried
on its own copies of Pokemon/AutoStory (frlg/stage2-rng 2148c96), so
both game chains merge them from the owning PR:

- StoryStep::once_per_save marks preparation (a TEACH, a check, a read)
  done once per save. build_story_checkpoint(data, executor, prepared)
  skips such a step while PreparedSteps has "<checkpoint>/<step>", and
  adds it when the step succeeds changing nothing, so a retry after a
  reload of the same save goes straight to the battle. The game empties
  the set when it saves or loads another save.
- Outcome::changed_nothing and outcome_unchanged(): a succeeded action
  that left the game as it found it, which a reload undoes nothing of.
- lint_story_checkpoint() rejects once_per_save together with skip_if.

The two-argument build_story_checkpoint() is unchanged, so a game without
the memory builds as before. Tests in the StorySteps suite: a retry
skips what changed nothing and repeats what taught; verify mode prepares
once in three runs, and every run without PreparedSteps.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_013VUubhHeYSMGSSDXZkKZss
dayfine and others added 2 commits November 13, 2026 16:01
…ve to CommonTools/ScreenEvents

Conflicts: the AutoStory test list and SourceFiles.cmake keep this
branch's suites; the screen event files and AutoStoryStats tests take
nav/screen-state's moves (CommonTools/ScreenEvents, StoryRunCounts).
Includes of the old Pokemon_ScreenEvents*.h paths follow the move.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_013VUubhHeYSMGSSDXZkKZss
ScreenObservation now takes ScreenEvent and ScreenEvents from
CommonTools/ScreenEvents/ScreenEventTypes.h instead of its own copies.
Renames: TEXT_BOX -> DIALOG_BOX, BATTLE -> BATTLE_STARTED, CAN_MOVE ->
PLAYER_CAN_MOVE, STILL -> SCREEN_STILL; ScreenEvents::add(e) ->
set(e, true). The shared describe() takes the separator the engine's
had, defaulting to ", ". screen_observation() keeps the same mapping:
the engine's events only, and a choice box also counts as a dialog box.
The FRLG observer and the interrupt/judge code drop the Pokemon::
prefix and include ScreenFades.h for fade_in()/fade_events().

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_013VUubhHeYSMGSSDXZkKZss
dayfine and others added 4 commits November 13, 2026 20:53
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_013VUubhHeYSMGSSDXZkKZss
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_013VUubhHeYSMGSSDXZkKZss
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_013VUubhHeYSMGSSDXZkKZss
…talk

TalkOverRule gains `calm`, how long the overworld with no box ends a talk,
still or not. It defaults to TALK_OVER_CALM (15 s), so FRLG and BDSP keep
their behaviour; PLZA (#335) sets it to 1 s, its party bar held. The field
is last, so positional initializers are unaffected.

TALK_OVER_QUIET and TALK_OVER_CALM move above the rule, which now names
TALK_OVER_CALM, and become inline constexpr. Two test_talk_over rows pin a
shorter calm: it ends the talk sooner, and a box restarts its clock.

Moved here from #335's 3175afd, since this PR owns the shared judge.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_013VUubhHeYSMGSSDXZkKZss
dayfine added a commit that referenced this pull request Nov 14, 2026
# Conflicts:
#	SerialPrograms/Source/Pokemon/AutoStory/Pokemon_SceneJudges.h
dayfine added a commit that referenced this pull request Nov 14, 2026
…m (d)

SceneMash takes the Button that advances the text instead of a bare bool
and compares it itself. mash_scene keeps the mash's start and its scene's
start window in one optional. OVERWORLD_HOLD and SCENE_START_WINDOW are
inline constexpr; the shared judge's `calm` now comes from #332, merged in.

Behaviour changes from the old rule, which waited whenever the party bar
showed: the party bar with a box now presses the text button, and with a
choice presses A; a battle HUD with the party bar no longer ends an
OVERWORLD mash after 1 s. New rows in test_scene_mash_rule and
test_scene_mash_battle_hud_not_overworld pin all three.

03.07d: into_the_counter and out_of_pokemon_center drop UNVERIFIED; 3 of 3
console B runs from the counter save reached the gate prompt.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_013VUubhHeYSMGSSDXZkKZss
dayfine and others added 2 commits November 14, 2026 12:15
Code Health's test-case rule wants each UnitTest built from one case
struct of name, input and expectation, with the name outside the input.
Move every case's name from its Input to the case itself, nest the
RngHandoff input and expectation structs, and give the first-save,
captured-transition and move-mechanics cases explicit names (the same
test names as before). Assertions and test bodies are unchanged.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_013VUubhHeYSMGSSDXZkKZss
… on #312, ScreenEvents case names

Conflicts: ScreenEvents_Tests.cpp takes #313's case struct (name outside the input); the story-data README keeps this branch's reader-only text.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_013VUubhHeYSMGSSDXZkKZss

@dayfine dayfine left a comment

Copy link
Copy Markdown
Owner Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Reviewed SHA: b432d7c

Verdict: mergeable on the fork

Verdict

APPROVED

The verdict covers the fork merge only. No game runs the engine yet, so none of the findings below blocks merging into nav/screen-state. Fix the should-fix items before FRLG/BDSP/PLZA move onto the engine. I read Engine/, the policy, the codec and metadata, and the CommonTools ScreenMachine/StepTrace changes in full, and only skimmed the tests and the merged-in nav/rng-handoff files. CI is green at this tip.

blocking

None.

should-fix

  1. SerialPrograms/Source/Pokemon/AutoStory/Engine/Pokemon_StoryEngine.cpp:286 (run_segment -> run_with_retries): in PER_CHECKPOINT mode a SAVE step saves part-way through a checkpoint (the gated handler at :58-69). If a later step then fails, the reload at :251 goes back to that mid-checkpoint save, but the retry runs the checkpoint again from step 1, and from_save (Pokemon_StoryStepExecutor.cpp:103) sets the pose to the checkpoint's start. That breaks the rule in StoryEngine.h:69-72 that the engine retries only when a reload returns to the save the checkpoint started from. Suggest: have the gated save step record that it saved during this attempt, and treat a failure after that save as FINAL (no reload). Add a Runs test for it: reproduction phase, SAVE step, a flaky step after it.
  2. SerialPrograms/Source/Pokemon/AutoStory/Engine/Pokemon_StoryPoseConcept.h:65: the concept requires StoryPoseTraits::from_declared(), but nothing calls it. Declared poses go through pose_of(DeclaredPose) -> grid_pose_of() (Pokemon_StoryStepRunner.cpp:52, Pokemon_StoryStepExecutor.cpp:22), which turns a ZoneDeclared into a GridPose and drops spot and heading. So the PR body's claim that "a checkpoint's declared poses read as the game's pose" does not hold. Either use from_declared where declared poses become state, or remove it from the concept and the body.
  3. SerialPrograms/Source/Pokemon/AutoStory/Types/Pokemon_StoryActionArg.h:67,78: INTEGER_ROWS has no user outside tests, and its wire shape is the same as TIMED_LEGS (both comments show [[0, 4500], ...]). Two arg types for one shape invite confusion in specs. Drop it until an action needs it.
  4. SerialPrograms/Source/Pokemon/AutoStory/Engine/Pokemon_StoryBuiltinActions.cpp:57,72,117: the press timing 80ms, 120ms appears three times with no reason given. Name it once (e.g. STORY_PRESS_HOLD / STORY_PRESS_RELEASE) with a short why-comment (user theme: magic numbers).

nit

  1. SerialPrograms/Source/Pokemon/AutoStory/Engine/Pokemon_StoryEngine.h:119: m_prepared is never emptied. The PreparedSteps contract (Pokemon_StoryStepExecutor.h:89-92) says it "empties it when it saves or loads another save". One engine used for two segments, or across a save, keeps the old keys. Clear it in save_if_allowed on a save, or document why the engine doesn't.
  2. Pokemon_StoryEngine.h:73, Pokemon_StoryEngineRuns_Tests.cpp:6 and :587: PR numbers (#329, #335) in code comments. Describe the rule itself and leave the history to the commits.
  3. SerialPrograms/Source/Pokemon/AutoStory/Engine/MIGRATION.md:53: the doc writes verify_checkpoint(checkpoint, state, policy), but the signature is (checkpoint, policy, state).
  4. SerialPrograms/Source/CommonTools/ScreenMachine/ScreenObservation.h:42: same_screen() is declared here but defined in ScreenMachine.cpp. Declare it in ScreenMachine.h, or give ScreenObservation its own .cpp. (This is infra: CommonTools.)
  5. Pokemon_StoryEngine.cpp:76,192: "lint_failed" is a string literal in two places, while CONSOLE_ONLY and GAME_NOT_RUNNING are named constants. Name it the same way.
  6. PR owns its files (not blocking): this PR edits files that #312 owns. It removes the writers in Data/Pokemon_StoryStepJson.cpp and Pokemon_AuthoredCheckpointJson.cpp (f360dd3) and restructures their test tables.

Dropped a few minor ones: inline on anonymous-namespace helpers in Pokemon_StoryActionRegistry.cpp; read_verification calling to_string_throw() without the source; timeout.count() / 1000 printing 0s for sub-second timeouts in run_screen_machine_on_observations.

Not checked: code_health limits and the build (CI is green). The merged-in Navigation/RngHandoff files were only skimmed.

dayfine and others added 2 commits November 14, 2026 13:47
@dayfine
dayfine changed the base branch from nav/screen-state to nav/shared November 14, 2026 21:56
@dayfine

dayfine commented Nov 14, 2026

Copy link
Copy Markdown
Owner Author

Review follow-up: 6935936 names the text press timing (should-fix 4). Should-fix 1-3 (a mid-checkpoint SAVE step in reproduction phase, the unused from_declared() and zone spot/heading loss, INTEGER_ROWS) are engine design changes left for a follow-up before a game moves onto the engine. #312 and #313 are merged into nav/shared; this PR now targets nav/shared.

@dayfine
dayfine merged commit ae2c629 into nav/shared Nov 14, 2026
16 checks passed
dayfine added a commit that referenced this pull request Nov 14, 2026
AutoStory: review fixes on the shared engine (#312, #313, #332, #474, #479)
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant