Skip to content

Pokemon navigation: the shared core for AutoStory - #114

Merged
dayfine merged 445 commits into
autostory/sv-retry-corefrom
nav/shared
Nov 15, 2026
Merged

dayfine merged 445 commits into
autostory/sv-retry-corefrom
nav/shared

Conversation

@dayfine

@dayfine dayfine commented Nov 1, 2026 •

Copy link
Copy Markdown
Owner

Depends on #391 (base autostory/sv-retry-core, which carries #325 and #45; the diff shows only this change; #43 and #44 are upstream as PokemonAutomation#1828).

BDSP and FRLG AutoStory each had their own grid, planner, walker and map format, so none of it could be shared or tested once. This adds the game-agnostic core: Pokemon/Navigation has the grid types, the leg planner, the leg walker with its stop hooks, the route log lines both walkers write, and Pokemon::MapData, the one JSON map schema both games' maps are written in (tiles in shared glyphs, elevation, warps that say how they are entered, objects, named points and flag sets); Pokemon/AutoStory has checkpoints as events, segments and the tile pose, with ScreenMachine/StepTrace in CommonTools. Navigation includes nothing from AutoStory or any game. Tested with the LegPlanner, LegWalker, MapData, RouteLog, StoryEvents and StorySegments suites in fork CI on Mac, Windows Clang and Ubuntu.

Update 2026-11-08 (4bea6f3): the LegWalker additions the FRLG stack carried on its own copies are landed here so both game chains merge them from this PR: a stopped open leg reports in LegResult.tiles how far the interrupt's timing puts the player, and LegSpec::stalled_steps makes leg_hold() a tile longer per step the game stalls (FireRed's map connections). Additive API; LegWalker suite extended.

Update 2026-11-10 (76d2645): from #312's review, StoryEvents and StorySegments take #312's edits (StoryLog lines now from #45), SegmentPolicy drops stop_at_first_failure and recoveries_per_event (with SegmentHooks::recover), and the plain segment types move to Types/Pokemon_StorySegmentTypes.h. Over-limit headers are split unchanged by concern (each still included by its old header) and char* is gone, for the newer code-health rules. Pokemon:: suites pass with the headless runner.

Update 2026-11-13 (bf1c777): the runner formats its own event line and other checkpoint lines (event_log_line, checkpoint_log_line in Pokemon_StoryEvents.h), #45 keeps only the checkpoint lines SV shares, and a segment's reload writes checkpoint_reset_line with the attempt limit.

Update 2026-11-10 (0859830, core split): the tile navigation package (planner, walker, map data, route log, runtime map, wall recovery, their tests, test maps, devtools and workflow) moved out of this PR into the 2D core PR #360; only Pokemon_Grid stays here, since the engine backend and PLZA use Direction. The PLZA tip built and its Pokemon:: suites pass on the headless test mode.

Update 2026-11-13 (f72260e): run_row() in StorySegments retries through #391's shared run_checkpoint_attempts(), with the same lines and counts; the StorySegments suite passes unchanged.

Update 2026-11-13 (941b676): Event::when_skipped runs when skip_if skips an event, so a skipped event's effect on the run state (a door it opens) is kept; moved here from FRLG's bc6a558, where a game PR had added it.

🤖 Generated with Claude Code

https://claude.ai/code/session_01AKYzhrMnPK61XHWEch4a6E

dayfine added a commit that referenced this pull request Nov 1, 2026
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01AKYzhrMnPK61XHWEch4a6E
dayfine added a commit that referenced this pull request Nov 1, 2026
@dayfine
dayfine marked this pull request as ready for review November 1, 2026 06:19
@dayfine

dayfine commented Nov 1, 2026

Copy link
Copy Markdown
Owner Author

LGTM

