Repository navigation
AutoStory: one story engine over a backend, save mode from checkpoint metadata - #332
Conversation
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
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
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
…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
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_013VUubhHeYSMGSSDXZkKZss
…limit 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
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
# Conflicts: # SerialPrograms/Source/Pokemon/AutoStory/Pokemon_SceneJudges.h
…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
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
…and #313 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_013VUubhHeYSMGSSDXZkKZss
dayfine
left a comment
There was a problem hiding this comment.
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
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, andfrom_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.SerialPrograms/Source/Pokemon/AutoStory/Engine/Pokemon_StoryPoseConcept.h:65: the concept requiresStoryPoseTraits::from_declared(), but nothing calls it. Declared poses go throughpose_of(DeclaredPose)->grid_pose_of()(Pokemon_StoryStepRunner.cpp:52, Pokemon_StoryStepExecutor.cpp:22), which turns a ZoneDeclared into a GridPose and dropsspotandheading. So the PR body's claim that "a checkpoint's declared poses read as the game's pose" does not hold. Either usefrom_declaredwhere declared poses become state, or remove it from the concept and the body.SerialPrograms/Source/Pokemon/AutoStory/Types/Pokemon_StoryActionArg.h:67,78:INTEGER_ROWShas no user outside tests, and its wire shape is the same asTIMED_LEGS(both comments show[[0, 4500], ...]). Two arg types for one shape invite confusion in specs. Drop it until an action needs it.SerialPrograms/Source/Pokemon/AutoStory/Engine/Pokemon_StoryBuiltinActions.cpp:57,72,117: the press timing80ms, 120msappears 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
SerialPrograms/Source/Pokemon/AutoStory/Engine/Pokemon_StoryEngine.h:119:m_preparedis never emptied. ThePreparedStepscontract (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 insave_if_allowedon a save, or document why the engine doesn't.Pokemon_StoryEngine.h:73,Pokemon_StoryEngineRuns_Tests.cpp:6and:587: PR numbers (#329, #335) in code comments. Describe the rule itself and leave the history to the commits.SerialPrograms/Source/Pokemon/AutoStory/Engine/MIGRATION.md:53: the doc writesverify_checkpoint(checkpoint, state, policy), but the signature is(checkpoint, policy, state).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.)Pokemon_StoryEngine.cpp:76,192:"lint_failed"is a string literal in two places, whileCONSOLE_ONLYandGAME_NOT_RUNNINGare named constants. Name it the same way.- PR owns its files (not blocking): this PR edits files that #312 owns. It removes the writers in
Data/Pokemon_StoryStepJson.cppandPokemon_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.
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
|
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. |
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) andStoryEngine(event layer, then postconditions, then the save mode). Templates on aStoryPoseconcept, instantiated once forGridPose.unsupported_stepnaming the hook until a game registers its own.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_observationbeside the imagematches(CommonTools, existing users unchanged), on a newScreenObservation.FakeStoryBackendfor tests;Engine/MIGRATION.mdlists what each game must do to move.Gaps the PLZA move (#335) found, closed in the engine: the fake backend and
ZonePosefor 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-lessStepTrace, the step in each handler'sStoryActionCall, the checkpoint inStoryGame::save,StoryEngine::run_segment()/verify_checkpoint()(retries only from a start save, #329), andconsole_onlyactions refused off a console.Not migrated here: FRLG, BDSP and PLZA, and the old
StoryStepExecutorstays until the last game moves.Testing: new
Pokemon::StoryEnginesuites (registry, runner, take_warp with the 00.31black_without_warpscript returningwarp_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 sharedrun_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 newPokemon::StoryEngine retrycases. Pokemon:: suites pass in test mode.Update 2026-11-13 (33fccf1): the leg planner's optional
open_stop_risk()andtap_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):
ScreenObservationnow uses #313'sScreenEvent/ScreenEventsfromCommonTools/ScreenEvents/ScreenEventTypes.hinstead 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 shareddescribe()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