Skip to content

CommonTools: the screen machine and its step trace - #541

Draft
dayfine wants to merge 11 commits into
plza/upstream/s2-06from
plza/upstream/s2-07
Draft

dayfine wants to merge 11 commits into
plza/upstream/s2-06from
plza/upstream/s2-07

Conversation

@dayfine

@dayfine dayfine commented Nov 15, 2026 •

Copy link
Copy Markdown
Owner

Depends on #540

Adds CommonTools/ScreenMachine: a closed loop over known screens (read, take the one step the screen calls for, read again, with each state listing the screens it may lead to), its step trace that logs every screen change and input, and the bridge from screen events to the engine's observation. Tests: the CommonTools::ScreenMachine suite on scripted observations. The console path (run_screen_machine(), read_screen_state()) and screen_observation() have no caller in this chain: Used by the PLZA program PR (batch 2). Fork Draft CI builds it. Part of the re-split of #522/#524/#525 into reviewable steps; review fixes are new commits on the PR that owns each problem, merged up the chain.

@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: f3a5605

Verdict

NEEDS_REWORK

First-pass review of this PR's own diff against plza/upstream/s2-06, held to the infra bar (CommonTools). Code health: 0 failures, 4 advisories. Fork Draft CI build passed; the ubuntu job was still pending when read.

High

  1. An infra module with no suite and, apart from tests, no caller. At the chain tip (#545, plza/upstream/s2-11):

    • The console path has no caller: run_screen_machine() (a template nothing instantiates, so it has never been compiled), read_screen_state(), and StepTrace(VideoStream&, ...) with its screenshot folder.
    • run_screen_machine_on_observations() and match_screen_state() are reached only from tests (Pokemon_StoryEngineRuns_Tests.cpp and Pokemon_StoryEnginePolicy_Tests.cpp in #542).
    • Pokemon::screen_observation() (Engine/Pokemon_ScreenObservation.cpp) is never called.

    Infra needs its own tests in the PR that adds it, and upstream will ask what uses it. Either add a ScreenMachine suite here (scripted observations: unexpected next screen, max_in_a_row, max_visits, max_still stall vs MAX_UNCHANGED, timeout, terminal) and name the program that will run the console path, or cut the module down to the observation loop the engine uses and add the console path with its first caller.

Medium

  1. CommonTools/ScreenMachine/ScreenMachine.h:49 size_t max_visits; has no default member initializer, unlike its neighbours. A ScreenState s; followed by field assignment (the pattern the #542 tests use) leaves it indeterminate if a caller forgets it. Give every field a default (= {} / = SIZE_MAX; Windows clang also flags omitted fields in designated initializers). Make "0" mean something documented, or make it required through a constructor.
  2. run_screen_machine() calls state.act() unconditionally (ScreenMachine.h), while run_screen_machine_on_observations() checks if (state->act). A state with no step throws std::bad_function_call on a console and works in a simulation. Pick one rule and document it on ScreenState::act.
  3. CommonTools/ScreenMachine/ScreenMachine.cpp:65 c--; on a size_t loop counter at 0 wraps to SIZE_MAX and comes back to 0 on c++. It works, but only through unsigned wraparound. Count frames with a separate counter, or use a while with an explicit read count (user theme T5).
  4. read_screen_state(..., VideoSnapshot& frame) (ScreenMachine.h:68) returns the frame through an output parameter. Return a small struct {const ScreenState& state; VideoSnapshot frame;} instead (user theme T4, TotW #176).
  5. Line endings. The four CommonTools files (ScreenMachine.{h,cpp}, StepTrace.{h,cpp}) are LF; every other new file in this chain, including ScreenObservation.h in the same folder (#538), is CRLF. Convert them to CRLF to match the codebase.

Low

  1. Unnamed literals: StepTrace.cpp:64 keeps 12 recent screens; read_screen_state uses 20 reads, 150 ms, 500 ms and 10 s, with "after 3s" only implied; same_screen has an RMSD threshold of 2.0. Name them with a why, as MAX_UNCHANGED already is (T2).
  2. Timeout messages print timeout.count() / 1000 as an integer, so a 1500 ms timeout reads "1s". Use tostr_fixed as StepTrace::screen does.
  3. Pokemon/AutoStory/Engine/Pokemon_ScreenObservation.{h,cpp} is Pokemon-side code in an infra PR, and with no caller and no test (see 1) it could wait for its first user.
  4. StepTrace::screen(const std::string&), action(const std::string&) and fail(const std::string&): read-only string parameters should be std::string_view by value.

Checked: brace style; filesystem only through the Filesystem:: wrappers; no std::thread/std::mutex; new files are in SourceFiles.cmake; same_screen() (declared in #538) is defined here.

…ts definition

The observation-loop tests (state matching, terminal state, no match, too
many visits, timeout, the still checks) move here from the engine suites as
CommonTools::ScreenMachine, on scripted observations. same_screen() is
declared in ScreenMachine.h beside its definition, max_visits defaults to no
limit, run_screen_machine() skips a state with no step as the observation
loop does, and the four files are CRLF like the rest of the tree.
@dayfine

dayfine commented Nov 15, 2026

Copy link
Copy Markdown
Owner Author

Review fixes, tip 47e9f273b:

Fixed: 1 (new CommonTools::ScreenMachine suite on scripted observations: matching, terminal state, no match, too many visits, timeout, the still limit and the 8-step stall, moved from #542; the description says the console path and screen_observation() are used by the PLZA program PR, batch 2), 2 (max_visits = SIZE_MAX), 3 (run_screen_machine() skips a state with no act, as the observation loop does; documented on act), 6 (four files CRLF). same_screen() is now declared here.
Not changed: 4, 5, 7, 8, 9, 10.

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