dayfine added a commit that referenced this pull request Nov 1, 2026
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01AKYzhrMnPK61XHWEch4a6E
dayfine added a commit that referenced this pull request Nov 1, 2026
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01AKYzhrMnPK61XHWEch4a6E
dayfine added a commit that referenced this pull request Nov 1, 2026
# Conflicts:
#	SerialPrograms/Source/ComputerPrograms/ComputerPrograms_UnitTestRunner.cpp
#	SerialPrograms/Source/Pokemon/Navigation/Pokemon_Navigation_Tests.h
#	SerialPrograms/cmake/SourceFiles.cmake
dayfine added a commit that referenced this pull request Nov 1, 2026
Brings in nav/shared (#114) through #117.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01AKYzhrMnPK61XHWEch4a6E
dayfine added a commit that referenced this pull request Nov 1, 2026
…count

Brings in nav/shared (#114) through #117 and #118, including the planner's wild-step weighting (7008f8c), which moved there from this branch's b4d1976.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01AKYzhrMnPK61XHWEch4a6E
dayfine added a commit that referenced this pull request Nov 1, 2026
…-mvp

#119 now has nav/shared (#114) through #117 and #118, so this PR's diff shows only its own files.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01AKYzhrMnPK61XHWEch4a6E
dayfine added a commit that referenced this pull request Nov 1, 2026
LegPlanner's wild-step weighting moved from #119 to #114 (7008f8c) and merged down #117 → #118 → #119 → #120; #120's diff is PokemonFRLG only. Adds #119, #120, #121 to the tree and a file-ownership table.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01AKYzhrMnPK61XHWEch4a6E
dayfine added a commit that referenced this pull request Nov 1, 2026
The shared engine replaces this branch's copies of the grid types, leg
planner and story events. LegWalker goes: nothing in BDSP uses it, and
FRLG brings its own on nav/shared. SandgemCenterEvents moves to the
shared Pose (a Position) and returns learned poses in its Outcome.

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

# Conflicts:
#	Common/Cpp/MoveOnlyFunction_Tests.cpp
#	SerialPrograms/Source/ComputerPrograms/ComputerPrograms_UnitTestRunner.cpp
#	SerialPrograms/Source/Pokemon/Navigation/Pokemon_Grid.cpp
#	SerialPrograms/Source/Pokemon/Navigation/Pokemon_Grid.h
#	SerialPrograms/Source/Pokemon/Navigation/Pokemon_LegPlanner.h
#	SerialPrograms/Source/Pokemon/Navigation/Pokemon_LegPlanner_Tests.cpp
#	SerialPrograms/Source/Pokemon/Navigation/Pokemon_Navigation_Tests.h
#	SerialPrograms/Source/Pokemon/Navigation/Pokemon_StoryEvents.cpp
#	SerialPrograms/Source/Pokemon/Navigation/Pokemon_StoryEvents.h
#	SerialPrograms/Source/Pokemon/Navigation/Pokemon_StoryEvents_Tests.cpp
#	SerialPrograms/cmake/SourceFiles.cmake
dayfine added a commit that referenced this pull request Nov 1, 2026
…p/maps-rederive

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01AKYzhrMnPK61XHWEch4a6E
dayfine added a commit that referenced this pull request Nov 1, 2026
A leg's wild flag was worked out from the tiles on its start map only, so
"north 22" from Pallet Town, through Route 1's grass beyond the map's
edge, was walked without watching for battles (console B, 2026-11-01).
It now comes from the planner's per-step wild flag (#114), set on tall
grass and water. The wild-steps route test checks that leg.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01AKYzhrMnPK61XHWEch4a6E
dayfine added a commit that referenced this pull request Nov 1, 2026
dayfine added a commit that referenced this pull request Nov 1, 2026
Brings pa_embed_text_files() (cmake/EmbedTextFiles.cmake), which #111
uses to build the BDSP maps' JSON into the tests.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01AKYzhrMnPK61XHWEch4a6E
dayfine added a commit that referenced this pull request Nov 1, 2026
…mes from #114

# Conflicts:
#	SerialPrograms/Source/Pokemon/Navigation/Pokemon_LegWalker.cpp
#	SerialPrograms/Source/Pokemon/Navigation/Pokemon_LegWalker.h
#	SerialPrograms/Source/Pokemon/Navigation/Pokemon_LegWalker_Tests.cpp
dayfine added a commit that referenced this pull request Nov 1, 2026
…s PR

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01AKYzhrMnPK61XHWEch4a6E
@dayfine
dayfine changed the base branch from base/upstream-main to autostory/r3-shared-stats November 1, 2026 20:30
dayfine and others added 21 commits November 14, 2026 14:06
A reload after that save would land mid-checkpoint while the retry runs
from step 1. The engine now records the save and ends the checkpoint's
attempts there.
…text

A test pins that the engine's SAVE step saves nothing in a testing run;
StoryStepExecutor::run says a game off the engine must gate it itself.
The step reader accepts once_per_save. The Save and Verify Mode texts
say when After verification saves.
Declared poses reach the run as the event layer's pose; a zone's spot and
heading are not carried until a game has a position reader.
… value

INTEGER_ROWS stays: FRLG's foe_threats and BDSP's avoid args use it.
A user's run skips dev-only rows, so the row a reload follows there must
autosave as well.
story_failure_class_info() throws for a class with no row in its place,
and a test checks every class has one.
Covers the first frame's rises, rose/fell edges, the capacity drop and
describe().
AutoStory: review fixes on the shared engine (#312, #313, #332, #474, #479)
…again

StoryDataTests takes the path of a pokesim-story-wire-cases/2 file, reads
each case with the native pose, step and checkpoint readers and checks the
accept/reject and the record read. The workflow pins PokemonSimulation
4e023f3 (#104, cases in the action-plus-args form) and runs it on all three
platforms.
Answers the #312 review: the Switch FireRed/LeafGreen are the GBA releases
reissued, one version per language with no in-game option, so all six
languages stay (as in upstream's FRLG programs). Gen 8-9 games have one
Spanish, so one "es". Code that reads text takes the language option.
…e fails loudly

The standalone main moves to devtools/story-data-tests/StoryDataMain.cpp so program source no longer includes a devtools header; other argument counts print usage and exit 2. The wire-case reader reads a case's own fields outside the try, so a malformed case file throws instead of reading as a rejection. Also plain statements for the verified fields and explicit includes.
Fix shared AutoStory engine review nits
Story data codec: run the shared wire cases natively again
A watch that ends in wall time reads a window full of dropped frames as
"not seen". FrameCoverage records the capture times of the frames a
watcher was handed and finds the largest gap in the window; judge_watch()
returns SEEN, NOT_SEEN (frames cover the window) or UNKNOWN (a gap longer
than max_gap). CoveredWatcher wraps any VisualInferenceCallback and can
stop on the first frame captured at a deadline; run_watched() and
watch_for() end a window in frame time, bounded by a wall-clock cap.
@dayfine

dayfine commented Nov 15, 2026

Copy link
Copy Markdown
Owner Author

Dropped frames in screen waits (58cee39). run_until/wait_until end a watch in wall time and return -1 whether the watcher saw a frame every 33 ms or one a second. The pivot hands each watcher the newest converted frame and dedupes nothing, and DetectorToFinder holds are measured on frame timestamps. So in PLZA 03.08 the banner fell into a gap and was read as "no new species". This follows the frame-timing design from #480: timeouts stay in ms, and the verdict is judged on frames. It identifies frames by VideoSnapshot::timestamp (no infra change) and uses the largest gap between inspected frames instead of a fixed frame count, because a hold detector needs frames at least as often as its hold.

New in Pokemon/AutoStory/Engine: FrameCoverage + judge_watch() return SEEN / NOT_SEEN / UNKNOWN (UNKNOWN when a gap is longer than max_gap). CoveredWatcher wraps any VisualInferenceCallback and can stop on the first frame captured at a deadline. run_watched() and watch_for() end a window in frame time, with a wall-clock cap. No call sites change. Tests: Pokemon::FrameCoverage and Pokemon::CoveredWatch on scripted frame times.

Game languages: FRLG keeps six languages, one Spanish (#312 review)

@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: 58cee39

Scope: only the dropped-frames commit 58cee39 (Pokemon/AutoStory/Engine/Pokemon_FrameCoverage.{h,cpp}, Pokemon_CoveredWatch.{h,cpp}, their tests, test registration, SourceFiles.cmake). Checked against comment 6886621137 and docs/design/AutoStory-FrameTiming.md on agents.

Verdict

NEEDS_REWORK

One medium finding (the header promises a catch that a hold watcher cannot make) and three low ones. The core design is sound. Deadlines stay in ms and the verdict is judged on frames, which matches the design doc §2.2. Threading is correct and the tests are well shaped.

What I checked and found correct

  • Thread safety. CoveredWatcher state (m_coverage, m_fired, m_stop_at) is not atomic. That is fine: VisualInferencePivot::run() is called under BusyPeriodicRunner::m_lock, and remove_event()/add_event() take the same lock. InferenceSession's destructor removes the callback before run_until/wait_until returns. So reading fired()/coverage() afterwards and calling stop_at() between the two sessions in run_watched are both ordered. No raw std::thread/std::mutex.
  • Stale frames. SnapshotManager::snapshot_recent_nonblocking() returns the cached converted frame on its "already up-to-date" path without checking min_time, so a new session can be handed a frame captured before it opened. FrameCoverage::record() correctly ignores those, and it ignores repeats (<= back). The "before the window opened" and "handed over again" cases cover this.
  • largest_gap. The clamping at end, and the leading gap from start and trailing gap to end, are correct. I hand-checked every expected number in COVERAGE_CASES and all are right.
  • Wall-clock cap. watch_for stops by end + cap. run_watched stops by cap after the command ends. When the cap is hit, the trailing gap counts in largest_gap, so the verdict cannot be NOT_SEEN on a window the frames do not cover.
  • Style. CRLF is kept in all new files. Control-flow brace style is followed. Test cases are name / Input / Expectation with the name outside the input. No tabs. Code health shows only one advisory for these files (check_watch is 32 lines). The failing code-health errors are all in other, older *_Tests.cpp files.

Findings

  1. Medium. A hold watcher cannot fire on a screen that shows at the end of the window, but the header says it is caught. (Pokemon_CoveredWatch.h:65-69, run_watched; same for watch_for)
    The extension stops on the first frame captured at or after end. A DetectorToFinder with hold h needs frames spanning h before it fires. So a screen that appears in (end - h, end] is cut off one frame after end and the result is NOT_SEEN, with good coverage. That contradicts "a screen that shows just as the command ends is still caught". The judge_watch comment only bounds max_gap; it does not say that a hold watcher's effective window ends hold early. This is the PLZA banner case the PR was written for, so it matters for the first real caller. Fix: either give the stop deadline a tail (stop_at(end + tail), where tail is the watcher's hold and is passed in or defaults to max_gap, still bounded by cap), or state the limit in both doc comments and have callers lengthen the window. The first fix is better, and a CoveredWatch case with a hold-style scripted watcher would lock it in.

  2. Low. largest_gap truncates to whole ms, which errs toward NOT_SEEN. (Pokemon_FrameCoverage.cpp:50)
    duration_cast<Milliseconds> rounds down. Frame timestamps are system_clock (µs or finer), so a 100.9 ms gap passes max_gap = 100ms as NOT_SEEN. The rounding is small, but it goes in the unsafe direction for a "did not show" verdict. Fix: compare the raw WallDuration against max_gap in judge_watch, or use std::chrono::ceil for the stored value.

  3. Low. A fire on a frame captured before the window opened counts as SEEN. (Pokemon_CoveredWatch.cpp:23-30)
    record() drops a pre-window frame as evidence, but the frame is still handed to the wrapped watcher, and a fire on it returns SEEN. wait_until has always behaved this way, so this is not a regression. But FrameCoverage now defines the window, and the wrapper is inconsistent with it: for a "did the screen change" watcher, the stale frame is exactly the wrong evidence. Either skip the inner watcher for frame.timestamp < start, or document that SEEN can rest on a stale frame. A test case would pin whichever you choose.

  4. Low. stop_at() is a public setter with no threading contract. (Pokemon_CoveredWatch.h:46-49)
    The class comment covers reads only. Calling stop_at() while the wrapper is live in a session would be a data race on std::optional. Add "set before the routine starts" to the comment, or take the deadline as an optional constructor argument (watch_for knows it at construction). That would also leave run_watched as the only place that sets it between sessions.

Nits

  • run_watched: !covered.coverage().reached(end) is always true when the watcher has not fired, because end is read after run_until returned and every inspected frame was captured before then. if (!covered.fired()) says the same thing more plainly.
  • run_watched and watch_for hard-code the default 50 ms video period. A caller that needs a faster poll than max_gap allows cannot ask for one. Not needed until a caller needs it; just noting it.
  • The composition (extension phase, cap, end bookkeeping) has no test, because it needs a VideoStream. This is acceptable for now; mention it in the description so the first caller's run is the check.
  • Pokemon_FrameCoverage.h uses size_t without <cstddef> (it compiles through Time.h).

Review of #114 (dropped frames):
- A hold watcher fires a hold after the screen shows, so a screen that
  shows in the window's last hold fired only after the watch stopped.
  CoveredWatcher now keeps watching until a frame captured `tail` after
  the window's end, still bounded by the wall-clock cap.
- largest_gap rounds up to whole ms, so a gap a fraction over max_gap is
  UNKNOWN, not NOT_SEEN.
- Frames captured before the window opened are not handed to the wrapped
  watcher, so a fire on one is not SEEN.
- The window's end is a constructor argument (watch_for) or set by
  end_at() between sessions (run_watched), documented as such.
- WatchLimits carries max_gap, tail, cap and the poll period; run_watched
  checks only fired(); <cstddef> for size_t.
@dayfine

dayfine commented Nov 15, 2026

Copy link
Copy Markdown
Owner Author

Re the dropped-frames review, fixed in b41b3ab:

  1. M1 hold watcher at the window's end. CoveredWatcher takes a tail (the watcher's hold) and, once the window's end is known, stops on the first frame captured at or after end + tail. run_watched and watch_for wait in wall time until end + tail + cap. The window is still judged on [start, end]. A fire in the tail means the screen showed by the end, since the watcher needs a hold of frames before it fires. New CoveredWatch cases: "a screen showing in the window's last hold fires in the tail" (red against the old stop-at-end) and "the watch stops a tail after the window's end without a fire".
  2. L1 truncation. largest_gap now uses std::chrono::ceil, so a 100.5 ms gap is 101 ms and judged UNKNOWN against max_gap = 100ms. New FrameCoverage case: "a gap a fraction of a ms over the max gap does not cover". Test frame times are now double ms.
  3. L2 stale fire. Frames captured before the window opened are not handed to the wrapped watcher, so a fire on one is not SEEN. New case: "a frame captured before the window opened is not handed to the watcher".
  4. L3 threading. watch_for passes the end to the constructor. run_watched calls end_at() between the two sessions. The class comment now says to call end_at() and read fired()/coverage() only while no inference routine runs the watcher.

Nits: run_watched now checks only !covered.fired(). A WatchLimits struct (max_gap, tail, cap, period) replaces the loose parameters and passes the poll period to run_until/wait_until. <cstddef> is included in Pokemon_FrameCoverage.h. run_watched/watch_for are still not unit-tested: they need a VideoStream, and no fake for one exists in the unit runner, so the first caller's console run is their check. I compile-checked one run_watched<ProControllerContext> instantiation locally.

StoryCheckpoint::postconditions gets = {} so designated initializers that
leave it out build on Windows Clang (-Wmissing-designated-field-initializers).
The eight AutoStory test tables now hold each case's name next to its input
and expectation, as code health's test-case rule asks; the step JSON tests
pass the name to the readers as the parse source.
Windows Clang errors on designated initializers that skip a field
(-Wmissing-designated-field-initializers). A syntax check of every .cpp
nav/shared touches, with the Compiler.h pragma disabled, found only these.
@dayfine
dayfine merged commit 53fdefc into autostory/sv-retry-core Nov 15, 2026
16 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

autostory AutoStory programs game:shared Shared or game-neutral code navigation Maps, planner, walker

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant