Skip to content

AutoStory: the story backend interface and what a game hands the engine - #538

Draft
dayfine wants to merge 10 commits into
plza/upstream/s2-03from
plza/upstream/s2-04
Draft

dayfine wants to merge 10 commits into
plza/upstream/s2-03from
plza/upstream/s2-04

Conversation

@dayfine

@dayfine dayfine commented Nov 15, 2026 •

Copy link
Copy Markdown
Owner

Depends on #537

Adds the interface the story engine drives: the backend (input and observation only; a console or a simulation implements it), the pose concept with the zone pose of a game with no tile grid (PLZA), the screen observation a backend returns, and StoryGame, what a game hands the engine as data plus functions. Some helpers (direction_degrees(), StoryActionNotImplemented) have no caller in this chain: Used by the PLZA program PR (batch 2). This is interface only; the fake backend and the tests that drive it come with the action registry in the next PR. 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: f7cc972

Verdict

NEEDS_REWORK

First-pass review of this PR's own diff against plza/upstream/s2-03. Code health: 0 failures, 2 advisories. Two allow tags (char_pointer on Exception::name(), public_methods=10 on StoryBackend) carry reasons that hold up. Fork Draft CI build passed; the ubuntu job was still pending when read.

High

  1. Code that nothing calls or tests, even at the chain tip (#545):

    • Engine/Pokemon_ZonePose.h:37 direction_degrees() has no caller.
    • Engine/Pokemon_StoryActionNotImplemented.h:21 StoryActionNotImplemented is never thrown or caught.
    • Engine/Pokemon_StoryPoseConcept.h:77 pose_matches() (both overloads, GridPose and ZonePose) is never called. The StoryPose concept (:58) requires it, but the engine never asks whether a pose matches a target.

    So the tile-subset logic in pose_matches(GridPose) has neither a user nor a test. Drop what no PR uses. For anything kept for a later PR, name that PR in the body and add a unit test here.

  2. same_screen() is declared here but defined in #541. CommonTools/ScreenMachine/ScreenObservation.h:42 declares it, and the definition is in ScreenMachine.cpp (#541). Nothing calls it before then, so this PR links, but an infra header declaring a function with no body does not stand alone. Move the declaration to #541 together with its definition and its tests, or define it here in a ScreenObservation.cpp.

Medium

  1. CommonTools/ScreenMachine/ScreenObservation.h is infra, added in a PR about Pokemon story interfaces. Its header comment points at ScreenState::matches_observation, which arrives in #541. Consider moving it into the ScreenMachine PR (#541) so the infra pieces get reviewed together at the infra bar. If it stays here, the comment should not depend on a type this PR does not have.
  2. Logic in this PR without a test in this PR: story_reader_supplies() (Engine/Pokemon_StoryGame.h:84, exact name or * prefix), story_heading(), pose_text(). The body says tests come with the fake backend in #539. story_reader_supplies is pure and has edge cases ("*" alone, "bag.*" against "bag"). A few table cases here would keep each PR standing alone.

Low

  1. ScreenObservation.h:30 when = WallClock::min(): is min() a "not set" sentinel any reader checks? If so, use std::optional<WallClock>. If not, say it is only a default.
  2. ScreenObservation.h:32: the example readings ("bag.RARE_CANDY", "facing") are game words in an infra comment. Use neutral examples, or say "a game names its readings".
  3. Engine/Pokemon_ZonePose.h:37: direction_degrees() is not about zone poses (if it stays at all). It belongs next to Direction or in the stick/walk action that would use it.

Checked: brace style, no std::filesystem/std::thread/std::mutex, CRLF kept, new files are in SourceFiles.cmake, and the includes resolve against the parents.

…ines it

The header declared same_screen() with no definition until the screen machine
arrives; the declaration moves there. Its comments no longer point at a type
that is not here yet or use one game's reading names.
@dayfine

dayfine commented Nov 15, 2026

Copy link
Copy Markdown
Owner Author

Review fixes, tip 4a5e9bf42:

Fixed: 2 (same_screen() declaration moved to ScreenMachine.h in #541, beside its definition and tests), 3 (comment no longer depends on ScreenState), 5 (when's default documented), 6 (neutral reading names).
1: direction_degrees() and StoryActionNotImplemented are used by the PLZA program (batch 2); the description says so. pose_matches() is kept because the StoryPose concept requires it; it has no caller anywhere yet, so dropping it from the concept is open for the user.
Not changed: 4, 7.

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