Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
38 commits
Select commit Hold shift + click to select a range
47e0779
AutoStory: breakpoints, pause before each step and each leg (hook, op…
dayfine Nov 13, 2026
d8f6848
AutoStory breakpoints: code health fixes
dayfine Nov 13, 2026
6268f4f
AutoStory breakpoints: executors pause before each step of their chec…
dayfine Nov 13, 2026
2cb35d5
Merge autostory/story-breakpoints (#448) into frlg/story-breakpoints
dayfine Nov 13, 2026
d81ad7a
FRLG AutoStory: breakpoints pause before each step and each leg of a …
dayfine Nov 13, 2026
3a1a4d3
AutoStory breakpoints: the pause wrapper holds a move-only act
dayfine Nov 13, 2026
0bebe26
Merge remote-tracking branch 'origin/autostory/story-breakpoints' int…
dayfine Nov 13, 2026
ca7557f
FRLG AutoStory: the panel hands the run's pause points to its executor
dayfine Nov 13, 2026
0ac33f9
FRLG AutoStory: screenshot at each route leg end and Fly landing; 12.…
dayfine Nov 13, 2026
ceb666c
FRLG AutoStory: 12.03 golden for the shore at (10, 16)
dayfine Nov 13, 2026
5236be9
FRLG AutoStory: 12.03 golden, drop the duplicated tail
dayfine Nov 13, 2026
a22ca77
FRLG AutoStory: Fly lands on a fade, then the player on screen
dayfine Nov 13, 2026
a88d8f6
FRLG AutoStory: Fly landing header includes the direction type's real…
dayfine Nov 13, 2026
780c8e2
FRLG AutoStory: Fly landing frames test reads the boy sprite sheet
dayfine Nov 13, 2026
2b469db
FRLG AutoStory: Fly landing frames test uses the Pallet standing frame
dayfine Nov 13, 2026
8377384
FRLG AutoStory: Fly landing frames test reads either player sheet
dayfine Nov 13, 2026
a106f1a
FRLG AutoStory: 12.03 walks straight out of Fuchsia's Center; a turn …
dayfine Nov 13, 2026
c5a9646
FRLG AutoStory: step_once() and face_wall() pass turn_to()'s sprite a…
dayfine Nov 13, 2026
de9c24c
FRLG AutoStory: a step's facing and tile go together as StepStart; ma…
dayfine Nov 13, 2026
89ee006
FRLG AutoStory: the map-edge check reads the planner's maps, which co…
dayfine Nov 13, 2026
af42d6d
FRLG AutoStory: Fly landing test with the 02:46 fly-off frame (red)
dayfine Nov 13, 2026
8469910
FRLG AutoStory: Fly lands only once the screen has left the departure…
dayfine Nov 13, 2026
f710f66
FRLG AutoStory: Fly landing's departure bar from the measured frames
dayfine Nov 13, 2026
546a19b
FRLG AutoStory: Fly landing frames test split under the function limit
dayfine Nov 13, 2026
80c390a
Merge frlg/stage19-victory-road into frlg/story-breakpoints: upstream…
dayfine Nov 13, 2026
b0f28bc
Merge origin/autostory/engine into autostory/story-breakpoints
dayfine Nov 13, 2026
c4efcde
Merge origin/autostory/story-breakpoints into frlg/story-breakpoints
dayfine Nov 13, 2026
78d0bd5
Merge origin/autostory/engine into autostory/story-breakpoints
dayfine Nov 13, 2026
fb12257
Merge origin/frlg/stage19-victory-road into frlg/story-breakpoints
dayfine Nov 13, 2026
063bb94
Merge origin/autostory/story-breakpoints into frlg/story-breakpoints
dayfine Nov 13, 2026
21b8a73
Story breakpoints: step_label(), the label of the step under way
dayfine Nov 13, 2026
3df66d3
Merge origin/frlg/stage19-victory-road into frlg/story-breakpoints
dayfine Nov 13, 2026
d2e1d0f
Merge origin/autostory/story-breakpoints into frlg/story-breakpoints
dayfine Nov 13, 2026
1effff7
Merge remote-tracking branch 'origin/autostory/engine' into HEAD
dayfine Nov 14, 2026
d46c9ac
Use the shared ScreenEvent names after merging autostory/engine
dayfine Nov 14, 2026
4551094
Merge origin/autostory/story-breakpoints into frlg/story-breakpoints:…
dayfine Nov 14, 2026
8dc7680
Merge frlg/stage19-victory-road into frlg/story-breakpoints
dayfine Nov 14, 2026
c3b01fd
Merge origin/frlg/stage19-victory-road into frlg/story-breakpoints
dayfine Nov 14, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Original file line number Diff line number Diff line change
Expand Up @@ -82,6 +82,7 @@ StoryActionRegistry<PoseType>::StoryActionRegistry(const StoryGame<PoseType>& ga
: m_game(game)
, m_actions(builtin_story_handlers<PoseType>())
, m_game_problems(tile_arg_problems(game))
, m_pause(game.breakpoints, game.pause_point)
{
// A game's action replaces the built-in of its kind and name in place,
// so a kind's default stays the built-in one's position.
Expand Down Expand Up @@ -172,7 +173,7 @@ Outcome StoryActionRegistry<PoseType>::dispatch(StoryBackend<PoseType>& backend,
));
}
const StoryActionArgs args = with_fallbacks(action->spec, step.args);
return action->handler(backend, StoryActionCall{.step = step, .args = args}, state);
return action->handler(backend, StoryActionCall{.step = step, .args = args, .pause = m_pause}, state);
}


Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -31,7 +31,7 @@

// `game`'s actions. `game` must outlive the registry.
template <StoryPose PoseType>
class StoryActionRegistry{

Check warning on line 34 in SerialPrograms/Source/Pokemon/AutoStory/Engine/Pokemon_StoryActionRegistry.h

View workflow job for this annotation

GitHub Actions / code-health

Code health (advisory)

PokemonAutomation::Pokemon::StoryActionRegistry: public_methods=6 (advisory above 5, limit 7)
public:
explicit StoryActionRegistry(const StoryGame<PoseType>& game);
StoryActionRegistry(const StoryActionRegistry&) = delete;
Expand All @@ -58,6 +58,12 @@
// actions fails too.
std::vector<std::string> lint(const StoryCheckpoint& checkpoint) const;

// The pause points of this game's run (StoryGame::breakpoints and
// pause_point). Mutable state of the run, not of the game's actions.
StoryPausePoints& pause_points() const{
return m_pause;
}

// Runs `step`'s action with its args' fallbacks filled in; a step with
// no registered action fails as unsupported_step(), a console_only
// action on another backend as CONSOLE_ONLY, before any input.
Expand All @@ -73,6 +79,7 @@
std::vector<StoryActionSpec> m_specs;
// What is wrong with the game's own actions, reported with every lint.
std::vector<std::string> m_game_problems;
mutable StoryPausePoints m_pause;
};

// Instantiated once, in Pokemon_StoryActionRegistry.cpp.
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -97,7 +97,15 @@ inline std::optional<Pose> after_legs(const Pose& start, const std::vector<Story
template <StoryPose PoseType>
Outcome walk_legs(StoryBackend<PoseType>& backend, const StoryActionCall& call, RunState& state){
const std::vector<StoryLeg>& legs = story_arg<std::vector<StoryLeg>>(call.args, "legs");
for (const StoryLeg& leg : legs){
const std::vector<TilePos> start = tiles_of(state.pose);
std::optional<TilePos> tile = start.size() == 1 ? std::optional<TilePos>(start[0]) : std::nullopt;
for (size_t index = 0; index < legs.size(); index++){
const StoryLeg& leg = legs[index];
for (int c = 0; tile && c < leg.tiles; c++){
tile = tile->next(leg.direction);
}
call.pause.before_leg(story_leg_pause_label(index, legs.size(), leg.direction, leg.tiles, tile));
backend.scope().throw_if_cancelled();
for (int c = 0; c < leg.tiles; c++){
backend.tap(leg.direction);
}
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -26,26 +26,43 @@ namespace{
template <StoryPose PoseType>
class RunnerExecutor : public StoryStepExecutor{
public:
RunnerExecutor(StoryStepRunner<PoseType>& runner, const StoryGame<PoseType>& game)
RunnerExecutor(StoryStepRunner<PoseType>& runner, const StoryGame<PoseType>& game, StoryPausePoints& pause)
: m_runner(runner)
, m_game(game)
, m_pause(pause)
{}

virtual void begin_attempt(const StoryCheckpoint& data) override{
m_checkpoint = &data;
if (m_game.begin_attempt){
m_game.begin_attempt(data);
}
}
virtual Outcome run(const StoryStep& step, RunState& state) override{
m_pause.before_step(pause_label(step));
return m_runner.act(step, state);
}
virtual bool holds(std::string_view condition, RunState& state) override{
return m_runner.holds(condition, state);
}

private:
// The step's place in its checkpoint (step names are unique, which the
// lint checks).
std::string pause_label(const StoryStep& step) const{
size_t index = 0;
if (m_checkpoint != nullptr){
while (index < m_checkpoint->steps.size() && m_checkpoint->steps[index].name != step.name){
index++;
}
}
return story_step_pause_label(m_checkpoint == nullptr ? "" : m_checkpoint->id, index, step.name);
}

StoryStepRunner<PoseType>& m_runner;
const StoryGame<PoseType>& m_game;
StoryPausePoints& m_pause;
const StoryCheckpoint* m_checkpoint = nullptr;
};

// `game` with its SAVE step "save" saving `current` only while `mode` is
Expand Down Expand Up @@ -167,7 +184,11 @@ StoryEngine<PoseType>::StoryEngine(const StoryGame<PoseType>& game, StoryBackend
, m_backend(backend)
, m_registry(m_game)
, m_runner(m_registry, backend)
{}
{
m_registry.pause_points().set_log([&backend](std::string_view line){
backend.log(line);
});
}

template <StoryPose PoseType>
std::string StoryEngine<PoseType>::steps_hash(const StoryCheckpoint& checkpoint) const{
Expand Down Expand Up @@ -346,7 +367,7 @@ VerifyReport StoryEngine<PoseType>::verify_checkpoint(const StoryCheckpoint& che

template <StoryPose PoseType>
CheckpointReport StoryEngine<PoseType>::run_steps(const StoryCheckpoint& checkpoint, RunState& state){
RunnerExecutor<PoseType> executor(m_runner, m_game);
RunnerExecutor<PoseType> executor(m_runner, m_game, m_registry.pause_points());
Checkpoint events = build_story_checkpoint(checkpoint, executor, &m_prepared);
if (m_game.interrupts){
events.interrupts = m_game.interrupts(m_backend);
Expand Down
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
/* Story Engine Runs Tests

Check warning on line 1 in SerialPrograms/Source/Pokemon/AutoStory/Engine/Pokemon_StoryEngineRuns_Tests.cpp

View workflow job for this annotation

GitHub Actions / code-health

Code health (advisory)

<file>: file_lines=959 (advisory above 500, limit 1000)
*
* From: https://github.com/PokemonAutomation/
*
Expand Down Expand Up @@ -746,6 +746,143 @@
}


// A game whose "mark" action records "run <step>" and whose pause hook
// records "pause <label>", in `events`, in `mode`.
StoryGame<GridPose> breakpoint_game(StoryBreakpoints mode, const std::shared_ptr<std::vector<std::string>>& events){
StoryGame<GridPose> game;
game.id = "test";
game.actions.push_back(game_action<GridPose>("mark", [events](StoryBackend<GridPose>&, const StoryActionCall& call, RunState&){
events->push_back(std::format("run {}", call.step.name));
return outcome_ok();
}));
game.breakpoints = mode;
game.pause_point = [events](std::string_view label){
events->push_back(std::format("pause {}", label));
};
return game;
}

StoryStep legs_step(std::string name){
StoryStep step;
step.kind = StoryStepKind::LEGS;
step.name = std::move(name);
step.args = {{"legs", std::vector<StoryLeg>{{Direction::NORTH, 2}, {Direction::EAST, 3}}}};
return step;
}

// What `events` should be, as one line each, or what differs.
std::string expect_events(const std::vector<std::string>& events, const std::vector<std::string>& expected){
return events == expected ? "" : std::format("expected [{}], got [{}]", joined(expected), joined(events));
}

// Breakpoints in STEPS mode: the hook runs before each step, in order,
// labelled with the checkpoint, the step's place and its name; a walk's
// legs do not pause.
std::string pauses_before_each_step(CancellableScope& scope){
const auto events = std::make_shared<std::vector<std::string>>();
const StoryGame<GridPose> game = breakpoint_game(StoryBreakpoints::STEPS, events);
FakeStoryBackend<GridPose> backend({.looks = {look<GridPose>({ScreenEvent::PLAYER_CAN_MOVE})}}, scope);
StoryEngine<GridPose> engine(game, backend);
const StoryCheckpoint checkpoint = checkpoint_of("12.03", {game_step("first", "mark"), legs_step("shore"), game_step("last", "mark")});
RunState state;
state.pose = tile_pose("Shore", {TilePos{5, 5}}, Direction::NORTH);
if (!engine.run_checkpoint(checkpoint, SavePoint::RUN_END, state).run.completed){
return joined(backend.lines());
}
const std::string error = expect_events(*events, {
"pause 12.03/1 first", "run first", "pause 12.03/2 shore", "pause 12.03/3 last", "run last",
});
if (!error.empty()){
return error;
}
return has_line(backend, "[Break] 12.03/1 first: paused") && has_line(backend, "[Break] 12.03/1 first: continued")
? "" : "expected the [Break] paused and continued lines";
}

// LEGS mode adds a pause before each leg, labelled with the step, the leg's
// place, direction, tiles and the tile it ends on.
std::string pauses_before_each_leg(CancellableScope& scope){
const auto events = std::make_shared<std::vector<std::string>>();
const StoryGame<GridPose> game = breakpoint_game(StoryBreakpoints::LEGS, events);
FakeStoryBackend<GridPose> backend({.looks = {look<GridPose>({ScreenEvent::PLAYER_CAN_MOVE})}}, scope);
StoryEngine<GridPose> engine(game, backend);
const StoryCheckpoint checkpoint = checkpoint_of("12.03", {game_step("first", "mark"), legs_step("shore")});
RunState state;
state.pose = tile_pose("Shore", {TilePos{5, 5}}, Direction::NORTH);
if (!engine.run_checkpoint(checkpoint, SavePoint::RUN_END, state).run.completed){
return joined(backend.lines());
}
const std::string error = expect_events(*events, {
"pause 12.03/1 first", "run first", "pause 12.03/2 shore",
"pause 12.03/2 shore leg 1/2 north 2 -> (5, 3)", "pause 12.03/2 shore leg 2/2 east 3 -> (8, 3)",
});
if (!error.empty()){
return error;
}
// The pause is before the leg's input.
return expect_inputs(backend, "tap north, tap north, tap east, tap east, tap east");
}

// A leg's label has no destination when the walk starts on no single tile.
std::string leg_label_without_a_known_tile(CancellableScope& scope){
const auto events = std::make_shared<std::vector<std::string>>();
const StoryGame<GridPose> game = breakpoint_game(StoryBreakpoints::LEGS, events);
FakeStoryBackend<GridPose> backend({.looks = {look<GridPose>({ScreenEvent::PLAYER_CAN_MOVE})}}, scope);
StoryEngine<GridPose> engine(game, backend);
const StoryCheckpoint checkpoint = checkpoint_of("12.03", {legs_step("shore")});
RunState state;
engine.run_checkpoint(checkpoint, SavePoint::RUN_END, state);
return expect_events(*events, {
"pause 12.03/1 shore", "pause 12.03/1 shore leg 1/2 north 2", "pause 12.03/1 shore leg 2/2 east 3",
});
}

// OFF, and a hook-less game, never pause or log.
std::string off_never_pauses(CancellableScope& scope){
const auto events = std::make_shared<std::vector<std::string>>();
StoryGame<GridPose> game = breakpoint_game(StoryBreakpoints::OFF, events);
FakeStoryBackend<GridPose> backend({.looks = {look<GridPose>({ScreenEvent::PLAYER_CAN_MOVE})}}, scope);
StoryEngine<GridPose> engine(game, backend);
const StoryCheckpoint checkpoint = checkpoint_of("12.03", {game_step("first", "mark"), legs_step("shore")});
RunState state;
engine.run_checkpoint(checkpoint, SavePoint::RUN_END, state);
const std::string error = expect_events(*events, {"run first"});
if (!error.empty()){
return error;
}
StoryGame<GridPose> no_hook = breakpoint_game(StoryBreakpoints::LEGS, events);
no_hook.pause_point = {};
FakeStoryBackend<GridPose> quiet({.looks = {look<GridPose>({ScreenEvent::PLAYER_CAN_MOVE})}}, scope);
StoryEngine<GridPose> quiet_engine(no_hook, quiet);
state = RunState();
quiet_engine.run_checkpoint(checkpoint, SavePoint::RUN_END, state);
for (const std::string& line : quiet.lines()){
if (line.starts_with("[Break]")){
return std::format("a game with no hook logged {}", line);
}
}
return "";
}

// A lab wait is called with the label and the run's scope; none installed,
// no hook.
std::string pause_hook_from_the_installed_wait(CancellableScope& scope){
if (make_story_pause_hook(scope)){
return "expected no hook while no wait is installed";
}
std::vector<std::string> waited;
set_story_pause_wait([&](std::string_view label, CancellableScope& with){
waited.push_back(std::format("{} {}", label, &with == &scope));
});
const StoryPauseHook hook = make_story_pause_hook(scope);
if (hook){
hook("12.03/1 first");
}
set_story_pause_wait({});
return waited == std::vector<std::string>{"12.03/1 first true"} ? "" : std::format("expected the wait to get the label and the scope: {}", joined(waited));
}


struct RunsCase{
// One check above, by name.
struct Input{
Expand Down Expand Up @@ -779,6 +916,11 @@
{.input = {.name = "console_only refused off console", .check = &console_only_refused}, .expectation = {}},
{.input = {.name = "no reload for console_only", .check = &segment_no_reload_for_console_only}, .expectation = {}},
{.input = {.name = "verify saves after all passed", .check = &verify_saves_after_all_passed}, .expectation = {}},
{.input = {.name = "breakpoints pause before each step", .check = &pauses_before_each_step}, .expectation = {}},
{.input = {.name = "breakpoints pause before each leg", .check = &pauses_before_each_leg}, .expectation = {}},
{.input = {.name = "breakpoints leg label needs a known tile", .check = &leg_label_without_a_known_tile}, .expectation = {}},
{.input = {.name = "breakpoints off never pauses", .check = &off_never_pauses}, .expectation = {}},
{.input = {.name = "breakpoints hook uses the installed wait", .check = &pause_hook_from_the_installed_wait}, .expectation = {}},
};

class StoryEngineRunsTest : public UnitTest{
Expand Down
12 changes: 12 additions & 0 deletions SerialPrograms/Source/Pokemon/AutoStory/Engine/Pokemon_StoryGame.h
Original file line number Diff line number Diff line change
Expand Up @@ -21,6 +21,7 @@
#include "Pokemon/AutoStory/Pokemon_StoryOutcome.h"
#include "Pokemon/AutoStory/Types/Pokemon_StoryActionArg.h"
#include "Pokemon/AutoStory/Types/Pokemon_StoryActionSpec.h"
#include "Pokemon/AutoStory/Types/Pokemon_StoryBreakpoints.h"
#include "Pokemon/AutoStory/Types/Pokemon_StoryCheckpoint.h"
#include "Pokemon/AutoStory/Types/Pokemon_StoryStep.h"
#include "Pokemon_StoryBackend.h"
Expand All @@ -35,6 +36,9 @@ namespace Pokemon{
struct StoryActionCall{
const StoryStep& step;
const StoryActionArgs& args;
// The run's pause points: an action that walks legs calls
// before_leg() before each (Pokemon_StoryBreakpoints.h).
StoryPausePoints& pause;
};

// An action's code: reads its call's args and drives the backend. A
Expand Down Expand Up @@ -118,6 +122,14 @@ struct StoryGame{
// What can stop a step part-way (a wild battle, a trainer who saw
// us), built for each checkpoint run. Optional.
std::function<std::vector<Interrupt>(StoryBackend<PoseType>& backend)> interrupts = {};
// Where the run pauses for the user to look at the console, and what a
// pause does: the engine calls the hook with a label such as
// "12.03/5 pallet_shore" before each step, and the walk action with
// "12.03/5 pallet_shore leg 2/5 east 4 -> (10, 10)" before each leg
// (only with LEGS). Optional: with no hook, or OFF, a run never pauses.
// The hook returns when the run goes on, or when the run is cancelled.
StoryBreakpoints breakpoints = StoryBreakpoints::OFF;
StoryPauseHook pause_point = {};
};


Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -121,8 +121,17 @@ Checkpoint build_story_checkpoint(const StoryCheckpoint& data, StoryStepExecutor
if (data.start || data.start_gates || !data.start_flags.empty()){
checkpoint.events.push_back(from_save_event(data));
}
for (const StoryStep& step : data.steps){
for (size_t index = 0; index < data.steps.size(); index++){
const StoryStep& step = data.steps[index];
checkpoint.events.push_back(story_event(step, executor));
if (StoryPausePoints* pause = executor.pause_points()){
checkpoint.events.back().act = [
act = std::move(checkpoint.events.back().act), pause, label = story_step_pause_label(data.id, index, step.name)
](RunState& state) mutable{
pause->before_step(label);
return act(state);
};
}
if (prepared != nullptr && step.once_per_save){
run_once_per_save(std::format("{}/{}", data.id, step.name), checkpoint.events.back(), *prepared);
}
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -40,6 +40,7 @@
#include "Pokemon_TilePose.h"
#include "Types/Pokemon_DeclaredPose.h"
#include "Types/Pokemon_GridPose.h"
#include "Types/Pokemon_StoryBreakpoints.h"
#include "Types/Pokemon_StoryCheckpoint.h"
#include "Types/Pokemon_StoryStep.h"
#include "Types/Pokemon_StoryStepKind.h"
Expand Down Expand Up @@ -67,6 +68,20 @@ class StoryStepExecutor{
// Whether the condition named in a step's skip_if holds: by default,
// whether the run has the flag (set by an earlier step's action).
virtual bool holds(std::string_view condition, RunState& state);

// The game's pause points (Pokemon_StoryBreakpoints.h), which the
// checkpoints built for this executor call before each of their steps.
// The game owns them and sets them before it builds a checkpoint; it
// calls before_leg() from its own leg loops. None by default: no pauses.
void set_pause_points(StoryPausePoints* pause){
m_pause = pause;
}
StoryPausePoints* pause_points() const{
return m_pause;
}

private:
StoryPausePoints* m_pause = nullptr;
};

// `pose` as the engine's Pose: a TilePose, TILE for one tile, SET for several.
Expand Down
Loading
Loading