From 3d9bf943def9a12d0f808bdf028af6c73a6e43a6 Mon Sep 17 00:00:00 2001 From: dayfine Date: Sun, 1 Nov 2026 09:53:37 -0800 Subject: [PATCH 001/102] Pokemon navigation: story steps, one table vocabulary for FRLG and BDSP 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 Claude-Session: https://claude.ai/code/session_01AKYzhrMnPK61XHWEch4a6E --- .../ComputerPrograms_UnitTestRunner.cpp | 1 + .../Navigation/Pokemon_Navigation_Tests.h | 1 + .../Pokemon/Navigation/Pokemon_StorySteps.cpp | 260 ++++++++++++ .../Pokemon/Navigation/Pokemon_StorySteps.h | 180 +++++++++ .../Navigation/Pokemon_StorySteps_Tests.cpp | 369 ++++++++++++++++++ SerialPrograms/cmake/SourceFiles.cmake | 3 + 6 files changed, 814 insertions(+) create mode 100644 SerialPrograms/Source/Pokemon/Navigation/Pokemon_StorySteps.cpp create mode 100644 SerialPrograms/Source/Pokemon/Navigation/Pokemon_StorySteps.h create mode 100644 SerialPrograms/Source/Pokemon/Navigation/Pokemon_StorySteps_Tests.cpp diff --git a/SerialPrograms/Source/ComputerPrograms/ComputerPrograms_UnitTestRunner.cpp b/SerialPrograms/Source/ComputerPrograms/ComputerPrograms_UnitTestRunner.cpp index 2e17398c46..f6b73d8901 100644 --- a/SerialPrograms/Source/ComputerPrograms/ComputerPrograms_UnitTestRunner.cpp +++ b/SerialPrograms/Source/ComputerPrograms/ComputerPrograms_UnitTestRunner.cpp @@ -65,6 +65,7 @@ UnitTestDatabase make_UNIT_TESTS_ALL(){ Pokemon::add_tests_MapData(ret); Pokemon::add_tests_StoryEvents(ret); Pokemon::add_tests_StorySegments(ret); + Pokemon::add_tests_StorySteps(ret); NintendoSwitch::add_tests_CheckOnlineDetector(ret); NintendoSwitch::add_tests_FailedToConnectDetector(ret); NintendoSwitch::add_tests_UpdatePopupDetector(ret); diff --git a/SerialPrograms/Source/Pokemon/Navigation/Pokemon_Navigation_Tests.h b/SerialPrograms/Source/Pokemon/Navigation/Pokemon_Navigation_Tests.h index 73eac9841a..8506321ce3 100644 --- a/SerialPrograms/Source/Pokemon/Navigation/Pokemon_Navigation_Tests.h +++ b/SerialPrograms/Source/Pokemon/Navigation/Pokemon_Navigation_Tests.h @@ -20,6 +20,7 @@ void add_tests_LegPlanner(UnitTestDatabase& database); void add_tests_MapData(UnitTestDatabase& database); void add_tests_StoryEvents(UnitTestDatabase& database); void add_tests_StorySegments(UnitTestDatabase& database); +void add_tests_StorySteps(UnitTestDatabase& database); // (name, JSON text) of each map in Pokemon/Navigation/TestMaps/, built into // the program by pa_embed_text_files() (cmake/EmbedTextFiles.cmake). diff --git a/SerialPrograms/Source/Pokemon/Navigation/Pokemon_StorySteps.cpp b/SerialPrograms/Source/Pokemon/Navigation/Pokemon_StorySteps.cpp new file mode 100644 index 0000000000..406e45e36f --- /dev/null +++ b/SerialPrograms/Source/Pokemon/Navigation/Pokemon_StorySteps.cpp @@ -0,0 +1,260 @@ +/* Story Steps + * + * From: https://github.com/PokemonAutomation/ + * + */ + +#include +#include +#include +#include +#include "Pokemon_StorySteps.h" + +namespace PokemonAutomation{ +namespace Pokemon{ + + +const char* story_step_kind_name(StoryStepKind kind){ + switch (kind){ + case StoryStepKind::NEW_GAME: + return "NEW_GAME"; + case StoryStepKind::OPTIONS: + return "OPTIONS"; + case StoryStepKind::ROUTE: + return "ROUTE"; + case StoryStepKind::LEGS: + return "LEGS"; + case StoryStepKind::STEP: + return "STEP"; + case StoryStepKind::TALK: + return "TALK"; + case StoryStepKind::ANSWER: + return "ANSWER"; + case StoryStepKind::MASH: + return "MASH"; + case StoryStepKind::BATTLE: + return "BATTLE"; + case StoryStepKind::TRAIN: + return "TRAIN"; + case StoryStepKind::HEAL: + return "HEAL"; + case StoryStepKind::SHOP: + return "SHOP"; + case StoryStepKind::SAVE: + return "SAVE"; + case StoryStepKind::READY: + return "READY"; + case StoryStepKind::GAME: + return "GAME"; + } + return "?"; +} + + +Outcome unsupported_step(const StoryStep& step){ + return outcome_failed("unsupported_step", std::format("{} {}", story_step_kind_name(step.kind), step.name)); +} + +Outcome StoryStepExecutor::run(RunState& state, const StoryStep& step){ + return dispatch_story_step(*this, state, step); +} + +Outcome StoryStepExecutor::new_game(RunState&, const StoryStep& step){ + return unsupported_step(step); +} +Outcome StoryStepExecutor::options(RunState&, const StoryStep& step){ + return unsupported_step(step); +} +Outcome StoryStepExecutor::route(RunState&, const StoryStep& step){ + return unsupported_step(step); +} +Outcome StoryStepExecutor::legs(RunState&, const StoryStep& step){ + return unsupported_step(step); +} +Outcome StoryStepExecutor::step(RunState&, const StoryStep& step){ + return unsupported_step(step); +} +Outcome StoryStepExecutor::talk(RunState&, const StoryStep& step){ + return unsupported_step(step); +} +Outcome StoryStepExecutor::answer(RunState&, const StoryStep& step){ + return unsupported_step(step); +} +Outcome StoryStepExecutor::mash(RunState&, const StoryStep& step){ + return unsupported_step(step); +} +Outcome StoryStepExecutor::battle(RunState&, const StoryStep& step){ + return unsupported_step(step); +} +Outcome StoryStepExecutor::train(RunState&, const StoryStep& step){ + return unsupported_step(step); +} +Outcome StoryStepExecutor::heal(RunState&, const StoryStep& step){ + return unsupported_step(step); +} +Outcome StoryStepExecutor::shop(RunState&, const StoryStep& step){ + return unsupported_step(step); +} +Outcome StoryStepExecutor::save(RunState&, const StoryStep& step){ + return unsupported_step(step); +} +Outcome StoryStepExecutor::ready(RunState&, const StoryStep& step){ + return unsupported_step(step); +} +Outcome StoryStepExecutor::game(RunState&, const StoryStep& step){ + return unsupported_step(step); +} + +Outcome dispatch_story_step(StoryStepExecutor& executor, RunState& state, const StoryStep& step){ + switch (step.kind){ + case StoryStepKind::NEW_GAME: + return executor.new_game(state, step); + case StoryStepKind::OPTIONS: + return executor.options(state, step); + case StoryStepKind::ROUTE: + return executor.route(state, step); + case StoryStepKind::LEGS: + return executor.legs(state, step); + case StoryStepKind::STEP: + return executor.step(state, step); + case StoryStepKind::TALK: + return executor.talk(state, step); + case StoryStepKind::ANSWER: + return executor.answer(state, step); + case StoryStepKind::MASH: + return executor.mash(state, step); + case StoryStepKind::BATTLE: + return executor.battle(state, step); + case StoryStepKind::TRAIN: + return executor.train(state, step); + case StoryStepKind::HEAL: + return executor.heal(state, step); + case StoryStepKind::SHOP: + return executor.shop(state, step); + case StoryStepKind::SAVE: + return executor.save(state, step); + case StoryStepKind::READY: + return executor.ready(state, step); + case StoryStepKind::GAME: + return executor.game(state, step); + } + return unsupported_step(step); +} + + +Event story_event(const StoryStep& step, StoryStepExecutor& executor){ + Event event; + event.name = step.name; + event.why = step.why; + for (const std::string& name : step.skip_if){ + event.skip_if.push_back(condition(name, [&executor, name](RunState& state){ + return executor.holds(name, state); + })); + } + event.act = [&executor, &step](RunState& state){ + return executor.run(state, step); + }; + event.pose_learned = step.pose_after; + return event; +} + +namespace{ + +// The first event of a checkpoint that starts from a save: where the save +// leaves the player, for a run that reloaded it. +Event from_save_event(const Pose& start){ + Event event; + event.name = "from_save"; + event.why = "where the checkpoint's save leaves the player"; + event.act = [](RunState&){ return outcome_ok(); }; + event.pose_learned = start; + return event; +} + +} + +Checkpoint build_story_checkpoint(const StoryCheckpoint& data, StoryStepExecutor& executor){ + Checkpoint checkpoint; + checkpoint.id = data.id; + if (data.start){ + checkpoint.events.push_back(from_save_event(*data.start)); + } + for (const StoryStep& step : data.steps){ + checkpoint.events.push_back(story_event(step, executor)); + } + return checkpoint; +} + + +namespace{ + +// What a step of its kind must have, or "" if it has it. +std::string missing_field(const StoryStep& step){ + switch (step.kind){ + case StoryStepKind::ROUTE: + case StoryStepKind::READY: + return step.target ? "" : "no target"; + case StoryStepKind::LEGS: + if (step.legs.empty()){ + return "no legs"; + } + for (const StoryLeg& leg : step.legs){ + if (leg.tiles <= 0){ + return "a leg of no tiles"; + } + } + return ""; + case StoryStepKind::TRAIN: + return step.battles > 0 ? "" : "no battles"; + case StoryStepKind::SHOP: + return step.items.empty() ? "no items" : ""; + case StoryStepKind::GAME: + return step.variant.empty() ? "no variant" : ""; + default: + return ""; + } +} + +} + +std::vector lint_story_checkpoint(const StoryCheckpoint& data){ + std::vector problems; + if (data.id.empty()){ + problems.emplace_back("a checkpoint has no id"); + } + std::set names; + for (size_t c = 0; c < data.steps.size(); c++){ + const StoryStep& step = data.steps[c]; + const std::string where = std::format("{} step {}", data.id, c + 1); + if (step.name.empty()){ + problems.emplace_back(where + ": no name"); + }else if (!names.insert(step.name).second){ + problems.emplace_back(std::format("{}: a second step named {}", where, step.name)); + } + const std::string missing = missing_field(step); + if (!missing.empty()){ + problems.emplace_back(std::format("{} {}: {} {}", where, step.name, story_step_kind_name(step.kind), missing)); + } + } + return problems; +} + + +Pose tile_pose(std::string map, std::vector tiles, std::optional facing){ + Pose pose; + pose.map = std::move(map); + pose.certainty = tiles.empty() ? PoseCertainty::UNKNOWN + : tiles.size() == 1 ? PoseCertainty::TILE : PoseCertainty::SET; + pose.where = std::make_shared(std::move(tiles), facing); + return pose; +} + +std::optional facing_of(const Pose& pose){ + const TilePose* tile_pose = dynamic_cast(pose.where.get()); + return tile_pose ? tile_pose->facing : std::nullopt; +} + + + +} +} diff --git a/SerialPrograms/Source/Pokemon/Navigation/Pokemon_StorySteps.h b/SerialPrograms/Source/Pokemon/Navigation/Pokemon_StorySteps.h new file mode 100644 index 0000000000..6e74929c8e --- /dev/null +++ b/SerialPrograms/Source/Pokemon/Navigation/Pokemon_StorySteps.h @@ -0,0 +1,180 @@ +/* Story Steps + * + * From: https://github.com/PokemonAutomation/ + * + * One vocabulary of story steps for the tile games (FRLG, BDSP): a route, + * a fixed walk, a step onto a trigger, a talk, a YES/NO, a scene, a + * battle, the nurse, a shop, a save, and so on. A checkpoint is a list of + * such steps, plain data, so a game's story is a table its unit tests can + * plan without a console. + * + * build_story_checkpoint() turns a table row into engine events + * (Pokemon_StoryEvents.h). Each event's action asks the game's + * StoryStepExecutor to do its step: one virtual per kind, so a game + * implements the kinds it uses, and a step the game has no way of doing + * fails by name instead of doing something else. + * + * Poses are the game's own (Pose, with a TilePose for these games): a + * checkpoint's start, a scene's end and a route's target are poses, and + * an executor that knows where a step left the player says so in its + * Outcome, which the engine writes into the run. + * + */ + +#ifndef PokemonAutomation_Pokemon_StorySteps_H +#define PokemonAutomation_Pokemon_StorySteps_H + +#include +#include +#include +#include +#include "Pokemon_Grid.h" +#include "Pokemon_StoryEvents.h" +#include "Pokemon_TilePose.h" + +namespace PokemonAutomation{ +namespace Pokemon{ + + +enum class StoryStepKind{ + NEW_GAME, // title screen (no save) to the first room + OPTIONS, // the game's options as the story needs them + ROUTE, // plan and walk to `target` + LEGS, // walk `legs` as given + STEP, // one step `direction`: onto a trigger, into a door + TALK, // A at what the player faces + ANSWER, // text to a YES/NO, then `yes` + MASH, // text until the overworld is back: a scene + BATTLE, // text into a battle, fight it, text to the overworld + TRAIN, // fight `battles` wild battles where the player stands + HEAL, // the nurse, from in front of her or of the Center's door + SHOP, // `items` from a shop + SAVE, // save the game where the player stands + READY, // before a big battle: items, and the nurse at `target` if they can't + GAME, // a step only this game has, named by `variant` +}; +const char* story_step_kind_name(StoryStepKind kind); + + +// A straight leg of a fixed walk. +struct StoryLeg{ + Direction direction = Direction::NORTH; + int tiles = 0; +}; + +// An item and how many to get. +struct StoryItem{ + std::string item; + size_t quantity = 0; +}; + +struct StoryStep{ + StoryStepKind kind = StoryStepKind::TALK; + std::string name; + std::string why; + + // ROUTE: where to go; with several tiles, any of them. READY: the nurse. + std::optional target; + // STEP + Direction direction = Direction::NORTH; + // LEGS + std::vector legs; + // ROUTE, LEGS: fight wild battles on the way instead of running. + bool fight_wild = false; + // ANSWER + bool yes = true; + // BATTLE: losing goes on (a rival's first battle). + bool may_lose = false; + // TRAIN + size_t battles = 0; + // SHOP + std::vector items; + // How this game does the kind, when it has more than one way: a + // route's plan costs, a door lined up by sight, the Mart lady instead + // of the clerk. Empty is the game's usual way. GAME: the step's name + // in the game's executor. + std::string variant; + + // Skipped when all of these hold (and there is at least one): names + // the game's executor answers (StoryStepExecutor::holds()). + std::vector skip_if; + // Where the step leaves the player, when its action does not say: the + // end of a scene that moves the player. + std::optional pose_after; +}; + +struct StoryCheckpoint{ + std::string id; + std::string title; + // Where its starting save leaves the player; none for a new game. + std::optional start; + std::vector steps; +}; + + +// How a game does each kind of step. Every kind fails as unsupported +// unless the game overrides it. +class StoryStepExecutor{ +public: + virtual ~StoryStepExecutor() = default; + + // Runs `step`: dispatch_story_step() by default. A game overrides it + // to wrap every step, e.g. to turn a failed console step into a failed + // Outcome. + virtual Outcome run(RunState& state, const StoryStep& step); + + // Whether the condition named in a step's skip_if holds. + virtual bool holds(const std::string& condition, RunState& state) = 0; + + virtual Outcome new_game(RunState& state, const StoryStep& step); + virtual Outcome options(RunState& state, const StoryStep& step); + virtual Outcome route(RunState& state, const StoryStep& step); + virtual Outcome legs(RunState& state, const StoryStep& step); + virtual Outcome step(RunState& state, const StoryStep& step); + virtual Outcome talk(RunState& state, const StoryStep& step); + virtual Outcome answer(RunState& state, const StoryStep& step); + virtual Outcome mash(RunState& state, const StoryStep& step); + virtual Outcome battle(RunState& state, const StoryStep& step); + virtual Outcome train(RunState& state, const StoryStep& step); + virtual Outcome heal(RunState& state, const StoryStep& step); + virtual Outcome shop(RunState& state, const StoryStep& step); + virtual Outcome save(RunState& state, const StoryStep& step); + virtual Outcome ready(RunState& state, const StoryStep& step); + virtual Outcome game(RunState& state, const StoryStep& step); +}; + +// Calls the executor's method for the step's kind. +Outcome dispatch_story_step(StoryStepExecutor& executor, RunState& state, const StoryStep& step); + +// "unsupported_step: TRAIN train_in_grass": what an executor without the kind returns. +Outcome unsupported_step(const StoryStep& step); + + +// The step as an event that runs it with `executor`. Both must outlive +// the event. +Event story_event(const StoryStep& step, StoryStepExecutor& executor); + +// The checkpoint `data` as events: "from_save" first when it has a start +// (the start pose, for a run that reloaded its save), then one event per +// step. `data` and `executor` must outlive the checkpoint. Saving is the +// game's: it sets the checkpoint's save, or adds a SAVE step. +Checkpoint build_story_checkpoint(const StoryCheckpoint& data, StoryStepExecutor& executor); + +// Problems an author should fix before running: an empty id, unnamed or +// repeated steps, a route or READY without a target, empty legs, a GAME +// step without a variant, TRAIN without battles, SHOP without items. +std::vector lint_story_checkpoint(const StoryCheckpoint& data); + + +// A pose on one of `tiles` of `map`, facing `facing` if set: TILE for one +// tile, SET for several, UNKNOWN for none. +Pose tile_pose(std::string map, std::vector tiles, std::optional facing = std::nullopt); + +// The facing of a tile pose; nothing for another pose or none. +std::optional facing_of(const Pose& pose); + + + +} +} +#endif diff --git a/SerialPrograms/Source/Pokemon/Navigation/Pokemon_StorySteps_Tests.cpp b/SerialPrograms/Source/Pokemon/Navigation/Pokemon_StorySteps_Tests.cpp new file mode 100644 index 0000000000..948efe3911 --- /dev/null +++ b/SerialPrograms/Source/Pokemon/Navigation/Pokemon_StorySteps_Tests.cpp @@ -0,0 +1,369 @@ +/* Story Steps Tests + * + * From: https://github.com/PokemonAutomation/ + * + * Story tables built into checkpoints and run against a fake executor + * that writes down each step it is asked to do: the order of the events, + * skipped steps, the pose each step leaves, and how a failure is named. + * Nothing here belongs to one game. + * + */ + +#include +#include +#include +#include +#include +#include +#include "Common/Cpp/TestRunners/UnitTest.h" +#include "Pokemon_StoryEvents.h" +#include "Pokemon_StorySegments.h" +#include "Pokemon_StorySteps.h" +#include "Pokemon_TilePose.h" +#include "Pokemon_Navigation_Tests.h" + +namespace PokemonAutomation{ +namespace Pokemon{ + + +namespace{ + +// A world of two maps. Routes arrive on their target; a step moves a tile +// from the run's pose. Each step it does is written down as "KIND name", +// with the pose it started from when that is known. +class FakeExecutor : public StoryStepExecutor{ +public: + std::vector trace; + std::set conditions; + // Steps by name that fail, and how. + std::set failing; + // The pose each step started from, by name. + std::vector> poses_seen; + + virtual Outcome run(RunState& state, const StoryStep& step) override{ + poses_seen.emplace_back(step.name, to_string(state.pose)); + trace.push_back(std::string(story_step_kind_name(step.kind)) + " " + step.name); + if (failing.contains(step.name)){ + return outcome_failed("blocked", step.name + " was blocked"); + } + return StoryStepExecutor::run(state, step); + } + virtual bool holds(const std::string& condition, RunState&) override{ + return conditions.contains(condition); + } + virtual Outcome route(RunState&, const StoryStep& step) override{ + return outcome_ok(*step.target); + } + virtual Outcome step(RunState& state, const StoryStep& step) override{ + const std::vector tiles = tiles_of(state.pose); + if (tiles.size() != 1){ + return outcome_failed("no_pose", to_string(state.pose)); + } + return outcome_ok(tile_pose(state.pose.map, {tiles[0].next(step.direction)}, step.direction)); + } + virtual Outcome talk(RunState&, const StoryStep&) override{ + return outcome_ok(); + } + virtual Outcome mash(RunState&, const StoryStep&) override{ + return outcome_ok(); + } + virtual Outcome battle(RunState&, const StoryStep& step) override{ + // The first battle is lost; a step that may lose goes on. + return step.may_lose ? outcome_ok() : outcome_failed("blackout"); + } + virtual Outcome shop(RunState&, const StoryStep& step) override{ + for (const StoryItem& item : step.items){ + trace.push_back(" bought " + std::to_string(item.quantity) + " " + item.item); + } + return outcome_ok(); + } + virtual Outcome game(RunState&, const StoryStep& step) override{ + trace.push_back(" game " + step.variant); + return outcome_ok(); + } +}; + +StoryStep make(StoryStepKind kind, std::string name){ + StoryStep step; + step.kind = kind; + step.name = std::move(name); + return step; +} + +StoryStep route_to(std::string name, Pose target){ + StoryStep step = make(StoryStepKind::ROUTE, std::move(name)); + step.target = std::move(target); + return step; +} + +StoryStep step_into(std::string name, Direction direction){ + StoryStep step = make(StoryStepKind::STEP, std::move(name)); + step.direction = direction; + return step; +} + +StoryStep scene(std::string name, std::optional pose_after){ + StoryStep step = make(StoryStepKind::MASH, std::move(name)); + step.pose_after = std::move(pose_after); + return step; +} + +// A lab checkpoint: to the table, a trigger, the scene into the lab, a +// talk, a shop, a game step. +StoryCheckpoint lab_checkpoint(){ + StoryStep shop = make(StoryStepKind::SHOP, "potions"); + shop.items = {{.item = "potion", .quantity = 5}, {.item = "antidote", .quantity = 3}}; + StoryStep game = make(StoryStepKind::GAME, "dance"); + game.variant = "dance"; + return StoryCheckpoint{ + .id = "00.03", + .title = "to the lab", + .start = tile_pose("Town", {{6, 8}}, Direction::SOUTH), + .steps = { + route_to("below_trigger", tile_pose("Town", {{12, 2}}, Direction::NORTH)), + step_into("trigger", Direction::NORTH), + scene("to_the_lab", tile_pose("Lab", {{6, 4}}, Direction::NORTH)), + make(StoryStepKind::TALK, "talk_oak"), + shop, + game, + }, + }; +} + +struct Run{ + CheckpointReport report; + RunState state; + std::vector lines; +}; + +Run run(const StoryCheckpoint& data, StoryStepExecutor& executor){ + Run ret; + Checkpoint checkpoint = build_story_checkpoint(data, executor); + EventLogger log = [&ret](const std::string& line){ ret.lines.push_back(line); }; + ret.report = run_checkpoint(ret.state, checkpoint, log); + return ret; +} + +std::string joined(const std::vector& lines){ + std::string text; + for (const std::string& line : lines){ + text += "\n " + line; + } + return text; +} + + +UnitTestResult test_events_in_table_order(){ + const StoryCheckpoint data = lab_checkpoint(); + FakeExecutor executor; + const Run result = run(data, executor); + const std::vector expected{ + "ROUTE below_trigger", + "STEP trigger", + "MASH to_the_lab", + "TALK talk_oak", + "SHOP potions", + " bought 5 potion", + " bought 3 antidote", + "GAME dance", + " game dance", + }; + if (!result.report.completed || executor.trace != expected){ + return "Expected the steps in table order:" + joined(expected) + "\nbut ran:" + joined(executor.trace); + } + // "from_save" is the engine's own event: the executor is not asked. + const std::string first = event_log_line("00.03", 1, "from_save", "start"); + if (result.lines.empty() || std::find(result.lines.begin(), result.lines.end(), first) == result.lines.end()){ + return "Expected the from_save event first:" + joined(result.lines); + } + return true; +} + +UnitTestResult test_skip_if(){ + StoryCheckpoint data = lab_checkpoint(); + data.steps[0].skip_if = {"has_parcel"}; + data.steps[3].skip_if = {"has_parcel", "talked"}; + FakeExecutor executor; + executor.conditions = {"has_parcel"}; + // The route is skipped; the talk needs both conditions, so it runs. + const Run result = run(data, executor); + if (!result.report.completed || result.report.events_skipped != 1){ + return "Expected one step skipped, got " + std::to_string(result.report.events_skipped) + ":" + joined(result.lines); + } + if (std::find(executor.trace.begin(), executor.trace.end(), "ROUTE below_trigger") != executor.trace.end()){ + return "Expected the route skipped:" + joined(executor.trace); + } + if (std::find(executor.trace.begin(), executor.trace.end(), "TALK talk_oak") == executor.trace.end()){ + return "Expected the talk run, one of its conditions not holding:" + joined(executor.trace); + } + return true; +} + +UnitTestResult test_pose_propagation(){ + const StoryCheckpoint data = lab_checkpoint(); + FakeExecutor executor; + const Run result = run(data, executor); + // Each step starts where the one before left the player: the save, the + // route's target, a tile north of it, the scene's end, and the scene's + // end again after a talk that says nothing of where it leaves us. + const std::vector> expected{ + {"below_trigger", "Town (6, 8) facing south (tile)"}, + {"trigger", "Town (12, 2) facing north (tile)"}, + {"to_the_lab", "Town (12, 1) facing north (tile)"}, + {"talk_oak", "Lab (6, 4) facing north (tile)"}, + {"potions", "Lab (6, 4) facing north (tile)"}, + {"dance", "Lab (6, 4) facing north (tile)"}, + }; + if (!result.report.completed || executor.poses_seen != expected){ + std::string text; + for (const auto& item : executor.poses_seen){ + text += "\n " + item.first + ": " + item.second; + } + return "Unexpected poses at the steps' starts:" + text; + } + if (to_string(result.state.pose) != "Lab (6, 4) facing north (tile)"){ + return "Expected the run to end at the scene's end, got " + to_string(result.state.pose); + } + return true; +} + +UnitTestResult test_failure_names_the_step(){ + const StoryCheckpoint data = lab_checkpoint(); + FakeExecutor executor; + executor.failing = {"trigger"}; + const Run result = run(data, executor); + // Event 3: from_save is event 1. + if (result.report.completed || result.report.failed_event != 3 || result.report.failed_name != "trigger" + || result.report.failure.failure != "blocked" + ){ + return "Expected a failure at event 3 trigger, blocked:" + joined(result.lines); + } + if (executor.trace.size() != 2){ + return "Expected nothing run after the failed step:" + joined(executor.trace); + } + return true; +} + +UnitTestResult test_unsupported_and_lost_battles(){ + // The fake has no TRAIN, and loses battles a step may not lose. + StoryStep train = make(StoryStepKind::TRAIN, "train"); + train.battles = 3; + FakeExecutor executor; + Run result = run(StoryCheckpoint{.id = "01", .title = "", .start = std::nullopt, .steps = {train}}, executor); + if (result.report.completed || result.report.failure.failure != "unsupported_step" || result.report.failure.detail != "TRAIN train"){ + return "Expected TRAIN unsupported:" + joined(result.lines); + } + StoryStep rival = make(StoryStepKind::BATTLE, "rival"); + rival.may_lose = true; + StoryStep brock = make(StoryStepKind::BATTLE, "brock"); + result = run(StoryCheckpoint{.id = "02", .title = "", .start = std::nullopt, .steps = {rival, brock}}, executor); + if (result.report.completed || result.report.failed_name != "brock" || result.report.failure.failure != "blackout"){ + return "Expected the rival's battle passed and Brock's lost:" + joined(result.lines); + } + return true; +} + +UnitTestResult test_segment_of_tables(){ + // Two rows built into a segment, run with saves and a reload from the + // game's hooks: the second row's first attempt fails, its retry starts + // over from its start pose. + const std::vector tables{ + lab_checkpoint(), + StoryCheckpoint{ + .id = "00.04", + .title = "the parcel", + .start = tile_pose("Lab", {{6, 4}}, Direction::NORTH), + .steps = {make(StoryStepKind::TALK, "give_parcel")}, + }, + }; + FakeExecutor executor; + Segment segment; + segment.id = "00"; + for (const StoryCheckpoint& data : tables){ + segment.checkpoints.push_back(CheckpointSpec{ + .id = data.id, .title = data.title, .saves = true, + .build = [&data, &executor]{ return build_story_checkpoint(data, executor); }, + }); + } + std::vector lines; + SegmentHooks hooks; + hooks.save = [&executor](RunState&){ + executor.trace.push_back("save"); + return outcome_ok(); + }; + // Whatever blocked the talk has gone by the reload. + hooks.reload = [&executor](RunState&){ + executor.trace.push_back("reload"); + executor.failing.clear(); + return outcome_ok(); + }; + hooks.log = [&lines](const std::string& line){ lines.push_back(line); }; + executor.failing = {"give_parcel"}; + RunState state; + const SegmentReport report = run_segment(state, segment, SegmentRange{}, SegmentPolicy{}, hooks); + const std::vector tail{"save", "TALK give_parcel", "reload", "TALK give_parcel", "save"}; + const bool tail_matches = executor.trace.size() >= tail.size() + && std::equal(tail.begin(), tail.end(), executor.trace.end() - (std::ptrdiff_t)tail.size()); + if (!report.completed || report.reloads != 1 || !tail_matches){ + return "Expected 00.04 reloaded once and passed:" + joined(executor.trace) + joined(lines); + } + return true; +} + +UnitTestResult test_lint(){ + StoryStep no_target = make(StoryStepKind::ROUTE, "walk"); + StoryStep again = make(StoryStepKind::TALK, "walk"); + StoryStep bad_legs = make(StoryStepKind::LEGS, "legs"); + bad_legs.legs = {{.direction = Direction::NORTH, .tiles = 0}}; + StoryStep no_variant = make(StoryStepKind::GAME, ""); + const StoryCheckpoint data{.id = "", .title = "", .start = std::nullopt, .steps = {no_target, again, bad_legs, no_variant}}; + const std::vector expected{ + "a checkpoint has no id", + " step 1 walk: ROUTE no target", + " step 2: a second step named walk", + " step 3 legs: LEGS a leg of no tiles", + " step 4: no name", + " step 4 : GAME no variant", + }; + const std::vector problems = lint_story_checkpoint(data); + if (problems != expected){ + return "Unexpected lint:" + joined(problems); + } + if (!lint_story_checkpoint(lab_checkpoint()).empty()){ + return "Expected the lab checkpoint to lint clean:" + joined(lint_story_checkpoint(lab_checkpoint())); + } + return true; +} + + +class Test_StorySteps : public UnitTest{ +public: + Test_StorySteps(std::string name, std::function body) + : UnitTest("Pokemon::StorySteps - " + std::move(name)) + , m_body(std::move(body)) + {} + virtual UnitTestResult run(Logger&, CancellableScope&) const override{ + return m_body(); + } + +private: + std::function m_body; +}; + +} + + +void add_tests_StorySteps(UnitTestDatabase& database){ + database.add("steps run in table order", test_events_in_table_order); + database.add("skip_if asks the executor", test_skip_if); + database.add("each step starts where the last left the player", test_pose_propagation); + database.add("a failure names its step", test_failure_names_the_step); + database.add("unsupported kinds and lost battles", test_unsupported_and_lost_battles); + database.add("tables as a segment, with a reload", test_segment_of_tables); + database.add("lint", test_lint); +} + + + +} +} diff --git a/SerialPrograms/cmake/SourceFiles.cmake b/SerialPrograms/cmake/SourceFiles.cmake index 05657bdfcc..6374b239a2 100644 --- a/SerialPrograms/cmake/SourceFiles.cmake +++ b/SerialPrograms/cmake/SourceFiles.cmake @@ -1456,6 +1456,9 @@ file(GLOB LIBRARY_SOURCES Source/Pokemon/Navigation/Pokemon_StorySegments.cpp Source/Pokemon/Navigation/Pokemon_StorySegments.h Source/Pokemon/Navigation/Pokemon_StorySegments_Tests.cpp + Source/Pokemon/Navigation/Pokemon_StorySteps.cpp + Source/Pokemon/Navigation/Pokemon_StorySteps.h + Source/Pokemon/Navigation/Pokemon_StorySteps_Tests.cpp Source/Pokemon/Navigation/Pokemon_TilePose.cpp Source/Pokemon/Navigation/Pokemon_TilePose.h Source/Pokemon/Options/Pokemon_BoxSortingTable.cpp From 474c2a013fe83abc1fc8146f721bcfbac7ae15b1 Mon Sep 17 00:00:00 2001 From: dayfine Date: Sun, 1 Nov 2026 10:01:14 -0800 Subject: [PATCH 002/102] Pokemon navigation: one retry policy for every story segment 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 Claude-Session: https://claude.ai/code/session_01AKYzhrMnPK61XHWEch4a6E --- .../Navigation/Pokemon_StorySegments.cpp | 69 +++++++- .../Navigation/Pokemon_StorySegments.h | 37 ++++- .../Pokemon/Navigation/Pokemon_StorySteps.cpp | 4 + .../Pokemon/Navigation/Pokemon_StorySteps.h | 8 +- .../Navigation/Pokemon_StorySteps_Tests.cpp | 147 +++++++++++++++++- .../Options/Pokemon_StoryRunOptions.cpp | 40 +++++ .../Pokemon/Options/Pokemon_StoryRunOptions.h | 41 +++++ SerialPrograms/cmake/SourceFiles.cmake | 2 + 8 files changed, 336 insertions(+), 12 deletions(-) create mode 100644 SerialPrograms/Source/Pokemon/Options/Pokemon_StoryRunOptions.cpp create mode 100644 SerialPrograms/Source/Pokemon/Options/Pokemon_StoryRunOptions.h diff --git a/SerialPrograms/Source/Pokemon/Navigation/Pokemon_StorySegments.cpp b/SerialPrograms/Source/Pokemon/Navigation/Pokemon_StorySegments.cpp index e80ff4915f..ad072e3411 100644 --- a/SerialPrograms/Source/Pokemon/Navigation/Pokemon_StorySegments.cpp +++ b/SerialPrograms/Source/Pokemon/Navigation/Pokemon_StorySegments.cpp @@ -83,21 +83,67 @@ Outcome reload(RunState& state, SegmentHooks& hooks){ return outcome_ok(); } +// The policy's in-place recovery, after each event's own: the game's +// recover hook, if any, then the event again. Counts into `used`. +void add_policy_recoveries(Checkpoint& checkpoint, const SegmentPolicy& policy, SegmentHooks& hooks, size_t& used){ + if (policy.recoveries_per_event == 0){ + return; + } + for (Event& event : checkpoint.events){ + Recovery recovery; + recovery.kind = RecoveryKind::REANCHOR; + recovery.attempts = policy.recoveries_per_event; + recovery.why = "the segment's policy: recover in place before reloading"; + recovery.prepare = [&hooks, &used, name = event.name](RunState& state){ + used++; + return hooks.recover ? hooks.recover(state, name) : outcome_ok(); + }; + event.recoveries.push_back(std::move(recovery)); + } +} + +std::string resets_text(size_t attempts){ + if (attempts == 1){ + return "one-shot"; + } + return std::format("{} reset{}", attempts - 1, attempts == 2 ? "" : "s"); +} + // One row to success, reloading and rebuilding after each failed attempt. -// Returns the last attempt's report, or the reload's failure. +// Returns the last attempt's report, or the reload's failure; `run` says +// how many attempts and recoveries it took. CheckpointReport run_row( RunState& state, const Segment& segment, CheckpointSpec& spec, - const SegmentPolicy& policy, SegmentHooks& hooks, SegmentReport& report + const SegmentPolicy& policy, SegmentHooks& hooks, SegmentReport& report, CheckpointRun& run ){ for (size_t attempt = 1; ; attempt++){ + run.attempts = attempt; Checkpoint checkpoint = spec.build(); if (spec.saves && !checkpoint.save){ checkpoint.save = [&hooks](RunState& state){ return hooks.save ? hooks.save(state) : outcome_failed("no_save_hook"); }; } + add_policy_recoveries(checkpoint, policy, hooks, run.recoveries); CheckpointReport result = run_checkpoint(state, checkpoint, hooks.log); - if (result.completed || attempt >= policy.attempts_per_checkpoint){ + if (result.completed){ + run.passed = true; + hooks.log(std::format( + "[Checkpoint] {}: passed on attempt {} ({}){}", + spec.id, attempt, resets_text(attempt), + run.recoveries == 0 ? "" : std::format(", {} in place", run.recoveries) + )); + return result; + } + if (policy.stop_at_first_failure){ + hooks.log(std::format( + "[Segment] {}: {} failed; stopping at the first failure, the game stays where it failed", + segment.id, spec.id + )); + report.stopped_at_first_failure = true; + return result; + } + if (attempt >= policy.attempts_per_checkpoint){ return result; } hooks.log(std::format( @@ -128,6 +174,19 @@ SegmentReport stop_segment(SegmentReport& report, SegmentHooks& hooks, const std } +bool CheckpointRun::one_shot() const{ + return passed && attempts == 1 && recoveries == 0; +} + +size_t SegmentReport::one_shot_passes() const{ + size_t count = 0; + for (const CheckpointRun& run : runs){ + count += run.one_shot() ? 1 : 0; + } + return count; +} + + SegmentReport run_segment( RunState& state, Segment& segment, const SegmentRange& range, const SegmentPolicy& policy, SegmentHooks& hooks @@ -141,7 +200,8 @@ SegmentReport run_segment( for (size_t c = selected.first; c <= selected.last; c++){ CheckpointSpec& spec = segment.checkpoints[c]; report.checkpoints_run++; - CheckpointReport result = run_row(state, segment, spec, policy, hooks, report); + report.runs.push_back(CheckpointRun{.id = spec.id}); + CheckpointReport result = run_row(state, segment, spec, policy, hooks, report, report.runs.back()); if (!result.completed){ report.failed_checkpoint = spec.id; report.failed_event = result.failed_name; @@ -149,6 +209,7 @@ SegmentReport run_segment( } } report.completed = true; + hooks.log(std::format("[Segment] {}: {} of {} checkpoints one-shot", segment.id, report.one_shot_passes(), report.checkpoints_run)); hooks.log(std::format("[Segment] {}: done, {} checkpoints", segment.id, report.checkpoints_run)); return report; } diff --git a/SerialPrograms/Source/Pokemon/Navigation/Pokemon_StorySegments.h b/SerialPrograms/Source/Pokemon/Navigation/Pokemon_StorySegments.h index 69e181ef57..5e6bf66e55 100644 --- a/SerialPrograms/Source/Pokemon/Navigation/Pokemon_StorySegments.h +++ b/SerialPrograms/Source/Pokemon/Navigation/Pokemon_StorySegments.h @@ -46,15 +46,28 @@ struct Segment{ // What the game lends the runner: how to save, how to reload the last save // (the run state is emptied first; the reload's Outcome says where the // player stands), and where to log. +// `recover`, if set, is the game's way of recovering in place from a failed +// event (re-anchor on a landmark, close a stray dialogue) before the event +// is tried again; see SegmentPolicy::recoveries_per_event. struct SegmentHooks{ Act save; Act reload; EventLogger log; + MoveOnlyFunction recover; }; +// How hard a segment tries, for every game: the one place retries are set. struct SegmentPolicy{ - // Runs of one checkpoint, reloading between them, before the segment stops. + // Runs of one checkpoint, reloading its save between them, before the + // segment stops. size_t attempts_per_checkpoint = 3; + // Lab: stop at the first failed attempt without reloading, leaving the + // game where it failed for a look. + bool stop_at_first_failure = false; + // Times each event may recover in place (SegmentHooks::recover, then + // the event again) once its own recoveries are used up, before its + // checkpoint fails and is reloaded. 0 keeps a failure a reload. + size_t recoveries_per_event = 0; }; // The checkpoints to run, by id, both inclusive. An unset end is the @@ -65,8 +78,22 @@ struct SegmentRange{ }; +// How one checkpoint went: one attempt with no in-place recovery is a +// one-shot pass. +struct CheckpointRun{ + std::string id; + bool passed = false; + size_t attempts = 0; + // In-place recoveries (SegmentPolicy::recoveries_per_event) used, in all attempts. + size_t recoveries = 0; + + bool one_shot() const; +}; + struct SegmentReport{ bool completed = false; + // The run stopped at its first failure (SegmentPolicy::stop_at_first_failure). + bool stopped_at_first_failure = false; // Both empty when nothing failed; the event is empty when a start // check, an end check, a save or a reload failed. std::string failed_checkpoint; @@ -75,13 +102,21 @@ struct SegmentReport{ size_t checkpoints_run = 0; // Reloads after failed attempts. size_t reloads = 0; + // Each checkpoint run, in order, the failed one last. + std::vector runs; + + size_t one_shot_passes() const; }; // Runs the checkpoints in `range`, in order. Logs through `hooks.log`, // around the checkpoint lines: // [Segment] 00: start, 3 checkpoints // [Segment] 00: 00.02 failed, reloading for attempt 2/3 +// [Checkpoint] 00.02: passed on attempt 2 (1 reset) +// [Checkpoint] 00.03: passed on attempt 1 (one-shot) +// [Segment] 00: 2 of 3 checkpoints one-shot // [Segment] 00: done, 3 checkpoints +// [Segment] 00: 00.02 failed; stopping at the first failure, the game stays where it failed // [Segment] 00: failed at 00.02 talk_mom: expect_failed: dialogue opened SegmentReport run_segment( RunState& state, Segment& segment, const SegmentRange& range, diff --git a/SerialPrograms/Source/Pokemon/Navigation/Pokemon_StorySteps.cpp b/SerialPrograms/Source/Pokemon/Navigation/Pokemon_StorySteps.cpp index 406e45e36f..b0ecdd4514 100644 --- a/SerialPrograms/Source/Pokemon/Navigation/Pokemon_StorySteps.cpp +++ b/SerialPrograms/Source/Pokemon/Navigation/Pokemon_StorySteps.cpp @@ -59,6 +59,10 @@ Outcome StoryStepExecutor::run(RunState& state, const StoryStep& step){ return dispatch_story_step(*this, state, step); } +bool StoryStepExecutor::holds(const std::string& condition, RunState& state){ + return state.flags.contains(condition); +} + Outcome StoryStepExecutor::new_game(RunState&, const StoryStep& step){ return unsupported_step(step); } diff --git a/SerialPrograms/Source/Pokemon/Navigation/Pokemon_StorySteps.h b/SerialPrograms/Source/Pokemon/Navigation/Pokemon_StorySteps.h index 6e74929c8e..41fe51fb77 100644 --- a/SerialPrograms/Source/Pokemon/Navigation/Pokemon_StorySteps.h +++ b/SerialPrograms/Source/Pokemon/Navigation/Pokemon_StorySteps.h @@ -96,7 +96,8 @@ struct StoryStep{ std::string variant; // Skipped when all of these hold (and there is at least one): names - // the game's executor answers (StoryStepExecutor::holds()). + // the game's executor answers (StoryStepExecutor::holds()), run flags + // unless the game reads them off the screen. std::vector skip_if; // Where the step leaves the player, when its action does not say: the // end of a scene that moves the player. @@ -123,8 +124,9 @@ class StoryStepExecutor{ // Outcome. virtual Outcome run(RunState& state, const StoryStep& step); - // Whether the condition named in a step's skip_if holds. - virtual bool holds(const std::string& condition, RunState& state) = 0; + // 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(const std::string& condition, RunState& state); virtual Outcome new_game(RunState& state, const StoryStep& step); virtual Outcome options(RunState& state, const StoryStep& step); diff --git a/SerialPrograms/Source/Pokemon/Navigation/Pokemon_StorySteps_Tests.cpp b/SerialPrograms/Source/Pokemon/Navigation/Pokemon_StorySteps_Tests.cpp index 948efe3911..fe0cc60623 100644 --- a/SerialPrograms/Source/Pokemon/Navigation/Pokemon_StorySteps_Tests.cpp +++ b/SerialPrograms/Source/Pokemon/Navigation/Pokemon_StorySteps_Tests.cpp @@ -11,6 +11,7 @@ #include #include +#include #include #include #include @@ -35,8 +36,10 @@ class FakeExecutor : public StoryStepExecutor{ public: std::vector trace; std::set conditions; - // Steps by name that fail, and how. + // Steps by name that always fail, and how. std::set failing; + // Steps by name that fail this many more times, then pass. + std::map failures_left; // The pose each step started from, by name. std::vector> poses_seen; @@ -46,10 +49,15 @@ class FakeExecutor : public StoryStepExecutor{ if (failing.contains(step.name)){ return outcome_failed("blocked", step.name + " was blocked"); } + size_t& left = failures_left[step.name]; + if (left > 0){ + left--; + return outcome_failed("blocked", step.name + " was blocked"); + } return StoryStepExecutor::run(state, step); } - virtual bool holds(const std::string& condition, RunState&) override{ - return conditions.contains(condition); + virtual bool holds(const std::string& condition, RunState& state) override{ + return conditions.contains(condition) || StoryStepExecutor::holds(condition, state); } virtual Outcome route(RunState&, const StoryStep& step) override{ return outcome_ok(*step.target); @@ -77,8 +85,10 @@ class FakeExecutor : public StoryStepExecutor{ } return outcome_ok(); } - virtual Outcome game(RunState&, const StoryStep& step) override{ + // A game step sets a run flag named for its variant. + virtual Outcome game(RunState& state, const StoryStep& step) override{ trace.push_back(" game " + step.variant); + state.flags.insert(step.variant); return outcome_ok(); } }; @@ -196,6 +206,18 @@ UnitTestResult test_skip_if(){ if (std::find(executor.trace.begin(), executor.trace.end(), "TALK talk_oak") == executor.trace.end()){ return "Expected the talk run, one of its conditions not holding:" + joined(executor.trace); } + + // By default a condition is a run flag: the game step "dance" sets + // one, and a talk after it that needs it is skipped. + StoryStep after = make(StoryStepKind::TALK, "talk_after_dance"); + after.skip_if = {"dance"}; + data = lab_checkpoint(); + data.steps.push_back(after); + FakeExecutor plain; + const Run flagged = run(data, plain); + if (!flagged.report.completed || flagged.report.events_skipped != 1 || plain.trace.back() != " game dance"){ + return "Expected the talk after the dance skipped on its flag:" + joined(plain.trace); + } return true; } @@ -307,6 +329,120 @@ UnitTestResult test_segment_of_tables(){ if (!report.completed || report.reloads != 1 || !tail_matches){ return "Expected 00.04 reloaded once and passed:" + joined(executor.trace) + joined(lines); } + // The report and the log tell a one-shot pass from a retried one. + const bool runs_ok = report.runs.size() == 2 + && report.runs[0].one_shot() && report.runs[0].attempts == 1 + && !report.runs[1].one_shot() && report.runs[1].attempts == 2 && report.runs[1].passed + && report.one_shot_passes() == 1; + const auto has = [&lines](const std::string& line){ + return std::find(lines.begin(), lines.end(), line) != lines.end(); + }; + if (!runs_ok + || !has("[Checkpoint] 00.03: passed on attempt 1 (one-shot)") + || !has("[Checkpoint] 00.04: passed on attempt 2 (1 reset)") + || !has("[Segment] 00: 1 of 2 checkpoints one-shot") + ){ + return "Expected 00.03 one-shot and 00.04 passed on attempt 2:" + joined(lines); + } + return true; +} + + +// The two tables of test_segment_of_tables() as a segment run by `executor`, +// with hooks that write saves, reloads and recoveries into its trace. +struct PolicyLab{ + std::vector tables{ + lab_checkpoint(), + StoryCheckpoint{ + .id = "00.04", + .title = "the parcel", + .start = tile_pose("Lab", {{6, 4}}, Direction::NORTH), + .steps = {make(StoryStepKind::TALK, "give_parcel")}, + }, + }; + FakeExecutor executor; + std::vector lines; + + SegmentReport run(const SegmentPolicy& policy){ + Segment segment; + segment.id = "00"; + for (const StoryCheckpoint& data : tables){ + segment.checkpoints.push_back(CheckpointSpec{ + .id = data.id, .title = data.title, .saves = true, + .build = [&data, this]{ return build_story_checkpoint(data, executor); }, + }); + } + SegmentHooks hooks; + hooks.save = [this](RunState&){ + executor.trace.push_back("save"); + return outcome_ok(); + }; + hooks.reload = [this](RunState&){ + executor.trace.push_back("reload"); + return outcome_ok(); + }; + hooks.recover = [this](RunState&, const std::string& event){ + executor.trace.push_back("recover " + event); + return outcome_ok(); + }; + hooks.log = [this](const std::string& line){ lines.push_back(line); }; + RunState state; + return run_segment(state, segment, SegmentRange{}, policy, hooks); + } + bool has(const std::string& line) const{ + return std::find(lines.begin(), lines.end(), line) != lines.end(); + } + size_t count(const std::string& item) const{ + return (size_t)std::count(executor.trace.begin(), executor.trace.end(), item); + } +}; + +UnitTestResult test_policy_attempts_then_fail(){ + // Three attempts by default, then the segment stops on the last one's failure. + PolicyLab lab; + lab.executor.failing = {"give_parcel"}; + const SegmentReport report = lab.run(SegmentPolicy{}); + if (report.completed || report.reloads != 2 || lab.count("TALK give_parcel") != 3 + || report.runs.size() != 2 || report.runs[1].passed || report.runs[1].attempts != 3 + || report.failed_checkpoint != "00.04" || report.failure.failure != "blocked" + ){ + return "Expected 00.04 tried 3 times, then failed:" + joined(lab.executor.trace) + joined(lab.lines); + } + return true; +} + +UnitTestResult test_policy_stop_at_first_failure(){ + PolicyLab lab; + lab.executor.failing = {"give_parcel"}; + const SegmentReport report = lab.run(SegmentPolicy{.stop_at_first_failure = true}); + if (report.completed || !report.stopped_at_first_failure || report.reloads != 0 || lab.count("reload") != 0 + || lab.count("TALK give_parcel") != 1 + || !lab.has("[Segment] 00: 00.04 failed; stopping at the first failure, the game stays where it failed") + ){ + return "Expected a stop at the first failure, with no reload:" + joined(lab.executor.trace) + joined(lab.lines); + } + return true; +} + +UnitTestResult test_policy_recovers_in_place(){ + // The talk fails twice; two recoveries in place get it through + // without a reload, but not one-shot. + PolicyLab lab; + lab.executor.failures_left = {{"give_parcel", 2}}; + const SegmentReport report = lab.run(SegmentPolicy{.recoveries_per_event = 2}); + if (!report.completed || report.reloads != 0 || lab.count("recover give_parcel") != 2 + || report.runs.size() != 2 || report.runs[1].recoveries != 2 || report.runs[1].one_shot() + || !lab.has("[Checkpoint] 00.04: passed on attempt 1 (one-shot), 2 in place") + ){ + return "Expected 00.04 recovered in place twice:" + joined(lab.executor.trace) + joined(lab.lines); + } + // Past the budget, the checkpoint is reloaded as before. + PolicyLab reloaded; + reloaded.executor.failures_left = {{"give_parcel", 2}}; + const SegmentReport second = reloaded.run(SegmentPolicy{.recoveries_per_event = 1}); + if (!second.completed || second.reloads != 1 || second.runs[1].attempts != 2){ + return "Expected a reload once the in-place budget was used:" + joined(reloaded.executor.trace) + joined(reloaded.lines); + } return true; } @@ -361,6 +497,9 @@ void add_tests_StorySteps(UnitTestDatabase& database){ database.add("unsupported kinds and lost battles", test_unsupported_and_lost_battles); database.add("tables as a segment, with a reload", test_segment_of_tables); database.add("lint", test_lint); + database.add("policy: attempts per checkpoint, then fail", test_policy_attempts_then_fail); + database.add("policy: stop at the first failure", test_policy_stop_at_first_failure); + database.add("policy: recover in place before reloading", test_policy_recovers_in_place); } diff --git a/SerialPrograms/Source/Pokemon/Options/Pokemon_StoryRunOptions.cpp b/SerialPrograms/Source/Pokemon/Options/Pokemon_StoryRunOptions.cpp new file mode 100644 index 0000000000..ceccb40638 --- /dev/null +++ b/SerialPrograms/Source/Pokemon/Options/Pokemon_StoryRunOptions.cpp @@ -0,0 +1,40 @@ +/* Story Run Options + * + * From: https://github.com/PokemonAutomation/ + * + */ + +#include "Pokemon_StoryRunOptions.h" + +namespace PokemonAutomation{ +namespace Pokemon{ + + +StoryRunOptions::StoryRunOptions() + : GroupOption("Checkpoint Retries", LockMode::LOCK_WHILE_RUNNING) + , ATTEMPTS_PER_CHECKPOINT( + "Attempts per checkpoint:
A failed checkpoint reloads its save and runs again, up to this many times in all.", + LockMode::LOCK_WHILE_RUNNING, + 3, 1, 20 + ) + , STOP_AT_FIRST_FAILURE( + "Stop at the first failure:
Stop without reloading, leaving the game where it failed for a look.", + LockMode::LOCK_WHILE_RUNNING, + false + ) +{ + PA_ADD_OPTION(ATTEMPTS_PER_CHECKPOINT); + PA_ADD_OPTION(STOP_AT_FIRST_FAILURE); +} + +SegmentPolicy StoryRunOptions::policy() const{ + SegmentPolicy policy; + policy.attempts_per_checkpoint = ATTEMPTS_PER_CHECKPOINT; + policy.stop_at_first_failure = STOP_AT_FIRST_FAILURE; + return policy; +} + + + +} +} diff --git a/SerialPrograms/Source/Pokemon/Options/Pokemon_StoryRunOptions.h b/SerialPrograms/Source/Pokemon/Options/Pokemon_StoryRunOptions.h new file mode 100644 index 0000000000..652ddd44ab --- /dev/null +++ b/SerialPrograms/Source/Pokemon/Options/Pokemon_StoryRunOptions.h @@ -0,0 +1,41 @@ +/* Story Run Options + * + * From: https://github.com/PokemonAutomation/ + * + * The options every AutoStory program shows for how hard to try: the + * same group in each game, read into the shared SegmentPolicy + * (Pokemon/Navigation/Pokemon_StorySegments.h). + * + */ + +#ifndef PokemonAutomation_Pokemon_StoryRunOptions_H +#define PokemonAutomation_Pokemon_StoryRunOptions_H + +#include +#include "Common/Cpp/Options/BooleanCheckBoxOption.h" +#include "Common/Cpp/Options/GroupOption.h" +#include "Common/Cpp/Options/SimpleIntegerOption.h" +#include "Pokemon/Navigation/Pokemon_StorySegments.h" + +namespace PokemonAutomation{ +namespace Pokemon{ + + +class StoryRunOptions : public GroupOption{ +public: + StoryRunOptions(); + + // The policy these options set. In-place recoveries are the game's to + // set, not the user's. + SegmentPolicy policy() const; + +public: + SimpleIntegerOption ATTEMPTS_PER_CHECKPOINT; + BooleanCheckBoxOption STOP_AT_FIRST_FAILURE; +}; + + + +} +} +#endif diff --git a/SerialPrograms/cmake/SourceFiles.cmake b/SerialPrograms/cmake/SourceFiles.cmake index 6374b239a2..ecf66e1e16 100644 --- a/SerialPrograms/cmake/SourceFiles.cmake +++ b/SerialPrograms/cmake/SourceFiles.cmake @@ -1474,6 +1474,8 @@ file(GLOB LIBRARY_SOURCES Source/Pokemon/Options/Pokemon_NameSelectWidget.h Source/Pokemon/Options/Pokemon_StatsHuntFilter.cpp Source/Pokemon/Options/Pokemon_StatsHuntFilter.h + Source/Pokemon/Options/Pokemon_StoryRunOptions.cpp + Source/Pokemon/Options/Pokemon_StoryRunOptions.h Source/Pokemon/Pokemon_AdvRng.cpp Source/Pokemon/Pokemon_AdvRng.h Source/Pokemon/Pokemon_BdspRng.cpp From f1408301ae52e39668f1a22c05a4bc21bf8fb29e Mon Sep 17 00:00:00 2001 From: dayfine Date: Sun, 1 Nov 2026 10:09:39 -0800 Subject: [PATCH 003/102] Pokemon navigation: story executors hear of each attempt (begin_attempt) 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 Claude-Session: https://claude.ai/code/session_01AKYzhrMnPK61XHWEch4a6E --- .../Source/Pokemon/Navigation/Pokemon_StorySteps.cpp | 3 +++ .../Source/Pokemon/Navigation/Pokemon_StorySteps.h | 5 +++++ .../Pokemon/Navigation/Pokemon_StorySteps_Tests.cpp | 10 ++++++++++ 3 files changed, 18 insertions(+) diff --git a/SerialPrograms/Source/Pokemon/Navigation/Pokemon_StorySteps.cpp b/SerialPrograms/Source/Pokemon/Navigation/Pokemon_StorySteps.cpp index b0ecdd4514..75422b02cc 100644 --- a/SerialPrograms/Source/Pokemon/Navigation/Pokemon_StorySteps.cpp +++ b/SerialPrograms/Source/Pokemon/Navigation/Pokemon_StorySteps.cpp @@ -59,6 +59,8 @@ Outcome StoryStepExecutor::run(RunState& state, const StoryStep& step){ return dispatch_story_step(*this, state, step); } +void StoryStepExecutor::begin_attempt(const StoryCheckpoint&){} + bool StoryStepExecutor::holds(const std::string& condition, RunState& state){ return state.flags.contains(condition); } @@ -178,6 +180,7 @@ Event from_save_event(const Pose& start){ } Checkpoint build_story_checkpoint(const StoryCheckpoint& data, StoryStepExecutor& executor){ + executor.begin_attempt(data); Checkpoint checkpoint; checkpoint.id = data.id; if (data.start){ diff --git a/SerialPrograms/Source/Pokemon/Navigation/Pokemon_StorySteps.h b/SerialPrograms/Source/Pokemon/Navigation/Pokemon_StorySteps.h index 41fe51fb77..0c877739ad 100644 --- a/SerialPrograms/Source/Pokemon/Navigation/Pokemon_StorySteps.h +++ b/SerialPrograms/Source/Pokemon/Navigation/Pokemon_StorySteps.h @@ -119,6 +119,11 @@ class StoryStepExecutor{ public: virtual ~StoryStepExecutor() = default; + // A checkpoint is being built for a new attempt: build_story_checkpoint() + // calls this first, so a game can start the attempt afresh (trainers + // who can see us again, the row's own settings). Does nothing by default. + virtual void begin_attempt(const StoryCheckpoint& data); + // Runs `step`: dispatch_story_step() by default. A game overrides it // to wrap every step, e.g. to turn a failed console step into a failed // Outcome. diff --git a/SerialPrograms/Source/Pokemon/Navigation/Pokemon_StorySteps_Tests.cpp b/SerialPrograms/Source/Pokemon/Navigation/Pokemon_StorySteps_Tests.cpp index fe0cc60623..bb73f89676 100644 --- a/SerialPrograms/Source/Pokemon/Navigation/Pokemon_StorySteps_Tests.cpp +++ b/SerialPrograms/Source/Pokemon/Navigation/Pokemon_StorySteps_Tests.cpp @@ -42,6 +42,12 @@ class FakeExecutor : public StoryStepExecutor{ std::map failures_left; // The pose each step started from, by name. std::vector> poses_seen; + // The checkpoints begun, one per attempt. + std::vector attempts; + + virtual void begin_attempt(const StoryCheckpoint& data) override{ + attempts.push_back(data.id); + } virtual Outcome run(RunState& state, const StoryStep& step) override{ poses_seen.emplace_back(step.name, to_string(state.pose)); @@ -329,6 +335,10 @@ UnitTestResult test_segment_of_tables(){ if (!report.completed || report.reloads != 1 || !tail_matches){ return "Expected 00.04 reloaded once and passed:" + joined(executor.trace) + joined(lines); } + // Each attempt is begun anew: 00.03 once, 00.04 twice. + if (executor.attempts != std::vector{"00.03", "00.04", "00.04"}){ + return "Expected the executor told of each attempt:" + joined(executor.attempts); + } // The report and the log tell a one-shot pass from a retried one. const bool runs_ok = report.runs.size() == 2 && report.runs[0].one_shot() && report.runs[0].attempts == 1 From 03298de07a55ff9b6e14c433de99c0649bd229b6 Mon Sep 17 00:00:00 2001 From: dayfine Date: Sun, 1 Nov 2026 10:32:43 -0800 Subject: [PATCH 004/102] Pokemon navigation: a shared checks level for story steps (Thorough or 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 Claude-Session: https://claude.ai/code/session_01AKYzhrMnPK61XHWEch4a6E --- .../Pokemon/Navigation/Pokemon_StorySteps.cpp | 11 +++++ .../Pokemon/Navigation/Pokemon_StorySteps.h | 22 ++++++++++ .../Navigation/Pokemon_StorySteps_Tests.cpp | 40 +++++++++++++++++++ .../Options/Pokemon_StoryRunOptions.cpp | 19 +++++++++ .../Pokemon/Options/Pokemon_StoryRunOptions.h | 12 ++++-- 5 files changed, 101 insertions(+), 3 deletions(-) diff --git a/SerialPrograms/Source/Pokemon/Navigation/Pokemon_StorySteps.cpp b/SerialPrograms/Source/Pokemon/Navigation/Pokemon_StorySteps.cpp index 75422b02cc..c9825391b0 100644 --- a/SerialPrograms/Source/Pokemon/Navigation/Pokemon_StorySteps.cpp +++ b/SerialPrograms/Source/Pokemon/Navigation/Pokemon_StorySteps.cpp @@ -51,6 +51,17 @@ const char* story_step_kind_name(StoryStepKind kind){ } +const char* story_checks_name(StoryChecks checks){ + switch (checks){ + case StoryChecks::THOROUGH: + return "thorough"; + case StoryChecks::FAST: + return "fast"; + } + return "?"; +} + + Outcome unsupported_step(const StoryStep& step){ return outcome_failed("unsupported_step", std::format("{} {}", story_step_kind_name(step.kind), step.name)); } diff --git a/SerialPrograms/Source/Pokemon/Navigation/Pokemon_StorySteps.h b/SerialPrograms/Source/Pokemon/Navigation/Pokemon_StorySteps.h index 0c877739ad..99b9b74583 100644 --- a/SerialPrograms/Source/Pokemon/Navigation/Pokemon_StorySteps.h +++ b/SerialPrograms/Source/Pokemon/Navigation/Pokemon_StorySteps.h @@ -55,6 +55,16 @@ enum class StoryStepKind{ }; const char* story_step_kind_name(StoryStepKind kind); +// How much a step reads the screen to confirm what it did. Each game +// decides what its steps check at each level. +enum class StoryChecks{ + // Confirm on screen: purchases, the Bag, status after battles, position. + THOROUGH, + // In a rush: trust counts and timings. + FAST, +}; +const char* story_checks_name(StoryChecks checks); + // A straight leg of a fixed walk. struct StoryLeg{ @@ -124,6 +134,15 @@ class StoryStepExecutor{ // who can see us again, the row's own settings). Does nothing by default. virtual void begin_attempt(const StoryCheckpoint& data); + // The checks level the program's options chose (StoryRunOptions); + // THOROUGH unless set. Steps read it to decide what to confirm. + StoryChecks checks() const{ + return m_checks; + } + void set_checks(StoryChecks checks){ + m_checks = checks; + } + // Runs `step`: dispatch_story_step() by default. A game overrides it // to wrap every step, e.g. to turn a failed console step into a failed // Outcome. @@ -148,6 +167,9 @@ class StoryStepExecutor{ virtual Outcome save(RunState& state, const StoryStep& step); virtual Outcome ready(RunState& state, const StoryStep& step); virtual Outcome game(RunState& state, const StoryStep& step); + +private: + StoryChecks m_checks = StoryChecks::THOROUGH; }; // Calls the executor's method for the step's kind. diff --git a/SerialPrograms/Source/Pokemon/Navigation/Pokemon_StorySteps_Tests.cpp b/SerialPrograms/Source/Pokemon/Navigation/Pokemon_StorySteps_Tests.cpp index bb73f89676..9886671245 100644 --- a/SerialPrograms/Source/Pokemon/Navigation/Pokemon_StorySteps_Tests.cpp +++ b/SerialPrograms/Source/Pokemon/Navigation/Pokemon_StorySteps_Tests.cpp @@ -17,6 +17,7 @@ #include #include #include "Common/Cpp/TestRunners/UnitTest.h" +#include "Pokemon/Options/Pokemon_StoryRunOptions.h" #include "Pokemon_StoryEvents.h" #include "Pokemon_StorySegments.h" #include "Pokemon_StorySteps.h" @@ -456,6 +457,43 @@ UnitTestResult test_policy_recovers_in_place(){ return true; } +// The checks level: THOROUGH by default, and what the program sets is +// what a step reads. +UnitTestResult test_checks_level(){ + class CheckingExecutor : public FakeExecutor{ + public: + std::vector seen; + virtual Outcome talk(RunState&, const StoryStep& step) override{ + seen.push_back(step.name + " " + story_checks_name(checks())); + return outcome_ok(); + } + }; + StoryCheckpoint data = lab_checkpoint(); + CheckingExecutor executor; + run(data, executor); + executor.set_checks(StoryChecks::FAST); + run(data, executor); + if (executor.seen != std::vector{"talk_oak thorough", "talk_oak fast"}){ + return "Expected the talk to read thorough, then fast:" + joined(executor.seen); + } + return true; +} + +// The program's option group: 3 attempts, no stop, Thorough, by default; +// Fast when chosen. +UnitTestResult test_run_options(){ + StoryRunOptions options; + const SegmentPolicy policy = options.policy(); + if (policy.attempts_per_checkpoint != 3 || policy.stop_at_first_failure || options.checks() != StoryChecks::THOROUGH){ + return "Expected 3 attempts, no stop at the first failure, and Thorough checks by default."; + } + options.CHECKS.set(StoryChecks::FAST); + if (options.checks() != StoryChecks::FAST){ + return "Expected Fast checks once chosen."; + } + return true; +} + UnitTestResult test_lint(){ StoryStep no_target = make(StoryStepKind::ROUTE, "walk"); StoryStep again = make(StoryStepKind::TALK, "walk"); @@ -507,6 +545,8 @@ void add_tests_StorySteps(UnitTestDatabase& database){ database.add("unsupported kinds and lost battles", test_unsupported_and_lost_battles); database.add("tables as a segment, with a reload", test_segment_of_tables); database.add("lint", test_lint); + database.add("the checks level reaches the steps", test_checks_level); + database.add("the run options' defaults", test_run_options); database.add("policy: attempts per checkpoint, then fail", test_policy_attempts_then_fail); database.add("policy: stop at the first failure", test_policy_stop_at_first_failure); database.add("policy: recover in place before reloading", test_policy_recovers_in_place); diff --git a/SerialPrograms/Source/Pokemon/Options/Pokemon_StoryRunOptions.cpp b/SerialPrograms/Source/Pokemon/Options/Pokemon_StoryRunOptions.cpp index ceccb40638..6f90320428 100644 --- a/SerialPrograms/Source/Pokemon/Options/Pokemon_StoryRunOptions.cpp +++ b/SerialPrograms/Source/Pokemon/Options/Pokemon_StoryRunOptions.cpp @@ -10,6 +10,14 @@ namespace PokemonAutomation{ namespace Pokemon{ +const EnumDropdownDatabase& StoryChecks_Database(){ + static const EnumDropdownDatabase database({ + {StoryChecks::THOROUGH, "thorough", "Thorough: confirm purchases, the Bag, status and position on screen"}, + {StoryChecks::FAST, "fast", "Fast: trust counts and timings"}, + }); + return database; +} + StoryRunOptions::StoryRunOptions() : GroupOption("Checkpoint Retries", LockMode::LOCK_WHILE_RUNNING) , ATTEMPTS_PER_CHECKPOINT( @@ -22,9 +30,16 @@ StoryRunOptions::StoryRunOptions() LockMode::LOCK_WHILE_RUNNING, false ) + , CHECKS( + "Checks:
Thorough reads the screen to confirm what each step did; Fast trusts counts and timings, for a run in a rush.", + StoryChecks_Database(), + LockMode::LOCK_WHILE_RUNNING, + StoryChecks::THOROUGH + ) { PA_ADD_OPTION(ATTEMPTS_PER_CHECKPOINT); PA_ADD_OPTION(STOP_AT_FIRST_FAILURE); + PA_ADD_OPTION(CHECKS); } SegmentPolicy StoryRunOptions::policy() const{ @@ -34,6 +49,10 @@ SegmentPolicy StoryRunOptions::policy() const{ return policy; } +StoryChecks StoryRunOptions::checks() const{ + return CHECKS; +} + } diff --git a/SerialPrograms/Source/Pokemon/Options/Pokemon_StoryRunOptions.h b/SerialPrograms/Source/Pokemon/Options/Pokemon_StoryRunOptions.h index 652ddd44ab..f32fdbad1a 100644 --- a/SerialPrograms/Source/Pokemon/Options/Pokemon_StoryRunOptions.h +++ b/SerialPrograms/Source/Pokemon/Options/Pokemon_StoryRunOptions.h @@ -2,9 +2,10 @@ * * From: https://github.com/PokemonAutomation/ * - * The options every AutoStory program shows for how hard to try: the - * same group in each game, read into the shared SegmentPolicy - * (Pokemon/Navigation/Pokemon_StorySegments.h). + * The options every AutoStory program shows for how hard to try and how + * much to check: the same group in each game, read into the shared + * SegmentPolicy (Pokemon/Navigation/Pokemon_StorySegments.h) and the + * executor's checks level (Pokemon_StorySteps.h). * */ @@ -13,9 +14,11 @@ #include #include "Common/Cpp/Options/BooleanCheckBoxOption.h" +#include "Common/Cpp/Options/EnumDropdownOption.h" #include "Common/Cpp/Options/GroupOption.h" #include "Common/Cpp/Options/SimpleIntegerOption.h" #include "Pokemon/Navigation/Pokemon_StorySegments.h" +#include "Pokemon/Navigation/Pokemon_StorySteps.h" namespace PokemonAutomation{ namespace Pokemon{ @@ -28,10 +31,13 @@ class StoryRunOptions : public GroupOption{ // The policy these options set. In-place recoveries are the game's to // set, not the user's. SegmentPolicy policy() const; + // The checks level for the game's story step executor (set_checks()). + StoryChecks checks() const; public: SimpleIntegerOption ATTEMPTS_PER_CHECKPOINT; BooleanCheckBoxOption STOP_AT_FIRST_FAILURE; + EnumDropdownOption CHECKS; }; From daf7b8faf9d7da7fcefeb58277fee4a10cd85ee2 Mon Sep 17 00:00:00 2001 From: dayfine Date: Sun, 1 Nov 2026 11:07:04 -0800 Subject: [PATCH 005/102] Pokemon navigation: story steps take the game's language, and never need 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 Claude-Session: https://claude.ai/code/session_01AKYzhrMnPK61XHWEch4a6E --- .../Pokemon/Navigation/Pokemon_StorySteps.h | 18 ++++++++++++ .../Navigation/Pokemon_StorySteps_Tests.cpp | 12 ++++++++ .../Options/Pokemon_StoryRunOptions.cpp | 28 +++++++++++++++++++ .../Pokemon/Options/Pokemon_StoryRunOptions.h | 5 ++++ 4 files changed, 63 insertions(+) diff --git a/SerialPrograms/Source/Pokemon/Navigation/Pokemon_StorySteps.h b/SerialPrograms/Source/Pokemon/Navigation/Pokemon_StorySteps.h index 99b9b74583..84972ead25 100644 --- a/SerialPrograms/Source/Pokemon/Navigation/Pokemon_StorySteps.h +++ b/SerialPrograms/Source/Pokemon/Navigation/Pokemon_StorySteps.h @@ -14,6 +14,13 @@ * implements the kinds it uses, and a step the game has no way of doing * fails by name instead of doing something else. * + * Steps never match dialogue or menu text: they look for screen state (a + * dialogue box, an arrow, a fade, a battle menu, colours, positions). The + * few reads that need text (item names in a shop or the Bag) take the + * game's language from the executor, and with no reader for it fall back + * to checks that need none (a row's position, digits, a changed screen), + * so a run never fails because its language is not supported. + * * Poses are the game's own (Pose, with a TilePose for these games): a * checkpoint's start, a scene's end and a route's target are poses, and * an executor that knows where a step left the player says so in its @@ -28,6 +35,7 @@ #include #include #include +#include "CommonFramework/Language.h" #include "Pokemon_Grid.h" #include "Pokemon_StoryEvents.h" #include "Pokemon_TilePose.h" @@ -142,6 +150,15 @@ class StoryStepExecutor{ void set_checks(StoryChecks checks){ m_checks = checks; } + // The game's language (StoryRunOptions), for the reads that need text; + // English unless set. A game with no reader for it uses language-free + // checks instead. + Language language() const{ + return m_language; + } + void set_language(Language language){ + m_language = language; + } // Runs `step`: dispatch_story_step() by default. A game overrides it // to wrap every step, e.g. to turn a failed console step into a failed @@ -170,6 +187,7 @@ class StoryStepExecutor{ private: StoryChecks m_checks = StoryChecks::THOROUGH; + Language m_language = Language::English; }; // Calls the executor's method for the step's kind. diff --git a/SerialPrograms/Source/Pokemon/Navigation/Pokemon_StorySteps_Tests.cpp b/SerialPrograms/Source/Pokemon/Navigation/Pokemon_StorySteps_Tests.cpp index 9886671245..4e44b6e3b3 100644 --- a/SerialPrograms/Source/Pokemon/Navigation/Pokemon_StorySteps_Tests.cpp +++ b/SerialPrograms/Source/Pokemon/Navigation/Pokemon_StorySteps_Tests.cpp @@ -472,7 +472,11 @@ UnitTestResult test_checks_level(){ CheckingExecutor executor; run(data, executor); executor.set_checks(StoryChecks::FAST); + executor.set_language(Language::Korean); run(data, executor); + if (executor.language() != Language::Korean){ + return "Expected the language set on the executor."; + } if (executor.seen != std::vector{"talk_oak thorough", "talk_oak fast"}){ return "Expected the talk to read thorough, then fast:" + joined(executor.seen); } @@ -491,6 +495,14 @@ UnitTestResult test_run_options(){ if (options.checks() != StoryChecks::FAST){ return "Expected Fast checks once chosen."; } + // Every game language can be chosen, read or not. + if (options.language() != Language::English){ + return "Expected English by default."; + } + options.LANGUAGE.set(Language::Japanese); + if (options.language() != Language::Japanese || !options.check_validity().empty()){ + return "Expected Japanese to be chosen and valid, reader or not."; + } return true; } diff --git a/SerialPrograms/Source/Pokemon/Options/Pokemon_StoryRunOptions.cpp b/SerialPrograms/Source/Pokemon/Options/Pokemon_StoryRunOptions.cpp index 6f90320428..c68a783002 100644 --- a/SerialPrograms/Source/Pokemon/Options/Pokemon_StoryRunOptions.cpp +++ b/SerialPrograms/Source/Pokemon/Options/Pokemon_StoryRunOptions.cpp @@ -18,6 +18,22 @@ const EnumDropdownDatabase& StoryChecks_Database(){ return database; } +const EnumDropdownDatabase& StoryLanguage_Database(){ + static const EnumDropdownDatabase database({ + {Language::English, "en", "English"}, + {Language::Japanese, "ja", "Japanese"}, + {Language::Spanish, "es", "Spanish"}, + {Language::French, "fr", "French"}, + {Language::German, "de", "German"}, + {Language::Italian, "it", "Italian"}, + {Language::Korean, "ko", "Korean"}, + {Language::ChineseSimplified, "zh-Hans", "Chinese (Simplified)"}, + {Language::ChineseTraditional, "zh-Hant", "Chinese (Traditional)"}, + }); + return database; +} + + StoryRunOptions::StoryRunOptions() : GroupOption("Checkpoint Retries", LockMode::LOCK_WHILE_RUNNING) , ATTEMPTS_PER_CHECKPOINT( @@ -36,10 +52,18 @@ StoryRunOptions::StoryRunOptions() LockMode::LOCK_WHILE_RUNNING, StoryChecks::THOROUGH ) + , LANGUAGE( + "Game language:
For the few reads that need text (item names in a shop or the Bag). " + "Story steps never match dialogue text; with no reader for this language they check positions, digits and the screen instead.", + StoryLanguage_Database(), + LockMode::LOCK_WHILE_RUNNING, + Language::English + ) { PA_ADD_OPTION(ATTEMPTS_PER_CHECKPOINT); PA_ADD_OPTION(STOP_AT_FIRST_FAILURE); PA_ADD_OPTION(CHECKS); + PA_ADD_OPTION(LANGUAGE); } SegmentPolicy StoryRunOptions::policy() const{ @@ -53,6 +77,10 @@ StoryChecks StoryRunOptions::checks() const{ return CHECKS; } +Language StoryRunOptions::language() const{ + return LANGUAGE; +} + } diff --git a/SerialPrograms/Source/Pokemon/Options/Pokemon_StoryRunOptions.h b/SerialPrograms/Source/Pokemon/Options/Pokemon_StoryRunOptions.h index f32fdbad1a..4f9a3a506b 100644 --- a/SerialPrograms/Source/Pokemon/Options/Pokemon_StoryRunOptions.h +++ b/SerialPrograms/Source/Pokemon/Options/Pokemon_StoryRunOptions.h @@ -33,11 +33,16 @@ class StoryRunOptions : public GroupOption{ SegmentPolicy policy() const; // The checks level for the game's story step executor (set_checks()). StoryChecks checks() const; + // The game's language, for the executor (set_language()). + Language language() const; public: SimpleIntegerOption ATTEMPTS_PER_CHECKPOINT; BooleanCheckBoxOption STOP_AT_FIRST_FAILURE; EnumDropdownOption CHECKS; + // Any language the game has, whether or not a reader supports it: + // steps without one use language-free checks, so none is refused. + EnumDropdownOption LANGUAGE; }; From 48ff39d512b0b6670f52a80f3d22f72e19e61fe5 Mon Sep 17 00:00:00 2001 From: dayfine Date: Sun, 1 Nov 2026 12:35:02 -0800 Subject: [PATCH 006/102] Pokemon navigation: start and end checkpoint dropdowns, and the shared 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 Claude-Session: https://claude.ai/code/session_01AKYzhrMnPK61XHWEch4a6E --- .../Pokemon/Navigation/Pokemon_StorySteps.cpp | 11 +++ .../Pokemon/Navigation/Pokemon_StorySteps.h | 7 ++ .../Navigation/Pokemon_StorySteps_Tests.cpp | 68 ++++++++++++++++++- .../Options/Pokemon_StoryRunOptions.cpp | 38 ++++++++++- .../Pokemon/Options/Pokemon_StoryRunOptions.h | 47 ++++++++++++- 5 files changed, 165 insertions(+), 6 deletions(-) diff --git a/SerialPrograms/Source/Pokemon/Navigation/Pokemon_StorySteps.cpp b/SerialPrograms/Source/Pokemon/Navigation/Pokemon_StorySteps.cpp index c9825391b0..2d6a0e9383 100644 --- a/SerialPrograms/Source/Pokemon/Navigation/Pokemon_StorySteps.cpp +++ b/SerialPrograms/Source/Pokemon/Navigation/Pokemon_StorySteps.cpp @@ -258,6 +258,17 @@ std::vector lint_story_checkpoint(const StoryCheckpoint& data){ } +void record_story_stats(AutoStoryStats& stats, const SegmentReport& report){ + stats.m_segment++; + for (const CheckpointRun& run : report.runs){ + if (run.passed){ + stats.m_checkpoint++; + } + } + stats.m_reset += report.reloads; +} + + Pose tile_pose(std::string map, std::vector tiles, std::optional facing){ Pose pose; pose.map = std::move(map); diff --git a/SerialPrograms/Source/Pokemon/Navigation/Pokemon_StorySteps.h b/SerialPrograms/Source/Pokemon/Navigation/Pokemon_StorySteps.h index 84972ead25..4643d82dc8 100644 --- a/SerialPrograms/Source/Pokemon/Navigation/Pokemon_StorySteps.h +++ b/SerialPrograms/Source/Pokemon/Navigation/Pokemon_StorySteps.h @@ -36,8 +36,10 @@ #include #include #include "CommonFramework/Language.h" +#include "Pokemon/AutoStory/Pokemon_AutoStoryStats.h" #include "Pokemon_Grid.h" #include "Pokemon_StoryEvents.h" +#include "Pokemon_StorySegments.h" #include "Pokemon_TilePose.h" namespace PokemonAutomation{ @@ -213,6 +215,11 @@ Checkpoint build_story_checkpoint(const StoryCheckpoint& data, StoryStepExecutor std::vector lint_story_checkpoint(const StoryCheckpoint& data); +// Adds a segment's run to the program's stats: the segment, each checkpoint +// that passed, each reload. +void record_story_stats(AutoStoryStats& stats, const SegmentReport& report); + + // A pose on one of `tiles` of `map`, facing `facing` if set: TILE for one // tile, SET for several, UNKNOWN for none. Pose tile_pose(std::string map, std::vector tiles, std::optional facing = std::nullopt); diff --git a/SerialPrograms/Source/Pokemon/Navigation/Pokemon_StorySteps_Tests.cpp b/SerialPrograms/Source/Pokemon/Navigation/Pokemon_StorySteps_Tests.cpp index 4e44b6e3b3..e80a33946b 100644 --- a/SerialPrograms/Source/Pokemon/Navigation/Pokemon_StorySteps_Tests.cpp +++ b/SerialPrograms/Source/Pokemon/Navigation/Pokemon_StorySteps_Tests.cpp @@ -483,10 +483,74 @@ UnitTestResult test_checks_level(){ return true; } +// Two sections of a story, as BDSP has segments 00 and 01. +const std::vector& two_sections(){ + static const std::vector rows{ + StoryCheckpoint{.id = "00.01", .title = "Leave the house", .start = std::nullopt, .steps = {}}, + StoryCheckpoint{.id = "00.02", .title = "Walk to Sandgem Town", .start = std::nullopt, .steps = {}}, + StoryCheckpoint{.id = "01.01", .title = "Jubilife to Barry", .start = std::nullopt, .steps = {}}, + }; + return rows; +} +const StringSelectDatabase& two_sections_database(){ + static const StringSelectDatabase database = story_checkpoint_database(two_sections()); + return database; +} + +// The dropdowns list the checkpoints as "id title", slugged by their index +// in the whole story, which is story_index() of a section's own index. +UnitTestResult test_checkpoint_dropdowns(){ + const StringSelectDatabase& database = two_sections_database(); + const std::vector expected{"00.01 Leave the house", "00.02 Walk to Sandgem Town", "01.01 Jubilife to Barry"}; + if (database.size() != expected.size()){ + return "Expected 3 entries, got " + std::to_string(database.size()); + } + for (size_t c = 0; c < expected.size(); c++){ + if (database[c].display_name != expected[c] || database[c].slug != std::to_string(c)){ + return "Unexpected entry " + std::to_string(c) + ": " + database[c].slug + " " + database[c].display_name; + } + } + if (database[story_index(true, 0, 2)].display_name != "01.01 Jubilife to Barry"){ + return "Expected the second section's first entry at story_index(true, 0, 2)."; + } + if (story_checkpoint_label(StoryCheckpoint{.id = "00.09", .title = "Pewter Gym: Camper Liam, then Brock", .start = std::nullopt, .steps = {}}) + != "00.09 Pewter Gym: Camper Liam, then Brock" + ){ + return "Unexpected label."; + } + StoryRunOptions options(database); + if (options.start_index() != 0 || options.end_index() != 2 || !options.check_validity().empty()){ + return "Expected the whole story by default."; + } + options.START_CHECKPOINT.set_by_index(2); + options.END_CHECKPOINT.set_by_index(1); + if (options.check_validity().empty()){ + return "Expected a start after the end to be refused."; + } + return true; +} + +// A segment's report in the shared AutoStory stats. +UnitTestResult test_story_stats(){ + SegmentReport report; + report.reloads = 2; + report.runs = { + CheckpointRun{.id = "00.03", .passed = true, .attempts = 1, .recoveries = 0}, + CheckpointRun{.id = "00.04", .passed = true, .attempts = 3, .recoveries = 0}, + CheckpointRun{.id = "00.05", .passed = false, .attempts = 1, .recoveries = 0}, + }; + AutoStoryStats stats; + record_story_stats(stats, report); + if (stats.m_segment != 1 || stats.m_checkpoint != 2 || stats.m_reset != 2){ + return "Expected 1 segment, 2 checkpoints and 2 resets."; + } + return true; +} + // The program's option group: 3 attempts, no stop, Thorough, by default; // Fast when chosen. UnitTestResult test_run_options(){ - StoryRunOptions options; + StoryRunOptions options(two_sections_database()); const SegmentPolicy policy = options.policy(); if (policy.attempts_per_checkpoint != 3 || policy.stop_at_first_failure || options.checks() != StoryChecks::THOROUGH){ return "Expected 3 attempts, no stop at the first failure, and Thorough checks by default."; @@ -559,6 +623,8 @@ void add_tests_StorySteps(UnitTestDatabase& database){ database.add("lint", test_lint); database.add("the checks level reaches the steps", test_checks_level); database.add("the run options' defaults", test_run_options); + database.add("start and end checkpoint dropdowns", test_checkpoint_dropdowns); + database.add("a segment's run in the AutoStory stats", test_story_stats); database.add("policy: attempts per checkpoint, then fail", test_policy_attempts_then_fail); database.add("policy: stop at the first failure", test_policy_stop_at_first_failure); database.add("policy: recover in place before reloading", test_policy_recovers_in_place); diff --git a/SerialPrograms/Source/Pokemon/Options/Pokemon_StoryRunOptions.cpp b/SerialPrograms/Source/Pokemon/Options/Pokemon_StoryRunOptions.cpp index c68a783002..2981c681b4 100644 --- a/SerialPrograms/Source/Pokemon/Options/Pokemon_StoryRunOptions.cpp +++ b/SerialPrograms/Source/Pokemon/Options/Pokemon_StoryRunOptions.cpp @@ -34,8 +34,25 @@ const EnumDropdownDatabase& StoryLanguage_Database(){ } -StoryRunOptions::StoryRunOptions() - : GroupOption("Checkpoint Retries", LockMode::LOCK_WHILE_RUNNING) +std::string story_checkpoint_label(const StoryCheckpoint& checkpoint){ + return checkpoint.title.empty() ? checkpoint.id : checkpoint.id + " " + checkpoint.title; +} + + +StoryRunOptions::StoryRunOptions(const StringSelectDatabase& checkpoints) + : GroupOption("Story Run", LockMode::LOCK_WHILE_RUNNING) + , START_CHECKPOINT( + "Start checkpoint:
The program starts from this checkpoint's save.", + checkpoints, + LockMode::LOCK_WHILE_RUNNING, + 0 + ) + , END_CHECKPOINT( + "End checkpoint:
The program stops after this checkpoint.", + checkpoints, + LockMode::LOCK_WHILE_RUNNING, + checkpoints.size() == 0 ? 0 : checkpoints.size() - 1 + ) , ATTEMPTS_PER_CHECKPOINT( "Attempts per checkpoint:
A failed checkpoint reloads its save and runs again, up to this many times in all.", LockMode::LOCK_WHILE_RUNNING, @@ -60,12 +77,29 @@ StoryRunOptions::StoryRunOptions() Language::English ) { + PA_ADD_OPTION(START_CHECKPOINT); + PA_ADD_OPTION(END_CHECKPOINT); PA_ADD_OPTION(ATTEMPTS_PER_CHECKPOINT); PA_ADD_OPTION(STOP_AT_FIRST_FAILURE); PA_ADD_OPTION(CHECKS); PA_ADD_OPTION(LANGUAGE); } +size_t StoryRunOptions::start_index() const{ + return START_CHECKPOINT.index(); +} + +size_t StoryRunOptions::end_index() const{ + return END_CHECKPOINT.index(); +} + +std::string StoryRunOptions::check_validity() const{ + if (start_index() > end_index()){ + return "The start checkpoint comes after the end checkpoint."; + } + return GroupOption::check_validity(); +} + SegmentPolicy StoryRunOptions::policy() const{ SegmentPolicy policy; policy.attempts_per_checkpoint = ATTEMPTS_PER_CHECKPOINT; diff --git a/SerialPrograms/Source/Pokemon/Options/Pokemon_StoryRunOptions.h b/SerialPrograms/Source/Pokemon/Options/Pokemon_StoryRunOptions.h index 4f9a3a506b..65e7a8258f 100644 --- a/SerialPrograms/Source/Pokemon/Options/Pokemon_StoryRunOptions.h +++ b/SerialPrograms/Source/Pokemon/Options/Pokemon_StoryRunOptions.h @@ -2,8 +2,8 @@ * * From: https://github.com/PokemonAutomation/ * - * The options every AutoStory program shows for how hard to try and how - * much to check: the same group in each game, read into the shared + * The options every AutoStory program shows for where to start and end, how + * hard to try and how much to check: the same group in each game, read into the shared * SegmentPolicy (Pokemon/Navigation/Pokemon_StorySegments.h) and the * executor's checks level (Pokemon_StorySteps.h). * @@ -13,10 +13,15 @@ #define PokemonAutomation_Pokemon_StoryRunOptions_H #include +#include +#include +#include #include "Common/Cpp/Options/BooleanCheckBoxOption.h" #include "Common/Cpp/Options/EnumDropdownOption.h" #include "Common/Cpp/Options/GroupOption.h" #include "Common/Cpp/Options/SimpleIntegerOption.h" +#include "CommonTools/Options/StringSelectOption.h" +#include "Pokemon/AutoStory/Pokemon_AutoStorySelect.h" #include "Pokemon/Navigation/Pokemon_StorySegments.h" #include "Pokemon/Navigation/Pokemon_StorySteps.h" @@ -24,9 +29,43 @@ namespace PokemonAutomation{ namespace Pokemon{ +// A checkpoint's entry in the start and end dropdowns, as SV labels its +// segments: "00.09 Pewter Gym: Camper Liam, then Brock". +struct StoryCheckpointEntry{ + std::string label; + const std::string& name() const{ + return label; + } +}; +std::string story_checkpoint_label(const StoryCheckpoint& checkpoint); + +// The start/end dropdown database of a story's checkpoints, `rows` in +// order, slugged by their index in it (make_story_select_database()). A +// game whose story is in sections (BDSP's segments 00 and 01) passes them +// joined: a section's entry i is then story_index(true, i, first of the +// section). The program keeps it in a function-local static: the options +// hold a reference. +template +StringSelectDatabase story_checkpoint_database(const std::vector& rows){ + std::vector> entries; + for (const StoryCheckpoint& row : rows){ + entries.emplace_back(std::make_unique(StoryCheckpointEntry{.label = story_checkpoint_label(row)})); + } + return make_story_select_database(entries, 0, entries.size()); +} + + class StoryRunOptions : public GroupOption{ public: - StoryRunOptions(); + // `checkpoints`: story_checkpoint_database() of the game's story, kept + // alive by the caller; the dropdowns start on its first and last. + explicit StoryRunOptions(const StringSelectDatabase& checkpoints); + + // The checkpoints to run, by index in the database, both inclusive. + size_t start_index() const; + size_t end_index() const; + // "The start checkpoint comes after the end checkpoint." if it does. + virtual std::string check_validity() const override; // The policy these options set. In-place recoveries are the game's to // set, not the user's. @@ -37,6 +76,8 @@ class StoryRunOptions : public GroupOption{ Language language() const; public: + StringSelectOption START_CHECKPOINT; + StringSelectOption END_CHECKPOINT; SimpleIntegerOption ATTEMPTS_PER_CHECKPOINT; BooleanCheckBoxOption STOP_AT_FIRST_FAILURE; EnumDropdownOption CHECKS; From daf7a0968a60cd5f3d690ed5bf2b7ce80470a1cf Mon Sep 17 00:00:00 2001 From: dayfine Date: Sun, 1 Nov 2026 14:16:26 -0800 Subject: [PATCH 007/102] Pokemon AutoStory: the story steps move out of Pokemon/Navigation 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 Claude-Session: https://claude.ai/code/session_01AKYzhrMnPK61XHWEch4a6E --- .../Source/Pokemon/AutoStory/Pokemon_AutoStory_Tests.h | 1 + .../{Navigation => AutoStory}/Pokemon_StorySteps.cpp | 0 .../Pokemon/{Navigation => AutoStory}/Pokemon_StorySteps.h | 4 ++-- .../{Navigation => AutoStory}/Pokemon_StorySteps_Tests.cpp | 2 +- .../Source/Pokemon/Navigation/Pokemon_Navigation_Tests.h | 1 - .../Source/Pokemon/Options/Pokemon_StoryRunOptions.h | 6 +++--- SerialPrograms/cmake/SourceFiles.cmake | 6 +++--- 7 files changed, 10 insertions(+), 10 deletions(-) rename SerialPrograms/Source/Pokemon/{Navigation => AutoStory}/Pokemon_StorySteps.cpp (100%) rename SerialPrograms/Source/Pokemon/{Navigation => AutoStory}/Pokemon_StorySteps.h (96%) rename SerialPrograms/Source/Pokemon/{Navigation => AutoStory}/Pokemon_StorySteps_Tests.cpp (97%) diff --git a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_AutoStory_Tests.h b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_AutoStory_Tests.h index 29e4dd765e..a3eabb13a8 100644 --- a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_AutoStory_Tests.h +++ b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_AutoStory_Tests.h @@ -17,6 +17,7 @@ namespace Pokemon{ void add_tests_StoryEvents(UnitTestDatabase& database); void add_tests_StorySegments(UnitTestDatabase& database); +void add_tests_StorySteps(UnitTestDatabase& database); diff --git a/SerialPrograms/Source/Pokemon/Navigation/Pokemon_StorySteps.cpp b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StorySteps.cpp similarity index 100% rename from SerialPrograms/Source/Pokemon/Navigation/Pokemon_StorySteps.cpp rename to SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StorySteps.cpp diff --git a/SerialPrograms/Source/Pokemon/Navigation/Pokemon_StorySteps.h b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StorySteps.h similarity index 96% rename from SerialPrograms/Source/Pokemon/Navigation/Pokemon_StorySteps.h rename to SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StorySteps.h index 4643d82dc8..fb5b2471d6 100644 --- a/SerialPrograms/Source/Pokemon/Navigation/Pokemon_StorySteps.h +++ b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StorySteps.h @@ -36,8 +36,8 @@ #include #include #include "CommonFramework/Language.h" -#include "Pokemon/AutoStory/Pokemon_AutoStoryStats.h" -#include "Pokemon_Grid.h" +#include "Pokemon/Navigation/Pokemon_Grid.h" +#include "Pokemon_AutoStoryStats.h" #include "Pokemon_StoryEvents.h" #include "Pokemon_StorySegments.h" #include "Pokemon_TilePose.h" diff --git a/SerialPrograms/Source/Pokemon/Navigation/Pokemon_StorySteps_Tests.cpp b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StorySteps_Tests.cpp similarity index 97% rename from SerialPrograms/Source/Pokemon/Navigation/Pokemon_StorySteps_Tests.cpp rename to SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StorySteps_Tests.cpp index e80a33946b..58232f50f8 100644 --- a/SerialPrograms/Source/Pokemon/Navigation/Pokemon_StorySteps_Tests.cpp +++ b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StorySteps_Tests.cpp @@ -22,7 +22,7 @@ #include "Pokemon_StorySegments.h" #include "Pokemon_StorySteps.h" #include "Pokemon_TilePose.h" -#include "Pokemon_Navigation_Tests.h" +#include "Pokemon_AutoStory_Tests.h" namespace PokemonAutomation{ namespace Pokemon{ diff --git a/SerialPrograms/Source/Pokemon/Navigation/Pokemon_Navigation_Tests.h b/SerialPrograms/Source/Pokemon/Navigation/Pokemon_Navigation_Tests.h index 0aa83f1749..06084295e8 100644 --- a/SerialPrograms/Source/Pokemon/Navigation/Pokemon_Navigation_Tests.h +++ b/SerialPrograms/Source/Pokemon/Navigation/Pokemon_Navigation_Tests.h @@ -20,7 +20,6 @@ void add_tests_LegPlanner(UnitTestDatabase& database); void add_tests_LegWalker(UnitTestDatabase& database); void add_tests_MapData(UnitTestDatabase& database); void add_tests_RouteLog(UnitTestDatabase& database); -void add_tests_StorySteps(UnitTestDatabase& database); // (name, JSON text) of each map in Pokemon/Navigation/TestMaps/, built into // the program by pa_embed_text_files() (cmake/EmbedTextFiles.cmake). diff --git a/SerialPrograms/Source/Pokemon/Options/Pokemon_StoryRunOptions.h b/SerialPrograms/Source/Pokemon/Options/Pokemon_StoryRunOptions.h index 65e7a8258f..2e293318a4 100644 --- a/SerialPrograms/Source/Pokemon/Options/Pokemon_StoryRunOptions.h +++ b/SerialPrograms/Source/Pokemon/Options/Pokemon_StoryRunOptions.h @@ -4,7 +4,7 @@ * * The options every AutoStory program shows for where to start and end, how * hard to try and how much to check: the same group in each game, read into the shared - * SegmentPolicy (Pokemon/Navigation/Pokemon_StorySegments.h) and the + * SegmentPolicy (Pokemon/AutoStory/Pokemon_StorySegments.h) and the * executor's checks level (Pokemon_StorySteps.h). * */ @@ -22,8 +22,8 @@ #include "Common/Cpp/Options/SimpleIntegerOption.h" #include "CommonTools/Options/StringSelectOption.h" #include "Pokemon/AutoStory/Pokemon_AutoStorySelect.h" -#include "Pokemon/Navigation/Pokemon_StorySegments.h" -#include "Pokemon/Navigation/Pokemon_StorySteps.h" +#include "Pokemon/AutoStory/Pokemon_StorySegments.h" +#include "Pokemon/AutoStory/Pokemon_StorySteps.h" namespace PokemonAutomation{ namespace Pokemon{ diff --git a/SerialPrograms/cmake/SourceFiles.cmake b/SerialPrograms/cmake/SourceFiles.cmake index ac36d37091..02fcfdf195 100644 --- a/SerialPrograms/cmake/SourceFiles.cmake +++ b/SerialPrograms/cmake/SourceFiles.cmake @@ -1465,9 +1465,6 @@ file(GLOB LIBRARY_SOURCES Source/Pokemon/Navigation/Pokemon_RouteLog.cpp Source/Pokemon/Navigation/Pokemon_RouteLog.h Source/Pokemon/Navigation/Pokemon_RouteLog_Tests.cpp - Source/Pokemon/Navigation/Pokemon_StorySteps.cpp - Source/Pokemon/Navigation/Pokemon_StorySteps.h - Source/Pokemon/Navigation/Pokemon_StorySteps_Tests.cpp Source/Pokemon/Options/Pokemon_BoxSortingTable.cpp Source/Pokemon/Options/Pokemon_BoxSortingTable.h Source/Pokemon/Options/Pokemon_EncounterBotOptions.h @@ -1492,6 +1489,9 @@ file(GLOB LIBRARY_SOURCES Source/Pokemon/AutoStory/Pokemon_StorySegments.cpp Source/Pokemon/AutoStory/Pokemon_StorySegments.h Source/Pokemon/AutoStory/Pokemon_StorySegments_Tests.cpp + Source/Pokemon/AutoStory/Pokemon_StorySteps.cpp + Source/Pokemon/AutoStory/Pokemon_StorySteps.h + Source/Pokemon/AutoStory/Pokemon_StorySteps_Tests.cpp Source/Pokemon/AutoStory/Pokemon_TilePose.cpp Source/Pokemon/AutoStory/Pokemon_TilePose.h Source/Pokemon/Pokemon_AdvRng.cpp From e67d36ccb4bf7babcf3370c0b45178d3674efdcd Mon Sep 17 00:00:00 2001 From: dayfine Date: Sun, 1 Nov 2026 14:31:18 -0800 Subject: [PATCH 008/102] Pokemon AutoStory: the executor's step-kind methods are protected 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 Claude-Session: https://claude.ai/code/session_01AKYzhrMnPK61XHWEch4a6E --- .../Pokemon/AutoStory/Pokemon_StorySteps.h | 4 ++ .../AutoStory/Pokemon_StorySteps_Tests.cpp | 44 +++++++++++-------- 2 files changed, 30 insertions(+), 18 deletions(-) diff --git a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StorySteps.h b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StorySteps.h index fb5b2471d6..d32868aeef 100644 --- a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StorySteps.h +++ b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StorySteps.h @@ -171,6 +171,10 @@ class StoryStepExecutor{ // whether the run has the flag (set by an earlier step's action). virtual bool holds(const std::string& condition, RunState& state); +protected: + // One per step kind, called by dispatch_story_step(); each fails as + // unsupported unless the game overrides it. + friend Outcome dispatch_story_step(StoryStepExecutor& executor, RunState& state, const StoryStep& step); virtual Outcome new_game(RunState& state, const StoryStep& step); virtual Outcome options(RunState& state, const StoryStep& step); virtual Outcome route(RunState& state, const StoryStep& step); diff --git a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StorySteps_Tests.cpp b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StorySteps_Tests.cpp index 58232f50f8..bae1b6977d 100644 --- a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StorySteps_Tests.cpp +++ b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StorySteps_Tests.cpp @@ -66,6 +66,8 @@ class FakeExecutor : public StoryStepExecutor{ virtual bool holds(const std::string& condition, RunState& state) override{ return conditions.contains(condition) || StoryStepExecutor::holds(condition, state); } + +protected: virtual Outcome route(RunState&, const StoryStep& step) override{ return outcome_ok(*step.target); } @@ -292,20 +294,10 @@ UnitTestResult test_unsupported_and_lost_battles(){ return true; } -UnitTestResult test_segment_of_tables(){ - // Two rows built into a segment, run with saves and a reload from the - // game's hooks: the second row's first attempt fails, its retry starts - // over from its start pose. - const std::vector tables{ - lab_checkpoint(), - StoryCheckpoint{ - .id = "00.04", - .title = "the parcel", - .start = tile_pose("Lab", {{6, 4}}, Direction::NORTH), - .steps = {make(StoryStepKind::TALK, "give_parcel")}, - }, - }; - FakeExecutor executor; +// Runs `tables` as one segment whose saves and reloads go into the +// executor's trace and whose log lines go into `lines`. Whatever blocked a +// step has gone by the reload. +SegmentReport run_tables(const std::vector& tables, FakeExecutor& executor, std::vector& lines){ Segment segment; segment.id = "00"; for (const StoryCheckpoint& data : tables){ @@ -314,22 +306,38 @@ UnitTestResult test_segment_of_tables(){ .build = [&data, &executor]{ return build_story_checkpoint(data, executor); }, }); } - std::vector lines; SegmentHooks hooks; hooks.save = [&executor](RunState&){ executor.trace.push_back("save"); return outcome_ok(); }; - // Whatever blocked the talk has gone by the reload. hooks.reload = [&executor](RunState&){ executor.trace.push_back("reload"); executor.failing.clear(); return outcome_ok(); }; hooks.log = [&lines](const std::string& line){ lines.push_back(line); }; - executor.failing = {"give_parcel"}; RunState state; - const SegmentReport report = run_segment(state, segment, SegmentRange{}, SegmentPolicy{}, hooks); + return run_segment(state, segment, SegmentRange{}, SegmentPolicy{}, hooks); +} + +UnitTestResult test_segment_of_tables(){ + // Two rows built into a segment, run with saves and a reload from the + // game's hooks: the second row's first attempt fails, its retry starts + // over from its start pose. + const std::vector tables{ + lab_checkpoint(), + StoryCheckpoint{ + .id = "00.04", + .title = "the parcel", + .start = tile_pose("Lab", {{6, 4}}, Direction::NORTH), + .steps = {make(StoryStepKind::TALK, "give_parcel")}, + }, + }; + FakeExecutor executor; + executor.failing = {"give_parcel"}; + std::vector lines; + const SegmentReport report = run_tables(tables, executor, lines); const std::vector tail{"save", "TALK give_parcel", "reload", "TALK give_parcel", "save"}; const bool tail_matches = executor.trace.size() >= tail.size() && std::equal(tail.begin(), tail.end(), executor.trace.end() - (std::ptrdiff_t)tail.size()); From 24444f0fc38c819440b1112fcafc292bce2e0b53 Mon Sep 17 00:00:00 2001 From: dayfine Date: Tue, 3 Nov 2026 05:16:01 -0800 Subject: [PATCH 009/102] Pokemon AutoStory: verify mode in the story run options 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 Claude-Session: https://claude.ai/code/session_01AKYzhrMnPK61XHWEch4a6E --- .../AutoStory/Pokemon_StorySteps_Tests.cpp | 26 ++++++++++++ .../Options/Pokemon_StoryRunOptions.cpp | 40 +++++++++++++++++++ .../Pokemon/Options/Pokemon_StoryRunOptions.h | 21 ++++++++++ 3 files changed, 87 insertions(+) diff --git a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StorySteps_Tests.cpp b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StorySteps_Tests.cpp index bae1b6977d..321362a126 100644 --- a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StorySteps_Tests.cpp +++ b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StorySteps_Tests.cpp @@ -12,6 +12,7 @@ #include #include #include +#include #include #include #include @@ -578,6 +579,30 @@ UnitTestResult test_run_options(){ return true; } +// Verify mode: off by default; 3 runs and 2 passes when on, for one +// checkpoint only, never needing more passes than runs. +UnitTestResult test_verify_options(){ + StoryRunOptions options(two_sections_database()); + if (options.VERIFY.policy()){ + return "Expected verify mode off by default."; + } + options.VERIFY.set_enabled(true); + if (options.check_validity().empty()){ + return "Expected verify mode refused over more than one checkpoint."; + } + options.END_CHECKPOINT.set_by_index(options.start_index()); + const std::optional policy = options.VERIFY.policy(); + if (!options.check_validity().empty() || !policy || policy->runs != 3 || policy->passes_needed != 2){ + return "Expected 3 runs and 2 passes on one checkpoint: " + options.check_validity(); + } + options.VERIFY.RUNS.set(2); + options.VERIFY.PASSES.set(3); + if (options.check_validity().empty()){ + return "Expected more passes than runs refused."; + } + return true; +} + UnitTestResult test_lint(){ StoryStep no_target = make(StoryStepKind::ROUTE, "walk"); StoryStep again = make(StoryStepKind::TALK, "walk"); @@ -631,6 +656,7 @@ void add_tests_StorySteps(UnitTestDatabase& database){ database.add("lint", test_lint); database.add("the checks level reaches the steps", test_checks_level); database.add("the run options' defaults", test_run_options); + database.add("the run options' verify mode", test_verify_options); database.add("start and end checkpoint dropdowns", test_checkpoint_dropdowns); database.add("a segment's run in the AutoStory stats", test_story_stats); database.add("policy: attempts per checkpoint, then fail", test_policy_attempts_then_fail); diff --git a/SerialPrograms/Source/Pokemon/Options/Pokemon_StoryRunOptions.cpp b/SerialPrograms/Source/Pokemon/Options/Pokemon_StoryRunOptions.cpp index 2981c681b4..a5d0b1862f 100644 --- a/SerialPrograms/Source/Pokemon/Options/Pokemon_StoryRunOptions.cpp +++ b/SerialPrograms/Source/Pokemon/Options/Pokemon_StoryRunOptions.cpp @@ -39,6 +39,42 @@ std::string story_checkpoint_label(const StoryCheckpoint& checkpoint){ } +StoryVerifyOptions::StoryVerifyOptions() + : GroupOption( + "Verify Mode: run the start checkpoint (also the end) from its save several times, never saving at its end", + LockMode::LOCK_WHILE_RUNNING, + EnableMode::DEFAULT_DISABLED + ) + , RUNS( + "Runs:
Runs of the checkpoint, each from its save.", + LockMode::LOCK_WHILE_RUNNING, + 3, 1, 20 + ) + , PASSES( + "Passes needed:
Runs that must pass for the checkpoint to be verified.", + LockMode::LOCK_WHILE_RUNNING, + 2, 1, 20 + ) +{ + PA_ADD_OPTION(RUNS); + PA_ADD_OPTION(PASSES); +} + +std::optional StoryVerifyOptions::policy() const{ + if (!enabled()){ + return std::nullopt; + } + return VerifyPolicy{.runs = RUNS, .passes_needed = PASSES}; +} + +std::string StoryVerifyOptions::check_validity() const{ + if (enabled() && PASSES > RUNS){ + return "Verify mode can't need more passes than it has runs."; + } + return GroupOption::check_validity(); +} + + StoryRunOptions::StoryRunOptions(const StringSelectDatabase& checkpoints) : GroupOption("Story Run", LockMode::LOCK_WHILE_RUNNING) , START_CHECKPOINT( @@ -83,6 +119,7 @@ StoryRunOptions::StoryRunOptions(const StringSelectDatabase& checkpoints) PA_ADD_OPTION(STOP_AT_FIRST_FAILURE); PA_ADD_OPTION(CHECKS); PA_ADD_OPTION(LANGUAGE); + PA_ADD_OPTION(VERIFY); } size_t StoryRunOptions::start_index() const{ @@ -97,6 +134,9 @@ std::string StoryRunOptions::check_validity() const{ if (start_index() > end_index()){ return "The start checkpoint comes after the end checkpoint."; } + if (VERIFY.enabled() && start_index() != end_index()){ + return "Verify mode runs one checkpoint: set the end checkpoint to the start checkpoint."; + } return GroupOption::check_validity(); } diff --git a/SerialPrograms/Source/Pokemon/Options/Pokemon_StoryRunOptions.h b/SerialPrograms/Source/Pokemon/Options/Pokemon_StoryRunOptions.h index 2e293318a4..0aa9c63a47 100644 --- a/SerialPrograms/Source/Pokemon/Options/Pokemon_StoryRunOptions.h +++ b/SerialPrograms/Source/Pokemon/Options/Pokemon_StoryRunOptions.h @@ -14,6 +14,7 @@ #include #include +#include #include #include #include "Common/Cpp/Options/BooleanCheckBoxOption.h" @@ -55,6 +56,24 @@ StringSelectDatabase story_checkpoint_database(const std::vector& rows){ } +// Verify mode, off by default (verify_checkpoint()): the start checkpoint +// RUNS times from its save, never saving at its end; verified when at +// least PASSES pass. For a battle that has lost twice or more, given its +// own checkpoint saved right before it. +class StoryVerifyOptions : public GroupOption{ +public: + StoryVerifyOptions(); + + // The runs and passes, unset when verify mode is off. + std::optional policy() const; + virtual std::string check_validity() const override; + +public: + SimpleIntegerOption RUNS; + SimpleIntegerOption PASSES; +}; + + class StoryRunOptions : public GroupOption{ public: // `checkpoints`: story_checkpoint_database() of the game's story, kept @@ -84,6 +103,8 @@ class StoryRunOptions : public GroupOption{ // Any language the game has, whether or not a reader supports it: // steps without one use language-free checks, so none is refused. EnumDropdownOption LANGUAGE; + // On, it runs one checkpoint: the start, which must also be the end. + StoryVerifyOptions VERIFY; }; From 58aa81d04b1db29db52bd13e801e407f99e35513 Mon Sep 17 00:00:00 2001 From: dayfine Date: Thu, 5 Nov 2026 12:55:33 -0800 Subject: [PATCH 010/102] Pokemon navigation: bring nav/story-steps into #231 lint conventions - 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 --- .../AutoStory/Pokemon_AutoStory_Tests.h | 1 + .../Pokemon/AutoStory/Pokemon_StorySteps.cpp | 8 +- .../Pokemon/AutoStory/Pokemon_StorySteps.h | 9 +- .../AutoStory/Pokemon_StorySteps_Tests.cpp | 111 ++++++++++++++---- .../Options/Pokemon_StoryRunOptions.cpp | 4 +- .../Pokemon/Options/Pokemon_StoryRunOptions.h | 9 +- 6 files changed, 109 insertions(+), 33 deletions(-) diff --git a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_AutoStory_Tests.h b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_AutoStory_Tests.h index fdc6ea9083..8757fff3fd 100644 --- a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_AutoStory_Tests.h +++ b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_AutoStory_Tests.h @@ -19,6 +19,7 @@ namespace Pokemon{ void add_tests_StoryEvents(UnitTestDatabase& database); // Registers unit tests for story segment running, verification, and branching. void add_tests_StorySegments(UnitTestDatabase& database); +// Registers unit tests for high-level story step dispatching and table conversion. void add_tests_StorySteps(UnitTestDatabase& database); diff --git a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StorySteps.cpp b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StorySteps.cpp index 2d6a0e9383..01f224f593 100644 --- a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StorySteps.cpp +++ b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StorySteps.cpp @@ -188,7 +188,7 @@ Event from_save_event(const Pose& start){ return event; } -} +} // namespace Checkpoint build_story_checkpoint(const StoryCheckpoint& data, StoryStepExecutor& executor){ executor.begin_attempt(data); @@ -233,7 +233,7 @@ std::string missing_field(const StoryStep& step){ } } -} +} // namespace std::vector lint_story_checkpoint(const StoryCheckpoint& data){ std::vector problems; @@ -285,5 +285,5 @@ std::optional facing_of(const Pose& pose){ -} -} +} // namespace Pokemon +} // namespace PokemonAutomation diff --git a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StorySteps.h b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StorySteps.h index d32868aeef..60e090cbf8 100644 --- a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StorySteps.h +++ b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StorySteps.h @@ -46,6 +46,7 @@ namespace PokemonAutomation{ namespace Pokemon{ +// Action category classification for individual story steps. enum class StoryStepKind{ NEW_GAME, // title screen (no save) to the first room OPTIONS, // the game's options as the story needs them @@ -63,6 +64,7 @@ enum class StoryStepKind{ READY, // before a big battle: items, and the nurse at `target` if they can't GAME, // a step only this game has, named by `variant` }; +// Returns the readable string representation of a story step kind. const char* story_step_kind_name(StoryStepKind kind); // How much a step reads the screen to confirm what it did. Each game @@ -73,6 +75,7 @@ enum class StoryChecks{ // In a rush: trust counts and timings. FAST, }; +// Returns the readable string representation of a story check level. const char* story_checks_name(StoryChecks checks); @@ -88,6 +91,7 @@ struct StoryItem{ size_t quantity = 0; }; +// Specification of an atomic story task with actions and postconditions. struct StoryStep{ StoryStepKind kind = StoryStepKind::TALK; std::string name; @@ -124,6 +128,7 @@ struct StoryStep{ std::optional pose_after; }; +// Milestone row in the story table grouping related steps and starting pose. struct StoryCheckpoint{ std::string id; std::string title; @@ -233,6 +238,6 @@ std::optional facing_of(const Pose& pose); -} -} +} // namespace Pokemon +} // namespace PokemonAutomation #endif diff --git a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StorySteps_Tests.cpp b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StorySteps_Tests.cpp index 321362a126..6bef5f7e6b 100644 --- a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StorySteps_Tests.cpp +++ b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StorySteps_Tests.cpp @@ -629,42 +629,107 @@ UnitTestResult test_lint(){ } +struct StoryStepInput{ + std::string name; + UnitTestResult (*test)(); +}; + +struct StoryStepExpectation{ + const char* description; +}; + +struct StoryStepTestCase{ + StoryStepInput input; + StoryStepExpectation expectation; +}; + class Test_StorySteps : public UnitTest{ public: - Test_StorySteps(std::string name, std::function body) - : UnitTest("Pokemon::StorySteps - " + std::move(name)) - , m_body(std::move(body)) + explicit Test_StorySteps(StoryStepTestCase scenario) + : UnitTest("Pokemon::StorySteps - " + scenario.input.name) + , m_scenario(std::move(scenario)) {} virtual UnitTestResult run(Logger&, CancellableScope&) const override{ - return m_body(); + return m_scenario.input.test(); } private: - std::function m_body; + StoryStepTestCase m_scenario; }; -} +const StoryStepTestCase STORY_STEP_CASES[] = { + { + .input = {.name = "steps run in table order", .test = test_events_in_table_order}, + .expectation = {.description = "executes story steps sequentially as defined in table"}, + }, + { + .input = {.name = "skip_if asks the executor", .test = test_skip_if}, + .expectation = {.description = "delegates skip condition check to executor"}, + }, + { + .input = {.name = "each step starts where the last left the player", .test = test_pose_propagation}, + .expectation = {.description = "propagates player pose across sequential step executions"}, + }, + { + .input = {.name = "a failure names its step", .test = test_failure_names_the_step}, + .expectation = {.description = "records failing step identifier on error"}, + }, + { + .input = {.name = "unsupported kinds and lost battles", .test = test_unsupported_and_lost_battles}, + .expectation = {.description = "flags unsupported step types and handles battle defeat"}, + }, + { + .input = {.name = "tables as a segment, with a reload", .test = test_segment_of_tables}, + .expectation = {.description = "converts step tables into segment with checkpoint reload support"}, + }, + { + .input = {.name = "lint", .test = test_lint}, + .expectation = {.description = "verifies lint validation rules on story checkpoints"}, + }, + { + .input = {.name = "the checks level reaches the steps", .test = test_checks_level}, + .expectation = {.description = "transfers checks granularity option to step execution"}, + }, + { + .input = {.name = "the run options' defaults", .test = test_run_options}, + .expectation = {.description = "validates initial default story run option values"}, + }, + { + .input = {.name = "the run options' verify mode", .test = test_verify_options}, + .expectation = {.description = "configures verification mode options and passes count"}, + }, + { + .input = {.name = "start and end checkpoint dropdowns", .test = test_checkpoint_dropdowns}, + .expectation = {.description = "populates start and end dropdown selections correctly"}, + }, + { + .input = {.name = "a segment's run in the AutoStory stats", .test = test_story_stats}, + .expectation = {.description = "updates story run statistics following segment completion"}, + }, + { + .input = {.name = "policy: attempts per checkpoint, then fail", .test = test_policy_attempts_then_fail}, + .expectation = {.description = "enforces max checkpoint attempt policy before terminal failure"}, + }, + { + .input = {.name = "policy: stop at the first failure", .test = test_policy_stop_at_first_failure}, + .expectation = {.description = "halts execution immediately when stop_at_first_failure is enabled"}, + }, + { + .input = {.name = "policy: recover in place before reloading", .test = test_policy_recovers_in_place}, + .expectation = {.description = "applies in-place recovery handler prior to reloading save"}, + }, +}; + +} // namespace void add_tests_StorySteps(UnitTestDatabase& database){ - database.add("steps run in table order", test_events_in_table_order); - database.add("skip_if asks the executor", test_skip_if); - database.add("each step starts where the last left the player", test_pose_propagation); - database.add("a failure names its step", test_failure_names_the_step); - database.add("unsupported kinds and lost battles", test_unsupported_and_lost_battles); - database.add("tables as a segment, with a reload", test_segment_of_tables); - database.add("lint", test_lint); - database.add("the checks level reaches the steps", test_checks_level); - database.add("the run options' defaults", test_run_options); - database.add("the run options' verify mode", test_verify_options); - database.add("start and end checkpoint dropdowns", test_checkpoint_dropdowns); - database.add("a segment's run in the AutoStory stats", test_story_stats); - database.add("policy: attempts per checkpoint, then fail", test_policy_attempts_then_fail); - database.add("policy: stop at the first failure", test_policy_stop_at_first_failure); - database.add("policy: recover in place before reloading", test_policy_recovers_in_place); + for (const auto& scenario : STORY_STEP_CASES){ + database.add(scenario); + } } -} -} +} // namespace Pokemon +} // namespace PokemonAutomation diff --git a/SerialPrograms/Source/Pokemon/Options/Pokemon_StoryRunOptions.cpp b/SerialPrograms/Source/Pokemon/Options/Pokemon_StoryRunOptions.cpp index a5d0b1862f..5ce0fb7ab0 100644 --- a/SerialPrograms/Source/Pokemon/Options/Pokemon_StoryRunOptions.cpp +++ b/SerialPrograms/Source/Pokemon/Options/Pokemon_StoryRunOptions.cpp @@ -157,5 +157,5 @@ Language StoryRunOptions::language() const{ -} -} +} // namespace Pokemon +} // namespace PokemonAutomation diff --git a/SerialPrograms/Source/Pokemon/Options/Pokemon_StoryRunOptions.h b/SerialPrograms/Source/Pokemon/Options/Pokemon_StoryRunOptions.h index 0aa9c63a47..c54482cc52 100644 --- a/SerialPrograms/Source/Pokemon/Options/Pokemon_StoryRunOptions.h +++ b/SerialPrograms/Source/Pokemon/Options/Pokemon_StoryRunOptions.h @@ -38,6 +38,7 @@ struct StoryCheckpointEntry{ return label; } }; +// Formats a checkpoint identifier and description into a dropdown label. std::string story_checkpoint_label(const StoryCheckpoint& checkpoint); // The start/end dropdown database of a story's checkpoints, `rows` in @@ -46,6 +47,9 @@ std::string story_checkpoint_label(const StoryCheckpoint& checkpoint); // joined: a section's entry i is then story_index(true, i, first of the // section). The program keeps it in a function-local static: the options // hold a reference. +template +StringSelectDatabase story_checkpoint_database(const std::vector& rows); + template StringSelectDatabase story_checkpoint_database(const std::vector& rows){ std::vector> entries; @@ -74,6 +78,7 @@ class StoryVerifyOptions : public GroupOption{ }; +// Configuration options panel for selecting story checkpoints and execution mode. class StoryRunOptions : public GroupOption{ public: // `checkpoints`: story_checkpoint_database() of the game's story, kept @@ -109,6 +114,6 @@ class StoryRunOptions : public GroupOption{ -} -} +} // namespace Pokemon +} // namespace PokemonAutomation #endif From 64540276b6ef7684fc2e572da3303939fc7aa279 Mon Sep 17 00:00:00 2001 From: Di Fan <26423504+dayfine@users.noreply.github.com> Date: Sat, 7 Nov 2026 20:05:40 -0800 Subject: [PATCH 011/102] Add shared story checkpoint JSON codec and portable tests (#250) * Add shared story checkpoint JSON codec and portable tests * Avoid shadowing pose input in facing decoder * Initialize rejection-case canonical value for Clang --- .github/workflows/story-data.yml | 34 ++ .../ComputerPrograms_UnitTestRunner.cpp | 1 + .../AutoStory/Pokemon_AutoStory_Tests.h | 3 + .../AutoStory/Pokemon_StoryStepJson.cpp | 355 ++++++++++++++++++ .../Pokemon/AutoStory/Pokemon_StoryStepJson.h | 26 ++ .../AutoStory/Pokemon_StoryStepJson_Tests.cpp | 150 ++++++++ SerialPrograms/cmake/SourceFiles.cmake | 3 + devtools/story-data-tests/CMakeLists.txt | 33 ++ devtools/story-data-tests/README.md | 35 ++ 9 files changed, 640 insertions(+) create mode 100644 .github/workflows/story-data.yml create mode 100644 SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryStepJson.cpp create mode 100644 SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryStepJson.h create mode 100644 SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryStepJson_Tests.cpp create mode 100644 devtools/story-data-tests/CMakeLists.txt create mode 100644 devtools/story-data-tests/README.md diff --git a/.github/workflows/story-data.yml b/.github/workflows/story-data.yml new file mode 100644 index 0000000000..545299ac51 --- /dev/null +++ b/.github/workflows/story-data.yml @@ -0,0 +1,34 @@ +name: Story data codec +on: + pull_request: + workflow_dispatch: +jobs: + native-codec: + strategy: + fail-fast: false + matrix: + os: [ubuntu-latest, macos-latest, windows-latest] + runs-on: ${{ matrix.os }} + steps: + - uses: actions/checkout@v7 + - uses: actions/checkout@v7 + with: + repository: dayfine/PokemonSimulation + # Synthetic contract cases, not an approved map/resource pin. + ref: 866613fa03e5c4a5eb7e57c91b59fafb44fc7ee3 + path: publisher + - uses: actions/setup-python@v6 + with: + python-version: '3.12' + - name: Check the Python reader against the same cases + working-directory: publisher + env: + PYTHONPATH: src + run: python -m unittest pokesim.story.test_checkpoint_wire + - run: cmake -S devtools/story-data-tests -B build-story-data -DCMAKE_BUILD_TYPE=Debug + - run: cmake --build build-story-data --config Debug -j4 + - run: ctest --test-dir build-story-data -C Debug --output-on-failure + - if: runner.os != 'Windows' + run: ./build-story-data/StoryDataTests publisher/data/story/wire-conformance.json + - if: runner.os == 'Windows' + run: ./build-story-data/Debug/StoryDataTests.exe publisher/data/story/wire-conformance.json diff --git a/SerialPrograms/Source/ComputerPrograms/ComputerPrograms_UnitTestRunner.cpp b/SerialPrograms/Source/ComputerPrograms/ComputerPrograms_UnitTestRunner.cpp index 5b8a97836b..e9b1a44ad6 100644 --- a/SerialPrograms/Source/ComputerPrograms/ComputerPrograms_UnitTestRunner.cpp +++ b/SerialPrograms/Source/ComputerPrograms/ComputerPrograms_UnitTestRunner.cpp @@ -78,6 +78,7 @@ UnitTestDatabase make_UNIT_TESTS_ALL(){ Pokemon::add_tests_StoryEvents(ret); Pokemon::add_tests_StorySegments(ret); Pokemon::add_tests_StorySteps(ret); + Pokemon::add_tests_StoryStepJson(ret); NintendoSwitch::add_tests_CheckOnlineDetector(ret); NintendoSwitch::add_tests_FailedToConnectDetector(ret); NintendoSwitch::add_tests_UpdatePopupDetector(ret); diff --git a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_AutoStory_Tests.h b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_AutoStory_Tests.h index 8757fff3fd..1f712fc7ae 100644 --- a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_AutoStory_Tests.h +++ b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_AutoStory_Tests.h @@ -24,6 +24,9 @@ void add_tests_StorySteps(UnitTestDatabase& database); +// Lossless shared story-data wire contract. +void add_tests_StoryStepJson(UnitTestDatabase& database); + } // namespace Pokemon } // namespace PokemonAutomation #endif diff --git a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryStepJson.cpp b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryStepJson.cpp new file mode 100644 index 0000000000..3ee2f51f6d --- /dev/null +++ b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryStepJson.cpp @@ -0,0 +1,355 @@ +/* Story Step JSON + * From: https://github.com/PokemonAutomation/ + */ +#include +#include +#include +#include +#include +#include +#include "Common/Cpp/Exceptions.h" +#include "Common/Cpp/Json/JsonArray.h" +#include "Common/Cpp/Json/JsonObject.h" +#include "Pokemon_StoryStepJson.h" +namespace PokemonAutomation{ +namespace Pokemon{ +namespace{ +constexpr std::array, 15> KINDS{{ + {StoryStepKind::NEW_GAME, "new_game"}, + {StoryStepKind::OPTIONS, "options"}, + {StoryStepKind::ROUTE, "route"}, + {StoryStepKind::LEGS, "legs"}, + {StoryStepKind::STEP, "step"}, + {StoryStepKind::TALK, "talk"}, + {StoryStepKind::ANSWER, "answer"}, + {StoryStepKind::MASH, "scene"}, + {StoryStepKind::BATTLE, "battle"}, + {StoryStepKind::TRAIN, "train"}, + {StoryStepKind::HEAL, "heal"}, + {StoryStepKind::SHOP, "shop"}, + {StoryStepKind::SAVE, "save"}, + {StoryStepKind::READY, "ready"}, + {StoryStepKind::GAME, "game_action"}, +}}; +constexpr std::array, 5> CERTAINTIES{{ + {PoseCertainty::TILE, "tile"}, + {PoseCertainty::COLUMN, "column"}, + {PoseCertainty::ROW, "row"}, + {PoseCertainty::SET, "set"}, + {PoseCertainty::UNKNOWN, "unknown"}, +}}; +constexpr std::array, 4> DIRECTIONS{{ + {Direction::NORTH, "north"}, + {Direction::EAST, "east"}, + {Direction::SOUTH, "south"}, + {Direction::WEST, "west"}, +}}; + +const JsonObject& fields(const JsonValue& value, std::initializer_list keys, std::string_view source){ + const JsonObject& object = value.to_object_throw(std::string(source)); + for (const auto& [key, unused] : object){ + bool known = false; + for (std::string_view allowed : keys){ + known |= key == allowed; + } + if (!known){ + throw ParseException(std::format("{}: unsupported field {}", source, key)); + } + } + return object; +} + +template +Enum read_enum(const std::array, N>& names, const std::string& name, std::string_view source){ + for (const auto& [value, label] : names){ + if (label == name){ + return value; + } + } + throw ParseException(std::format("{}: unsupported value {}", source, name)); +} + +template +std::string enum_name(const std::array, N>& names, Enum value){ + for (const auto& [candidate, label] : names){ + if (candidate == value){ + return std::string(label); + } + } + throw ParseException("Unsupported story enum value."); +} + +int integer(const JsonValue& value, std::string_view source){ + const int64_t number = value.to_integer_throw(std::string(source)); + if (number < std::numeric_limits::min() || number > std::numeric_limits::max()){ + throw ParseException(std::format("{}: coordinate exceeds native int", source)); + } + return (int)number; +} + +size_t count(const JsonValue& value, std::string_view source){ + const int64_t number = value.to_integer_throw(std::string(source)); + if (number < 0 || (uint64_t)number > std::numeric_limits::max()){ + throw ParseException(std::format("{}: count is out of range", source)); + } + return (size_t)number; +} + +JsonValue count_json(size_t value){ + if ((uint64_t)value > (uint64_t)std::numeric_limits::max()){ + throw ParseException("Story count exceeds the wire integer range."); + } + return (uint64_t)value; +} + +JsonArray strings_json(const std::vector& strings){ + JsonArray result; + for (const std::string& value : strings){ + result.push_back(value); + } + return result; +} + +std::vector read_strings(const JsonValue& value, std::string_view source){ + std::vector result; + for (const JsonValue& item : value.to_array_throw(std::string(source))){ + result.push_back(item.to_string_throw(std::string(source))); + } + return result; +} + +JsonArray legs_json(const std::vector& legs){ + JsonArray result; + for (const StoryLeg& leg : legs){ + JsonObject item; + item["direction"] = enum_name(DIRECTIONS, leg.direction); + item["tiles"] = leg.tiles; + result.push_back(std::move(item)); + } + return result; +} + +std::vector read_legs(const JsonValue& value, std::string_view source){ + std::vector result; + for (const JsonValue& item : value.to_array_throw(std::string(source))){ + const JsonObject& row = fields(item, {"direction", "tiles"}, source); + result.push_back({.direction = read_enum(DIRECTIONS, row.get_string_throw("direction"), source), + .tiles = integer(row.get_value_throw("tiles"), source)}); + } + return result; +} + +JsonArray items_json(const std::vector& items){ + JsonArray result; + for (const StoryItem& item : items){ + JsonObject row; + row["item"] = item.item; + row["quantity"] = count_json(item.quantity); + result.push_back(std::move(row)); + } + return result; +} + +std::vector read_items(const JsonValue& value, std::string_view source){ + std::vector result; + for (const JsonValue& item : value.to_array_throw(std::string(source))){ + const JsonObject& row = fields(item, {"item", "quantity"}, source); + result.push_back({.item = row.get_string_throw("item"), .quantity = count(row.get_value_throw("quantity"), source)}); + } + return result; +} +StoryStep read_step_options(StoryStep result, const JsonObject& root, std::string_view source){ + if (const JsonValue* field = root.get_value("fight_wild")){ + result.fight_wild = field->to_boolean_throw(); + } + if (const JsonValue* field = root.get_value("yes")){ + result.yes = field->to_boolean_throw(); + } + if (const JsonValue* field = root.get_value("may_lose")){ + result.may_lose = field->to_boolean_throw(); + } + if (const JsonValue* field = root.get_value("battles")){ + result.battles = count(*field, source); + } + return result; +} + +} // namespace + +JsonValue story_pose_json(const Pose& pose){ + JsonObject result; + result["map"] = pose.map; + result["certainty"] = enum_name(CERTAINTIES, pose.certainty); + JsonObject where; + where["kind"] = "unknown"; + if (pose.where){ + const auto* tiles = dynamic_cast(pose.where.get()); + if (!tiles){ + throw ParseException("Unsupported story Position subtype."); + } + where["kind"] = "tiles"; + JsonArray positions; + for (const TilePos& tile : tiles->tiles){ + JsonArray pair; + pair.push_back(tile.x); pair.push_back(tile.y); + positions.push_back(std::move(pair)); + } + where["tiles"] = std::move(positions); + if (tiles->facing){ + where["facing"] = enum_name(DIRECTIONS, *tiles->facing); + } + } + result["where"] = std::move(where); + return result; +} + +Pose read_story_pose(const JsonValue& value, std::string_view source){ + const JsonObject& root = fields(value, {"map", "certainty", "where"}, source); + Pose result; + result.map = root.get_string_throw("map"); + result.certainty = read_enum(CERTAINTIES, root.get_string_throw("certainty"), source); + const JsonObject& where = fields(root.get_value_throw("where"), {"kind", "tiles", "facing"}, source); + const std::string& kind = where.get_string_throw("kind"); + if (kind == "unknown"){ + if (where.size() != 1){ + throw ParseException("Unknown story position has extra fields."); + } + return result; + } + if (kind != "tiles"){ + throw ParseException("Unsupported story position kind."); + } + std::vector tiles; + for (const JsonValue& item : where.get_array_throw("tiles")){ + const JsonArray& pair = item.to_array_throw(std::string(source)); + if (pair.size() != 2){ + throw ParseException("Story tile needs two coordinates."); + } + tiles.push_back({integer(pair[0], source), integer(pair[1], source)}); + } + std::optional facing; + if (const JsonValue* field = where.get_value("facing")){ + facing = read_enum(DIRECTIONS, field->to_string_throw(), source); + } + result.where = std::make_shared(std::move(tiles), facing); + return result; +} + +JsonValue story_step_json(const StoryStep& step){ + JsonObject result; + result["id"] = step.name; + result["kind"] = enum_name(KINDS, step.kind); + if (!step.why.empty()){ + result["why"] = step.why; + } + if (step.target){ + result["target"] = story_pose_json(*step.target); + } + if (step.direction != Direction::NORTH){ + result["direction"] = enum_name(DIRECTIONS, step.direction); + } + if (!step.legs.empty()){ + result["legs"] = legs_json(step.legs); + } + if (step.fight_wild){ + result["fight_wild"] = true; + } + if (!step.yes){ + result["yes"] = false; + } + if (step.may_lose){ + result["may_lose"] = true; + } + if (step.battles){ + result["battles"] = count_json(step.battles); + } + if (!step.items.empty()){ + result["items"] = items_json(step.items); + } + if (!step.variant.empty()){ + result["variant"] = step.variant; + } + if (!step.skip_if.empty()){ + result["skip_if"] = strings_json(step.skip_if); + } + if (step.pose_after){ + result["declared_after"] = story_pose_json(*step.pose_after); + } + return result; +} + +StoryStep read_story_step(const JsonValue& value, std::string_view source){ + const JsonObject& root = fields(value, {"id", "kind", "why", "target", "direction", "legs", "fight_wild", "yes", + "may_lose", "battles", "items", "variant", "skip_if", "declared_after"}, source); + StoryStep result; + result.name = root.get_string_throw("id"); + if (result.name.empty()){ + throw ParseException("Empty story step id."); + } + result.kind = read_enum(KINDS, root.get_string_throw("kind"), source); + if (const JsonValue* field = root.get_value("why")){ + result.why = field->to_string_throw(); + } + if (const JsonValue* field = root.get_value("target")){ + result.target = read_story_pose(*field, source); + } + if (const JsonValue* field = root.get_value("direction")){ + result.direction = read_enum(DIRECTIONS, field->to_string_throw(), source); + } + if (const JsonValue* field = root.get_value("legs")){ + result.legs = read_legs(*field, source); + } + result = read_step_options(std::move(result), root, source); + if (const JsonValue* field = root.get_value("items")){ + result.items = read_items(*field, source); + } + if (const JsonValue* field = root.get_value("variant")){ + result.variant = field->to_string_throw(); + } + if (const JsonValue* field = root.get_value("skip_if")){ + result.skip_if = read_strings(*field, source); + } + if (const JsonValue* field = root.get_value("declared_after")){ + result.pose_after = read_story_pose(*field, source); + } + return result; +} + +JsonValue story_checkpoint_json(const StoryCheckpoint& checkpoint){ + JsonObject result; + result["id"] = checkpoint.id; + result["title"] = checkpoint.title; + if (checkpoint.start){ + result["start"] = story_pose_json(*checkpoint.start); + } + JsonArray events; + for (const StoryStep& step : checkpoint.steps){ + events.push_back(story_step_json(step)); + } + result["events"] = std::move(events); + return result; +} + +StoryCheckpoint read_story_checkpoint(const JsonValue& value, std::string_view source){ + const JsonObject& root = fields(value, {"id", "title", "start", "events"}, source); + StoryCheckpoint result; + result.id = root.get_string_throw("id"); + if (result.id.empty()){ + throw ParseException("Empty story checkpoint id."); + } + result.title = root.get_string_throw("title"); + if (const JsonValue* start = root.get_value("start")){ + result.start = read_story_pose(*start, source); + } + std::set names; + for (const JsonValue& event : root.get_array_throw("events")){ + StoryStep step = read_story_step(event, source); + if (step.name.empty() || !names.insert(step.name).second){ + throw ParseException("Empty or duplicate story event id."); + } + result.steps.push_back(std::move(step)); + } + return result; +} +} // namespace Pokemon +} // namespace PokemonAutomation diff --git a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryStepJson.h b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryStepJson.h new file mode 100644 index 0000000000..d58fd9828c --- /dev/null +++ b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryStepJson.h @@ -0,0 +1,26 @@ +/* Story Step JSON + * From: https://github.com/PokemonAutomation/ + */ +#ifndef PokemonAutomation_StoryStepJson_H +#define PokemonAutomation_StoryStepJson_H +#include +#include "Common/Cpp/Json/JsonValue.h" +#include "Pokemon_StorySteps.h" +namespace PokemonAutomation{ +namespace Pokemon{ +// Lossless tile-game pose data, including uncertainty and absent position/facing. +// An unsupported Position subtype fails instead of being converted to unknown. +JsonValue story_pose_json(const Pose& pose); +// Read a tile-game pose; malformed fields and unsupported position tags fail. +Pose read_story_pose(const JsonValue& value, std::string_view source); +// Encode every shared step field. This does not bind or execute an action. +JsonValue story_step_json(const StoryStep& step); +// Read the shared step record; unknown fields/kinds and invalid values fail. +StoryStep read_story_step(const JsonValue& value, std::string_view source); +// Encode the common checkpoint; game adapters supply the shared policy/state envelope. +JsonValue story_checkpoint_json(const StoryCheckpoint& checkpoint); +// Read only the common checkpoint record, retaining ordered steps and start belief. +StoryCheckpoint read_story_checkpoint(const JsonValue& value, std::string_view source); +} // namespace Pokemon +} // namespace PokemonAutomation +#endif diff --git a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryStepJson_Tests.cpp b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryStepJson_Tests.cpp new file mode 100644 index 0000000000..021b18f508 --- /dev/null +++ b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryStepJson_Tests.cpp @@ -0,0 +1,150 @@ +/* Story Step JSON Tests + * From: https://github.com/PokemonAutomation/ + */ +#include +#include "Common/Cpp/Exceptions.h" +#include "Common/Cpp/Json/JsonObject.h" +#include "Common/Cpp/Json/JsonArray.h" +#include "Pokemon_StoryStepJson.h" +#ifndef PA_STORY_DATA_STANDALONE +#include "Pokemon_AutoStory_Tests.h" +#endif +namespace PokemonAutomation{ +namespace Pokemon{ +namespace{ +enum class Record{ POSE, STEP, CHECKPOINT }; +struct WireInput{ + std::string_view name; + Record record = Record::STEP; + std::string_view json; +}; +struct WireExpectation{ + std::string_view canonical = {}; + bool rejected = false; +}; +struct WireCase{ + WireInput input; + WireExpectation expectation; +}; +const WireCase CASES[] = { + {.input = {.name = "default fields", .json = R"({"id":"talk","kind":"talk"})"}, .expectation = {.canonical = R"({"id":"talk","kind":"talk"})"}}, + {.input = {.name = "all shared fields", .json = R"({"id":"all","kind":"game_action","why":"source reason","direction":"west","legs":[{"direction":"south","tiles":0}],"fight_wild":true,"yes":false,"may_lose":true,"battles":3,"items":[{"item":"potion","quantity":0}],"variant":"profile","skip_if":["flag"],"target":{"map":"A","certainty":"unknown","where":{"kind":"unknown"}},"declared_after":{"map":"B","certainty":"set","where":{"kind":"tiles","tiles":[[0,0],[1,0]],"facing":"east"}}})"}, .expectation = {.canonical = R"({"id":"all","kind":"game_action","why":"source reason","direction":"west","legs":[{"direction":"south","tiles":0}],"fight_wild":true,"yes":false,"may_lose":true,"battles":3,"items":[{"item":"potion","quantity":0}],"variant":"profile","skip_if":["flag"],"target":{"map":"A","certainty":"unknown","where":{"kind":"unknown"}},"declared_after":{"map":"B","certainty":"set","where":{"kind":"tiles","tiles":[[0,0],[1,0]],"facing":"east"}}})"}}, + {.input = {.name = "unknown facing stays absent", .record = Record::POSE, .json = R"({"map":"M","certainty":"tile","where":{"kind":"tiles","tiles":[[0,0]]}})"}, .expectation = {.canonical = R"({"map":"M","certainty":"tile","where":{"kind":"tiles","tiles":[[0,0]]}})"}}, + {.input = {.name = "empty position differs from no position", .record = Record::POSE, .json = R"({"map":"M","certainty":"unknown","where":{"kind":"tiles","tiles":[]}})"}, .expectation = {.canonical = R"({"map":"M","certainty":"unknown","where":{"kind":"tiles","tiles":[]}})"}}, + {.input = {.name = "ordered checkpoint", .record = Record::CHECKPOINT, .json = R"({"id":"00.05","title":"Parcel","events":[{"id":"first","kind":"route"},{"id":"second","kind":"scene"}]})"}, .expectation = {.canonical = R"({"id":"00.05","title":"Parcel","events":[{"id":"first","kind":"route"},{"id":"second","kind":"scene"}]})"}}, + {.input = {.name = "unknown field", .json = R"({"id":"a","kind":"talk","mystery":0})"}, .expectation = {.rejected = true}}, + {.input = {.name = "unknown action", .json = R"({"id":"a","kind":"magic"})"}, .expectation = {.rejected = true}}, + {.input = {.name = "negative count", .json = R"({"id":"a","kind":"train","battles":-1})"}, .expectation = {.rejected = true}}, + {.input = {.name = "boolean count", .json = R"({"id":"a","kind":"train","battles":false})"}, .expectation = {.rejected = true}}, + {.input = {.name = "wrong bool", .json = R"({"id":"a","kind":"answer","yes":0})"}, .expectation = {.rejected = true}}, + {.input = {.name = "unknown position", .record = Record::POSE, .json = R"({"map":"M","certainty":"unknown","where":{"kind":"gps"}})"}, .expectation = {.rejected = true}}, + {.input = {.name = "bad coordinate", .record = Record::POSE, .json = R"({"map":"M","certainty":"tile","where":{"kind":"tiles","tiles":[[0,true]]}})"}, .expectation = {.rejected = true}}, + {.input = {.name = "duplicate events", .record = Record::CHECKPOINT, .json = R"({"id":"x","title":"X","events":[{"id":"a","kind":"talk"},{"id":"a","kind":"talk"}]})"}, .expectation = {.rejected = true}}, +}; + +JsonValue round_trip(const WireInput& input){ + const JsonValue value = parse_json(std::string(input.json)); + switch (input.record){ + case Record::POSE: return story_pose_json(read_story_pose(value, input.name)); + case Record::STEP: return story_step_json(read_story_step(value, input.name)); + case Record::CHECKPOINT: return story_checkpoint_json(read_story_checkpoint(value, input.name)); + } + throw ParseException("Unknown test record."); +} + +std::string check_case(const WireCase& test){ + try{ + const JsonValue actual = round_trip(test.input); + if (test.expectation.rejected){ + return "Expected rejection, read accepted record."; + } + const JsonValue expected = parse_json(std::string(test.expectation.canonical)); + if (!(actual == expected)){ + return "Expected " + expected.dump() + ", read " + actual.dump(); + } + }catch (const ParseException& error){ + return test.expectation.rejected ? "" : "Unexpected parse failure: " + error.message(); + } + return ""; +} +#ifdef PA_STORY_DATA_STANDALONE +Record record_kind(const std::string& name){ + if (name == "pose"){ + return Record::POSE; + } + if (name == "step"){ + return Record::STEP; + } + if (name == "checkpoint"){ + return Record::CHECKPOINT; + } + throw ParseException("Unsupported shared case record kind."); +} + +int check_shared_file(const std::string& filename){ + const JsonValue document = load_json_file(filename); + const JsonObject& root = document.to_object_throw(filename); + if (root.get_string_throw("format") != "pokesim-story-wire-cases/1"){ + throw ParseException("Unsupported story wire case format."); + } + int failed = 0; + for (const JsonValue& value : root.get_array_throw("cases")){ + const JsonObject& row = value.to_object_throw(filename); + const JsonObject& input = row.get_object_throw("input"); + const JsonObject& expected = row.get_object_throw("expectation"); + const std::string source = input.get_value_throw("value").dump(); + const JsonValue* normalized = expected.get_value("canonical"); + const std::string canonical = normalized ? normalized->dump() : ""; + const JsonValue* rejected = expected.get_value("rejected"); + const WireCase test{ + .input = {.name = input.get_string_throw("name"), .record = record_kind(input.get_string_throw("record")), .json = source}, + .expectation = {.canonical = canonical, .rejected = rejected && rejected->to_boolean_throw()}, + }; + const std::string error = check_case(test); + if (!error.empty()){ + std::cerr << test.input.name << ": " << error << '\n'; + failed++; + } + } + std::cout << "Checked " << root.get_array_throw("cases").size() << " shared story records.\n"; + return failed != 0; +} +#endif + +#ifndef PA_STORY_DATA_STANDALONE +class StoryJsonTest : public UnitTest{ +public: + explicit StoryJsonTest(WireCase test) + : UnitTest("Pokemon::StoryStepJson - " + std::string(test.input.name)), m_case(test){} + virtual UnitTestResult run(Logger&, CancellableScope&) const override{ + const std::string error = check_case(m_case); + return error.empty() ? UnitTestResult(true) : UnitTestResult(error); + } +private: + WireCase m_case; +}; +#endif +} // namespace +#ifndef PA_STORY_DATA_STANDALONE +void add_tests_StoryStepJson(UnitTestDatabase& database){ + for (const WireCase& test : CASES){ + database.add(test); + } +} +#endif +} // namespace Pokemon +} // namespace PokemonAutomation +#ifdef PA_STORY_DATA_STANDALONE +int main(int argc, char** argv){ + if (argc == 2){ + return PokemonAutomation::Pokemon::check_shared_file(argv[1]); + } + int failed = 0; + for (const auto& test : PokemonAutomation::Pokemon::CASES){ + const std::string error = PokemonAutomation::Pokemon::check_case(test); + std::cout << test.input.name << ": " << (error.empty() ? "PASS" : error) << '\n'; + failed += !error.empty(); + } + return failed != 0; +} +#endif diff --git a/SerialPrograms/cmake/SourceFiles.cmake b/SerialPrograms/cmake/SourceFiles.cmake index 117bf52a54..4d83c21a19 100644 --- a/SerialPrograms/cmake/SourceFiles.cmake +++ b/SerialPrograms/cmake/SourceFiles.cmake @@ -1504,6 +1504,9 @@ file(GLOB LIBRARY_SOURCES Source/Pokemon/AutoStory/Pokemon_StorySegments.cpp Source/Pokemon/AutoStory/Pokemon_StorySegments.h Source/Pokemon/AutoStory/Pokemon_StorySegments_Tests.cpp + Source/Pokemon/AutoStory/Pokemon_StoryStepJson.cpp + Source/Pokemon/AutoStory/Pokemon_StoryStepJson.h + Source/Pokemon/AutoStory/Pokemon_StoryStepJson_Tests.cpp Source/Pokemon/AutoStory/Pokemon_StorySteps.cpp Source/Pokemon/AutoStory/Pokemon_StorySteps.h Source/Pokemon/AutoStory/Pokemon_StorySteps_Tests.cpp diff --git a/devtools/story-data-tests/CMakeLists.txt b/devtools/story-data-tests/CMakeLists.txt new file mode 100644 index 0000000000..9bfc400ae3 --- /dev/null +++ b/devtools/story-data-tests/CMakeLists.txt @@ -0,0 +1,33 @@ +# Offline codec checks, no Qt application or controller initialization: +# cmake -S devtools/story-data-tests -B build/story-data-tests +# cmake --build build/story-data-tests -j4 +# ctest --test-dir build/story-data-tests --output-on-failure +cmake_minimum_required(VERSION 3.24) +project(StoryDataTests LANGUAGES CXX) +enable_testing() +get_filename_component(ROOT "../.." ABSOLUTE) +set(STORY "${ROOT}/SerialPrograms/Source/Pokemon/AutoStory") +add_executable(StoryDataTests + "${STORY}/Pokemon_StoryStepJson.cpp" + "${STORY}/Pokemon_StoryStepJson_Tests.cpp" + "${STORY}/Pokemon_TilePose.cpp" + "${ROOT}/SerialPrograms/Source/Pokemon/Navigation/Pokemon_Grid.cpp" + "${ROOT}/Common/Cpp/Exceptions.cpp" + "${ROOT}/Common/Cpp/Json/JsonValue.cpp" + "${ROOT}/Common/Cpp/Json/JsonObject.cpp" + "${ROOT}/Common/Cpp/Json/JsonArray.cpp" + "${ROOT}/Common/Cpp/Json/JsonTools.cpp" + "${ROOT}/Common/Cpp/Filesystem/FileIO.cpp" + "${ROOT}/Common/Cpp/Filesystem/FilePath.cpp" + "${ROOT}/Common/Cpp/Strings/Unicode.cpp") +target_include_directories(StoryDataTests PRIVATE "${ROOT}" "${ROOT}/SerialPrograms/Source") +target_compile_features(StoryDataTests PRIVATE cxx_std_23) +target_compile_definitions(StoryDataTests PRIVATE PA_STORY_DATA_STANDALONE) +if(MSVC) + target_compile_definitions(StoryDataTests PRIVATE _CRT_SECURE_NO_WARNINGS) + target_compile_options(StoryDataTests PRIVATE /W4 /WX) + set_property(SOURCE "${ROOT}/Common/Cpp/Filesystem/FileIO.cpp" APPEND PROPERTY COMPILE_OPTIONS /wd4505) +else() + target_compile_options(StoryDataTests PRIVATE -Wall -Wextra -Werror) +endif() +add_test(NAME StoryData COMMAND StoryDataTests) diff --git a/devtools/story-data-tests/README.md b/devtools/story-data-tests/README.md new file mode 100644 index 0000000000..2c32b00685 --- /dev/null +++ b/devtools/story-data-tests/README.md @@ -0,0 +1,35 @@ +# Shared story-record codec tests + +Run without Qt, controllers, profiles or game saves: + +```sh +cmake -S devtools/story-data-tests -B build/story-data-tests +cmake --build build/story-data-tests -j4 +ctest --test-dir build/story-data-tests --output-on-failure +build/story-data-tests/StoryDataTests /path/to/PokemonSimulation/data/story/wire-conformance.json +``` + +For a multi-configuration generator, add `--config Debug` to the build, +`-C Debug` to CTest and use `build/story-data-tests/Debug/StoryDataTests.exe`. +The same native cases are registered in the application's unit-test runner. + +`Pokemon_StoryStepJson` encodes and reads the common `StoryCheckpoint`, +`StoryStep` and tile-based `Pose` records. It retains action order, alternative +tiles, certainty, absent facing and explicit false/zero values. Unknown fields, +action/position tags and invalid primitive types fail. Native default values +are omitted canonically; encoding does not establish semantic route validity. + +The portable workflow also reads the 31 synthetic conformance cases at +[PokemonSimulation revision 866613f](https://github.com/dayfine/PokemonSimulation/tree/866613fa03e5c4a5eb7e57c91b59fafb44fc7ee3/data/story). +Python reads the same input/expectation records. This fixture revision is a +contract-test dependency, not an approved map-resource revision. + +See the [shared checkpoint contract](https://github.com/dayfine/PokemonSimulation/blob/866613fa03e5c4a5eb7e57c91b59fafb44fc7ee3/docs/story/CHECKPOINT_CONTRACT.md) +for the field boundary and proposed common requirements, state, save/retry and +handoff envelope. Both games can use those policies; their menu/detector/action +bindings remain game specific. + +These are synthetic codec tests, not exports of either game's authored story +tables or captured controller replay. Evaluated FRLG/BDSP table exporters, +policy/state envelope binding and execution parity remain subsequent work. +No gameplay behavior changes here. From 46d000fa82a8e600e1c2d35980609ff0be5cccb6 Mon Sep 17 00:00:00 2001 From: dayfine Date: Sun, 8 Nov 2026 01:16:41 -0800 Subject: [PATCH 012/102] Pokemon AutoStory: once-per-save steps and Outcome::changed_nothing Lands the shared story-engine additions the FRLG AutoStory stack carried on its own copies of Pokemon/AutoStory (frlg/stage2-rng 2148c9615), 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 "/", 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 Claude-Session: https://claude.ai/code/session_013VUubhHeYSMGSSDXZkKZss --- .../Pokemon/AutoStory/Pokemon_StoryEvents.cpp | 5 + .../Pokemon/AutoStory/Pokemon_StoryEvents.h | 6 + .../Pokemon/AutoStory/Pokemon_StorySteps.cpp | 36 ++++++ .../Pokemon/AutoStory/Pokemon_StorySteps.h | 18 +++ .../AutoStory/Pokemon_StorySteps_Tests.cpp | 121 +++++++++++++++++- 5 files changed, 185 insertions(+), 1 deletion(-) diff --git a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryEvents.cpp b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryEvents.cpp index d355460da3..8ef5f5286f 100644 --- a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryEvents.cpp +++ b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryEvents.cpp @@ -68,6 +68,11 @@ Outcome outcome_ok(Pose pose){ outcome.pose = std::move(pose); return outcome; } +Outcome outcome_unchanged(){ + Outcome outcome; + outcome.changed_nothing = true; + return outcome; +} Outcome outcome_failed(std::string failure, std::string detail){ Outcome outcome; outcome.failure = std::move(failure); diff --git a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryEvents.h b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryEvents.h index 0a2673ff38..a1b5ffaa2e 100644 --- a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryEvents.h +++ b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryEvents.h @@ -97,6 +97,10 @@ struct Outcome{ std::string failure; std::string detail; std::optional pose; + // A succeeded action that left the game as it found it: a read, a + // check, a TM the lead already knows. A reload of the same save undoes + // nothing it did. + bool changed_nothing = false; bool succeeded() const; }; @@ -104,6 +108,8 @@ struct Outcome{ Outcome outcome_ok(); // Constructs a successful event outcome updating the run pose. Outcome outcome_ok(Pose pose); +// outcome_ok() with `changed_nothing`. +Outcome outcome_unchanged(); // Constructs a failed event outcome with reason and optional diagnostic detail. Outcome outcome_failed(std::string failure, std::string detail = ""); // "probe_exhausted: 4 rows": the failure and its detail, if any. diff --git a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StorySteps.cpp b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StorySteps.cpp index 01f224f593..3004ba6013 100644 --- a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StorySteps.cpp +++ b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StorySteps.cpp @@ -203,6 +203,38 @@ Checkpoint build_story_checkpoint(const StoryCheckpoint& data, StoryStepExecutor return checkpoint; } +namespace{ + +// `event`, for a once_per_save step known in `prepared` as `key`: skipped +// while `prepared` has it, and added to it when it succeeds changing +// nothing. +void run_once_per_save(Event& event, std::string key, PreparedSteps& prepared){ + event.skip_if.push_back(condition("done_from_this_save", [&prepared, key](RunState&){ + return prepared.contains(key); + })); + event.act = [act = std::move(event.act), &prepared, key](RunState& state) mutable{ + Outcome outcome = act(state); + if (outcome.succeeded() && outcome.changed_nothing){ + prepared.insert(key); + } + return outcome; + }; +} + +} // namespace + +Checkpoint build_story_checkpoint(const StoryCheckpoint& data, StoryStepExecutor& executor, PreparedSteps& prepared){ + Checkpoint checkpoint = build_story_checkpoint(data, executor); + // After "from_save", the events are the steps in order. + const size_t first = data.start ? 1 : 0; + for (size_t c = 0; c < data.steps.size(); c++){ + if (data.steps[c].once_per_save){ + run_once_per_save(checkpoint.events[first + c], data.id + "/" + data.steps[c].name, prepared); + } + } + return checkpoint; +} + namespace{ @@ -253,6 +285,10 @@ std::vector lint_story_checkpoint(const StoryCheckpoint& data){ if (!missing.empty()){ problems.emplace_back(std::format("{} {}: {} {}", where, step.name, story_step_kind_name(step.kind), missing)); } + // skip_if's conditions must all hold; once per save is one more. + if (step.once_per_save && !step.skip_if.empty()){ + problems.emplace_back(std::format("{} {}: once per save with skip_if", where, step.name)); + } } return problems; } diff --git a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StorySteps.h b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StorySteps.h index 60e090cbf8..27aaabad8a 100644 --- a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StorySteps.h +++ b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StorySteps.h @@ -33,6 +33,7 @@ #include #include +#include #include #include #include "CommonFramework/Language.h" @@ -123,6 +124,13 @@ struct StoryStep{ // the game's executor answers (StoryStepExecutor::holds()), run flags // unless the game reads them off the screen. std::vector skip_if; + // Preparation for what follows, done once per save: a TEACH, a check, + // a read. Once it has succeeded and changed nothing + // (Outcome::changed_nothing), the attempts after a reload of the same + // save skip it, so a retry goes from the reload straight to the + // battle. One that changed the game (a TM taught) runs again, as the + // reload undid it. Only with build_story_checkpoint()'s PreparedSteps. + bool once_per_save = false; // Where the step leaves the player, when its action does not say: the // end of a scene that moves the player. std::optional pose_after; @@ -218,6 +226,16 @@ Event story_event(const StoryStep& step, StoryStepExecutor& executor); // game's: it sets the checkpoint's save, or adds a SAVE step. Checkpoint build_story_checkpoint(const StoryCheckpoint& data, StoryStepExecutor& executor); +// The once_per_save steps done from the save the game is on that changed +// nothing, as "/". The game keeps it across reloads and +// empties it when it saves or loads another save. +using PreparedSteps = std::set; + +// As above, and each once_per_save step is skipped while `prepared` has +// it, and added to it when it succeeds changing nothing. `prepared` must +// outlive the checkpoint. +Checkpoint build_story_checkpoint(const StoryCheckpoint& data, StoryStepExecutor& executor, PreparedSteps& prepared); + // Problems an author should fix before running: an empty id, unnamed or // repeated steps, a route or READY without a target, empty legs, a GAME // step without a variant, TRAIN without battles, SHOP without items. diff --git a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StorySteps_Tests.cpp b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StorySteps_Tests.cpp index 6bef5f7e6b..e61a1eeb95 100644 --- a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StorySteps_Tests.cpp +++ b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StorySteps_Tests.cpp @@ -46,6 +46,8 @@ class FakeExecutor : public StoryStepExecutor{ std::vector> poses_seen; // The checkpoints begun, one per attempt. std::vector attempts; + // Game steps by name that change nothing in the game. + std::set unchanged; virtual void begin_attempt(const StoryCheckpoint& data) override{ attempts.push_back(data.id); @@ -99,7 +101,7 @@ class FakeExecutor : public StoryStepExecutor{ virtual Outcome game(RunState& state, const StoryStep& step) override{ trace.push_back(" game " + step.variant); state.flags.insert(step.variant); - return outcome_ok(); + return unchanged.contains(step.name) ? outcome_unchanged() : outcome_ok(); } }; @@ -466,6 +468,115 @@ UnitTestResult test_policy_recovers_in_place(){ return true; } +// A boss's checkpoint: a TEACH of a move the lead knows (changes +// nothing), a TEACH that teaches, both once per save, then the battle, +// lost on the first attempt. The segment's saves empty `prepared`. +struct BossLab{ + StoryCheckpoint table{ + .id = "00.15b", + .title = "the rival", + .start = tile_pose("Cerulean", {{23, 7}}, Direction::NORTH), + .steps = {once("teach_known"), once("teach_new"), make(StoryStepKind::BATTLE, "rival")}, + }; + FakeExecutor executor; + PreparedSteps prepared; + std::vector lines; + + static StoryStep once(std::string name){ + StoryStep step = make(StoryStepKind::GAME, name); + step.variant = name; + step.once_per_save = true; + return step; + } + BossLab(){ + executor.unchanged = {"teach_known"}; + } + Segment segment(){ + Segment segment; + segment.id = "00"; + segment.checkpoints.push_back(CheckpointSpec{ + .id = table.id, .title = table.title, .saves = true, + .build = [this]{ return build_story_checkpoint(table, executor, prepared); }, + }); + return segment; + } + SegmentHooks hooks(){ + SegmentHooks hooks; + hooks.save = [this](RunState&){ + executor.trace.push_back("save"); + prepared.clear(); + return outcome_ok(); + }; + hooks.reload = [this](RunState&){ + executor.trace.push_back("reload"); + return outcome_ok(); + }; + hooks.log = [this](const std::string& line){ lines.push_back(line); }; + return hooks; + } + size_t count(const std::string& item) const{ + return (size_t)std::count(executor.trace.begin(), executor.trace.end(), item); + } +}; + +// A retry after a reload of the same save skips the preparation that +// changed nothing and goes to the battle; the TEACH that taught runs +// again, as the reload undid it. The save at the end empties the memory. +UnitTestResult test_once_per_save_retry(){ + BossLab lab; + StoryStep battle = make(StoryStepKind::BATTLE, "rival"); + battle.may_lose = true; + lab.table.steps.back() = battle; + lab.executor.failures_left = {{"rival", 1}}; + Segment segment = lab.segment(); + SegmentHooks hooks = lab.hooks(); + RunState state; + const SegmentReport report = run_segment(state, segment, SegmentRange{}, SegmentPolicy{}, hooks); + if (!report.completed || report.reloads != 1 || lab.count("GAME teach_known") != 1 + || lab.count("GAME teach_new") != 2 || lab.count("BATTLE rival") != 2 + ){ + return "Expected the known TEACH once, the new one twice, the battle twice:" + joined(lab.executor.trace) + joined(lab.lines); + } + if (!lab.prepared.empty()){ + return "Expected the save to empty the prepared steps."; + } + return true; +} + +// Verify mode: three runs from one save; the preparation that changed +// nothing runs in the first only. +UnitTestResult test_once_per_save_verify(){ + BossLab lab; + StoryStep battle = make(StoryStepKind::BATTLE, "rival"); + battle.may_lose = true; + lab.table.steps.back() = battle; + Segment segment = lab.segment(); + SegmentHooks hooks = lab.hooks(); + RunState state; + const VerifyReport report = verify_checkpoint(state, segment, "00.15b", VerifyPolicy{}, hooks); + if (!report.verified || report.runs != 3 || lab.count("GAME teach_known") != 1 + || lab.count("GAME teach_new") != 3 || lab.count("BATTLE rival") != 3 + ){ + return "Expected the known TEACH once in 3 runs, the new one each run:" + joined(lab.executor.trace) + joined(lab.lines); + } + // Without the memory, every run prepares. + FakeExecutor plain; + plain.unchanged = {"teach_known"}; + Segment without; + without.id = "00"; + without.checkpoints.push_back(CheckpointSpec{ + .id = lab.table.id, .title = "", .saves = true, + .build = [&]{ return build_story_checkpoint(lab.table, plain); }, + }); + RunState again; + verify_checkpoint(again, without, "00.15b", VerifyPolicy{}, hooks); + if (std::count(plain.trace.begin(), plain.trace.end(), "GAME teach_known") != 3){ + return "Expected every run to prepare without PreparedSteps:" + joined(plain.trace); + } + return true; +} + + // The checks level: THOROUGH by default, and what the program sets is // what a step reads. UnitTestResult test_checks_level(){ @@ -718,6 +829,14 @@ const StoryStepTestCase STORY_STEP_CASES[] = { .input = {.name = "policy: recover in place before reloading", .test = test_policy_recovers_in_place}, .expectation = {.description = "applies in-place recovery handler prior to reloading save"}, }, + { + .input = {.name = "once per save: a retry skips what changed nothing", .test = test_once_per_save_retry}, + .expectation = {.description = "skips steps that changed nothing during once per save retry"}, + }, + { + .input = {.name = "once per save: verify runs prepare once", .test = test_once_per_save_verify}, + .expectation = {.description = "executes once per save prepare step only once during verification"}, + }, }; } // namespace From edc3a19ac01d612854246dfbdf7cdf476d0f6820 Mon Sep 17 00:00:00 2001 From: Di Fan <26423504+dayfine@users.noreply.github.com> Date: Sun, 8 Nov 2026 15:59:28 -0800 Subject: [PATCH 013/102] Share authored checkpoint envelopes and embedded resource loading (#266) --- .../ComputerPrograms_UnitTestRunner.cpp | 1 + .../Pokemon_AuthoredCheckpointJson.cpp | 67 +++++++++ .../Pokemon_AuthoredCheckpointJson.h | 53 +++++++ .../Pokemon_AuthoredCheckpointJson_Tests.cpp | 139 ++++++++++++++++++ .../AutoStory/Pokemon_AutoStory_Tests.h | 3 + SerialPrograms/cmake/SourceFiles.cmake | 3 + devtools/story-data-tests/CMakeLists.txt | 22 ++- devtools/story-data-tests/README.md | 2 + 8 files changed, 284 insertions(+), 6 deletions(-) create mode 100644 SerialPrograms/Source/Pokemon/AutoStory/Pokemon_AuthoredCheckpointJson.cpp create mode 100644 SerialPrograms/Source/Pokemon/AutoStory/Pokemon_AuthoredCheckpointJson.h create mode 100644 SerialPrograms/Source/Pokemon/AutoStory/Pokemon_AuthoredCheckpointJson_Tests.cpp diff --git a/SerialPrograms/Source/ComputerPrograms/ComputerPrograms_UnitTestRunner.cpp b/SerialPrograms/Source/ComputerPrograms/ComputerPrograms_UnitTestRunner.cpp index 4792436378..df98fc4df2 100644 --- a/SerialPrograms/Source/ComputerPrograms/ComputerPrograms_UnitTestRunner.cpp +++ b/SerialPrograms/Source/ComputerPrograms/ComputerPrograms_UnitTestRunner.cpp @@ -82,6 +82,7 @@ UnitTestDatabase make_UNIT_TESTS_ALL(){ Pokemon::add_tests_StorySegments(ret); Pokemon::add_tests_StorySteps(ret); Pokemon::add_tests_StoryStepJson(ret); + Pokemon::add_tests_AuthoredCheckpointJson(ret); NintendoSwitch::add_tests_CheckOnlineDetector(ret); NintendoSwitch::add_tests_FailedToConnectDetector(ret); NintendoSwitch::add_tests_UpdatePopupDetector(ret); diff --git a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_AuthoredCheckpointJson.cpp b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_AuthoredCheckpointJson.cpp new file mode 100644 index 0000000000..699ece6df1 --- /dev/null +++ b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_AuthoredCheckpointJson.cpp @@ -0,0 +1,67 @@ +/* Shared Authored Checkpoint JSON + * From: https://github.com/PokemonAutomation/ + */ + +#include +#include +#include "Common/Cpp/Exceptions.h" +#include "Pokemon_StoryStepJson.h" +#include "Pokemon_AuthoredCheckpointJson.h" + +namespace PokemonAutomation{ +namespace Pokemon{ + + +void require_story_json_fields( + const JsonObject& object, std::initializer_list fields, std::string_view source +){ + if (object.size() != fields.size()){ + throw ParseException(std::format("{}: missing or extra authored checkpoint fields.", source)); + } + for (std::string_view field : fields){ + object.get_value_throw(std::string(field), std::string(source)); + } +} + +AuthoredCheckpoint read_authored_checkpoint( + const JsonValue& value, std::string_view expected_game, std::string_view source +){ + const JsonObject& root = value.to_object_throw(std::string(source)); + require_story_json_fields(root, {"format", "game", "checkpoint", "execution"}, source); + if (expected_game.empty() || root.get_string_throw("format") != "pokesim-authored-checkpoint/1" + || root.get_string_throw("game") != expected_game + ){ + throw ParseException(std::format("{}: unsupported authored checkpoint format/game.", source)); + } + return { + .checkpoint = read_story_checkpoint(root.get_value_throw("checkpoint"), source), + .execution = root.get_object_throw("execution", std::string(source)).clone(), + }; +} + +JsonValue authored_checkpoint_json(const StoryCheckpoint& checkpoint, std::string_view game, JsonObject execution){ + if (game.empty()){ + throw ParseException("Authored checkpoint game must not be empty."); + } + JsonObject result; + result["format"] = "pokesim-authored-checkpoint/1"; + result["game"] = std::string(game); + result["checkpoint"] = story_checkpoint_json(checkpoint); + result["execution"] = std::move(execution); + return result; +} + +AuthoredCheckpoint load_authored_checkpoint( + std::span> files, std::string_view file, std::string_view expected_game +){ + for (const auto& [name, text] : files){ + if (name == file){ + return read_authored_checkpoint(parse_json(text), expected_game, file); + } + } + throw InternalProgramError(nullptr, PA_CURRENT_FUNCTION, "Authored checkpoint is not embedded: " + std::string(file)); +} + + +} // namespace Pokemon +} // namespace PokemonAutomation diff --git a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_AuthoredCheckpointJson.h b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_AuthoredCheckpointJson.h new file mode 100644 index 0000000000..1b1be213dd --- /dev/null +++ b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_AuthoredCheckpointJson.h @@ -0,0 +1,53 @@ +/* Shared Authored Checkpoint JSON + * From: https://github.com/PokemonAutomation/ + */ + +#ifndef PokemonAutomation_AuthoredCheckpointJson_H +#define PokemonAutomation_AuthoredCheckpointJson_H + +#include +#include +#include +#include +#include +#include "Common/Cpp/Json/JsonObject.h" +#include "Pokemon_StorySteps.h" + +namespace PokemonAutomation{ +namespace Pokemon{ + + +// Common story data and an owned execution object for the game adapter to validate. +// Parsing this document does not validate game policies or bind/execute actions. +struct AuthoredCheckpoint{ + StoryCheckpoint checkpoint; + JsonObject execution; +}; + +// Require exactly these fields, including fields whose value is null/zero/false. +// Missing/unknown fields throw ParseException with the document source. +void require_story_json_fields( + const JsonObject& object, std::initializer_list fields, std::string_view source +); + +// Read the strict authored envelope and common checkpoint for expected_game. +// The game adapter must still validate execution fields and values before use. +AuthoredCheckpoint read_authored_checkpoint( + const JsonValue& value, std::string_view expected_game, std::string_view source +); + +// Encode the authored envelope; execution is supplied by the game adapter. +// This does not encode game bookkeeping or the legacy native-export envelope. +JsonValue authored_checkpoint_json(const StoryCheckpoint& checkpoint, std::string_view game, JsonObject execution); + +// Find and parse an embedded (filename without .json, text) resource for this game. +// Missing resources throw InternalProgramError; malformed documents throw ParseException. +AuthoredCheckpoint load_authored_checkpoint( + std::span> files, std::string_view file, std::string_view expected_game +); + + +} // namespace Pokemon +} // namespace PokemonAutomation + +#endif diff --git a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_AuthoredCheckpointJson_Tests.cpp b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_AuthoredCheckpointJson_Tests.cpp new file mode 100644 index 0000000000..7aba0e12f4 --- /dev/null +++ b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_AuthoredCheckpointJson_Tests.cpp @@ -0,0 +1,139 @@ +/* Shared Authored Checkpoint JSON Tests + * From: https://github.com/PokemonAutomation/ + */ + +#include +#include +#include "Common/Cpp/Exceptions.h" +#include "Pokemon_AuthoredCheckpointJson.h" +#include "Pokemon_StoryStepJson.h" +#ifndef PA_STORY_DATA_STANDALONE +#include "Pokemon_AutoStory_Tests.h" +#endif + +namespace PokemonAutomation{ +namespace Pokemon{ +namespace{ + +// Documents intentionally contain no game headers or native bookkeeping. +const std::string FRLG = R"({"format":"pokesim-authored-checkpoint/1","game":"frlg","checkpoint":{"id":"00.05","title":"Parcel","events":[{"id":"first","kind":"route"},{"id":"second","kind":"scene"}]},"execution":{"menu":"before_pokedex"}})"; +const std::string BDSP = R"({"format":"pokesim-authored-checkpoint/1","game":"bdsp","checkpoint":{"id":"01.03","title":"Mine","events":[{"id":"roark","kind":"talk"}]},"execution":{"on_failure":"reload_and_retry","saves_in":"Oreburgh City"}})"; + +enum class Failure{ NONE, PARSE, MISSING_RESOURCE }; + +struct AuthoredInput{ + std::string name; + std::string json; + std::string game = "frlg"; + bool resource = false; + std::string file = "plan"; +}; + +struct AuthoredExpectation{ + std::string checkpoint = "00.05"; + std::string execution = R"({"menu":"before_pokedex"})"; + std::vector events = {"first", "second"}; + Failure failure = Failure::NONE; +}; + +struct AuthoredCase{ + AuthoredInput input; + AuthoredExpectation expectation; +}; + +const AuthoredCase CASES[] = { + {.input = {.name = "FRLG envelope", .json = FRLG}, .expectation = {}}, + {.input = {.name = "BDSP embedded resource", .json = BDSP, .game = "bdsp", .resource = true}, .expectation = { + .checkpoint = "01.03", .execution = R"({"on_failure":"reload_and_retry","saves_in":"Oreburgh City"})", .events = {"roark"}}}, + {.input = {.name = "FRLG embedded resource", .json = FRLG, .resource = true}, .expectation = {}}, + {.input = {.name = "wrong game", .json = BDSP}, .expectation = {.failure = Failure::PARSE}}, + {.input = {.name = "empty expected game", .json = FRLG, .game = ""}, .expectation = {.failure = Failure::PARSE}}, + {.input = {.name = "missing resource", .json = FRLG, .resource = true, .file = "absent"}, .expectation = {.failure = Failure::MISSING_RESOURCE}}, + {.input = {.name = "invalid embedded JSON", .json = "{", .resource = true}, .expectation = {.failure = Failure::PARSE}}, + {.input = {.name = "wrong format", .json = R"({"format":"future","game":"frlg","checkpoint":{},"execution":{}})"}, .expectation = {.failure = Failure::PARSE}}, + {.input = {.name = "missing execution", .json = R"({"format":"pokesim-authored-checkpoint/1","game":"frlg","checkpoint":{}})"}, .expectation = {.failure = Failure::PARSE}}, + {.input = {.name = "same count wrong field", .json = R"({"format":"pokesim-authored-checkpoint/1","game":"frlg","checkpoint":{},"extra":{}})"}, .expectation = {.failure = Failure::PARSE}}, + {.input = {.name = "extra envelope field", .json = R"({"format":"pokesim-authored-checkpoint/1","game":"frlg","checkpoint":{},"execution":{},"extra":0})"}, .expectation = {.failure = Failure::PARSE}}, + {.input = {.name = "execution must be object", .json = R"({"format":"pokesim-authored-checkpoint/1","game":"frlg","checkpoint":{"id":"x","title":"X","events":[]},"execution":false})"}, .expectation = {.failure = Failure::PARSE}}, + {.input = {.name = "invalid common action", .json = R"({"format":"pokesim-authored-checkpoint/1","game":"frlg","checkpoint":{"id":"x","title":"X","events":[{"id":"bad","kind":"magic"}]},"execution":{}})"}, .expectation = {.failure = Failure::PARSE}}, + {.input = {.name = "execution stays game owned", .json = R"({"format":"pokesim-authored-checkpoint/1","game":"future","checkpoint":{"id":"x","title":"X","events":[]},"execution":{"zero":0,"false":false,"null":null}})", .game = "future"}, .expectation = { + .checkpoint = "x", .execution = R"({"zero":0,"false":false,"null":null})", .events = {}}}, +}; + +std::string check_loaded(const AuthoredCheckpoint& actual, const AuthoredCase& test){ + if (test.expectation.failure != Failure::NONE){ + return "Expected rejection, read accepted authored checkpoint."; + } + if (actual.checkpoint.id != test.expectation.checkpoint){ + return "Expected checkpoint " + test.expectation.checkpoint + ", read " + actual.checkpoint.id; + } + if (!(JsonValue(actual.execution.clone()) == parse_json(test.expectation.execution))){ + return "Expected execution " + test.expectation.execution + ", read " + actual.execution.dump(); + } + std::vector events; + for (const StoryStep& step : actual.checkpoint.steps){ + events.push_back(step.name); + } + if (events != test.expectation.events){ + return "Expected authored event IDs in their original order."; + } + const JsonValue encoded = authored_checkpoint_json(actual.checkpoint, test.input.game, actual.execution.clone()); + const AuthoredCheckpoint reread = read_authored_checkpoint(encoded, test.input.game, test.input.name); + if (!(story_checkpoint_json(actual.checkpoint) == story_checkpoint_json(reread.checkpoint)) || actual.execution != reread.execution){ + return "Expected checkpoint and execution to survive the shared writer/reader round trip."; + } + return ""; +} + +std::string check_case(const AuthoredCase& test){ + try{ + const std::vector> files = {{"plan", test.input.json}}; + const AuthoredCheckpoint actual = test.input.resource + ? load_authored_checkpoint(files, test.input.file, test.input.game) + : read_authored_checkpoint(parse_json(test.input.json), test.input.game, test.input.name); + return check_loaded(actual, test); + }catch (const ParseException& error){ + return test.expectation.failure == Failure::PARSE ? "" : "Unexpected parse failure: " + error.message(); + }catch (const InternalProgramError& error){ + return test.expectation.failure == Failure::MISSING_RESOURCE ? "" : "Unexpected resource failure: " + error.message(); + } +} + +#ifndef PA_STORY_DATA_STANDALONE +class AuthoredJsonTest : public UnitTest{ +public: + explicit AuthoredJsonTest(AuthoredCase test) + : UnitTest("Pokemon::AuthoredCheckpointJson - " + test.input.name), m_case(std::move(test)){} + virtual UnitTestResult run(Logger&, CancellableScope&) const override{ + const std::string error = check_case(m_case); + return error.empty() ? UnitTestResult(true) : UnitTestResult(error); + } +private: + AuthoredCase m_case; +}; +#endif + +} // namespace + +#ifndef PA_STORY_DATA_STANDALONE +void add_tests_AuthoredCheckpointJson(UnitTestDatabase& database){ + for (const AuthoredCase& test : CASES){ + database.add(test); + } +} +#endif + +} // namespace Pokemon +} // namespace PokemonAutomation + +#ifdef PA_STORY_DATA_STANDALONE +int main(){ + int failed = 0; + for (const auto& test : PokemonAutomation::Pokemon::CASES){ + const std::string error = PokemonAutomation::Pokemon::check_case(test); + std::cout << test.input.name << ": " << (error.empty() ? "PASS" : error) << '\n'; + failed += !error.empty(); + } + return failed != 0; +} +#endif diff --git a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_AutoStory_Tests.h b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_AutoStory_Tests.h index 1f712fc7ae..5d0bbe1172 100644 --- a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_AutoStory_Tests.h +++ b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_AutoStory_Tests.h @@ -27,6 +27,9 @@ void add_tests_StorySteps(UnitTestDatabase& database); // Lossless shared story-data wire contract. void add_tests_StoryStepJson(UnitTestDatabase& database); +// Shared authored envelope, game identity and embedded-resource loading. +void add_tests_AuthoredCheckpointJson(UnitTestDatabase& database); + } // namespace Pokemon } // namespace PokemonAutomation #endif diff --git a/SerialPrograms/cmake/SourceFiles.cmake b/SerialPrograms/cmake/SourceFiles.cmake index dc08917bb4..7be1fec8ae 100644 --- a/SerialPrograms/cmake/SourceFiles.cmake +++ b/SerialPrograms/cmake/SourceFiles.cmake @@ -1504,6 +1504,9 @@ file(GLOB LIBRARY_SOURCES Source/Pokemon/AutoStory/Pokemon_StorySegments.cpp Source/Pokemon/AutoStory/Pokemon_StorySegments.h Source/Pokemon/AutoStory/Pokemon_StorySegments_Tests.cpp + Source/Pokemon/AutoStory/Pokemon_AuthoredCheckpointJson.cpp + Source/Pokemon/AutoStory/Pokemon_AuthoredCheckpointJson.h + Source/Pokemon/AutoStory/Pokemon_AuthoredCheckpointJson_Tests.cpp Source/Pokemon/AutoStory/Pokemon_StoryStepJson.cpp Source/Pokemon/AutoStory/Pokemon_StoryStepJson.h Source/Pokemon/AutoStory/Pokemon_StoryStepJson_Tests.cpp diff --git a/devtools/story-data-tests/CMakeLists.txt b/devtools/story-data-tests/CMakeLists.txt index 9bfc400ae3..978db4f6d0 100644 --- a/devtools/story-data-tests/CMakeLists.txt +++ b/devtools/story-data-tests/CMakeLists.txt @@ -20,14 +20,24 @@ add_executable(StoryDataTests "${ROOT}/Common/Cpp/Filesystem/FileIO.cpp" "${ROOT}/Common/Cpp/Filesystem/FilePath.cpp" "${ROOT}/Common/Cpp/Strings/Unicode.cpp") -target_include_directories(StoryDataTests PRIVATE "${ROOT}" "${ROOT}/SerialPrograms/Source") -target_compile_features(StoryDataTests PRIVATE cxx_std_23) -target_compile_definitions(StoryDataTests PRIVATE PA_STORY_DATA_STANDALONE) +# Reuse the Qt/controller-free support sources; each codec has its own test main. +get_target_property(STORY_DATA_SOURCES StoryDataTests SOURCES) +list(REMOVE_ITEM STORY_DATA_SOURCES "${STORY}/Pokemon_StoryStepJson_Tests.cpp") +add_executable(AuthoredCheckpointTests ${STORY_DATA_SOURCES} + "${STORY}/Pokemon_AuthoredCheckpointJson.cpp" + "${STORY}/Pokemon_AuthoredCheckpointJson_Tests.cpp") + +foreach(TEST_TARGET IN ITEMS StoryDataTests AuthoredCheckpointTests) +target_include_directories(${TEST_TARGET} PRIVATE "${ROOT}" "${ROOT}/SerialPrograms/Source") +target_compile_features(${TEST_TARGET} PRIVATE cxx_std_23) +target_compile_definitions(${TEST_TARGET} PRIVATE PA_STORY_DATA_STANDALONE) if(MSVC) - target_compile_definitions(StoryDataTests PRIVATE _CRT_SECURE_NO_WARNINGS) - target_compile_options(StoryDataTests PRIVATE /W4 /WX) + target_compile_definitions(${TEST_TARGET} PRIVATE _CRT_SECURE_NO_WARNINGS) + target_compile_options(${TEST_TARGET} PRIVATE /W4 /WX) set_property(SOURCE "${ROOT}/Common/Cpp/Filesystem/FileIO.cpp" APPEND PROPERTY COMPILE_OPTIONS /wd4505) else() - target_compile_options(StoryDataTests PRIVATE -Wall -Wextra -Werror) + target_compile_options(${TEST_TARGET} PRIVATE -Wall -Wextra -Werror) endif() +endforeach() add_test(NAME StoryData COMMAND StoryDataTests) +add_test(NAME AuthoredCheckpoint COMMAND AuthoredCheckpointTests) diff --git a/devtools/story-data-tests/README.md b/devtools/story-data-tests/README.md index 2c32b00685..310cea3ea3 100644 --- a/devtools/story-data-tests/README.md +++ b/devtools/story-data-tests/README.md @@ -33,3 +33,5 @@ These are synthetic codec tests, not exports of either game's authored story tables or captured controller replay. Evaluated FRLG/BDSP table exporters, policy/state envelope binding and execution parity remain subsequent work. No gameplay behavior changes here. + +The same CTest command also runs `AuthoredCheckpointTests`: shared authored-envelope parsing/writing and embedded-resource lookup for FRLG, BDSP, and opaque future game settings. Game adapters must validate their own execution object before running anything. The shared codec does not interpret FRLG menus, BDSP save-card policy, native bookkeeping, or controller evidence. From f01947b24a622f64d96cf7c57adcae30db4b7ed2 Mon Sep 17 00:00:00 2001 From: dayfine Date: Sun, 8 Nov 2026 22:31:35 -0800 Subject: [PATCH 014/102] AutoStory: shared screen events and the judgements over them A game-agnostic vocabulary of what a story step sees (fades, location banner, dialog and choice boxes, interact prompt, battle start/end, player can move, screen still), an observer interface a game implements with its own detectors, and a run_until watcher form that records events and stops on chosen ones. The warp judgement (WarpSeen, fade_of) and the TalkOver judge from BDSP's #284/#289 move here, expressed over the events. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_013VUubhHeYSMGSSDXZkKZss --- .../ComputerPrograms_UnitTestRunner.cpp | 1 + .../AutoStory/Pokemon_AutoStory_Tests.h | 2 + .../Pokemon/AutoStory/Pokemon_SceneJudges.cpp | 84 +++++++ .../Pokemon/AutoStory/Pokemon_SceneJudges.h | 99 ++++++++ .../AutoStory/Pokemon_ScreenEvents.cpp | 132 ++++++++++ .../Pokemon/AutoStory/Pokemon_ScreenEvents.h | 171 +++++++++++++ .../AutoStory/Pokemon_ScreenEvents_Tests.cpp | 235 ++++++++++++++++++ SerialPrograms/cmake/SourceFiles.cmake | 5 + 8 files changed, 729 insertions(+) create mode 100644 SerialPrograms/Source/Pokemon/AutoStory/Pokemon_SceneJudges.cpp create mode 100644 SerialPrograms/Source/Pokemon/AutoStory/Pokemon_SceneJudges.h create mode 100644 SerialPrograms/Source/Pokemon/AutoStory/Pokemon_ScreenEvents.cpp create mode 100644 SerialPrograms/Source/Pokemon/AutoStory/Pokemon_ScreenEvents.h create mode 100644 SerialPrograms/Source/Pokemon/AutoStory/Pokemon_ScreenEvents_Tests.cpp diff --git a/SerialPrograms/Source/ComputerPrograms/ComputerPrograms_UnitTestRunner.cpp b/SerialPrograms/Source/ComputerPrograms/ComputerPrograms_UnitTestRunner.cpp index df98fc4df2..2257d00254 100644 --- a/SerialPrograms/Source/ComputerPrograms/ComputerPrograms_UnitTestRunner.cpp +++ b/SerialPrograms/Source/ComputerPrograms/ComputerPrograms_UnitTestRunner.cpp @@ -78,6 +78,7 @@ UnitTestDatabase make_UNIT_TESTS_ALL(){ Pokemon::add_tests_MapData(ret); Pokemon::add_tests_RuntimeMap(ret); Pokemon::add_tests_RouteLog(ret); + Pokemon::add_tests_ScreenEvents(ret); Pokemon::add_tests_StoryEvents(ret); Pokemon::add_tests_StorySegments(ret); Pokemon::add_tests_StorySteps(ret); diff --git a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_AutoStory_Tests.h b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_AutoStory_Tests.h index 5d0bbe1172..237cd643d7 100644 --- a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_AutoStory_Tests.h +++ b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_AutoStory_Tests.h @@ -15,6 +15,8 @@ namespace PokemonAutomation{ namespace Pokemon{ +// Registers unit tests for the shared screen events and the judgements over them. +void add_tests_ScreenEvents(UnitTestDatabase& database); // Registers unit tests for story event sequencing and execution. void add_tests_StoryEvents(UnitTestDatabase& database); // Registers unit tests for story segment running, verification, and branching. diff --git a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_SceneJudges.cpp b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_SceneJudges.cpp new file mode 100644 index 0000000000..1c8aaa01c8 --- /dev/null +++ b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_SceneJudges.cpp @@ -0,0 +1,84 @@ +/* Scene Judges + * + * From: https://github.com/PokemonAutomation/ + * + */ + +#include "Pokemon_SceneJudges.h" + +namespace PokemonAutomation{ +namespace Pokemon{ + + +void WarpSeen::see(const ScreenEvents& events, const std::string& banner_read){ + if (fade == WarpFade::NONE){ + fade = events.fade(); + } + if (banner.empty() && events.has(ScreenEvent::LOCATION_BANNER)){ + banner = banner_read; + } +} + +std::string describe(const WarpSeen& seen){ + if (!seen.any()){ + return "nothing"; + } + std::string out = seen.fade == WarpFade::NONE ? "" : warp_fade_name(seen.fade); + if (!seen.banner.empty()){ + out += (out.empty() ? "banner \"" : ", banner \"") + seen.banner + "\""; + } + return out; +} + + +SceneMove TalkOver::look(const ScreenEvents& look, WallClock now){ + if (look.has(ScreenEvent::BATTLE_STARTED)){ + m_quiet_since = WallClock::max(); + m_calm_since = WallClock::max(); + return SceneMove::BATTLE; + } + if (look.fade() != WarpFade::NONE){ + m_fade = look.fade(); + } + m_banner |= look.has(ScreenEvent::LOCATION_BANNER); + const bool box = look.has(ScreenEvent::DIALOG_BOX); + const bool calm = !box && look.has(ScreenEvent::PLAYER_CAN_MOVE) && warped(); + const bool quiet = calm && look.has(ScreenEvent::SCREEN_STILL); + if (!calm){ + m_calm_since = WallClock::max(); + }else if (m_calm_since == WallClock::max()){ + m_calm_since = now; + } + if (!quiet){ + m_quiet_since = WallClock::max(); + }else if (m_quiet_since == WallClock::max()){ + m_quiet_since = now; + } + const bool over = + (quiet && now - m_quiet_since >= TALK_OVER_QUIET) || + (calm && now - m_calm_since >= TALK_OVER_CALM); + if (over && m_rule.end_on_quiet){ + return SceneMove::DONE; + } + return box ? SceneMove::NEXT : SceneMove::B; +} + +bool TalkOver::warped() const{ + return !m_rule.warp || m_fade != WarpFade::NONE || m_banner; +} + +std::string TalkOver::describe() const{ + if (m_fade == WarpFade::NONE && !m_banner){ + return "no fade or banner"; + } + std::string out = m_fade == WarpFade::NONE ? "" : warp_fade_name(m_fade); + if (m_banner){ + out += out.empty() ? "banner read" : ", banner read"; + } + return out; +} + + + +} // namespace Pokemon +} // namespace PokemonAutomation diff --git a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_SceneJudges.h b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_SceneJudges.h new file mode 100644 index 0000000000..1c7ee14800 --- /dev/null +++ b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_SceneJudges.h @@ -0,0 +1,99 @@ +/* Scene Judges + * + * From: https://github.com/PokemonAutomation/ + * + * Judgements a story step makes from screen events (Pokemon_ScreenEvents.h) + * over time, not from one look (#268's design note): a warp is a fade or + * the banner of the map arrived on, and a talk or a scene is over when the + * overworld has been quiet for a while. Pure: tests drive them with + * scripted scenes, and every game shares them. + * + */ + +#ifndef PokemonAutomation_Pokemon_SceneJudges_H +#define PokemonAutomation_Pokemon_SceneJudges_H + +#include +#include "Common/Cpp/Time.h" +#include "Pokemon_ScreenEvents.h" + +namespace PokemonAutomation{ +namespace Pokemon{ + + +// What a walk or a step saw of a warp (#268): a fade or the location +// banner of the map arrived on. Either one alone is the warp. +struct WarpSeen{ + WarpFade fade = WarpFade::NONE; + // The banner read, "" if none. + std::string banner = {}; + + bool any() const{ + return fade != WarpFade::NONE || !banner.empty(); + } + // Notes a frame's events: its fade, and `banner_read` when it shows + // LOCATION_BANNER. The first of each counts. + void see(const ScreenEvents& events, const std::string& banner_read = ""); +}; +// How it was seen, for the log: a black fade, banner "Route 203". +std::string describe(const WarpSeen& seen); + + +// What to do after a look. +enum class SceneMove{ + NEXT, // A box shows: press the talk's button. + B, // No box: press B. It never starts a talk on the overworld + // (A would, and answers Yes on a prompt). + BATTLE, // A battle started. + DONE, // The talk or scene is over. +}; + +// What ends a talk-over, besides the quiet. +struct TalkOverRule{ + // A map change must come first: a fade or the banner. Only the quiet + // after it counts: r30's scene went quiet for 5 s before the fade home. + bool warp = false; + // False when a battle is to follow (a trainer's lines pause for more + // than 4 s before it, r210d): no quiet ends the talk then. + bool end_on_quiet = true; +}; + +// The overworld with no box and a still screen this long ends it: a scene +// pauses while someone walks off (Dawn and Barry after Rowan leaves, r23), +// a scripted walk-in ran 5 s with no text before Mom spoke (r31), and +// Roark's badge speech pauses for the fanfare (lab-B 2026-10-31 09:45 and +// 2026-11-08 15:06). The clock is the last look that was not quiet. +constexpr Milliseconds TALK_OVER_QUIET = Milliseconds(5000); +// The overworld with no box this long ends it, still or not: wanderers or +// grass can keep the screen from ever being still. +constexpr Milliseconds TALK_OVER_CALM = Milliseconds(15000); + +// When a talk or a scene is over, from looks alone. A look is a frame's +// events: DIALOG_BOX, PLAYER_CAN_MOVE, SCREEN_STILL, a fade, +// LOCATION_BANNER (the expected map's) and BATTLE_STARTED are read. +class TalkOver{ +public: + explicit TalkOver(TalkOverRule rule = {}) + : m_rule(rule) + {} + + SceneMove look(const ScreenEvents& look, WallClock now); + + // Whether the warp the rule asks for has shown (true without one). + bool warped() const; + // What it has seen, for the log: "black fade, banner read". + std::string describe() const; + +private: + TalkOverRule m_rule; + WarpFade m_fade = WarpFade::NONE; + bool m_banner = false; + WallClock m_quiet_since = WallClock::max(); + WallClock m_calm_since = WallClock::max(); +}; + + + +} // namespace Pokemon +} // namespace PokemonAutomation +#endif diff --git a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_ScreenEvents.cpp b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_ScreenEvents.cpp new file mode 100644 index 0000000000..4ee56d206f --- /dev/null +++ b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_ScreenEvents.cpp @@ -0,0 +1,132 @@ +/* Screen Events + * + * From: https://github.com/PokemonAutomation/ + * + */ + +#include "CommonFramework/ImageTools/ImageBoxes.h" +#include "CommonFramework/ImageTypes/ImageRGB32.h" +#include "Pokemon_ScreenEvents.h" + +namespace PokemonAutomation{ +namespace Pokemon{ + + +const char* screen_event_name(ScreenEvent event){ + switch (event){ + case ScreenEvent::FADE_BLACK: return "black fade"; + case ScreenEvent::FADE_WHITE: return "white fade"; + case ScreenEvent::LOCATION_BANNER: return "location banner"; + case ScreenEvent::DIALOG_BOX: return "dialog box"; + case ScreenEvent::CHOICE_BOX: return "choice box"; + case ScreenEvent::INTERACT_PROMPT: return "interact prompt"; + case ScreenEvent::BATTLE_STARTED: return "battle started"; + case ScreenEvent::BATTLE_ENDED: return "battle ended"; + case ScreenEvent::PLAYER_CAN_MOVE: return "player can move"; + case ScreenEvent::SCREEN_STILL: return "screen still"; + } + return "?"; +} + +const char* warp_fade_name(WarpFade fade){ + switch (fade){ + case WarpFade::NONE: return "no fade"; + case WarpFade::BLACK: return "black fade"; + case WarpFade::WHITE: return "white fade"; + } + return "?"; +} + + +ScreenEvents::ScreenEvents(std::initializer_list events){ + for (ScreenEvent event : events){ + set(event); + } +} +void ScreenEvents::set(ScreenEvent event, bool on){ + if (on){ + m_bits |= bit(event); + }else{ + m_bits &= ~bit(event); + } +} +void ScreenEvents::add_fade(WarpFade fade){ + switch (fade){ + case WarpFade::NONE: + return; + case WarpFade::BLACK: + set(ScreenEvent::FADE_BLACK); + return; + case WarpFade::WHITE: + set(ScreenEvent::FADE_WHITE); + return; + } +} +WarpFade ScreenEvents::fade() const{ + if (has(ScreenEvent::FADE_BLACK)){ + return WarpFade::BLACK; + } + if (has(ScreenEvent::FADE_WHITE)){ + return WarpFade::WHITE; + } + return WarpFade::NONE; +} +ScreenEvents ScreenEvents::from_bits(uint32_t bits){ + ScreenEvents out; + out.m_bits = bits & ((uint32_t(1) << SCREEN_EVENT_COUNT) - 1); + return out; +} +std::string ScreenEvents::describe() const{ + std::string out; + for (size_t c = 0; c < SCREEN_EVENT_COUNT; c++){ + const ScreenEvent event = (ScreenEvent)c; + if (!has(event)){ + continue; + } + if (!out.empty()){ + out += ", "; + } + out += screen_event_name(event); + } + return out.empty() ? "nothing" : out; +} + + +WarpFade fade_of(const ImageStats& middle){ + if (middle.stddev.sum() > FADE_MAX_STDDEV_SUM){ + return WarpFade::NONE; + } + const double sum = middle.average.sum(); + return sum <= FADE_MAX_DARK_SUM ? WarpFade::BLACK : sum >= FADE_MIN_WHITE_SUM ? WarpFade::WHITE : WarpFade::NONE; +} +WarpFade fade_of_screen(const ImageViewRGB32& screen){ + return fade_of(image_stats(extract_box_reference(screen, ImageFloatBox(0.1, 0.1, 0.8, 0.8)))); +} + + +ScreenEventWatcher::ScreenEventWatcher(ScreenEventObserver& observer, ScreenEvents stop_on) + : VisualInferenceCallback("ScreenEventWatcher") + , m_observer(observer) + , m_stop_on(stop_on) +{} +void ScreenEventWatcher::make_overlays(VideoOverlaySet& items) const{ + m_observer.make_overlays(items); +} +bool ScreenEventWatcher::process_frame(const VideoSnapshot& frame){ + const ScreenEvents events = m_observer.observe(frame, frame.timestamp); + m_seen.fetch_or(events.bits(), std::memory_order_acq_rel); + if (!events.any_of(m_stop_on)){ + return false; + } + m_stopped_on.store(events.bits(), std::memory_order_release); + return true; +} +void ScreenEventWatcher::reset(){ + m_seen.store(0, std::memory_order_release); + m_stopped_on.store(0, std::memory_order_release); +} + + + +} // namespace Pokemon +} // namespace PokemonAutomation diff --git a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_ScreenEvents.h b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_ScreenEvents.h new file mode 100644 index 0000000000..a588013fd6 --- /dev/null +++ b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_ScreenEvents.h @@ -0,0 +1,171 @@ +/* Screen Events + * + * From: https://github.com/PokemonAutomation/ + * + * What a story step can see on the screen, in words every game shares: a + * fade, a location banner, a dialogue box, a battle starting. Each game + * implements ScreenEventObserver with its own detectors; the judgements + * built on these events (Pokemon_SceneJudges.h) are then the same for all + * of them. + * + * An observer runs during a controller action as a ScreenEventWatcher + * (a VisualInferenceCallback for run_until), or is asked frame by frame. + * + */ + +#ifndef PokemonAutomation_Pokemon_ScreenEvents_H +#define PokemonAutomation_Pokemon_ScreenEvents_H + +#include +#include +#include +#include +#include "Common/Cpp/Time.h" +#include "CommonFramework/ImageTools/ImageStats.h" +#include "CommonFramework/ImageTypes/ImageViewRGB32.h" +#include "CommonFramework/VideoPipeline/VideoFeed.h" +#include "CommonTools/InferenceCallbacks/VisualInferenceCallback.h" + +namespace PokemonAutomation{ +namespace Pokemon{ + + +// One thing a frame shows. A game reports the ones its detectors can see. +enum class ScreenEvent : uint8_t{ + FADE_BLACK, // A uniform dark screen: a door, a cave mouth, a scene cut. + FADE_WHITE, // A uniform white screen: a cave exit. + LOCATION_BANNER, // A location banner. An observer given an expected + // map reports only that map's. + DIALOG_BOX, // A dialogue box. + CHOICE_BOX, // A choice (Yes/No, a menu of answers). + INTERACT_PROMPT, // A button prompt to interact ("A Talk"). + BATTLE_STARTED, // A battle shows (its menu, its HUD or its opening). + BATTLE_ENDED, // A battle's closing screen. + PLAYER_CAN_MOVE, // The overworld with the player in control. + SCREEN_STILL, // The screen barely changed since the frame before. +}; +constexpr size_t SCREEN_EVENT_COUNT = 10; +// "dialog box", for the log. +const char* screen_event_name(ScreenEvent event); + + +// How a screen's fade looks: the kind of FADE_BLACK / FADE_WHITE. +enum class WarpFade{ + NONE, + BLACK, // a door's black, or a cave mouth's dim fade + WHITE, // a cave exit's white, with no battle after it +}; +// "black fade", for the log. +const char* warp_fade_name(WarpFade fade); + + +// The events of one frame, or of all the frames a watcher saw. +class ScreenEvents{ +public: + ScreenEvents() = default; + ScreenEvents(std::initializer_list events); + + bool has(ScreenEvent event) const{ + return (m_bits & bit(event)) != 0; + } + bool empty() const{ + return m_bits == 0; + } + // Whether any of `events` is in this set. + bool any_of(const ScreenEvents& events) const{ + return (m_bits & events.m_bits) != 0; + } + // Adds `event`, or removes it when `on` is false (as std::bitset::set). + void set(ScreenEvent event, bool on = true); + // Adds the fade's event (nothing for WarpFade::NONE). + void add_fade(WarpFade fade); + // The fade this set shows: BLACK before WHITE if it has both. + WarpFade fade() const; + void merge(const ScreenEvents& events){ + m_bits |= events.m_bits; + } + + uint32_t bits() const{ + return m_bits; + } + static ScreenEvents from_bits(uint32_t bits); + + // "dialog box, player can move"; "nothing" when empty. + std::string describe() const; + + bool operator==(const ScreenEvents& other) const = default; + +private: + static uint32_t bit(ScreenEvent event){ + return uint32_t(1) << (uint32_t)event; + } + + uint32_t m_bits = 0; +}; + + +// A fade is uniform over the middle 80% of the screen, the shared +// Black/WhiteScreenWatcher's stddev test (upstream #1717): a dim cave floor +// is textured, so it is no fade (BDSP's Oreburgh Gate, mean 46, lab-B +// 2026-11-08). Check against the Gate's frames on the console before +// tightening. +constexpr double FADE_MAX_STDDEV_SUM = 10; +// Dark goes to an rgb sum of 225, as a cave mouth's fade is dim, 45 to 64 +// a channel, not black. +constexpr double FADE_MAX_DARK_SUM = 225; +// White from an rgb sum of 500, as the shared WhiteScreenWatcher's. +constexpr double FADE_MIN_WHITE_SUM = 500; +// The fade `middle` (the stats of the screen's middle 80%) shows, if any. +WarpFade fade_of(const ImageStats& middle); +// fade_of() for a screen. +WarpFade fade_of_screen(const ImageViewRGB32& screen); + + +// A game's detectors, as events. Observers may keep state between frames +// (the frame before, for SCREEN_STILL; when a banner was last read, to +// gate OCR), so one observer watches one stream at a time. +class ScreenEventObserver{ +public: + virtual ~ScreenEventObserver() = default; + + // What `frame` shows. `now` is the caller's clock, for observers that + // rate-limit expensive reads. A null frame shows nothing. + virtual ScreenEvents observe(const VideoSnapshot& frame, WallClock now) = 0; + + // The boxes the detectors read, for the video overlay. + virtual void make_overlays(VideoOverlaySet& items) const = 0; +}; + + +// An observer as a run_until callback: it records every event it sees and +// stops the action on any of `stop_on` (none: it only records). +class ScreenEventWatcher : public VisualInferenceCallback{ +public: + ScreenEventWatcher(ScreenEventObserver& observer, ScreenEvents stop_on = {}); + + virtual void make_overlays(VideoOverlaySet& items) const override; + using VisualInferenceCallback::process_frame; + virtual bool process_frame(const VideoSnapshot& frame) override; + + // Every event seen since construction (or the last reset()). + ScreenEvents seen() const{ + return ScreenEvents::from_bits(m_seen.load(std::memory_order_acquire)); + } + // The events of the frame that stopped the action ("nothing" if none did). + ScreenEvents stopped_on() const{ + return ScreenEvents::from_bits(m_stopped_on.load(std::memory_order_acquire)); + } + void reset(); + +private: + ScreenEventObserver& m_observer; + const ScreenEvents m_stop_on; + std::atomic m_seen{0}; + std::atomic m_stopped_on{0}; +}; + + + +} // namespace Pokemon +} // namespace PokemonAutomation +#endif diff --git a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_ScreenEvents_Tests.cpp b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_ScreenEvents_Tests.cpp new file mode 100644 index 0000000000..ee46e4864e --- /dev/null +++ b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_ScreenEvents_Tests.cpp @@ -0,0 +1,235 @@ +/* Screen Events Tests + * + * From: https://github.com/PokemonAutomation/ + * + * The shared event vocabulary, the watcher form of an observer, and the + * judgements over events (warp seen, talk-over). + * + */ + +#include +#include +#include +#include +#include +#include "Common/Cpp/TestRunners/UnitTest.h" +#include "CommonFramework/ImageTypes/ImageRGB32.h" +#include "Pokemon_AutoStory_Tests.h" +#include "Pokemon_SceneJudges.h" +#include "Pokemon_ScreenEvents.h" + +namespace PokemonAutomation{ +namespace Pokemon{ + +namespace{ + +using namespace std::chrono_literals; + +class Test_ScreenEvents : public UnitTest{ +public: + Test_ScreenEvents(std::string name, std::function body) + : UnitTest("Pokemon::ScreenEvents - " + std::move(name)) + , m_body(std::move(body)) + {} + virtual UnitTestResult run(Logger&, CancellableScope&) const override{ + return m_body(); + } + +private: + std::function m_body; +}; + +UnitTestResult expect_equal(const std::string& what, const std::string& got, const std::string& expected){ + if (got == expected){ + return true; + } + return std::format("{}: expected \"{}\", got \"{}\"", what, expected, got); +} + + +UnitTestResult test_set_and_describe(){ + ScreenEvents events{ScreenEvent::DIALOG_BOX, ScreenEvent::PLAYER_CAN_MOVE}; + if (!events.has(ScreenEvent::DIALOG_BOX) || events.has(ScreenEvent::CHOICE_BOX)){ + return "has() disagrees with the constructor's events"; + } + events.set(ScreenEvent::DIALOG_BOX, false); + events.add_fade(WarpFade::WHITE); + events.add_fade(WarpFade::NONE); + if (events.fade() != WarpFade::WHITE){ + return "add_fade(WHITE) did not give a white fade"; + } + if (ScreenEvents::from_bits(events.bits()) != events){ + return "from_bits(bits()) is not the same set"; + } + if (!ScreenEvents().describe().starts_with("nothing")){ + return "an empty set does not describe as nothing"; + } + return expect_equal("describe()", events.describe(), "white fade, player can move"); +} + +// A screen filled with one colour, or a checkerboard of two. +ImageRGB32 screen_of(uint32_t a, uint32_t b){ + ImageRGB32 out(64, 36); + for (size_t y = 0; y < out.height(); y++){ + for (size_t x = 0; x < out.width(); x++){ + out.pixel(x, y) = (x + y) % 2 == 0 ? a : b; + } + } + return out; +} + +UnitTestResult test_fade_of_screen(){ + struct Row{ + const char* name; + uint32_t a; + uint32_t b; + WarpFade fade; + }; + const std::vector rows = { + {"black", 0xff000000, 0xff000000, WarpFade::BLACK}, + {"a cave mouth's dim fade (60 a channel)", 0xff3c3c3c, 0xff3c3c3c, WarpFade::BLACK}, + {"white", 0xffffffff, 0xffffffff, WarpFade::WHITE}, + {"grey, neither", 0xff787878, 0xff787878, WarpFade::NONE}, + {"a dark textured floor", 0xff101010, 0xff505050, WarpFade::NONE}, + }; + for (const Row& row : rows){ + const WarpFade got = fade_of_screen(screen_of(row.a, row.b)); + if (got != row.fade){ + return std::format("{}: expected {}, got {}", row.name, warp_fade_name(row.fade), warp_fade_name(got)); + } + } + return true; +} + +UnitTestResult test_warp_seen(){ + WarpSeen seen; + seen.see({ScreenEvent::DIALOG_BOX}, "Route 203"); + if (seen.any()){ + return "a dialog box with no banner event counted as a warp"; + } + seen.see({ScreenEvent::FADE_BLACK}); + seen.see({ScreenEvent::FADE_WHITE, ScreenEvent::LOCATION_BANNER}, "Route 203"); + seen.see({ScreenEvent::LOCATION_BANNER}, "Oreburgh Gate"); + return expect_equal("describe(WarpSeen)", describe(seen), "black fade, banner \"Route 203\""); +} + + +// A scripted scene: a look per beat, each `every` apart. Returns the beat +// TalkOver first says `want` at, or -1. +int first_beat(TalkOver& judge, const std::vector& beats, SceneMove want, Milliseconds every = 1000ms){ + WallClock now = WallClock(); + for (size_t c = 0; c < beats.size(); c++){ + if (judge.look(beats[c], now) == want){ + return (int)c; + } + now += every; + } + return -1; +} + +const ScreenEvents QUIET{ScreenEvent::PLAYER_CAN_MOVE, ScreenEvent::SCREEN_STILL}; +const ScreenEvents CALM{ScreenEvent::PLAYER_CAN_MOVE}; +const ScreenEvents BOX{ScreenEvent::DIALOG_BOX, ScreenEvent::PLAYER_CAN_MOVE, ScreenEvent::SCREEN_STILL}; + +std::vector repeat(const ScreenEvents& look, size_t count){ + return std::vector(count, look); +} +std::vector concat(std::vector a, const std::vector& b){ + a.insert(a.end(), b.begin(), b.end()); + return a; +} + +UnitTestResult test_talk_over(){ + struct Row{ + const char* name; + TalkOverRule rule; + std::vector beats; + SceneMove want; + int beat; + }; + const std::vector rows = { + {"5 s of quiet ends it", {}, repeat(QUIET, 8), SceneMove::DONE, 5}, + {"a box restarts the quiet", {}, concat(concat(repeat(QUIET, 3), {BOX}), repeat(QUIET, 8)), SceneMove::DONE, 9}, + {"a box is answered", {}, {BOX}, SceneMove::NEXT, 0}, + {"no box is a B press", {}, {QUIET}, SceneMove::B, 0}, + {"15 s calm but moving ends it", {}, repeat(CALM, 20), SceneMove::DONE, 15}, + {"a warp rule waits for the fade", {.warp = true}, + concat(concat(repeat(QUIET, 8), {ScreenEvents{ScreenEvent::FADE_BLACK}}), repeat(QUIET, 8)), + SceneMove::DONE, 14}, + {"a banner is the warp too", {.warp = true}, + concat({ScreenEvents{ScreenEvent::LOCATION_BANNER, ScreenEvent::PLAYER_CAN_MOVE}}, repeat(QUIET, 8)), + SceneMove::DONE, 6}, + {"no quiet ends a talk before a battle", {.end_on_quiet = false}, repeat(QUIET, 30), SceneMove::DONE, -1}, + {"a battle", {.end_on_quiet = false}, concat(repeat(QUIET, 6), {ScreenEvents{ScreenEvent::BATTLE_STARTED}}), SceneMove::BATTLE, 6}, + }; + for (const Row& row : rows){ + TalkOver judge(row.rule); + const int got = first_beat(judge, row.beats, row.want); + if (got != row.beat){ + return std::format("{}: expected beat {}, got {} ({})", row.name, row.beat, got, judge.describe()); + } + } + return true; +} + + +// Replays a fixed list of event sets, one per frame. +class ScriptedObserver : public ScreenEventObserver{ +public: + explicit ScriptedObserver(std::vector frames) + : m_frames(std::move(frames)) + {} + virtual ScreenEvents observe(const VideoSnapshot&, WallClock) override{ + return m_next < m_frames.size() ? m_frames[m_next++] : ScreenEvents(); + } + virtual void make_overlays(VideoOverlaySet&) const override{} + +private: + std::vector m_frames; + size_t m_next = 0; +}; + +UnitTestResult test_watcher(){ + ScriptedObserver observer({ + {ScreenEvent::PLAYER_CAN_MOVE}, + {ScreenEvent::FADE_BLACK}, + {ScreenEvent::LOCATION_BANNER, ScreenEvent::PLAYER_CAN_MOVE}, + {ScreenEvent::DIALOG_BOX}, + }); + ScreenEventWatcher watcher(observer, {ScreenEvent::LOCATION_BANNER}); + const VideoSnapshot frame; + std::vector stops; + for (size_t c = 0; c < 4; c++){ + stops.push_back(watcher.process_frame(frame)); + } + if (stops != std::vector{false, false, true, false}){ + return "the watcher did not stop exactly on the banner frame"; + } + UnitTestResult result = expect_equal("seen()", watcher.seen().describe(), + "black fade, location banner, dialog box, player can move"); + if (result.result != UnitTestResult::PASSED){ + return result; + } + result = expect_equal("stopped_on()", watcher.stopped_on().describe(), "location banner, player can move"); + if (result.result != UnitTestResult::PASSED){ + return result; + } + watcher.reset(); + return expect_equal("seen() after reset()", watcher.seen().describe(), "nothing"); +} + +} // namespace + + +void add_tests_ScreenEvents(UnitTestDatabase& database){ + database.add("a set of events, its fade and its log text", test_set_and_describe); + database.add("a fade is uniform, dark or white; a textured floor is none", test_fade_of_screen); + database.add("a warp is the first fade and the first banner seen", test_warp_seen); + database.add("talk-over from scripted events", test_talk_over); + database.add("an observer as a watcher records and stops", test_watcher); +} + + + +} // namespace Pokemon +} // namespace PokemonAutomation diff --git a/SerialPrograms/cmake/SourceFiles.cmake b/SerialPrograms/cmake/SourceFiles.cmake index 7be1fec8ae..df48c82405 100644 --- a/SerialPrograms/cmake/SourceFiles.cmake +++ b/SerialPrograms/cmake/SourceFiles.cmake @@ -1498,6 +1498,11 @@ file(GLOB LIBRARY_SOURCES Source/Pokemon/AutoStory/Pokemon_AutoStorySelect_Tests.h Source/Pokemon/AutoStory/Pokemon_AutoStoryStats.h Source/Pokemon/AutoStory/Pokemon_AutoStory_Tests.h + Source/Pokemon/AutoStory/Pokemon_SceneJudges.cpp + Source/Pokemon/AutoStory/Pokemon_SceneJudges.h + Source/Pokemon/AutoStory/Pokemon_ScreenEvents.cpp + Source/Pokemon/AutoStory/Pokemon_ScreenEvents.h + Source/Pokemon/AutoStory/Pokemon_ScreenEvents_Tests.cpp Source/Pokemon/AutoStory/Pokemon_StoryEvents.cpp Source/Pokemon/AutoStory/Pokemon_StoryEvents.h Source/Pokemon/AutoStory/Pokemon_StoryEvents_Tests.cpp From d0c49bbfa514b305f77277303f3b258d37476d10 Mon Sep 17 00:00:00 2001 From: dayfine Date: Sun, 8 Nov 2026 22:34:31 -0800 Subject: [PATCH 015/102] FRLG AutoStory: screen events from FRLG's detectors FrlgScreenObserver maps the white dialog box, the selection box, the battle menu and battle text, and uniform fades to the shared events. Unit tests on synthetic frames; real frames are the detectors' own tests. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_013VUubhHeYSMGSSDXZkKZss --- .../PokemonFRLG/PokemonFRLG_Tests.cpp | 2 + .../PokemonFRLG_AutoStoryScreenEvents.cpp | 53 ++++++++++++ .../PokemonFRLG_AutoStoryScreenEvents.h | 52 ++++++++++++ ...okemonFRLG_AutoStoryScreenEvents_Tests.cpp | 80 +++++++++++++++++++ SerialPrograms/cmake/SourceFiles.cmake | 3 + 5 files changed, 190 insertions(+) create mode 100644 SerialPrograms/Source/VideoGames/PokemonFRLG/Programs/AutoStory/PokemonFRLG_AutoStoryScreenEvents.cpp create mode 100644 SerialPrograms/Source/VideoGames/PokemonFRLG/Programs/AutoStory/PokemonFRLG_AutoStoryScreenEvents.h create mode 100644 SerialPrograms/Source/VideoGames/PokemonFRLG/Programs/AutoStory/PokemonFRLG_AutoStoryScreenEvents_Tests.cpp diff --git a/SerialPrograms/Source/VideoGames/PokemonFRLG/PokemonFRLG_Tests.cpp b/SerialPrograms/Source/VideoGames/PokemonFRLG/PokemonFRLG_Tests.cpp index d734e275f7..68ab2a274b 100644 --- a/SerialPrograms/Source/VideoGames/PokemonFRLG/PokemonFRLG_Tests.cpp +++ b/SerialPrograms/Source/VideoGames/PokemonFRLG/PokemonFRLG_Tests.cpp @@ -8,6 +8,7 @@ #include "Common/Cpp/Filesystem/Filesystem.h" #include "Common/Cpp/TestRunners/UnitTestDatabase.h" #include "CommonFramework/StaticGlobals.h" +#include "Programs/AutoStory/PokemonFRLG_AutoStoryScreenEvents.h" #include "Inference/Box/PokemonFRLG_BoxCellOccupiedDetector.h" #include "Inference/Box/PokemonFRLG_BoxCellReader.h" #include "Inference/Box/PokemonFRLG_BoxGenderReader.h" @@ -288,6 +289,7 @@ void add_tests(UnitTestDatabase& database){ add_tests_BattleMoveSelectionArrow(database); add_tests_BagDetector(database); add_tests_ExitWildBattle(database); + add_tests_AutoStoryScreenEvents(database); } diff --git a/SerialPrograms/Source/VideoGames/PokemonFRLG/Programs/AutoStory/PokemonFRLG_AutoStoryScreenEvents.cpp b/SerialPrograms/Source/VideoGames/PokemonFRLG/Programs/AutoStory/PokemonFRLG_AutoStoryScreenEvents.cpp new file mode 100644 index 0000000000..677ec6771e --- /dev/null +++ b/SerialPrograms/Source/VideoGames/PokemonFRLG/Programs/AutoStory/PokemonFRLG_AutoStoryScreenEvents.cpp @@ -0,0 +1,53 @@ +/* FRLG AutoStory - Screen Events + * + * From: https://github.com/PokemonAutomation/ + * + */ + +#include "PokemonFRLG_AutoStoryScreenEvents.h" + +namespace PokemonAutomation{ +namespace NintendoSwitch{ +namespace PokemonFRLG{ + +using Pokemon::ScreenEvent; +using Pokemon::ScreenEvents; + + +FrlgScreenObserver::FrlgScreenObserver() + : m_dialog(COLOR_RED) + , m_choice(COLOR_RED) + , m_battle_menu(COLOR_RED) + , m_battle_dialog(COLOR_RED) +{} + +ScreenEvents FrlgScreenObserver::observe(const VideoSnapshot& frame, WallClock){ + ScreenEvents out; + if (!frame){ + return out; + } + const ImageViewRGB32& screen = *frame.frame; + out.add_fade(Pokemon::fade_of_screen(screen)); + if (out.fade() != Pokemon::WarpFade::NONE){ + // A uniform screen has no box or menu to read. + return out; + } + const bool battle = m_battle_menu.detect(screen) || m_battle_dialog.detect(screen); + out.set(ScreenEvent::BATTLE_STARTED, battle); + out.set(ScreenEvent::DIALOG_BOX, !battle && m_dialog.detect(screen)); + out.set(ScreenEvent::CHOICE_BOX, !battle && m_choice.detect(screen)); + return out; +} + +void FrlgScreenObserver::make_overlays(VideoOverlaySet& items) const{ + m_dialog.make_overlays(items); + m_choice.make_overlays(items); + m_battle_menu.make_overlays(items); + m_battle_dialog.make_overlays(items); +} + + + +} // namespace PokemonFRLG +} // namespace NintendoSwitch +} // namespace PokemonAutomation diff --git a/SerialPrograms/Source/VideoGames/PokemonFRLG/Programs/AutoStory/PokemonFRLG_AutoStoryScreenEvents.h b/SerialPrograms/Source/VideoGames/PokemonFRLG/Programs/AutoStory/PokemonFRLG_AutoStoryScreenEvents.h new file mode 100644 index 0000000000..d807432278 --- /dev/null +++ b/SerialPrograms/Source/VideoGames/PokemonFRLG/Programs/AutoStory/PokemonFRLG_AutoStoryScreenEvents.h @@ -0,0 +1,52 @@ +/* FRLG AutoStory - Screen Events + * + * From: https://github.com/PokemonAutomation/ + * + * FRLG's detectors as the shared screen events (Pokemon_ScreenEvents.h), + * so the shared judgements (Pokemon_SceneJudges.h) read FRLG frames too. + * + */ + +#ifndef PokemonAutomation_PokemonFRLG_AutoStoryScreenEvents_H +#define PokemonAutomation_PokemonFRLG_AutoStoryScreenEvents_H + +#include "Common/Cpp/TestRunners/UnitTestDatabase.h" +#include "Pokemon/AutoStory/Pokemon_ScreenEvents.h" +#include "VideoGames/PokemonFRLG/Inference/Dialogs/PokemonFRLG_BattleDialogs.h" +#include "VideoGames/PokemonFRLG/Inference/Dialogs/PokemonFRLG_DialogDetector.h" + +namespace PokemonAutomation{ +namespace NintendoSwitch{ +namespace PokemonFRLG{ + + +// The shared events from FRLG's detectors: +// - DIALOG_BOX: the overworld's white text box (WhiteDialogDetector); +// - CHOICE_BOX: a Yes/No or answer box beside it (SelectionDialogDetector); +// - BATTLE_STARTED: the battle menu or a battle's text box; +// - FADE_BLACK / FADE_WHITE: fade_of_screen(). +// Not reported yet, as FRLG has no detector for them here: the map-name +// popup (LOCATION_BANNER), PLAYER_CAN_MOVE, SCREEN_STILL, the interact +// prompt (FRLG has none) and a battle's end. +class FrlgScreenObserver : public Pokemon::ScreenEventObserver{ +public: + FrlgScreenObserver(); + + virtual Pokemon::ScreenEvents observe(const VideoSnapshot& frame, WallClock now) override; + virtual void make_overlays(VideoOverlaySet& items) const override; + +private: + WhiteDialogDetector m_dialog; + SelectionDialogDetector m_choice; + BattleMenuDetector m_battle_menu; + BattleDialogDetector m_battle_dialog; +}; + +void add_tests_AutoStoryScreenEvents(UnitTestDatabase& database); + + + +} // namespace PokemonFRLG +} // namespace NintendoSwitch +} // namespace PokemonAutomation +#endif diff --git a/SerialPrograms/Source/VideoGames/PokemonFRLG/Programs/AutoStory/PokemonFRLG_AutoStoryScreenEvents_Tests.cpp b/SerialPrograms/Source/VideoGames/PokemonFRLG/Programs/AutoStory/PokemonFRLG_AutoStoryScreenEvents_Tests.cpp new file mode 100644 index 0000000000..ef394c2954 --- /dev/null +++ b/SerialPrograms/Source/VideoGames/PokemonFRLG/Programs/AutoStory/PokemonFRLG_AutoStoryScreenEvents_Tests.cpp @@ -0,0 +1,80 @@ +/* FRLG AutoStory - Screen Events Tests + * + * From: https://github.com/PokemonAutomation/ + * + * The adapter on synthetic frames: a uniform screen is a fade and nothing + * else, and no frame shows nothing. Frames of real boxes and battles are + * the detectors' own image tests (CommandLineTests). + * + */ + +#include +#include +#include +#include +#include "Common/Cpp/TestRunners/UnitTest.h" +#include "CommonFramework/ImageTypes/ImageRGB32.h" +#include "PokemonFRLG_AutoStoryScreenEvents.h" + +namespace PokemonAutomation{ +namespace NintendoSwitch{ +namespace PokemonFRLG{ + +using Pokemon::ScreenEvent; +using Pokemon::ScreenEvents; + +namespace{ + +struct ScreenEventsScenario{ + std::string name; + // The frame's colour; 0 for no frame. + uint32_t color; + ScreenEvents expected; +}; + +class Test_AutoStoryScreenEvents : public UnitTest{ +public: + Test_AutoStoryScreenEvents(ScreenEventsScenario scenario) + : UnitTest("PokemonFRLG::AutoStoryScreenEvents - " + scenario.name) + , m_scenario(std::move(scenario)) + {} + + virtual UnitTestResult run(Logger&, CancellableScope&) const override{ + VideoSnapshot frame(ImageRGB32(), WallClock()); + if (m_scenario.color != 0){ + ImageRGB32 image(1920, 1080); + image.fill(m_scenario.color); + frame = VideoSnapshot(std::move(image), WallClock()); + } + FrlgScreenObserver observer; + const ScreenEvents got = observer.observe(frame, WallClock()); + if (got != m_scenario.expected){ + return std::format("expected {}, got {}", m_scenario.expected.describe(), got.describe()); + } + return true; + } + +private: + const ScreenEventsScenario m_scenario; +}; + +} // namespace + + +void add_tests_AutoStoryScreenEvents(UnitTestDatabase& database){ + const std::vector scenarios = { + {"no frame shows nothing", 0, {}}, + {"a black screen is a black fade only", 0xff000000, {ScreenEvent::FADE_BLACK}}, + {"a white screen is a white fade only", 0xffffffff, {ScreenEvent::FADE_WHITE}}, + {"a grey screen shows nothing", 0xff787878, {}}, + }; + for (const ScreenEventsScenario& scenario : scenarios){ + database.add(scenario); + } +} + + + +} // namespace PokemonFRLG +} // namespace NintendoSwitch +} // namespace PokemonAutomation diff --git a/SerialPrograms/cmake/SourceFiles.cmake b/SerialPrograms/cmake/SourceFiles.cmake index df48c82405..d06a8af31a 100644 --- a/SerialPrograms/cmake/SourceFiles.cmake +++ b/SerialPrograms/cmake/SourceFiles.cmake @@ -1834,6 +1834,9 @@ file(GLOB LIBRARY_SOURCES Source/VideoGames/PokemonFRLG/Programs/Farming/PokemonFRLG_NuggetBridgeFarmer.h Source/VideoGames/PokemonFRLG/Programs/Farming/PokemonFRLG_PickupFarmer.cpp Source/VideoGames/PokemonFRLG/Programs/Farming/PokemonFRLG_PickupFarmer.h + Source/VideoGames/PokemonFRLG/Programs/AutoStory/PokemonFRLG_AutoStoryScreenEvents.cpp + Source/VideoGames/PokemonFRLG/Programs/AutoStory/PokemonFRLG_AutoStoryScreenEvents.h + Source/VideoGames/PokemonFRLG/Programs/AutoStory/PokemonFRLG_AutoStoryScreenEvents_Tests.cpp Source/VideoGames/PokemonFRLG/Programs/PokemonFRLG_BattleMenuNavigation.cpp Source/VideoGames/PokemonFRLG/Programs/PokemonFRLG_BattleMenuNavigation.h Source/VideoGames/PokemonFRLG/Programs/PokemonFRLG_SafariOptimalAction.cpp From 4259210e3533fd84c03c3c9a64c8a3af2fba72ae Mon Sep 17 00:00:00 2001 From: dayfine Date: Sun, 8 Nov 2026 22:35:25 -0800 Subject: [PATCH 016/102] FRLG AutoStory: screen events test builds an empty snapshot plainly Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_013VUubhHeYSMGSSDXZkKZss --- .../AutoStory/PokemonFRLG_AutoStoryScreenEvents_Tests.cpp | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/SerialPrograms/Source/VideoGames/PokemonFRLG/Programs/AutoStory/PokemonFRLG_AutoStoryScreenEvents_Tests.cpp b/SerialPrograms/Source/VideoGames/PokemonFRLG/Programs/AutoStory/PokemonFRLG_AutoStoryScreenEvents_Tests.cpp index ef394c2954..030f7812d6 100644 --- a/SerialPrograms/Source/VideoGames/PokemonFRLG/Programs/AutoStory/PokemonFRLG_AutoStoryScreenEvents_Tests.cpp +++ b/SerialPrograms/Source/VideoGames/PokemonFRLG/Programs/AutoStory/PokemonFRLG_AutoStoryScreenEvents_Tests.cpp @@ -40,7 +40,7 @@ class Test_AutoStoryScreenEvents : public UnitTest{ {} virtual UnitTestResult run(Logger&, CancellableScope&) const override{ - VideoSnapshot frame(ImageRGB32(), WallClock()); + VideoSnapshot frame; if (m_scenario.color != 0){ ImageRGB32 image(1920, 1080); image.fill(m_scenario.color); From 1460617845b638fb00200634d50bfe3ec18525f4 Mon Sep 17 00:00:00 2001 From: dayfine Date: Sun, 8 Nov 2026 22:36:01 -0800 Subject: [PATCH 017/102] FRLG AutoStory: drop the flat grey frame from the screen-event tests The battle text box detector reads a flat grey frame as its box; that frame is no real screen, so it tests nothing about the adapter. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_013VUubhHeYSMGSSDXZkKZss --- .../AutoStory/PokemonFRLG_AutoStoryScreenEvents_Tests.cpp | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/SerialPrograms/Source/VideoGames/PokemonFRLG/Programs/AutoStory/PokemonFRLG_AutoStoryScreenEvents_Tests.cpp b/SerialPrograms/Source/VideoGames/PokemonFRLG/Programs/AutoStory/PokemonFRLG_AutoStoryScreenEvents_Tests.cpp index 030f7812d6..d6febab504 100644 --- a/SerialPrograms/Source/VideoGames/PokemonFRLG/Programs/AutoStory/PokemonFRLG_AutoStoryScreenEvents_Tests.cpp +++ b/SerialPrograms/Source/VideoGames/PokemonFRLG/Programs/AutoStory/PokemonFRLG_AutoStoryScreenEvents_Tests.cpp @@ -4,7 +4,8 @@ * * The adapter on synthetic frames: a uniform screen is a fade and nothing * else, and no frame shows nothing. Frames of real boxes and battles are - * the detectors' own image tests (CommandLineTests). + * the detectors' own image tests (CommandLineTests); a flat grey frame is + * not one of those (the battle text box reads it as a box). * */ @@ -66,7 +67,6 @@ void add_tests_AutoStoryScreenEvents(UnitTestDatabase& database){ {"no frame shows nothing", 0, {}}, {"a black screen is a black fade only", 0xff000000, {ScreenEvent::FADE_BLACK}}, {"a white screen is a white fade only", 0xffffffff, {ScreenEvent::FADE_WHITE}}, - {"a grey screen shows nothing", 0xff787878, {}}, }; for (const ScreenEventsScenario& scenario : scenarios){ database.add(scenario); From 8b320918a75efc5190e3c8e79f59f32f68155f99 Mon Sep 17 00:00:00 2001 From: dayfine Date: Sun, 8 Nov 2026 22:39:40 -0800 Subject: [PATCH 018/102] AutoStory screen events: fit the code-health limits ScreenEvents keeps its set operations; fades and the log text become free functions (fade_events, fade_in, describe), WarpSeen::see becomes note_warp(), and the tests use the case-table form. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_013VUubhHeYSMGSSDXZkKZss --- .../Pokemon/AutoStory/Pokemon_SceneJudges.cpp | 15 +-- .../Pokemon/AutoStory/Pokemon_SceneJudges.h | 6 +- .../AutoStory/Pokemon_ScreenEvents.cpp | 34 +++--- .../Pokemon/AutoStory/Pokemon_ScreenEvents.h | 19 ++-- .../AutoStory/Pokemon_ScreenEvents_Tests.cpp | 100 ++++++++++++------ .../PokemonFRLG_AutoStoryScreenEvents.cpp | 7 +- .../PokemonFRLG_AutoStoryScreenEvents.h | 1 + ...okemonFRLG_AutoStoryScreenEvents_Tests.cpp | 53 ++++++---- 8 files changed, 142 insertions(+), 93 deletions(-) diff --git a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_SceneJudges.cpp b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_SceneJudges.cpp index 1c8aaa01c8..628be668dc 100644 --- a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_SceneJudges.cpp +++ b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_SceneJudges.cpp @@ -10,13 +10,14 @@ namespace PokemonAutomation{ namespace Pokemon{ -void WarpSeen::see(const ScreenEvents& events, const std::string& banner_read){ - if (fade == WarpFade::NONE){ - fade = events.fade(); +WarpSeen note_warp(WarpSeen seen, const ScreenEvents& events, const std::string& banner_read){ + if (seen.fade == WarpFade::NONE){ + seen.fade = fade_in(events); } - if (banner.empty() && events.has(ScreenEvent::LOCATION_BANNER)){ - banner = banner_read; + if (seen.banner.empty() && events.has(ScreenEvent::LOCATION_BANNER)){ + seen.banner = banner_read; } + return seen; } std::string describe(const WarpSeen& seen){ @@ -37,8 +38,8 @@ SceneMove TalkOver::look(const ScreenEvents& look, WallClock now){ m_calm_since = WallClock::max(); return SceneMove::BATTLE; } - if (look.fade() != WarpFade::NONE){ - m_fade = look.fade(); + if (fade_in(look) != WarpFade::NONE){ + m_fade = fade_in(look); } m_banner |= look.has(ScreenEvent::LOCATION_BANNER); const bool box = look.has(ScreenEvent::DIALOG_BOX); diff --git a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_SceneJudges.h b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_SceneJudges.h index 1c7ee14800..704ecf9a86 100644 --- a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_SceneJudges.h +++ b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_SceneJudges.h @@ -31,10 +31,10 @@ struct WarpSeen{ bool any() const{ return fade != WarpFade::NONE || !banner.empty(); } - // Notes a frame's events: its fade, and `banner_read` when it shows - // LOCATION_BANNER. The first of each counts. - void see(const ScreenEvents& events, const std::string& banner_read = ""); }; +// `seen` after a frame's events: their fade, and `banner_read` when they +// show LOCATION_BANNER. The first of each counts. +WarpSeen note_warp(WarpSeen seen, const ScreenEvents& events, const std::string& banner_read); // How it was seen, for the log: a black fade, banner "Route 203". std::string describe(const WarpSeen& seen); diff --git a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_ScreenEvents.cpp b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_ScreenEvents.cpp index 4ee56d206f..d8ea3b5beb 100644 --- a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_ScreenEvents.cpp +++ b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_ScreenEvents.cpp @@ -40,7 +40,7 @@ const char* warp_fade_name(WarpFade fade){ ScreenEvents::ScreenEvents(std::initializer_list events){ for (ScreenEvent event : events){ - set(event); + set(event, true); } } void ScreenEvents::set(ScreenEvent event, bool on){ @@ -50,37 +50,37 @@ void ScreenEvents::set(ScreenEvent event, bool on){ m_bits &= ~bit(event); } } -void ScreenEvents::add_fade(WarpFade fade){ +ScreenEvents ScreenEvents::from_bits(uint32_t bits){ + ScreenEvents out; + out.m_bits = bits & ((uint32_t(1) << SCREEN_EVENT_COUNT) - 1); + return out; +} + +ScreenEvents fade_events(WarpFade fade){ switch (fade){ case WarpFade::NONE: - return; + return {}; case WarpFade::BLACK: - set(ScreenEvent::FADE_BLACK); - return; + return {ScreenEvent::FADE_BLACK}; case WarpFade::WHITE: - set(ScreenEvent::FADE_WHITE); - return; + return {ScreenEvent::FADE_WHITE}; } + return {}; } -WarpFade ScreenEvents::fade() const{ - if (has(ScreenEvent::FADE_BLACK)){ +WarpFade fade_in(const ScreenEvents& events){ + if (events.has(ScreenEvent::FADE_BLACK)){ return WarpFade::BLACK; } - if (has(ScreenEvent::FADE_WHITE)){ + if (events.has(ScreenEvent::FADE_WHITE)){ return WarpFade::WHITE; } return WarpFade::NONE; } -ScreenEvents ScreenEvents::from_bits(uint32_t bits){ - ScreenEvents out; - out.m_bits = bits & ((uint32_t(1) << SCREEN_EVENT_COUNT) - 1); - return out; -} -std::string ScreenEvents::describe() const{ +std::string describe(const ScreenEvents& events){ std::string out; for (size_t c = 0; c < SCREEN_EVENT_COUNT; c++){ const ScreenEvent event = (ScreenEvent)c; - if (!has(event)){ + if (!events.has(event)){ continue; } if (!out.empty()){ diff --git a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_ScreenEvents.h b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_ScreenEvents.h index a588013fd6..1bf6ca6649 100644 --- a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_ScreenEvents.h +++ b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_ScreenEvents.h @@ -44,6 +44,7 @@ enum class ScreenEvent : uint8_t{ PLAYER_CAN_MOVE, // The overworld with the player in control. SCREEN_STILL, // The screen barely changed since the frame before. }; +// How many ScreenEvent values there are. constexpr size_t SCREEN_EVENT_COUNT = 10; // "dialog box", for the log. const char* screen_event_name(ScreenEvent event); @@ -68,19 +69,12 @@ class ScreenEvents{ bool has(ScreenEvent event) const{ return (m_bits & bit(event)) != 0; } - bool empty() const{ - return m_bits == 0; - } // Whether any of `events` is in this set. bool any_of(const ScreenEvents& events) const{ return (m_bits & events.m_bits) != 0; } // Adds `event`, or removes it when `on` is false (as std::bitset::set). - void set(ScreenEvent event, bool on = true); - // Adds the fade's event (nothing for WarpFade::NONE). - void add_fade(WarpFade fade); - // The fade this set shows: BLACK before WHITE if it has both. - WarpFade fade() const; + void set(ScreenEvent event, bool on); void merge(const ScreenEvents& events){ m_bits |= events.m_bits; } @@ -90,9 +84,6 @@ class ScreenEvents{ } static ScreenEvents from_bits(uint32_t bits); - // "dialog box, player can move"; "nothing" when empty. - std::string describe() const; - bool operator==(const ScreenEvents& other) const = default; private: @@ -102,6 +93,12 @@ class ScreenEvents{ uint32_t m_bits = 0; }; +// The event of a fade: FADE_BLACK, FADE_WHITE, or none for WarpFade::NONE. +ScreenEvents fade_events(WarpFade fade); +// The fade `events` show: BLACK before WHITE if they have both. +WarpFade fade_in(const ScreenEvents& events); +// "dialog box, player can move"; "nothing" when empty. +std::string describe(const ScreenEvents& events); // A fade is uniform over the middle 80% of the screen, the shared diff --git a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_ScreenEvents_Tests.cpp b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_ScreenEvents_Tests.cpp index ee46e4864e..2d0db31cfd 100644 --- a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_ScreenEvents_Tests.cpp +++ b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_ScreenEvents_Tests.cpp @@ -25,20 +25,6 @@ namespace{ using namespace std::chrono_literals; -class Test_ScreenEvents : public UnitTest{ -public: - Test_ScreenEvents(std::string name, std::function body) - : UnitTest("Pokemon::ScreenEvents - " + std::move(name)) - , m_body(std::move(body)) - {} - virtual UnitTestResult run(Logger&, CancellableScope&) const override{ - return m_body(); - } - -private: - std::function m_body; -}; - UnitTestResult expect_equal(const std::string& what, const std::string& got, const std::string& expected){ if (got == expected){ return true; @@ -53,18 +39,18 @@ UnitTestResult test_set_and_describe(){ return "has() disagrees with the constructor's events"; } events.set(ScreenEvent::DIALOG_BOX, false); - events.add_fade(WarpFade::WHITE); - events.add_fade(WarpFade::NONE); - if (events.fade() != WarpFade::WHITE){ - return "add_fade(WHITE) did not give a white fade"; + events.merge(fade_events(WarpFade::WHITE)); + events.merge(fade_events(WarpFade::NONE)); + if (fade_in(events) != WarpFade::WHITE){ + return "fade_events(WHITE) did not give a white fade"; } if (ScreenEvents::from_bits(events.bits()) != events){ return "from_bits(bits()) is not the same set"; } - if (!ScreenEvents().describe().starts_with("nothing")){ + if (describe(ScreenEvents()) != "nothing"){ return "an empty set does not describe as nothing"; } - return expect_equal("describe()", events.describe(), "white fade, player can move"); + return expect_equal("describe()", describe(events), "white fade, player can move"); } // A screen filled with one colour, or a checkerboard of two. @@ -102,14 +88,13 @@ UnitTestResult test_fade_of_screen(){ } UnitTestResult test_warp_seen(){ - WarpSeen seen; - seen.see({ScreenEvent::DIALOG_BOX}, "Route 203"); + WarpSeen seen = note_warp({}, {ScreenEvent::DIALOG_BOX}, "Route 203"); if (seen.any()){ return "a dialog box with no banner event counted as a warp"; } - seen.see({ScreenEvent::FADE_BLACK}); - seen.see({ScreenEvent::FADE_WHITE, ScreenEvent::LOCATION_BANNER}, "Route 203"); - seen.see({ScreenEvent::LOCATION_BANNER}, "Oreburgh Gate"); + seen = note_warp(seen, {ScreenEvent::FADE_BLACK}, ""); + seen = note_warp(seen, {ScreenEvent::FADE_WHITE, ScreenEvent::LOCATION_BANNER}, "Route 203"); + seen = note_warp(seen, {ScreenEvent::LOCATION_BANNER}, "Oreburgh Gate"); return expect_equal("describe(WarpSeen)", describe(seen), "black fade, banner \"Route 203\""); } @@ -205,28 +190,77 @@ UnitTestResult test_watcher(){ if (stops != std::vector{false, false, true, false}){ return "the watcher did not stop exactly on the banner frame"; } - UnitTestResult result = expect_equal("seen()", watcher.seen().describe(), + UnitTestResult result = expect_equal("seen()", describe(watcher.seen()), "black fade, location banner, dialog box, player can move"); if (result.result != UnitTestResult::PASSED){ return result; } - result = expect_equal("stopped_on()", watcher.stopped_on().describe(), "location banner, player can move"); + result = expect_equal("stopped_on()", describe(watcher.stopped_on()), "location banner, player can move"); if (result.result != UnitTestResult::PASSED){ return result; } watcher.reset(); - return expect_equal("seen() after reset()", watcher.seen().describe(), "nothing"); + return expect_equal("seen() after reset()", describe(watcher.seen()), "nothing"); } + +struct ScreenEventsInput{ + std::string name; + std::function body; +}; + +struct ScreenEventsExpectation{ +}; + +struct ScreenEventsCase{ + ScreenEventsInput input; + ScreenEventsExpectation expectation; +}; + +class Test_ScreenEvents : public UnitTest{ +public: + explicit Test_ScreenEvents(ScreenEventsCase test_case) + : UnitTest("Pokemon::ScreenEvents - " + test_case.input.name) + , m_case(std::move(test_case)) + {} + virtual UnitTestResult run(Logger&, CancellableScope&) const override{ + return m_case.input.body(); + } + +private: + ScreenEventsCase m_case; +}; + } // namespace +const ScreenEventsCase SCREEN_EVENTS_CASES[] = { + { + .input = {"a set of events, its fade and its log text", test_set_and_describe}, + .expectation = {}, + }, + { + .input = {"a fade is uniform, dark or white; a textured floor is none", test_fade_of_screen}, + .expectation = {}, + }, + { + .input = {"a warp is the first fade and the first banner seen", test_warp_seen}, + .expectation = {}, + }, + { + .input = {"talk-over from scripted events", test_talk_over}, + .expectation = {}, + }, + { + .input = {"an observer as a watcher records and stops", test_watcher}, + .expectation = {}, + }, +}; + void add_tests_ScreenEvents(UnitTestDatabase& database){ - database.add("a set of events, its fade and its log text", test_set_and_describe); - database.add("a fade is uniform, dark or white; a textured floor is none", test_fade_of_screen); - database.add("a warp is the first fade and the first banner seen", test_warp_seen); - database.add("talk-over from scripted events", test_talk_over); - database.add("an observer as a watcher records and stops", test_watcher); + for (const auto& item : SCREEN_EVENTS_CASES){ + database.add(item); + } } diff --git a/SerialPrograms/Source/VideoGames/PokemonFRLG/Programs/AutoStory/PokemonFRLG_AutoStoryScreenEvents.cpp b/SerialPrograms/Source/VideoGames/PokemonFRLG/Programs/AutoStory/PokemonFRLG_AutoStoryScreenEvents.cpp index 677ec6771e..85edb74b36 100644 --- a/SerialPrograms/Source/VideoGames/PokemonFRLG/Programs/AutoStory/PokemonFRLG_AutoStoryScreenEvents.cpp +++ b/SerialPrograms/Source/VideoGames/PokemonFRLG/Programs/AutoStory/PokemonFRLG_AutoStoryScreenEvents.cpp @@ -22,13 +22,12 @@ FrlgScreenObserver::FrlgScreenObserver() {} ScreenEvents FrlgScreenObserver::observe(const VideoSnapshot& frame, WallClock){ - ScreenEvents out; if (!frame){ - return out; + return {}; } const ImageViewRGB32& screen = *frame.frame; - out.add_fade(Pokemon::fade_of_screen(screen)); - if (out.fade() != Pokemon::WarpFade::NONE){ + ScreenEvents out = Pokemon::fade_events(Pokemon::fade_of_screen(screen)); + if (Pokemon::fade_in(out) != Pokemon::WarpFade::NONE){ // A uniform screen has no box or menu to read. return out; } diff --git a/SerialPrograms/Source/VideoGames/PokemonFRLG/Programs/AutoStory/PokemonFRLG_AutoStoryScreenEvents.h b/SerialPrograms/Source/VideoGames/PokemonFRLG/Programs/AutoStory/PokemonFRLG_AutoStoryScreenEvents.h index d807432278..d6403a765f 100644 --- a/SerialPrograms/Source/VideoGames/PokemonFRLG/Programs/AutoStory/PokemonFRLG_AutoStoryScreenEvents.h +++ b/SerialPrograms/Source/VideoGames/PokemonFRLG/Programs/AutoStory/PokemonFRLG_AutoStoryScreenEvents.h @@ -42,6 +42,7 @@ class FrlgScreenObserver : public Pokemon::ScreenEventObserver{ BattleDialogDetector m_battle_dialog; }; +// Registers the adapter's unit tests (synthetic frames). void add_tests_AutoStoryScreenEvents(UnitTestDatabase& database); diff --git a/SerialPrograms/Source/VideoGames/PokemonFRLG/Programs/AutoStory/PokemonFRLG_AutoStoryScreenEvents_Tests.cpp b/SerialPrograms/Source/VideoGames/PokemonFRLG/Programs/AutoStory/PokemonFRLG_AutoStoryScreenEvents_Tests.cpp index d6febab504..7f8182bccc 100644 --- a/SerialPrograms/Source/VideoGames/PokemonFRLG/Programs/AutoStory/PokemonFRLG_AutoStoryScreenEvents_Tests.cpp +++ b/SerialPrograms/Source/VideoGames/PokemonFRLG/Programs/AutoStory/PokemonFRLG_AutoStoryScreenEvents_Tests.cpp @@ -12,7 +12,6 @@ #include #include #include -#include #include "Common/Cpp/TestRunners/UnitTest.h" #include "CommonFramework/ImageTypes/ImageRGB32.h" #include "PokemonFRLG_AutoStoryScreenEvents.h" @@ -26,50 +25,68 @@ using Pokemon::ScreenEvents; namespace{ -struct ScreenEventsScenario{ +struct ScreenEventsInput{ std::string name; // The frame's colour; 0 for no frame. uint32_t color; - ScreenEvents expected; +}; + +struct ScreenEventsExpectation{ + ScreenEvents events; +}; + +struct ScreenEventsCase{ + ScreenEventsInput input; + ScreenEventsExpectation expectation; }; class Test_AutoStoryScreenEvents : public UnitTest{ public: - Test_AutoStoryScreenEvents(ScreenEventsScenario scenario) - : UnitTest("PokemonFRLG::AutoStoryScreenEvents - " + scenario.name) - , m_scenario(std::move(scenario)) + explicit Test_AutoStoryScreenEvents(ScreenEventsCase test_case) + : UnitTest("PokemonFRLG::AutoStoryScreenEvents - " + test_case.input.name) + , m_case(std::move(test_case)) {} virtual UnitTestResult run(Logger&, CancellableScope&) const override{ VideoSnapshot frame; - if (m_scenario.color != 0){ + if (m_case.input.color != 0){ ImageRGB32 image(1920, 1080); - image.fill(m_scenario.color); + image.fill(m_case.input.color); frame = VideoSnapshot(std::move(image), WallClock()); } FrlgScreenObserver observer; const ScreenEvents got = observer.observe(frame, WallClock()); - if (got != m_scenario.expected){ - return std::format("expected {}, got {}", m_scenario.expected.describe(), got.describe()); + if (got != m_case.expectation.events){ + return std::format("expected {}, got {}", describe(m_case.expectation.events), describe(got)); } return true; } private: - const ScreenEventsScenario m_scenario; + ScreenEventsCase m_case; }; } // namespace +const ScreenEventsCase SCREEN_EVENTS_CASES[] = { + { + .input = {"no frame shows nothing", 0}, + .expectation = {{}}, + }, + { + .input = {"a black screen is a black fade only", 0xff000000}, + .expectation = {{ScreenEvent::FADE_BLACK}}, + }, + { + .input = {"a white screen is a white fade only", 0xffffffff}, + .expectation = {{ScreenEvent::FADE_WHITE}}, + }, +}; + void add_tests_AutoStoryScreenEvents(UnitTestDatabase& database){ - const std::vector scenarios = { - {"no frame shows nothing", 0, {}}, - {"a black screen is a black fade only", 0xff000000, {ScreenEvent::FADE_BLACK}}, - {"a white screen is a white fade only", 0xffffffff, {ScreenEvent::FADE_WHITE}}, - }; - for (const ScreenEventsScenario& scenario : scenarios){ - database.add(scenario); + for (const auto& item : SCREEN_EVENTS_CASES){ + database.add(item); } } From a7e440ce0de545eccb0e091b55751c147cad654f Mon Sep 17 00:00:00 2001 From: dayfine Date: Mon, 9 Nov 2026 01:10:11 -0800 Subject: [PATCH 019/102] AutoStory: story action table, variant parser and TableExecutor StoryActionTable keys a game's actions by step kind and variant name (exact, then any kind, then the kind's default). TableExecutor runs a step through it inside a game's StepGuard, which turns a failed console step into a failed Outcome unless the row stops on failure. The shared variant parser reads "name key=value" variants; lint_story_checkpoint() names steps without an action. Additive: no game uses it yet. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_013VUubhHeYSMGSSDXZkKZss --- .../ComputerPrograms_UnitTestRunner.cpp | 1 + .../AutoStory/Pokemon_AutoStory_Tests.h | 2 + .../AutoStory/Pokemon_StoryActions.cpp | 113 ++++++ .../Pokemon/AutoStory/Pokemon_StoryActions.h | 116 ++++++ .../AutoStory/Pokemon_StoryActions_Tests.cpp | 384 ++++++++++++++++++ .../AutoStory/Pokemon_StoryVariant.cpp | 72 ++++ .../Pokemon/AutoStory/Pokemon_StoryVariant.h | 51 +++ SerialPrograms/cmake/SourceFiles.cmake | 5 + 8 files changed, 744 insertions(+) create mode 100644 SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryActions.cpp create mode 100644 SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryActions.h create mode 100644 SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryActions_Tests.cpp create mode 100644 SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryVariant.cpp create mode 100644 SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryVariant.h diff --git a/SerialPrograms/Source/ComputerPrograms/ComputerPrograms_UnitTestRunner.cpp b/SerialPrograms/Source/ComputerPrograms/ComputerPrograms_UnitTestRunner.cpp index 2257d00254..922cc58df9 100644 --- a/SerialPrograms/Source/ComputerPrograms/ComputerPrograms_UnitTestRunner.cpp +++ b/SerialPrograms/Source/ComputerPrograms/ComputerPrograms_UnitTestRunner.cpp @@ -79,6 +79,7 @@ UnitTestDatabase make_UNIT_TESTS_ALL(){ Pokemon::add_tests_RuntimeMap(ret); Pokemon::add_tests_RouteLog(ret); Pokemon::add_tests_ScreenEvents(ret); + Pokemon::add_tests_StoryActions(ret); Pokemon::add_tests_StoryEvents(ret); Pokemon::add_tests_StorySegments(ret); Pokemon::add_tests_StorySteps(ret); diff --git a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_AutoStory_Tests.h b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_AutoStory_Tests.h index 237cd643d7..8a4abecfe2 100644 --- a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_AutoStory_Tests.h +++ b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_AutoStory_Tests.h @@ -17,6 +17,8 @@ namespace Pokemon{ // Registers unit tests for the shared screen events and the judgements over them. void add_tests_ScreenEvents(UnitTestDatabase& database); +// Story action tables, the variant parser and the table executor. +void add_tests_StoryActions(UnitTestDatabase& database); // Registers unit tests for story event sequencing and execution. void add_tests_StoryEvents(UnitTestDatabase& database); // Registers unit tests for story segment running, verification, and branching. diff --git a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryActions.cpp b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryActions.cpp new file mode 100644 index 0000000000..2366323e97 --- /dev/null +++ b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryActions.cpp @@ -0,0 +1,113 @@ +/* Story Actions + * + * From: https://github.com/PokemonAutomation/ + * + */ + +#include +#include +#include "Common/Cpp/Exceptions.h" +#include "Pokemon_StoryVariant.h" +#include "Pokemon_StoryActions.h" + +namespace PokemonAutomation{ +namespace Pokemon{ + + +namespace{ + +const StoryAction* find_in(const std::map>& actions, std::string_view name){ + const auto iter = actions.find(name); + return iter == actions.end() ? nullptr : &iter->second; +} + +} // namespace + + +void StoryActionTable::add(StoryStepKind kind, std::string name, StoryAction action){ + const std::string key = std::format("{} '{}'", story_step_kind_name(kind), name); + if (!m_by_kind[kind].emplace(std::move(name), std::move(action)).second){ + throw InternalProgramError(nullptr, PA_CURRENT_FUNCTION, "A second story action for " + key); + } +} + +void StoryActionTable::add_any_kind(std::string name, StoryAction action){ + if (name.empty()){ + throw InternalProgramError(nullptr, PA_CURRENT_FUNCTION, "A story action for any kind needs a name."); + } + const std::string key = name; + if (!m_any_kind.emplace(std::move(name), std::move(action)).second){ + throw InternalProgramError(nullptr, PA_CURRENT_FUNCTION, "A second story action for any kind named " + key); + } +} + +const StoryAction* StoryActionTable::find(StoryStepKind kind, std::string_view name) const{ + const auto kind_iter = m_by_kind.find(kind); + if (kind_iter != m_by_kind.end()){ + if (const StoryAction* exact = find_in(kind_iter->second, name)){ + return exact; + } + } + if (const StoryAction* any_kind = find_in(m_any_kind, name)){ + return any_kind; + } + if (kind_iter != m_by_kind.end()){ + return find_in(kind_iter->second, ""); + } + return nullptr; +} + +const StoryAction* StoryActionTable::find(const StoryStep& step) const{ + return find(step.kind, variant_name(step.variant)); +} + + +std::vector lint_story_checkpoint(const StoryCheckpoint& data, const StoryActionTable& table){ + std::vector problems; + for (size_t c = 0; c < data.steps.size(); c++){ + const StoryStep& step = data.steps[c]; + if (table.find(step) == nullptr){ + problems.emplace_back(std::format( + "{} step {} {}: no action for {} '{}'", + data.id, c + 1, step.name, story_step_kind_name(step.kind), variant_name(step.variant) + )); + } + } + return problems; +} + + +void StepGuard::before_step(const StoryStep&){} + +bool StepGuard::stops_on_failure(const StoryStep&) const{ + return false; +} + +void StepGuard::on_failure(const StoryStep&, const OperationFailedException&){} + + +TableExecutor::TableExecutor(const StoryActionTable& table, StepGuard& guard) + : m_table(table) + , m_guard(guard) +{} + +Outcome TableExecutor::run(RunState& state, const StoryStep& step){ + m_guard.before_step(step); + try{ + if (const StoryAction* action = m_table.find(step)){ + return action->act(state, step); + } + return StoryStepExecutor::run(state, step); + }catch (OperationFailedException& e){ + if (m_guard.stops_on_failure(step)){ + throw; + } + m_guard.on_failure(step, e); + return outcome_failed("operation_failed", e.message()); + } +} + + + +} // namespace Pokemon +} // namespace PokemonAutomation diff --git a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryActions.h b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryActions.h new file mode 100644 index 0000000000..0bd5906ed6 --- /dev/null +++ b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryActions.h @@ -0,0 +1,116 @@ +/* Story Actions + * + * From: https://github.com/PokemonAutomation/ + * + * A game's story steps as a table of actions instead of one virtual per + * kind. An action is keyed by the step's kind and its variant's name + * (variant_name(), Pokemon_StoryVariant.h), so one table holds a game's + * usual way of doing a kind, its other ways, and the steps only it has. + * The console and a simulation bind the same rows to different actions. + * + * TableExecutor runs a step through the table, inside the game's + * StepGuard: the log line, and a failed console step turned into a failed + * Outcome. Today each game writes that guard itself (BDSP's + * StoryExecutor::run(), FRLG's guarded(), PLZA's Executor::run()). + * + */ + +#ifndef PokemonAutomation_Pokemon_StoryActions_H +#define PokemonAutomation_Pokemon_StoryActions_H + +#include +#include +#include +#include +#include +#include "CommonFramework/Exceptions/OperationFailedException.h" +#include "Pokemon_StoryEvents.h" +#include "Pokemon_StorySteps.h" + +namespace PokemonAutomation{ +namespace Pokemon{ + + +// Does `step`, from the run so far. +using StoryActionFunction = std::function; + +// A row of a StoryActionTable: what does a step, and what it needs. +struct StoryAction{ + StoryActionFunction act = {}; + // Moves or reads the console. A binding without one (a simulation) + // can't run it. + bool needs_console = false; + // The screen event the action ends on ("fade", "dialog"). Declared for + // the event-driven waits to come; nothing reads it yet. + std::string waits_for = {}; +}; + + +// A game's actions by step kind and variant name. +class StoryActionTable{ +public: + // The action for steps of `kind` whose variant is named `name`. An + // empty `name` is the kind's default. A second action for the same + // key throws InternalProgramError. + void add(StoryStepKind kind, std::string name, StoryAction action); + // The action for steps of any kind whose variant is named `name`, + // which must not be empty. + void add_any_kind(std::string name, StoryAction action); + + // The action for a step of `kind` with a variant named `name`: the + // one added for both, else the one for `name` of any kind, else the + // kind's default. nullptr if there is none. + const StoryAction* find(StoryStepKind kind, std::string_view name) const; + // find() for the step's kind and its variant's name. + const StoryAction* find(const StoryStep& step) const; + +private: + using ByName = std::map>; + std::map m_by_kind; + ByName m_any_kind; +}; + +// The steps of `data` that `table` has no action for, as +// " step : no action for GAME 'bill'". +std::vector lint_story_checkpoint(const StoryCheckpoint& data, const StoryActionTable& table); + + +// What a game does around every step a TableExecutor runs. Does nothing +// by default, and a failed step fails the step. +class StepGuard{ +public: + virtual ~StepGuard() = default; + + // Before the step runs: e.g. the step's log line. + virtual void before_step(const StoryStep& step); + // Whether a failed step stops the program, leaving the console on the + // failure, instead of failing the step for the segment to reload: the + // rows a developer is fixing. + virtual bool stops_on_failure(const StoryStep& step) const; + // The step threw `error` and fails: e.g. log it and save a screenshot. + virtual void on_failure(const StoryStep& step, const OperationFailedException& error); +}; + + +// Runs each step with the table's action for it, inside `guard`. +class TableExecutor : public StoryStepExecutor{ +public: + // `table` and `guard` must outlive the executor. + TableExecutor(const StoryActionTable& table, StepGuard& guard); + + // The table's action for the step; with none, the kind's virtual + // (StoryStepExecutor::run()), so a game can move to the table one + // kind at a time. An OperationFailedException from either is the + // failed Outcome "operation_failed", unless the guard stops on it. + virtual Outcome run(RunState& state, const StoryStep& step) override; + +private: + const StoryActionTable& m_table; + StepGuard& m_guard; +}; + + + +} // namespace Pokemon +} // namespace PokemonAutomation +#endif diff --git a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryActions_Tests.cpp b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryActions_Tests.cpp new file mode 100644 index 0000000000..851a6ecd03 --- /dev/null +++ b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryActions_Tests.cpp @@ -0,0 +1,384 @@ +/* Story Actions Tests + * + * From: https://github.com/PokemonAutomation/ + * + */ + +#include +#include +#include +#include +#include +#include +#include "Common/Cpp/Exceptions.h" +#include "Common/Cpp/TestRunners/UnitTest.h" +#include "CommonFramework/Exceptions/OperationFailedException.h" +#include "Pokemon_StoryActions.h" +#include "Pokemon_StoryVariant.h" +#include "Pokemon_AutoStory_Tests.h" + +namespace PokemonAutomation{ +namespace Pokemon{ + + +namespace{ + +std::string joined(const std::vector& words){ + std::string out; + for (std::string_view word : words){ + out += "["; + out += word; + out += "]"; + } + return out; +} + +StoryStep make(StoryStepKind kind, std::string name, std::string variant = ""){ + StoryStep step; + step.kind = kind; + step.name = std::move(name); + step.variant = std::move(variant); + return step; +} + +// An action that fails with `name`, so a test sees which one ran. +StoryAction named(std::string name){ + return StoryAction{ + .act = [name](RunState&, const StoryStep&){ + return outcome_failed(name); + }, + }; +} + +// The name of the action the table finds for `kind` and `variant`; "none" +// without one. +std::string found(const StoryActionTable& table, StoryStepKind kind, std::string variant){ + const StoryAction* action = table.find(make(kind, "step", std::move(variant))); + if (action == nullptr){ + return "none"; + } + RunState state; + return action->act(state, make(kind, "step")).failure; +} + + +UnitTestResult test_variant_words(){ + const std::string words = joined(variant_words(" mart PewterCity_Mart budget=2000 ")); + if (words != "[mart][PewterCity_Mart][budget=2000]"){ + return "Expected three words, got " + words; + } + if (!variant_words("").empty() || !variant_words(" ").empty()){ + return "Expected no words in an empty variant."; + } + return true; +} + +UnitTestResult test_variant_pairs(){ + const std::optional pair = variant_pair("budget=2000"); + if (!pair || pair->key != "budget" || pair->value != "2000"){ + return "Expected budget=2000 as a pair."; + } + const std::optional empty_value = variant_pair("door="); + if (!empty_value || empty_value->key != "door" || !empty_value->value.empty()){ + return "Expected door= as a pair with an empty value."; + } + const std::optional two = variant_pair("a=b=c"); + if (!two || two->key != "a" || two->value != "b=c"){ + return "Expected a=b=c split at the first '='."; + } + if (variant_pair("=2000") || variant_pair("mart")){ + return "Expected no pair without a key or an '='."; + } + return true; +} + +UnitTestResult test_variant_name_and_values(){ + if (variant_name(" bill shot=1") != "bill" || !variant_name("shot=1 bill").empty() || !variant_name("").empty()){ + return "Expected the name to be the first word unless it is a pair."; + } + const std::string_view variant = "mart potion=5 budget=2000 potion=9"; + if (variant_value(variant, "potion") != std::optional("5")){ + return "Expected the first potion= value."; + } + if (variant_value(variant, "mart") || variant_value(variant, "repel")){ + return "Expected no value for a plain word or a missing key."; + } + return true; +} + +UnitTestResult test_variant_numbers(){ + if (variant_number("2000") != 2000u || variant_number("0") != 0u || variant_number("999999") != 999999u){ + return "Expected decimal numbers read."; + } + if (variant_number("") || variant_number("12a") || variant_number("-1") || variant_number("1234567")){ + return "Expected no number from empty, non-digit or too long text."; + } + if (variant_number("123", 2) || variant_number("12", 2) != 12u){ + return "Expected max_digits respected."; + } + return true; +} + + +UnitTestResult test_lookup_order(){ + StoryActionTable table; + table.add(StoryStepKind::TALK, "", named("talk default")); + table.add(StoryStepKind::TALK, "bill", named("talk bill")); + table.add_any_kind("bill", named("any bill")); + table.add_any_kind("nurse", named("any nurse")); + const std::pair checks[] = { + {found(table, StoryStepKind::TALK, "bill x=1"), "talk bill"}, + {found(table, StoryStepKind::MASH, "bill"), "any bill"}, + {found(table, StoryStepKind::TALK, "nurse"), "any nurse"}, + {found(table, StoryStepKind::TALK, "oak"), "talk default"}, + {found(table, StoryStepKind::TALK, ""), "talk default"}, + {found(table, StoryStepKind::TALK, "x=1"), "talk default"}, + {found(table, StoryStepKind::MASH, "oak"), "none"}, + {found(table, StoryStepKind::MASH, ""), "none"}, + }; + for (const auto& [actual, expected] : checks){ + if (actual != expected){ + return "Expected " + expected + ", got " + actual; + } + } + return true; +} + +UnitTestResult test_duplicate_actions_throw(){ + StoryActionTable table; + table.add(StoryStepKind::TALK, "bill", named("first")); + table.add_any_kind("bill", named("any")); + const auto throws = [](auto add){ + try{ + add(); + }catch (InternalProgramError&){ + return true; + } + return false; + }; + if (!throws([&]{ table.add(StoryStepKind::TALK, "bill", named("second")); })){ + return "Expected a second TALK 'bill' to throw."; + } + if (!throws([&]{ table.add_any_kind("bill", named("second")); })){ + return "Expected a second any-kind 'bill' to throw."; + } + if (!throws([&]{ table.add_any_kind("", named("nameless")); })){ + return "Expected an any-kind action without a name to throw."; + } + return found(table, StoryStepKind::TALK, "bill") == "first" ? UnitTestResult(true) : UnitTestResult("Expected the first action kept."); +} + +UnitTestResult test_lint_names_steps_without_actions(){ + StoryActionTable table; + table.add(StoryStepKind::ROUTE, "", named("route")); + table.add_any_kind("bill", named("bill")); + const StoryCheckpoint data{ + .id = "00.05", + .title = "", + .start = std::nullopt, + .steps = { + make(StoryStepKind::ROUTE, "to the cape", "costs=grass"), + make(StoryStepKind::GAME, "meet Bill", "bill"), + make(StoryStepKind::GAME, "teleporter", "cell_separator x=1"), + make(StoryStepKind::TALK, "talk"), + }, + }; + const std::vector problems = lint_story_checkpoint(data, table); + const std::vector expected = { + "00.05 step 3 teleporter: no action for GAME 'cell_separator'", + "00.05 step 4 talk: no action for TALK ''", + }; + if (problems != expected){ + std::string got; + for (const std::string& problem : problems){ + got += "\n" + problem; + } + return "Expected two steps without actions, got:" + got; + } + return true; +} + + +// Steps without an action of their own go to this TALK. +class FakeTableExecutor : public TableExecutor{ +public: + using TableExecutor::TableExecutor; + +protected: + virtual Outcome talk(RunState&, const StoryStep&) override{ + return outcome_failed("talk virtual"); + } +}; + +// Writes down what the executor asked of it. +class FakeGuard : public StepGuard{ +public: + std::vector trace; + bool stops = false; + + virtual void before_step(const StoryStep& step) override{ + trace.push_back("before " + step.name); + } + virtual bool stops_on_failure(const StoryStep&) const override{ + return stops; + } + virtual void on_failure(const StoryStep& step, const OperationFailedException& error) override{ + trace.push_back("failed " + step.name + ": " + error.message()); + } +}; + +StoryAction throwing(){ + return StoryAction{ + .act = [](RunState&, const StoryStep&) -> Outcome{ + throw OperationFailedException(ErrorReportMode::NO_ERROR_REPORT, "no dialog"); + }, + .needs_console = true, + }; +} + +UnitTestResult test_executor_uses_table_then_virtuals(){ + StoryActionTable table; + table.add(StoryStepKind::GAME, "bill", named("bill action")); + FakeGuard guard; + FakeTableExecutor executor(table, guard); + RunState state; + const std::string bill = executor.run(state, make(StoryStepKind::GAME, "bill", "bill")).failure; + const std::string talk = executor.run(state, make(StoryStepKind::TALK, "talk")).failure; + const std::string mash = executor.run(state, make(StoryStepKind::MASH, "mash")).failure; + if (bill != "bill action" || talk != "talk virtual" || mash != "unsupported_step"){ + return "Expected table, virtual, unsupported; got " + bill + ", " + talk + ", " + mash; + } + if (guard.trace != std::vector{"before bill", "before talk", "before mash"}){ + return "Expected the guard before every step."; + } + return true; +} + +UnitTestResult test_guard_turns_failures_into_outcomes(){ + StoryActionTable table; + table.add(StoryStepKind::TALK, "", throwing()); + FakeGuard guard; + TableExecutor executor(table, guard); + RunState state; + const Outcome outcome = executor.run(state, make(StoryStepKind::TALK, "oak")); + if (outcome.failure != "operation_failed" || outcome.detail != "no dialog"){ + return "Expected operation_failed: no dialog, got " + to_string(outcome); + } + if (guard.trace != std::vector{"before oak", "failed oak: no dialog"}){ + return "Expected the guard told of the failure."; + } + return true; +} + +UnitTestResult test_guard_stop_rethrows(){ + StoryActionTable table; + table.add(StoryStepKind::TALK, "", throwing()); + table.add(StoryStepKind::MASH, "", StoryAction{ + .act = [](RunState&, const StoryStep&) -> Outcome{ + throw std::runtime_error("not a console failure"); + }, + }); + FakeGuard guard; + guard.stops = true; + TableExecutor executor(table, guard); + RunState state; + try{ + executor.run(state, make(StoryStepKind::TALK, "oak")); + return "Expected a stop row's failure rethrown."; + }catch (OperationFailedException&){} + guard.stops = false; + try{ + executor.run(state, make(StoryStepKind::MASH, "scene")); + return "Expected other exceptions passed through."; + }catch (std::runtime_error&){} + if (guard.trace != std::vector{"before oak", "before scene"}){ + return "Expected no failure reported for a stop or another exception."; + } + return true; +} + + +struct StoryActionsInput{ + std::string_view name; + UnitTestResult (*test)(); +}; + +struct StoryActionsExpectation{ + std::string_view description; +}; + +struct StoryActionsCase{ + StoryActionsInput input; + StoryActionsExpectation expectation; +}; + +class Test_StoryActions : public UnitTest{ +public: + explicit Test_StoryActions(StoryActionsCase scenario) + : UnitTest("Pokemon::StoryActions - " + std::string(scenario.input.name)) + , m_scenario(scenario) + {} + virtual UnitTestResult run(Logger&, CancellableScope&) const override{ + return m_scenario.input.test(); + } + +private: + StoryActionsCase m_scenario; +}; + +const StoryActionsCase STORY_ACTIONS_CASES[] = { + { + .input = {.name = "variant: words split on spaces", .test = test_variant_words}, + .expectation = {.description = "drops empty words between, before and after spaces"}, + }, + { + .input = {.name = "variant: key=value pairs", .test = test_variant_pairs}, + .expectation = {.description = "splits at the first '=', needs a key, allows an empty value"}, + }, + { + .input = {.name = "variant: name and values", .test = test_variant_name_and_values}, + .expectation = {.description = "names the first plain word and reads the first value of a key"}, + }, + { + .input = {.name = "variant: numbers", .test = test_variant_numbers}, + .expectation = {.description = "reads decimal digits only, up to max_digits"}, + }, + { + .input = {.name = "table: exact, then any kind, then the kind's default", .test = test_lookup_order}, + .expectation = {.description = "finds the most specific action, or none"}, + }, + { + .input = {.name = "table: a second action for a key throws", .test = test_duplicate_actions_throw}, + .expectation = {.description = "keeps the first action and rejects nameless any-kind actions"}, + }, + { + .input = {.name = "lint: steps without an action", .test = test_lint_names_steps_without_actions}, + .expectation = {.description = "names each step the table has no action for"}, + }, + { + .input = {.name = "executor: the table, then the kind's virtual", .test = test_executor_uses_table_then_virtuals}, + .expectation = {.description = "falls back to the per-kind virtuals, guarded before every step"}, + }, + { + .input = {.name = "executor: a console failure fails the step", .test = test_guard_turns_failures_into_outcomes}, + .expectation = {.description = "turns OperationFailedException into operation_failed and tells the guard"}, + }, + { + .input = {.name = "executor: a stop row rethrows", .test = test_guard_stop_rethrows}, + .expectation = {.description = "rethrows on a stop row and passes other exceptions through"}, + }, +}; + +} // namespace + + +void add_tests_StoryActions(UnitTestDatabase& database){ + for (const StoryActionsCase& scenario : STORY_ACTIONS_CASES){ + database.add(scenario); + } +} + + + +} // namespace Pokemon +} // namespace PokemonAutomation diff --git a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryVariant.cpp b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryVariant.cpp new file mode 100644 index 0000000000..6df0e9df31 --- /dev/null +++ b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryVariant.cpp @@ -0,0 +1,72 @@ +/* Story Variant + * + * From: https://github.com/PokemonAutomation/ + * + */ + +#include "Pokemon_StoryVariant.h" + +namespace PokemonAutomation{ +namespace Pokemon{ + + +std::vector variant_words(std::string_view text){ + std::vector words; + while (!text.empty()){ + const size_t space = text.find(' '); + const std::string_view word = text.substr(0, space); + if (!word.empty()){ + words.push_back(word); + } + if (space == std::string_view::npos){ + break; + } + text.remove_prefix(space + 1); + } + return words; +} + +std::optional variant_pair(std::string_view word){ + const size_t equals = word.find('='); + if (equals == std::string_view::npos || equals == 0){ + return std::nullopt; + } + return VariantPair{word.substr(0, equals), word.substr(equals + 1)}; +} + +std::string_view variant_name(std::string_view variant){ + const std::vector words = variant_words(variant); + if (words.empty() || variant_pair(words[0])){ + return {}; + } + return words[0]; +} + +std::optional variant_value(std::string_view variant, std::string_view key){ + for (std::string_view word : variant_words(variant)){ + const std::optional pair = variant_pair(word); + if (pair && pair->key == key){ + return pair->value; + } + } + return std::nullopt; +} + +std::optional variant_number(std::string_view text, size_t max_digits){ + if (text.empty() || text.size() > max_digits){ + return std::nullopt; + } + size_t value = 0; + for (char c : text){ + if (c < '0' || c > '9'){ + return std::nullopt; + } + value = value * 10 + size_t(c - '0'); + } + return value; +} + + + +} // namespace Pokemon +} // namespace PokemonAutomation diff --git a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryVariant.h b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryVariant.h new file mode 100644 index 0000000000..f136fa147b --- /dev/null +++ b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryVariant.h @@ -0,0 +1,51 @@ +/* Story Variant + * + * From: https://github.com/PokemonAutomation/ + * + * Reading a step's variant (StoryStep::variant): a name, then words split + * on spaces, some of them "key=value" pairs and small numbers. A table + * writes "mart PewterCity_Mart budget=2000 potion=5"; the name ("mart") + * picks the step's action (Pokemon_StoryActions.h) and the action reads + * the rest. + * + */ + +#ifndef PokemonAutomation_Pokemon_StoryVariant_H +#define PokemonAutomation_Pokemon_StoryVariant_H + +#include +#include +#include +#include + +namespace PokemonAutomation{ +namespace Pokemon{ + + +// `text`'s words, split on spaces, empty words dropped. +std::vector variant_words(std::string_view text); + +// A word "key=value" as its two halves. +struct VariantPair{ + std::string_view key; + std::string_view value; +}; +// `word` split at its first '='; nothing without one or with an empty key. +std::optional variant_pair(std::string_view word); + +// The variant's name: its first word, unless that is a "key=value" pair. +// Empty for an empty variant or one of pairs only. +std::string_view variant_name(std::string_view variant); + +// The value of the first "key=value" word with `key`; nothing if none. +std::optional variant_value(std::string_view variant, std::string_view key); + +// `text` as a number of up to `max_digits` decimal digits; nothing if it +// isn't one. +std::optional variant_number(std::string_view text, size_t max_digits = 6); + + + +} // namespace Pokemon +} // namespace PokemonAutomation +#endif diff --git a/SerialPrograms/cmake/SourceFiles.cmake b/SerialPrograms/cmake/SourceFiles.cmake index d06a8af31a..a75f283568 100644 --- a/SerialPrograms/cmake/SourceFiles.cmake +++ b/SerialPrograms/cmake/SourceFiles.cmake @@ -1503,6 +1503,9 @@ file(GLOB LIBRARY_SOURCES Source/Pokemon/AutoStory/Pokemon_ScreenEvents.cpp Source/Pokemon/AutoStory/Pokemon_ScreenEvents.h Source/Pokemon/AutoStory/Pokemon_ScreenEvents_Tests.cpp + Source/Pokemon/AutoStory/Pokemon_StoryActions.cpp + Source/Pokemon/AutoStory/Pokemon_StoryActions.h + Source/Pokemon/AutoStory/Pokemon_StoryActions_Tests.cpp Source/Pokemon/AutoStory/Pokemon_StoryEvents.cpp Source/Pokemon/AutoStory/Pokemon_StoryEvents.h Source/Pokemon/AutoStory/Pokemon_StoryEvents_Tests.cpp @@ -1512,6 +1515,8 @@ file(GLOB LIBRARY_SOURCES Source/Pokemon/AutoStory/Pokemon_AuthoredCheckpointJson.cpp Source/Pokemon/AutoStory/Pokemon_AuthoredCheckpointJson.h Source/Pokemon/AutoStory/Pokemon_AuthoredCheckpointJson_Tests.cpp + Source/Pokemon/AutoStory/Pokemon_StoryVariant.cpp + Source/Pokemon/AutoStory/Pokemon_StoryVariant.h Source/Pokemon/AutoStory/Pokemon_StoryStepJson.cpp Source/Pokemon/AutoStory/Pokemon_StoryStepJson.h Source/Pokemon/AutoStory/Pokemon_StoryStepJson_Tests.cpp From 3a7e7433a958f9ae741abddfdb3a7d21a448c6fd Mon Sep 17 00:00:00 2001 From: dayfine Date: Mon, 9 Nov 2026 01:54:19 -0800 Subject: [PATCH 020/102] AutoStory: timed screen-event log, interrupt classifier and warp judge ScreenEventLog records when each screen event rose and fell, bounded, counting what it drops; ScreenEventWatcher keeps one. classify_interrupt reads the order of events in a window as a wild encounter, a trainer's sight, a dialog, a warp, or unsettled (a fade too recent to rule out a battle), with the changes it used. Per-game timing is data (InterruptKnobs). judge_warp checks a fade went down, held and came back up on another scene. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_013VUubhHeYSMGSSDXZkKZss --- .../ComputerPrograms_UnitTestRunner.cpp | 1 + .../AutoStory/Pokemon_AutoStory_Tests.h | 2 + .../Pokemon/AutoStory/Pokemon_Interrupts.cpp | 242 ++++++++++++ .../Pokemon/AutoStory/Pokemon_Interrupts.h | 137 +++++++ .../AutoStory/Pokemon_Interrupts_Tests.cpp | 367 ++++++++++++++++++ .../AutoStory/Pokemon_ScreenEvents.cpp | 53 +++ .../Pokemon/AutoStory/Pokemon_ScreenEvents.h | 78 +++- SerialPrograms/cmake/SourceFiles.cmake | 3 + 8 files changed, 881 insertions(+), 2 deletions(-) create mode 100644 SerialPrograms/Source/Pokemon/AutoStory/Pokemon_Interrupts.cpp create mode 100644 SerialPrograms/Source/Pokemon/AutoStory/Pokemon_Interrupts.h create mode 100644 SerialPrograms/Source/Pokemon/AutoStory/Pokemon_Interrupts_Tests.cpp diff --git a/SerialPrograms/Source/ComputerPrograms/ComputerPrograms_UnitTestRunner.cpp b/SerialPrograms/Source/ComputerPrograms/ComputerPrograms_UnitTestRunner.cpp index 922cc58df9..1060aef826 100644 --- a/SerialPrograms/Source/ComputerPrograms/ComputerPrograms_UnitTestRunner.cpp +++ b/SerialPrograms/Source/ComputerPrograms/ComputerPrograms_UnitTestRunner.cpp @@ -79,6 +79,7 @@ UnitTestDatabase make_UNIT_TESTS_ALL(){ Pokemon::add_tests_RuntimeMap(ret); Pokemon::add_tests_RouteLog(ret); Pokemon::add_tests_ScreenEvents(ret); + Pokemon::add_tests_Interrupts(ret); Pokemon::add_tests_StoryActions(ret); Pokemon::add_tests_StoryEvents(ret); Pokemon::add_tests_StorySegments(ret); diff --git a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_AutoStory_Tests.h b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_AutoStory_Tests.h index 8a4abecfe2..ea5a13d757 100644 --- a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_AutoStory_Tests.h +++ b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_AutoStory_Tests.h @@ -17,6 +17,8 @@ namespace Pokemon{ // Registers unit tests for the shared screen events and the judgements over them. void add_tests_ScreenEvents(UnitTestDatabase& database); +// The timed screen-event log, the warp judge and the interrupt classifier. +void add_tests_Interrupts(UnitTestDatabase& database); // Story action tables, the variant parser and the table executor. void add_tests_StoryActions(UnitTestDatabase& database); // Registers unit tests for story event sequencing and execution. diff --git a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_Interrupts.cpp b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_Interrupts.cpp new file mode 100644 index 0000000000..54839a1d8a --- /dev/null +++ b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_Interrupts.cpp @@ -0,0 +1,242 @@ +/* Interrupts + * + * From: https://github.com/PokemonAutomation/ + * + */ + +#include +#include +#include "Pokemon_Interrupts.h" + +namespace PokemonAutomation{ +namespace Pokemon{ + + +const char* warp_judgement_name(WarpJudgement judgement){ + switch (judgement){ + case WarpJudgement::NO_FADE: return "no fade"; + case WarpJudgement::FADE_SHOWING: return "fade still showing"; + case WarpJudgement::TOO_SHORT: return "fade too short"; + case WarpJudgement::SAME_SCENE: return "same scene after the fade"; + case WarpJudgement::WARPED: return "warped"; + } + return "?"; +} + +const char* interrupt_kind_name(InterruptKind kind){ + switch (kind){ + case InterruptKind::NONE: return "none"; + case InterruptKind::WILD_ENCOUNTER: return "wild encounter"; + case InterruptKind::TRAINER_SIGHT: return "trainer sight"; + case InterruptKind::DIALOG: return "dialog"; + case InterruptKind::WARP: return "warp"; + case InterruptKind::UNSETTLED: return "unsettled"; + } + return "?"; +} + + +namespace{ + +using Changes = std::vector; + +Changes changes_in(const ScreenEventLog& log, InterruptWindow window){ + Changes out; + for (const ScreenEventChange& change : log.changes()){ + if (window.start <= change.time && change.time <= window.end){ + out.push_back(change); + } + } + return out; +} + +bool rose(const ScreenEventChange& change, ScreenEvent event){ + return change.event == event && change.edge == ScreenEventEdge::ROSE; +} +bool fade_rose(const ScreenEventChange& change){ + return rose(change, ScreenEvent::FADE_BLACK) || rose(change, ScreenEvent::FADE_WHITE); +} + +// The first rise of `event`, if any. +std::optional first_rise(const Changes& changes, ScreenEvent event){ + for (const ScreenEventChange& change : changes){ + if (rose(change, event)){ + return change; + } + } + return std::nullopt; +} + +// The last fade that went down, and when it came back up. +std::optional last_fade(const Changes& changes){ + std::optional out; + for (const ScreenEventChange& change : changes){ + if (fade_rose(change)){ + out = FadeSpan{fade_in({change.event}), change.time, std::nullopt}; + }else if (out && !out->up && change.edge == ScreenEventEdge::FELL && fade_events(out->fade).has(change.event)){ + out->up = change.time; + } + } + return out; +} + +ScreenEvent fade_event(WarpFade fade){ + return fade == WarpFade::WHITE ? ScreenEvent::FADE_WHITE : ScreenEvent::FADE_BLACK; +} +void add_fade_evidence(Changes& evidence, const FadeSpan& fade){ + evidence.push_back({fade.down, fade_event(fade.fade), ScreenEventEdge::ROSE}); + if (fade.up){ + evidence.push_back({*fade.up, fade_event(fade.fade), ScreenEventEdge::FELL}); + } +} + + +// A battle, and whose. The battle's fade is the last one that went down +// no more than battle_after_fade before it; a box that rose before that +// fade (or before the battle, with no fade) is a trainer's lines. A box +// after the fade is the battle's own opening text. +std::optional battle_verdict(const Changes& changes, const InterruptKnobs& knobs){ + const std::optional battle = first_rise(changes, ScreenEvent::BATTLE_STARTED); + if (!battle){ + return std::nullopt; + } + std::optional fade; + for (const ScreenEventChange& change : changes){ + if (change.time > battle->time){ + break; + } + if (fade_rose(change) && battle->time - change.time <= knobs.battle_after_fade){ + fade = change; + } + } + const WallClock cut = fade ? fade->time : battle->time; + std::optional lines; + for (const ScreenEventChange& change : changes){ + if (change.time >= cut){ + break; + } + if (rose(change, ScreenEvent::DIALOG_BOX) && cut - change.time <= knobs.sight_lines_lead){ + lines = change; + break; + } + } + InterruptVerdict out{lines ? InterruptKind::TRAINER_SIGHT : InterruptKind::WILD_ENCOUNTER, {}, false}; + for (const std::optional& change : {lines, fade, battle}){ + if (change){ + out.evidence.push_back(*change); + } + } + return out; +} + +// A warp: a banner, or a fade back up with no battle after it for +// battle_after_fade. A fade still showing, or back up too recently, may +// yet be an encounter's flash. +std::optional warp_verdict( + const ScreenEventLog& log, InterruptWindow window, const Changes& changes, const InterruptKnobs& knobs +){ + const WarpVerdict warp = judge_warp(log, window, knobs, SceneChange::UNKNOWN); + const std::optional banner = first_rise(changes, ScreenEvent::LOCATION_BANNER); + InterruptVerdict out{InterruptKind::WARP, {}, false}; + if (warp.fade && warp.judgement != WarpJudgement::TOO_SHORT){ + add_fade_evidence(out.evidence, *warp.fade); + } + if (banner){ + out.evidence.push_back(*banner); + std::stable_sort(out.evidence.begin(), out.evidence.end(), [](const auto& a, const auto& b){ + return a.time < b.time; + }); + return out; + } + switch (warp.judgement){ + case WarpJudgement::FADE_SHOWING: + out.kind = InterruptKind::UNSETTLED; + return out; + case WarpJudgement::WARPED:{ + const WallClock seen_until = std::min(window.end, log.last_frame().value_or(window.end)); + if (seen_until - *warp.fade->up < knobs.battle_after_fade){ + out.kind = InterruptKind::UNSETTLED; + } + return out; + } + case WarpJudgement::NO_FADE: + case WarpJudgement::TOO_SHORT: + case WarpJudgement::SAME_SCENE: + break; + } + return std::nullopt; +} + +std::optional dialog_verdict(const Changes& changes){ + const std::optional box = first_rise(changes, ScreenEvent::DIALOG_BOX); + if (!box){ + return std::nullopt; + } + return InterruptVerdict{InterruptKind::DIALOG, {*box}, false}; +} + +} // namespace + + +WarpVerdict judge_warp( + const ScreenEventLog& log, InterruptWindow window, + const InterruptKnobs& knobs, SceneChange change +){ + WarpVerdict out{WarpJudgement::NO_FADE, last_fade(changes_in(log, window))}; + if (!out.fade){ + return out; + } + if (!out.fade->up){ + out.judgement = WarpJudgement::FADE_SHOWING; + }else if (*out.fade->up - out.fade->down < knobs.min_fade_hold){ + out.judgement = WarpJudgement::TOO_SHORT; + }else if (change == SceneChange::SAME){ + out.judgement = WarpJudgement::SAME_SCENE; + }else{ + out.judgement = WarpJudgement::WARPED; + } + return out; +} + + +std::string describe(const InterruptVerdict& verdict, WallClock origin){ + std::string out = interrupt_kind_name(verdict.kind); + const char* separator = ": "; + for (const ScreenEventChange& change : verdict.evidence){ + out += std::format( + "{}{:+} ms {} {}", + separator, + std::chrono::duration_cast(change.time - origin).count(), + screen_event_name(change.event), + change.edge == ScreenEventEdge::ROSE ? "rose" : "fell" + ); + separator = ", "; + } + if (verdict.log_truncated){ + out += " (log truncated)"; + } + return out; +} + + +InterruptVerdict classify_interrupt( + const ScreenEventLog& log, InterruptWindow window, const InterruptKnobs& knobs +){ + const Changes changes = changes_in(log, window); + std::optional verdict = battle_verdict(changes, knobs); + if (!verdict){ + verdict = warp_verdict(log, window, changes, knobs); + } + if (!verdict){ + verdict = dialog_verdict(changes); + } + InterruptVerdict out = verdict.value_or(InterruptVerdict{}); + out.log_truncated = log.dropped() > 0 && + (log.changes().empty() || window.start <= log.changes().front().time); + return out; +} + + + +} // namespace Pokemon +} // namespace PokemonAutomation diff --git a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_Interrupts.h b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_Interrupts.h new file mode 100644 index 0000000000..c1050f3abf --- /dev/null +++ b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_Interrupts.h @@ -0,0 +1,137 @@ +/* Interrupts + * + * From: https://github.com/PokemonAutomation/ + * + * What stopped the player, judged from the order of screen events + * (ScreenEventLog), the same way for every game: a wild encounter, a + * trainer's sight, a dialog, a warp. One frame cannot tell them apart; the + * order can. A white flash then a battle is an encounter, a white fade with + * no battle after it a cave exit (BDSP's walk fled one as a battle, #268); + * a box then a flash then a battle is a trainer's lines; a flash then a box + * then a battle is a wild battle's opening text. + * + * Games differ in timing only, so they pass their numbers (InterruptKnobs) + * rather than their own classifier. + * + */ + +#ifndef PokemonAutomation_Pokemon_Interrupts_H +#define PokemonAutomation_Pokemon_Interrupts_H + +#include +#include +#include +#include "Common/Cpp/Time.h" +#include "Pokemon_ScreenEvents.h" + +namespace PokemonAutomation{ +namespace Pokemon{ + + +// A game's timing, as data. +struct InterruptKnobs{ + // A fade must hold this long to be a warp's. One uniform frame is enough + // by default: a 50 ms fade can show on one frame only. + Milliseconds min_fade_hold = Milliseconds(0); + // A battle that shows this soon after a fade ends is that fade's + // encounter, and a fade is no warp before this has passed with no + // battle. BDSP's encounter flash shows its battle within 8 s + // (WHITE_FLASH_BATTLE_WAIT in its walk). + Milliseconds battle_after_fade = Milliseconds(8000); + // A dialog box that rose this long or less before a battle's fade is a + // trainer's lines. A trainer's lines can pause more than 4 s before the + // battle (BDSP r210d), and a trainer may say several boxes. + Milliseconds sight_lines_lead = Milliseconds(20000); +}; + +// The span of the log to judge: changes at `start` or later, and no later +// than `end`. +struct InterruptWindow{ + WallClock start = {}; + WallClock end = {}; +}; + + +// How a fade looked, for the warp judge. +struct FadeSpan{ + WarpFade fade = WarpFade::NONE; + WallClock down = {}; + // When the screen came back; none while it still shows the fade. + std::optional up = {}; +}; + +// Whether the screen differs after a fade from before it. The log has no +// images; the caller compares the frames, or says it did not. +enum class SceneChange{ + UNKNOWN, + SAME, + DIFFERENT, +}; + +// What the warp judge made of a fade. +enum class WarpJudgement{ + NO_FADE, // No fade went down in the window. + FADE_SHOWING, // It went down and has not come back up. + TOO_SHORT, // It came back up before min_fade_hold. + SAME_SCENE, // It came back up on the scene it left. + WARPED, // Down, held, back up; not on the same scene. +}; +// "fade too short", for the log. +const char* warp_judgement_name(WarpJudgement judgement); + +// The warp judge's verdict and the fade it judged. +struct WarpVerdict{ + WarpJudgement judgement = WarpJudgement::NO_FADE; + // The last fade that went down in the window, if any. + std::optional fade = {}; +}; + +// A warp is a fade going down, holding uniform, and coming back up on +// another scene. The last fade that went down in `window` is judged; a +// LOCATION_BANNER does not count here (WarpSeen does). `change` is what +// the caller saw of the scene before and after: UNKNOWN does not rule the +// warp out. This judges the fade only: a battle after it is +// classify_interrupt()'s question. +WarpVerdict judge_warp( + const ScreenEventLog& log, InterruptWindow window, + const InterruptKnobs& knobs, SceneChange change +); + + +// What stopped the player. +enum class InterruptKind{ + NONE, + WILD_ENCOUNTER, // A battle with no trainer's lines before it. + TRAINER_SIGHT, // A dialog box, then a battle. + DIALOG, // A dialog box and no battle. + WARP, // A fade back up with no battle after it, or a banner. + UNSETTLED, // A fade, too recent to know if a battle follows. +}; +// "trainer sight", for the log. +const char* interrupt_kind_name(InterruptKind kind); + +// What stopped the player, and the evidence for it. +struct InterruptVerdict{ + InterruptKind kind = InterruptKind::NONE; + // The changes it was judged on, in order. + std::vector evidence = {}; + // The log dropped changes the window reaches back to: the verdict may + // miss what came first. + bool log_truncated = false; +}; +// "wild encounter: +0 ms white fade rose, +3400 ms battle started rose", +// times from `origin`. +std::string describe(const InterruptVerdict& verdict, WallClock origin); + +// What interrupted the player in `window` of `log`. Order of precedence: a +// battle, then a warp, then a dialog. Only events that rose in the window +// count: a box already up when it starts is not this interrupt's. +InterruptVerdict classify_interrupt( + const ScreenEventLog& log, InterruptWindow window, const InterruptKnobs& knobs +); + + + +} // namespace Pokemon +} // namespace PokemonAutomation +#endif diff --git a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_Interrupts_Tests.cpp b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_Interrupts_Tests.cpp new file mode 100644 index 0000000000..6622da1d90 --- /dev/null +++ b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_Interrupts_Tests.cpp @@ -0,0 +1,367 @@ +/* Interrupts Tests + * + * From: https://github.com/PokemonAutomation/ + * + * The timed screen-event log, the warp judge and the interrupt classifier, + * driven by synthetic scenes: a frame's events at a time. + * + */ + +#include +#include +#include +#include +#include +#include "Common/Cpp/TestRunners/UnitTest.h" +#include "CommonFramework/ImageTypes/ImageRGB32.h" +#include "Pokemon_AutoStory_Tests.h" +#include "Pokemon_Interrupts.h" +#include "Pokemon_ScreenEvents.h" + +namespace PokemonAutomation{ +namespace Pokemon{ + +namespace{ + +using namespace std::chrono_literals; + +const WallClock T0 = WallClock() + std::chrono::hours(1); + +UnitTestResult expect_equal(const std::string& what, const std::string& got, const std::string& expected){ + if (got == expected){ + return true; + } + return std::format("{}: expected \"{}\", got \"{}\"", what, expected, got); +} + +// One frame of a synthetic scene: its events, at `ms` after T0. +struct Frame{ + int ms; + ScreenEvents events; +}; + +// A log of `frames`, then the same as the last one every 500 ms until +// `until_ms` (a walk's screen, looked at while nothing changes). +ScreenEventLog log_of(const std::vector& frames, int until_ms, size_t capacity = SCREEN_EVENT_LOG_CAPACITY){ + ScreenEventLog log(capacity); + for (const Frame& frame : frames){ + log.record(frame.events, T0 + Milliseconds(frame.ms)); + } + const ScreenEvents last = frames.empty() ? ScreenEvents() : frames.back().events; + for (int ms = frames.empty() ? 0 : frames.back().ms + 500; ms <= until_ms; ms += 500){ + log.record(last, T0 + Milliseconds(ms)); + } + return log; +} + +const ScreenEvents WALK{ScreenEvent::PLAYER_CAN_MOVE}; +const ScreenEvents BLACK{ScreenEvent::FADE_BLACK}; +const ScreenEvents WHITE{ScreenEvent::FADE_WHITE}; +const ScreenEvents BOX{ScreenEvent::DIALOG_BOX, ScreenEvent::PLAYER_CAN_MOVE}; +const ScreenEvents BATTLE{ScreenEvent::BATTLE_STARTED}; +const ScreenEvents BATTLE_TEXT{ScreenEvent::DIALOG_BOX}; +const ScreenEvents BANNER{ScreenEvent::LOCATION_BANNER, ScreenEvent::PLAYER_CAN_MOVE}; + +InterruptWindow whole(int until_ms){ + return {T0, T0 + Milliseconds(until_ms)}; +} + + +UnitTestResult test_log_records_rises_and_falls(){ + const ScreenEventLog log = log_of({ + {0, WALK}, + {100, WALK}, + {200, BLACK}, + {450, ScreenEvents{ScreenEvent::LOCATION_BANNER, ScreenEvent::PLAYER_CAN_MOVE}}, + }, 450); + if (log.showing() != BANNER || log.last_frame() != T0 + 450ms || log.dropped() != 0){ + return "the log's last frame is not the banner frame at +450 ms"; + } + return expect_equal("describe(log)", describe(log, T0), + "+0 ms player can move rose\n" + "+200 ms black fade rose\n" + "+200 ms player can move fell\n" + "+450 ms black fade fell\n" + "+450 ms location banner rose\n" + "+450 ms player can move rose\n" + ); +} + +UnitTestResult test_log_overflow_and_clear(){ + ScreenEventLog log = log_of({{0, WALK}, {100, BOX}, {200, WALK}, {300, BOX}, {400, WALK}}, 400, 3); + if (log.changes().size() != 3 || log.dropped() != 2){ + return std::format("expected 3 kept and 2 dropped, got {} and {}", log.changes().size(), log.dropped()); + } + if (log.changes().front() != ScreenEventChange{T0 + 200ms, ScreenEvent::DIALOG_BOX, ScreenEventEdge::FELL}){ + return "the oldest change kept is not the box falling at +200 ms"; + } + const InterruptVerdict early = classify_interrupt(log, whole(400), {}); + const InterruptVerdict late = classify_interrupt(log, {T0 + 250ms, T0 + 400ms}, {}); + if (!early.log_truncated || late.log_truncated){ + return "only a window reaching back past the kept changes is truncated"; + } + UnitTestResult result = expect_equal("truncated verdict", describe(early, T0), "dialog: +300 ms dialog box rose (log truncated)"); + if (result.result != UnitTestResult::PASSED){ + return result; + } + log.clear(); + if (!log.changes().empty() || log.dropped() != 0 || log.last_frame() || log.showing() != ScreenEvents()){ + return "clear() did not empty the log"; + } + return true; +} + +UnitTestResult test_empty_log(){ + const ScreenEventLog log; + const InterruptVerdict verdict = classify_interrupt(log, whole(1000), {}); + if (judge_warp(log, whole(1000), {}, SceneChange::DIFFERENT).judgement != WarpJudgement::NO_FADE){ + return "an empty log has a fade"; + } + return expect_equal("empty log", describe(verdict, T0), "none"); +} + + +UnitTestResult test_judge_warp(){ + struct Row{ + const char* name; + std::vector frames; + SceneChange change; + WarpJudgement expected; + }; + const std::vector rows = { + {"down, held, back up on another scene", {{0, WALK}, {1000, BLACK}, {1400, WALK}}, SceneChange::DIFFERENT, WarpJudgement::WARPED}, + {"no frame compare does not rule it out", {{0, WALK}, {1000, BLACK}, {1400, WALK}}, SceneChange::UNKNOWN, WarpJudgement::WARPED}, + {"back on the same scene", {{0, WALK}, {1000, BLACK}, {1400, WALK}}, SceneChange::SAME, WarpJudgement::SAME_SCENE}, + {"a flicker", {{0, WALK}, {1000, BLACK}, {1050, WALK}}, SceneChange::DIFFERENT, WarpJudgement::TOO_SHORT}, + {"still dark", {{0, WALK}, {1000, BLACK}}, SceneChange::UNKNOWN, WarpJudgement::FADE_SHOWING}, + {"no fade", {{0, WALK}, {1000, BOX}}, SceneChange::DIFFERENT, WarpJudgement::NO_FADE}, + }; + const InterruptKnobs knobs{.min_fade_hold = 200ms}; + for (const Row& row : rows){ + const ScreenEventLog log = log_of(row.frames, 3000); + const WarpJudgement got = judge_warp(log, whole(3000), knobs, row.change).judgement; + if (got != row.expected){ + return std::format("{}: expected {}, got {}", row.name, warp_judgement_name(row.expected), warp_judgement_name(got)); + } + } + return true; +} + + +// Replays a fixed list of event sets, one per frame. +class ScriptedObserver : public ScreenEventObserver{ +public: + explicit ScriptedObserver(std::vector frames) + : m_frames(std::move(frames)) + {} + virtual ScreenEvents observe(const VideoSnapshot&, WallClock) override{ + return m_next < m_frames.size() ? m_frames[m_next++] : ScreenEvents(); + } + virtual void make_overlays(VideoOverlaySet&) const override{} + +private: + std::vector m_frames; + size_t m_next = 0; +}; + +UnitTestResult test_watcher_log(){ + ScriptedObserver observer({WALK, WHITE, WALK}); + ScreenEventWatcher watcher(observer); + for (int c = 0; c < 3; c++){ + watcher.process_frame(VideoSnapshot(ImageRGB32(4, 4), T0 + Milliseconds(100 * c))); + } + UnitTestResult result = expect_equal("watcher log", describe(watcher.log(), T0), + "+0 ms player can move rose\n" + "+100 ms white fade rose\n" + "+100 ms player can move fell\n" + "+200 ms white fade fell\n" + "+200 ms player can move rose\n" + ); + if (result.result != UnitTestResult::PASSED){ + return result; + } + watcher.reset(); + return expect_equal("watcher log after reset()", describe(watcher.log(), T0), "no changes"); +} + + +struct InterruptsInput{ + std::string name; + std::function body; +}; + +struct InterruptsExpectation{ +}; + +struct InterruptsCase{ + InterruptsInput input; + InterruptsExpectation expectation; +}; + +class Test_Interrupts : public UnitTest{ +public: + explicit Test_Interrupts(InterruptsCase test_case) + : UnitTest("Pokemon::Interrupts - " + test_case.input.name) + , m_case(std::move(test_case)) + {} + virtual UnitTestResult run(Logger&, CancellableScope&) const override{ + return m_case.input.body(); + } + +private: + InterruptsCase m_case; +}; + + +// A synthetic scene, and the window of it to judge. +struct ClassifyInput{ + std::string name; + std::vector frames; + int until_ms = 0; + InterruptKnobs knobs = {}; + int window_from_ms = 0; +}; + +struct ClassifyExpectation{ + // describe(verdict, T0). + std::string verdict; +}; + +struct ClassifyCase{ + ClassifyInput input; + ClassifyExpectation expectation; +}; + +class Test_InterruptClassify : public UnitTest{ +public: + explicit Test_InterruptClassify(ClassifyCase test_case) + : UnitTest("Pokemon::Interrupts - classify: " + test_case.input.name) + , m_case(std::move(test_case)) + {} + virtual UnitTestResult run(Logger&, CancellableScope&) const override{ + const ClassifyInput& input = m_case.input; + const ScreenEventLog log = log_of(input.frames, input.until_ms); + const InterruptWindow window{T0 + Milliseconds(input.window_from_ms), T0 + Milliseconds(input.until_ms)}; + const InterruptVerdict verdict = classify_interrupt(log, window, input.knobs); + return expect_equal("verdict", describe(verdict, T0), m_case.expectation.verdict); + } + +private: + ClassifyCase m_case; +}; + +} // namespace + + +const InterruptsCase INTERRUPTS_CASES[] = { + { + .input = {"the log keeps rises and falls in order, timed", test_log_records_rises_and_falls}, + .expectation = {}, + }, + { + .input = {"a full log drops its oldest changes and says so", test_log_overflow_and_clear}, + .expectation = {}, + }, + { + .input = {"an empty log is no interrupt and no fade", test_empty_log}, + .expectation = {}, + }, + { + .input = {"a warp is down, held, back up, not the same scene", test_judge_warp}, + .expectation = {}, + }, + { + .input = {"a watcher keeps a timed log", test_watcher_log}, + .expectation = {}, + }, +}; + +const ClassifyCase CLASSIFY_CASES[] = { + { + .input = {"an encounter's white flash, then the battle", + {{0, WALK}, {1000, WHITE}, {1300, ScreenEvents()}, {3000, BATTLE}}, 3000}, + .expectation = {"wild encounter: +1000 ms white fade rose, +3000 ms battle started rose"}, + }, + { + .input = {"a wild battle's opening text comes after its flash", + {{0, WALK}, {1000, WHITE}, {1300, BATTLE_TEXT}, {2500, BATTLE}}, 2500}, + .expectation = {"wild encounter: +1000 ms white fade rose, +2500 ms battle started rose"}, + }, + { + .input = {"a trainer's lines, a pause, the battle's fade", + {{0, WALK}, {1000, BOX}, {2000, WALK}, {6000, BLACK}, {6400, BATTLE}}, 6400}, + .expectation = {"trainer sight: +1000 ms dialog box rose, +6000 ms black fade rose, +6400 ms battle started rose"}, + }, + { + .input = {"a trainer's lines, then the battle with no fade seen", + {{0, WALK}, {1000, BOX}, {2000, BATTLE}}, 2000}, + .expectation = {"trainer sight: +1000 ms dialog box rose, +2000 ms battle started rose"}, + }, + { + .input = {"a box and no battle", {{0, WALK}, {1000, BOX}}, 20000}, + .expectation = {"dialog: +1000 ms dialog box rose"}, + }, + { + .input = {"a cave exit's white fade, and no battle for 8 s", + {{0, WALK}, {1000, WHITE}, {1600, WALK}}, 12000}, + .expectation = {"warp: +1000 ms white fade rose, +1600 ms white fade fell"}, + }, + { + .input = {"a white fade too recent to rule out a battle", + {{0, WALK}, {1000, WHITE}, {1600, WALK}}, 4000}, + .expectation = {"unsettled: +1000 ms white fade rose, +1600 ms white fade fell"}, + }, + { + .input = {"a fade still showing", {{0, WALK}, {1000, BLACK}}, 3000}, + .expectation = {"unsettled: +1000 ms black fade rose"}, + }, + { + .input = {"a banner after the white settles it at once", + {{0, WALK}, {1000, WHITE}, {1600, WALK}, {2000, BANNER}}, 2500}, + .expectation = {"warp: +1000 ms white fade rose, +1600 ms white fade fell, +2000 ms location banner rose"}, + }, + { + .input = {"a box during a fade is the scene cut's", + {{0, WALK}, {1000, BLACK}, {1300, ScreenEvents{ScreenEvent::FADE_BLACK, ScreenEvent::DIALOG_BOX}}, + {1800, BOX}, {3000, WALK}}, 12000}, + .expectation = {"warp: +1000 ms black fade rose, +1800 ms black fade fell"}, + }, + { + .input = {"a door's fade long before a battle is not the battle's", + {{0, WALK}, {500, BLACK}, {900, WALK}, {20000, BATTLE}}, 20000}, + .expectation = {"wild encounter: +20000 ms battle started rose"}, + }, + { + .input = {"a box up before the window is not this interrupt's", + {{0, BOX}, {1000, WALK}, {3000, WHITE}, {3300, WALK}, {5000, BATTLE}}, 5000, {}, 500}, + .expectation = {"wild encounter: +3000 ms white fade rose, +5000 ms battle started rose"}, + }, + { + .input = {"a one-frame flicker is no fade with a hold to meet", + {{0, WALK}, {1000, BLACK}, {1050, WALK}}, 12000, {.min_fade_hold = 200ms}}, + .expectation = {"none"}, + }, + { + .input = {"a one-frame fade is a warp by default", + {{0, WALK}, {1000, BLACK}, {1050, WALK}}, 12000}, + .expectation = {"warp: +1000 ms black fade rose, +1050 ms black fade fell"}, + }, + { + .input = {"a walk with nothing in it", {{0, WALK}}, 5000}, + .expectation = {"none"}, + }, +}; + +void add_tests_Interrupts(UnitTestDatabase& database){ + for (const auto& item : INTERRUPTS_CASES){ + database.add(item); + } + for (const auto& item : CLASSIFY_CASES){ + database.add(item); + } +} + + + +} // namespace Pokemon +} // namespace PokemonAutomation diff --git a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_ScreenEvents.cpp b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_ScreenEvents.cpp index d8ea3b5beb..e80ed6161f 100644 --- a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_ScreenEvents.cpp +++ b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_ScreenEvents.cpp @@ -4,6 +4,7 @@ * */ +#include #include "CommonFramework/ImageTools/ImageBoxes.h" #include "CommonFramework/ImageTypes/ImageRGB32.h" #include "Pokemon_ScreenEvents.h" @@ -104,6 +105,48 @@ WarpFade fade_of_screen(const ImageViewRGB32& screen){ } +ScreenEventLog::ScreenEventLog(size_t capacity) + : m_capacity(capacity) +{} +void ScreenEventLog::record(const ScreenEvents& frame, WallClock now){ + const uint32_t changed = frame.bits() ^ m_showing.bits(); + for (size_t c = 0; c < SCREEN_EVENT_COUNT; c++){ + if ((changed & (uint32_t(1) << c)) == 0){ + continue; + } + const ScreenEvent event = (ScreenEvent)c; + m_changes.push_back({now, event, frame.has(event) ? ScreenEventEdge::ROSE : ScreenEventEdge::FELL}); + } + while (m_changes.size() > m_capacity){ + m_changes.pop_front(); + m_dropped++; + } + m_showing = frame; + m_last_frame = now; +} +void ScreenEventLog::clear(){ + m_changes.clear(); + m_dropped = 0; + m_showing = ScreenEvents(); + m_last_frame.reset(); +} +std::string describe(const ScreenEventLog& log, WallClock origin){ + std::string out; + if (log.dropped() > 0){ + out += std::format("({} older changes dropped)\n", log.dropped()); + } + for (const ScreenEventChange& change : log.changes()){ + out += std::format( + "{:+} ms {} {}\n", + std::chrono::duration_cast(change.time - origin).count(), + screen_event_name(change.event), + change.edge == ScreenEventEdge::ROSE ? "rose" : "fell" + ); + } + return out.empty() ? "no changes" : out; +} + + ScreenEventWatcher::ScreenEventWatcher(ScreenEventObserver& observer, ScreenEvents stop_on) : VisualInferenceCallback("ScreenEventWatcher") , m_observer(observer) @@ -115,15 +158,25 @@ void ScreenEventWatcher::make_overlays(VideoOverlaySet& items) const{ bool ScreenEventWatcher::process_frame(const VideoSnapshot& frame){ const ScreenEvents events = m_observer.observe(frame, frame.timestamp); m_seen.fetch_or(events.bits(), std::memory_order_acq_rel); + { + LockGuard lg(m_log_lock); + m_log.record(events, frame.timestamp); + } if (!events.any_of(m_stop_on)){ return false; } m_stopped_on.store(events.bits(), std::memory_order_release); return true; } +ScreenEventLog ScreenEventWatcher::log() const{ + LockGuard lg(m_log_lock); + return m_log; +} void ScreenEventWatcher::reset(){ m_seen.store(0, std::memory_order_release); m_stopped_on.store(0, std::memory_order_release); + LockGuard lg(m_log_lock); + m_log.clear(); } diff --git a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_ScreenEvents.h b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_ScreenEvents.h index 1bf6ca6649..cd633e0f60 100644 --- a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_ScreenEvents.h +++ b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_ScreenEvents.h @@ -18,8 +18,11 @@ #include #include +#include #include +#include #include +#include "Common/Cpp/Concurrency/Mutex.h" #include "Common/Cpp/Time.h" #include "CommonFramework/ImageTools/ImageStats.h" #include "CommonFramework/ImageTypes/ImageViewRGB32.h" @@ -118,6 +121,71 @@ WarpFade fade_of(const ImageStats& middle); WarpFade fade_of_screen(const ImageViewRGB32& screen); +// Whether an event started or stopped showing. +enum class ScreenEventEdge : uint8_t{ + ROSE, + FELL, +}; + +// One event starting or stopping to show, at the frame that showed it. +struct ScreenEventChange{ + WallClock time; + ScreenEvent event; + ScreenEventEdge edge; + + bool operator==(const ScreenEventChange& other) const = default; +}; + +// How many changes a log keeps. A walk's events change a few times a +// second at most (a fade's black, a box, the screen going still), so this +// is a minute or more of a busy scene. +constexpr size_t SCREEN_EVENT_LOG_CAPACITY = 256; + +// The events of a stream of frames, in order and timed: what rose and fell +// when, not only what was seen (ScreenEventWatcher::seen()). The judges that +// care about order read it (Pokemon_Interrupts.h): a flash then a battle is +// an encounter, a box then a battle a trainer's sight. +// +// It keeps the newest `capacity` changes and counts the ones it dropped. +// Not thread-safe; ScreenEventWatcher guards its own. +class ScreenEventLog{ +public: + explicit ScreenEventLog(size_t capacity = SCREEN_EVENT_LOG_CAPACITY); + + // Adds a frame: a change for each event that rose or fell since the + // frame before (the first frame's events all rise). `now` must not go + // back in time. + void record(const ScreenEvents& frame, WallClock now); + + // The changes kept, oldest first. + const std::deque& changes() const{ + return m_changes; + } + // How many changes were dropped, oldest first, to keep the capacity. + size_t dropped() const{ + return m_dropped; + } + // The events of the last frame recorded. + ScreenEvents showing() const{ + return m_showing; + } + // When the last frame was recorded; none before the first. + std::optional last_frame() const{ + return m_last_frame; + } + void clear(); + +private: + size_t m_capacity; + std::deque m_changes; + size_t m_dropped = 0; + ScreenEvents m_showing; + std::optional m_last_frame; +}; +// "+1200 ms dialog box rose", times from `origin`, one change per line. +std::string describe(const ScreenEventLog& log, WallClock origin); + + // A game's detectors, as events. Observers may keep state between frames // (the frame before, for SCREEN_STILL; when a banner was last read, to // gate OCR), so one observer watches one stream at a time. @@ -134,8 +202,9 @@ class ScreenEventObserver{ }; -// An observer as a run_until callback: it records every event it sees and -// stops the action on any of `stop_on` (none: it only records). +// An observer as a run_until callback: it records every event it sees, in +// order in a log, and stops the action on any of `stop_on` (none: it only +// records). class ScreenEventWatcher : public VisualInferenceCallback{ public: ScreenEventWatcher(ScreenEventObserver& observer, ScreenEvents stop_on = {}); @@ -152,6 +221,9 @@ class ScreenEventWatcher : public VisualInferenceCallback{ ScreenEvents stopped_on() const{ return ScreenEvents::from_bits(m_stopped_on.load(std::memory_order_acquire)); } + // A copy of the timed log of every frame since construction (or the + // last reset()). + ScreenEventLog log() const; void reset(); private: @@ -159,6 +231,8 @@ class ScreenEventWatcher : public VisualInferenceCallback{ const ScreenEvents m_stop_on; std::atomic m_seen{0}; std::atomic m_stopped_on{0}; + mutable Mutex m_log_lock; + ScreenEventLog m_log; }; diff --git a/SerialPrograms/cmake/SourceFiles.cmake b/SerialPrograms/cmake/SourceFiles.cmake index a75f283568..4c92b891e2 100644 --- a/SerialPrograms/cmake/SourceFiles.cmake +++ b/SerialPrograms/cmake/SourceFiles.cmake @@ -1498,6 +1498,9 @@ file(GLOB LIBRARY_SOURCES Source/Pokemon/AutoStory/Pokemon_AutoStorySelect_Tests.h Source/Pokemon/AutoStory/Pokemon_AutoStoryStats.h Source/Pokemon/AutoStory/Pokemon_AutoStory_Tests.h + Source/Pokemon/AutoStory/Pokemon_Interrupts.cpp + Source/Pokemon/AutoStory/Pokemon_Interrupts.h + Source/Pokemon/AutoStory/Pokemon_Interrupts_Tests.cpp Source/Pokemon/AutoStory/Pokemon_SceneJudges.cpp Source/Pokemon/AutoStory/Pokemon_SceneJudges.h Source/Pokemon/AutoStory/Pokemon_ScreenEvents.cpp From 46b688e790d76b87ee6091206be269ab0864aa7f Mon Sep 17 00:00:00 2001 From: dayfine Date: Mon, 9 Nov 2026 02:08:21 -0800 Subject: [PATCH 021/102] AutoStory: transition tracker and per-game fade profiles TransitionTracker follows a fade over many frames (scene, falling, uniform hold, rising, scene) instead of fade_of()'s one frame, and compares the scenes before and after through a caller-supplied comparison. A short fade whose hold falls between two frames is still reported when the falling frames lead to another scene. FadeProfile holds each game's numbers as data: BDSP's uniform tier is the shared walk's stddev 10 and its partial tier run_into_door()'s 60; FRLG fades to true black and has no white fade. White transitions are a flash, a white fade, or WHITE_UNSURE when hold and scene do not settle it. judge_warp() takes a tracked transition too. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_013VUubhHeYSMGSSDXZkKZss --- .../ComputerPrograms_UnitTestRunner.cpp | 1 + .../AutoStory/Pokemon_AutoStory_Tests.h | 2 + .../Pokemon/AutoStory/Pokemon_Interrupts.cpp | 21 + .../Pokemon/AutoStory/Pokemon_Interrupts.h | 16 +- .../Pokemon/AutoStory/Pokemon_Transitions.cpp | 272 +++++++++++++ .../Pokemon/AutoStory/Pokemon_Transitions.h | 197 +++++++++ .../AutoStory/Pokemon_Transitions_Tests.cpp | 378 ++++++++++++++++++ SerialPrograms/cmake/SourceFiles.cmake | 3 + 8 files changed, 882 insertions(+), 8 deletions(-) create mode 100644 SerialPrograms/Source/Pokemon/AutoStory/Pokemon_Transitions.cpp create mode 100644 SerialPrograms/Source/Pokemon/AutoStory/Pokemon_Transitions.h create mode 100644 SerialPrograms/Source/Pokemon/AutoStory/Pokemon_Transitions_Tests.cpp diff --git a/SerialPrograms/Source/ComputerPrograms/ComputerPrograms_UnitTestRunner.cpp b/SerialPrograms/Source/ComputerPrograms/ComputerPrograms_UnitTestRunner.cpp index 1060aef826..902cbc8f3e 100644 --- a/SerialPrograms/Source/ComputerPrograms/ComputerPrograms_UnitTestRunner.cpp +++ b/SerialPrograms/Source/ComputerPrograms/ComputerPrograms_UnitTestRunner.cpp @@ -80,6 +80,7 @@ UnitTestDatabase make_UNIT_TESTS_ALL(){ Pokemon::add_tests_RouteLog(ret); Pokemon::add_tests_ScreenEvents(ret); Pokemon::add_tests_Interrupts(ret); + Pokemon::add_tests_Transitions(ret); Pokemon::add_tests_StoryActions(ret); Pokemon::add_tests_StoryEvents(ret); Pokemon::add_tests_StorySegments(ret); diff --git a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_AutoStory_Tests.h b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_AutoStory_Tests.h index ea5a13d757..cff7994f00 100644 --- a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_AutoStory_Tests.h +++ b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_AutoStory_Tests.h @@ -19,6 +19,8 @@ namespace Pokemon{ void add_tests_ScreenEvents(UnitTestDatabase& database); // The timed screen-event log, the warp judge and the interrupt classifier. void add_tests_Interrupts(UnitTestDatabase& database); +// The transition tracker and the games' fade profiles. +void add_tests_Transitions(UnitTestDatabase& database); // Story action tables, the variant parser and the table executor. void add_tests_StoryActions(UnitTestDatabase& database); // Registers unit tests for story event sequencing and execution. diff --git a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_Interrupts.cpp b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_Interrupts.cpp index 54839a1d8a..07cfbade70 100644 --- a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_Interrupts.cpp +++ b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_Interrupts.cpp @@ -19,6 +19,8 @@ const char* warp_judgement_name(WarpJudgement judgement){ case WarpJudgement::TOO_SHORT: return "fade too short"; case WarpJudgement::SAME_SCENE: return "same scene after the fade"; case WarpJudgement::WARPED: return "warped"; + case WarpJudgement::FLASH: return "an encounter's flash"; + case WarpJudgement::WHITE_UNSURE: return "a white, flash or fade"; } return "?"; } @@ -162,6 +164,8 @@ std::optional warp_verdict( case WarpJudgement::NO_FADE: case WarpJudgement::TOO_SHORT: case WarpJudgement::SAME_SCENE: + case WarpJudgement::FLASH: + case WarpJudgement::WHITE_UNSURE: break; } return std::nullopt; @@ -198,6 +202,23 @@ WarpVerdict judge_warp( return out; } +WarpVerdict judge_warp(const Transition& transition, const InterruptKnobs& knobs){ + const WarpFade fade = transition.kind == TransitionKind::FADE_BLACK ? WarpFade::BLACK : WarpFade::WHITE; + WarpVerdict out{WarpJudgement::WARPED, FadeSpan{fade, transition.start, transition.end}}; + if (!transition.end){ + out.judgement = WarpJudgement::FADE_SHOWING; + }else if (transition.kind == TransitionKind::FLASH){ + out.judgement = WarpJudgement::FLASH; + }else if (transition.change == SceneChange::SAME){ + out.judgement = WarpJudgement::SAME_SCENE; + }else if (transition.kind == TransitionKind::WHITE_UNSURE){ + out.judgement = WarpJudgement::WHITE_UNSURE; + }else if (transition.peak && transition.change != SceneChange::DIFFERENT && transition.hold() < knobs.min_fade_hold){ + out.judgement = WarpJudgement::TOO_SHORT; + } + return out; +} + std::string describe(const InterruptVerdict& verdict, WallClock origin){ std::string out = interrupt_kind_name(verdict.kind); diff --git a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_Interrupts.h b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_Interrupts.h index c1050f3abf..2134a8a458 100644 --- a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_Interrupts.h +++ b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_Interrupts.h @@ -23,6 +23,7 @@ #include #include "Common/Cpp/Time.h" #include "Pokemon_ScreenEvents.h" +#include "Pokemon_Transitions.h" namespace PokemonAutomation{ namespace Pokemon{ @@ -60,14 +61,6 @@ struct FadeSpan{ std::optional up = {}; }; -// Whether the screen differs after a fade from before it. The log has no -// images; the caller compares the frames, or says it did not. -enum class SceneChange{ - UNKNOWN, - SAME, - DIFFERENT, -}; - // What the warp judge made of a fade. enum class WarpJudgement{ NO_FADE, // No fade went down in the window. @@ -75,6 +68,9 @@ enum class WarpJudgement{ TOO_SHORT, // It came back up before min_fade_hold. SAME_SCENE, // It came back up on the scene it left. WARPED, // Down, held, back up; not on the same scene. + FLASH, // An encounter's flash (a tracked transition only). + WHITE_UNSURE, // A white that may be a flash or a cave exit (a + // tracked transition only): wait for a battle. }; // "fade too short", for the log. const char* warp_judgement_name(WarpJudgement judgement); @@ -96,6 +92,10 @@ WarpVerdict judge_warp( const ScreenEventLog& log, InterruptWindow window, const InterruptKnobs& knobs, SceneChange change ); +// The same judge over a TransitionTracker's transition, which has its own +// scene comparison. A transition whose hold went unseen onto another scene +// is a warp whatever min_fade_hold says: the scene change is the evidence. +WarpVerdict judge_warp(const Transition& transition, const InterruptKnobs& knobs); // What stopped the player. diff --git a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_Transitions.cpp b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_Transitions.cpp new file mode 100644 index 0000000000..715869aa27 --- /dev/null +++ b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_Transitions.cpp @@ -0,0 +1,272 @@ +/* Transitions + * + * From: https://github.com/PokemonAutomation/ + * + */ + +#include +#include +#include "CommonFramework/ImageTools/ImageBoxes.h" +#include "Pokemon_Transitions.h" + +namespace PokemonAutomation{ +namespace Pokemon{ + + +const FadeProfile BDSP_FADE_PROFILE{ + .uniform_max_stddev_sum = 10, + .partial_max_stddev_sum = 60, + .dark_max_sum = 225, + .partial_dark_max_sum = 300, + .white_min_sum = 500, + .partial_white_min_sum = 450, + .max_fall = Milliseconds(1000), + .max_hold = Milliseconds(8000), + .has_white_fade = true, + .flash_max_hold = Milliseconds(150), + .white_fade_min_hold = Milliseconds(400), +}; +const FadeProfile FRLG_FADE_PROFILE{ + .uniform_max_stddev_sum = 10, + .partial_max_stddev_sum = 60, + .dark_max_sum = 100, + .partial_dark_max_sum = 200, + .white_min_sum = 500, + .partial_white_min_sum = 450, + .max_fall = Milliseconds(1000), + .max_hold = Milliseconds(8000), + .has_white_fade = false, + .flash_max_hold = Milliseconds(150), + .white_fade_min_hold = Milliseconds(400), +}; + + +const char* transition_kind_name(TransitionKind kind){ + switch (kind){ + case TransitionKind::FADE_BLACK: return "black fade"; + case TransitionKind::FADE_WHITE: return "white fade"; + case TransitionKind::FLASH: return "flash"; + case TransitionKind::WHITE_UNSURE: return "white, flash or fade"; + } + return "?"; +} + + +TransitionSample transition_sample(const VideoSnapshot& frame){ + TransitionSample out{frame.timestamp, {}, frame}; + if (frame){ + out.middle = image_stats(extract_box_reference(*frame.frame, ImageFloatBox(0.1, 0.1, 0.8, 0.8))); + } + return out; +} + + +Milliseconds Transition::hold() const{ + if (!peak || !rise){ + return Milliseconds(0); + } + return std::chrono::duration_cast(*rise - *peak); +} + +namespace{ + +std::string offset(std::optional time, WallClock origin){ + if (!time){ + return "unseen"; + } + return std::format("{:+} ms", std::chrono::duration_cast(*time - origin).count()); +} +const char* scene_change_name(SceneChange change){ + switch (change){ + case SceneChange::UNKNOWN: return "scene unknown"; + case SceneChange::SAME: return "same scene"; + case SceneChange::DIFFERENT: return "other scene"; + } + return "?"; +} + +} // namespace + +std::string describe(const Transition& transition, WallClock origin){ + std::string out = std::format( + "{} {}, peak {}, rise {}", + transition_kind_name(transition.kind), + offset(transition.start, origin), + offset(transition.peak, origin), + offset(transition.rise, origin) + ); + if (!transition.end){ + return out + ", in progress"; + } + return out + std::format(", end {}, {}", offset(transition.end, origin), scene_change_name(transition.change)); +} + + +TransitionTracker::TransitionTracker(FadeProfile profile, CompareScenes compare) + : m_profile(profile) + , m_compare(std::move(compare)) +{} + +TransitionTracker::Level TransitionTracker::level_of(const ImageStats& middle) const{ + const double stddev = middle.stddev.sum(); + const double sum = middle.average.sum(); + if (stddev <= m_profile.uniform_max_stddev_sum){ + if (sum <= m_profile.dark_max_sum){ + return Level::DARK; + } + if (sum >= m_profile.white_min_sum){ + return Level::WHITE; + } + } + if (stddev <= m_profile.partial_max_stddev_sum){ + if (sum <= m_profile.partial_dark_max_sum){ + return Level::PARTIAL_DARK; + } + if (sum >= m_profile.partial_white_min_sum){ + return Level::PARTIAL_WHITE; + } + } + return Level::SCENE; +} + +std::optional TransitionTracker::push(const TransitionSample& sample){ + switch (level_of(sample.middle)){ + case Level::SCENE: + return on_scene(sample); + case Level::PARTIAL_DARK: + return on_partial(sample, false); + case Level::PARTIAL_WHITE: + return on_partial(sample, true); + case Level::DARK: + on_uniform(sample, false); + return std::nullopt; + case Level::WHITE: + on_uniform(sample, true); + return std::nullopt; + } + return std::nullopt; +} + +std::optional TransitionTracker::on_scene(const TransitionSample& sample){ + m_scene_is_partial = false; + if (m_phase == TransitionPhase::SCENE){ + m_before = sample; + return std::nullopt; + } + if (m_phase == TransitionPhase::HOLD){ + m_current.rise = sample.time; + } + return finish(sample); +} + +// A partial frame starts a fall from a scene, unless the scene itself +// looks partial (a dim floor). Partial frames for longer than max_fall, +// falling or rising, are a scene again. +std::optional TransitionTracker::on_partial(const TransitionSample& sample, bool white){ + switch (m_phase){ + case TransitionPhase::SCENE: + if (m_scene_is_partial){ + m_before = sample; + return std::nullopt; + } + m_current = Transition{.start = sample.time}; + m_white = white; + m_phase = TransitionPhase::FALLING; + return std::nullopt; + case TransitionPhase::FALLING: + m_white = white; + if (sample.time - m_current.start > m_profile.max_fall){ + m_phase = TransitionPhase::SCENE; + m_scene_is_partial = true; + m_before = sample; + } + return std::nullopt; + case TransitionPhase::HOLD: + m_current.rise = sample.time; + m_phase = TransitionPhase::RISING; + return std::nullopt; + case TransitionPhase::RISING: + if (sample.time - *m_current.rise <= m_profile.max_fall){ + return std::nullopt; + } + m_scene_is_partial = true; + return finish(sample); + } + return std::nullopt; +} + +void TransitionTracker::on_uniform(const TransitionSample& sample, bool white){ + switch (m_phase){ + case TransitionPhase::SCENE: + m_current = Transition{.start = sample.time, .peak = sample.time}; + m_white = white; + break; + case TransitionPhase::FALLING: + m_current.peak = sample.time; + m_white = white; + break; + case TransitionPhase::HOLD: + break; + case TransitionPhase::RISING: + // Back down again before a scene showed: the same hold. + m_current.rise.reset(); + break; + } + m_phase = TransitionPhase::HOLD; +} + +// Back on a scene: a transition if it held, or if it fell to another +// scene with its hold unseen. A fall back to the same scene is a dip. +std::optional TransitionTracker::finish(const TransitionSample& sample){ + const SceneChange change = m_compare && m_before ? m_compare(*m_before, sample) : SceneChange::UNKNOWN; + m_phase = TransitionPhase::SCENE; + m_before = sample; + if (!m_current.peak && change != SceneChange::DIFFERENT){ + return std::nullopt; + } + m_current.end = sample.time; + m_current.change = change; + m_current.kind = m_white ? kind_of(m_current.hold(), change) : TransitionKind::FADE_BLACK; + m_last = m_current; + return m_current; +} + +TransitionKind TransitionTracker::kind_of(Milliseconds hold, SceneChange change) const{ + if (!m_profile.has_white_fade){ + return TransitionKind::FLASH; + } + if (hold <= m_profile.flash_max_hold && change != SceneChange::DIFFERENT){ + return TransitionKind::FLASH; + } + if (hold >= m_profile.white_fade_min_hold && change != SceneChange::SAME){ + return TransitionKind::FADE_WHITE; + } + return TransitionKind::WHITE_UNSURE; +} + +std::optional TransitionTracker::current() const{ + if (m_phase == TransitionPhase::SCENE){ + return m_last; + } + Transition out = m_current; + out.kind = m_white ? TransitionKind::WHITE_UNSURE : TransitionKind::FADE_BLACK; + return out; +} + +bool TransitionTracker::timed_out(WallClock now) const{ + return m_phase != TransitionPhase::SCENE && now - m_current.start > m_profile.max_hold; +} + +void TransitionTracker::reset(){ + m_phase = TransitionPhase::SCENE; + m_white = false; + m_scene_is_partial = false; + m_before.reset(); + m_current = Transition{}; + m_last.reset(); +} + + + +} // namespace Pokemon +} // namespace PokemonAutomation diff --git a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_Transitions.h b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_Transitions.h new file mode 100644 index 0000000000..5764247571 --- /dev/null +++ b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_Transitions.h @@ -0,0 +1,197 @@ +/* Transitions + * + * From: https://github.com/PokemonAutomation/ + * + * A screen transition followed over many frames rather than judged on one: + * the scene, the screen falling toward a uniform colour, the uniform hold, + * the rise, and the scene it comes back on. fade_of() alone judges one + * frame, so a 50 ms door fade that falls between two sampled frames is never + * seen, and the step waits out its whole timeout (12 s for a BDSP door). + * The tracker sees the frames around it instead: the screen falling, then a + * different scene. + * + * Each game's numbers are a FadeProfile; the tracker is the same for all. + * + */ + +#ifndef PokemonAutomation_Pokemon_Transitions_H +#define PokemonAutomation_Pokemon_Transitions_H + +#include +#include +#include +#include +#include "Common/Cpp/Time.h" +#include "CommonFramework/ImageTools/ImageStats.h" +#include "CommonFramework/VideoPipeline/VideoFeed.h" + +namespace PokemonAutomation{ +namespace Pokemon{ + + +// Whether the screen differs after a transition from before it. The +// tracker has only frame statistics; the caller compares the frames, or +// says it did not. +enum class SceneChange{ + UNKNOWN, + SAME, + DIFFERENT, +}; + + +// A game's fades, as data. Two tiers of the same test: a frame is uniform +// (the fade's hold) when its middle's stddev sum is at most +// `uniform_max_stddev_sum`, and partial (on the way down or up) when it is +// at most `partial_max_stddev_sum`. Either way it is dark or white by its +// rgb sum. +struct FadeProfile{ + double uniform_max_stddev_sum = 10; + double partial_max_stddev_sum = 60; + // Dark at or below this rgb sum; a partial frame up to `partial_dark_max_sum`. + double dark_max_sum = 225; + double partial_dark_max_sum = 300; + // White at or above this rgb sum; a partial frame from `partial_white_min_sum`. + double white_min_sum = 500; + double partial_white_min_sum = 450; + + // Partial frames for longer than this, with no hold, are the scene's + // own look (a dim cave floor, a street at night), not a fade. + Milliseconds max_fall = Milliseconds(1000); + // A transition still dark or white after this has timed out: the + // screen did not come back. + Milliseconds max_hold = Milliseconds(8000); + + // Whether the game fades to white between maps (BDSP's cave exits). + // Without, every white is an encounter's flash. + bool has_white_fade = true; + // A white held this long or less, back on the same scene, is a flash. + Milliseconds flash_max_hold = Milliseconds(150); + // A white held this long or more, not back on the same scene, is a + // white fade. Between the two the white is unsure. + Milliseconds white_fade_min_hold = Milliseconds(400); +}; + +// BDSP. The uniform tier is the shared walk's (FADE_MAX_STDDEV_SUM, the +// Oreburgh Gate's textured floor is no fade, lab-B 2026-11-08); the partial +// tier is run_into_door()'s 60, which caught the doorway's dim fade frames. +// A cave mouth's fade is dim (45 to 64 a channel), hence the dark sum of 225. +// The flash and white-fade holds are provisional: no console frames of an +// encounter flash and a cave exit have been timed side by side yet, so the +// band between them is wide and reports WHITE_UNSURE. +extern const FadeProfile BDSP_FADE_PROFILE; +// FRLG. The GBA fades to true black, so the dark tiers are the shared +// BlackScreenDetector's 100 and a little above; it has no white fade between +// maps, so every white is an encounter's flash. +extern const FadeProfile FRLG_FADE_PROFILE; + + +// What a transition was. +enum class TransitionKind : uint8_t{ + FADE_BLACK, // A door, a cave mouth, a scene cut, a battle's own fade. + FADE_WHITE, // A cave exit: a long white onto another scene. + FLASH, // An encounter's flash: a short white, back on the scene. + WHITE_UNSURE, // A white that may be either: wait for a battle. +}; +// "black fade", for the log. +const char* transition_kind_name(TransitionKind kind); + +// Where the tracker is in a transition. +enum class TransitionPhase : uint8_t{ + SCENE, // No transition: the screen shows a scene. + FALLING, // Partial frames, toward dark or white. + HOLD, // Uniform frames. + RISING, // Partial frames after the hold. +}; + +// One frame, as the tracker reads it. +struct TransitionSample{ + WallClock time = {}; + // The stats of the screen's middle 80%, as fade_of_screen() reads. + ImageStats middle = {}; + // The frame itself, for the caller's scene comparison. May be empty. + VideoSnapshot frame = {}; +}; +// A sample of `frame`, at its timestamp. +TransitionSample transition_sample(const VideoSnapshot& frame); + +// One transition, complete or in progress. +struct Transition{ + TransitionKind kind = TransitionKind::FADE_BLACK; + // The first frame off the scene: falling, or the hold if no fall was seen. + WallClock start = {}; + // The first uniform frame. None: the hold fell between two frames, and + // only the falling frames and the new scene were seen. + std::optional peak = {}; + // The first frame off the hold. + std::optional rise = {}; + // The first frame back on a scene. None while in progress. + std::optional end = {}; + // The scene after against the one before; UNKNOWN in progress. + SceneChange change = SceneChange::UNKNOWN; + + // How long the uniform frames showed; zero with no peak. + Milliseconds hold() const; +}; +// "black fade +200 ms, peak +300 ms, rise +700 ms, end +800 ms, other scene", +// times from `origin`. +std::string describe(const Transition& transition, WallClock origin); + + +// The transition state machine, fed one frame at a time: scene, falling, +// hold, rising, scene. Not thread-safe. +class TransitionTracker{ +public: + // Compares the last scene frame before a transition with the first + // after it. + using CompareScenes = std::function; + + // With no `compare`, every scene change is UNKNOWN, and a transition + // whose hold went unseen is not reported. + explicit TransitionTracker(FadeProfile profile, CompareScenes compare = {}); + + // Adds a frame; times must not go back. Returns the transition this + // frame completed, if any. + std::optional push(const TransitionSample& sample); + + TransitionPhase phase() const{ + return m_phase; + } + // The transition in progress, else the last one completed. + std::optional current() const; + // Whether the transition in progress has gone on longer than max_hold + // at `now`. + bool timed_out(WallClock now) const; + void reset(); + +private: + enum class Level : uint8_t{ + SCENE, + PARTIAL_DARK, + PARTIAL_WHITE, + DARK, + WHITE, + }; + Level level_of(const ImageStats& middle) const; + + std::optional on_scene(const TransitionSample& sample); + std::optional on_partial(const TransitionSample& sample, bool white); + void on_uniform(const TransitionSample& sample, bool white); + std::optional finish(const TransitionSample& sample); + TransitionKind kind_of(Milliseconds hold, SceneChange change) const; + + FadeProfile m_profile; + CompareScenes m_compare; + TransitionPhase m_phase = TransitionPhase::SCENE; + bool m_white = false; + // The scene itself looks partial (a dim floor): partial frames are no fall. + bool m_scene_is_partial = false; + std::optional m_before; + Transition m_current; + std::optional m_last; +}; + + + +} // namespace Pokemon +} // namespace PokemonAutomation +#endif diff --git a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_Transitions_Tests.cpp b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_Transitions_Tests.cpp new file mode 100644 index 0000000000..2f29f54475 --- /dev/null +++ b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_Transitions_Tests.cpp @@ -0,0 +1,378 @@ +/* Transitions Tests + * + * From: https://github.com/PokemonAutomation/ + * + * The transition tracker on synthetic frame statistics: a frame is its + * middle's mean and stddev at a time. Then the same tracker on captured + * frames from CommandLineTests, when they are checked out. + * + */ + +#include +#include +#include +#include +#include +#include "Common/Cpp/Filesystem/FileIO.h" +#include "Common/Cpp/Filesystem/Filesystem.h" +#include "Common/Cpp/TestRunners/UnitTest.h" +#include "CommonFramework/GlobalAutoPaths.h" +#include "CommonFramework/ImageTypes/ImageRGB32.h" +#include "Pokemon_AutoStory_Tests.h" +#include "Pokemon_Interrupts.h" +#include "Pokemon_Transitions.h" + +namespace PokemonAutomation{ +namespace Pokemon{ + +namespace{ + +using namespace std::chrono_literals; + +const WallClock T0 = WallClock() + std::chrono::hours(1); + +ImageStats stats(double r, double g, double b, double stddev){ + return ImageStats(FloatPixel(r, g, b), FloatPixel(stddev, stddev, stddev), 1000); +} + +// Scenes are textured; each has its own mean, which the comparison reads. +const ImageStats ROUTE = stats(120, 100, 90, 40); +const ImageStats HOUSE = stats(100, 120, 90, 40); +// A cave: dark, but textured past the partial tier. +const ImageStats CAVE = stats(50, 45, 40, 25); +// The Oreburgh Gate's dim floor: mean 46, textured within the partial tier. +const ImageStats DIM_FLOOR = stats(46, 46, 46, 8); +// A street at night: dark, but lit windows keep it textured. +const ImageStats NIGHT = stats(40, 40, 55, 30); +const ImageStats FALLING_DARK = stats(60, 60, 60, 10); +const ImageStats DARK = stats(5, 5, 5, 1); +const ImageStats FALLING_WHITE = stats(160, 160, 160, 10); +const ImageStats WHITE = stats(250, 250, 250, 1); + +SceneChange compare_means(const TransitionSample& before, const TransitionSample& after){ + const FloatPixel& a = before.middle.average; + const FloatPixel& b = after.middle.average; + return a.r == b.r && a.g == b.g && a.b == b.b ? SceneChange::SAME : SceneChange::DIFFERENT; +} + +// `stats` from `from_ms` to `to_ms`, a frame every 100 ms. +struct Span{ + int from_ms; + int to_ms; + ImageStats stats; +}; + +// The transitions completed, as describe() puts them, joined by "; "; +// "none" if none. +std::string run_tracker(TransitionTracker& tracker, const std::vector& spans){ + std::string out; + for (const Span& span : spans){ + for (int ms = span.from_ms; ms <= span.to_ms; ms += 100){ + const std::optional done = tracker.push({T0 + Milliseconds(ms), span.stats, {}}); + if (done){ + out += (out.empty() ? "" : "; ") + describe(*done, T0); + } + } + } + return out.empty() ? "none" : out; +} + + +// A synthetic stream of frames, through one game's profile. +struct TrackInput{ + std::string name; + std::vector spans; + const FadeProfile* profile = &BDSP_FADE_PROFILE; + bool compare = true; +}; + +struct TrackExpectation{ + // The transitions completed, as run_tracker() puts them. + std::string transitions; + // What judge_warp() makes of the tracker's current() at the end; empty + // for none. + std::string warp = ""; +}; + +struct TrackCase{ + TrackInput input; + TrackExpectation expectation; +}; + +class Test_TransitionTracker : public UnitTest{ +public: + explicit Test_TransitionTracker(TrackCase test_case) + : UnitTest("Pokemon::Transitions - " + test_case.input.name) + , m_case(std::move(test_case)) + {} + virtual UnitTestResult run(Logger&, CancellableScope&) const override{ + const TrackInput& input = m_case.input; + TransitionTracker tracker(*input.profile, input.compare ? compare_means : TransitionTracker::CompareScenes()); + const std::string got = run_tracker(tracker, input.spans); + if (got != m_case.expectation.transitions){ + return std::format("transitions: expected \"{}\", got \"{}\"", m_case.expectation.transitions, got); + } + const std::optional current = tracker.current(); + const InterruptKnobs knobs{.min_fade_hold = 200ms}; + const std::string warp = current ? warp_judgement_name(judge_warp(*current, knobs).judgement) : ""; + if (warp != m_case.expectation.warp){ + return std::format("warp: expected \"{}\", got \"{}\"", m_case.expectation.warp, warp); + } + return true; + } + +private: + TrackCase m_case; +}; + + +UnitTestResult test_timeout(){ + TransitionTracker tracker(BDSP_FADE_PROFILE, compare_means); + const std::string got = run_tracker(tracker, {{0, 100, ROUTE}, {200, 8200, DARK}}); + if (got != "none" || tracker.phase() != TransitionPhase::HOLD){ + return "a screen that stays dark completes no transition and stays in its hold"; + } + if (tracker.timed_out(T0 + 8200ms) || !tracker.timed_out(T0 + 8300ms)){ + return "a transition times out max_hold after it started, not before"; + } + const std::string current = describe(*tracker.current(), T0); + if (current != "black fade +200 ms, peak +200 ms, rise unseen, in progress"){ + return "current(): " + current; + } + tracker.reset(); + if (tracker.phase() != TransitionPhase::SCENE || tracker.current() || tracker.timed_out(T0 + 9000ms)){ + return "reset() did not clear the tracker"; + } + return true; +} + +UnitTestResult test_sample_of_frame(){ + ImageRGB32 image(40, 40); + image.fill(0xff000000); + const TransitionSample sample = transition_sample(VideoSnapshot(std::move(image), T0)); + TransitionTracker tracker(BDSP_FADE_PROFILE); + tracker.push(sample); + if (sample.time != T0 || tracker.phase() != TransitionPhase::HOLD){ + return "a black frame's sample is not a hold at its timestamp"; + } + return transition_sample(VideoSnapshot()).middle.count == 0 + ? UnitTestResult(true) + : UnitTestResult("an empty frame has stats"); +} + + +// Captured frames: CommandLineTests//Transitions// holds +// frames named by their time in ms ("0.png", "250.png"), and expected.txt +// with the transitions run_tracker() should report (no scene comparison). +struct CapturedInput{ + std::string game; + const FadeProfile* profile; +}; + +// Each case folder's expected.txt holds its expectation. +struct CapturedExpectation{ +}; + +struct CapturedCase{ + CapturedInput input; + CapturedExpectation expectation; +}; + +std::string track_captured_case(const Filesystem::Path& folder, const FadeProfile& profile){ + std::vector> frames; + for (const Filesystem::Path& file : Filesystem::list_directory(folder)){ + if (file.extension().string() == ".png"){ + frames.emplace_back(std::stoi(file.stem().string()), file); + } + } + std::sort(frames.begin(), frames.end(), [](const auto& a, const auto& b){ + return a.first < b.first; + }); + TransitionTracker tracker(profile); + std::string out; + for (const auto& frame : frames){ + VideoSnapshot snapshot(ImageRGB32(frame.second.string()), T0 + Milliseconds(frame.first)); + const std::optional done = tracker.push(transition_sample(snapshot)); + if (done){ + out += (out.empty() ? "" : "; ") + describe(*done, T0); + } + } + return out.empty() ? "none" : out; +} + +class Test_CapturedTransitions : public UnitTest{ +public: + explicit Test_CapturedTransitions(CapturedCase test_case) + : UnitTest("Pokemon::Transitions - captured frames: " + test_case.input.game) + , m_input(std::move(test_case.input)) + {} + virtual UnitTestResult run(Logger&, CancellableScope&) const override{ + const Filesystem::Path root(UNIT_TEST_RESOURCE_PATH() + m_input.game + "/Transitions/"); + if (!Filesystem::is_directory(root)){ + return UnitTestResult(UnitTestResult::SKIPPED, "no captured transitions at " + root.string()); + } + for (const Filesystem::Path& folder : Filesystem::list_directory(root)){ + if (!Filesystem::is_directory(folder)){ + continue; + } + std::string expected = file_to_string((folder / "expected.txt").string()); + expected.erase(expected.find_last_not_of("\r\n") + 1); + const std::string got = track_captured_case(folder, *m_input.profile); + if (got != expected){ + return std::format("{}: expected \"{}\", got \"{}\"", folder.filename().string(), expected, got); + } + } + return true; + } + +private: + CapturedInput m_input; +}; + + +struct TransitionsInput{ + std::string name; + UnitTestResult (*body)(); +}; + +// The body checks its own expectations. +struct TransitionsExpectation{ +}; + +struct TransitionsCase{ + TransitionsInput input; + TransitionsExpectation expectation; +}; + +class Test_Transitions : public UnitTest{ +public: + explicit Test_Transitions(TransitionsCase test_case) + : UnitTest("Pokemon::Transitions - " + test_case.input.name) + , m_input(std::move(test_case.input)) + {} + virtual UnitTestResult run(Logger&, CancellableScope&) const override{ + return m_input.body(); + } + +private: + TransitionsInput m_input; +}; + +} // namespace + + +const TrackCase TRACK_CASES[] = { + { + .input = {"a door: falls, holds, rises onto another scene", + {{0, 100, ROUTE}, {200, 200, FALLING_DARK}, {300, 700, DARK}, {800, 800, FALLING_DARK}, {900, 1000, HOUSE}}}, + .expectation = {"black fade +200 ms, peak +300 ms, rise +800 ms, end +900 ms, other scene", "warped"}, + }, + { + .input = {"a missed short fade: falling, then another scene", + {{0, 100, ROUTE}, {200, 200, FALLING_DARK}, {300, 400, HOUSE}}}, + .expectation = {"black fade +200 ms, peak unseen, rise unseen, end +300 ms, other scene", "warped"}, + }, + { + .input = {"a missed fade is not reported with no scene comparison", + {{0, 100, ROUTE}, {200, 200, FALLING_DARK}, {300, 400, HOUSE}}, &BDSP_FADE_PROFILE, false}, + .expectation = {"none"}, + }, + { + .input = {"a dip back onto the same scene is no transition", + {{0, 100, ROUTE}, {200, 300, FALLING_DARK}, {400, 500, ROUTE}}}, + .expectation = {"none"}, + }, + { + .input = {"a one-frame black onto the same scene is too short", + {{0, 100, ROUTE}, {200, 200, DARK}, {300, 400, ROUTE}}}, + .expectation = {"black fade +200 ms, peak +200 ms, rise +300 ms, end +300 ms, same scene", "same scene after the fade"}, + }, + { + .input = {"a one-frame black, scene unknown, is too short", + {{0, 100, ROUTE}, {200, 200, DARK}, {300, 400, ROUTE}}, &BDSP_FADE_PROFILE, false}, + .expectation = {"black fade +200 ms, peak +200 ms, rise +300 ms, end +300 ms, scene unknown", "fade too short"}, + }, + { + .input = {"an encounter's flash: a short white, back on the scene", + {{0, 100, ROUTE}, {200, 200, WHITE}, {300, 400, ROUTE}}}, + .expectation = {"flash +200 ms, peak +200 ms, rise +300 ms, end +300 ms, same scene", "an encounter's flash"}, + }, + { + .input = {"a cave exit: a long white onto another scene", + {{0, 100, CAVE}, {200, 200, FALLING_WHITE}, {300, 800, WHITE}, {900, 900, FALLING_WHITE}, {1000, 1100, ROUTE}}}, + .expectation = {"white fade +200 ms, peak +300 ms, rise +900 ms, end +1000 ms, other scene", "warped"}, + }, + { + .input = {"a white between a flash and a fade, scene unknown, is unsure", + {{0, 100, ROUTE}, {200, 400, WHITE}, {500, 600, ROUTE}}, &BDSP_FADE_PROFILE, false}, + .expectation = {"white, flash or fade +200 ms, peak +200 ms, rise +500 ms, end +500 ms, scene unknown", "a white, flash or fade"}, + }, + { + .input = {"a short white onto another scene may be the battle: unsure", + {{0, 100, ROUTE}, {200, 200, WHITE}, {300, 400, HOUSE}}}, + .expectation = {"white, flash or fade +200 ms, peak +200 ms, rise +300 ms, end +300 ms, other scene", "a white, flash or fade"}, + }, + { + .input = {"FRLG has no white fade: a long white is a flash", + {{0, 100, CAVE}, {300, 800, WHITE}, {1000, 1100, ROUTE}}, &FRLG_FADE_PROFILE}, + .expectation = {"flash +300 ms, peak +300 ms, rise +1000 ms, end +1000 ms, other scene", "an encounter's flash"}, + }, + { + .input = {"the Oreburgh Gate's dim floor is no fade, a door from it is", + {{0, 100, ROUTE}, {200, 3000, DIM_FLOOR}, {3100, 3400, DARK}, {3500, 3600, HOUSE}}}, + .expectation = {"black fade +3100 ms, peak +3100 ms, rise +3500 ms, end +3500 ms, other scene", "warped"}, + }, + { + .input = {"a street at night is no fade", {{0, 5000, NIGHT}}}, + .expectation = {"none"}, + }, + { + .input = {"a cave mouth's fade rises into a dim cave", + {{0, 100, ROUTE}, {200, 500, DARK}, {600, 2500, DIM_FLOOR}}}, + .expectation = {"black fade +200 ms, peak +200 ms, rise +600 ms, end +1700 ms, other scene", "warped"}, + }, + { + .input = {"a fade in progress is still showing", + {{0, 100, ROUTE}, {200, 200, FALLING_DARK}, {300, 600, DARK}}}, + .expectation = {"none", "fade still showing"}, + }, +}; + +const TransitionsCase TRANSITIONS_CASES[] = { + { + .input = {"a screen that stays dark times out", test_timeout}, + .expectation = {}, + }, + { + .input = {"a video frame's sample", test_sample_of_frame}, + .expectation = {}, + }, +}; + +const CapturedCase CAPTURED_CASES[] = { + { + .input = {"PokemonBDSP", &BDSP_FADE_PROFILE}, + .expectation = {}, + }, + { + .input = {"PokemonFRLG", &FRLG_FADE_PROFILE}, + .expectation = {}, + }, +}; + +void add_tests_Transitions(UnitTestDatabase& database){ + for (const auto& item : TRACK_CASES){ + database.add(item); + } + for (const auto& item : TRANSITIONS_CASES){ + database.add(item); + } + for (const auto& item : CAPTURED_CASES){ + database.add(item); + } +} + + + +} // namespace Pokemon +} // namespace PokemonAutomation diff --git a/SerialPrograms/cmake/SourceFiles.cmake b/SerialPrograms/cmake/SourceFiles.cmake index 4c92b891e2..eb33f74317 100644 --- a/SerialPrograms/cmake/SourceFiles.cmake +++ b/SerialPrograms/cmake/SourceFiles.cmake @@ -1528,6 +1528,9 @@ file(GLOB LIBRARY_SOURCES Source/Pokemon/AutoStory/Pokemon_StorySteps_Tests.cpp Source/Pokemon/AutoStory/Pokemon_TilePose.cpp Source/Pokemon/AutoStory/Pokemon_TilePose.h + Source/Pokemon/AutoStory/Pokemon_Transitions.cpp + Source/Pokemon/AutoStory/Pokemon_Transitions.h + Source/Pokemon/AutoStory/Pokemon_Transitions_Tests.cpp Source/Pokemon/Pokemon_AdvRng.cpp Source/Pokemon/Pokemon_AdvRng.h Source/Pokemon/Pokemon_BdspRng.cpp From b3aa69e1951f53edfa014d5d4d0821f102590826 Mon Sep 17 00:00:00 2001 From: dayfine Date: Mon, 9 Nov 2026 02:25:55 -0800 Subject: [PATCH 022/102] AutoStory: time an interrupt's step from its screen events interrupt_step_time() takes a classified interrupt and the game's measured lag per screen event, and returns when the step that set it off was taken: the first timed rise in its evidence, less its lag. A walker that sees a wild battle only after its hold has ended can then place it by what the timed log saw during the hold. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_013VUubhHeYSMGSSDXZkKZss --- .../Pokemon/AutoStory/Pokemon_Interrupts.cpp | 15 ++++ .../Pokemon/AutoStory/Pokemon_Interrupts.h | 20 ++++++ .../AutoStory/Pokemon_Interrupts_Tests.cpp | 68 +++++++++++++++++++ 3 files changed, 103 insertions(+) diff --git a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_Interrupts.cpp b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_Interrupts.cpp index 07cfbade70..e93ce9f5c9 100644 --- a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_Interrupts.cpp +++ b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_Interrupts.cpp @@ -258,6 +258,21 @@ InterruptVerdict classify_interrupt( } +std::optional interrupt_step_time(const InterruptVerdict& verdict, const std::vector& lags){ + for (const ScreenEventChange& change : verdict.evidence){ + if (change.edge != ScreenEventEdge::ROSE){ + continue; + } + for (const EventLag& lag : lags){ + if (lag.event == change.event){ + return change.time - lag.lag; + } + } + } + return std::nullopt; +} + + } // namespace Pokemon } // namespace PokemonAutomation diff --git a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_Interrupts.h b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_Interrupts.h index 2134a8a458..52d23c811c 100644 --- a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_Interrupts.h +++ b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_Interrupts.h @@ -131,6 +131,26 @@ InterruptVerdict classify_interrupt( ); +// How long after the step that set an interrupt off one of its events +// shows, as a game measured it on its console. +struct EventLag{ + ScreenEvent event = ScreenEvent::BATTLE_STARTED; + Milliseconds lag = Milliseconds(0); +}; + +// When the step that set `verdict`'s interrupt off was taken: the first +// rise in its evidence that `lags` times, less that lag. The first, as it +// shows nearest the step. Nothing if `lags` times none of them, as for a +// game that hasn't measured its events, or for no verdict. Lags are one +// kind of interrupt's (a wild battle's box, not a trainer's): the caller +// checks the verdict's kind first. +// +// This places an interrupt seen only after a walk's hold has ended, by +// what the log saw of it during the hold, instead of by when the watcher +// that stopped for it fired. +std::optional interrupt_step_time(const InterruptVerdict& verdict, const std::vector& lags); + + } // namespace Pokemon } // namespace PokemonAutomation diff --git a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_Interrupts_Tests.cpp b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_Interrupts_Tests.cpp index 6622da1d90..aecc5cbbd8 100644 --- a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_Interrupts_Tests.cpp +++ b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_Interrupts_Tests.cpp @@ -9,6 +9,7 @@ #include #include +#include #include #include #include @@ -250,6 +251,45 @@ class Test_InterruptClassify : public UnitTest{ ClassifyCase m_case; }; + +// A synthetic scene, classified over all of it, and the lags to time it. +struct StepTimeInput{ + std::string name; + std::vector frames; + int until_ms = 0; + std::vector lags; +}; + +struct StepTimeExpectation{ + // "+700 ms" from T0, or "none". + std::string step; +}; + +struct StepTimeCase{ + StepTimeInput input; + StepTimeExpectation expectation; +}; + +class Test_InterruptStepTime : public UnitTest{ +public: + explicit Test_InterruptStepTime(StepTimeCase test_case) + : UnitTest("Pokemon::Interrupts - step time: " + test_case.input.name) + , m_case(std::move(test_case)) + {} + virtual UnitTestResult run(Logger&, CancellableScope&) const override{ + const StepTimeInput& input = m_case.input; + const InterruptVerdict verdict = classify_interrupt(log_of(input.frames, input.until_ms), whole(input.until_ms), {}); + const std::optional step = interrupt_step_time(verdict, input.lags); + const std::string got = step + ? std::format("{:+} ms", std::chrono::duration_cast(*step - T0).count()) + : "none"; + return expect_equal("step time of " + describe(verdict, T0), got, m_case.expectation.step); + } + +private: + StepTimeCase m_case; +}; + } // namespace @@ -352,6 +392,31 @@ const ClassifyCase CLASSIFY_CASES[] = { }, }; +const StepTimeCase STEP_TIME_CASES[] = { + { + .input = {"a wild battle's box, its fade untimed", + {{0, WALK}, {1500, BLACK}, {2000, ScreenEvents()}, {4400, BATTLE}}, 6000, + {{ScreenEvent::BATTLE_STARTED, 3700ms}}}, + .expectation = {"+700 ms"}, + }, + { + .input = {"the first timed rise wins", + {{0, WALK}, {1500, BLACK}, {2000, ScreenEvents()}, {4400, BATTLE}}, 6000, + {{ScreenEvent::BATTLE_STARTED, 3700ms}, {ScreenEvent::FADE_BLACK, 1000ms}}}, + .expectation = {"+500 ms"}, + }, + { + .input = {"no lags, no time", + {{0, WALK}, {4400, BATTLE}}, 6000, {}}, + .expectation = {"none"}, + }, + { + .input = {"no interrupt, no time", + {{0, WALK}}, 6000, {{ScreenEvent::BATTLE_STARTED, 3700ms}}}, + .expectation = {"none"}, + }, +}; + void add_tests_Interrupts(UnitTestDatabase& database){ for (const auto& item : INTERRUPTS_CASES){ database.add(item); @@ -359,6 +424,9 @@ void add_tests_Interrupts(UnitTestDatabase& database){ for (const auto& item : CLASSIFY_CASES){ database.add(item); } + for (const auto& item : STEP_TIME_CASES){ + database.add(item); + } } From bfaaab0be44bea8c414d3046cc40cd6e9ae4c146 Mon Sep 17 00:00:00 2001 From: dayfine Date: Mon, 9 Nov 2026 03:50:52 -0800 Subject: [PATCH 023/102] AutoStory: clear interrupts between story steps The table executor looks at the screen before each step and after a failed one, judges the look with classify_interrupt() and clears what it found with the game's handler for that kind (InterruptHandlerTable): a wild battle, a trainer's sight, a dialog, a warp. An unsettled look is looked at again, up to max_looks; a failed step an interrupt explains runs again once it is cleared, up to max_per_step. Without interrupts set, the executor runs as before. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_013VUubhHeYSMGSSDXZkKZss --- .../ComputerPrograms_UnitTestRunner.cpp | 1 + .../AutoStory/Pokemon_AutoStory_Tests.h | 2 + .../AutoStory/Pokemon_StoryActions.cpp | 64 ++- .../Pokemon/AutoStory/Pokemon_StoryActions.h | 25 + .../Pokemon/AutoStory/Pokemon_StoryEvents.cpp | 4 + .../Pokemon/AutoStory/Pokemon_StoryEvents.h | 2 + .../AutoStory/Pokemon_StoryInterrupts.cpp | 96 ++++ .../AutoStory/Pokemon_StoryInterrupts.h | 118 +++++ .../Pokemon_StoryInterrupts_Tests.cpp | 480 ++++++++++++++++++ SerialPrograms/cmake/SourceFiles.cmake | 3 + 10 files changed, 786 insertions(+), 9 deletions(-) create mode 100644 SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryInterrupts.cpp create mode 100644 SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryInterrupts.h create mode 100644 SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryInterrupts_Tests.cpp diff --git a/SerialPrograms/Source/ComputerPrograms/ComputerPrograms_UnitTestRunner.cpp b/SerialPrograms/Source/ComputerPrograms/ComputerPrograms_UnitTestRunner.cpp index 902cbc8f3e..2f878a6551 100644 --- a/SerialPrograms/Source/ComputerPrograms/ComputerPrograms_UnitTestRunner.cpp +++ b/SerialPrograms/Source/ComputerPrograms/ComputerPrograms_UnitTestRunner.cpp @@ -82,6 +82,7 @@ UnitTestDatabase make_UNIT_TESTS_ALL(){ Pokemon::add_tests_Interrupts(ret); Pokemon::add_tests_Transitions(ret); Pokemon::add_tests_StoryActions(ret); + Pokemon::add_tests_StoryInterrupts(ret); Pokemon::add_tests_StoryEvents(ret); Pokemon::add_tests_StorySegments(ret); Pokemon::add_tests_StorySteps(ret); diff --git a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_AutoStory_Tests.h b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_AutoStory_Tests.h index cff7994f00..10c5ab8848 100644 --- a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_AutoStory_Tests.h +++ b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_AutoStory_Tests.h @@ -23,6 +23,8 @@ void add_tests_Interrupts(UnitTestDatabase& database); void add_tests_Transitions(UnitTestDatabase& database); // Story action tables, the variant parser and the table executor. void add_tests_StoryActions(UnitTestDatabase& database); +// The table executor's looks for interrupts between steps. +void add_tests_StoryInterrupts(UnitTestDatabase& database); // Registers unit tests for story event sequencing and execution. void add_tests_StoryEvents(UnitTestDatabase& database); // Registers unit tests for story segment running, verification, and branching. diff --git a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryActions.cpp b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryActions.cpp index 2366323e97..349aa3e530 100644 --- a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryActions.cpp +++ b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryActions.cpp @@ -85,6 +85,8 @@ bool StepGuard::stops_on_failure(const StoryStep&) const{ void StepGuard::on_failure(const StoryStep&, const OperationFailedException&){} +void StepGuard::on_interrupt(const StoryStep&, const InterruptCheck&){} + TableExecutor::TableExecutor(const StoryActionTable& table, StepGuard& guard) : m_table(table) @@ -93,20 +95,64 @@ TableExecutor::TableExecutor(const StoryActionTable& table, StepGuard& guard) Outcome TableExecutor::run(RunState& state, const StoryStep& step){ m_guard.before_step(step); - try{ - if (const StoryAction* action = m_table.find(step)){ - return action->act(state, step); + size_t cleared = 0; + while (true){ + if (std::optional failed = clear_interrupts(state, step, cleared)){ + return *failed; } - return StoryStepExecutor::run(state, step); - }catch (OperationFailedException& e){ - if (m_guard.stops_on_failure(step)){ - throw; + try{ + Outcome outcome = run_action(state, step); + if (outcome.succeeded() || !cleared_after_failure(state, step, cleared)){ + return outcome; + } + }catch (OperationFailedException& e){ + if (cleared_after_failure(state, step, cleared)){ + continue; + } + if (m_guard.stops_on_failure(step)){ + throw; + } + m_guard.on_failure(step, e); + return outcome_failed("operation_failed", e.message()); } - m_guard.on_failure(step, e); - return outcome_failed("operation_failed", e.message()); } } +Outcome TableExecutor::run_action(RunState& state, const StoryStep& step){ + if (const StoryAction* action = m_table.find(step)){ + return action->act(state, step); + } + return StoryStepExecutor::run(state, step); +} + +// Clears what interrupted the player before `step`, counting it in +// `cleared`. Nothing when there was nothing or it is cleared; else the +// step's failure. +std::optional TableExecutor::clear_interrupts(RunState& state, const StoryStep& step, size_t& cleared){ + if (m_interrupts == nullptr){ + return std::nullopt; + } + InterruptCheck check = clear_story_interrupt(*m_interrupts, state, step); + if (check.verdict.kind == InterruptKind::NONE){ + return std::nullopt; + } + if (check.outcome.succeeded() && ++cleared > m_interrupts->max_per_step){ + check.outcome = outcome_failed("too_many_interrupts", step.name); + } + m_guard.on_interrupt(step, check); + if (!check.outcome.succeeded()){ + return check.outcome; + } + return std::nullopt; +} + +// Whether an interrupt explains the failure of `step`: one showed after +// it failed and is cleared, so the step runs again. +bool TableExecutor::cleared_after_failure(RunState& state, const StoryStep& step, size_t& cleared){ + const size_t before = cleared; + return !clear_interrupts(state, step, cleared) && cleared > before; +} + } // namespace Pokemon diff --git a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryActions.h b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryActions.h index 0bd5906ed6..9f66529814 100644 --- a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryActions.h +++ b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryActions.h @@ -12,6 +12,8 @@ * StepGuard: the log line, and a failed console step turned into a failed * Outcome. Today each game writes that guard itself (BDSP's * StoryExecutor::run(), FRLG's guarded(), PLZA's Executor::run()). + * With the game's interrupts set, it also clears what stopped the player + * between steps (Pokemon_StoryInterrupts.h). * */ @@ -20,11 +22,13 @@ #include #include +#include #include #include #include #include "CommonFramework/Exceptions/OperationFailedException.h" #include "Pokemon_StoryEvents.h" +#include "Pokemon_StoryInterrupts.h" #include "Pokemon_StorySteps.h" namespace PokemonAutomation{ @@ -89,6 +93,9 @@ class StepGuard{ virtual bool stops_on_failure(const StoryStep& step) const; // The step threw `error` and fails: e.g. log it and save a screenshot. virtual void on_failure(const StoryStep& step, const OperationFailedException& error); + // A look before the step, or after it failed, found an interrupt and + // cleared it or failed to (`check`): e.g. log it. + virtual void on_interrupt(const StoryStep& step, const InterruptCheck& check); }; @@ -102,11 +109,29 @@ class TableExecutor : public StoryStepExecutor{ // (StoryStepExecutor::run()), so a game can move to the table one // kind at a time. An OperationFailedException from either is the // failed Outcome "operation_failed", unless the guard stops on it. + // With interrupts set, each step first clears what stopped the player + // since the step before, and a failed step that an interrupt explains + // runs again once it is cleared. virtual Outcome run(RunState& state, const StoryStep& step) override; + // The game's interrupts between steps, which must outlive the + // executor; none (the default) looks for none. + void set_interrupts(const StoryInterrupts* interrupts){ + m_interrupts = interrupts; + } + +protected: + // The table's action for the step, or the kind's virtual: what run() + // runs once the screen is clear. A binding may wrap it. + virtual Outcome run_action(RunState& state, const StoryStep& step); + private: + std::optional clear_interrupts(RunState& state, const StoryStep& step, size_t& cleared); + bool cleared_after_failure(RunState& state, const StoryStep& step, size_t& cleared); + const StoryActionTable& m_table; StepGuard& m_guard; + const StoryInterrupts* m_interrupts = nullptr; }; diff --git a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryEvents.cpp b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryEvents.cpp index 8ef5f5286f..79a095fb9f 100644 --- a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryEvents.cpp +++ b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryEvents.cpp @@ -161,6 +161,8 @@ Outcome attempt_event(Event& event, RunState& state){ return check_expects(event, state); } +} // namespace + void apply_interrupt_pose(Pose& pose, InterruptPose effect){ switch (effect){ case InterruptPose::UNCHANGED: @@ -177,6 +179,8 @@ void apply_interrupt_pose(Pose& pose, InterruptPose effect){ } } +namespace{ + // One event being run, with what it has used up. struct EventRun{ diff --git a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryEvents.h b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryEvents.h index a1b5ffaa2e..10e96b6bc4 100644 --- a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryEvents.h +++ b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryEvents.h @@ -195,6 +195,8 @@ struct Interrupt{ InterruptPose pose = InterruptPose::UNCHANGED; ResumePolicy resume = ResumePolicy::RETRY_EVENT; }; +// Writes what an interrupt did (`effect`) into `pose`. +void apply_interrupt_pose(Pose& pose, InterruptPose effect); // Story milestone containing pre/post conditions and a series of events. diff --git a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryInterrupts.cpp b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryInterrupts.cpp new file mode 100644 index 0000000000..258d334ba2 --- /dev/null +++ b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryInterrupts.cpp @@ -0,0 +1,96 @@ +/* Story Interrupts + * + * From: https://github.com/PokemonAutomation/ + * + */ + +#include +#include "Common/Cpp/Exceptions.h" +#include "Pokemon_StoryInterrupts.h" + +namespace PokemonAutomation{ +namespace Pokemon{ + + +void InterruptHandlerTable::add(InterruptKind kind, InterruptHandler handler){ + if (kind == InterruptKind::NONE || kind == InterruptKind::UNSETTLED){ + throw InternalProgramError( + nullptr, PA_CURRENT_FUNCTION, + std::string("No handler can clear ") + interrupt_kind_name(kind) + "." + ); + } + if (!m_handlers.emplace(kind, std::move(handler)).second){ + throw InternalProgramError( + nullptr, PA_CURRENT_FUNCTION, + std::string("A second interrupt handler for ") + interrupt_kind_name(kind) + ); + } +} + +const InterruptHandler* InterruptHandlerTable::find(InterruptKind kind) const{ + const auto iter = m_handlers.find(kind); + return iter == m_handlers.end() ? nullptr : &iter->second; +} + +void InterruptHandlerTable::starts_on(StoryStepKind step, InterruptKind kind){ + m_starts_on.emplace(step, kind); +} + +bool InterruptHandlerTable::step_starts_on(StoryStepKind step, InterruptKind kind) const{ + return m_starts_on.contains({step, kind}); +} + + +namespace{ + +InterruptVerdict judge(const StoryInterrupts& interrupts, bool fresh){ + const ScreenLook look = interrupts.look(fresh); + return classify_interrupt(look.log, look.window, interrupts.knobs); +} + +// The look's verdict, looked at again while it is unsettled, up to +// max_looks looks in all. +InterruptVerdict settled_verdict(const StoryInterrupts& interrupts){ + InterruptVerdict verdict = judge(interrupts, true); + for (size_t looks = 1; verdict.kind == InterruptKind::UNSETTLED && looks < interrupts.max_looks; looks++){ + verdict = judge(interrupts, false); + } + return verdict; +} + +} // namespace + + +InterruptCheck clear_story_interrupt(const StoryInterrupts& interrupts, RunState& state, const StoryStep& step){ + InterruptCheck out; + out.verdict = settled_verdict(interrupts); + const InterruptKind kind = out.verdict.kind; + if (kind == InterruptKind::NONE){ + return out; + } + if (interrupts.handlers.step_starts_on(step.kind, kind)){ + out.verdict = {}; + return out; + } + if (kind == InterruptKind::UNSETTLED){ + out.outcome = outcome_failed("interrupt_unsettled", step.name); + return out; + } + const InterruptHandler* handler = interrupts.handlers.find(kind); + if (handler == nullptr || !handler->handle){ + out.outcome = outcome_failed("unhandled_interrupt", std::string(interrupt_kind_name(kind)) + " before " + step.name); + return out; + } + const Outcome handled = handler->handle(state, out.verdict); + if (!handled.succeeded()){ + out.outcome = outcome_failed("interrupt_failed", std::string(interrupt_kind_name(kind)) + ": " + to_string(handled)); + return out; + } + apply_interrupt_pose(state.pose, handler->pose); + return out; +} + + + +} // namespace Pokemon +} // namespace PokemonAutomation diff --git a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryInterrupts.h b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryInterrupts.h new file mode 100644 index 0000000000..048aa8538f --- /dev/null +++ b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryInterrupts.h @@ -0,0 +1,118 @@ +/* Story Interrupts + * + * From: https://github.com/PokemonAutomation/ + * + * What stops the story between two of its steps: someone walks up and + * talks, a trainer sees us as a step ends, a wild battle starts on the + * last tile of a walk, a door takes us somewhere. A walk's own walker + * clears what happens part-way through it (Pokemon_LegWalker.h, BDSP's + * walks); this is what is left once a step has settled. + * + * Before each step, and after a step fails, the TableExecutor looks at + * the screen through the game's eyes (ScreenLookFunction), judges the + * look with the shared classifier (classify_interrupt()) and clears what + * it found with the game's handler for that kind of interrupt. The + * handlers are a table, like the story's actions: data a game binds to + * its console or its simulation, not a type per game. + * + * A step that starts on what the look found (a MASH on its scene's box, + * a BATTLE on its trainer's lines) is not interrupted by it: the table + * says which (InterruptHandlerTable::starts_on()). + * + */ + +#ifndef PokemonAutomation_Pokemon_StoryInterrupts_H +#define PokemonAutomation_Pokemon_StoryInterrupts_H + +#include +#include +#include +#include +#include +#include "Pokemon_Interrupts.h" +#include "Pokemon_ScreenEvents.h" +#include "Pokemon_StoryEvents.h" +#include "Pokemon_StorySteps.h" + +namespace PokemonAutomation{ +namespace Pokemon{ + + +// What a game saw of the screen between two steps: its timed events, and +// the span of them the classifier judges. +struct ScreenLook{ + ScreenEventLog log{}; + InterruptWindow window = {}; +}; + +// Looks at the screen. `fresh` starts a new look; otherwise the look goes +// on from the last one, to see how an unsettled screen ends. +using ScreenLookFunction = std::function; + +// Clears an interrupt a look found: flees or fights the battle, closes +// the dialog, waits out the warp. +using InterruptAction = std::function; + +// A row of an InterruptHandlerTable. +struct InterruptHandler{ + InterruptAction handle = {}; + // What clearing it did to where the player is. + InterruptPose pose = InterruptPose::UNCHANGED; +}; + + +// A game's handlers by kind of interrupt, and the steps that start on one. +class InterruptHandlerTable{ +public: + // The handler for `kind`: one of WILD_ENCOUNTER, TRAINER_SIGHT, + // DIALOG or WARP. Another kind, or a second handler for one, throws + // InternalProgramError. + void add(InterruptKind kind, InterruptHandler handler); + // The handler for `kind`; nullptr if there is none. + const InterruptHandler* find(InterruptKind kind) const; + + // Steps of `step` start on `kind` showing: before one, it is the + // step's to clear, not an interrupt. + void starts_on(StoryStepKind step, InterruptKind kind); + bool step_starts_on(StoryStepKind step, InterruptKind kind) const; + +private: + std::map m_handlers; + std::set> m_starts_on; +}; + + +// A game's interrupts between steps: how it looks, how it judges what it +// saw, and what it does about each kind. +struct StoryInterrupts{ + ScreenLookFunction look = {}; + InterruptKnobs knobs = {}; + InterruptHandlerTable handlers = {}; + // Looks at a screen that stays UNSETTLED (a fade with no battle yet) + // before it fails the step as "interrupt_unsettled". + size_t max_looks = 3; + // Interrupts cleared for one step before it fails as + // "too_many_interrupts". + size_t max_per_step = 3; +}; + + +// What a look between steps found, and what clearing it came to. +struct InterruptCheck{ + // NONE when nothing interrupted, or when the step starts on it. + InterruptVerdict verdict = {}; + // Failed when the look stayed unsettled, the kind had no handler, or + // the handler failed. + Outcome outcome = {}; +}; + +// Looks at the screen before `step` (or after it failed) and clears what +// interrupted the player, if anything, writing the handler's effect on +// the pose into `state`. +InterruptCheck clear_story_interrupt(const StoryInterrupts& interrupts, RunState& state, const StoryStep& step); + + + +} // namespace Pokemon +} // namespace PokemonAutomation +#endif diff --git a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryInterrupts_Tests.cpp b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryInterrupts_Tests.cpp new file mode 100644 index 0000000000..2dedf86142 --- /dev/null +++ b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryInterrupts_Tests.cpp @@ -0,0 +1,480 @@ +/* Story Interrupts Tests + * + * From: https://github.com/PokemonAutomation/ + * + * The table executor's looks between steps, against a fake game: a + * scripted screen and handlers that note what they cleared. + * + */ + +#include +#include +#include +#include +#include +#include +#include +#include "Common/Cpp/Exceptions.h" +#include "Common/Cpp/TestRunners/UnitTest.h" +#include "CommonFramework/Exceptions/OperationFailedException.h" +#include "Pokemon_StoryActions.h" +#include "Pokemon_StoryInterrupts.h" +#include "Pokemon_AutoStory_Tests.h" + +namespace PokemonAutomation{ +namespace Pokemon{ + + +namespace{ + +const WallClock T0 = WallClock() + std::chrono::hours(1); + +// One frame of a scripted screen: its events, at `ms` after T0. +struct Frame{ + int ms; + ScreenEvents events; +}; + +const ScreenEvents WALK{ScreenEvent::PLAYER_CAN_MOVE}; +const ScreenEvents BOX{ScreenEvent::DIALOG_BOX, ScreenEvent::PLAYER_CAN_MOVE}; +const ScreenEvents WHITE{ScreenEvent::FADE_WHITE}; +const ScreenEvents BLACK{ScreenEvent::FADE_BLACK}; +const ScreenEvents BATTLE{ScreenEvent::BATTLE_STARTED}; +const ScreenEvents BANNER{ScreenEvent::LOCATION_BANNER, ScreenEvent::PLAYER_CAN_MOVE}; + +// A look at `frames`, judged up to `until_ms`. +ScreenLook look_of(const std::vector& frames, int until_ms){ + ScreenLook look; + for (const Frame& frame : frames){ + look.log.record(frame.events, T0 + Milliseconds(frame.ms)); + } + look.window = {T0, T0 + Milliseconds(until_ms)}; + return look; +} + +ScreenLook quiet(){ + return look_of({{0, WALK}, {300, WALK}}, 300); +} +ScreenLook dialog(){ + return look_of({{0, WALK}, {100, BOX}}, 300); +} +ScreenLook wild(){ + return look_of({{0, WALK}, {100, WHITE}, {400, WALK}, {1500, BATTLE}}, 2000); +} +ScreenLook trainer(){ + return look_of({{0, WALK}, {100, BOX}, {2000, BLACK}, {2500, BATTLE}}, 3000); +} +ScreenLook warp(){ + return look_of({{0, WALK}, {100, BLACK}, {600, WALK}, {900, BANNER}}, 1200); +} +// A white fade with no battle yet: an encounter's flash or a cave exit. +ScreenLook white_unsettled(){ + return look_of({{0, WALK}, {100, WHITE}, {700, WALK}}, 1000); +} +// The same white, looked at for long enough after it: a cave exit. +ScreenLook white_settled(){ + return look_of({{0, WALK}, {100, WHITE}, {700, WALK}, {10000, WALK}}, 10000); +} + + +// The fake game: the screen its looks show, one per look and then the +// last again, and a trace of what was looked at, cleared and run. +struct FakeGame{ + std::vector screens; + size_t looks = 0; + std::vector trace; + + ScreenLook look(bool fresh){ + trace.push_back(fresh ? "look" : "look again"); + const ScreenLook& out = screens.empty() ? quiet() : screens[std::min(looks, screens.size() - 1)]; + looks++; + return out; + } +}; + +// A handler that notes its kind; fails with `failure` if set. +InterruptHandler noting(FakeGame& game, std::string name, InterruptPose pose = InterruptPose::UNCHANGED, std::string failure = ""){ + return InterruptHandler{ + .handle = [&game, name, failure](RunState&, const InterruptVerdict&){ + game.trace.push_back("clear " + name); + return failure.empty() ? outcome_ok() : outcome_failed(failure); + }, + .pose = pose, + }; +} + +// All four handlers, a warp losing the pose; MASH starts on a dialog. +StoryInterrupts fake_interrupts(FakeGame& game){ + StoryInterrupts interrupts; + interrupts.look = [&game](bool fresh){ + return game.look(fresh); + }; + interrupts.handlers.add(InterruptKind::WILD_ENCOUNTER, noting(game, "wild")); + interrupts.handlers.add(InterruptKind::TRAINER_SIGHT, noting(game, "trainer")); + interrupts.handlers.add(InterruptKind::DIALOG, noting(game, "dialog")); + interrupts.handlers.add(InterruptKind::WARP, noting(game, "warp", InterruptPose::LOST)); + interrupts.handlers.starts_on(StoryStepKind::MASH, InterruptKind::DIALOG); + return interrupts; +} + +StoryStep make(StoryStepKind kind, std::string name){ + StoryStep step; + step.kind = kind; + step.name = std::move(name); + return step; +} + +// The step's action: notes it ran, and fails its first `failures` runs, +// returning a failed Outcome or, with `throws`, throwing. +struct FakeAction{ + size_t failures = 0; + bool throws = false; +}; +StoryActionTable table_of(FakeGame& game, FakeAction action){ + StoryActionTable table; + auto runs = std::make_shared(0); + table.add_any_kind("act", StoryAction{ + .act = [&game, action, runs](RunState&, const StoryStep& step) -> Outcome{ + game.trace.push_back("run " + step.name); + if ((*runs)++ >= action.failures){ + return outcome_ok(); + } + if (action.throws){ + throw OperationFailedException(ErrorReportMode::NO_ERROR_REPORT, "stopped by a dialog"); + } + return outcome_failed("dialog", "stopped by a dialog"); + }, + }); + return table; +} + +// A guard that notes the interrupts it was told of. +class NotingGuard : public StepGuard{ +public: + explicit NotingGuard(FakeGame& game) + : m_game(game) + {} + virtual void on_interrupt(const StoryStep&, const InterruptCheck& check) override{ + m_game.trace.push_back(std::format("told {} {}", interrupt_kind_name(check.verdict.kind), to_string(check.outcome))); + } + +private: + FakeGame& m_game; +}; + +// `step` (variant "act") run once by a TableExecutor with the fake +// game's interrupts, from a known pose. +struct FakeRun{ + Outcome outcome; + RunState state; +}; +FakeRun run_step(FakeGame& game, StoryInterrupts& interrupts, StoryStep step, FakeAction action = {}){ + const StoryActionTable table = table_of(game, action); + NotingGuard guard(game); + TableExecutor executor(table, guard); + executor.set_interrupts(&interrupts); + FakeRun out; + out.state.pose.map = "Town"; + out.state.pose.certainty = PoseCertainty::TILE; + step.variant = "act"; + out.outcome = executor.run(out.state, step); + return out; +} + +UnitTestResult expect_trace(const FakeGame& game, const std::vector& expected){ + if (game.trace == expected){ + return true; + } + std::string out = "Expected the trace:"; + for (const std::string& line : expected){ + out += "\n " + line; + } + out += "\ngot:"; + for (const std::string& line : game.trace){ + out += "\n " + line; + } + return out; +} + + +UnitTestResult test_no_interrupts_set(){ + FakeGame game; + const StoryActionTable table = table_of(game, {}); + StepGuard guard; + TableExecutor executor(table, guard); + RunState state; + StoryStep step = make(StoryStepKind::ROUTE, "walk"); + step.variant = "act"; + const Outcome outcome = executor.run(state, step); + if (!outcome.succeeded()){ + return "Expected the step to succeed, got " + to_string(outcome); + } + return expect_trace(game, {"run walk"}); +} + +UnitTestResult test_quiet_screen(){ + FakeGame game; + StoryInterrupts interrupts = fake_interrupts(game); + const FakeRun run = run_step(game, interrupts, make(StoryStepKind::ROUTE, "walk")); + if (!run.outcome.succeeded() || run.state.pose.certainty != PoseCertainty::TILE){ + return "Expected the step to succeed where it stood, got " + to_string(run.outcome); + } + return expect_trace(game, {"look", "run walk"}); +} + +// A look showing `screen` before a ROUTE step: cleared by `handler`, then +// the step runs. +UnitTestResult test_cleared(ScreenLook screen, const std::string& kind, const std::string& handler, PoseCertainty pose){ + FakeGame game; + game.screens = {std::move(screen), quiet()}; + StoryInterrupts interrupts = fake_interrupts(game); + const FakeRun run = run_step(game, interrupts, make(StoryStepKind::ROUTE, "walk")); + if (!run.outcome.succeeded()){ + return "Expected the step to succeed, got " + to_string(run.outcome); + } + if (run.state.pose.certainty != pose){ + return std::string("Expected the pose ") + certainty_name(pose) + ", got " + certainty_name(run.state.pose.certainty); + } + return expect_trace(game, {"look", "clear " + handler, "told " + kind + " ", "run walk"}); +} + +UnitTestResult test_wild_encounter(){ + return test_cleared(wild(), "wild encounter", "wild", PoseCertainty::TILE); +} +UnitTestResult test_trainer_sight(){ + return test_cleared(trainer(), "trainer sight", "trainer", PoseCertainty::TILE); +} +UnitTestResult test_dialog(){ + return test_cleared(dialog(), "dialog", "dialog", PoseCertainty::TILE); +} +UnitTestResult test_warp(){ + return test_cleared(warp(), "warp", "warp", PoseCertainty::UNKNOWN); +} + +UnitTestResult test_step_starts_on_it(){ + FakeGame game; + game.screens = {dialog()}; + StoryInterrupts interrupts = fake_interrupts(game); + const FakeRun run = run_step(game, interrupts, make(StoryStepKind::MASH, "scene")); + if (!run.outcome.succeeded()){ + return "Expected the step to succeed, got " + to_string(run.outcome); + } + return expect_trace(game, {"look", "run scene"}); +} + +UnitTestResult test_handler_fails_the_step(){ + FakeGame game; + game.screens = {dialog()}; + StoryInterrupts interrupts = fake_interrupts(game); + interrupts.handlers = InterruptHandlerTable(); + interrupts.handlers.add(InterruptKind::DIALOG, noting(game, "dialog", InterruptPose::UNCHANGED, "still_up")); + const FakeRun run = run_step(game, interrupts, make(StoryStepKind::ROUTE, "walk")); + if (run.outcome.failure != "interrupt_failed" || run.outcome.detail != "dialog: still_up"){ + return "Expected interrupt_failed: dialog: still_up, got " + to_string(run.outcome); + } + return expect_trace(game, {"look", "clear dialog", "told dialog interrupt_failed: dialog: still_up"}); +} + +UnitTestResult test_unhandled_kind(){ + FakeGame game; + game.screens = {trainer()}; + StoryInterrupts interrupts = fake_interrupts(game); + interrupts.handlers = InterruptHandlerTable(); + const FakeRun run = run_step(game, interrupts, make(StoryStepKind::ROUTE, "walk")); + if (run.outcome.failure != "unhandled_interrupt"){ + return "Expected unhandled_interrupt, got " + to_string(run.outcome); + } + return expect_trace(game, {"look", "told trainer sight unhandled_interrupt: trainer sight before walk"}); +} + +UnitTestResult test_unsettled_looks_again(){ + FakeGame game; + game.screens = {white_unsettled(), white_settled(), quiet()}; + StoryInterrupts interrupts = fake_interrupts(game); + const FakeRun run = run_step(game, interrupts, make(StoryStepKind::ROUTE, "walk")); + if (!run.outcome.succeeded()){ + return "Expected the step to succeed, got " + to_string(run.outcome); + } + return expect_trace(game, {"look", "look again", "clear warp", "told warp ", "run walk"}); +} + +UnitTestResult test_unsettled_is_bounded(){ + FakeGame game; + game.screens = {white_unsettled()}; + StoryInterrupts interrupts = fake_interrupts(game); + const FakeRun run = run_step(game, interrupts, make(StoryStepKind::ROUTE, "walk")); + if (run.outcome.failure != "interrupt_unsettled"){ + return "Expected interrupt_unsettled, got " + to_string(run.outcome); + } + return expect_trace(game, {"look", "look again", "look again", "told unsettled interrupt_unsettled: walk"}); +} + +UnitTestResult test_failure_explained(bool throws){ + FakeGame game; + // Before the step, after its failure, before its second run. + game.screens = {quiet(), dialog(), quiet()}; + StoryInterrupts interrupts = fake_interrupts(game); + const FakeRun run = run_step(game, interrupts, make(StoryStepKind::ROUTE, "walk"), {.failures = 1, .throws = throws}); + if (!run.outcome.succeeded()){ + return "Expected the step run again and succeed, got " + to_string(run.outcome); + } + return expect_trace(game, {"look", "run walk", "look", "clear dialog", "told dialog ", "look", "run walk"}); +} +UnitTestResult test_failed_outcome_explained(){ + return test_failure_explained(false); +} +UnitTestResult test_thrown_failure_explained(){ + return test_failure_explained(true); +} + +UnitTestResult test_failure_not_explained(){ + FakeGame game; + StoryInterrupts interrupts = fake_interrupts(game); + const FakeRun run = run_step(game, interrupts, make(StoryStepKind::ROUTE, "walk"), {.failures = 1}); + if (run.outcome.failure != "dialog"){ + return "Expected the step's own failure, got " + to_string(run.outcome); + } + return expect_trace(game, {"look", "run walk", "look"}); +} + +// A step that keeps failing with a dialog that keeps coming back: run +// again while the dialogs are cleared, until there have been too many. +UnitTestResult test_too_many_interrupts(){ + FakeGame game; + game.screens = {dialog()}; + StoryInterrupts interrupts = fake_interrupts(game); + const FakeRun run = run_step(game, interrupts, make(StoryStepKind::ROUTE, "walk"), {.failures = 10}); + if (run.outcome.failure != "dialog" || game.looks != interrupts.max_per_step + 1){ + return std::format("Expected the step's own failure after {} looks, got {} after {}", + interrupts.max_per_step + 1, to_string(run.outcome), game.looks); + } + if (game.trace.back() != "told dialog too_many_interrupts: walk"){ + return "Expected the guard told of too many interrupts, got " + game.trace.back(); + } + return true; +} + +UnitTestResult test_table_rejects(){ + InterruptHandlerTable table; + table.add(InterruptKind::DIALOG, {}); + for (InterruptKind kind : {InterruptKind::NONE, InterruptKind::UNSETTLED, InterruptKind::DIALOG}){ + try{ + table.add(kind, {}); + return std::string("Expected a handler for ") + interrupt_kind_name(kind) + " rejected."; + }catch (InternalProgramError&){} + } + if (table.find(InterruptKind::DIALOG) == nullptr || table.find(InterruptKind::WARP) != nullptr){ + return "Expected the dialog's handler found and no warp's."; + } + return true; +} + + +struct StoryInterruptsInput{ + std::string_view name; + UnitTestResult (*test)(); +}; + +struct StoryInterruptsExpectation{ + std::string_view description; +}; + +struct StoryInterruptsCase{ + StoryInterruptsInput input; + StoryInterruptsExpectation expectation; +}; + +class Test_StoryInterrupts : public UnitTest{ +public: + explicit Test_StoryInterrupts(StoryInterruptsCase scenario) + : UnitTest("Pokemon::StoryInterrupts - " + std::string(scenario.input.name)) + , m_scenario(scenario) + {} + virtual UnitTestResult run(Logger&, CancellableScope&) const override{ + return m_scenario.input.test(); + } + +private: + StoryInterruptsCase m_scenario; +}; + +const StoryInterruptsCase STORY_INTERRUPTS_CASES[] = { + { + .input = {.name = "no interrupts set: no look", .test = test_no_interrupts_set}, + .expectation = {.description = "the executor runs the step as before"}, + }, + { + .input = {.name = "a quiet screen: one look, then the step", .test = test_quiet_screen}, + .expectation = {.description = "nothing cleared, the pose kept"}, + }, + { + .input = {.name = "a wild encounter before a step", .test = test_wild_encounter}, + .expectation = {.description = "the wild handler, then the step"}, + }, + { + .input = {.name = "a trainer's sight before a step", .test = test_trainer_sight}, + .expectation = {.description = "the trainer handler, then the step"}, + }, + { + .input = {.name = "a dialog before a step", .test = test_dialog}, + .expectation = {.description = "the dialog handler, then the step"}, + }, + { + .input = {.name = "a warp before a step", .test = test_warp}, + .expectation = {.description = "the warp handler, the pose lost, then the step"}, + }, + { + .input = {.name = "a step that starts on it", .test = test_step_starts_on_it}, + .expectation = {.description = "a MASH's box is the step's, not an interrupt"}, + }, + { + .input = {.name = "a handler that fails fails the step", .test = test_handler_fails_the_step}, + .expectation = {.description = "interrupt_failed, the step not run"}, + }, + { + .input = {.name = "a kind with no handler fails the step", .test = test_unhandled_kind}, + .expectation = {.description = "unhandled_interrupt, the step not run"}, + }, + { + .input = {.name = "unsettled: look again until it settles", .test = test_unsettled_looks_again}, + .expectation = {.description = "a white with no battle after it is a warp"}, + }, + { + .input = {.name = "unsettled: at most max_looks looks", .test = test_unsettled_is_bounded}, + .expectation = {.description = "interrupt_unsettled after three looks"}, + }, + { + .input = {.name = "a failed step an interrupt explains runs again", .test = test_failed_outcome_explained}, + .expectation = {.description = "cleared after the failure, then the step again"}, + }, + { + .input = {.name = "a thrown step an interrupt explains runs again", .test = test_thrown_failure_explained}, + .expectation = {.description = "the console's failure too"}, + }, + { + .input = {.name = "a failed step with nothing on screen fails", .test = test_failure_not_explained}, + .expectation = {.description = "the step's own failure, run once"}, + }, + { + .input = {.name = "too many interrupts fail the step", .test = test_too_many_interrupts}, + .expectation = {.description = "the step's failure once max_per_step are cleared"}, + }, + { + .input = {.name = "table: one handler a kind that can be cleared", .test = test_table_rejects}, + .expectation = {.description = "rejects NONE, UNSETTLED and a second handler"}, + }, +}; + +} // namespace + + +void add_tests_StoryInterrupts(UnitTestDatabase& database){ + for (const StoryInterruptsCase& scenario : STORY_INTERRUPTS_CASES){ + database.add(scenario); + } +} + + + +} // namespace Pokemon +} // namespace PokemonAutomation diff --git a/SerialPrograms/cmake/SourceFiles.cmake b/SerialPrograms/cmake/SourceFiles.cmake index eb33f74317..fc888392dc 100644 --- a/SerialPrograms/cmake/SourceFiles.cmake +++ b/SerialPrograms/cmake/SourceFiles.cmake @@ -1512,6 +1512,9 @@ file(GLOB LIBRARY_SOURCES Source/Pokemon/AutoStory/Pokemon_StoryEvents.cpp Source/Pokemon/AutoStory/Pokemon_StoryEvents.h Source/Pokemon/AutoStory/Pokemon_StoryEvents_Tests.cpp + Source/Pokemon/AutoStory/Pokemon_StoryInterrupts.cpp + Source/Pokemon/AutoStory/Pokemon_StoryInterrupts.h + Source/Pokemon/AutoStory/Pokemon_StoryInterrupts_Tests.cpp Source/Pokemon/AutoStory/Pokemon_StorySegments.cpp Source/Pokemon/AutoStory/Pokemon_StorySegments.h Source/Pokemon/AutoStory/Pokemon_StorySegments_Tests.cpp From 680662b0a4772c09cac638f7597b347504675de0 Mon Sep 17 00:00:00 2001 From: dayfine Date: Mon, 9 Nov 2026 12:18:01 -0800 Subject: [PATCH 024/102] StoryInterrupts: a battle's opening before a battle step is the step's An UNSETTLED look (a fade with no battle yet) failed any step as interrupt_unsettled after three looks, including a BATTLE step whose battle was already opening (BDSP 00.02's Starly battle right after the starter pick, lab-B run 3). A step that starts on WILD_ENCOUNTER or TRAINER_SIGHT now starts on UNSETTLED too, and gets it on the first look. Walk steps keep the check. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_013VUubhHeYSMGSSDXZkKZss --- .../AutoStory/Pokemon_StoryInterrupts.cpp | 17 +++++++++++++---- .../AutoStory/Pokemon_StoryInterrupts.h | 11 ++++++++--- .../Pokemon_StoryInterrupts_Tests.cpp | 19 +++++++++++++++++++ 3 files changed, 40 insertions(+), 7 deletions(-) diff --git a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryInterrupts.cpp b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryInterrupts.cpp index 258d334ba2..0f64cbb35e 100644 --- a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryInterrupts.cpp +++ b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryInterrupts.cpp @@ -37,7 +37,13 @@ void InterruptHandlerTable::starts_on(StoryStepKind step, InterruptKind kind){ } bool InterruptHandlerTable::step_starts_on(StoryStepKind step, InterruptKind kind) const{ - return m_starts_on.contains({step, kind}); + if (m_starts_on.contains({step, kind})){ + return true; + } + return kind == InterruptKind::UNSETTLED && ( + m_starts_on.contains({step, InterruptKind::WILD_ENCOUNTER}) || + m_starts_on.contains({step, InterruptKind::TRAINER_SIGHT}) + ); } @@ -49,9 +55,12 @@ InterruptVerdict judge(const StoryInterrupts& interrupts, bool fresh){ } // The look's verdict, looked at again while it is unsettled, up to -// max_looks looks in all. -InterruptVerdict settled_verdict(const StoryInterrupts& interrupts){ +// max_looks looks in all; not again before a step that starts on it. +InterruptVerdict settled_verdict(const StoryInterrupts& interrupts, StoryStepKind step){ InterruptVerdict verdict = judge(interrupts, true); + if (interrupts.handlers.step_starts_on(step, InterruptKind::UNSETTLED)){ + return verdict; + } for (size_t looks = 1; verdict.kind == InterruptKind::UNSETTLED && looks < interrupts.max_looks; looks++){ verdict = judge(interrupts, false); } @@ -63,7 +72,7 @@ InterruptVerdict settled_verdict(const StoryInterrupts& interrupts){ InterruptCheck clear_story_interrupt(const StoryInterrupts& interrupts, RunState& state, const StoryStep& step){ InterruptCheck out; - out.verdict = settled_verdict(interrupts); + out.verdict = settled_verdict(interrupts, step.kind); const InterruptKind kind = out.verdict.kind; if (kind == InterruptKind::NONE){ return out; diff --git a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryInterrupts.h b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryInterrupts.h index 048aa8538f..76df68eb3e 100644 --- a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryInterrupts.h +++ b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryInterrupts.h @@ -17,7 +17,10 @@ * * A step that starts on what the look found (a MASH on its scene's box, * a BATTLE on its trainer's lines) is not interrupted by it: the table - * says which (InterruptHandlerTable::starts_on()). + * says which (InterruptHandlerTable::starts_on()). A step that starts on + * a battle also starts on an UNSETTLED screen, a fade with no battle yet: + * that is its battle's opening, still playing (BDSP's Starly battle right + * after the starter is picked), and the step waits for it itself. * */ @@ -72,7 +75,8 @@ class InterruptHandlerTable{ const InterruptHandler* find(InterruptKind kind) const; // Steps of `step` start on `kind` showing: before one, it is the - // step's to clear, not an interrupt. + // step's to clear, not an interrupt. A step that starts on + // WILD_ENCOUNTER or TRAINER_SIGHT starts on UNSETTLED too. void starts_on(StoryStepKind step, InterruptKind kind); bool step_starts_on(StoryStepKind step, InterruptKind kind) const; @@ -89,7 +93,8 @@ struct StoryInterrupts{ InterruptKnobs knobs = {}; InterruptHandlerTable handlers = {}; // Looks at a screen that stays UNSETTLED (a fade with no battle yet) - // before it fails the step as "interrupt_unsettled". + // before it fails the step as "interrupt_unsettled". A step that + // starts on it gets it on the first look. size_t max_looks = 3; // Interrupts cleared for one step before it fails as // "too_many_interrupts". diff --git a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryInterrupts_Tests.cpp b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryInterrupts_Tests.cpp index 2dedf86142..8f4d0644c5 100644 --- a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryInterrupts_Tests.cpp +++ b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryInterrupts_Tests.cpp @@ -309,6 +309,21 @@ UnitTestResult test_unsettled_is_bounded(){ return expect_trace(game, {"look", "look again", "look again", "told unsettled interrupt_unsettled: walk"}); } +// A battle's opening still playing when a step that starts on a battle +// begins (BDSP's Starly battle, right after the starter is picked): the +// step's, on the first look, not interrupt_unsettled. +UnitTestResult test_unsettled_before_a_battle(){ + FakeGame game; + game.screens = {white_unsettled()}; + StoryInterrupts interrupts = fake_interrupts(game); + interrupts.handlers.starts_on(StoryStepKind::BATTLE, InterruptKind::WILD_ENCOUNTER); + const FakeRun run = run_step(game, interrupts, make(StoryStepKind::BATTLE, "starly")); + if (!run.outcome.succeeded()){ + return "Expected the battle step to run, got " + to_string(run.outcome); + } + return expect_trace(game, {"look", "run starly"}); +} + UnitTestResult test_failure_explained(bool throws){ FakeGame game; // Before the step, after its failure, before its second run. @@ -443,6 +458,10 @@ const StoryInterruptsCase STORY_INTERRUPTS_CASES[] = { .input = {.name = "unsettled: at most max_looks looks", .test = test_unsettled_is_bounded}, .expectation = {.description = "interrupt_unsettled after three looks"}, }, + { + .input = {.name = "unsettled: a battle's opening before a battle step", .test = test_unsettled_before_a_battle}, + .expectation = {.description = "the step's, after one look"}, + }, { .input = {.name = "a failed step an interrupt explains runs again", .test = test_failed_outcome_explained}, .expectation = {.description = "cleared after the failure, then the step again"}, From 46c99dca6c32acf83259c1137209196d8ef6f662 Mon Sep 17 00:00:00 2001 From: dayfine Date: Mon, 9 Nov 2026 14:14:06 -0800 Subject: [PATCH 025/102] StoryInterrupts tests: a battle's opening before a walk step (red) The BDSP fault sweep (#226) injects a battle's opening at the start of each step after a walk: 51 steps of 00.01-01.11 fail as interrupt_unsettled after three looks, as the opening takes longer than three looks to show its battle. These cases expect the looks to wait for the battle and clear it before the walk. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_013VUubhHeYSMGSSDXZkKZss --- .../Pokemon_StoryInterrupts_Tests.cpp | 36 +++++++++++++++++++ 1 file changed, 36 insertions(+) diff --git a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryInterrupts_Tests.cpp b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryInterrupts_Tests.cpp index 8f4d0644c5..a86d058fb8 100644 --- a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryInterrupts_Tests.cpp +++ b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryInterrupts_Tests.cpp @@ -71,6 +71,10 @@ ScreenLook warp(){ ScreenLook white_unsettled(){ return look_of({{0, WALK}, {100, WHITE}, {700, WALK}}, 1000); } +// A trainer's lines, then the battle's black, still down: no battle yet. +ScreenLook trainer_opening(){ + return look_of({{0, WALK}, {100, BOX}, {2000, BLACK}}, 2100); +} // The same white, looked at for long enough after it: a cave exit. ScreenLook white_settled(){ return look_of({{0, WALK}, {100, WHITE}, {700, WALK}, {10000, WALK}}, 10000); @@ -324,6 +328,30 @@ UnitTestResult test_unsettled_before_a_battle(){ return expect_trace(game, {"look", "run starly"}); } +// A battle's opening still playing when a walk step begins: the walk +// before it ended in grass or in a trainer's sight (BDSP fault sweep, 51 +// steps of 00.01-01.11). The looks wait for the battle, past max_looks, +// and its handler clears it before the step. +UnitTestResult test_opening_before_a_walk(ScreenLook opening, ScreenLook battle, const std::string& kind, const std::string& handler){ + FakeGame game; + game.screens = {opening, opening, opening, opening, std::move(battle), quiet()}; + StoryInterrupts interrupts = fake_interrupts(game); + const FakeRun run = run_step(game, interrupts, make(StoryStepKind::ROUTE, "walk")); + if (!run.outcome.succeeded()){ + return "Expected the walk to run after the battle, got " + to_string(run.outcome); + } + return expect_trace(game, { + "look", "look again", "look again", "look again", "look again", + "clear " + handler, "told " + kind + " ", "run walk", + }); +} +UnitTestResult test_wild_opening_before_a_walk(){ + return test_opening_before_a_walk(white_unsettled(), wild(), "wild encounter", "wild"); +} +UnitTestResult test_trainer_opening_before_a_walk(){ + return test_opening_before_a_walk(trainer_opening(), trainer(), "trainer sight", "trainer"); +} + UnitTestResult test_failure_explained(bool throws){ FakeGame game; // Before the step, after its failure, before its second run. @@ -462,6 +490,14 @@ const StoryInterruptsCase STORY_INTERRUPTS_CASES[] = { .input = {.name = "unsettled: a battle's opening before a battle step", .test = test_unsettled_before_a_battle}, .expectation = {.description = "the step's, after one look"}, }, + { + .input = {.name = "unsettled: a wild battle's opening before a walk", .test = test_wild_opening_before_a_walk}, + .expectation = {.description = "waits for the battle, clears it, then the walk"}, + }, + { + .input = {.name = "unsettled: a trainer battle's opening before a walk", .test = test_trainer_opening_before_a_walk}, + .expectation = {.description = "waits for the battle, fights it, then the walk"}, + }, { .input = {.name = "a failed step an interrupt explains runs again", .test = test_failed_outcome_explained}, .expectation = {.description = "cleared after the failure, then the step again"}, From 0be68acae1a1ab8ed43035bacc5672dc4afbf945 Mon Sep 17 00:00:00 2001 From: dayfine Date: Mon, 9 Nov 2026 14:15:01 -0800 Subject: [PATCH 026/102] StoryInterrupts: wait for a battle's opening before any step A walk that ends in grass or in a trainer's sight leaves the next step to start on the battle's opening: a white flash, or a fade still down, with no battle yet. Three looks (0.9 s on BDSP) were too few for its battle to show, and the step failed as interrupt_unsettled (BDSP fault sweep, #226: 51 steps of 00.01-01.11). An unsettled screen that may be a battle's opening (a white fade, a fade still down, or a fade after a dialog box) is now looked at up to max_opening_looks (40) looks, until its battle shows; the battle is then cleared by its handler (wild: run, trainer: fight) and the step goes on. A door's fade, back up with no box before it, keeps the three looks. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_013VUubhHeYSMGSSDXZkKZss --- .../AutoStory/Pokemon_StoryInterrupts.cpp | 40 +++++++++++++++---- .../AutoStory/Pokemon_StoryInterrupts.h | 11 +++++ .../Pokemon_StoryInterrupts_Tests.cpp | 29 +++++++++++++- 3 files changed, 71 insertions(+), 9 deletions(-) diff --git a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryInterrupts.cpp b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryInterrupts.cpp index 0f64cbb35e..32a14b42fa 100644 --- a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryInterrupts.cpp +++ b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryInterrupts.cpp @@ -4,6 +4,7 @@ * */ +#include #include #include "Common/Cpp/Exceptions.h" #include "Pokemon_StoryInterrupts.h" @@ -49,20 +50,45 @@ bool InterruptHandlerTable::step_starts_on(StoryStepKind step, InterruptKind kin namespace{ -InterruptVerdict judge(const StoryInterrupts& interrupts, bool fresh){ - const ScreenLook look = interrupts.look(fresh); - return classify_interrupt(look.log, look.window, interrupts.knobs); +// Whether an UNSETTLED verdict on `look` may be a battle's opening: its +// fade is white (an encounter's flash), still down (a battle's fade ends +// on the battle), or came after a dialog box (a trainer's lines). +bool may_open_a_battle(const ScreenLook& look, const InterruptVerdict& verdict){ + const auto fade = std::find_if(verdict.evidence.begin(), verdict.evidence.end(), [](const ScreenEventChange& change){ + return change.edge == ScreenEventEdge::ROSE && + (change.event == ScreenEvent::FADE_WHITE || change.event == ScreenEvent::FADE_BLACK); + }); + if (fade == verdict.evidence.end()){ + return false; + } + const bool still_down = std::none_of(verdict.evidence.begin(), verdict.evidence.end(), [](const ScreenEventChange& change){ + return change.edge == ScreenEventEdge::FELL; + }); + if (fade->event == ScreenEvent::FADE_WHITE || still_down){ + return true; + } + return std::any_of(look.log.changes().begin(), look.log.changes().end(), [&](const ScreenEventChange& change){ + return change.event == ScreenEvent::DIALOG_BOX && change.edge == ScreenEventEdge::ROSE && + look.window.start <= change.time && change.time < fade->time; + }); } // The look's verdict, looked at again while it is unsettled, up to -// max_looks looks in all; not again before a step that starts on it. +// max_looks looks in all, or max_opening_looks while it may be a battle's +// opening; not again before a step that starts on it. InterruptVerdict settled_verdict(const StoryInterrupts& interrupts, StoryStepKind step){ - InterruptVerdict verdict = judge(interrupts, true); + ScreenLook look = interrupts.look(true); + InterruptVerdict verdict = classify_interrupt(look.log, look.window, interrupts.knobs); if (interrupts.handlers.step_starts_on(step, InterruptKind::UNSETTLED)){ return verdict; } - for (size_t looks = 1; verdict.kind == InterruptKind::UNSETTLED && looks < interrupts.max_looks; looks++){ - verdict = judge(interrupts, false); + for (size_t looks = 1; verdict.kind == InterruptKind::UNSETTLED; looks++){ + const size_t limit = may_open_a_battle(look, verdict) ? interrupts.max_opening_looks : interrupts.max_looks; + if (looks >= limit){ + break; + } + look = interrupts.look(false); + verdict = classify_interrupt(look.log, look.window, interrupts.knobs); } return verdict; } diff --git a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryInterrupts.h b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryInterrupts.h index 76df68eb3e..1a43414580 100644 --- a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryInterrupts.h +++ b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryInterrupts.h @@ -22,6 +22,13 @@ * that is its battle's opening, still playing (BDSP's Starly battle right * after the starter is picked), and the step waits for it itself. * + * Before another step, an unsettled screen that may be a battle's opening + * (a white flash, a fade still down, a fade after a dialog box) is looked + * at until its battle shows, up to max_opening_looks looks: the walk + * before the step ended in grass or in a trainer's sight. The battle is + * then cleared as any other. A fade that came back up with no box before + * it (a door's) is looked at max_looks times only. + * */ #ifndef PokemonAutomation_Pokemon_StoryInterrupts_H @@ -96,6 +103,10 @@ struct StoryInterrupts{ // before it fails the step as "interrupt_unsettled". A step that // starts on it gets it on the first look. size_t max_looks = 3; + // The same, for a screen that may be a battle's opening: enough looks + // for its battle to show. BDSP's 300 ms looks cover 12 s, past its + // battle_after_fade (8 s), after which a fade with no battle settles. + size_t max_opening_looks = 40; // Interrupts cleared for one step before it fails as // "too_many_interrupts". size_t max_per_step = 3; diff --git a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryInterrupts_Tests.cpp b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryInterrupts_Tests.cpp index a86d058fb8..187a6b14a5 100644 --- a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryInterrupts_Tests.cpp +++ b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryInterrupts_Tests.cpp @@ -75,6 +75,10 @@ ScreenLook white_unsettled(){ ScreenLook trainer_opening(){ return look_of({{0, WALK}, {100, BOX}, {2000, BLACK}}, 2100); } +// A door's black, back up with no box before it: a warp, not yet settled. +ScreenLook black_unsettled(){ + return look_of({{0, WALK}, {100, BLACK}, {700, WALK}}, 1000); +} // The same white, looked at for long enough after it: a cave exit. ScreenLook white_settled(){ return look_of({{0, WALK}, {100, WHITE}, {700, WALK}, {10000, WALK}}, 10000); @@ -302,9 +306,10 @@ UnitTestResult test_unsettled_looks_again(){ return expect_trace(game, {"look", "look again", "clear warp", "told warp ", "run walk"}); } +// A door's fade is no battle's opening: three looks, as before. UnitTestResult test_unsettled_is_bounded(){ FakeGame game; - game.screens = {white_unsettled()}; + game.screens = {black_unsettled()}; StoryInterrupts interrupts = fake_interrupts(game); const FakeRun run = run_step(game, interrupts, make(StoryStepKind::ROUTE, "walk")); if (run.outcome.failure != "interrupt_unsettled"){ @@ -352,6 +357,22 @@ UnitTestResult test_trainer_opening_before_a_walk(){ return test_opening_before_a_walk(trainer_opening(), trainer(), "trainer sight", "trainer"); } +// A white that shows no battle and does not settle: max_opening_looks. +UnitTestResult test_opening_is_bounded(){ + FakeGame game; + game.screens = {white_unsettled()}; + StoryInterrupts interrupts = fake_interrupts(game); + interrupts.max_opening_looks = 5; + const FakeRun run = run_step(game, interrupts, make(StoryStepKind::ROUTE, "walk")); + if (run.outcome.failure != "interrupt_unsettled"){ + return "Expected interrupt_unsettled, got " + to_string(run.outcome); + } + return expect_trace(game, { + "look", "look again", "look again", "look again", "look again", + "told unsettled interrupt_unsettled: walk", + }); +} + UnitTestResult test_failure_explained(bool throws){ FakeGame game; // Before the step, after its failure, before its second run. @@ -484,7 +505,7 @@ const StoryInterruptsCase STORY_INTERRUPTS_CASES[] = { }, { .input = {.name = "unsettled: at most max_looks looks", .test = test_unsettled_is_bounded}, - .expectation = {.description = "interrupt_unsettled after three looks"}, + .expectation = {.description = "a door's fade: interrupt_unsettled after three looks"}, }, { .input = {.name = "unsettled: a battle's opening before a battle step", .test = test_unsettled_before_a_battle}, @@ -498,6 +519,10 @@ const StoryInterruptsCase STORY_INTERRUPTS_CASES[] = { .input = {.name = "unsettled: a trainer battle's opening before a walk", .test = test_trainer_opening_before_a_walk}, .expectation = {.description = "waits for the battle, fights it, then the walk"}, }, + { + .input = {.name = "unsettled: at most max_opening_looks for an opening", .test = test_opening_is_bounded}, + .expectation = {.description = "a white with no battle: interrupt_unsettled"}, + }, { .input = {.name = "a failed step an interrupt explains runs again", .test = test_failed_outcome_explained}, .expectation = {.description = "cleared after the failure, then the step again"}, From 500e624763a415b5c9d54fcdd9d1b45f9e7caa14 Mon Sep 17 00:00:00 2001 From: dayfine Date: Mon, 9 Nov 2026 14:46:04 -0800 Subject: [PATCH 027/102] Scene judges tests: a closing fade is no quiet (red) Mom's Running Shoes scene (lab-B 2026-11-09 14:33) ended at the start of its closing fade: BDSP's overworld reads a black frame as no box and it stays still, so TalkOver counted it as quiet. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_013VUubhHeYSMGSSDXZkKZss --- .../Pokemon/AutoStory/Pokemon_ScreenEvents_Tests.cpp | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_ScreenEvents_Tests.cpp b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_ScreenEvents_Tests.cpp index 2d0db31cfd..6620fd0204 100644 --- a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_ScreenEvents_Tests.cpp +++ b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_ScreenEvents_Tests.cpp @@ -115,6 +115,9 @@ int first_beat(TalkOver& judge, const std::vector& beats, SceneMov const ScreenEvents QUIET{ScreenEvent::PLAYER_CAN_MOVE, ScreenEvent::SCREEN_STILL}; const ScreenEvents CALM{ScreenEvent::PLAYER_CAN_MOVE}; const ScreenEvents BOX{ScreenEvent::DIALOG_BOX, ScreenEvent::PLAYER_CAN_MOVE, ScreenEvent::SCREEN_STILL}; +// A black frame as BDSP's eyes see it: no box, so "overworld", and still. +const ScreenEvents FADED{ScreenEvent::FADE_BLACK, ScreenEvent::PLAYER_CAN_MOVE, ScreenEvent::SCREEN_STILL}; +const ScreenEvents CALM_FADED{ScreenEvent::FADE_BLACK, ScreenEvent::PLAYER_CAN_MOVE}; std::vector repeat(const ScreenEvents& look, size_t count){ return std::vector(count, look); @@ -146,6 +149,14 @@ UnitTestResult test_talk_over(){ SceneMove::DONE, 6}, {"no quiet ends a talk before a battle", {.end_on_quiet = false}, repeat(QUIET, 30), SceneMove::DONE, -1}, {"a battle", {.end_on_quiet = false}, concat(repeat(QUIET, 6), {ScreenEvents{ScreenEvent::BATTLE_STARTED}}), SceneMove::BATTLE, 6}, + // Mom's Running Shoes scene (lab-B 2026-11-09 14:33): quiet, then + // the scene's closing fade. It ended at the fade's start and the + // next step's input landed in the fade. + {"a closing fade starts the quiet over", {}, + concat(concat(repeat(QUIET, 4), repeat(FADED, 3)), repeat(QUIET, 8)), + SceneMove::DONE, 12}, + {"a fade still down never ends it", {}, concat(repeat(QUIET, 3), repeat(FADED, 20)), SceneMove::DONE, -1}, + {"a fade is never calm", {}, concat(repeat(CALM, 10), repeat(CALM_FADED, 10)), SceneMove::DONE, -1}, }; for (const Row& row : rows){ TalkOver judge(row.rule); From 7c6e9bd4c41e6b74e8cad10d4b2c43d27cbca27c Mon Sep 17 00:00:00 2001 From: dayfine Date: Mon, 9 Nov 2026 14:49:51 -0800 Subject: [PATCH 028/102] Scene judges: a fade ends no quiet; log the screen before every step TalkOver counted a black frame as quiet overworld (BDSP reads it as no box, and it stays still), so Mom's Running Shoes scene ended as its closing fade went down and the next step's input landed in the fade (lab-B 2026-11-09 14:33). A look that shows a fade now starts the quiet and the calm over: a scene ends once every fade is back up, no box shows and the overworld has been quiet for TALK_OVER_QUIET. The look before each step now also says how the screen ended (judge_settle(): its last frame's events and how long they held), and the TableExecutor hands it to StepGuard::on_screen() for every step, interrupt or not, so a run log shows whether the scene had ended before the first input. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_013VUubhHeYSMGSSDXZkKZss --- .../Pokemon/AutoStory/Pokemon_SceneJudges.cpp | 14 +++- .../Pokemon/AutoStory/Pokemon_SceneJudges.h | 5 ++ .../AutoStory/Pokemon_StoryActions.cpp | 3 + .../Pokemon/AutoStory/Pokemon_StoryActions.h | 4 + .../AutoStory/Pokemon_StoryInterrupts.cpp | 66 +++++++++++++--- .../AutoStory/Pokemon_StoryInterrupts.h | 22 ++++++ .../Pokemon_StoryInterrupts_Tests.cpp | 75 +++++++++++++++++++ 7 files changed, 174 insertions(+), 15 deletions(-) diff --git a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_SceneJudges.cpp b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_SceneJudges.cpp index 628be668dc..b92a63e2a9 100644 --- a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_SceneJudges.cpp +++ b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_SceneJudges.cpp @@ -38,12 +38,17 @@ SceneMove TalkOver::look(const ScreenEvents& look, WallClock now){ m_calm_since = WallClock::max(); return SceneMove::BATTLE; } - if (fade_in(look) != WarpFade::NONE){ - m_fade = fade_in(look); + m_fade_showing = fade_in(look); + if (m_fade_showing != WarpFade::NONE){ + m_fade = m_fade_showing; } m_banner |= look.has(ScreenEvent::LOCATION_BANNER); const bool box = look.has(ScreenEvent::DIALOG_BOX); - const bool calm = !box && look.has(ScreenEvent::PLAYER_CAN_MOVE) && warped(); + // A fade is never calm: BDSP's overworld reads a black frame as no + // box, and black stays still, so a closing fade counted as quiet and + // ended Mom's scene as it went down (lab-B 2026-11-09 14:33). + const bool calm = !box && m_fade_showing == WarpFade::NONE && + look.has(ScreenEvent::PLAYER_CAN_MOVE) && warped(); const bool quiet = calm && look.has(ScreenEvent::SCREEN_STILL); if (!calm){ m_calm_since = WallClock::max(); @@ -73,6 +78,9 @@ std::string TalkOver::describe() const{ return "no fade or banner"; } std::string out = m_fade == WarpFade::NONE ? "" : warp_fade_name(m_fade); + if (m_fade != WarpFade::NONE){ + out += m_fade_showing == WarpFade::NONE ? " back up" : " still down"; + } if (m_banner){ out += out.empty() ? "banner read" : ", banner read"; } diff --git a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_SceneJudges.h b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_SceneJudges.h index 704ecf9a86..908dcaa39c 100644 --- a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_SceneJudges.h +++ b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_SceneJudges.h @@ -71,6 +71,9 @@ constexpr Milliseconds TALK_OVER_CALM = Milliseconds(15000); // When a talk or a scene is over, from looks alone. A look is a frame's // events: DIALOG_BOX, PLAYER_CAN_MOVE, SCREEN_STILL, a fade, // LOCATION_BANNER (the expected map's) and BATTLE_STARTED are read. +// It is over only once every fade has come back up, no box shows, and +// the overworld has been quiet (or calm) since: a look that shows a fade +// starts the quiet over, however still it is. class TalkOver{ public: explicit TalkOver(TalkOverRule rule = {}) @@ -86,7 +89,9 @@ class TalkOver{ private: TalkOverRule m_rule; + // The first fade seen, and the one the last look showed. WarpFade m_fade = WarpFade::NONE; + WarpFade m_fade_showing = WarpFade::NONE; bool m_banner = false; WallClock m_quiet_since = WallClock::max(); WallClock m_calm_since = WallClock::max(); diff --git a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryActions.cpp b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryActions.cpp index 349aa3e530..d09f78f553 100644 --- a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryActions.cpp +++ b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryActions.cpp @@ -87,6 +87,8 @@ void StepGuard::on_failure(const StoryStep&, const OperationFailedException&){} void StepGuard::on_interrupt(const StoryStep&, const InterruptCheck&){} +void StepGuard::on_screen(const StoryStep&, const ScreenSettle&){} + TableExecutor::TableExecutor(const StoryActionTable& table, StepGuard& guard) : m_table(table) @@ -133,6 +135,7 @@ std::optional TableExecutor::clear_interrupts(RunState& state, const St return std::nullopt; } InterruptCheck check = clear_story_interrupt(*m_interrupts, state, step); + m_guard.on_screen(step, check.screen); if (check.verdict.kind == InterruptKind::NONE){ return std::nullopt; } diff --git a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryActions.h b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryActions.h index 9f66529814..e672b0df15 100644 --- a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryActions.h +++ b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryActions.h @@ -96,6 +96,10 @@ class StepGuard{ // A look before the step, or after it failed, found an interrupt and // cleared it or failed to (`check`): e.g. log it. virtual void on_interrupt(const StoryStep& step, const InterruptCheck& check); + // How the screen looked when the look before the step (or after it + // failed) ended, interrupt or not: e.g. log it, so a run log shows + // whether the scene before had ended before the step's first input. + virtual void on_screen(const StoryStep& step, const ScreenSettle& screen); }; diff --git a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryInterrupts.cpp b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryInterrupts.cpp index 32a14b42fa..8fe58620e9 100644 --- a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryInterrupts.cpp +++ b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryInterrupts.cpp @@ -5,6 +5,9 @@ */ #include +#include +#include +#include #include #include "Common/Cpp/Exceptions.h" #include "Pokemon_StoryInterrupts.h" @@ -75,30 +78,69 @@ bool may_open_a_battle(const ScreenLook& look, const InterruptVerdict& verdict){ // The look's verdict, looked at again while it is unsettled, up to // max_looks looks in all, or max_opening_looks while it may be a battle's -// opening; not again before a step that starts on it. -InterruptVerdict settled_verdict(const StoryInterrupts& interrupts, StoryStepKind step){ +// opening; not again before a step that starts on it. `screen` is how the +// last look ended. +InterruptVerdict settled_verdict(const StoryInterrupts& interrupts, StoryStepKind step, ScreenSettle& screen){ ScreenLook look = interrupts.look(true); InterruptVerdict verdict = classify_interrupt(look.log, look.window, interrupts.knobs); - if (interrupts.handlers.step_starts_on(step, InterruptKind::UNSETTLED)){ - return verdict; - } - for (size_t looks = 1; verdict.kind == InterruptKind::UNSETTLED; looks++){ - const size_t limit = may_open_a_battle(look, verdict) ? interrupts.max_opening_looks : interrupts.max_looks; - if (looks >= limit){ - break; + if (!interrupts.handlers.step_starts_on(step, InterruptKind::UNSETTLED)){ + for (size_t looks = 1; verdict.kind == InterruptKind::UNSETTLED; looks++){ + const size_t limit = may_open_a_battle(look, verdict) ? interrupts.max_opening_looks : interrupts.max_looks; + if (looks >= limit){ + break; + } + look = interrupts.look(false); + verdict = classify_interrupt(look.log, look.window, interrupts.knobs); } - look = interrupts.look(false); - verdict = classify_interrupt(look.log, look.window, interrupts.knobs); } + screen = judge_settle(look); return verdict; } } // namespace +ScreenSettle judge_settle(const ScreenLook& look){ + ScreenSettle out; + const std::optional last = look.log.last_frame(); + if (!last || *last < look.window.start){ + return out; + } + out.seen = true; + out.showing = look.log.showing(); + WallClock since = look.window.start; + for (const ScreenEventChange& change : look.log.changes()){ + if (change.time <= look.window.end){ + since = std::max(since, change.time); + } + } + const WallClock end = std::max(look.window.end, since); + out.quiet = std::chrono::duration_cast(end - since); + return out; +} + +bool is_settled(const ScreenSettle& settle){ + return settle.seen && + settle.showing.has(ScreenEvent::PLAYER_CAN_MOVE) && + !settle.showing.any_of({ScreenEvent::DIALOG_BOX, ScreenEvent::BATTLE_STARTED}) && + fade_in(settle.showing) == WarpFade::NONE; +} + +std::string describe(const ScreenSettle& settle){ + if (!settle.seen){ + return "no frame seen"; + } + const std::string quiet = std::format("quiet {:.1f} s", settle.quiet.count() / 1000.0); + if (is_settled(settle)){ + return "settled overworld (" + quiet + ")"; + } + return describe(settle.showing) + " showing (" + quiet + ")"; +} + + InterruptCheck clear_story_interrupt(const StoryInterrupts& interrupts, RunState& state, const StoryStep& step){ InterruptCheck out; - out.verdict = settled_verdict(interrupts, step.kind); + out.verdict = settled_verdict(interrupts, step.kind, out.screen); const InterruptKind kind = out.verdict.kind; if (kind == InterruptKind::NONE){ return out; diff --git a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryInterrupts.h b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryInterrupts.h index 1a43414580..2f7583c07f 100644 --- a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryInterrupts.h +++ b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryInterrupts.h @@ -38,6 +38,7 @@ #include #include #include +#include #include #include "Pokemon_Interrupts.h" #include "Pokemon_ScreenEvents.h" @@ -113,8 +114,29 @@ struct StoryInterrupts{ }; +// How the screen looked at the end of a look: the line a run log needs to +// answer "had the scene ended before the step's first input?". +struct ScreenSettle{ + // Whether the look saw a frame at all. + bool seen = false; + // The events its last frame showed. + ScreenEvents showing = {}; + // How long the screen had shown them unchanged when the look ended. + Milliseconds quiet = Milliseconds(0); +}; +// The end of `look`: its last frame's events, and how long they held. +ScreenSettle judge_settle(const ScreenLook& look); +// Whether it ended on the overworld with no box, no fade and no battle. +bool is_settled(const ScreenSettle& settle); +// "settled overworld (quiet 0.3 s)", "black fade showing (quiet 0.1 s)", +// "no frame seen". +std::string describe(const ScreenSettle& settle); + + // What a look between steps found, and what clearing it came to. struct InterruptCheck{ + // How the screen looked when the look ended, judged or not. + ScreenSettle screen = {}; // NONE when nothing interrupted, or when the step starts on it. InterruptVerdict verdict = {}; // Failed when the look stayed unsettled, the kind had no handler, or diff --git a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryInterrupts_Tests.cpp b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryInterrupts_Tests.cpp index 187a6b14a5..aaf2693940 100644 --- a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryInterrupts_Tests.cpp +++ b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryInterrupts_Tests.cpp @@ -433,6 +433,73 @@ UnitTestResult test_table_rejects(){ return true; } +// A guard that notes how the screen looked before each step. +class ScreenGuard : public StepGuard{ +public: + explicit ScreenGuard(FakeGame& game) + : m_game(game) + {} + virtual void on_screen(const StoryStep& step, const ScreenSettle& screen) override{ + m_game.trace.push_back("before " + step.name + ": " + describe(screen)); + } + +private: + FakeGame& m_game; +}; + +// The guard hears how the screen looked before every step, interrupt or +// not: the run log's answer to "had the scene ended before the input?". +UnitTestResult test_screen_before_each_step(){ + FakeGame game; + // A scene's closing fade still down: no battle comes, so the step + // fails unsettled, and the guard hears the fade was showing. + game.screens = {look_of({{0, WALK}, {100, BLACK}}, 300)}; + StoryInterrupts interrupts = fake_interrupts(game); + interrupts.max_opening_looks = 2; + const StoryActionTable table = table_of(game, {}); + ScreenGuard guard(game); + TableExecutor executor(table, guard); + executor.set_interrupts(&interrupts); + RunState state; + StoryStep step = make(StoryStepKind::ROUTE, "by_the_counter"); + step.variant = "act"; + const Outcome faded = executor.run(state, step); + if (faded.succeeded()){ + return "Expected a step in a fade to fail unsettled, got " + to_string(faded); + } + game.screens = {quiet()}; + game.looks = 0; + const Outcome settled = executor.run(state, step); + if (!settled.succeeded()){ + return "Expected the step on a quiet screen to run, got " + to_string(settled); + } + return expect_trace(game, { + "look", "look again", "before by_the_counter: black fade showing (quiet 0.2 s)", + "look", "before by_the_counter: settled overworld (quiet 0.3 s)", "run by_the_counter", + }); +} + +UnitTestResult test_settle_of_a_look(){ + struct Row{ + const char* name; + ScreenLook look; + const char* expected; + }; + const std::vector rows = { + {"no frame", ScreenLook{}, "no frame seen"}, + {"a quiet overworld", quiet(), "settled overworld (quiet 0.3 s)"}, + {"a box", dialog(), "dialog box, player can move showing (quiet 0.2 s)"}, + {"a door's fade back up", black_unsettled(), "settled overworld (quiet 0.3 s)"}, + }; + for (const Row& row : rows){ + const std::string got = describe(judge_settle(row.look)); + if (got != row.expected){ + return std::format("{}: expected \"{}\", got \"{}\"", row.name, row.expected, got); + } + } + return true; +} + struct StoryInterruptsInput{ std::string_view name; @@ -543,6 +610,14 @@ const StoryInterruptsCase STORY_INTERRUPTS_CASES[] = { .input = {.name = "table: one handler a kind that can be cleared", .test = test_table_rejects}, .expectation = {.description = "rejects NONE, UNSETTLED and a second handler"}, }, + { + .input = {.name = "the screen before each step, for the log", .test = test_screen_before_each_step}, + .expectation = {.description = "a fade still down is told, and fails unsettled; a quiet overworld is settled"}, + }, + { + .input = {.name = "how a look ended", .test = test_settle_of_a_look}, + .expectation = {.description = "the last frame's events and how long they held"}, + }, }; } // namespace From 9b00e533402494806a042b2521b3d5c6c8dd2cdb Mon Sep 17 00:00:00 2001 From: dayfine Date: Mon, 9 Nov 2026 15:41:40 -0800 Subject: [PATCH 029/102] Story interrupts: red tests for a step that starts on the Switch HOME menu lab-B 2026-11-09 15:31: BDSP AutoStory started with the game closed; the look before the save said "settled overworld", X went to HOME and the next step walked east 22 tiles on it. Adds ScreenEvent::SWITCH_HOME_MENU and the cases: told as HOME, the step fails as game_not_running before any input, and the segment neither recovers nor reloads. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_013VUubhHeYSMGSSDXZkKZss --- .../AutoStory/Pokemon_ScreenEvents.cpp | 1 + .../Pokemon/AutoStory/Pokemon_ScreenEvents.h | 3 +- .../Pokemon_StoryInterrupts_Tests.cpp | 97 +++++++++++++++++++ 3 files changed, 100 insertions(+), 1 deletion(-) diff --git a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_ScreenEvents.cpp b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_ScreenEvents.cpp index e80ed6161f..b796c50e69 100644 --- a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_ScreenEvents.cpp +++ b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_ScreenEvents.cpp @@ -25,6 +25,7 @@ const char* screen_event_name(ScreenEvent event){ case ScreenEvent::BATTLE_ENDED: return "battle ended"; case ScreenEvent::PLAYER_CAN_MOVE: return "player can move"; case ScreenEvent::SCREEN_STILL: return "screen still"; + case ScreenEvent::SWITCH_HOME_MENU: return "Switch HOME menu"; } return "?"; } diff --git a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_ScreenEvents.h b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_ScreenEvents.h index cd633e0f60..66e5a1384c 100644 --- a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_ScreenEvents.h +++ b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_ScreenEvents.h @@ -46,9 +46,10 @@ enum class ScreenEvent : uint8_t{ BATTLE_ENDED, // A battle's closing screen. PLAYER_CAN_MOVE, // The overworld with the player in control. SCREEN_STILL, // The screen barely changed since the frame before. + SWITCH_HOME_MENU, // The Switch's HOME menu: the game is not on the screen. }; // How many ScreenEvent values there are. -constexpr size_t SCREEN_EVENT_COUNT = 10; +constexpr size_t SCREEN_EVENT_COUNT = 11; // "dialog box", for the log. const char* screen_event_name(ScreenEvent event); diff --git a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryInterrupts_Tests.cpp b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryInterrupts_Tests.cpp index aaf2693940..f8d0ae445c 100644 --- a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryInterrupts_Tests.cpp +++ b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryInterrupts_Tests.cpp @@ -19,6 +19,7 @@ #include "CommonFramework/Exceptions/OperationFailedException.h" #include "Pokemon_StoryActions.h" #include "Pokemon_StoryInterrupts.h" +#include "Pokemon_StorySegments.h" #include "Pokemon_AutoStory_Tests.h" namespace PokemonAutomation{ @@ -41,6 +42,8 @@ const ScreenEvents WHITE{ScreenEvent::FADE_WHITE}; const ScreenEvents BLACK{ScreenEvent::FADE_BLACK}; const ScreenEvents BATTLE{ScreenEvent::BATTLE_STARTED}; const ScreenEvents BANNER{ScreenEvent::LOCATION_BANNER, ScreenEvent::PLAYER_CAN_MOVE}; +// The Switch's HOME menu: the game is not running. +const ScreenEvents HOME{ScreenEvent::SWITCH_HOME_MENU}; // A look at `frames`, judged up to `until_ms`. ScreenLook look_of(const std::vector& frames, int until_ms){ @@ -83,6 +86,10 @@ ScreenLook black_unsettled(){ ScreenLook white_settled(){ return look_of({{0, WALK}, {100, WHITE}, {700, WALK}, {10000, WALK}}, 10000); } +// The HOME menu, still: the program started with the game closed. +ScreenLook home_menu(){ + return look_of({{0, HOME}, {300, HOME}}, 300); +} // The fake game: the screen its looks show, one per look and then the @@ -479,6 +486,86 @@ UnitTestResult test_screen_before_each_step(){ }); } +// The program started on the HOME menu (lab-B 2026-11-09 15:31: "before +// save: settled overworld", then X on HOME and a 22-tile walk on it). The +// screen is told as HOME and the step fails at once, before any input, +// and before a step that starts on a battle's opening too. +UnitTestResult test_home_menu_before_a_step(){ + for (StoryStepKind kind : {StoryStepKind::SAVE, StoryStepKind::ROUTE, StoryStepKind::BATTLE}){ + FakeGame game; + game.screens = {home_menu()}; + StoryInterrupts interrupts = fake_interrupts(game); + interrupts.handlers.starts_on(StoryStepKind::BATTLE, InterruptKind::TRAINER_SIGHT); + const StoryActionTable table = table_of(game, {}); + ScreenGuard guard(game); + TableExecutor executor(table, guard); + executor.set_interrupts(&interrupts); + RunState state; + StoryStep step = make(kind, "save"); + step.variant = "act"; + const Outcome outcome = executor.run(state, step); + if (to_string(outcome) != "game_not_running: the game is not running: the Switch HOME menu is showing"){ + return "Expected the step on HOME to fail as game_not_running, got " + to_string(outcome); + } + if (UnitTestResult trace = expect_trace(game, {"look", "before save: Switch HOME menu (quiet 0.3 s)"}); trace.result != UnitTestResult::PASSED){ + return trace; + } + } + return true; +} + +// A checkpoint that fails on the HOME menu is neither recovered in place +// nor reloaded: every press would go to the console's menus. +UnitTestResult test_home_menu_stops_the_segment(){ + std::vector trace; + CheckpointSpec spec; + spec.id = "00.03"; + spec.build = [&trace]{ + Checkpoint checkpoint; + checkpoint.id = "00.03"; + Event save; + save.name = "save"; + save.act = [&trace](RunState&){ + trace.push_back("save"); + return outcome_failed("game_not_running", "the game is not running: the Switch HOME menu is showing"); + }; + Recovery wait; + wait.kind = RecoveryKind::WAIT; + wait.prepare = [&trace](RunState&){ + trace.push_back("recover"); + return outcome_ok(); + }; + save.recoveries.push_back(std::move(wait)); + checkpoint.events.push_back(std::move(save)); + return checkpoint; + }; + Segment segment; + segment.id = "00"; + segment.checkpoints.push_back(std::move(spec)); + SegmentHooks hooks; + hooks.reload = [&trace](RunState&){ + trace.push_back("reload"); + return outcome_ok(); + }; + hooks.recover = [&trace](RunState&, const std::string&){ + trace.push_back("recover in place"); + return outcome_ok(); + }; + RunState state; + const SegmentReport report = run_segment(state, segment, SegmentRange{}, SegmentPolicy{.recoveries_per_event = 2}, hooks); + if (report.completed || report.failure.failure != "game_not_running" || report.reloads != 0){ + return "Expected the segment to stop on game_not_running with no reload, got " + to_string(report.failure); + } + if (trace != std::vector{"save"}){ + std::string got; + for (const std::string& line : trace){ + got += " " + line; + } + return "Expected the save tried once and nothing else, got:" + got; + } + return true; +} + UnitTestResult test_settle_of_a_look(){ struct Row{ const char* name; @@ -490,6 +577,8 @@ UnitTestResult test_settle_of_a_look(){ {"a quiet overworld", quiet(), "settled overworld (quiet 0.3 s)"}, {"a box", dialog(), "dialog box, player can move showing (quiet 0.2 s)"}, {"a door's fade back up", black_unsettled(), "settled overworld (quiet 0.3 s)"}, + {"the HOME menu", home_menu(), "Switch HOME menu (quiet 0.3 s)"}, + {"HOME read as a quiet overworld too", look_of({{0, ScreenEvents{ScreenEvent::SWITCH_HOME_MENU, ScreenEvent::PLAYER_CAN_MOVE}}}, 300), "Switch HOME menu (quiet 0.3 s)"}, }; for (const Row& row : rows){ const std::string got = describe(judge_settle(row.look)); @@ -618,6 +707,14 @@ const StoryInterruptsCase STORY_INTERRUPTS_CASES[] = { .input = {.name = "how a look ended", .test = test_settle_of_a_look}, .expectation = {.description = "the last frame's events and how long they held"}, }, + { + .input = {.name = "the HOME menu before a step", .test = test_home_menu_before_a_step}, + .expectation = {.description = "told as HOME; game_not_running before any input"}, + }, + { + .input = {.name = "the HOME menu stops the segment", .test = test_home_menu_stops_the_segment}, + .expectation = {.description = "no recovery in place, no reload"}, + }, }; } // namespace From fd603cac25e899577fbb1b535a6b28904fcf0e67 Mon Sep 17 00:00:00 2001 From: dayfine Date: Mon, 9 Nov 2026 15:43:08 -0800 Subject: [PATCH 030/102] Story interrupts: the HOME menu is not an overworld; a step on it fails at once A look that ends on the Switch's HOME menu is told as "Switch HOME menu", never settled. The step before it fails as game_not_running ("the game is not running: the Switch HOME menu is showing") before any input, whatever it starts on; no recovery runs and the segment stops without a reload. SwitchHomeObserver puts the shared HomeMenuDetector in front of a game's observer, for the games' looks between steps. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_013VUubhHeYSMGSSDXZkKZss --- .../AutoStory/Pokemon_ScreenEvents.cpp | 17 +++++++++++++++++ .../Pokemon/AutoStory/Pokemon_ScreenEvents.h | 19 +++++++++++++++++++ .../AutoStory/Pokemon_StoryActions.cpp | 3 ++- .../Pokemon/AutoStory/Pokemon_StoryEvents.cpp | 7 +++++++ .../Pokemon/AutoStory/Pokemon_StoryEvents.h | 7 +++++++ .../AutoStory/Pokemon_StoryInterrupts.cpp | 17 +++++++++++++++-- .../AutoStory/Pokemon_StoryInterrupts.h | 10 +++++++--- .../Pokemon_StoryInterrupts_Tests.cpp | 8 +++++++- .../AutoStory/Pokemon_StorySegments.cpp | 11 ++++++----- 9 files changed, 87 insertions(+), 12 deletions(-) diff --git a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_ScreenEvents.cpp b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_ScreenEvents.cpp index b796c50e69..b58a85cd9a 100644 --- a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_ScreenEvents.cpp +++ b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_ScreenEvents.cpp @@ -148,6 +148,23 @@ std::string describe(const ScreenEventLog& log, WallClock origin){ } +SwitchHomeObserver::SwitchHomeObserver(NintendoSwitch::ConsoleHandle& console, ScreenEventObserver& game) + : m_game(game) + , m_home(console, COLOR_RED) +{} + +ScreenEvents SwitchHomeObserver::observe(const VideoSnapshot& frame, WallClock now){ + if (frame && m_home.detect_only(*frame.frame)){ + return {ScreenEvent::SWITCH_HOME_MENU}; + } + return m_game.observe(frame, now); +} + +void SwitchHomeObserver::make_overlays(VideoOverlaySet& items) const{ + m_game.make_overlays(items); +} + + ScreenEventWatcher::ScreenEventWatcher(ScreenEventObserver& observer, ScreenEvents stop_on) : VisualInferenceCallback("ScreenEventWatcher") , m_observer(observer) diff --git a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_ScreenEvents.h b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_ScreenEvents.h index 66e5a1384c..800351a306 100644 --- a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_ScreenEvents.h +++ b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_ScreenEvents.h @@ -28,6 +28,8 @@ #include "CommonFramework/ImageTypes/ImageViewRGB32.h" #include "CommonFramework/VideoPipeline/VideoFeed.h" #include "CommonTools/InferenceCallbacks/VisualInferenceCallback.h" +#include "NintendoSwitch/NintendoSwitch_ConsoleHandle.h" +#include "NintendoSwitch/Inference/NintendoSwitch_HomeMenuDetector.h" namespace PokemonAutomation{ namespace Pokemon{ @@ -203,6 +205,23 @@ class ScreenEventObserver{ }; +// A game's observer behind a look at the Switch itself: a frame showing +// the HOME menu shows SWITCH_HOME_MENU and nothing else, as a game's +// detectors may read HOME's plain screen as a quiet overworld (BDSP, +// lab-B 2026-11-09). Every other frame is the game's to read. +class SwitchHomeObserver : public ScreenEventObserver{ +public: + SwitchHomeObserver(NintendoSwitch::ConsoleHandle& console, ScreenEventObserver& game); + + virtual ScreenEvents observe(const VideoSnapshot& frame, WallClock now) override; + virtual void make_overlays(VideoOverlaySet& items) const override; + +private: + ScreenEventObserver& m_game; + NintendoSwitch::HomeMenuDetector m_home; +}; + + // An observer as a run_until callback: it records every event it sees, in // order in a log, and stops the action on any of `stop_on` (none: it only // records). diff --git a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryActions.cpp b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryActions.cpp index d09f78f553..99138d9a23 100644 --- a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryActions.cpp +++ b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryActions.cpp @@ -137,7 +137,8 @@ std::optional TableExecutor::clear_interrupts(RunState& state, const St InterruptCheck check = clear_story_interrupt(*m_interrupts, state, step); m_guard.on_screen(step, check.screen); if (check.verdict.kind == InterruptKind::NONE){ - return std::nullopt; + // Nothing interrupted; failed only when the game is not running. + return check.outcome.succeeded() ? std::nullopt : std::optional(check.outcome); } if (check.outcome.succeeded() && ++cleared > m_interrupts->max_per_step){ check.outcome = outcome_failed("too_many_interrupts", step.name); diff --git a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryEvents.cpp b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryEvents.cpp index 79a095fb9f..ad22d7a6a7 100644 --- a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryEvents.cpp +++ b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryEvents.cpp @@ -83,6 +83,10 @@ std::string to_string(const Outcome& outcome){ return outcome.detail.empty() ? outcome.failure : outcome.failure + ": " + outcome.detail; } +Outcome outcome_game_not_running(){ + return outcome_failed(GAME_NOT_RUNNING, "the game is not running: the Switch HOME menu is showing"); +} + Condition condition(std::string name, Check check){ return Condition{std::move(name), std::move(check)}; } @@ -266,6 +270,9 @@ Recovery* next_recovery(EventRun& run, const std::string& failure){ // is answered in turn, so escalation goes on from there. std::optional recover(EventRun& run, Outcome failure){ while (true){ + if (failure.failure == GAME_NOT_RUNNING){ + return failure; + } Recovery* recovery = next_recovery(run, failure.failure); if (recovery == nullptr){ return failure; diff --git a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryEvents.h b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryEvents.h index 10e96b6bc4..388ce48b03 100644 --- a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryEvents.h +++ b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryEvents.h @@ -115,6 +115,13 @@ Outcome outcome_failed(std::string failure, std::string detail = ""); // "probe_exhausted: 4 rows": the failure and its detail, if any. std::string to_string(const Outcome& outcome); +// The failure of a step that found the Switch's HOME menu instead of the +// game. Nothing in the story can answer it, as every press goes to the +// console's menus: no recovery runs and no reload, the run stops. +constexpr const char* GAME_NOT_RUNNING = "game_not_running"; +// GAME_NOT_RUNNING, saying so for the run log. +Outcome outcome_game_not_running(); + // Callable action executed for a story event. using Act = MoveOnlyFunction; diff --git a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryInterrupts.cpp b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryInterrupts.cpp index 8fe58620e9..f431425718 100644 --- a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryInterrupts.cpp +++ b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryInterrupts.cpp @@ -83,7 +83,8 @@ bool may_open_a_battle(const ScreenLook& look, const InterruptVerdict& verdict){ InterruptVerdict settled_verdict(const StoryInterrupts& interrupts, StoryStepKind step, ScreenSettle& screen){ ScreenLook look = interrupts.look(true); InterruptVerdict verdict = classify_interrupt(look.log, look.window, interrupts.knobs); - if (!interrupts.handlers.step_starts_on(step, InterruptKind::UNSETTLED)){ + const bool home = look.log.showing().has(ScreenEvent::SWITCH_HOME_MENU); + if (!home && !interrupts.handlers.step_starts_on(step, InterruptKind::UNSETTLED)){ for (size_t looks = 1; verdict.kind == InterruptKind::UNSETTLED; looks++){ const size_t limit = may_open_a_battle(look, verdict) ? interrupts.max_opening_looks : interrupts.max_looks; if (looks >= limit){ @@ -119,8 +120,12 @@ ScreenSettle judge_settle(const ScreenLook& look){ return out; } +bool on_home_menu(const ScreenSettle& settle){ + return settle.seen && settle.showing.has(ScreenEvent::SWITCH_HOME_MENU); +} + bool is_settled(const ScreenSettle& settle){ - return settle.seen && + return settle.seen && !on_home_menu(settle) && settle.showing.has(ScreenEvent::PLAYER_CAN_MOVE) && !settle.showing.any_of({ScreenEvent::DIALOG_BOX, ScreenEvent::BATTLE_STARTED}) && fade_in(settle.showing) == WarpFade::NONE; @@ -131,6 +136,9 @@ std::string describe(const ScreenSettle& settle){ return "no frame seen"; } const std::string quiet = std::format("quiet {:.1f} s", settle.quiet.count() / 1000.0); + if (on_home_menu(settle)){ + return "Switch HOME menu (" + quiet + ")"; + } if (is_settled(settle)){ return "settled overworld (" + quiet + ")"; } @@ -141,6 +149,11 @@ std::string describe(const ScreenSettle& settle){ InterruptCheck clear_story_interrupt(const StoryInterrupts& interrupts, RunState& state, const StoryStep& step){ InterruptCheck out; out.verdict = settled_verdict(interrupts, step.kind, out.screen); + if (on_home_menu(out.screen)){ + out.verdict = {}; + out.outcome = outcome_game_not_running(); + return out; + } const InterruptKind kind = out.verdict.kind; if (kind == InterruptKind::NONE){ return out; diff --git a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryInterrupts.h b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryInterrupts.h index 2f7583c07f..15b024134e 100644 --- a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryInterrupts.h +++ b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryInterrupts.h @@ -126,10 +126,12 @@ struct ScreenSettle{ }; // The end of `look`: its last frame's events, and how long they held. ScreenSettle judge_settle(const ScreenLook& look); +// Whether it ended on the HOME menu: the game is not running. +bool on_home_menu(const ScreenSettle& settle); // Whether it ended on the overworld with no box, no fade and no battle. bool is_settled(const ScreenSettle& settle); // "settled overworld (quiet 0.3 s)", "black fade showing (quiet 0.1 s)", -// "no frame seen". +// "Switch HOME menu (quiet 0.3 s)", "no frame seen". std::string describe(const ScreenSettle& settle); @@ -140,13 +142,15 @@ struct InterruptCheck{ // NONE when nothing interrupted, or when the step starts on it. InterruptVerdict verdict = {}; // Failed when the look stayed unsettled, the kind had no handler, or - // the handler failed. + // the handler failed; GAME_NOT_RUNNING, with no verdict, when the + // look ended on the Switch's HOME menu. Outcome outcome = {}; }; // Looks at the screen before `step` (or after it failed) and clears what // interrupted the player, if anything, writing the handler's effect on -// the pose into `state`. +// the pose into `state`. On the HOME menu it fails as GAME_NOT_RUNNING +// and clears nothing, whatever the step starts on. InterruptCheck clear_story_interrupt(const StoryInterrupts& interrupts, RunState& state, const StoryStep& step); diff --git a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryInterrupts_Tests.cpp b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryInterrupts_Tests.cpp index f8d0ae445c..f9b4b9d079 100644 --- a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryInterrupts_Tests.cpp +++ b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryInterrupts_Tests.cpp @@ -90,6 +90,12 @@ ScreenLook white_settled(){ ScreenLook home_menu(){ return look_of({{0, HOME}, {300, HOME}}, 300); } +// The same, with a game's detectors reading it as the overworld too. +ScreenLook home_read_as_overworld(){ + ScreenEvents both = HOME; + both.set(ScreenEvent::PLAYER_CAN_MOVE, true); + return look_of({{0, both}}, 300); +} // The fake game: the screen its looks show, one per look and then the @@ -578,7 +584,7 @@ UnitTestResult test_settle_of_a_look(){ {"a box", dialog(), "dialog box, player can move showing (quiet 0.2 s)"}, {"a door's fade back up", black_unsettled(), "settled overworld (quiet 0.3 s)"}, {"the HOME menu", home_menu(), "Switch HOME menu (quiet 0.3 s)"}, - {"HOME read as a quiet overworld too", look_of({{0, ScreenEvents{ScreenEvent::SWITCH_HOME_MENU, ScreenEvent::PLAYER_CAN_MOVE}}}, 300), "Switch HOME menu (quiet 0.3 s)"}, + {"HOME read as a quiet overworld too", home_read_as_overworld(), "Switch HOME menu (quiet 0.3 s)"}, }; for (const Row& row : rows){ const std::string got = describe(judge_settle(row.look)); diff --git a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StorySegments.cpp b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StorySegments.cpp index e217d6ce0b..5653725467 100644 --- a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StorySegments.cpp +++ b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StorySegments.cpp @@ -155,12 +155,13 @@ CheckpointReport run_row( )); return result; } - if (policy.stop_at_first_failure){ - say(hooks, std::format( - "[Segment] {}: {} failed; stopping at the first failure, the game stays where it failed", - segment.id, spec.id + const bool not_running = result.failure.failure == GAME_NOT_RUNNING; + if (not_running || policy.stop_at_first_failure){ + say(hooks, std::format("[Segment] {}: {} failed; {}", segment.id, spec.id, not_running + ? "the game is not running, so no reload" + : "stopping at the first failure, the game stays where it failed" )); - report.stopped_at_first_failure = true; + report.stopped_at_first_failure = !not_running; return result; } if (attempt >= policy.attempts_per_checkpoint){ From 6b908f4c1210ce6b76183ee9aa4cfb161c092349 Mon Sep 17 00:00:00 2001 From: dayfine Date: Mon, 9 Nov 2026 20:25:55 -0800 Subject: [PATCH 031/102] AutoStory: TableExecutor without per-kind virtuals #312's StoryStepExecutor no longer has a virtual per step kind, so a step the table has no action for is unsupported_step(). A binding that still does some kinds itself overrides run_action(). Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_013VUubhHeYSMGSSDXZkKZss --- .../AutoStory/Pokemon_StoryActions.cpp | 2 +- .../Pokemon/AutoStory/Pokemon_StoryActions.h | 13 ++++++------ .../AutoStory/Pokemon_StoryActions_Tests.cpp | 20 +++++++++++-------- 3 files changed, 20 insertions(+), 15 deletions(-) diff --git a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryActions.cpp b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryActions.cpp index 99138d9a23..9dbe7f0bcb 100644 --- a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryActions.cpp +++ b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryActions.cpp @@ -124,7 +124,7 @@ Outcome TableExecutor::run_action(RunState& state, const StoryStep& step){ if (const StoryAction* action = m_table.find(step)){ return action->act(state, step); } - return StoryStepExecutor::run(state, step); + return unsupported_step(step); } // Clears what interrupted the player before `step`, counting it in diff --git a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryActions.h b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryActions.h index e672b0df15..9f7143d8dc 100644 --- a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryActions.h +++ b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryActions.h @@ -109,10 +109,10 @@ class TableExecutor : public StoryStepExecutor{ // `table` and `guard` must outlive the executor. TableExecutor(const StoryActionTable& table, StepGuard& guard); - // The table's action for the step; with none, the kind's virtual - // (StoryStepExecutor::run()), so a game can move to the table one - // kind at a time. An OperationFailedException from either is the - // failed Outcome "operation_failed", unless the guard stops on it. + // The table's action for the step (run_action()); with none, the + // step is unsupported (unsupported_step()). An OperationFailedException + // from the action is the failed Outcome "operation_failed", unless the + // guard stops on it. // With interrupts set, each step first clears what stopped the player // since the step before, and a failed step that an interrupt explains // runs again once it is cleared. @@ -125,8 +125,9 @@ class TableExecutor : public StoryStepExecutor{ } protected: - // The table's action for the step, or the kind's virtual: what run() - // runs once the screen is clear. A binding may wrap it. + // The table's action for the step, or unsupported_step() with none: + // what run() runs once the screen is clear. A binding may wrap it, or + // do the kinds its table does not have yet. virtual Outcome run_action(RunState& state, const StoryStep& step); private: diff --git a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryActions_Tests.cpp b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryActions_Tests.cpp index 851a6ecd03..7c916d45aa 100644 --- a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryActions_Tests.cpp +++ b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryActions_Tests.cpp @@ -199,14 +199,18 @@ UnitTestResult test_lint_names_steps_without_actions(){ } -// Steps without an action of their own go to this TALK. +// A binding that does TALK itself when its table has no action for it. class FakeTableExecutor : public TableExecutor{ public: using TableExecutor::TableExecutor; protected: - virtual Outcome talk(RunState&, const StoryStep&) override{ - return outcome_failed("talk virtual"); + virtual Outcome run_action(RunState& state, const StoryStep& step) override{ + const Outcome outcome = TableExecutor::run_action(state, step); + if (step.kind == StoryStepKind::TALK && outcome.failure == "unsupported_step"){ + return outcome_failed("talk binding"); + } + return outcome; } }; @@ -236,7 +240,7 @@ StoryAction throwing(){ }; } -UnitTestResult test_executor_uses_table_then_virtuals(){ +UnitTestResult test_executor_uses_table_then_binding(){ StoryActionTable table; table.add(StoryStepKind::GAME, "bill", named("bill action")); FakeGuard guard; @@ -245,8 +249,8 @@ UnitTestResult test_executor_uses_table_then_virtuals(){ const std::string bill = executor.run(state, make(StoryStepKind::GAME, "bill", "bill")).failure; const std::string talk = executor.run(state, make(StoryStepKind::TALK, "talk")).failure; const std::string mash = executor.run(state, make(StoryStepKind::MASH, "mash")).failure; - if (bill != "bill action" || talk != "talk virtual" || mash != "unsupported_step"){ - return "Expected table, virtual, unsupported; got " + bill + ", " + talk + ", " + mash; + if (bill != "bill action" || talk != "talk binding" || mash != "unsupported_step"){ + return "Expected table, binding, unsupported; got " + bill + ", " + talk + ", " + mash; } if (guard.trace != std::vector{"before bill", "before talk", "before mash"}){ return "Expected the guard before every step."; @@ -356,8 +360,8 @@ const StoryActionsCase STORY_ACTIONS_CASES[] = { .expectation = {.description = "names each step the table has no action for"}, }, { - .input = {.name = "executor: the table, then the kind's virtual", .test = test_executor_uses_table_then_virtuals}, - .expectation = {.description = "falls back to the per-kind virtuals, guarded before every step"}, + .input = {.name = "executor: the table, then the binding", .test = test_executor_uses_table_then_binding}, + .expectation = {.description = "a step without a table action is the binding's or unsupported, guarded before every step"}, }, { .input = {.name = "executor: a console failure fails the step", .test = test_guard_turns_failures_into_outcomes}, From 29844566fe5230e77efc65bdd4df064c45b394f0 Mon Sep 17 00:00:00 2001 From: dayfine Date: Mon, 9 Nov 2026 20:43:46 -0800 Subject: [PATCH 032/102] AutoStory: actions declare their args; lint checks steps against them StoryAction::args lists the args an action's steps may carry, and lint_story_checkpoint() reports a step whose args don't fit, as it reports a step without an action. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_013VUubhHeYSMGSSDXZkKZss --- .../AutoStory/Pokemon_StoryActions.cpp | 8 ++++--- .../Pokemon/AutoStory/Pokemon_StoryActions.h | 7 +++++- .../AutoStory/Pokemon_StoryActions_Tests.cpp | 22 ++++++++++++++++++- 3 files changed, 32 insertions(+), 5 deletions(-) diff --git a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryActions.cpp b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryActions.cpp index 9dbe7f0bcb..fb95a779f8 100644 --- a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryActions.cpp +++ b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryActions.cpp @@ -66,10 +66,12 @@ std::vector lint_story_checkpoint(const StoryCheckpoint& data, cons std::vector problems; for (size_t c = 0; c < data.steps.size(); c++){ const StoryStep& step = data.steps[c]; - if (table.find(step) == nullptr){ + const StoryAction* action = table.find(step); + const std::string error = action == nullptr ? "no action" : story_args_error(step.args, action->args); + if (!error.empty()){ problems.emplace_back(std::format( - "{} step {} {}: no action for {} '{}'", - data.id, c + 1, step.name, story_step_kind_name(step.kind), variant_name(step.variant) + "{} step {} {}: {} for {} '{}'", + data.id, c + 1, step.name, error, story_step_kind_name(step.kind), variant_name(step.variant) )); } } diff --git a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryActions.h b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryActions.h index 9f7143d8dc..3f778729ee 100644 --- a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryActions.h +++ b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryActions.h @@ -23,6 +23,7 @@ #include #include #include +#include #include #include #include @@ -47,6 +48,9 @@ struct StoryAction{ // The screen event the action ends on ("fade", "dialog"). Declared for // the event-driven waits to come; nothing reads it yet. std::string waits_for = {}; + // The args its steps may carry (StoryStep::args); a step with any + // other, or without a required one, fails lint_story_checkpoint(). + std::span args = {}; }; @@ -75,7 +79,8 @@ class StoryActionTable{ }; // The steps of `data` that `table` has no action for, as -// " step : no action for GAME 'bill'". +// " step : no action for GAME 'bill'", or whose args +// don't fit their action's, as "... missing argument \"budget\" for GAME 'mart'". std::vector lint_story_checkpoint(const StoryCheckpoint& data, const StoryActionTable& table); diff --git a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryActions_Tests.cpp b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryActions_Tests.cpp index 7c916d45aa..c29ac429e3 100644 --- a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryActions_Tests.cpp +++ b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryActions_Tests.cpp @@ -168,10 +168,25 @@ UnitTestResult test_duplicate_actions_throw(){ return found(table, StoryStepKind::TALK, "bill") == "first" ? UnitTestResult(true) : UnitTestResult("Expected the first action kept."); } +// The args a test Mart takes. +constexpr StoryArgSpec MART_ARGS[] = { + {.key = "map", .type = StoryArgType::TEXT, .required = true}, + {.key = "budget", .type = StoryArgType::NUMBER, .required = true}, +}; + +// `step` with `args`. +StoryStep with_args(StoryStep step, StoryArgs args){ + step.args = std::move(args); + return step; +} + UnitTestResult test_lint_names_steps_without_actions(){ StoryActionTable table; table.add(StoryStepKind::ROUTE, "", named("route")); table.add_any_kind("bill", named("bill")); + StoryAction mart = named("mart"); + mart.args = MART_ARGS; + table.add(StoryStepKind::GAME, "mart", std::move(mart)); const StoryCheckpoint data{ .id = "00.05", .title = "", @@ -181,19 +196,24 @@ UnitTestResult test_lint_names_steps_without_actions(){ make(StoryStepKind::GAME, "meet Bill", "bill"), make(StoryStepKind::GAME, "teleporter", "cell_separator x=1"), make(StoryStepKind::TALK, "talk"), + with_args(make(StoryStepKind::GAME, "buy", "mart"), {{"map", std::string("M")}, {"budget", int64_t(1500)}}), + with_args(make(StoryStepKind::GAME, "buy more", "mart"), {{"map", std::string("M")}}), + with_args(make(StoryStepKind::GAME, "meet Bill again", "bill"), {{"slot", int64_t(1)}}), }, }; const std::vector problems = lint_story_checkpoint(data, table); const std::vector expected = { "00.05 step 3 teleporter: no action for GAME 'cell_separator'", "00.05 step 4 talk: no action for TALK ''", + "00.05 step 6 buy more: missing argument \"budget\" for GAME 'mart'", + "00.05 step 7 meet Bill again: unknown argument \"slot\" for GAME 'bill'", }; if (problems != expected){ std::string got; for (const std::string& problem : problems){ got += "\n" + problem; } - return "Expected two steps without actions, got:" + got; + return "Expected two steps without actions and two with bad args, got:" + got; } return true; } From a03bfe6c7496705649b0deba380c9110028d8b55 Mon Sep 17 00:00:00 2001 From: dayfine Date: Mon, 9 Nov 2026 22:45:47 -0800 Subject: [PATCH 033/102] AutoStory: StoryActions lint lists every args error story_args_errors() now returns each error (#312 review); the action table's checkpoint lint reports one problem per error. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_013VUubhHeYSMGSSDXZkKZss --- .../Source/Pokemon/AutoStory/Pokemon_StoryActions.cpp | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryActions.cpp b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryActions.cpp index fb95a779f8..9447d11f11 100644 --- a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryActions.cpp +++ b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryActions.cpp @@ -67,8 +67,10 @@ std::vector lint_story_checkpoint(const StoryCheckpoint& data, cons for (size_t c = 0; c < data.steps.size(); c++){ const StoryStep& step = data.steps[c]; const StoryAction* action = table.find(step); - const std::string error = action == nullptr ? "no action" : story_args_error(step.args, action->args); - if (!error.empty()){ + const std::vector errors = action == nullptr + ? std::vector{"no action"} + : story_args_errors(step.args, action->args); + for (const std::string& error : errors){ problems.emplace_back(std::format( "{} step {} {}: {} for {} '{}'", data.id, c + 1, step.name, error, story_step_kind_name(step.kind), variant_name(step.variant) From d9d2e64493b3cd1d0d774dec81c2eed8e22da633 Mon Sep 17 00:00:00 2001 From: dayfine Date: Mon, 9 Nov 2026 23:55:51 -0800 Subject: [PATCH 034/102] AutoStory: the action table and its tests read StoryStep::action and typed arg specs (after #312's review) The variant word tests go with Pokemon_StoryVariant; the segment test no longer sets in-place recoveries, which SegmentPolicy dropped. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_013VUubhHeYSMGSSDXZkKZss --- .../AutoStory/Pokemon_StoryActions.cpp | 7 +- .../Pokemon/AutoStory/Pokemon_StoryActions.h | 17 +-- .../AutoStory/Pokemon_StoryActions_Tests.cpp | 107 ++---------------- .../Pokemon_StoryInterrupts_Tests.cpp | 16 +-- 4 files changed, 29 insertions(+), 118 deletions(-) diff --git a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryActions.cpp b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryActions.cpp index 9447d11f11..9dd748b015 100644 --- a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryActions.cpp +++ b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryActions.cpp @@ -7,7 +7,6 @@ #include #include #include "Common/Cpp/Exceptions.h" -#include "Pokemon_StoryVariant.h" #include "Pokemon_StoryActions.h" namespace PokemonAutomation{ @@ -58,7 +57,7 @@ const StoryAction* StoryActionTable::find(StoryStepKind kind, std::string_view n } const StoryAction* StoryActionTable::find(const StoryStep& step) const{ - return find(step.kind, variant_name(step.variant)); + return find(step.kind, step.action); } @@ -69,11 +68,11 @@ std::vector lint_story_checkpoint(const StoryCheckpoint& data, cons const StoryAction* action = table.find(step); const std::vector errors = action == nullptr ? std::vector{"no action"} - : story_args_errors(step.args, action->args); + : story_args_errors(StoryActionSpec{.kind = step.kind, .name = step.action, .args = action->args}, step.args); for (const std::string& error : errors){ problems.emplace_back(std::format( "{} step {} {}: {} for {} '{}'", - data.id, c + 1, step.name, error, story_step_kind_name(step.kind), variant_name(step.variant) + data.id, c + 1, step.name, error, story_step_kind_name(step.kind), step.action )); } } diff --git a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryActions.h b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryActions.h index 9cc6fab0bc..36009acf73 100644 --- a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryActions.h +++ b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryActions.h @@ -3,8 +3,8 @@ * From: https://github.com/PokemonAutomation/ * * A game's story steps as a table of actions instead of one virtual per - * kind. An action is keyed by the step's kind and its variant's name - * (variant_name(), Pokemon_StoryVariant.h), so one table holds a game's + * kind. An action is keyed by the step's kind and its action's name + * (StoryStep::action), so one table holds a game's * usual way of doing a kind, its other ways, and the steps only it has. * The console and a simulation bind the same rows to different actions. * @@ -31,6 +31,7 @@ #include "Pokemon_StoryEvents.h" #include "Pokemon_StoryInterrupts.h" #include "Pokemon_StoryStepExecutor.h" +#include "Types/Pokemon_StoryActionSpec.h" namespace PokemonAutomation{ namespace Pokemon{ @@ -50,26 +51,26 @@ struct StoryAction{ std::string waits_for = {}; // The args its steps may carry (StoryStep::args); a step with any // other, or without a required one, fails lint_story_checkpoint(). - std::span args = {}; + std::vector args = {}; }; -// A game's actions by step kind and variant name. +// A game's actions by step kind and action name. class StoryActionTable{ public: - // The action for steps of `kind` whose variant is named `name`. An + // The action for steps of `kind` whose action is named `name`. An // empty `name` is the kind's default. A second action for the same // key throws InternalProgramError. void add(StoryStepKind kind, std::string name, StoryAction action); - // The action for steps of any kind whose variant is named `name`, + // The action for steps of any kind whose action is named `name`, // which must not be empty. void add_any_kind(std::string name, StoryAction action); - // The action for a step of `kind` with a variant named `name`: the + // The action for a step of `kind` with an action named `name`: the // one added for both, else the one for `name` of any kind, else the // kind's default. nullptr if there is none. const StoryAction* find(StoryStepKind kind, std::string_view name) const; - // find() for the step's kind and its variant's name. + // find() for the step's kind and its action's name. const StoryAction* find(const StoryStep& step) const; private: diff --git a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryActions_Tests.cpp b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryActions_Tests.cpp index c29ac429e3..78744b35e6 100644 --- a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryActions_Tests.cpp +++ b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryActions_Tests.cpp @@ -14,7 +14,6 @@ #include "Common/Cpp/TestRunners/UnitTest.h" #include "CommonFramework/Exceptions/OperationFailedException.h" #include "Pokemon_StoryActions.h" -#include "Pokemon_StoryVariant.h" #include "Pokemon_AutoStory_Tests.h" namespace PokemonAutomation{ @@ -23,21 +22,11 @@ namespace Pokemon{ namespace{ -std::string joined(const std::vector& words){ - std::string out; - for (std::string_view word : words){ - out += "["; - out += word; - out += "]"; - } - return out; -} - -StoryStep make(StoryStepKind kind, std::string name, std::string variant = ""){ +StoryStep make(StoryStepKind kind, std::string name, std::string action = ""){ StoryStep step; step.kind = kind; step.name = std::move(name); - step.variant = std::move(variant); + step.action = std::move(action); return step; } @@ -50,10 +39,10 @@ StoryAction named(std::string name){ }; } -// The name of the action the table finds for `kind` and `variant`; "none" +// The name of the action the table finds for `kind` and `action`; "none" // without one. -std::string found(const StoryActionTable& table, StoryStepKind kind, std::string variant){ - const StoryAction* action = table.find(make(kind, "step", std::move(variant))); +std::string found(const StoryActionTable& table, StoryStepKind kind, std::string name){ + const StoryAction* action = table.find(make(kind, "step", std::move(name))); if (action == nullptr){ return "none"; } @@ -62,64 +51,6 @@ std::string found(const StoryActionTable& table, StoryStepKind kind, std::string } -UnitTestResult test_variant_words(){ - const std::string words = joined(variant_words(" mart PewterCity_Mart budget=2000 ")); - if (words != "[mart][PewterCity_Mart][budget=2000]"){ - return "Expected three words, got " + words; - } - if (!variant_words("").empty() || !variant_words(" ").empty()){ - return "Expected no words in an empty variant."; - } - return true; -} - -UnitTestResult test_variant_pairs(){ - const std::optional pair = variant_pair("budget=2000"); - if (!pair || pair->key != "budget" || pair->value != "2000"){ - return "Expected budget=2000 as a pair."; - } - const std::optional empty_value = variant_pair("door="); - if (!empty_value || empty_value->key != "door" || !empty_value->value.empty()){ - return "Expected door= as a pair with an empty value."; - } - const std::optional two = variant_pair("a=b=c"); - if (!two || two->key != "a" || two->value != "b=c"){ - return "Expected a=b=c split at the first '='."; - } - if (variant_pair("=2000") || variant_pair("mart")){ - return "Expected no pair without a key or an '='."; - } - return true; -} - -UnitTestResult test_variant_name_and_values(){ - if (variant_name(" bill shot=1") != "bill" || !variant_name("shot=1 bill").empty() || !variant_name("").empty()){ - return "Expected the name to be the first word unless it is a pair."; - } - const std::string_view variant = "mart potion=5 budget=2000 potion=9"; - if (variant_value(variant, "potion") != std::optional("5")){ - return "Expected the first potion= value."; - } - if (variant_value(variant, "mart") || variant_value(variant, "repel")){ - return "Expected no value for a plain word or a missing key."; - } - return true; -} - -UnitTestResult test_variant_numbers(){ - if (variant_number("2000") != 2000u || variant_number("0") != 0u || variant_number("999999") != 999999u){ - return "Expected decimal numbers read."; - } - if (variant_number("") || variant_number("12a") || variant_number("-1") || variant_number("1234567")){ - return "Expected no number from empty, non-digit or too long text."; - } - if (variant_number("123", 2) || variant_number("12", 2) != 12u){ - return "Expected max_digits respected."; - } - return true; -} - - UnitTestResult test_lookup_order(){ StoryActionTable table; table.add(StoryStepKind::TALK, "", named("talk default")); @@ -169,13 +100,13 @@ UnitTestResult test_duplicate_actions_throw(){ } // The args a test Mart takes. -constexpr StoryArgSpec MART_ARGS[] = { - {.key = "map", .type = StoryArgType::TEXT, .required = true}, - {.key = "budget", .type = StoryArgType::NUMBER, .required = true}, +const std::vector MART_ARGS = { + {.key = "map", .type = StoryArgType::WORD, .required = true, .fallback = std::nullopt, .why = ""}, + {.key = "budget", .type = StoryArgType::INTEGER, .required = true, .fallback = std::nullopt, .why = ""}, }; // `step` with `args`. -StoryStep with_args(StoryStep step, StoryArgs args){ +StoryStep with_args(StoryStep step, StoryActionArgs args){ step.args = std::move(args); return step; } @@ -192,9 +123,9 @@ UnitTestResult test_lint_names_steps_without_actions(){ .title = "", .start = std::nullopt, .steps = { - make(StoryStepKind::ROUTE, "to the cape", "costs=grass"), + make(StoryStepKind::ROUTE, "to the cape", "route"), make(StoryStepKind::GAME, "meet Bill", "bill"), - make(StoryStepKind::GAME, "teleporter", "cell_separator x=1"), + make(StoryStepKind::GAME, "teleporter", "cell_separator"), make(StoryStepKind::TALK, "talk"), with_args(make(StoryStepKind::GAME, "buy", "mart"), {{"map", std::string("M")}, {"budget", int64_t(1500)}}), with_args(make(StoryStepKind::GAME, "buy more", "mart"), {{"map", std::string("M")}}), @@ -351,22 +282,6 @@ class Test_StoryActions : public UnitTest{ }; const StoryActionsCase STORY_ACTIONS_CASES[] = { - { - .input = {.name = "variant: words split on spaces", .test = test_variant_words}, - .expectation = {.description = "drops empty words between, before and after spaces"}, - }, - { - .input = {.name = "variant: key=value pairs", .test = test_variant_pairs}, - .expectation = {.description = "splits at the first '=', needs a key, allows an empty value"}, - }, - { - .input = {.name = "variant: name and values", .test = test_variant_name_and_values}, - .expectation = {.description = "names the first plain word and reads the first value of a key"}, - }, - { - .input = {.name = "variant: numbers", .test = test_variant_numbers}, - .expectation = {.description = "reads decimal digits only, up to max_digits"}, - }, { .input = {.name = "table: exact, then any kind, then the kind's default", .test = test_lookup_order}, .expectation = {.description = "finds the most specific action, or none"}, diff --git a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryInterrupts_Tests.cpp b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryInterrupts_Tests.cpp index f9b4b9d079..318ae0ee13 100644 --- a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryInterrupts_Tests.cpp +++ b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryInterrupts_Tests.cpp @@ -183,7 +183,7 @@ class NotingGuard : public StepGuard{ FakeGame& m_game; }; -// `step` (variant "act") run once by a TableExecutor with the fake +// `step` (action "act") run once by a TableExecutor with the fake // game's interrupts, from a known pose. struct FakeRun{ Outcome outcome; @@ -197,7 +197,7 @@ FakeRun run_step(FakeGame& game, StoryInterrupts& interrupts, StoryStep step, Fa FakeRun out; out.state.pose.map = "Town"; out.state.pose.certainty = PoseCertainty::TILE; - step.variant = "act"; + step.action = "act"; out.outcome = executor.run(out.state, step); return out; } @@ -225,7 +225,7 @@ UnitTestResult test_no_interrupts_set(){ TableExecutor executor(table, guard); RunState state; StoryStep step = make(StoryStepKind::ROUTE, "walk"); - step.variant = "act"; + step.action = "act"; const Outcome outcome = executor.run(state, step); if (!outcome.succeeded()){ return "Expected the step to succeed, got " + to_string(outcome); @@ -475,7 +475,7 @@ UnitTestResult test_screen_before_each_step(){ executor.set_interrupts(&interrupts); RunState state; StoryStep step = make(StoryStepKind::ROUTE, "by_the_counter"); - step.variant = "act"; + step.action = "act"; const Outcome faded = executor.run(state, step); if (faded.succeeded()){ return "Expected a step in a fade to fail unsettled, got " + to_string(faded); @@ -508,7 +508,7 @@ UnitTestResult test_home_menu_before_a_step(){ executor.set_interrupts(&interrupts); RunState state; StoryStep step = make(kind, "save"); - step.variant = "act"; + step.action = "act"; const Outcome outcome = executor.run(state, step); if (to_string(outcome) != "game_not_running: the game is not running: the Switch HOME menu is showing"){ return "Expected the step on HOME to fail as game_not_running, got " + to_string(outcome); @@ -553,12 +553,8 @@ UnitTestResult test_home_menu_stops_the_segment(){ trace.push_back("reload"); return outcome_ok(); }; - hooks.recover = [&trace](RunState&, const std::string&){ - trace.push_back("recover in place"); - return outcome_ok(); - }; RunState state; - const SegmentReport report = run_segment(state, segment, SegmentRange{}, SegmentPolicy{.recoveries_per_event = 2}, hooks); + const SegmentReport report = run_segment(state, segment, SegmentRange{}, SegmentPolicy{}, hooks); if (report.completed || report.failure.failure != "game_not_running" || report.reloads != 0){ return "Expected the segment to stop on game_not_running with no reload, got " + to_string(report.failure); } From 8cc0d89ea231b174233d0ad704d62f29b8561e08 Mon Sep 17 00:00:00 2001 From: dayfine Date: Mon, 9 Nov 2026 23:56:30 -0800 Subject: [PATCH 035/102] AutoStory: lookup test names actions, not variants Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_013VUubhHeYSMGSSDXZkKZss --- .../Source/Pokemon/AutoStory/Pokemon_StoryActions_Tests.cpp | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryActions_Tests.cpp b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryActions_Tests.cpp index 78744b35e6..49f835cac7 100644 --- a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryActions_Tests.cpp +++ b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryActions_Tests.cpp @@ -58,12 +58,11 @@ UnitTestResult test_lookup_order(){ table.add_any_kind("bill", named("any bill")); table.add_any_kind("nurse", named("any nurse")); const std::pair checks[] = { - {found(table, StoryStepKind::TALK, "bill x=1"), "talk bill"}, + {found(table, StoryStepKind::TALK, "bill"), "talk bill"}, {found(table, StoryStepKind::MASH, "bill"), "any bill"}, {found(table, StoryStepKind::TALK, "nurse"), "any nurse"}, {found(table, StoryStepKind::TALK, "oak"), "talk default"}, {found(table, StoryStepKind::TALK, ""), "talk default"}, - {found(table, StoryStepKind::TALK, "x=1"), "talk default"}, {found(table, StoryStepKind::MASH, "oak"), "none"}, {found(table, StoryStepKind::MASH, ""), "none"}, }; From 7d04d131b781828a5e4bd21fa0dd56768f3c03e1 Mon Sep 17 00:00:00 2001 From: dayfine Date: Tue, 10 Nov 2026 00:05:19 -0800 Subject: [PATCH 036/102] AutoStory: split over-limit headers, drop char* for code health The newer code-health rules failed 22 times against nav/story-engine. Declarations move unchanged into headers by concern, each included by the header they came from (ScreenEvents: event types, fades, event log; Interrupts: warp judge; StoryInterrupts: interrupt handlers; Transitions: fade profiles; AutoStory_Tests: the screen-state suites). The *_name() helpers return std::string and test rows hold std::string. No behavior change. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_013VUubhHeYSMGSSDXZkKZss --- .../AutoStory/Pokemon_AutoStory_Tests.h | 11 +- .../Pokemon/AutoStory/Pokemon_FadeProfiles.h | 94 +++++++++++ .../AutoStory/Pokemon_InterruptHandlers.h | 95 +++++++++++ .../Pokemon/AutoStory/Pokemon_Interrupts.cpp | 6 +- .../Pokemon/AutoStory/Pokemon_Interrupts.h | 72 +------- .../AutoStory/Pokemon_Interrupts_Tests.cpp | 2 +- .../AutoStory/Pokemon_ScreenEventLog.h | 100 +++++++++++ .../AutoStory/Pokemon_ScreenEventTypes.h | 100 +++++++++++ .../AutoStory/Pokemon_ScreenEvents.cpp | 4 +- .../Pokemon/AutoStory/Pokemon_ScreenEvents.h | 155 +----------------- .../AutoStory/Pokemon_ScreenEvents_Tests.cpp | 4 +- .../Pokemon/AutoStory/Pokemon_ScreenFades.h | 60 +++++++ .../AutoStory/Pokemon_ScreenStory_Tests.h | 33 ++++ .../AutoStory/Pokemon_StoryInterrupts.h | 66 +------- .../Pokemon_StoryInterrupts_Tests.cpp | 4 +- .../Pokemon/AutoStory/Pokemon_Transitions.cpp | 4 +- .../Pokemon/AutoStory/Pokemon_Transitions.h | 67 +------- .../Pokemon/AutoStory/Pokemon_WarpJudge.h | 95 +++++++++++ SerialPrograms/cmake/SourceFiles.cmake | 7 + 19 files changed, 602 insertions(+), 377 deletions(-) create mode 100644 SerialPrograms/Source/Pokemon/AutoStory/Pokemon_FadeProfiles.h create mode 100644 SerialPrograms/Source/Pokemon/AutoStory/Pokemon_InterruptHandlers.h create mode 100644 SerialPrograms/Source/Pokemon/AutoStory/Pokemon_ScreenEventLog.h create mode 100644 SerialPrograms/Source/Pokemon/AutoStory/Pokemon_ScreenEventTypes.h create mode 100644 SerialPrograms/Source/Pokemon/AutoStory/Pokemon_ScreenFades.h create mode 100644 SerialPrograms/Source/Pokemon/AutoStory/Pokemon_ScreenStory_Tests.h create mode 100644 SerialPrograms/Source/Pokemon/AutoStory/Pokemon_WarpJudge.h diff --git a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_AutoStory_Tests.h b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_AutoStory_Tests.h index d30371064f..80205a98f2 100644 --- a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_AutoStory_Tests.h +++ b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_AutoStory_Tests.h @@ -10,21 +10,12 @@ #define PokemonAutomation_Pokemon_AutoStory_Tests_H #include "Common/Cpp/TestRunners/UnitTestDatabase.h" +#include "Pokemon_ScreenStory_Tests.h" namespace PokemonAutomation{ namespace Pokemon{ -// Registers unit tests for the shared screen events and the judgements over them. -void add_tests_ScreenEvents(UnitTestDatabase& database); -// The timed screen-event log, the warp judge and the interrupt classifier. -void add_tests_Interrupts(UnitTestDatabase& database); -// The transition tracker and the games' fade profiles. -void add_tests_Transitions(UnitTestDatabase& database); -// Story action tables, the variant parser and the table executor. -void add_tests_StoryActions(UnitTestDatabase& database); -// The table executor's looks for interrupts between steps. -void add_tests_StoryInterrupts(UnitTestDatabase& database); // Registers unit tests for story event sequencing and execution. void add_tests_StoryEvents(UnitTestDatabase& database); // Registers unit tests for story segment running, verification, and branching. diff --git a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_FadeProfiles.h b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_FadeProfiles.h new file mode 100644 index 0000000000..a4dd2ac915 --- /dev/null +++ b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_FadeProfiles.h @@ -0,0 +1,94 @@ +/* Fade Profiles + * + * From: https://github.com/PokemonAutomation/ + * + * Split out of Pokemon_Transitions.h, unchanged; it includes this header. + * + */ + +#ifndef PokemonAutomation_Pokemon_FadeProfiles_H +#define PokemonAutomation_Pokemon_FadeProfiles_H + +#include +#include +#include +#include +#include "Common/Cpp/Time.h" +#include "CommonFramework/ImageTools/ImageStats.h" +#include "CommonFramework/VideoPipeline/VideoFeed.h" + +namespace PokemonAutomation{ +namespace Pokemon{ + + +// Whether the screen differs after a transition from before it. The +// tracker has only frame statistics; the caller compares the frames, or +// says it did not. +enum class SceneChange{ + UNKNOWN, + SAME, + DIFFERENT, +}; + + +// A game's fades, as data. Two tiers of the same test: a frame is uniform +// (the fade's hold) when its middle's stddev sum is at most +// `uniform_max_stddev_sum`, and partial (on the way down or up) when it is +// at most `partial_max_stddev_sum`. Either way it is dark or white by its +// rgb sum. +struct FadeProfile{ + double uniform_max_stddev_sum = 10; + double partial_max_stddev_sum = 60; + // Dark at or below this rgb sum; a partial frame up to `partial_dark_max_sum`. + double dark_max_sum = 225; + double partial_dark_max_sum = 300; + // White at or above this rgb sum; a partial frame from `partial_white_min_sum`. + double white_min_sum = 500; + double partial_white_min_sum = 450; + + // Partial frames for longer than this, with no hold, are the scene's + // own look (a dim cave floor, a street at night), not a fade. + Milliseconds max_fall = Milliseconds(1000); + // A transition still dark or white after this has timed out: the + // screen did not come back. + Milliseconds max_hold = Milliseconds(8000); + + // Whether the game fades to white between maps (BDSP's cave exits). + // Without, every white is an encounter's flash. + bool has_white_fade = true; + // A white held this long or less, back on the same scene, is a flash. + Milliseconds flash_max_hold = Milliseconds(150); + // A white held this long or more, not back on the same scene, is a + // white fade. Between the two the white is unsure. + Milliseconds white_fade_min_hold = Milliseconds(400); +}; + +// BDSP. The uniform tier is the shared walk's (FADE_MAX_STDDEV_SUM, the +// Oreburgh Gate's textured floor is no fade, lab-B 2026-11-08); the partial +// tier is run_into_door()'s 60, which caught the doorway's dim fade frames. +// A cave mouth's fade is dim (45 to 64 a channel), hence the dark sum of 225. +// The flash and white-fade holds are provisional: no console frames of an +// encounter flash and a cave exit have been timed side by side yet, so the +// band between them is wide and reports WHITE_UNSURE. +extern const FadeProfile BDSP_FADE_PROFILE; +// FRLG. The GBA fades to true black, so the dark tiers are the shared +// BlackScreenDetector's 100 and a little above; it has no white fade between +// maps, so every white is an encounter's flash. +extern const FadeProfile FRLG_FADE_PROFILE; + + +// What a transition was. +enum class TransitionKind : uint8_t{ + FADE_BLACK, // A door, a cave mouth, a scene cut, a battle's own fade. + FADE_WHITE, // A cave exit: a long white onto another scene. + FLASH, // An encounter's flash: a short white, back on the scene. + WHITE_UNSURE, // A white that may be either: wait for a battle. +}; +// "black fade", for the log. +std::string transition_kind_name(TransitionKind kind); + + + +} // namespace Pokemon +} // namespace PokemonAutomation +#endif diff --git a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_InterruptHandlers.h b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_InterruptHandlers.h new file mode 100644 index 0000000000..c63b14124c --- /dev/null +++ b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_InterruptHandlers.h @@ -0,0 +1,95 @@ +/* Interrupt Handlers + * + * From: https://github.com/PokemonAutomation/ + * + * Split out of Pokemon_StoryInterrupts.h, unchanged; it includes this header. + * + */ + +#ifndef PokemonAutomation_Pokemon_InterruptHandlers_H +#define PokemonAutomation_Pokemon_InterruptHandlers_H + +#include +#include +#include +#include +#include +#include +#include "Pokemon_Interrupts.h" +#include "Pokemon_ScreenEvents.h" +#include "Pokemon_StoryEvents.h" +#include "Pokemon_StoryStepExecutor.h" + +namespace PokemonAutomation{ +namespace Pokemon{ + + +// What a game saw of the screen between two steps: its timed events, and +// the span of them the classifier judges. +struct ScreenLook{ + ScreenEventLog log{}; + InterruptWindow window = {}; +}; + +// Looks at the screen. `fresh` starts a new look; otherwise the look goes +// on from the last one, to see how an unsettled screen ends. +using ScreenLookFunction = std::function; + +// Clears an interrupt a look found: flees or fights the battle, closes +// the dialog, waits out the warp. +using InterruptAction = std::function; + +// A row of an InterruptHandlerTable. +struct InterruptHandler{ + InterruptAction handle = {}; + // What clearing it did to where the player is. + InterruptPose pose = InterruptPose::UNCHANGED; +}; + + +// A game's handlers by kind of interrupt, and the steps that start on one. +class InterruptHandlerTable{ +public: + // The handler for `kind`: one of WILD_ENCOUNTER, TRAINER_SIGHT, + // DIALOG or WARP. Another kind, or a second handler for one, throws + // InternalProgramError. + void add(InterruptKind kind, InterruptHandler handler); + // The handler for `kind`; nullptr if there is none. + const InterruptHandler* find(InterruptKind kind) const; + + // Steps of `step` start on `kind` showing: before one, it is the + // step's to clear, not an interrupt. A step that starts on + // WILD_ENCOUNTER or TRAINER_SIGHT starts on UNSETTLED too. + void starts_on(StoryStepKind step, InterruptKind kind); + bool step_starts_on(StoryStepKind step, InterruptKind kind) const; + +private: + std::map m_handlers; + std::set> m_starts_on; +}; + + +// A game's interrupts between steps: how it looks, how it judges what it +// saw, and what it does about each kind. +struct StoryInterrupts{ + ScreenLookFunction look = {}; + InterruptKnobs knobs = {}; + InterruptHandlerTable handlers = {}; + // Looks at a screen that stays UNSETTLED (a fade with no battle yet) + // before it fails the step as "interrupt_unsettled". A step that + // starts on it gets it on the first look. + size_t max_looks = 3; + // The same, for a screen that may be a battle's opening: enough looks + // for its battle to show. BDSP's 300 ms looks cover 12 s, past its + // battle_after_fade (8 s), after which a fade with no battle settles. + size_t max_opening_looks = 40; + // Interrupts cleared for one step before it fails as + // "too_many_interrupts". + size_t max_per_step = 3; +}; + + + +} // namespace Pokemon +} // namespace PokemonAutomation +#endif diff --git a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_Interrupts.cpp b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_Interrupts.cpp index e93ce9f5c9..ebee346629 100644 --- a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_Interrupts.cpp +++ b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_Interrupts.cpp @@ -12,7 +12,7 @@ namespace PokemonAutomation{ namespace Pokemon{ -const char* warp_judgement_name(WarpJudgement judgement){ +std::string warp_judgement_name(WarpJudgement judgement){ switch (judgement){ case WarpJudgement::NO_FADE: return "no fade"; case WarpJudgement::FADE_SHOWING: return "fade still showing"; @@ -25,7 +25,7 @@ const char* warp_judgement_name(WarpJudgement judgement){ return "?"; } -const char* interrupt_kind_name(InterruptKind kind){ +std::string interrupt_kind_name(InterruptKind kind){ switch (kind){ case InterruptKind::NONE: return "none"; case InterruptKind::WILD_ENCOUNTER: return "wild encounter"; @@ -222,7 +222,7 @@ WarpVerdict judge_warp(const Transition& transition, const InterruptKnobs& knobs std::string describe(const InterruptVerdict& verdict, WallClock origin){ std::string out = interrupt_kind_name(verdict.kind); - const char* separator = ": "; + std::string_view separator = ": "; for (const ScreenEventChange& change : verdict.evidence){ out += std::format( "{}{:+} ms {} {}", diff --git a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_Interrupts.h b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_Interrupts.h index 52d23c811c..b7637ad044 100644 --- a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_Interrupts.h +++ b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_Interrupts.h @@ -24,80 +24,12 @@ #include "Common/Cpp/Time.h" #include "Pokemon_ScreenEvents.h" #include "Pokemon_Transitions.h" +#include "Pokemon_WarpJudge.h" namespace PokemonAutomation{ namespace Pokemon{ -// A game's timing, as data. -struct InterruptKnobs{ - // A fade must hold this long to be a warp's. One uniform frame is enough - // by default: a 50 ms fade can show on one frame only. - Milliseconds min_fade_hold = Milliseconds(0); - // A battle that shows this soon after a fade ends is that fade's - // encounter, and a fade is no warp before this has passed with no - // battle. BDSP's encounter flash shows its battle within 8 s - // (WHITE_FLASH_BATTLE_WAIT in its walk). - Milliseconds battle_after_fade = Milliseconds(8000); - // A dialog box that rose this long or less before a battle's fade is a - // trainer's lines. A trainer's lines can pause more than 4 s before the - // battle (BDSP r210d), and a trainer may say several boxes. - Milliseconds sight_lines_lead = Milliseconds(20000); -}; - -// The span of the log to judge: changes at `start` or later, and no later -// than `end`. -struct InterruptWindow{ - WallClock start = {}; - WallClock end = {}; -}; - - -// How a fade looked, for the warp judge. -struct FadeSpan{ - WarpFade fade = WarpFade::NONE; - WallClock down = {}; - // When the screen came back; none while it still shows the fade. - std::optional up = {}; -}; - -// What the warp judge made of a fade. -enum class WarpJudgement{ - NO_FADE, // No fade went down in the window. - FADE_SHOWING, // It went down and has not come back up. - TOO_SHORT, // It came back up before min_fade_hold. - SAME_SCENE, // It came back up on the scene it left. - WARPED, // Down, held, back up; not on the same scene. - FLASH, // An encounter's flash (a tracked transition only). - WHITE_UNSURE, // A white that may be a flash or a cave exit (a - // tracked transition only): wait for a battle. -}; -// "fade too short", for the log. -const char* warp_judgement_name(WarpJudgement judgement); - -// The warp judge's verdict and the fade it judged. -struct WarpVerdict{ - WarpJudgement judgement = WarpJudgement::NO_FADE; - // The last fade that went down in the window, if any. - std::optional fade = {}; -}; - -// A warp is a fade going down, holding uniform, and coming back up on -// another scene. The last fade that went down in `window` is judged; a -// LOCATION_BANNER does not count here (WarpSeen does). `change` is what -// the caller saw of the scene before and after: UNKNOWN does not rule the -// warp out. This judges the fade only: a battle after it is -// classify_interrupt()'s question. -WarpVerdict judge_warp( - const ScreenEventLog& log, InterruptWindow window, - const InterruptKnobs& knobs, SceneChange change -); -// The same judge over a TransitionTracker's transition, which has its own -// scene comparison. A transition whose hold went unseen onto another scene -// is a warp whatever min_fade_hold says: the scene change is the evidence. -WarpVerdict judge_warp(const Transition& transition, const InterruptKnobs& knobs); - - // What stopped the player. enum class InterruptKind{ NONE, @@ -108,7 +40,7 @@ enum class InterruptKind{ UNSETTLED, // A fade, too recent to know if a battle follows. }; // "trainer sight", for the log. -const char* interrupt_kind_name(InterruptKind kind); +std::string interrupt_kind_name(InterruptKind kind); // What stopped the player, and the evidence for it. struct InterruptVerdict{ diff --git a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_Interrupts_Tests.cpp b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_Interrupts_Tests.cpp index aecc5cbbd8..37f03590a0 100644 --- a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_Interrupts_Tests.cpp +++ b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_Interrupts_Tests.cpp @@ -124,7 +124,7 @@ UnitTestResult test_empty_log(){ UnitTestResult test_judge_warp(){ struct Row{ - const char* name; + std::string name; std::vector frames; SceneChange change; WarpJudgement expected; diff --git a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_ScreenEventLog.h b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_ScreenEventLog.h new file mode 100644 index 0000000000..62f34e2f6b --- /dev/null +++ b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_ScreenEventLog.h @@ -0,0 +1,100 @@ +/* Screen Event Log + * + * From: https://github.com/PokemonAutomation/ + * + * Split out of Pokemon_ScreenEvents.h, unchanged; it includes this header. + * + */ + +#ifndef PokemonAutomation_Pokemon_ScreenEventLog_H +#define PokemonAutomation_Pokemon_ScreenEventLog_H + +#include +#include +#include +#include +#include +#include +#include "Common/Cpp/Concurrency/Mutex.h" +#include "Common/Cpp/Time.h" +#include "CommonFramework/ImageTools/ImageStats.h" +#include "CommonFramework/ImageTypes/ImageViewRGB32.h" +#include "CommonFramework/VideoPipeline/VideoFeed.h" +#include "CommonTools/InferenceCallbacks/VisualInferenceCallback.h" +#include "NintendoSwitch/NintendoSwitch_ConsoleHandle.h" +#include "NintendoSwitch/Inference/NintendoSwitch_HomeMenuDetector.h" +#include "Pokemon_ScreenFades.h" + +namespace PokemonAutomation{ +namespace Pokemon{ + + +// Whether an event started or stopped showing. +enum class ScreenEventEdge : uint8_t{ + ROSE, + FELL, +}; + +// One event starting or stopping to show, at the frame that showed it. +struct ScreenEventChange{ + WallClock time; + ScreenEvent event; + ScreenEventEdge edge; + + bool operator==(const ScreenEventChange& other) const = default; +}; + +// How many changes a log keeps. A walk's events change a few times a +// second at most (a fade's black, a box, the screen going still), so this +// is a minute or more of a busy scene. +constexpr size_t SCREEN_EVENT_LOG_CAPACITY = 256; + +// The events of a stream of frames, in order and timed: what rose and fell +// when, not only what was seen (ScreenEventWatcher::seen()). The judges that +// care about order read it (Pokemon_Interrupts.h): a flash then a battle is +// an encounter, a box then a battle a trainer's sight. +// +// It keeps the newest `capacity` changes and counts the ones it dropped. +// Not thread-safe; ScreenEventWatcher guards its own. +class ScreenEventLog{ +public: + explicit ScreenEventLog(size_t capacity = SCREEN_EVENT_LOG_CAPACITY); + + // Adds a frame: a change for each event that rose or fell since the + // frame before (the first frame's events all rise). `now` must not go + // back in time. + void record(const ScreenEvents& frame, WallClock now); + + // The changes kept, oldest first. + const std::deque& changes() const{ + return m_changes; + } + // How many changes were dropped, oldest first, to keep the capacity. + size_t dropped() const{ + return m_dropped; + } + // The events of the last frame recorded. + ScreenEvents showing() const{ + return m_showing; + } + // When the last frame was recorded; none before the first. + std::optional last_frame() const{ + return m_last_frame; + } + void clear(); + +private: + size_t m_capacity; + std::deque m_changes; + size_t m_dropped = 0; + ScreenEvents m_showing; + std::optional m_last_frame; +}; +// "+1200 ms dialog box rose", times from `origin`, one change per line. +std::string describe(const ScreenEventLog& log, WallClock origin); + + + +} // namespace Pokemon +} // namespace PokemonAutomation +#endif diff --git a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_ScreenEventTypes.h b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_ScreenEventTypes.h new file mode 100644 index 0000000000..45988abc4e --- /dev/null +++ b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_ScreenEventTypes.h @@ -0,0 +1,100 @@ +/* Screen Event Types + * + * From: https://github.com/PokemonAutomation/ + * + * Split out of Pokemon_ScreenEvents.h, unchanged; it includes this header. + * + */ + +#ifndef PokemonAutomation_Pokemon_ScreenEventTypes_H +#define PokemonAutomation_Pokemon_ScreenEventTypes_H + +#include +#include +#include +#include +#include +#include +#include "Common/Cpp/Concurrency/Mutex.h" +#include "Common/Cpp/Time.h" +#include "CommonFramework/ImageTools/ImageStats.h" +#include "CommonFramework/ImageTypes/ImageViewRGB32.h" +#include "CommonFramework/VideoPipeline/VideoFeed.h" +#include "CommonTools/InferenceCallbacks/VisualInferenceCallback.h" +#include "NintendoSwitch/NintendoSwitch_ConsoleHandle.h" +#include "NintendoSwitch/Inference/NintendoSwitch_HomeMenuDetector.h" + +namespace PokemonAutomation{ +namespace Pokemon{ + + +// One thing a frame shows. A game reports the ones its detectors can see. +enum class ScreenEvent : uint8_t{ + FADE_BLACK, // A uniform dark screen: a door, a cave mouth, a scene cut. + FADE_WHITE, // A uniform white screen: a cave exit. + LOCATION_BANNER, // A location banner. An observer given an expected + // map reports only that map's. + DIALOG_BOX, // A dialogue box. + CHOICE_BOX, // A choice (Yes/No, a menu of answers). + INTERACT_PROMPT, // A button prompt to interact ("A Talk"). + BATTLE_STARTED, // A battle shows (its menu, its HUD or its opening). + BATTLE_ENDED, // A battle's closing screen. + PLAYER_CAN_MOVE, // The overworld with the player in control. + SCREEN_STILL, // The screen barely changed since the frame before. + SWITCH_HOME_MENU, // The Switch's HOME menu: the game is not on the screen. +}; +// How many ScreenEvent values there are. +constexpr size_t SCREEN_EVENT_COUNT = 11; +// "dialog box", for the log. +std::string screen_event_name(ScreenEvent event); + + +// How a screen's fade looks: the kind of FADE_BLACK / FADE_WHITE. +enum class WarpFade{ + NONE, + BLACK, // a door's black, or a cave mouth's dim fade + WHITE, // a cave exit's white, with no battle after it +}; +// "black fade", for the log. +std::string warp_fade_name(WarpFade fade); + + +// The events of one frame, or of all the frames a watcher saw. +class ScreenEvents{ +public: + ScreenEvents() = default; + ScreenEvents(std::initializer_list events); + + bool has(ScreenEvent event) const{ + return (m_bits & bit(event)) != 0; + } + // Whether any of `events` is in this set. + bool any_of(const ScreenEvents& events) const{ + return (m_bits & events.m_bits) != 0; + } + // Adds `event`, or removes it when `on` is false (as std::bitset::set). + void set(ScreenEvent event, bool on); + void merge(const ScreenEvents& events){ + m_bits |= events.m_bits; + } + + uint32_t bits() const{ + return m_bits; + } + static ScreenEvents from_bits(uint32_t bits); + + bool operator==(const ScreenEvents& other) const = default; + +private: + static uint32_t bit(ScreenEvent event){ + return uint32_t(1) << (uint32_t)event; + } + + uint32_t m_bits = 0; +}; + + + +} // namespace Pokemon +} // namespace PokemonAutomation +#endif diff --git a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_ScreenEvents.cpp b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_ScreenEvents.cpp index b58a85cd9a..db2e5fbfa7 100644 --- a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_ScreenEvents.cpp +++ b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_ScreenEvents.cpp @@ -13,7 +13,7 @@ namespace PokemonAutomation{ namespace Pokemon{ -const char* screen_event_name(ScreenEvent event){ +std::string screen_event_name(ScreenEvent event){ switch (event){ case ScreenEvent::FADE_BLACK: return "black fade"; case ScreenEvent::FADE_WHITE: return "white fade"; @@ -30,7 +30,7 @@ const char* screen_event_name(ScreenEvent event){ return "?"; } -const char* warp_fade_name(WarpFade fade){ +std::string warp_fade_name(WarpFade fade){ switch (fade){ case WarpFade::NONE: return "no fade"; case WarpFade::BLACK: return "black fade"; diff --git a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_ScreenEvents.h b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_ScreenEvents.h index 800351a306..ee3080235d 100644 --- a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_ScreenEvents.h +++ b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_ScreenEvents.h @@ -30,165 +30,12 @@ #include "CommonTools/InferenceCallbacks/VisualInferenceCallback.h" #include "NintendoSwitch/NintendoSwitch_ConsoleHandle.h" #include "NintendoSwitch/Inference/NintendoSwitch_HomeMenuDetector.h" +#include "Pokemon_ScreenEventLog.h" namespace PokemonAutomation{ namespace Pokemon{ -// One thing a frame shows. A game reports the ones its detectors can see. -enum class ScreenEvent : uint8_t{ - FADE_BLACK, // A uniform dark screen: a door, a cave mouth, a scene cut. - FADE_WHITE, // A uniform white screen: a cave exit. - LOCATION_BANNER, // A location banner. An observer given an expected - // map reports only that map's. - DIALOG_BOX, // A dialogue box. - CHOICE_BOX, // A choice (Yes/No, a menu of answers). - INTERACT_PROMPT, // A button prompt to interact ("A Talk"). - BATTLE_STARTED, // A battle shows (its menu, its HUD or its opening). - BATTLE_ENDED, // A battle's closing screen. - PLAYER_CAN_MOVE, // The overworld with the player in control. - SCREEN_STILL, // The screen barely changed since the frame before. - SWITCH_HOME_MENU, // The Switch's HOME menu: the game is not on the screen. -}; -// How many ScreenEvent values there are. -constexpr size_t SCREEN_EVENT_COUNT = 11; -// "dialog box", for the log. -const char* screen_event_name(ScreenEvent event); - - -// How a screen's fade looks: the kind of FADE_BLACK / FADE_WHITE. -enum class WarpFade{ - NONE, - BLACK, // a door's black, or a cave mouth's dim fade - WHITE, // a cave exit's white, with no battle after it -}; -// "black fade", for the log. -const char* warp_fade_name(WarpFade fade); - - -// The events of one frame, or of all the frames a watcher saw. -class ScreenEvents{ -public: - ScreenEvents() = default; - ScreenEvents(std::initializer_list events); - - bool has(ScreenEvent event) const{ - return (m_bits & bit(event)) != 0; - } - // Whether any of `events` is in this set. - bool any_of(const ScreenEvents& events) const{ - return (m_bits & events.m_bits) != 0; - } - // Adds `event`, or removes it when `on` is false (as std::bitset::set). - void set(ScreenEvent event, bool on); - void merge(const ScreenEvents& events){ - m_bits |= events.m_bits; - } - - uint32_t bits() const{ - return m_bits; - } - static ScreenEvents from_bits(uint32_t bits); - - bool operator==(const ScreenEvents& other) const = default; - -private: - static uint32_t bit(ScreenEvent event){ - return uint32_t(1) << (uint32_t)event; - } - - uint32_t m_bits = 0; -}; -// The event of a fade: FADE_BLACK, FADE_WHITE, or none for WarpFade::NONE. -ScreenEvents fade_events(WarpFade fade); -// The fade `events` show: BLACK before WHITE if they have both. -WarpFade fade_in(const ScreenEvents& events); -// "dialog box, player can move"; "nothing" when empty. -std::string describe(const ScreenEvents& events); - - -// A fade is uniform over the middle 80% of the screen, the shared -// Black/WhiteScreenWatcher's stddev test (upstream #1717): a dim cave floor -// is textured, so it is no fade (BDSP's Oreburgh Gate, mean 46, lab-B -// 2026-11-08). Check against the Gate's frames on the console before -// tightening. -constexpr double FADE_MAX_STDDEV_SUM = 10; -// Dark goes to an rgb sum of 225, as a cave mouth's fade is dim, 45 to 64 -// a channel, not black. -constexpr double FADE_MAX_DARK_SUM = 225; -// White from an rgb sum of 500, as the shared WhiteScreenWatcher's. -constexpr double FADE_MIN_WHITE_SUM = 500; -// The fade `middle` (the stats of the screen's middle 80%) shows, if any. -WarpFade fade_of(const ImageStats& middle); -// fade_of() for a screen. -WarpFade fade_of_screen(const ImageViewRGB32& screen); - - -// Whether an event started or stopped showing. -enum class ScreenEventEdge : uint8_t{ - ROSE, - FELL, -}; - -// One event starting or stopping to show, at the frame that showed it. -struct ScreenEventChange{ - WallClock time; - ScreenEvent event; - ScreenEventEdge edge; - - bool operator==(const ScreenEventChange& other) const = default; -}; - -// How many changes a log keeps. A walk's events change a few times a -// second at most (a fade's black, a box, the screen going still), so this -// is a minute or more of a busy scene. -constexpr size_t SCREEN_EVENT_LOG_CAPACITY = 256; - -// The events of a stream of frames, in order and timed: what rose and fell -// when, not only what was seen (ScreenEventWatcher::seen()). The judges that -// care about order read it (Pokemon_Interrupts.h): a flash then a battle is -// an encounter, a box then a battle a trainer's sight. -// -// It keeps the newest `capacity` changes and counts the ones it dropped. -// Not thread-safe; ScreenEventWatcher guards its own. -class ScreenEventLog{ -public: - explicit ScreenEventLog(size_t capacity = SCREEN_EVENT_LOG_CAPACITY); - - // Adds a frame: a change for each event that rose or fell since the - // frame before (the first frame's events all rise). `now` must not go - // back in time. - void record(const ScreenEvents& frame, WallClock now); - - // The changes kept, oldest first. - const std::deque& changes() const{ - return m_changes; - } - // How many changes were dropped, oldest first, to keep the capacity. - size_t dropped() const{ - return m_dropped; - } - // The events of the last frame recorded. - ScreenEvents showing() const{ - return m_showing; - } - // When the last frame was recorded; none before the first. - std::optional last_frame() const{ - return m_last_frame; - } - void clear(); - -private: - size_t m_capacity; - std::deque m_changes; - size_t m_dropped = 0; - ScreenEvents m_showing; - std::optional m_last_frame; -}; -// "+1200 ms dialog box rose", times from `origin`, one change per line. -std::string describe(const ScreenEventLog& log, WallClock origin); - - // A game's detectors, as events. Observers may keep state between frames // (the frame before, for SCREEN_STILL; when a banner was last read, to // gate OCR), so one observer watches one stream at a time. diff --git a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_ScreenEvents_Tests.cpp b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_ScreenEvents_Tests.cpp index 6620fd0204..ef57a2e747 100644 --- a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_ScreenEvents_Tests.cpp +++ b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_ScreenEvents_Tests.cpp @@ -66,7 +66,7 @@ ImageRGB32 screen_of(uint32_t a, uint32_t b){ UnitTestResult test_fade_of_screen(){ struct Row{ - const char* name; + std::string name; uint32_t a; uint32_t b; WarpFade fade; @@ -129,7 +129,7 @@ std::vector concat(std::vector a, const std::vector< UnitTestResult test_talk_over(){ struct Row{ - const char* name; + std::string name; TalkOverRule rule; std::vector beats; SceneMove want; diff --git a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_ScreenFades.h b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_ScreenFades.h new file mode 100644 index 0000000000..57de9f6a3d --- /dev/null +++ b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_ScreenFades.h @@ -0,0 +1,60 @@ +/* Screen Fades + * + * From: https://github.com/PokemonAutomation/ + * + * Split out of Pokemon_ScreenEvents.h, unchanged; it includes this header. + * + */ + +#ifndef PokemonAutomation_Pokemon_ScreenFades_H +#define PokemonAutomation_Pokemon_ScreenFades_H + +#include +#include +#include +#include +#include +#include +#include "Common/Cpp/Concurrency/Mutex.h" +#include "Common/Cpp/Time.h" +#include "CommonFramework/ImageTools/ImageStats.h" +#include "CommonFramework/ImageTypes/ImageViewRGB32.h" +#include "CommonFramework/VideoPipeline/VideoFeed.h" +#include "CommonTools/InferenceCallbacks/VisualInferenceCallback.h" +#include "NintendoSwitch/NintendoSwitch_ConsoleHandle.h" +#include "NintendoSwitch/Inference/NintendoSwitch_HomeMenuDetector.h" +#include "Pokemon_ScreenEventTypes.h" + +namespace PokemonAutomation{ +namespace Pokemon{ + + +// The event of a fade: FADE_BLACK, FADE_WHITE, or none for WarpFade::NONE. +ScreenEvents fade_events(WarpFade fade); +// The fade `events` show: BLACK before WHITE if they have both. +WarpFade fade_in(const ScreenEvents& events); +// "dialog box, player can move"; "nothing" when empty. +std::string describe(const ScreenEvents& events); + + +// A fade is uniform over the middle 80% of the screen, the shared +// Black/WhiteScreenWatcher's stddev test (upstream #1717): a dim cave floor +// is textured, so it is no fade (BDSP's Oreburgh Gate, mean 46, lab-B +// 2026-11-08). Check against the Gate's frames on the console before +// tightening. +constexpr double FADE_MAX_STDDEV_SUM = 10; +// Dark goes to an rgb sum of 225, as a cave mouth's fade is dim, 45 to 64 +// a channel, not black. +constexpr double FADE_MAX_DARK_SUM = 225; +// White from an rgb sum of 500, as the shared WhiteScreenWatcher's. +constexpr double FADE_MIN_WHITE_SUM = 500; +// The fade `middle` (the stats of the screen's middle 80%) shows, if any. +WarpFade fade_of(const ImageStats& middle); +// fade_of() for a screen. +WarpFade fade_of_screen(const ImageViewRGB32& screen); + + + +} // namespace Pokemon +} // namespace PokemonAutomation +#endif diff --git a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_ScreenStory_Tests.h b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_ScreenStory_Tests.h new file mode 100644 index 0000000000..7760c923eb --- /dev/null +++ b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_ScreenStory_Tests.h @@ -0,0 +1,33 @@ +/* Screen Story Tests + * + * From: https://github.com/PokemonAutomation/ + * + * Split out of Pokemon_AutoStory_Tests.h, unchanged; it includes this header. + * + */ + +#ifndef PokemonAutomation_Pokemon_ScreenStory_Tests_H +#define PokemonAutomation_Pokemon_ScreenStory_Tests_H + +#include "Common/Cpp/TestRunners/UnitTestDatabase.h" + +namespace PokemonAutomation{ +namespace Pokemon{ + + +// Registers unit tests for the shared screen events and the judgements over them. +void add_tests_ScreenEvents(UnitTestDatabase& database); +// The timed screen-event log, the warp judge and the interrupt classifier. +void add_tests_Interrupts(UnitTestDatabase& database); +// The transition tracker and the games' fade profiles. +void add_tests_Transitions(UnitTestDatabase& database); +// Story action tables, the variant parser and the table executor. +void add_tests_StoryActions(UnitTestDatabase& database); +// The table executor's looks for interrupts between steps. +void add_tests_StoryInterrupts(UnitTestDatabase& database); + + + +} // namespace Pokemon +} // namespace PokemonAutomation +#endif diff --git a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryInterrupts.h b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryInterrupts.h index 2696e79b90..b9f5abe2a9 100644 --- a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryInterrupts.h +++ b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryInterrupts.h @@ -44,76 +44,12 @@ #include "Pokemon_ScreenEvents.h" #include "Pokemon_StoryEvents.h" #include "Pokemon_StoryStepExecutor.h" +#include "Pokemon_InterruptHandlers.h" namespace PokemonAutomation{ namespace Pokemon{ -// What a game saw of the screen between two steps: its timed events, and -// the span of them the classifier judges. -struct ScreenLook{ - ScreenEventLog log{}; - InterruptWindow window = {}; -}; - -// Looks at the screen. `fresh` starts a new look; otherwise the look goes -// on from the last one, to see how an unsettled screen ends. -using ScreenLookFunction = std::function; - -// Clears an interrupt a look found: flees or fights the battle, closes -// the dialog, waits out the warp. -using InterruptAction = std::function; - -// A row of an InterruptHandlerTable. -struct InterruptHandler{ - InterruptAction handle = {}; - // What clearing it did to where the player is. - InterruptPose pose = InterruptPose::UNCHANGED; -}; - - -// A game's handlers by kind of interrupt, and the steps that start on one. -class InterruptHandlerTable{ -public: - // The handler for `kind`: one of WILD_ENCOUNTER, TRAINER_SIGHT, - // DIALOG or WARP. Another kind, or a second handler for one, throws - // InternalProgramError. - void add(InterruptKind kind, InterruptHandler handler); - // The handler for `kind`; nullptr if there is none. - const InterruptHandler* find(InterruptKind kind) const; - - // Steps of `step` start on `kind` showing: before one, it is the - // step's to clear, not an interrupt. A step that starts on - // WILD_ENCOUNTER or TRAINER_SIGHT starts on UNSETTLED too. - void starts_on(StoryStepKind step, InterruptKind kind); - bool step_starts_on(StoryStepKind step, InterruptKind kind) const; - -private: - std::map m_handlers; - std::set> m_starts_on; -}; - - -// A game's interrupts between steps: how it looks, how it judges what it -// saw, and what it does about each kind. -struct StoryInterrupts{ - ScreenLookFunction look = {}; - InterruptKnobs knobs = {}; - InterruptHandlerTable handlers = {}; - // Looks at a screen that stays UNSETTLED (a fade with no battle yet) - // before it fails the step as "interrupt_unsettled". A step that - // starts on it gets it on the first look. - size_t max_looks = 3; - // The same, for a screen that may be a battle's opening: enough looks - // for its battle to show. BDSP's 300 ms looks cover 12 s, past its - // battle_after_fade (8 s), after which a fade with no battle settles. - size_t max_opening_looks = 40; - // Interrupts cleared for one step before it fails as - // "too_many_interrupts". - size_t max_per_step = 3; -}; - - // How the screen looked at the end of a look: the line a run log needs to // answer "had the scene ended before the step's first input?". struct ScreenSettle{ diff --git a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryInterrupts_Tests.cpp b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryInterrupts_Tests.cpp index 318ae0ee13..764352933d 100644 --- a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryInterrupts_Tests.cpp +++ b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryInterrupts_Tests.cpp @@ -570,9 +570,9 @@ UnitTestResult test_home_menu_stops_the_segment(){ UnitTestResult test_settle_of_a_look(){ struct Row{ - const char* name; + std::string name; ScreenLook look; - const char* expected; + std::string expected; }; const std::vector rows = { {"no frame", ScreenLook{}, "no frame seen"}, diff --git a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_Transitions.cpp b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_Transitions.cpp index 715869aa27..7b58c05649 100644 --- a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_Transitions.cpp +++ b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_Transitions.cpp @@ -41,7 +41,7 @@ const FadeProfile FRLG_FADE_PROFILE{ }; -const char* transition_kind_name(TransitionKind kind){ +std::string transition_kind_name(TransitionKind kind){ switch (kind){ case TransitionKind::FADE_BLACK: return "black fade"; case TransitionKind::FADE_WHITE: return "white fade"; @@ -76,7 +76,7 @@ std::string offset(std::optional time, WallClock origin){ } return std::format("{:+} ms", std::chrono::duration_cast(*time - origin).count()); } -const char* scene_change_name(SceneChange change){ +std::string scene_change_name(SceneChange change){ switch (change){ case SceneChange::UNKNOWN: return "scene unknown"; case SceneChange::SAME: return "same scene"; diff --git a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_Transitions.h b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_Transitions.h index 5764247571..9cae9bbe35 100644 --- a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_Transitions.h +++ b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_Transitions.h @@ -24,77 +24,12 @@ #include "Common/Cpp/Time.h" #include "CommonFramework/ImageTools/ImageStats.h" #include "CommonFramework/VideoPipeline/VideoFeed.h" +#include "Pokemon_FadeProfiles.h" namespace PokemonAutomation{ namespace Pokemon{ -// Whether the screen differs after a transition from before it. The -// tracker has only frame statistics; the caller compares the frames, or -// says it did not. -enum class SceneChange{ - UNKNOWN, - SAME, - DIFFERENT, -}; - - -// A game's fades, as data. Two tiers of the same test: a frame is uniform -// (the fade's hold) when its middle's stddev sum is at most -// `uniform_max_stddev_sum`, and partial (on the way down or up) when it is -// at most `partial_max_stddev_sum`. Either way it is dark or white by its -// rgb sum. -struct FadeProfile{ - double uniform_max_stddev_sum = 10; - double partial_max_stddev_sum = 60; - // Dark at or below this rgb sum; a partial frame up to `partial_dark_max_sum`. - double dark_max_sum = 225; - double partial_dark_max_sum = 300; - // White at or above this rgb sum; a partial frame from `partial_white_min_sum`. - double white_min_sum = 500; - double partial_white_min_sum = 450; - - // Partial frames for longer than this, with no hold, are the scene's - // own look (a dim cave floor, a street at night), not a fade. - Milliseconds max_fall = Milliseconds(1000); - // A transition still dark or white after this has timed out: the - // screen did not come back. - Milliseconds max_hold = Milliseconds(8000); - - // Whether the game fades to white between maps (BDSP's cave exits). - // Without, every white is an encounter's flash. - bool has_white_fade = true; - // A white held this long or less, back on the same scene, is a flash. - Milliseconds flash_max_hold = Milliseconds(150); - // A white held this long or more, not back on the same scene, is a - // white fade. Between the two the white is unsure. - Milliseconds white_fade_min_hold = Milliseconds(400); -}; - -// BDSP. The uniform tier is the shared walk's (FADE_MAX_STDDEV_SUM, the -// Oreburgh Gate's textured floor is no fade, lab-B 2026-11-08); the partial -// tier is run_into_door()'s 60, which caught the doorway's dim fade frames. -// A cave mouth's fade is dim (45 to 64 a channel), hence the dark sum of 225. -// The flash and white-fade holds are provisional: no console frames of an -// encounter flash and a cave exit have been timed side by side yet, so the -// band between them is wide and reports WHITE_UNSURE. -extern const FadeProfile BDSP_FADE_PROFILE; -// FRLG. The GBA fades to true black, so the dark tiers are the shared -// BlackScreenDetector's 100 and a little above; it has no white fade between -// maps, so every white is an encounter's flash. -extern const FadeProfile FRLG_FADE_PROFILE; - - -// What a transition was. -enum class TransitionKind : uint8_t{ - FADE_BLACK, // A door, a cave mouth, a scene cut, a battle's own fade. - FADE_WHITE, // A cave exit: a long white onto another scene. - FLASH, // An encounter's flash: a short white, back on the scene. - WHITE_UNSURE, // A white that may be either: wait for a battle. -}; -// "black fade", for the log. -const char* transition_kind_name(TransitionKind kind); - // Where the tracker is in a transition. enum class TransitionPhase : uint8_t{ SCENE, // No transition: the screen shows a scene. diff --git a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_WarpJudge.h b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_WarpJudge.h new file mode 100644 index 0000000000..ab112a4362 --- /dev/null +++ b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_WarpJudge.h @@ -0,0 +1,95 @@ +/* Warp Judge + * + * From: https://github.com/PokemonAutomation/ + * + * Split out of Pokemon_Interrupts.h, unchanged; it includes this header. + * + */ + +#ifndef PokemonAutomation_Pokemon_WarpJudge_H +#define PokemonAutomation_Pokemon_WarpJudge_H + +#include +#include +#include +#include "Common/Cpp/Time.h" +#include "Pokemon_ScreenEvents.h" +#include "Pokemon_Transitions.h" + +namespace PokemonAutomation{ +namespace Pokemon{ + + +// A game's timing, as data. +struct InterruptKnobs{ + // A fade must hold this long to be a warp's. One uniform frame is enough + // by default: a 50 ms fade can show on one frame only. + Milliseconds min_fade_hold = Milliseconds(0); + // A battle that shows this soon after a fade ends is that fade's + // encounter, and a fade is no warp before this has passed with no + // battle. BDSP's encounter flash shows its battle within 8 s + // (WHITE_FLASH_BATTLE_WAIT in its walk). + Milliseconds battle_after_fade = Milliseconds(8000); + // A dialog box that rose this long or less before a battle's fade is a + // trainer's lines. A trainer's lines can pause more than 4 s before the + // battle (BDSP r210d), and a trainer may say several boxes. + Milliseconds sight_lines_lead = Milliseconds(20000); +}; + +// The span of the log to judge: changes at `start` or later, and no later +// than `end`. +struct InterruptWindow{ + WallClock start = {}; + WallClock end = {}; +}; + + +// How a fade looked, for the warp judge. +struct FadeSpan{ + WarpFade fade = WarpFade::NONE; + WallClock down = {}; + // When the screen came back; none while it still shows the fade. + std::optional up = {}; +}; + +// What the warp judge made of a fade. +enum class WarpJudgement{ + NO_FADE, // No fade went down in the window. + FADE_SHOWING, // It went down and has not come back up. + TOO_SHORT, // It came back up before min_fade_hold. + SAME_SCENE, // It came back up on the scene it left. + WARPED, // Down, held, back up; not on the same scene. + FLASH, // An encounter's flash (a tracked transition only). + WHITE_UNSURE, // A white that may be a flash or a cave exit (a + // tracked transition only): wait for a battle. +}; +// "fade too short", for the log. +std::string warp_judgement_name(WarpJudgement judgement); + +// The warp judge's verdict and the fade it judged. +struct WarpVerdict{ + WarpJudgement judgement = WarpJudgement::NO_FADE; + // The last fade that went down in the window, if any. + std::optional fade = {}; +}; + +// A warp is a fade going down, holding uniform, and coming back up on +// another scene. The last fade that went down in `window` is judged; a +// LOCATION_BANNER does not count here (WarpSeen does). `change` is what +// the caller saw of the scene before and after: UNKNOWN does not rule the +// warp out. This judges the fade only: a battle after it is +// classify_interrupt()'s question. +WarpVerdict judge_warp( + const ScreenEventLog& log, InterruptWindow window, + const InterruptKnobs& knobs, SceneChange change +); +// The same judge over a TransitionTracker's transition, which has its own +// scene comparison. A transition whose hold went unseen onto another scene +// is a warp whatever min_fade_hold says: the scene change is the evidence. +WarpVerdict judge_warp(const Transition& transition, const InterruptKnobs& knobs); + + + +} // namespace Pokemon +} // namespace PokemonAutomation +#endif diff --git a/SerialPrograms/cmake/SourceFiles.cmake b/SerialPrograms/cmake/SourceFiles.cmake index f240d555aa..d72b5d513e 100644 --- a/SerialPrograms/cmake/SourceFiles.cmake +++ b/SerialPrograms/cmake/SourceFiles.cmake @@ -1516,15 +1516,21 @@ file(GLOB LIBRARY_SOURCES Source/Pokemon/AutoStory/Pokemon_AutoStory_Tests.h Source/Pokemon/AutoStory/Pokemon_BuiltinStoryActions.cpp Source/Pokemon/AutoStory/Pokemon_BuiltinStoryActions.h + Source/Pokemon/AutoStory/Pokemon_FadeProfiles.h + Source/Pokemon/AutoStory/Pokemon_InterruptHandlers.h Source/Pokemon/AutoStory/Pokemon_Interrupts.cpp Source/Pokemon/AutoStory/Pokemon_Interrupts.h Source/Pokemon/AutoStory/Pokemon_Interrupts_Tests.cpp Source/Pokemon/AutoStory/Pokemon_MapUtil.h Source/Pokemon/AutoStory/Pokemon_SceneJudges.cpp Source/Pokemon/AutoStory/Pokemon_SceneJudges.h + Source/Pokemon/AutoStory/Pokemon_ScreenEventLog.h + Source/Pokemon/AutoStory/Pokemon_ScreenEventTypes.h Source/Pokemon/AutoStory/Pokemon_ScreenEvents.cpp Source/Pokemon/AutoStory/Pokemon_ScreenEvents.h Source/Pokemon/AutoStory/Pokemon_ScreenEvents_Tests.cpp + Source/Pokemon/AutoStory/Pokemon_ScreenFades.h + Source/Pokemon/AutoStory/Pokemon_ScreenStory_Tests.h Source/Pokemon/AutoStory/Pokemon_StoryActions.cpp Source/Pokemon/AutoStory/Pokemon_StoryActions.h Source/Pokemon/AutoStory/Pokemon_StoryActions_Tests.cpp @@ -1553,6 +1559,7 @@ file(GLOB LIBRARY_SOURCES Source/Pokemon/AutoStory/Pokemon_Transitions.cpp Source/Pokemon/AutoStory/Pokemon_Transitions.h Source/Pokemon/AutoStory/Pokemon_Transitions_Tests.cpp + Source/Pokemon/AutoStory/Pokemon_WarpJudge.h Source/Pokemon/AutoStory/Types/Pokemon_GridPose.h Source/Pokemon/AutoStory/Types/Pokemon_StoryActionArg.cpp Source/Pokemon/AutoStory/Types/Pokemon_StoryActionArg.h From f03df6f28e669fd378fef35814e8452a78bb54aa Mon Sep 17 00:00:00 2001 From: dayfine Date: Tue, 10 Nov 2026 10:19:59 -0800 Subject: [PATCH 037/102] AutoStory: one story engine over a backend, with save policy from metadata Engine/ adds the shared story executor, templated on the pose type and instantiated for GridPose: StoryBackend (press/tap/hold/wait/observe, battle), StoryGame (actions, readers, save as data plus functions), StoryActionRegistry (built-ins with the game's on top, lint, dispatch), StoryStepRunner (skip_if, pose_after, [Step] line) and StoryEngine (event layer, then postconditions, then the save mode from metadata.phase and steps_hash). A FakeStoryBackend scripts a game for tests. Checkpoint JSON gets "metadata" (phase, verified, source, postconditions); ScreenMachine states can match on a ScreenObservation as well as on pixels. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_013VUubhHeYSMGSSDXZkKZss --- .../ScreenMachine/ScreenMachine.cpp | 12 +- .../CommonTools/ScreenMachine/ScreenMachine.h | 10 + .../ScreenMachine/ScreenObservation.h | 80 ++++ .../AutoStory/Data/Pokemon_StoryStepJson.cpp | 75 ++- .../Engine/Pokemon_StoryActionRegistry.cpp | 128 ++++++ .../Engine/Pokemon_StoryActionRegistry.h | 73 +++ .../AutoStory/Engine/Pokemon_StoryBackend.h | 70 +++ .../Engine/Pokemon_StoryBuiltinActions.cpp | 157 +++++++ .../Engine/Pokemon_StoryBuiltinActions.h | 47 ++ .../AutoStory/Engine/Pokemon_StoryEngine.cpp | 186 ++++++++ .../AutoStory/Engine/Pokemon_StoryEngine.h | 83 ++++ .../Engine/Pokemon_StoryEnginePolicy.cpp | 83 ++++ .../Engine/Pokemon_StoryEnginePolicy.h | 61 +++ .../Pokemon_StoryEnginePolicy_Tests.cpp | 433 ++++++++++++++++++ .../Engine/Pokemon_StoryEngine_Tests.cpp | 363 +++++++++++++++ .../Engine/Pokemon_StoryEngine_Tests.h | 28 ++ .../Engine/Pokemon_StoryFakeBackend.cpp | 86 ++++ .../Engine/Pokemon_StoryFakeBackend.h | 73 +++ .../AutoStory/Engine/Pokemon_StoryGame.h | 76 +++ .../Engine/Pokemon_StoryPoseConcept.cpp | 44 ++ .../Engine/Pokemon_StoryPoseConcept.h | 43 ++ .../Engine/Pokemon_StoryStepRunner.cpp | 84 ++++ .../Engine/Pokemon_StoryStepRunner.h | 58 +++ .../AutoStory/Pokemon_AutoStory_Tests.h | 3 + .../Pokemon_StorySavePolicy_Tests.cpp | 4 +- .../AutoStory/Types/Pokemon_StoryCheckpoint.h | 5 + .../Types/Pokemon_StoryCheckpointMetadata.cpp | 37 ++ .../Types/Pokemon_StoryCheckpointMetadata.h | 69 +++ SerialPrograms/cmake/SourceFiles.cmake | 22 + 29 files changed, 2485 insertions(+), 8 deletions(-) create mode 100644 SerialPrograms/Source/CommonTools/ScreenMachine/ScreenObservation.h create mode 100644 SerialPrograms/Source/Pokemon/AutoStory/Engine/Pokemon_StoryActionRegistry.cpp create mode 100644 SerialPrograms/Source/Pokemon/AutoStory/Engine/Pokemon_StoryActionRegistry.h create mode 100644 SerialPrograms/Source/Pokemon/AutoStory/Engine/Pokemon_StoryBackend.h create mode 100644 SerialPrograms/Source/Pokemon/AutoStory/Engine/Pokemon_StoryBuiltinActions.cpp create mode 100644 SerialPrograms/Source/Pokemon/AutoStory/Engine/Pokemon_StoryBuiltinActions.h create mode 100644 SerialPrograms/Source/Pokemon/AutoStory/Engine/Pokemon_StoryEngine.cpp create mode 100644 SerialPrograms/Source/Pokemon/AutoStory/Engine/Pokemon_StoryEngine.h create mode 100644 SerialPrograms/Source/Pokemon/AutoStory/Engine/Pokemon_StoryEnginePolicy.cpp create mode 100644 SerialPrograms/Source/Pokemon/AutoStory/Engine/Pokemon_StoryEnginePolicy.h create mode 100644 SerialPrograms/Source/Pokemon/AutoStory/Engine/Pokemon_StoryEnginePolicy_Tests.cpp create mode 100644 SerialPrograms/Source/Pokemon/AutoStory/Engine/Pokemon_StoryEngine_Tests.cpp create mode 100644 SerialPrograms/Source/Pokemon/AutoStory/Engine/Pokemon_StoryEngine_Tests.h create mode 100644 SerialPrograms/Source/Pokemon/AutoStory/Engine/Pokemon_StoryFakeBackend.cpp create mode 100644 SerialPrograms/Source/Pokemon/AutoStory/Engine/Pokemon_StoryFakeBackend.h create mode 100644 SerialPrograms/Source/Pokemon/AutoStory/Engine/Pokemon_StoryGame.h create mode 100644 SerialPrograms/Source/Pokemon/AutoStory/Engine/Pokemon_StoryPoseConcept.cpp create mode 100644 SerialPrograms/Source/Pokemon/AutoStory/Engine/Pokemon_StoryPoseConcept.h create mode 100644 SerialPrograms/Source/Pokemon/AutoStory/Engine/Pokemon_StoryStepRunner.cpp create mode 100644 SerialPrograms/Source/Pokemon/AutoStory/Engine/Pokemon_StoryStepRunner.h create mode 100644 SerialPrograms/Source/Pokemon/AutoStory/Types/Pokemon_StoryCheckpointMetadata.cpp create mode 100644 SerialPrograms/Source/Pokemon/AutoStory/Types/Pokemon_StoryCheckpointMetadata.h diff --git a/SerialPrograms/Source/CommonTools/ScreenMachine/ScreenMachine.cpp b/SerialPrograms/Source/CommonTools/ScreenMachine/ScreenMachine.cpp index 3bbc9cbd1c..a7c290bc8b 100644 --- a/SerialPrograms/Source/CommonTools/ScreenMachine/ScreenMachine.cpp +++ b/SerialPrograms/Source/CommonTools/ScreenMachine/ScreenMachine.cpp @@ -17,7 +17,7 @@ namespace{ const ScreenState* classify(const std::vector& states, const ImageViewRGB32& screen){ for (const ScreenState& state : states){ - if (state.matches(screen)){ + if (state.matches && state.matches(screen)){ return &state; } } @@ -27,6 +27,16 @@ const ScreenState* classify(const std::vector& states, const ImageV } // namespace +const ScreenState* match_screen_state(const std::vector& states, const ScreenObservation& observation){ + for (const ScreenState& state : states){ + if (state.matches_observation && state.matches_observation(observation)){ + return &state; + } + } + return nullptr; +} + + const ScreenState& read_screen_state( VideoStream& stream, CancellableScope& scope, StepTrace& trace, const std::vector& states, VideoSnapshot& frame diff --git a/SerialPrograms/Source/CommonTools/ScreenMachine/ScreenMachine.h b/SerialPrograms/Source/CommonTools/ScreenMachine/ScreenMachine.h index 33cfa9f2dd..6ac31e0635 100644 --- a/SerialPrograms/Source/CommonTools/ScreenMachine/ScreenMachine.h +++ b/SerialPrograms/Source/CommonTools/ScreenMachine/ScreenMachine.h @@ -22,6 +22,7 @@ #include "CommonFramework/ImageTypes/ImageViewRGB32.h" #include "CommonFramework/Tools/VideoStream.h" #include "CommonFramework/VideoPipeline/VideoFeed.h" +#include "ScreenObservation.h" #include "StepTrace.h" namespace PokemonAutomation{ @@ -33,6 +34,11 @@ struct ScreenState{ // Whether this is the screen. States are tried in order; the first match wins, so // the last state should match anything. std::function matches; + // Whether this is the screen, from what a look at the game observed + // instead of from its pixels, so the state also runs in a simulation. + // A state may have either or both; read_screen_state() uses `matches` + // and skips a state without it. + std::function matches_observation = nullptr; // The one step to take on this screen. std::function act; // The screens the step may lead to besides staying here. Empty: any. @@ -53,6 +59,10 @@ const ScreenState& read_screen_state( const std::vector& states, VideoSnapshot& frame ); +// The first of `states` whose matches_observation() accepts `observation`; +// null when none does. States without one are skipped. +const ScreenState* match_screen_state(const std::vector& states, const ScreenObservation& observation); + // The checks between reads: the screen must be one the previous state can lead // to, no state may come up too often, and steps must keep changing the screen. class ScreenMachineChecks{ diff --git a/SerialPrograms/Source/CommonTools/ScreenMachine/ScreenObservation.h b/SerialPrograms/Source/CommonTools/ScreenMachine/ScreenObservation.h new file mode 100644 index 0000000000..96eccb0df4 --- /dev/null +++ b/SerialPrograms/Source/CommonTools/ScreenMachine/ScreenObservation.h @@ -0,0 +1,80 @@ +/* Screen Observation + * + * From: https://github.com/PokemonAutomation/ + * + * What one look at the game showed, as facts rather than pixels: the + * events on screen (a fade, a text box, a battle) and named readings. A + * console fills it from a frame with the game's detectors; a simulation + * fills it from its model and has no frame. A ScreenState that matches on + * an observation (ScreenState::matches_observation) therefore runs in + * both. + * + */ + +#ifndef PokemonAutomation_CommonTools_ScreenObservation_H +#define PokemonAutomation_CommonTools_ScreenObservation_H + +#include +#include +#include +#include +#include +#include +#include "Common/Cpp/Time.h" +#include "CommonFramework/VideoPipeline/VideoFeed.h" + +namespace PokemonAutomation{ + + +// Something a look at the screen can show. Several can hold at once. +enum class ScreenEvent : uint8_t{ + FADE_BLACK, // the screen is (fading to) black: a warp, a battle start + FADE_WHITE, // the screen is (fading to) white + TEXT_BOX, // a dialogue or message box is open + BATTLE, // a battle is showing + CAN_MOVE, // the player can move: no box, menu or scene holds them + STILL, // nothing moved since the previous look +}; + +// The set of events one look showed. +class ScreenEvents{ +public: + ScreenEvents() = default; + explicit ScreenEvents(std::initializer_list events){ + for (ScreenEvent event : events){ + add(event); + } + } + + bool has(ScreenEvent event) const{ + return (m_bits & bit(event)) != 0; + } + void add(ScreenEvent event){ + m_bits |= bit(event); + } + + bool operator==(const ScreenEvents& other) const = default; + +private: + static uint32_t bit(ScreenEvent event){ + return (uint32_t)1 << (uint32_t)event; + } + + uint32_t m_bits = 0; +}; + +// One look at the game. +struct ScreenObservation{ + WallClock when = WallClock::min(); + ScreenEvents events = {}; + // Named numbers a reader found: "bag.RARE_CANDY", "facing". + std::map> readings = {}; + // The frame looked at; none in a simulation. A state that needs it + // can only run on a console. + std::optional frame = std::nullopt; +}; + + + +} // namespace PokemonAutomation +#endif diff --git a/SerialPrograms/Source/Pokemon/AutoStory/Data/Pokemon_StoryStepJson.cpp b/SerialPrograms/Source/Pokemon/AutoStory/Data/Pokemon_StoryStepJson.cpp index 98f434c568..471db0eae1 100644 --- a/SerialPrograms/Source/Pokemon/AutoStory/Data/Pokemon_StoryStepJson.cpp +++ b/SerialPrograms/Source/Pokemon/AutoStory/Data/Pokemon_StoryStepJson.cpp @@ -310,6 +310,71 @@ StoryPostconditions read_postconditions(const JsonValue& value, std::string_view } +JsonValue verification_json(const StoryVerification& verified){ + JsonObject result; + result["steps_hash"] = verified.steps_hash; + result["build"] = verified.build; + result["date"] = verified.date; + result["runs"] = verified.runs; + return result; +} + +StoryVerification read_verification(const JsonValue& value, std::string_view source){ + const JsonObject& root = fields(value, {"steps_hash", "build", "date", "runs"}, source); + StoryVerification result; + result.steps_hash = root.get_string_throw("steps_hash"); + if (const JsonValue* field = root.get_value("build")){ + result.build = field->to_string_throw(); + } + if (const JsonValue* field = root.get_value("date")){ + result.date = field->to_string_throw(); + } + if (const JsonValue* field = root.get_value("runs")){ + result.runs = field->to_string_throw(); + } + return result; +} + +// The "metadata" object: the phase, the verification, the source and the +// postconditions. +JsonValue metadata_json(const StoryCheckpoint& checkpoint){ + JsonObject result; + result["phase"] = story_phase_name(checkpoint.metadata.phase); + if (checkpoint.metadata.verified){ + result["verified"] = verification_json(*checkpoint.metadata.verified); + } + if (!checkpoint.metadata.source.empty()){ + result["source"] = checkpoint.metadata.source; + } + if (checkpoint.postconditions != StoryPostconditions{}){ + result["postconditions"] = postconditions_json(checkpoint.postconditions); + } + return result; +} + +// Reads "metadata" into `checkpoint`. A missing phase is testing. +void read_metadata(StoryCheckpoint& checkpoint, const JsonValue& value, std::string_view source){ + const JsonObject& root = fields(value, {"phase", "verified", "source", "postconditions"}, source); + if (const JsonValue* field = root.get_value("phase")){ + const std::string name = field->to_string_throw(); + const std::optional phase = read_story_phase(name); + if (!phase){ + throw ParseException(std::format("{}: unknown phase {}", source, name)); + } + checkpoint.metadata.phase = *phase; + } + if (const JsonValue* field = root.get_value("verified")){ + checkpoint.metadata.verified = read_verification(*field, source); + } + if (const JsonValue* field = root.get_value("source")){ + checkpoint.metadata.source = field->to_string_throw(); + } + if (const JsonValue* field = root.get_value("postconditions")){ + checkpoint.postconditions = read_postconditions(*field, source); + } +} + + } // namespace @@ -396,14 +461,14 @@ JsonValue story_checkpoint_json(const StoryCheckpoint& checkpoint){ events.push_back(story_step_json(step)); } result["events"] = std::move(events); - if (checkpoint.postconditions != StoryPostconditions{}){ - result["postconditions"] = postconditions_json(checkpoint.postconditions); + if (checkpoint.postconditions != StoryPostconditions{} || checkpoint.metadata != StoryCheckpointMetadata{}){ + result["metadata"] = metadata_json(checkpoint); } return result; } StoryCheckpoint read_story_checkpoint(const JsonValue& value, std::string_view source, std::span actions){ - const JsonObject& root = fields(value, {"id", "title", "start", "events", "postconditions"}, source); + const JsonObject& root = fields(value, {"id", "title", "start", "events", "metadata"}, source); StoryCheckpoint result; result.id = root.get_string_throw("id"); if (result.id.empty()){ @@ -421,8 +486,8 @@ StoryCheckpoint read_story_checkpoint(const JsonValue& value, std::string_view s } result.steps.push_back(std::move(step)); } - if (const JsonValue* postconditions = root.get_value("postconditions")){ - result.postconditions = read_postconditions(*postconditions, source); + if (const JsonValue* metadata = root.get_value("metadata")){ + read_metadata(result, *metadata, source); } return result; } diff --git a/SerialPrograms/Source/Pokemon/AutoStory/Engine/Pokemon_StoryActionRegistry.cpp b/SerialPrograms/Source/Pokemon/AutoStory/Engine/Pokemon_StoryActionRegistry.cpp new file mode 100644 index 0000000000..fec02f1e79 --- /dev/null +++ b/SerialPrograms/Source/Pokemon/AutoStory/Engine/Pokemon_StoryActionRegistry.cpp @@ -0,0 +1,128 @@ +/* Story Action Registry + * + * From: https://github.com/PokemonAutomation/ + * + */ + +#include +#include +#include +#include +#include "Pokemon/AutoStory/Pokemon_MapUtil.h" +#include "Pokemon/AutoStory/Pokemon_StoryStepExecutor.h" +#include "Pokemon_StoryActionRegistry.h" +#include "Pokemon_StoryBuiltinActions.h" + +namespace PokemonAutomation{ +namespace Pokemon{ + + +namespace{ + + +// A walk of no legs, or a leg of no tiles. +inline std::vector leg_problems(const StoryActionArgs& args){ + const std::vector* legs = value_if_at_it>(args, args.find("legs")); + if (legs == nullptr){ + return {}; + } + std::vector problems; + if (legs->empty()){ + problems.emplace_back("no legs"); + } + for (const StoryLeg& leg : *legs){ + if (leg.tiles <= 0){ + problems.emplace_back("a leg of no tiles"); + } + } + return problems; +} + + +} // namespace + + +template +StoryActionRegistry::StoryActionRegistry(const StoryGame& game) + : m_game(game) + , m_actions(builtin_story_handlers(game)) +{ + // 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. + for (const StoryAction& action : game.actions){ + const auto same = std::find_if(m_actions.begin(), m_actions.end(), [&](const StoryAction& builtin){ + return builtin.spec.kind == action.spec.kind && builtin.spec.name == action.spec.name; + }); + if (same != m_actions.end()){ + *same = action; + }else{ + m_actions.push_back(action); + } + } + for (const StoryAction& action : m_actions){ + m_specs.push_back(action.spec); + } +} + +template +const StoryAction* StoryActionRegistry::find(StoryStepKind kind, std::string_view name) const{ + for (const StoryAction& action : m_actions){ + if (action.spec.kind == kind && (name.empty() || action.spec.name == name)){ + return &action; + } + } + return nullptr; +} + +template +std::vector StoryActionRegistry::check(const StoryStep& step) const{ + if (step.kind == StoryStepKind::GAME && step.action.empty()){ + return {"no action"}; + } + const StoryAction* action = find(step.kind, step.action); + if (action == nullptr){ + return {std::format("unknown action \"{}\" for {}", step.action, story_step_kind_name(step.kind))}; + } + std::vector problems = story_args_errors(action->spec, step.args); + for (std::string& problem : leg_problems(step.args)){ + problems.push_back(std::move(problem)); + } + return problems; +} + +template +std::vector StoryActionRegistry::lint(const StoryCheckpoint& checkpoint) const{ + std::vector problems; + if (checkpoint.id.empty()){ + problems.emplace_back("a checkpoint has no id"); + } + std::set names; + for (size_t c = 0; c < checkpoint.steps.size(); c++){ + const StoryStep& step = checkpoint.steps[c]; + const std::string where = std::format("{} step {} {}", checkpoint.id, c + 1, step.name); + if (step.name.empty() || !names.insert(step.name).second){ + problems.push_back(where + ": empty or repeated name"); + } + for (const std::string& problem : check(step)){ + problems.push_back(std::format("{}: {}", where, problem)); + } + } + return problems; +} + +template +Outcome StoryActionRegistry::dispatch(StoryBackend& backend, RunState& state, const StoryStep& step) const{ + const StoryAction* action = find(step.kind, step.action); + if (action == nullptr || !action->handler){ + return unsupported_step(step); + } + return action->handler(backend, state, with_fallbacks(action->spec, step.args)); +} + + +template class StoryActionRegistry; + + + +} // namespace Pokemon +} // namespace PokemonAutomation diff --git a/SerialPrograms/Source/Pokemon/AutoStory/Engine/Pokemon_StoryActionRegistry.h b/SerialPrograms/Source/Pokemon/AutoStory/Engine/Pokemon_StoryActionRegistry.h new file mode 100644 index 0000000000..dfbb99c84e --- /dev/null +++ b/SerialPrograms/Source/Pokemon/AutoStory/Engine/Pokemon_StoryActionRegistry.h @@ -0,0 +1,73 @@ +/* Story Action Registry + * + * From: https://github.com/PokemonAutomation/ + * + * A game's actions, looked up by a step's kind and action name: the + * shared built-ins (Pokemon_StoryBuiltinActions.h) with the game's own on + * top. It checks a step against its action's spec before anything runs, + * and runs a step's action with the spec's fallbacks filled in. + * + */ + +#ifndef PokemonAutomation_Pokemon_StoryActionRegistry_H +#define PokemonAutomation_Pokemon_StoryActionRegistry_H + +#include +#include +#include +#include "Pokemon/AutoStory/Types/Pokemon_GridPose.h" +#include "Pokemon/AutoStory/Types/Pokemon_StoryCheckpoint.h" +#include "Pokemon/AutoStory/Types/Pokemon_StoryStep.h" +#include "Pokemon_StoryGame.h" + +namespace PokemonAutomation{ +namespace Pokemon{ + + +// `game`'s actions. `game` must outlive the registry. +template +class StoryActionRegistry{ +public: + explicit StoryActionRegistry(const StoryGame& game); + StoryActionRegistry(const StoryActionRegistry&) = delete; + StoryActionRegistry& operator=(const StoryActionRegistry&) = delete; + + const StoryGame& game() const{ + return m_game; + } + + // Every action's spec, for the JSON reader (read_story_checkpoint()). + const std::vector& specs() const{ + return m_specs; + } + + // What is wrong with `step` before it runs: an action that is not + // registered, args that don't fit its spec, a walk of no legs. + std::vector check(const StoryStep& step) const; + + // check() for each step of `checkpoint`, and its step names: none + // empty, none repeated. + std::vector lint(const StoryCheckpoint& checkpoint) const; + + // Runs `step`'s action with its args' fallbacks filled in; a step with + // no registered action fails as unsupported_step(). + Outcome dispatch(StoryBackend& backend, RunState& state, const StoryStep& step) const; + +private: + // The action of `kind` named `name`; for an empty name, the kind's + // first. Null when there is none. + const StoryAction* find(StoryStepKind kind, std::string_view name) const; + + const StoryGame& m_game; + std::vector> m_actions; + std::vector m_specs; +}; + +// Instantiated once, in Pokemon_StoryActionRegistry.cpp. +extern template class StoryActionRegistry; + + + +} // namespace Pokemon +} // namespace PokemonAutomation +#endif diff --git a/SerialPrograms/Source/Pokemon/AutoStory/Engine/Pokemon_StoryBackend.h b/SerialPrograms/Source/Pokemon/AutoStory/Engine/Pokemon_StoryBackend.h new file mode 100644 index 0000000000..9c14276f57 --- /dev/null +++ b/SerialPrograms/Source/Pokemon/AutoStory/Engine/Pokemon_StoryBackend.h @@ -0,0 +1,70 @@ +/* Story Backend + * + * From: https://github.com/PokemonAutomation/ + * + * Input and observation, nothing else: what the story engine drives. One + * per run. A console backend wraps the console's controller and video and + * builds each observation with the game's detectors; a simulation backend + * wraps a model of the game. The engine and every action run the same on + * both. + * + */ + +#ifndef PokemonAutomation_Pokemon_StoryBackend_H +#define PokemonAutomation_Pokemon_StoryBackend_H + +#include +#include +#include "Common/Cpp/CancellableScope.h" +#include "Common/Cpp/Time.h" +#include "CommonTools/ScreenMachine/ScreenObservation.h" +#include "NintendoSwitch/Controllers/NintendoSwitch_ControllerButtons.h" +#include "Pokemon/AutoStory/Pokemon_StoryOutcome.h" +#include "Pokemon/AutoStory/Types/Pokemon_StoryActionArg.h" +#include "Pokemon/Navigation/Pokemon_Grid.h" +#include "Pokemon_StoryPoseConcept.h" + +namespace PokemonAutomation{ +namespace Pokemon{ + + +// How fast a held direction moves the player. +enum class StoryPace{ + WALK, + RUN, +}; + +// One look at the game, with where the player is when a reader knows it +// (StoryGame::readers fill `pose` and the readings). +template +struct Observation : public ScreenObservation{ + std::optional pose = std::nullopt; +}; + +// The engine's only way to the game. +// code-health: allow public_methods -- the agreed backend boundary is these eight low-level calls; splitting them would make every action take two objects +template +class StoryBackend{ +public: + virtual ~StoryBackend() = default; + + virtual void press(NintendoSwitch::Button button, Milliseconds hold, Milliseconds release) = 0; + // One tile in `direction`, or a turn to face it. + virtual void tap(Direction direction) = 0; + virtual void hold(Direction direction, Milliseconds duration, StoryPace pace) = 0; + virtual void wait(Milliseconds duration) = 0; + // The game now, once every input sent so far has been done. + virtual Observation observe() = 0; + // A whole battle, from its start to the overworld. High level for now: + // a console fights with the game's battle code, a simulation with its + // battle model. `args` are the BATTLE step's. + virtual Outcome battle(const StoryActionArgs& args) = 0; + virtual void log(std::string_view line) = 0; + virtual CancellableScope& scope() = 0; +}; + + + +} // namespace Pokemon +} // namespace PokemonAutomation +#endif diff --git a/SerialPrograms/Source/Pokemon/AutoStory/Engine/Pokemon_StoryBuiltinActions.cpp b/SerialPrograms/Source/Pokemon/AutoStory/Engine/Pokemon_StoryBuiltinActions.cpp new file mode 100644 index 0000000000..33110781b5 --- /dev/null +++ b/SerialPrograms/Source/Pokemon/AutoStory/Engine/Pokemon_StoryBuiltinActions.cpp @@ -0,0 +1,157 @@ +/* Story Builtin Actions + * + * From: https://github.com/PokemonAutomation/ + * + */ + +#include +#include +#include +#include +#include +#include +#include +#include "Pokemon/AutoStory/Pokemon_BuiltinStoryActions.h" +#include "Pokemon/AutoStory/Pokemon_TilePose.h" +#include "Pokemon_StoryBuiltinActions.h" + +namespace PokemonAutomation{ +namespace Pokemon{ + + +namespace{ + + +// Looks before a text or scene counts as stuck. +inline constexpr size_t MAX_TEXT_LOOKS = 80; +// Looks for a text box to open after a talk's A. +inline constexpr size_t MAX_OPEN_LOOKS = 20; + + +// The action of a built-in that needs the game's own code. +template +StoryActionHandler needs_game(std::string name){ + return [name = std::move(name)](StoryBackend&, RunState&, const StoryActionArgs&){ + return outcome_failed( + "unsupported_step", + std::format("{} needs the game's own action: register one named \"{}\" in StoryGame::actions", name, name) + ); + }; +} + +// Presses A through text and scenes until the player can move. +template +Outcome mash_to_overworld(StoryBackend& backend){ + using namespace std::chrono_literals; + for (size_t c = 0; c < MAX_TEXT_LOOKS; c++){ + const Observation now = backend.observe(); + if (now.events.has(ScreenEvent::CAN_MOVE) && !now.events.has(ScreenEvent::TEXT_BOX)){ + return outcome_ok(); + } + backend.press(NintendoSwitch::BUTTON_A, 80ms, 120ms); + } + return outcome_failed("mash_no_overworld", std::format("no overworld after {} looks", MAX_TEXT_LOOKS)); +} + +template +Outcome mash(StoryBackend& backend, RunState&, const StoryActionArgs&){ + return mash_to_overworld(backend); +} + +// A at what the player faces must open a text box; then text to the +// overworld. No box is a failure: nobody was there to talk to. +template +Outcome talk(StoryBackend& backend, RunState&, const StoryActionArgs&){ + using namespace std::chrono_literals; + backend.press(NintendoSwitch::BUTTON_A, 80ms, 120ms); + for (size_t c = 0; c < MAX_OPEN_LOOKS; c++){ + if (backend.observe().events.has(ScreenEvent::TEXT_BOX)){ + return mash_to_overworld(backend); + } + backend.wait(100ms); + } + return outcome_failed("talk_no_text", "A opened no text box"); +} + +// Where `legs` leave a run that stood on one tile; nothing otherwise. +inline std::optional after_legs(const Pose& start, const std::vector& legs){ + const std::vector tiles = tiles_of(start); + if (tiles.size() != 1 || legs.empty()){ + return std::nullopt; + } + TilePos tile = tiles[0]; + for (const StoryLeg& leg : legs){ + for (int c = 0; c < leg.tiles; c++){ + tile = tile.next(leg.direction); + } + } + return tile_pose(start.map, {tile}, legs.back().direction); +} + +template +Outcome walk_legs(StoryBackend& backend, RunState& state, const StoryActionArgs& args){ + const std::vector& legs = story_arg>(args, "legs"); + for (const StoryLeg& leg : legs){ + for (int c = 0; c < leg.tiles; c++){ + backend.tap(leg.direction); + } + } + return outcome_ok(after_legs(state.pose, legs)); +} + +template +Outcome face(StoryBackend& backend, RunState&, const StoryActionArgs& args){ + backend.tap(story_arg(args, "direction")); + return outcome_ok(); +} + +template +Outcome answer(StoryBackend& backend, RunState&, const StoryActionArgs& args){ + using namespace std::chrono_literals; + backend.press(story_arg(args, "yes") ? NintendoSwitch::BUTTON_A : NintendoSwitch::BUTTON_B, 80ms, 120ms); + return outcome_ok(); +} + +template +Outcome fight(StoryBackend& backend, RunState&, const StoryActionArgs& args){ + return backend.battle(args); +} + +// The built-in action named `name`, or the hook for a game's own. +template +StoryActionHandler builtin_handler(std::string_view name){ + const std::map, std::less<>> handlers{ + {"legs", &walk_legs}, + {"face", &face}, + {"answer", &answer}, + {"fight", &fight}, + }; + const auto it = handlers.find(name); + return it != handlers.end() ? it->second : needs_game(std::string(name)); +} + + +} // namespace + + +template +std::vector> builtin_story_handlers(const StoryGame& game){ + std::vector> actions; + for (const StoryActionSpec& spec : builtin_story_actions()){ + actions.push_back({.spec = spec, .handler = builtin_handler(spec.name)}); + } + actions.push_back({.spec = {.kind = StoryStepKind::TALK, .name = "talk", .args = {}}, .handler = &talk}); + actions.push_back({.spec = {.kind = StoryStepKind::MASH, .name = "mash", .args = {}}, .handler = &mash}); + StoryActionHandler save = [save = game.save](StoryBackend& backend, RunState&, const StoryActionArgs&){ + return save ? save(backend) : outcome_failed("unsupported_step", "save needs StoryGame::save"); + }; + actions.push_back({.spec = {.kind = StoryStepKind::SAVE, .name = "save", .args = {}}, .handler = std::move(save)}); + return actions; +} + +template std::vector> builtin_story_handlers(const StoryGame& game); + + + +} // namespace Pokemon +} // namespace PokemonAutomation diff --git a/SerialPrograms/Source/Pokemon/AutoStory/Engine/Pokemon_StoryBuiltinActions.h b/SerialPrograms/Source/Pokemon/AutoStory/Engine/Pokemon_StoryBuiltinActions.h new file mode 100644 index 0000000000..dae70e1048 --- /dev/null +++ b/SerialPrograms/Source/Pokemon/AutoStory/Engine/Pokemon_StoryBuiltinActions.h @@ -0,0 +1,47 @@ +/* Story Builtin Actions + * + * From: https://github.com/PokemonAutomation/ + * + * The code of the shared built-in actions, written once against the + * backend, so every game and both backends do them the same way: + * + * legs LEGS a tap per tile; the pose moves along when it was one tile + * face STEP a tap in `direction` + * answer ANSWER A for yes, B for no + * talk TALK A, then a text box must open, then text to the overworld + * mash MASH text until the player can move + * fight BATTLE the backend's battle + * save SAVE the game's save (StoryGame::save) + * + * route, ready, train and shop need a game's map, planner or menus: their + * built-in action fails as "unsupported_step" naming the hook, and a game + * that has them registers an action of the same kind and name in + * StoryGame::actions, which replaces the built-in one. + * + */ + +#ifndef PokemonAutomation_Pokemon_StoryBuiltinActions_H +#define PokemonAutomation_Pokemon_StoryBuiltinActions_H + +#include +#include "Pokemon/AutoStory/Types/Pokemon_GridPose.h" +#include "Pokemon_StoryGame.h" + +namespace PokemonAutomation{ +namespace Pokemon{ + + +// The built-in actions, in the order a kind's default comes first: the +// specs of builtin_story_actions() (Pokemon_BuiltinStoryActions.h), then +// talk, mash and save, which take no args. `game` gives the save. +template +std::vector> builtin_story_handlers(const StoryGame& game); + +// Instantiated once, in Pokemon_StoryBuiltinActions.cpp. +extern template std::vector> builtin_story_handlers(const StoryGame& game); + + + +} // namespace Pokemon +} // namespace PokemonAutomation +#endif diff --git a/SerialPrograms/Source/Pokemon/AutoStory/Engine/Pokemon_StoryEngine.cpp b/SerialPrograms/Source/Pokemon/AutoStory/Engine/Pokemon_StoryEngine.cpp new file mode 100644 index 0000000000..24ecc52a46 --- /dev/null +++ b/SerialPrograms/Source/Pokemon/AutoStory/Engine/Pokemon_StoryEngine.cpp @@ -0,0 +1,186 @@ +/* Story Engine + * + * From: https://github.com/PokemonAutomation/ + * + */ + +#include +#include +#include +#include +#include "Pokemon/AutoStory/Pokemon_StoryEvents.h" +#include "Pokemon_StoryEngine.h" + +namespace PokemonAutomation{ +namespace Pokemon{ + + +namespace{ + + +// The old executor interface over the step runner, so the engine builds +// its events with build_story_checkpoint() (from_save, once_per_save). +// Goes once StoryStepExecutor is deleted and that code moves here. +template +class RunnerExecutor : public StoryStepExecutor{ +public: + RunnerExecutor(StoryStepRunner& runner, const StoryGame& game) + : m_runner(runner) + , m_game(game) + {} + + virtual void begin_attempt(const StoryCheckpoint& data) override{ + if (m_game.begin_attempt){ + m_game.begin_attempt(data); + } + } + virtual Outcome run(RunState& state, const StoryStep& step) override{ + return m_runner.act(state, step); + } + virtual bool holds(std::string_view condition, RunState& state) override{ + return m_runner.holds(condition, state); + } + +private: + StoryStepRunner& m_runner; + const StoryGame& m_game; +}; + +// `game` with its SAVE step "save" saving only while `mode` is +// PER_CHECKPOINT: a checkpoint under test or verification must not save +// part-way. +template +StoryGame with_gated_save_step(StoryGame game, const StorySaveMode& mode){ + StoryActionHandler gated = [&mode, save = game.save](StoryBackend& backend, RunState&, const StoryActionArgs&){ + if (mode != StorySaveMode::PER_CHECKPOINT){ + backend.log(std::format("[Save] save step skipped: save mode {}", story_save_mode_name(mode))); + return outcome_unchanged(); + } + return save ? save(backend) : outcome_failed("unsupported_step", "save needs StoryGame::save"); + }; + game.actions.push_back({.spec = {.kind = StoryStepKind::SAVE, .name = "save", .args = {}}, .handler = std::move(gated)}); + return game; +} + + +} // namespace + + +ObservedState observed_state(const Observation& observation){ + constexpr std::string_view BAG = "bag."; + constexpr std::string_view FLAG = "flag."; + ObservedState observed; + if (observation.pose){ + observed.map = observation.pose->map; + if (observation.pose->tiles.size() == 1){ + observed.tile = observation.pose->tiles[0]; + } + observed.facing = observation.pose->facing; + } + for (const auto& [name, value] : observation.readings){ + if (name.starts_with(BAG)){ + observed.items[name.substr(BAG.size())] = value < 0 ? 0 : (size_t)value; + }else if (name.starts_with(FLAG)){ + observed.flags[name.substr(FLAG.size())] = value != 0; + } + } + return observed; +} + + +template +StoryEngine::StoryEngine(const StoryGame& game, StoryBackend& backend) + : m_game(with_gated_save_step(game, m_save_mode)) + , m_backend(backend) + , m_registry(m_game) + , m_runner(m_registry, backend) +{} + +template +std::string StoryEngine::steps_hash(const StoryCheckpoint& checkpoint) const{ + return story_steps_hash(checkpoint, m_registry.specs()); +} + +template +StoryEngineReport StoryEngine::run_checkpoint(const StoryCheckpoint& checkpoint, RunState& state, SavePoint point){ + StoryEngineReport report; + const std::vector problems = m_registry.lint(checkpoint); + if (!problems.empty()){ + for (const std::string& problem : problems){ + m_backend.log("[Lint] " + problem); + } + report.run.failure = outcome_failed("lint_failed", problems.front()); + return report; + } + report.save = decide_story_save(checkpoint, steps_hash(checkpoint)); + m_backend.log(report.save.reason); + m_save_mode = report.save.mode; + report.run = run_steps(checkpoint, state); + m_save_mode = StorySaveMode::NONE; + if (!report.run.completed){ + m_backend.log(std::format("[Save] {}: run failed: not saved", checkpoint.id)); + return report; + } + report.postconditions = check_postconditions(checkpoint); + report.verdict = report.postconditions->count(PostconditionVerdict::FAILED) == 0 + ? CheckpointVerdict::PASSED + : CheckpointVerdict::FAILED; + save_if_allowed(report, checkpoint, point); + return report; +} + +template +CheckpointReport StoryEngine::run_steps(const StoryCheckpoint& checkpoint, RunState& state){ + RunnerExecutor executor(m_runner, m_game); + Checkpoint events = build_story_checkpoint(checkpoint, executor, &m_prepared); + if (m_game.interrupts){ + events.interrupts = m_game.interrupts(m_backend); + } + EventLogger log = [this](const std::string& line){ + m_backend.log(line); + }; + return Pokemon::run_checkpoint(state, events, log); +} + +template +void StoryEngine::save_if_allowed(StoryEngineReport& report, const StoryCheckpoint& checkpoint, SavePoint point){ + const bool passed = report.verdict == CheckpointVerdict::PASSED; + if (!story_save_allowed(report.save.mode, report.verdict, point)){ + m_backend.log(std::format( + "[Save] {}: not saved: save mode {}, {}", checkpoint.id, + story_save_mode_name(report.save.mode), passed ? "passed" : "postconditions failed" + )); + return; + } + if (!m_game.save){ + m_backend.log(std::format("[Save] {}: not saved: the game has no save", checkpoint.id)); + return; + } + const Outcome saved = m_game.save(m_backend); + report.saved = saved.succeeded(); + m_backend.log(std::format("[Save] {}: {}", checkpoint.id, report.saved ? "saved" : "save failed: " + to_string(saved))); +} + +template +PostconditionReport StoryEngine::check_postconditions(const StoryCheckpoint& checkpoint){ + Observation observation = m_backend.observe(); + for (const auto& [name, reader] : m_game.readers){ + if (reader){ + reader(m_backend, observation); + } + } + PostconditionReport report = Pokemon::check_postconditions(checkpoint, observed_state(observation)); + for (const std::string& line : postcondition_log_lines(report)){ + m_backend.log(line); + } + return report; +} + + +template class StoryEngine; + + + + +} // namespace Pokemon +} // namespace PokemonAutomation diff --git a/SerialPrograms/Source/Pokemon/AutoStory/Engine/Pokemon_StoryEngine.h b/SerialPrograms/Source/Pokemon/AutoStory/Engine/Pokemon_StoryEngine.h new file mode 100644 index 0000000000..0cbf5b37ca --- /dev/null +++ b/SerialPrograms/Source/Pokemon/AutoStory/Engine/Pokemon_StoryEngine.h @@ -0,0 +1,83 @@ +/* Story Engine + * + * From: https://github.com/PokemonAutomation/ + * + * The one story executor, for every game and both backends. A run of a + * checkpoint lints its steps against the game's actions (a problem fails + * the run before any input), runs them through the event layer + * (Pokemon_StoryEvents.h: skip_if, retries, recoveries, interrupts) with + * the step runner, checks the postconditions with the game's readers, and + * saves only as the checkpoint's phase allows (Pokemon_StoryEnginePolicy.h). + * + * See MIGRATION.md in this folder for moving a game onto it. + * + */ + +#ifndef PokemonAutomation_Pokemon_StoryEngine_H +#define PokemonAutomation_Pokemon_StoryEngine_H + +#include +#include +#include "Pokemon/AutoStory/Pokemon_StoryPostconditionCheck.h" +#include "Pokemon/AutoStory/Pokemon_StoryStepExecutor.h" +#include "Pokemon/AutoStory/Types/Pokemon_GridPose.h" +#include "Pokemon/AutoStory/Types/Pokemon_StorySaveMode.h" +#include "Pokemon_StoryActionRegistry.h" +#include "Pokemon_StoryEnginePolicy.h" +#include "Pokemon_StoryStepRunner.h" + +namespace PokemonAutomation{ +namespace Pokemon{ + + +// What a look at a tile game shows of a checkpoint's postconditions: the +// map, the tile (when the pose is one tile) and the facing from the pose; +// items from "bag." readings; flags from "flag." readings +// (non-zero is set). +ObservedState observed_state(const Observation& observation); + +// Runs `game`'s checkpoints on `backend`. Both must outlive it. +template +class StoryEngine{ +public: + StoryEngine(const StoryGame& game, StoryBackend& backend); + StoryEngine(const StoryEngine&) = delete; + StoryEngine& operator=(const StoryEngine&) = delete; + + const StoryActionRegistry& registry() const{ + return m_registry; + } + + // story_steps_hash() of `checkpoint` with this game's actions. + std::string steps_hash(const StoryCheckpoint& checkpoint) const; + + // Runs `checkpoint` from `state`, then checks its postconditions and + // saves if its phase allows a save at `point`. A SAVE step among its + // steps saves only in PER_CHECKPOINT mode. + StoryEngineReport run_checkpoint(const StoryCheckpoint& checkpoint, RunState& state, SavePoint point = SavePoint::RUN_END); + + // `checkpoint`'s postconditions against a fresh observation read by + // every reader of the game; logged as "[Postcondition]" lines. + PostconditionReport check_postconditions(const StoryCheckpoint& checkpoint); + +private: + CheckpointReport run_steps(const StoryCheckpoint& checkpoint, RunState& state); + void save_if_allowed(StoryEngineReport& report, const StoryCheckpoint& checkpoint, SavePoint point); + + // Declared first: m_game's save step reads it. + StorySaveMode m_save_mode = StorySaveMode::NONE; + StoryGame m_game; + StoryBackend& m_backend; + StoryActionRegistry m_registry; + StoryStepRunner m_runner; + PreparedSteps m_prepared; +}; + +// Instantiated once, in Pokemon_StoryEngine.cpp. +extern template class StoryEngine; + + + +} // namespace Pokemon +} // namespace PokemonAutomation +#endif diff --git a/SerialPrograms/Source/Pokemon/AutoStory/Engine/Pokemon_StoryEnginePolicy.cpp b/SerialPrograms/Source/Pokemon/AutoStory/Engine/Pokemon_StoryEnginePolicy.cpp new file mode 100644 index 0000000000..75c9afe4e4 --- /dev/null +++ b/SerialPrograms/Source/Pokemon/AutoStory/Engine/Pokemon_StoryEnginePolicy.cpp @@ -0,0 +1,83 @@ +/* Story Engine Policy + * + * From: https://github.com/PokemonAutomation/ + * + */ + +#include +#include +#include "Common/Cpp/Cryptography/SHA256.h" +#include "Common/Cpp/Json/JsonArray.h" +#include "Pokemon/AutoStory/Data/Pokemon_StoryStepJson.h" +#include "Pokemon/AutoStory/Pokemon_BuiltinStoryActions.h" +#include "Pokemon_StoryEnginePolicy.h" + +namespace PokemonAutomation{ +namespace Pokemon{ + + +namespace{ + + +// `step` as it runs: its action named, its args' fallbacks filled in, no why. +StoryStep as_run(const StoryStep& step, std::span specs){ + StoryStep result = step; + result.why.clear(); + if (const StoryActionSpec* spec = find_story_action(specs, step.kind, step.action)){ + result.action = spec->name; + result.args = with_fallbacks(*spec, std::move(result.args)); + } + return result; +} + +StorySaveMode mode_of(StoryPhase phase){ + switch (phase){ + case StoryPhase::TESTING: + return StorySaveMode::NONE; + case StoryPhase::VERIFICATION: + return StorySaveMode::AFTER_VERIFICATION; + case StoryPhase::REPRODUCTION: + return StorySaveMode::PER_CHECKPOINT; + } + return StorySaveMode::NONE; +} + + +} // namespace + + +std::string story_steps_hash(const StoryCheckpoint& checkpoint, std::span specs){ + JsonArray steps; + for (const StoryStep& step : checkpoint.steps){ + steps.push_back(story_step_json(as_run(step, specs))); + } + const std::string text = JsonValue(std::move(steps)).dump(0); + SHA256 hash; + hash.push(text.data(), text.size()); + hash.finish(); + return "sha256:" + hash.get_hash_hex(); +} + +StorySaveDecision decide_story_save(const StoryCheckpoint& checkpoint, std::string_view steps_hash){ + const StoryCheckpointMetadata& metadata = checkpoint.metadata; + const std::string phase = story_phase_name(metadata.phase); + if (metadata.phase == StoryPhase::TESTING){ + return {.mode = StorySaveMode::NONE, .reason = std::format("[Save] {}: phase testing: save mode none", checkpoint.id)}; + } + if (!metadata.verified || metadata.verified->steps_hash != steps_hash){ + return { + .mode = StorySaveMode::NONE, + .reason = std::format( + "[Save] {}: phase {} but steps_hash mismatch (recorded {}, now {}): treated as testing, save mode none", + checkpoint.id, phase, metadata.verified ? metadata.verified->steps_hash : "none", steps_hash + ), + }; + } + const StorySaveMode mode = mode_of(metadata.phase); + return {.mode = mode, .reason = std::format("[Save] {}: phase {}: save mode {}", checkpoint.id, phase, story_save_mode_name(mode))}; +} + + + +} // namespace Pokemon +} // namespace PokemonAutomation diff --git a/SerialPrograms/Source/Pokemon/AutoStory/Engine/Pokemon_StoryEnginePolicy.h b/SerialPrograms/Source/Pokemon/AutoStory/Engine/Pokemon_StoryEnginePolicy.h new file mode 100644 index 0000000000..46a53d2e3b --- /dev/null +++ b/SerialPrograms/Source/Pokemon/AutoStory/Engine/Pokemon_StoryEnginePolicy.h @@ -0,0 +1,61 @@ +/* Story Engine Policy + * + * From: https://github.com/PokemonAutomation/ + * + * When an engine run of a checkpoint may save, from the checkpoint's + * metadata (autostory/SAVE_POLICY.md on the notes branch): a testing + * checkpoint never saves, a verification one saves once after its runs + * passed, a reproduction one at its end. A checkpoint whose steps no + * longer hash to the ones it was verified with is treated as testing: its + * verification was of other steps. + * + */ + +#ifndef PokemonAutomation_Pokemon_StoryEnginePolicy_H +#define PokemonAutomation_Pokemon_StoryEnginePolicy_H + +#include +#include +#include +#include +#include "Pokemon/AutoStory/Pokemon_StoryCheckpointTypes.h" +#include "Pokemon/AutoStory/Pokemon_StoryPostconditionCheck.h" +#include "Pokemon/AutoStory/Types/Pokemon_StoryActionSpec.h" +#include "Pokemon/AutoStory/Types/Pokemon_StoryCheckpoint.h" +#include "Pokemon/AutoStory/Types/Pokemon_StorySaveMode.h" + +namespace PokemonAutomation{ +namespace Pokemon{ + + +// "sha256:" of `checkpoint`'s steps as their JSON, each with its +// action named and its args' fallbacks filled in from `specs`, and +// without its why: two files that run the same steps hash the same. +std::string story_steps_hash(const StoryCheckpoint& checkpoint, std::span specs); + +// A run's save mode and the log line that says why. +struct StorySaveDecision{ + StorySaveMode mode = StorySaveMode::NONE; + std::string reason = {}; +}; + +// The save mode of a run of `checkpoint`, whose steps hash to `steps_hash`. +StorySaveDecision decide_story_save(const StoryCheckpoint& checkpoint, std::string_view steps_hash); + +// An engine run of one checkpoint. +struct StoryEngineReport{ + // The steps' run. A checkpoint that failed its lint has none. + CheckpointReport run = {}; + StorySaveDecision save = {}; + // PASSED when the steps completed and no postcondition failed. + CheckpointVerdict verdict = CheckpointVerdict::FAILED; + // Checked after steps that completed. + std::optional postconditions = std::nullopt; + bool saved = false; +}; + + + +} // namespace Pokemon +} // namespace PokemonAutomation +#endif diff --git a/SerialPrograms/Source/Pokemon/AutoStory/Engine/Pokemon_StoryEnginePolicy_Tests.cpp b/SerialPrograms/Source/Pokemon/AutoStory/Engine/Pokemon_StoryEnginePolicy_Tests.cpp new file mode 100644 index 0000000000..20f6ea0d6e --- /dev/null +++ b/SerialPrograms/Source/Pokemon/AutoStory/Engine/Pokemon_StoryEnginePolicy_Tests.cpp @@ -0,0 +1,433 @@ +/* Story Engine Policy Tests + * + * From: https://github.com/PokemonAutomation/ + * + * The engine's whole run of a checkpoint on a scripted backend: the save + * mode from the checkpoint's phase and steps hash, the postconditions + * (passed, failed, not checked) and whether it saved. Then the steps hash + * on its own, the metadata in the JSON, and ScreenMachine states that + * match on an observation. + * + */ + +#include +#include +#include +#include +#include +#include "Common/Cpp/Exceptions.h" +#include "Common/Cpp/Json/JsonValue.h" +#include "Common/Cpp/TestRunners/UnitTest.h" +#include "CommonTools/ScreenMachine/ScreenMachine.h" +#include "Pokemon/AutoStory/Data/Pokemon_StoryStepJson.h" +#include "Pokemon_StoryEngine.h" +#include "Pokemon_StoryFakeBackend.h" +#include "Pokemon_StoryEngine_Tests.h" + +namespace PokemonAutomation{ +namespace Pokemon{ + + +namespace{ + + +// FRLG 00.31's end in the shared format, its steps given: beside B3F's +// Rare Candy, facing north, with two Rare Candies. +std::string checkpoint_0031(std::string_view phase, std::string_view steps){ + return std::string(R"({"id": "00.31", "title": "Rocket Hideout", "events": )") + std::string(steps) + R"(, + "metadata": {"phase": ")" + std::string(phase) + R"(", "source": "test", "postconditions": { + "position": {"map": "RocketHideout_B3F", "tiles": [[12, 13]], "facing": "north"}, + "items": [{"item": "RARE_CANDY", "quantity": 2}] + }}})"; +} + +inline constexpr std::string_view TALK_STEPS = R"([{"id": "b3f_rare_candy", "kind": "talk", "why": "the second candy"}])"; +inline constexpr std::string_view SAVE_STEPS = R"([{"id": "b3f_rare_candy", "kind": "talk"}, {"id": "save_here", "kind": "save"}])"; + +// The verification a checkpoint records. +enum class HashRecord{ + MATCHING, // of these steps + STALE, // of other steps + MISSING, // none +}; + +// A look at B3F (12, 13) or wherever `map` is. +Observation end_look(std::string map){ + Observation observation; + observation.events = ScreenEvents{ScreenEvent::CAN_MOVE}; + observation.pose = GridPose{.map = std::move(map), .tiles = {{12, 13}}, .facing = Direction::NORTH}; + return observation; +} + +// A game whose save is recorded as an input, and whose "bag" reader +// reads `candies` Rare Candies (no reader when unset). +StoryGame engine_game(std::optional candies){ + StoryGame game; + game.id = "test"; + game.save = [](StoryBackend& backend){ + backend.wait(Milliseconds(1)); + backend.log("[Test] save"); + return outcome_ok(); + }; + if (candies){ + game.readers.emplace_back("bag", [count = *candies](StoryBackend&, Observation& observation){ + observation.readings["bag.RARE_CANDY"] = count; + }); + } + return game; +} + + + +// One engine run of 00.31 in `phase`, the player ending on `end_map`. +struct EngineInput{ + std::string_view name; + std::string_view phase; + HashRecord hash = HashRecord::MATCHING; + std::string_view steps = TALK_STEPS; + // Where the talk leaves the player; empty: the talk opens no text. + std::string_view end_map = "RocketHideout_B3F"; + std::optional candies = 2; +}; + +// The save mode chosen, the verdict, whether the game saved (each save +// logs "[Test] save") and a line the run logged. +struct EngineExpectation{ + StorySaveMode mode = StorySaveMode::NONE; + CheckpointVerdict verdict = CheckpointVerdict::PASSED; + size_t saves = 0; + std::string_view line = {}; +}; + +struct EngineCase{ + EngineInput input; + EngineExpectation expectation; +}; + +const EngineCase ENGINE_CASES[] = { + {.input = {.name = "testing never saves", .phase = "testing"}, + .expectation = {.mode = StorySaveMode::NONE, .saves = 0, .line = "[Save] 00.31: phase testing: save mode none"}}, + {.input = {.name = "verification saves at the end", .phase = "verification"}, + .expectation = {.mode = StorySaveMode::AFTER_VERIFICATION, .saves = 1, .line = "[Save] 00.31: saved"}}, + {.input = {.name = "reproduction saves", .phase = "reproduction"}, + .expectation = {.mode = StorySaveMode::PER_CHECKPOINT, .saves = 1, .line = "[Save] 00.31: phase reproduction: save mode per_checkpoint"}}, + {.input = {.name = "stale steps_hash is testing", .phase = "verification", .hash = HashRecord::STALE}, + .expectation = {.mode = StorySaveMode::NONE, .saves = 0, .line = "[Save] 00.31: phase verification but steps_hash mismatch (recorded sha256:old, now "}}, + {.input = {.name = "no steps_hash is testing", .phase = "reproduction", .hash = HashRecord::MISSING}, + .expectation = {.mode = StorySaveMode::NONE, .saves = 0, .line = "[Save] 00.31: phase reproduction but steps_hash mismatch (recorded none, now "}}, + {.input = {.name = "B4F false pass fails postconditions", .phase = "verification", .end_map = "RocketHideout_B4F"}, + .expectation = {.mode = StorySaveMode::AFTER_VERIFICATION, .verdict = CheckpointVerdict::FAILED, .saves = 0, + .line = "[Postcondition] 00.31 map: failed: expected RocketHideout_B3F, read RocketHideout_B4F"}}, + {.input = {.name = "unread bag is not checked", .phase = "verification", .candies = std::nullopt}, + .expectation = {.mode = StorySaveMode::AFTER_VERIFICATION, .saves = 1, + .line = "[Postcondition] 00.31: 3 passed, 0 failed, 1 not checked: incomplete"}}, + {.input = {.name = "wrong candy count fails", .phase = "reproduction", .candies = 1}, + .expectation = {.mode = StorySaveMode::PER_CHECKPOINT, .verdict = CheckpointVerdict::FAILED, .saves = 0, + .line = "[Postcondition] 00.31 item RARE_CANDY: failed: expected 2, read 1"}}, + {.input = {.name = "failed run never saves", .phase = "reproduction", .end_map = ""}, + .expectation = {.mode = StorySaveMode::PER_CHECKPOINT, .verdict = CheckpointVerdict::FAILED, .saves = 0, + .line = "[Save] 00.31: run failed: not saved"}}, + {.input = {.name = "save step skipped while verifying", .phase = "verification", .steps = SAVE_STEPS}, + .expectation = {.mode = StorySaveMode::AFTER_VERIFICATION, .saves = 1, .line = "[Save] save step skipped: save mode after_verification"}}, + {.input = {.name = "save step saves in reproduction", .phase = "reproduction", .steps = SAVE_STEPS}, + .expectation = {.mode = StorySaveMode::PER_CHECKPOINT, .saves = 2, .line = "[Step] save_here SAVE/default: ok"}}, +}; + +// A text box, then the overworld on `end_map`; only the overworld when +// `end_map` is empty. +std::vector> engine_looks(std::string_view end_map){ + if (end_map.empty()){ + return {end_look("RocketHideout_B3F")}; + } + Observation text; + text.events = ScreenEvents{ScreenEvent::TEXT_BOX}; + return {std::move(text), end_look(std::string(end_map))}; +} + +std::string check_engine_lines(const EngineCase& test, const FakeStoryBackend& backend){ + size_t saves = 0; + bool found = false; + for (const std::string& line : backend.lines()){ + saves += line == "[Test] save" ? 1 : 0; + found |= line.starts_with(test.expectation.line); + } + if (saves != test.expectation.saves){ + return "expected " + std::to_string(test.expectation.saves) + " saves, got " + std::to_string(saves); + } + return found ? "" : "expected a line starting \"" + std::string(test.expectation.line) + "\""; +} + +std::string check_engine(const EngineCase& test, CancellableScope& scope){ + const StoryGame game = engine_game(test.input.candies); + FakeStoryBackend backend({.looks = engine_looks(test.input.end_map)}, scope); + StoryEngine engine(game, backend); + StoryCheckpoint checkpoint = read_story_checkpoint( + parse_json(checkpoint_0031(test.input.phase, test.input.steps)), test.input.name, engine.registry().specs() + ); + if (test.input.hash != HashRecord::MISSING){ + checkpoint.metadata.verified = StoryVerification{ + .steps_hash = test.input.hash == HashRecord::MATCHING ? engine.steps_hash(checkpoint) : "sha256:old", + .build = "abc", .date = "2026-11-10", .runs = "3/3", + }; + } + RunState state; + const StoryEngineReport report = engine.run_checkpoint(checkpoint, state); + if (report.save.mode != test.expectation.mode){ + return "expected save mode " + story_save_mode_name(test.expectation.mode) + ", got " + story_save_mode_name(report.save.mode); + } + if (report.verdict != test.expectation.verdict){ + return std::string("expected the checkpoint ") + (test.expectation.verdict == CheckpointVerdict::PASSED ? "passed" : "failed"); + } + return check_engine_lines(test, backend); +} + +class StoryEngineSaveTest : public UnitTest{ +public: + explicit StoryEngineSaveTest(EngineCase test) + : UnitTest("Pokemon::StoryEngine save - " + std::string(test.input.name)) + , m_case(std::move(test)) + {} + virtual UnitTestResult run(Logger&, CancellableScope& scope) const override{ + const std::string error = check_engine(m_case, scope); + return error.empty() ? UnitTestResult(true) : UnitTestResult(error); + } +private: + EngineCase m_case; +}; + + + +// Two checkpoints' events, hashed with the built-in actions. +struct HashInput{ + std::string_view name; + std::string_view a; + std::string_view b; +}; + +// Whether they hash the same, and `a`'s hash when pinned: a change to it +// means every recorded verification goes stale. +struct HashExpectation{ + bool same = true; + std::optional hash_a = std::nullopt; +}; + +struct HashCase{ + HashInput input; + HashExpectation expectation; +}; + +inline constexpr std::string_view ROUTE_B3F = R"([{"id": "go", "kind": "route", "args": {"target": {"map": "RocketHideout_B3F", "tiles": [[12, 13]]}}}])"; + +const HashCase HASH_CASES[] = { + {.input = {.name = "pinned", .a = ROUTE_B3F, .b = ROUTE_B3F}, + .expectation = {.same = true, .hash_a = "sha256:PIN"}}, + {.input = {.name = "why is not hashed", .a = R"([{"id": "t", "kind": "talk", "why": "a"}])", .b = R"([{"id": "t", "kind": "talk", "why": "b"}])"}, + .expectation = {.same = true}}, + {.input = {.name = "fallbacks are filled", .a = R"([{"id": "f", "kind": "battle"}])", .b = R"([{"id": "f", "kind": "battle", "args": {"may_lose": false}}])"}, + .expectation = {.same = true}}, + {.input = {.name = "default action is named", .a = ROUTE_B3F, + .b = R"([{"id": "go", "kind": "route", "action": "route", "args": {"target": {"map": "RocketHideout_B3F", "tiles": [[12, 13]]}}}])"}, + .expectation = {.same = true}}, + {.input = {.name = "another target differs", .a = ROUTE_B3F, + .b = R"([{"id": "go", "kind": "route", "args": {"target": {"map": "RocketHideout_B3F", "tiles": [[12, 14]]}}}])"}, + .expectation = {.same = false}}, + {.input = {.name = "another step name differs", .a = R"([{"id": "t", "kind": "talk"}])", .b = R"([{"id": "u", "kind": "talk"}])"}, + .expectation = {.same = false}}, +}; + +std::string hash_of(std::string_view events, std::string_view source){ + const std::string json = std::string(R"({"id": "x", "title": "x", "events": )") + std::string(events) + "}"; + return story_steps_hash(read_story_checkpoint(parse_json(json), source), builtin_story_actions()); +} + +std::string check_hash(const HashCase& test){ + const std::string a = hash_of(test.input.a, test.input.name); + const std::string b = hash_of(test.input.b, test.input.name); + if ((a == b) != test.expectation.same){ + return std::string("expected the hashes ") + (test.expectation.same ? "equal" : "different") + ": " + a + ", " + b; + } + if (test.expectation.hash_a && a != *test.expectation.hash_a){ + return "expected the pinned hash " + std::string(*test.expectation.hash_a) + ", got " + a; + } + return ""; +} + +class StoryStepsHashTest : public UnitTest{ +public: + explicit StoryStepsHashTest(HashCase test) + : UnitTest("Pokemon::StoryEngine steps_hash - " + std::string(test.input.name)) + , m_case(std::move(test)) + {} + virtual UnitTestResult run(Logger&, CancellableScope&) const override{ + const std::string error = check_hash(m_case); + return error.empty() ? UnitTestResult(true) : UnitTestResult(error); + } +private: + HashCase m_case; +}; + + + +// A checkpoint's "metadata", read. +struct MetadataInput{ + std::string_view name; + std::string_view metadata; +}; + +// The error the read throws (contained), or what it read. +struct MetadataExpectation{ + std::string_view error = {}; + StoryPhase phase = StoryPhase::TESTING; + std::string_view steps_hash = {}; + size_t items = 0; +}; + +struct MetadataCase{ + MetadataInput input; + MetadataExpectation expectation; +}; + +const MetadataCase METADATA_CASES[] = { + {.input = {.name = "none is testing", .metadata = ""}, + .expectation = {.phase = StoryPhase::TESTING}}, + {.input = {.name = "verified", .metadata = R"(, "metadata": {"phase": "verification", "verified": {"steps_hash": "sha256:ab", "build": "1", "date": "d", "runs": "3/3"}})"}, + .expectation = {.phase = StoryPhase::VERIFICATION, .steps_hash = "sha256:ab"}}, + {.input = {.name = "postconditions", .metadata = R"(, "metadata": {"phase": "reproduction", "postconditions": {"items": [{"item": "LIFT_KEY", "quantity": 1}]}})"}, + .expectation = {.phase = StoryPhase::REPRODUCTION, .items = 1}}, + {.input = {.name = "unknown phase", .metadata = R"(, "metadata": {"phase": "tested"})"}, + .expectation = {.error = "unknown phase tested"}}, + {.input = {.name = "unknown field", .metadata = R"(, "metadata": {"phase": "testing", "runs": 3})"}, + .expectation = {.error = "unsupported field runs"}}, +}; + +std::string check_metadata(const MetadataCase& test){ + const std::string json = std::string(R"({"id": "x", "title": "x", "events": [])") + std::string(test.input.metadata) + "}"; + StoryCheckpoint checkpoint; + try{ + checkpoint = read_story_checkpoint(parse_json(json), "metadata"); + }catch (const ParseException& error){ + const bool expected = !test.expectation.error.empty() && error.message().find(test.expectation.error) != std::string::npos; + return expected ? "" : "unexpected error: " + error.message(); + } + if (!test.expectation.error.empty()){ + return "expected the error \"" + std::string(test.expectation.error) + "\""; + } + const std::string hash = checkpoint.metadata.verified ? checkpoint.metadata.verified->steps_hash : ""; + if (checkpoint.metadata.phase != test.expectation.phase || hash != test.expectation.steps_hash){ + return "read phase " + story_phase_name(checkpoint.metadata.phase) + ", steps_hash \"" + hash + "\""; + } + if (checkpoint.postconditions.items.size() != test.expectation.items){ + return "read " + std::to_string(checkpoint.postconditions.items.size()) + " items"; + } + return ""; +} + +class StoryMetadataTest : public UnitTest{ +public: + explicit StoryMetadataTest(MetadataCase test) + : UnitTest("Pokemon::StoryEngine metadata - " + std::string(test.input.name)) + , m_case(std::move(test)) + {} + virtual UnitTestResult run(Logger&, CancellableScope&) const override{ + const std::string error = check_metadata(m_case); + return error.empty() ? UnitTestResult(true) : UnitTestResult(error); + } +private: + MetadataCase m_case; +}; + + + +// What a look showed, classified by ScreenMachine states that match on +// observations. +struct ScreenInput{ + std::string_view name; + std::vector events; +}; + +// The state matched; none when no state did. +struct ScreenExpectation{ + std::optional state = std::nullopt; +}; + +struct ScreenCase{ + ScreenInput input; + ScreenExpectation expectation; +}; + +const ScreenCase SCREEN_CASES[] = { + {.input = {.name = "battle first", .events = {ScreenEvent::BATTLE, ScreenEvent::TEXT_BOX}}, .expectation = {.state = "battle"}}, + {.input = {.name = "text", .events = {ScreenEvent::TEXT_BOX}}, .expectation = {.state = "text"}}, + {.input = {.name = "overworld", .events = {ScreenEvent::CAN_MOVE}}, .expectation = {.state = "overworld"}}, + {.input = {.name = "image-only state skipped", .events = {ScreenEvent::FADE_WHITE}}, .expectation = {}}, +}; + +ScreenState observation_state(std::string name, ScreenEvent event){ + ScreenState state; + state.name = std::move(name); + state.matches_observation = [event](const ScreenObservation& observation){ + return observation.events.has(event); + }; + state.max_visits = 10; + return state; +} + +std::string check_screen(const ScreenCase& test){ + std::vector states{ + observation_state("battle", ScreenEvent::BATTLE), + observation_state("text", ScreenEvent::TEXT_BOX), + observation_state("overworld", ScreenEvent::CAN_MOVE), + }; + ScreenState image_only; + image_only.name = "image_only"; + image_only.matches = [](const ImageViewRGB32&){ + return true; + }; + image_only.max_visits = 10; + states.push_back(std::move(image_only)); + ScreenObservation observation; + for (ScreenEvent event : test.input.events){ + observation.events.add(event); + } + const ScreenState* state = match_screen_state(states, observation); + const std::string got = state ? state->name : "none"; + return got == test.expectation.state.value_or("none") ? "" : "matched " + got; +} + +class ScreenObservationTest : public UnitTest{ +public: + explicit ScreenObservationTest(ScreenCase test) + : UnitTest("Pokemon::StoryEngine screen observation - " + std::string(test.input.name)) + , m_case(std::move(test)) + {} + virtual UnitTestResult run(Logger&, CancellableScope&) const override{ + const std::string error = check_screen(m_case); + return error.empty() ? UnitTestResult(true) : UnitTestResult(error); + } +private: + ScreenCase m_case; +}; + + +} // namespace + + +void add_tests_StoryEnginePolicy(UnitTestDatabase& database){ + for (const EngineCase& test : ENGINE_CASES){ + database.add(test); + } + for (const HashCase& test : HASH_CASES){ + database.add(test); + } + for (const MetadataCase& test : METADATA_CASES){ + database.add(test); + } + for (const ScreenCase& test : SCREEN_CASES){ + database.add(test); + } +} + + + +} // namespace Pokemon +} // namespace PokemonAutomation diff --git a/SerialPrograms/Source/Pokemon/AutoStory/Engine/Pokemon_StoryEngine_Tests.cpp b/SerialPrograms/Source/Pokemon/AutoStory/Engine/Pokemon_StoryEngine_Tests.cpp new file mode 100644 index 0000000000..1c6be80ef3 --- /dev/null +++ b/SerialPrograms/Source/Pokemon/AutoStory/Engine/Pokemon_StoryEngine_Tests.cpp @@ -0,0 +1,363 @@ +/* Story Engine Tests + * + * From: https://github.com/PokemonAutomation/ + * + * The engine's lower layers on a scripted backend: the action registry + * (lint and dispatch, a game's action replacing a built-in), the step + * runner (skip_if from flags and readers, the declared end pose, the + * "[Step]" line), and the worked example of a game action, take_warp. + * + */ + +#include +#include +#include +#include +#include +#include +#include "Common/Cpp/Json/JsonValue.h" +#include "Common/Cpp/TestRunners/UnitTest.h" +#include "Pokemon/AutoStory/Data/Pokemon_StoryStepJson.h" +#include "Pokemon/AutoStory/Pokemon_BuiltinStoryActions.h" +#include "Pokemon/AutoStory/Pokemon_StoryStepExecutor.h" +#include "Pokemon_StoryActionRegistry.h" +#include "Pokemon_StoryFakeBackend.h" +#include "Pokemon_StoryStepRunner.h" +#include "Pokemon_StoryEngine_Tests.h" + +namespace PokemonAutomation{ +namespace Pokemon{ + + +namespace{ + +using namespace std::chrono_literals; + + +// One look: `events`, standing on `pose` if given. +Observation look(std::initializer_list events, std::optional pose = std::nullopt){ + Observation observation; + observation.events = ScreenEvents(events); + observation.pose = std::move(pose); + return observation; +} + +GridPose on_map(std::string map){ + return GridPose{.map = std::move(map), .tiles = {}, .facing = std::nullopt}; +} + +std::string joined(const std::vector& items){ + std::string text; + for (const std::string& item : items){ + text += (text.empty() ? "" : ", ") + item; + } + return text; +} + +bool has_line(const FakeStoryBackend& backend, std::string_view line){ + for (const std::string& each : backend.lines()){ + if (each == line){ + return true; + } + } + return false; +} + + +// The worked example of a game's own action: a door or stairs warp. A +// warp is a fade out, then a fade in on the target's map. No fade is not +// "arrived": FRLG 00.31 (console B, 2026-11-10) took it so and saved on +// the wrong floor. +Outcome take_warp(StoryBackend& backend, RunState&, const StoryActionArgs& args){ + const Direction direction = story_arg(args, "direction"); + const GridPose& to = story_arg(args, "to"); + backend.hold(direction, 400ms, StoryPace::WALK); + bool faded = false; + for (size_t c = 0; c < 40; c++){ + const Observation now = backend.observe(); + if (now.events.has(ScreenEvent::FADE_BLACK)){ + faded = true; + }else if (faded && now.pose && now.pose->map == to.map){ + return outcome_ok(pose_of(*now.pose)); + } + backend.wait(100ms); + } + return outcome_failed(faded ? "warp_wrong_map" : "warp_no_fade"); +} + +// A game with take_warp, a route of its own (one hold north) and a +// reader "door_open" that reads `door_open`. +StoryGame test_game(std::optional door_open = std::nullopt){ + StoryGame game; + game.id = "test"; + game.actions.push_back({ + .spec = {.kind = StoryStepKind::GAME, .name = "take_warp", .args = { + {.key = "direction", .type = StoryArgType::DIRECTION, .required = true, .fallback = std::nullopt, .why = "into the door"}, + {.key = "to", .type = StoryArgType::GRID_POSE, .required = true, .fallback = std::nullopt, .why = "the warp's end"}, + }}, + .handler = &take_warp, + }); + game.actions.push_back({ + .spec = *find_story_action(builtin_story_actions(), StoryStepKind::ROUTE, "route"), + .handler = [](StoryBackend& backend, RunState&, const StoryActionArgs&){ + backend.hold(Direction::NORTH, 100ms, StoryPace::RUN); + return outcome_ok(); + }, + }); + if (door_open){ + game.readers.emplace_back("door_open", [value = *door_open](StoryBackend&, Observation& observation){ + observation.readings["door_open"] = value; + }); + } + return game; +} + +StoryStep make_step(StoryStepKind kind, std::string action, StoryActionArgs args){ + StoryStep step; + step.kind = kind; + step.name = "s"; + step.action = std::move(action); + step.args = std::move(args); + return step; +} + + + +// A step checked and, when it lints clean, dispatched on a backend that +// shows talk text once, then the overworld. +struct RegistryInput{ + std::string_view name; + StoryStep step; +}; + +// The lint errors joined by "; ", then (for a clean step) the failure and +// the inputs sent. +struct RegistryExpectation{ + std::string_view lint = {}; + std::string_view failure = {}; + std::string_view inputs = {}; +}; + +struct RegistryCase{ + RegistryInput input; + RegistryExpectation expectation; +}; + +const RegistryCase REGISTRY_CASES[] = { + {.input = {.name = "legs tap each tile", .step = make_step(StoryStepKind::LEGS, "", {{"legs", std::vector{{Direction::NORTH, 2}, {Direction::EAST, 1}}}})}, + .expectation = {.inputs = "tap north, tap north, tap east"}}, + {.input = {.name = "legs empty", .step = make_step(StoryStepKind::LEGS, "", {{"legs", std::vector{}}})}, + .expectation = {.lint = "no legs"}}, + {.input = {.name = "face without direction", .step = make_step(StoryStepKind::STEP, "face", {})}, + .expectation = {.lint = "missing argument \"direction\" (the way to step or face)"}}, + {.input = {.name = "unknown game action", .step = make_step(StoryStepKind::GAME, "take_wrap", {})}, + .expectation = {.lint = "unknown action \"take_wrap\" for GAME"}}, + {.input = {.name = "talk", .step = make_step(StoryStepKind::TALK, "", {})}, + .expectation = {.inputs = "press A, press A"}}, + {.input = {.name = "answer no", .step = make_step(StoryStepKind::ANSWER, "", {{"yes", false}})}, + .expectation = {.inputs = "press B"}}, + {.input = {.name = "battle", .step = make_step(StoryStepKind::BATTLE, "", {})}, + .expectation = {.inputs = "battle"}}, + {.input = {.name = "ready needs the game", .step = make_step(StoryStepKind::READY, "", {{"target", on_map("CeruleanCity")}})}, + .expectation = {.failure = "unsupported_step"}}, + {.input = {.name = "game route replaces the built-in", .step = make_step(StoryStepKind::ROUTE, "", {{"target", on_map("Route4")}})}, + .expectation = {.inputs = "hold north 100ms run"}}, + {.input = {.name = "save without the game's save", .step = make_step(StoryStepKind::SAVE, "", {})}, + .expectation = {.failure = "unsupported_step"}}, +}; + +std::string check_registry(const RegistryCase& test, CancellableScope& scope){ + const StoryGame game = test_game(); + const StoryActionRegistry registry(game); + std::vector lint = registry.check(test.input.step); + if (joined(lint) != test.expectation.lint){ + return "expected lint \"" + std::string(test.expectation.lint) + "\", got \"" + joined(lint) + "\""; + } + if (!lint.empty()){ + return ""; + } + FakeStoryBackend backend({.looks = {look({ScreenEvent::TEXT_BOX}), look({ScreenEvent::TEXT_BOX}), look({ScreenEvent::CAN_MOVE})}}, scope); + RunState state; + const Outcome outcome = registry.dispatch(backend, state, test.input.step); + if (outcome.failure != test.expectation.failure){ + return "expected failure \"" + std::string(test.expectation.failure) + "\", got \"" + to_string(outcome) + "\""; + } + if (joined(backend.inputs()) != test.expectation.inputs){ + return "expected inputs \"" + std::string(test.expectation.inputs) + "\", got \"" + joined(backend.inputs()) + "\""; + } + return ""; +} + +class StoryActionRegistryTest : public UnitTest{ +public: + explicit StoryActionRegistryTest(RegistryCase test) + : UnitTest("Pokemon::StoryEngine registry - " + std::string(test.input.name)) + , m_case(std::move(test)) + {} + virtual UnitTestResult run(Logger&, CancellableScope& scope) const override{ + const std::string error = check_registry(m_case, scope); + return error.empty() ? UnitTestResult(true) : UnitTestResult(error); + } +private: + RegistryCase m_case; +}; + + + +// One step, read from JSON, run by the step runner on a backend that +// shows the overworld, with `flags` set and the "door_open" reader +// reading `door_open`. +struct RunnerInput{ + std::string_view name; + std::string_view step; + std::vector flags = {}; + std::optional door_open = std::nullopt; +}; + +// The failure, a line the run logged and the map of the outcome's pose. +struct RunnerExpectation{ + std::string_view failure = {}; + std::string_view line = {}; + std::string_view pose_map = {}; +}; + +struct RunnerCase{ + RunnerInput input; + RunnerExpectation expectation; +}; + +const RunnerCase RUNNER_CASES[] = { + {.input = {.name = "skip_if a flag", .step = R"({"id": "s", "kind": "talk", "skip_if": ["got_candy"]})", .flags = {"got_candy"}}, + .expectation = {.line = "[Step] s TALK/default: skipped"}}, + {.input = {.name = "skip_if a reader", .step = R"({"id": "s", "kind": "talk", "skip_if": ["door_open"]})", .door_open = 1}, + .expectation = {.line = "[Step] s TALK/default: skipped"}}, + {.input = {.name = "skip_if a reader that says no", .step = R"({"id": "s", "kind": "scene", "skip_if": ["door_open"]})", .door_open = 0}, + .expectation = {.line = "[Step] s MASH/default: ok"}}, + {.input = {.name = "skip_if nobody answers", .step = R"({"id": "s", "kind": "scene", "skip_if": ["door_open"]})"}, + .expectation = {.line = "[Step] s MASH/default: ok"}}, + {.input = {.name = "declared end pose", .step = R"({"id": "s", "kind": "scene", "declared_after": {"map": "Route1", "tiles": [[1, 2]]}})"}, + .expectation = {.line = "[Step] s MASH/default: ok", .pose_map = "Route1"}}, + {.input = {.name = "talk to nobody fails", .step = R"({"id": "s", "kind": "talk"})"}, + .expectation = {.failure = "talk_no_text", .line = "[Step] s TALK/default: failed: talk_no_text: A opened no text box"}}, +}; + +std::string check_runner(const RunnerCase& test, CancellableScope& scope){ + const StoryGame game = test_game(test.input.door_open); + const StoryActionRegistry registry(game); + FakeStoryBackend backend({.looks = {look({ScreenEvent::CAN_MOVE})}}, scope); + StoryStepRunner runner(registry, backend); + RunState state; + state.flags.insert(test.input.flags.begin(), test.input.flags.end()); + const StoryStep step = read_story_step(parse_json(std::string(test.input.step)), test.input.name, registry.specs()); + const Outcome outcome = runner.run(state, step); + if (outcome.failure != test.expectation.failure){ + return "expected failure \"" + std::string(test.expectation.failure) + "\", got \"" + to_string(outcome) + "\""; + } + if (!has_line(backend, test.expectation.line)){ + return "expected the line \"" + std::string(test.expectation.line) + "\", logged: " + joined(backend.lines()); + } + const std::string map = outcome.pose ? outcome.pose->map : ""; + if (map != test.expectation.pose_map){ + return "expected the pose on \"" + std::string(test.expectation.pose_map) + "\", got \"" + map + "\""; + } + return ""; +} + +class StoryStepRunnerTest : public UnitTest{ +public: + explicit StoryStepRunnerTest(RunnerCase test) + : UnitTest("Pokemon::StoryEngine runner - " + std::string(test.input.name)) + , m_case(std::move(test)) + {} + virtual UnitTestResult run(Logger&, CancellableScope& scope) const override{ + const std::string error = check_runner(m_case, scope); + return error.empty() ? UnitTestResult(true) : UnitTestResult(error); + } +private: + RunnerCase m_case; +}; + + + +// take_warp north to B3F, from B4F, on a scripted game. +struct WarpInput{ + std::string_view name; + std::vector> looks; +}; + +// How take_warp ended: "" for arrived. +struct WarpExpectation{ + std::string_view failure = {}; +}; + +struct WarpCase{ + WarpInput input; + WarpExpectation expectation; +}; + +const WarpCase WARP_CASES[] = { + {.input = {.name = "fade then B3F", .looks = { + look({}, on_map("RocketHideout_B4F")), look({ScreenEvent::FADE_BLACK}), look({ScreenEvent::CAN_MOVE}, on_map("RocketHideout_B3F")), + }}, .expectation = {}}, + // The screen darkens at the stairs but no fade starts and the map + // stays B4F: the old wait took this for arrived (00.31's false pass). + {.input = {.name = "black_without_warp", .looks = {look({ScreenEvent::STILL}, on_map("RocketHideout_B4F"))}}, + .expectation = {.failure = "warp_no_fade"}}, + {.input = {.name = "fade back to B4F", .looks = {look({ScreenEvent::FADE_BLACK}), look({ScreenEvent::CAN_MOVE}, on_map("RocketHideout_B4F"))}}, + .expectation = {.failure = "warp_wrong_map"}}, +}; + +std::string check_warp(const WarpCase& test, CancellableScope& scope){ + const StoryGame game = test_game(); + const StoryActionRegistry registry(game); + FakeStoryBackend backend({.looks = test.input.looks}, scope); + StoryStepRunner runner(registry, backend); + RunState state; + const StoryStep step = make_step(StoryStepKind::GAME, "take_warp", { + {"direction", Direction::NORTH}, + {"to", on_map("RocketHideout_B3F")}, + }); + const Outcome outcome = runner.run(state, step); + if (outcome.failure != test.expectation.failure){ + return "expected \"" + std::string(test.expectation.failure) + "\", got \"" + to_string(outcome) + "\""; + } + if (outcome.succeeded() && (!outcome.pose || outcome.pose->map != "RocketHideout_B3F")){ + return "expected the pose on RocketHideout_B3F"; + } + return ""; +} + +class StoryTakeWarpTest : public UnitTest{ +public: + explicit StoryTakeWarpTest(WarpCase test) + : UnitTest("Pokemon::StoryEngine take_warp - " + std::string(test.input.name)) + , m_case(std::move(test)) + {} + virtual UnitTestResult run(Logger&, CancellableScope& scope) const override{ + const std::string error = check_warp(m_case, scope); + return error.empty() ? UnitTestResult(true) : UnitTestResult(error); + } +private: + WarpCase m_case; +}; + + +} // namespace + + +void add_tests_StoryEngine(UnitTestDatabase& database){ + for (const RegistryCase& test : REGISTRY_CASES){ + database.add(test); + } + for (const RunnerCase& test : RUNNER_CASES){ + database.add(test); + } + for (const WarpCase& test : WARP_CASES){ + database.add(test); + } +} + + + +} // namespace Pokemon +} // namespace PokemonAutomation diff --git a/SerialPrograms/Source/Pokemon/AutoStory/Engine/Pokemon_StoryEngine_Tests.h b/SerialPrograms/Source/Pokemon/AutoStory/Engine/Pokemon_StoryEngine_Tests.h new file mode 100644 index 0000000000..e7d4aaeef2 --- /dev/null +++ b/SerialPrograms/Source/Pokemon/AutoStory/Engine/Pokemon_StoryEngine_Tests.h @@ -0,0 +1,28 @@ +/* Story Engine Tests + * + * From: https://github.com/PokemonAutomation/ + * + * The unit tests of the story engine (Pokemon/AutoStory/Engine). + * + */ + +#ifndef PokemonAutomation_Pokemon_StoryEngine_Tests_H +#define PokemonAutomation_Pokemon_StoryEngine_Tests_H + +#include "Common/Cpp/TestRunners/UnitTestDatabase.h" + +namespace PokemonAutomation{ +namespace Pokemon{ + + +// Registers unit tests for the action registry, the step runner and the take_warp example. +void add_tests_StoryEngine(UnitTestDatabase& database); + +// Registers unit tests for the engine's save decision, postconditions, steps hash, metadata and observation screens. +void add_tests_StoryEnginePolicy(UnitTestDatabase& database); + + + +} // namespace Pokemon +} // namespace PokemonAutomation +#endif diff --git a/SerialPrograms/Source/Pokemon/AutoStory/Engine/Pokemon_StoryFakeBackend.cpp b/SerialPrograms/Source/Pokemon/AutoStory/Engine/Pokemon_StoryFakeBackend.cpp new file mode 100644 index 0000000000..f8c7c1d82e --- /dev/null +++ b/SerialPrograms/Source/Pokemon/AutoStory/Engine/Pokemon_StoryFakeBackend.cpp @@ -0,0 +1,86 @@ +/* Story Fake Backend + * + * From: https://github.com/PokemonAutomation/ + * + */ + +#include +#include +#include "Pokemon_StoryFakeBackend.h" + +namespace PokemonAutomation{ +namespace Pokemon{ + + +namespace{ + + +std::string button_name(NintendoSwitch::Button button){ + switch (button){ + case NintendoSwitch::BUTTON_A: + return "A"; + case NintendoSwitch::BUTTON_B: + return "B"; + case NintendoSwitch::BUTTON_X: + return "X"; + case NintendoSwitch::BUTTON_Y: + return "Y"; + case NintendoSwitch::BUTTON_PLUS: + return "PLUS"; + default: + return std::format("{}", (uint32_t)button); + } +} + + +} // namespace + + +FakeStoryBackend::FakeStoryBackend(FakeStoryScript script, CancellableScope& scope) + : m_script(std::move(script)) + , m_scope(scope) +{} + +void FakeStoryBackend::press(NintendoSwitch::Button button, Milliseconds, Milliseconds){ + m_inputs.push_back("press " + button_name(button)); +} + +void FakeStoryBackend::tap(Direction direction){ + m_inputs.push_back("tap " + direction_name(direction)); +} + +void FakeStoryBackend::hold(Direction direction, Milliseconds duration, StoryPace pace){ + m_inputs.push_back(std::format( + "hold {} {}ms {}", direction_name(direction), duration.count(), pace == StoryPace::RUN ? "run" : "walk" + )); +} + +void FakeStoryBackend::wait(Milliseconds duration){ + m_inputs.push_back(std::format("wait {}ms", duration.count())); +} + +Observation FakeStoryBackend::observe(){ + if (m_script.looks.empty()){ + return {}; + } + const size_t look = m_next_look < m_script.looks.size() ? m_next_look++ : m_script.looks.size() - 1; + return m_script.looks[look]; +} + +Outcome FakeStoryBackend::battle(const StoryActionArgs&){ + m_inputs.push_back("battle"); + return m_script.battle; +} + +void FakeStoryBackend::log(std::string_view line){ + m_lines.emplace_back(line); +} + +CancellableScope& FakeStoryBackend::scope(){ + return m_scope; +} + + + +} // namespace Pokemon +} // namespace PokemonAutomation diff --git a/SerialPrograms/Source/Pokemon/AutoStory/Engine/Pokemon_StoryFakeBackend.h b/SerialPrograms/Source/Pokemon/AutoStory/Engine/Pokemon_StoryFakeBackend.h new file mode 100644 index 0000000000..c2825e7d11 --- /dev/null +++ b/SerialPrograms/Source/Pokemon/AutoStory/Engine/Pokemon_StoryFakeBackend.h @@ -0,0 +1,73 @@ +/* Story Fake Backend + * + * From: https://github.com/PokemonAutomation/ + * + * A scripted game for engine tests, with no console and no model: each + * observe() returns the script's next look (the last one repeats), every + * input and log line is recorded, and a battle ends as scripted. A fault + * is a script: "black_without_warp" is a door that dims the screen and + * never warps. + * + */ + +#ifndef PokemonAutomation_Pokemon_StoryFakeBackend_H +#define PokemonAutomation_Pokemon_StoryFakeBackend_H + +#include +#include +#include +#include +#include "Pokemon/AutoStory/Types/Pokemon_GridPose.h" +#include "Pokemon_StoryBackend.h" + +namespace PokemonAutomation{ +namespace Pokemon{ + + +// What a FakeStoryBackend shows and does. +struct FakeStoryScript{ + // observe()'s answers in order; the last repeats. None: an empty look. + std::vector> looks = {}; + // How each battle ends. + Outcome battle = outcome_ok(); +}; + +// The backend of the engine's unit tests and of executor-level sim tests +// that only need a script. +// code-health: allow public_methods -- the eight backend calls it fakes plus the two recordings tests read; nothing to split +class FakeStoryBackend : public StoryBackend{ +public: + FakeStoryBackend(FakeStoryScript script, CancellableScope& scope); + + // Each input, in order: "press A", "tap north", "hold east 400ms walk", + // "wait 100ms", "battle". + const std::vector& inputs() const{ + return m_inputs; + } + // Each log line, in order. + const std::vector& lines() const{ + return m_lines; + } + + virtual void press(NintendoSwitch::Button button, Milliseconds hold, Milliseconds release) override; + virtual void tap(Direction direction) override; + virtual void hold(Direction direction, Milliseconds duration, StoryPace pace) override; + virtual void wait(Milliseconds duration) override; + virtual Observation observe() override; + virtual Outcome battle(const StoryActionArgs& args) override; + virtual void log(std::string_view line) override; + virtual CancellableScope& scope() override; + +private: + FakeStoryScript m_script; + CancellableScope& m_scope; + size_t m_next_look = 0; + std::vector m_inputs; + std::vector m_lines; +}; + + + +} // namespace Pokemon +} // namespace PokemonAutomation +#endif diff --git a/SerialPrograms/Source/Pokemon/AutoStory/Engine/Pokemon_StoryGame.h b/SerialPrograms/Source/Pokemon/AutoStory/Engine/Pokemon_StoryGame.h new file mode 100644 index 0000000000..0a1e50d1a8 --- /dev/null +++ b/SerialPrograms/Source/Pokemon/AutoStory/Engine/Pokemon_StoryGame.h @@ -0,0 +1,76 @@ +/* Story Game + * + * From: https://github.com/PokemonAutomation/ + * + * What a game hands the story engine: its actions, its readers and its + * save, as data plus functions. No subclassing. The engine registers the + * shared built-in actions first (Pokemon_StoryBuiltinActions.h); a game's + * action with the same kind and name replaces the built-in one. + * + */ + +#ifndef PokemonAutomation_Pokemon_StoryGame_H +#define PokemonAutomation_Pokemon_StoryGame_H + +#include +#include +#include +#include +#include "Pokemon/AutoStory/Pokemon_StoryCheckpointTypes.h" +#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_StoryCheckpoint.h" +#include "Pokemon_StoryBackend.h" + +namespace PokemonAutomation{ +namespace Pokemon{ + + +// An action's code: reads its args (fallbacks already filled in) and +// drives the backend. A succeeded action that knows where it left the +// player returns that pose in its Outcome. +template +using StoryActionHandler = std::function& backend, RunState& state, const StoryActionArgs& args)>; + +// Fills an observation's pose or readings from what the backend saw: a +// console reads the frame (OCR, templates), a simulation its model. A +// reader whose name is a step's skip_if condition answers it: the +// condition holds when the reader sets a non-zero reading of that name. +template +using StoryReader = std::function& backend, Observation& observation)>; + +// An action: its spec (kind, name, args) and its code. +template +struct StoryAction{ + StoryActionSpec spec = {}; + StoryActionHandler handler = {}; +}; + +// A game, for the engine. +template +struct StoryGame{ + // "frlg", "bdsp", "plza". + std::string id = {}; + // The game's own actions, and its replacements of built-in ones. + std::vector> actions = {}; + // By name: "pose", "bag", "facing", or a skip_if condition. + std::vector>> readers = {}; + // The game's save (the menu, or a wait for an autosave). The engine + // decides whether to call it (Pokemon_StoryEnginePolicy.h). + std::function& backend)> save = {}; + // Back to the last save. + std::function& backend)> reload = {}; + // Called as each attempt at a checkpoint starts, to reset what the game + // keeps per attempt (trainers who can see us again). Optional. + std::function begin_attempt = {}; + // What can stop a step part-way (a wild battle, a trainer who saw + // us), built for each checkpoint run. Optional. + std::function(StoryBackend& backend)> interrupts = {}; +}; + + + +} // namespace Pokemon +} // namespace PokemonAutomation +#endif diff --git a/SerialPrograms/Source/Pokemon/AutoStory/Engine/Pokemon_StoryPoseConcept.cpp b/SerialPrograms/Source/Pokemon/AutoStory/Engine/Pokemon_StoryPoseConcept.cpp new file mode 100644 index 0000000000..794ec9d6b8 --- /dev/null +++ b/SerialPrograms/Source/Pokemon/AutoStory/Engine/Pokemon_StoryPoseConcept.cpp @@ -0,0 +1,44 @@ +/* Story Pose Concept + * + * From: https://github.com/PokemonAutomation/ + * + */ + +#include +#include +#include "Pokemon_StoryPoseConcept.h" + +namespace PokemonAutomation{ +namespace Pokemon{ + + +bool pose_matches(const GridPose& actual, const GridPose& target){ + if (actual.map != target.map){ + return false; + } + if (target.facing && actual.facing != target.facing){ + return false; + } + if (target.tiles.empty()){ + return true; + } + return !actual.tiles.empty() && std::all_of(actual.tiles.begin(), actual.tiles.end(), [&](const TilePos& tile){ + return std::find(target.tiles.begin(), target.tiles.end(), tile) != target.tiles.end(); + }); +} + +std::string pose_text(const GridPose& pose){ + std::string text = pose.map; + for (const TilePos& tile : pose.tiles){ + text += " " + to_string(tile); + } + if (pose.facing){ + text += " facing " + direction_name(*pose.facing); + } + return text; +} + + + +} // namespace Pokemon +} // namespace PokemonAutomation diff --git a/SerialPrograms/Source/Pokemon/AutoStory/Engine/Pokemon_StoryPoseConcept.h b/SerialPrograms/Source/Pokemon/AutoStory/Engine/Pokemon_StoryPoseConcept.h new file mode 100644 index 0000000000..622967cc77 --- /dev/null +++ b/SerialPrograms/Source/Pokemon/AutoStory/Engine/Pokemon_StoryPoseConcept.h @@ -0,0 +1,43 @@ +/* Story Pose Concept + * + * From: https://github.com/PokemonAutomation/ + * + * What the story engine needs of a game's pose type: whether a pose read + * off the game is a target, and a line of text for the log. The tile + * games (FRLG, BDSP) use GridPose; a game that moves freely brings its + * own type (PLZA: a zone until it has a position reader). + * + */ + +#ifndef PokemonAutomation_Pokemon_StoryPoseConcept_H +#define PokemonAutomation_Pokemon_StoryPoseConcept_H + +#include +#include +#include "Pokemon/AutoStory/Types/Pokemon_GridPose.h" + +namespace PokemonAutomation{ +namespace Pokemon{ + + +// A pose the engine can carry: pose_matches(actual, target) and +// pose_text(pose), found by argument-dependent lookup. +template +concept StoryPose = std::copyable && requires(const PoseType& actual, const PoseType& target){ + { pose_matches(actual, target) } -> std::convertible_to; + { pose_text(actual) } -> std::convertible_to; +}; + +// Whether `actual` is on `target`'s map, each of its tiles is one of +// `target`'s (any tile when `target` names none), and it faces `target`'s +// facing when `target` has one. +bool pose_matches(const GridPose& actual, const GridPose& target); + +// "PalletTown (3, 4) facing north". +std::string pose_text(const GridPose& pose); + + + +} // namespace Pokemon +} // namespace PokemonAutomation +#endif diff --git a/SerialPrograms/Source/Pokemon/AutoStory/Engine/Pokemon_StoryStepRunner.cpp b/SerialPrograms/Source/Pokemon/AutoStory/Engine/Pokemon_StoryStepRunner.cpp new file mode 100644 index 0000000000..a2297934df --- /dev/null +++ b/SerialPrograms/Source/Pokemon/AutoStory/Engine/Pokemon_StoryStepRunner.cpp @@ -0,0 +1,84 @@ +/* Story Step Runner + * + * From: https://github.com/PokemonAutomation/ + * + */ + +#include +#include +#include "Pokemon/AutoStory/Pokemon_StoryStepExecutor.h" +#include "Pokemon_StoryStepRunner.h" + +namespace PokemonAutomation{ +namespace Pokemon{ + + +namespace{ + + +// "route/route" or "game_action/take_warp": the step's kind and action. +inline std::string step_label(const StoryStep& step){ + return std::format("{}/{}", story_step_kind_name(step.kind), step.action.empty() ? "default" : step.action); +} + + +} // namespace + + +template +StoryStepRunner::StoryStepRunner(const StoryActionRegistry& registry, StoryBackend& backend) + : m_registry(registry) + , m_backend(backend) +{} + +template +Outcome StoryStepRunner::run(RunState& state, const StoryStep& step){ + bool skip = !step.skip_if.empty(); + for (const std::string& condition : step.skip_if){ + skip = skip && holds(condition, state); + } + if (skip){ + m_backend.log(std::format("[Step] {} {}: skipped", step.name, step_label(step))); + return outcome_unchanged(); + } + return act(state, step); +} + +template +Outcome StoryStepRunner::act(RunState& state, const StoryStep& step){ + m_backend.scope().throw_if_cancelled(); + Outcome outcome = m_registry.dispatch(m_backend, state, step); + if (outcome.succeeded() && !outcome.pose && step.pose_after){ + outcome.pose = pose_of(*step.pose_after); + } + m_backend.log(std::format( + "[Step] {} {}: {}", step.name, step_label(step), + outcome.succeeded() ? "ok" : "failed: " + to_string(outcome) + )); + return outcome; +} + +template +bool StoryStepRunner::holds(std::string_view condition, RunState& state){ + if (state.flags.contains(std::string(condition))){ + return true; + } + for (const auto& [name, reader] : m_registry.game().readers){ + if (name != condition || !reader){ + continue; + } + Observation observation = m_backend.observe(); + reader(m_backend, observation); + const auto reading = observation.readings.find(condition); + return reading != observation.readings.end() && reading->second != 0; + } + return false; +} + + +template class StoryStepRunner; + + + +} // namespace Pokemon +} // namespace PokemonAutomation diff --git a/SerialPrograms/Source/Pokemon/AutoStory/Engine/Pokemon_StoryStepRunner.h b/SerialPrograms/Source/Pokemon/AutoStory/Engine/Pokemon_StoryStepRunner.h new file mode 100644 index 0000000000..88aecea47a --- /dev/null +++ b/SerialPrograms/Source/Pokemon/AutoStory/Engine/Pokemon_StoryStepRunner.h @@ -0,0 +1,58 @@ +/* Story Step Runner + * + * From: https://github.com/PokemonAutomation/ + * + * Runs one story step on a backend: skips it when its skip_if conditions + * hold, runs its action through the registry, writes its declared end + * pose into the outcome, and logs a "[Step]" line. The one step executor + * of every game, on a console or in a simulation; it replaces + * StoryStepExecutor and the games' own executors. + * + */ + +#ifndef PokemonAutomation_Pokemon_StoryStepRunner_H +#define PokemonAutomation_Pokemon_StoryStepRunner_H + +#include +#include "Pokemon/AutoStory/Types/Pokemon_GridPose.h" +#include "Pokemon/AutoStory/Types/Pokemon_StoryStep.h" +#include "Pokemon_StoryActionRegistry.h" + +namespace PokemonAutomation{ +namespace Pokemon{ + + +// Runs steps with `registry`'s actions on `backend`. Both must outlive it. +template +class StoryStepRunner{ +public: + StoryStepRunner(const StoryActionRegistry& registry, StoryBackend& backend); + StoryStepRunner(const StoryStepRunner&) = delete; + StoryStepRunner& operator=(const StoryStepRunner&) = delete; + + // `step`, unless all its skip_if conditions hold (and it has some): + // then it changes nothing and says so. + Outcome run(RunState& state, const StoryStep& step); + + // `step`'s action without the skip_if check, for a caller that checks + // it itself (the event layer): dispatch, then the declared end pose + // when the action gave none, then the "[Step]" line. + Outcome act(RunState& state, const StoryStep& step); + + // Whether `condition` holds: a flag of the run, or else a non-zero + // reading from the game's reader of that name on a fresh observation. + bool holds(std::string_view condition, RunState& state); + +private: + const StoryActionRegistry& m_registry; + StoryBackend& m_backend; +}; + +// Instantiated once, in Pokemon_StoryStepRunner.cpp. +extern template class StoryStepRunner; + + + +} // namespace Pokemon +} // namespace PokemonAutomation +#endif diff --git a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_AutoStory_Tests.h b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_AutoStory_Tests.h index 5fa2aad20e..36148caba5 100644 --- a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_AutoStory_Tests.h +++ b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_AutoStory_Tests.h @@ -10,6 +10,7 @@ #define PokemonAutomation_Pokemon_AutoStory_Tests_H #include "Common/Cpp/TestRunners/UnitTestDatabase.h" +#include "Engine/Pokemon_StoryEngine_Tests.h" namespace PokemonAutomation{ namespace Pokemon{ @@ -38,6 +39,8 @@ inline void add_tests_AutoStory(UnitTestDatabase& database){ add_tests_StoryActionArg(database); add_tests_AuthoredCheckpointJson(database); add_tests_StorySavePolicy(database); + add_tests_StoryEngine(database); + add_tests_StoryEnginePolicy(database); } diff --git a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StorySavePolicy_Tests.cpp b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StorySavePolicy_Tests.cpp index b587854125..9bf0b511de 100644 --- a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StorySavePolicy_Tests.cpp +++ b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StorySavePolicy_Tests.cpp @@ -284,10 +284,10 @@ inline constexpr std::string_view CHECKPOINT_0031 = R"({ {"id": "beside_b3f_rare_candy", "kind": "route", "args": {"target": {"map": "RocketHideout_B3F", "tiles": [[12, 13]], "facing": "north"}}}, {"id": "b3f_rare_candy", "kind": "talk"} ], - "postconditions": { + "metadata": {"phase": "testing", "postconditions": { "position": {"map": "RocketHideout_B3F", "tiles": [[12, 13]], "facing": "north"}, "items": [{"item": "LIFT_KEY", "quantity": 1}, {"item": "RARE_CANDY", "quantity": 2}] - } + }} })"; StoryCheckpoint checkpoint_0031(){ diff --git a/SerialPrograms/Source/Pokemon/AutoStory/Types/Pokemon_StoryCheckpoint.h b/SerialPrograms/Source/Pokemon/AutoStory/Types/Pokemon_StoryCheckpoint.h index 1a4719017c..b080dbfe77 100644 --- a/SerialPrograms/Source/Pokemon/AutoStory/Types/Pokemon_StoryCheckpoint.h +++ b/SerialPrograms/Source/Pokemon/AutoStory/Types/Pokemon_StoryCheckpoint.h @@ -15,6 +15,7 @@ #include #include #include "Pokemon_GridPose.h" +#include "Pokemon_StoryCheckpointMetadata.h" #include "Pokemon_StoryPostconditions.h" #include "Pokemon_StoryStep.h" @@ -30,7 +31,11 @@ struct StoryCheckpoint{ std::optional start; std::vector steps; // What must hold when it is done; checked on its own after a run. + // JSON: "metadata": {"postconditions": ...}. StoryPostconditions postconditions; + // Its phase and verification (JSON "metadata"), which decide when a + // run of it may save. + StoryCheckpointMetadata metadata = {}; }; diff --git a/SerialPrograms/Source/Pokemon/AutoStory/Types/Pokemon_StoryCheckpointMetadata.cpp b/SerialPrograms/Source/Pokemon/AutoStory/Types/Pokemon_StoryCheckpointMetadata.cpp new file mode 100644 index 0000000000..fb6eac85fd --- /dev/null +++ b/SerialPrograms/Source/Pokemon/AutoStory/Types/Pokemon_StoryCheckpointMetadata.cpp @@ -0,0 +1,37 @@ +/* Story Checkpoint Metadata + * + * From: https://github.com/PokemonAutomation/ + * + */ + +#include "Pokemon_StoryCheckpointMetadata.h" + +namespace PokemonAutomation{ +namespace Pokemon{ + + +std::string story_phase_name(StoryPhase phase){ + switch (phase){ + case StoryPhase::TESTING: + return "testing"; + case StoryPhase::VERIFICATION: + return "verification"; + case StoryPhase::REPRODUCTION: + return "reproduction"; + } + return "?"; +} + +std::optional read_story_phase(std::string_view name){ + for (StoryPhase phase : {StoryPhase::TESTING, StoryPhase::VERIFICATION, StoryPhase::REPRODUCTION}){ + if (story_phase_name(phase) == name){ + return phase; + } + } + return std::nullopt; +} + + + +} // namespace Pokemon +} // namespace PokemonAutomation diff --git a/SerialPrograms/Source/Pokemon/AutoStory/Types/Pokemon_StoryCheckpointMetadata.h b/SerialPrograms/Source/Pokemon/AutoStory/Types/Pokemon_StoryCheckpointMetadata.h new file mode 100644 index 0000000000..0a305e0591 --- /dev/null +++ b/SerialPrograms/Source/Pokemon/AutoStory/Types/Pokemon_StoryCheckpointMetadata.h @@ -0,0 +1,69 @@ +/* Story Checkpoint Metadata + * + * From: https://github.com/PokemonAutomation/ + * + * What a checkpoint's JSON says about the checkpoint rather than how to + * play it: its phase (autostory/SAVE_POLICY.md on the notes branch), the + * steps it was verified with, and where it came from. The engine picks + * the save mode from the phase, and only while the steps still hash to + * the verified ones (Engine/Pokemon_StoryEnginePolicy.h). + * + */ + +#ifndef PokemonAutomation_Pokemon_StoryCheckpointMetadata_H +#define PokemonAutomation_Pokemon_StoryCheckpointMetadata_H + +#include +#include +#include + +namespace PokemonAutomation{ +namespace Pokemon{ + + +// Where a checkpoint stands. It moves forward only on passes; a change to +// its steps moves it back to TESTING. +enum class StoryPhase{ + // New or changed: one run, never saves. + TESTING, + // Passed its test: 2-3 runs from the same start save, then one save. + VERIFICATION, + // Verified: a playthrough saves at its end. + REPRODUCTION, +}; + +// The wire and log name of a phase: "testing", "verification", "reproduction". +std::string story_phase_name(StoryPhase phase); + +// The phase named `name`; none for another name. +std::optional read_story_phase(std::string_view name); + +// The runs that moved the checkpoint out of testing, as recorded. +struct StoryVerification{ + // story_steps_hash() of the steps those runs ran: "sha256:". + std::string steps_hash = {}; + // The build those runs used (a commit). + std::string build = {}; + std::string date = {}; + // Passes out of runs, e.g. "3/3". + std::string runs = {}; + + bool operator==(const StoryVerification& other) const = default; +}; + +// A checkpoint's "metadata" object, less its postconditions, which the +// checkpoint keeps beside its steps (StoryCheckpoint::postconditions). +struct StoryCheckpointMetadata{ + StoryPhase phase = StoryPhase::TESTING; + std::optional verified = std::nullopt; + // Where the steps came from: a walkthrough, a console recording. + std::string source = {}; + + bool operator==(const StoryCheckpointMetadata& other) const = default; +}; + + + +} // namespace Pokemon +} // namespace PokemonAutomation +#endif diff --git a/SerialPrograms/cmake/SourceFiles.cmake b/SerialPrograms/cmake/SourceFiles.cmake index 85b75fea58..b86f170dbf 100644 --- a/SerialPrograms/cmake/SourceFiles.cmake +++ b/SerialPrograms/cmake/SourceFiles.cmake @@ -905,6 +905,7 @@ file(GLOB LIBRARY_SOURCES Source/CommonTools/Resources/SpriteDatabase.h Source/CommonTools/ScreenMachine/ScreenMachine.cpp Source/CommonTools/ScreenMachine/ScreenMachine.h + Source/CommonTools/ScreenMachine/ScreenObservation.h Source/CommonTools/ScreenMachine/StepTrace.cpp Source/CommonTools/ScreenMachine/StepTrace.h Source/CommonTools/StartupChecks/StartProgramChecks.cpp @@ -1509,6 +1510,25 @@ file(GLOB LIBRARY_SOURCES Source/Pokemon/AutoStory/Data/Pokemon_StoryStepJson.cpp Source/Pokemon/AutoStory/Data/Pokemon_StoryStepJson.h Source/Pokemon/AutoStory/Data/Pokemon_StoryStepJson_Tests.cpp + Source/Pokemon/AutoStory/Engine/Pokemon_StoryActionRegistry.cpp + Source/Pokemon/AutoStory/Engine/Pokemon_StoryActionRegistry.h + Source/Pokemon/AutoStory/Engine/Pokemon_StoryBackend.h + Source/Pokemon/AutoStory/Engine/Pokemon_StoryBuiltinActions.cpp + Source/Pokemon/AutoStory/Engine/Pokemon_StoryBuiltinActions.h + Source/Pokemon/AutoStory/Engine/Pokemon_StoryEngine.cpp + Source/Pokemon/AutoStory/Engine/Pokemon_StoryEngine.h + Source/Pokemon/AutoStory/Engine/Pokemon_StoryEngine_Tests.cpp + Source/Pokemon/AutoStory/Engine/Pokemon_StoryEngine_Tests.h + Source/Pokemon/AutoStory/Engine/Pokemon_StoryEnginePolicy.cpp + Source/Pokemon/AutoStory/Engine/Pokemon_StoryEnginePolicy.h + Source/Pokemon/AutoStory/Engine/Pokemon_StoryEnginePolicy_Tests.cpp + Source/Pokemon/AutoStory/Engine/Pokemon_StoryFakeBackend.cpp + Source/Pokemon/AutoStory/Engine/Pokemon_StoryFakeBackend.h + Source/Pokemon/AutoStory/Engine/Pokemon_StoryGame.h + Source/Pokemon/AutoStory/Engine/Pokemon_StoryPoseConcept.cpp + Source/Pokemon/AutoStory/Engine/Pokemon_StoryPoseConcept.h + Source/Pokemon/AutoStory/Engine/Pokemon_StoryStepRunner.cpp + Source/Pokemon/AutoStory/Engine/Pokemon_StoryStepRunner.h Source/Pokemon/AutoStory/Pokemon_AutoStorySelect.h Source/Pokemon/AutoStory/Pokemon_AutoStorySelect_Tests.cpp Source/Pokemon/AutoStory/Pokemon_AutoStorySelect_Tests.h @@ -1548,6 +1568,8 @@ file(GLOB LIBRARY_SOURCES Source/Pokemon/AutoStory/Types/Pokemon_StoryCheckLevel.cpp Source/Pokemon/AutoStory/Types/Pokemon_StoryCheckLevel.h Source/Pokemon/AutoStory/Types/Pokemon_StoryCheckpoint.h + Source/Pokemon/AutoStory/Types/Pokemon_StoryCheckpointMetadata.cpp + Source/Pokemon/AutoStory/Types/Pokemon_StoryCheckpointMetadata.h Source/Pokemon/AutoStory/Types/Pokemon_StoryPostconditions.h Source/Pokemon/AutoStory/Types/Pokemon_StorySaveMode.cpp Source/Pokemon/AutoStory/Types/Pokemon_StorySaveMode.h From 45d43323b3ebdc5d8425b7a1e2be429721944f9b Mon Sep 17 00:00:00 2001 From: dayfine Date: Tue, 10 Nov 2026 10:21:01 -0800 Subject: [PATCH 038/102] AutoStory engine: pin the steps hash; MIGRATION.md for the game moves Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_013VUubhHeYSMGSSDXZkKZss --- .../Pokemon/AutoStory/Engine/MIGRATION.md | 56 +++++++++++++++++++ .../Pokemon_StoryEnginePolicy_Tests.cpp | 2 +- 2 files changed, 57 insertions(+), 1 deletion(-) create mode 100644 SerialPrograms/Source/Pokemon/AutoStory/Engine/MIGRATION.md diff --git a/SerialPrograms/Source/Pokemon/AutoStory/Engine/MIGRATION.md b/SerialPrograms/Source/Pokemon/AutoStory/Engine/MIGRATION.md new file mode 100644 index 0000000000..937bc77de2 --- /dev/null +++ b/SerialPrograms/Source/Pokemon/AutoStory/Engine/MIGRATION.md @@ -0,0 +1,56 @@ +# Moving a game onto the story engine + +The engine (`Pokemon_StoryEngine.h`) replaces each game's `StoryExecutor` and the shared +`StoryStepExecutor`. A game moves in its own PR, after this one, in this order: FRLG, BDSP, PLZA. +Each move deletes that game's executor; the last one deletes `StoryStepExecutor`. + +## What each game does + +1. **Backends.** Write a console backend: `StoryBackend` over the console handle and the + controller context. `observe()` waits for pending input (`wait_for_all_requests()`), takes a + frame and fills `ScreenObservation::events` from the game's detectors (fade, text box, battle, + can move, still). `battle()` calls the game's battle code. A simulation backend wraps the + PokemonSimulation model the same way; `FakeStoryBackend` is the scripted one for unit tests. +2. **StoryGame.** Build the game's `StoryGame` once: + - `actions`: the game's own actions (GAME steps, e.g. FRLG `take_warp`) and its replacements of + built-ins that need its map or menus: `route`, `ready`, `train`, `shop`, and the kinds with no + built-in (`heal`, `new_game`, `options`). A replacement uses the built-in's kind and name + (`find_story_action(builtin_story_actions(), kind, name)` gives its spec). Don't register + `save`: the engine owns the SAVE step so it can hold it back while testing; give `save`. + - `readers`: `"pose"` (map, tile, facing into `Observation::pose`), `"bag"` (`bag.` + readings), story flags (`flag.`), and one per `skip_if` condition the game answers from + the screen. Postconditions are checked only with what the readers read. + - `save`, `reload`, `begin_attempt` (today's `StoryStepExecutor::begin_attempt`) and + `interrupts` (wild battles, trainers). +3. **Data.** Every checkpoint is a checked-in JSON file with `metadata`: `phase`, and for + verification or reproduction `verified.steps_hash` (`StoryEngine::steps_hash()`). Add a unit + test that loads every checkpoint, lints it (`StoryActionRegistry::lint`) and fails when a + verification or reproduction checkpoint's recorded hash differs from its steps' hash. Delete the + C++ table rows once the JSON parity test passes. +4. **Run.** Replace the program's executor loop with `StoryEngine::run_checkpoint()` per + checkpoint; pass `SavePoint::CHECKPOINT_END` for all but the last checkpoint of a run. The save + mode now comes from the checkpoint's phase, not from the run options. +5. **Tests.** Port the executor's tests to the engine on the fake or simulation backend; each + console failure stays a red-first regression test (the 00.31 warp is the worked example in + `Pokemon_StoryEngine_Tests.cpp`). + +## Per game + +- **FRLG** (GridPose): `take_warp` from `PokemonFRLG_OverworldWalk.cpp` `wait_out_warp`, written + against the backend as in the test; the route action over its grids; the PC, Mart and nurse + actions; position, facing and Bag readers (tile and facing at least, for #329's check). +- **BDSP** (GridPose): the same, with D-pad legs; its warp and settle rules become actions or + readers. +- **PLZA**: add `ZonePose{std::string zone;}` with `pose_matches` / `pose_text` next to + `Pokemon_StoryPoseConcept.h`, and an explicit instantiation line for it in each engine `.cpp`. + `StoryCheckpoint` positions are `GridPose` today: PLZA steps carry their zone in action args + until checkpoints are templated on the pose, and its postconditions need an `observed_state()` + overload for `Observation`. + +## Moves in shared code when the last executor goes + +- `build_story_checkpoint()`, `story_event()`, `pose_of()` and `unsupported_step()` move from + `Pokemon_StoryStepExecutor.*` into the engine; `RunnerExecutor` in `Pokemon_StoryEngine.cpp` + (the adapter over the old interface) goes. +- `lint_story_checkpoint()` is replaced by `StoryActionRegistry::lint()`. +- `run_segment()` / `verify_checkpoint()` (Pokemon_StorySegments) call the engine per checkpoint. diff --git a/SerialPrograms/Source/Pokemon/AutoStory/Engine/Pokemon_StoryEnginePolicy_Tests.cpp b/SerialPrograms/Source/Pokemon/AutoStory/Engine/Pokemon_StoryEnginePolicy_Tests.cpp index 20f6ea0d6e..ba59dc194f 100644 --- a/SerialPrograms/Source/Pokemon/AutoStory/Engine/Pokemon_StoryEnginePolicy_Tests.cpp +++ b/SerialPrograms/Source/Pokemon/AutoStory/Engine/Pokemon_StoryEnginePolicy_Tests.cpp @@ -220,7 +220,7 @@ inline constexpr std::string_view ROUTE_B3F = R"([{"id": "go", "kind": "route", const HashCase HASH_CASES[] = { {.input = {.name = "pinned", .a = ROUTE_B3F, .b = ROUTE_B3F}, - .expectation = {.same = true, .hash_a = "sha256:PIN"}}, + .expectation = {.same = true, .hash_a = "sha256:c4b4a5c60e0a2b65b188f75f64b699073485aafa278fcbdd4afbd055da878af0"}}, {.input = {.name = "why is not hashed", .a = R"([{"id": "t", "kind": "talk", "why": "a"}])", .b = R"([{"id": "t", "kind": "talk", "why": "b"}])"}, .expectation = {.same = true}}, {.input = {.name = "fallbacks are filled", .a = R"([{"id": "f", "kind": "battle"}])", .b = R"([{"id": "f", "kind": "battle", "args": {"may_lose": false}}])"}, From 5274bc13449377c95bda5e74831ff92ec9047a18 Mon Sep 17 00:00:00 2001 From: dayfine Date: Tue, 10 Nov 2026 10:29:29 -0800 Subject: [PATCH 039/102] AutoStory engine: ZonePose, instantiated beside GridPose PLZA has no tile grid; its pose is the zone it is in until it has a position reader. Adds ZonePose (pose_matches, pose_text), the engine's explicit instantiations for it, and observed_state() for a zone observation (map = zone; items and flags from readings as for tiles). Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_013VUubhHeYSMGSSDXZkKZss (cherry picked from commit da4bb94248c75a73efc51daae7bf83611fdcd384) --- .../Engine/Pokemon_StoryActionRegistry.cpp | 1 + .../Engine/Pokemon_StoryActionRegistry.h | 1 + .../AutoStory/Engine/Pokemon_StoryBackend.h | 1 + .../Engine/Pokemon_StoryBuiltinActions.cpp | 1 + .../Engine/Pokemon_StoryBuiltinActions.h | 1 + .../AutoStory/Engine/Pokemon_StoryEngine.cpp | 35 +++++++++++++----- .../AutoStory/Engine/Pokemon_StoryEngine.h | 4 ++ .../Engine/Pokemon_StoryStepRunner.cpp | 1 + .../Engine/Pokemon_StoryStepRunner.h | 1 + .../AutoStory/Engine/Pokemon_ZonePose.cpp | 25 +++++++++++++ .../AutoStory/Engine/Pokemon_ZonePose.h | 37 +++++++++++++++++++ SerialPrograms/cmake/SourceFiles.cmake | 2 + 12 files changed, 101 insertions(+), 9 deletions(-) create mode 100644 SerialPrograms/Source/Pokemon/AutoStory/Engine/Pokemon_ZonePose.cpp create mode 100644 SerialPrograms/Source/Pokemon/AutoStory/Engine/Pokemon_ZonePose.h diff --git a/SerialPrograms/Source/Pokemon/AutoStory/Engine/Pokemon_StoryActionRegistry.cpp b/SerialPrograms/Source/Pokemon/AutoStory/Engine/Pokemon_StoryActionRegistry.cpp index fec02f1e79..56f0988134 100644 --- a/SerialPrograms/Source/Pokemon/AutoStory/Engine/Pokemon_StoryActionRegistry.cpp +++ b/SerialPrograms/Source/Pokemon/AutoStory/Engine/Pokemon_StoryActionRegistry.cpp @@ -121,6 +121,7 @@ Outcome StoryActionRegistry::dispatch(StoryBackend& backend, template class StoryActionRegistry; +template class StoryActionRegistry; diff --git a/SerialPrograms/Source/Pokemon/AutoStory/Engine/Pokemon_StoryActionRegistry.h b/SerialPrograms/Source/Pokemon/AutoStory/Engine/Pokemon_StoryActionRegistry.h index dfbb99c84e..57dfbc06f4 100644 --- a/SerialPrograms/Source/Pokemon/AutoStory/Engine/Pokemon_StoryActionRegistry.h +++ b/SerialPrograms/Source/Pokemon/AutoStory/Engine/Pokemon_StoryActionRegistry.h @@ -65,6 +65,7 @@ class StoryActionRegistry{ // Instantiated once, in Pokemon_StoryActionRegistry.cpp. extern template class StoryActionRegistry; +extern template class StoryActionRegistry; diff --git a/SerialPrograms/Source/Pokemon/AutoStory/Engine/Pokemon_StoryBackend.h b/SerialPrograms/Source/Pokemon/AutoStory/Engine/Pokemon_StoryBackend.h index 9c14276f57..f259e5279e 100644 --- a/SerialPrograms/Source/Pokemon/AutoStory/Engine/Pokemon_StoryBackend.h +++ b/SerialPrograms/Source/Pokemon/AutoStory/Engine/Pokemon_StoryBackend.h @@ -23,6 +23,7 @@ #include "Pokemon/AutoStory/Types/Pokemon_StoryActionArg.h" #include "Pokemon/Navigation/Pokemon_Grid.h" #include "Pokemon_StoryPoseConcept.h" +#include "Pokemon_ZonePose.h" namespace PokemonAutomation{ namespace Pokemon{ diff --git a/SerialPrograms/Source/Pokemon/AutoStory/Engine/Pokemon_StoryBuiltinActions.cpp b/SerialPrograms/Source/Pokemon/AutoStory/Engine/Pokemon_StoryBuiltinActions.cpp index 33110781b5..0dbf917793 100644 --- a/SerialPrograms/Source/Pokemon/AutoStory/Engine/Pokemon_StoryBuiltinActions.cpp +++ b/SerialPrograms/Source/Pokemon/AutoStory/Engine/Pokemon_StoryBuiltinActions.cpp @@ -150,6 +150,7 @@ std::vector> builtin_story_handlers(const StoryGame> builtin_story_handlers(const StoryGame& game); +template std::vector> builtin_story_handlers(const StoryGame& game); diff --git a/SerialPrograms/Source/Pokemon/AutoStory/Engine/Pokemon_StoryBuiltinActions.h b/SerialPrograms/Source/Pokemon/AutoStory/Engine/Pokemon_StoryBuiltinActions.h index dae70e1048..0df6f597c6 100644 --- a/SerialPrograms/Source/Pokemon/AutoStory/Engine/Pokemon_StoryBuiltinActions.h +++ b/SerialPrograms/Source/Pokemon/AutoStory/Engine/Pokemon_StoryBuiltinActions.h @@ -39,6 +39,7 @@ std::vector> builtin_story_handlers(const StoryGame> builtin_story_handlers(const StoryGame& game); +extern template std::vector> builtin_story_handlers(const StoryGame& game); diff --git a/SerialPrograms/Source/Pokemon/AutoStory/Engine/Pokemon_StoryEngine.cpp b/SerialPrograms/Source/Pokemon/AutoStory/Engine/Pokemon_StoryEngine.cpp index 24ecc52a46..4799a068be 100644 --- a/SerialPrograms/Source/Pokemon/AutoStory/Engine/Pokemon_StoryEngine.cpp +++ b/SerialPrograms/Source/Pokemon/AutoStory/Engine/Pokemon_StoryEngine.cpp @@ -63,13 +63,28 @@ StoryGame with_gated_save_step(StoryGame game, const StorySa } +// The items ("bag.") and flags ("flag.", non-zero is set) of +// `observation`'s readings. +ObservedState observed_readings(const ScreenObservation& observation){ + constexpr std::string_view BAG = "bag."; + constexpr std::string_view FLAG = "flag."; + ObservedState observed; + for (const auto& [name, value] : observation.readings){ + if (name.starts_with(BAG)){ + observed.items[name.substr(BAG.size())] = value < 0 ? 0 : (size_t)value; + }else if (name.starts_with(FLAG)){ + observed.flags[name.substr(FLAG.size())] = value != 0; + } + } + return observed; +} + + } // namespace ObservedState observed_state(const Observation& observation){ - constexpr std::string_view BAG = "bag."; - constexpr std::string_view FLAG = "flag."; - ObservedState observed; + ObservedState observed = observed_readings(observation); if (observation.pose){ observed.map = observation.pose->map; if (observation.pose->tiles.size() == 1){ @@ -77,12 +92,13 @@ ObservedState observed_state(const Observation& observation){ } observed.facing = observation.pose->facing; } - for (const auto& [name, value] : observation.readings){ - if (name.starts_with(BAG)){ - observed.items[name.substr(BAG.size())] = value < 0 ? 0 : (size_t)value; - }else if (name.starts_with(FLAG)){ - observed.flags[name.substr(FLAG.size())] = value != 0; - } + return observed; +} + +ObservedState observed_state(const Observation& observation){ + ObservedState observed = observed_readings(observation); + if (observation.pose){ + observed.map = observation.pose->zone; } return observed; } @@ -178,6 +194,7 @@ PostconditionReport StoryEngine::check_postconditions(const StoryCheck template class StoryEngine; +template class StoryEngine; diff --git a/SerialPrograms/Source/Pokemon/AutoStory/Engine/Pokemon_StoryEngine.h b/SerialPrograms/Source/Pokemon/AutoStory/Engine/Pokemon_StoryEngine.h index 0cbf5b37ca..a36fb351f5 100644 --- a/SerialPrograms/Source/Pokemon/AutoStory/Engine/Pokemon_StoryEngine.h +++ b/SerialPrograms/Source/Pokemon/AutoStory/Engine/Pokemon_StoryEngine.h @@ -36,6 +36,9 @@ namespace Pokemon{ // (non-zero is set). ObservedState observed_state(const Observation& observation); +// The same for a zone game: the map is the zone; no tile or facing. +ObservedState observed_state(const Observation& observation); + // Runs `game`'s checkpoints on `backend`. Both must outlive it. template class StoryEngine{ @@ -75,6 +78,7 @@ class StoryEngine{ // Instantiated once, in Pokemon_StoryEngine.cpp. extern template class StoryEngine; +extern template class StoryEngine; diff --git a/SerialPrograms/Source/Pokemon/AutoStory/Engine/Pokemon_StoryStepRunner.cpp b/SerialPrograms/Source/Pokemon/AutoStory/Engine/Pokemon_StoryStepRunner.cpp index a2297934df..93c30c493f 100644 --- a/SerialPrograms/Source/Pokemon/AutoStory/Engine/Pokemon_StoryStepRunner.cpp +++ b/SerialPrograms/Source/Pokemon/AutoStory/Engine/Pokemon_StoryStepRunner.cpp @@ -77,6 +77,7 @@ bool StoryStepRunner::holds(std::string_view condition, RunState& stat template class StoryStepRunner; +template class StoryStepRunner; diff --git a/SerialPrograms/Source/Pokemon/AutoStory/Engine/Pokemon_StoryStepRunner.h b/SerialPrograms/Source/Pokemon/AutoStory/Engine/Pokemon_StoryStepRunner.h index 88aecea47a..fc4a16b245 100644 --- a/SerialPrograms/Source/Pokemon/AutoStory/Engine/Pokemon_StoryStepRunner.h +++ b/SerialPrograms/Source/Pokemon/AutoStory/Engine/Pokemon_StoryStepRunner.h @@ -50,6 +50,7 @@ class StoryStepRunner{ // Instantiated once, in Pokemon_StoryStepRunner.cpp. extern template class StoryStepRunner; +extern template class StoryStepRunner; diff --git a/SerialPrograms/Source/Pokemon/AutoStory/Engine/Pokemon_ZonePose.cpp b/SerialPrograms/Source/Pokemon/AutoStory/Engine/Pokemon_ZonePose.cpp new file mode 100644 index 0000000000..49e435b28c --- /dev/null +++ b/SerialPrograms/Source/Pokemon/AutoStory/Engine/Pokemon_ZonePose.cpp @@ -0,0 +1,25 @@ +/* Zone Pose + * + * From: https://github.com/PokemonAutomation/ + * + */ + +#include +#include "Pokemon_ZonePose.h" + +namespace PokemonAutomation{ +namespace Pokemon{ + + +bool pose_matches(const ZonePose& actual, const ZonePose& target){ + return target.zone.empty() || actual.zone == target.zone; +} + +std::string pose_text(const ZonePose& pose){ + return "zone " + (pose.zone.empty() ? std::string("unknown") : pose.zone); +} + + + +} // namespace Pokemon +} // namespace PokemonAutomation diff --git a/SerialPrograms/Source/Pokemon/AutoStory/Engine/Pokemon_ZonePose.h b/SerialPrograms/Source/Pokemon/AutoStory/Engine/Pokemon_ZonePose.h new file mode 100644 index 0000000000..e9f54f02a5 --- /dev/null +++ b/SerialPrograms/Source/Pokemon/AutoStory/Engine/Pokemon_ZonePose.h @@ -0,0 +1,37 @@ +/* Zone Pose + * + * From: https://github.com/PokemonAutomation/ + * + * The pose of a game with no tile grid (PLZA): the zone the player is in, + * by name, until the game has a reader of its position. A StoryPose + * (Pokemon_StoryPoseConcept.h). + * + */ + +#ifndef PokemonAutomation_Pokemon_ZonePose_H +#define PokemonAutomation_Pokemon_ZonePose_H + +#include + +namespace PokemonAutomation{ +namespace Pokemon{ + + +// Where the player is: a zone, "LumioseCity" or "HotelZ". +struct ZonePose{ + std::string zone = {}; + + bool operator==(const ZonePose& other) const = default; +}; + +// Whether `actual` is in `target`'s zone; any zone when `target` names none. +bool pose_matches(const ZonePose& actual, const ZonePose& target); + +// "zone LumioseCity". +std::string pose_text(const ZonePose& pose); + + + +} // namespace Pokemon +} // namespace PokemonAutomation +#endif diff --git a/SerialPrograms/cmake/SourceFiles.cmake b/SerialPrograms/cmake/SourceFiles.cmake index b86f170dbf..a65d891ab7 100644 --- a/SerialPrograms/cmake/SourceFiles.cmake +++ b/SerialPrograms/cmake/SourceFiles.cmake @@ -1529,6 +1529,8 @@ file(GLOB LIBRARY_SOURCES Source/Pokemon/AutoStory/Engine/Pokemon_StoryPoseConcept.h Source/Pokemon/AutoStory/Engine/Pokemon_StoryStepRunner.cpp Source/Pokemon/AutoStory/Engine/Pokemon_StoryStepRunner.h + Source/Pokemon/AutoStory/Engine/Pokemon_ZonePose.cpp + Source/Pokemon/AutoStory/Engine/Pokemon_ZonePose.h Source/Pokemon/AutoStory/Pokemon_AutoStorySelect.h Source/Pokemon/AutoStory/Pokemon_AutoStorySelect_Tests.cpp Source/Pokemon/AutoStory/Pokemon_AutoStorySelect_Tests.h From 81929f6ddc4a799814410ce954fbb371decfea37 Mon Sep 17 00:00:00 2001 From: dayfine Date: Tue, 10 Nov 2026 10:58:33 -0800 Subject: [PATCH 040/102] AutoStory engine: close the gaps the PLZA move found What PLZA (#335) had to work around, now in the engine: - FakeStoryBackend and its script are templated on the pose (GridPose and ZonePose instantiated); ZonePose moves into the engine (cherry-picked). - StoryBackend::stick(degrees, duration, pace) for free-moving games, and the "heading" reading (STORY_HEADING, story_heading()). - ScreenEvent gains CHOICE_BOX and INTERACT_PROMPT. - run_screen_machine_on_observations(): ScreenMachine states over looks, failures returned; ScreenMachineChecks::problem() for observations; StepTrace without video (lines to a log, no screenshots). - Handlers get a StoryActionCall {step, args}; StoryGame::save gets the checkpoint. - StoryEngine::run_segment() and verify_checkpoint(): retries only when a reload returns to the checkpoint's start save (#329), no reload for lint, console_only or game-not-running failures; verify saves only on the last run when every run passed. - StoryActionSpec::console_only, refused off a console as "console_only"; StoryBackend::kind(). - StoryPoseTraits: TILE_MOVES (legs/face only for tile games) and from_declared() (a checkpoint's start and declared_after read as the game's pose; the lint fails what does not fit). A declared pose may omit "tiles". Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_013VUubhHeYSMGSSDXZkKZss --- .../ScreenMachine/ScreenMachine.cpp | 66 ++- .../CommonTools/ScreenMachine/ScreenMachine.h | 34 ++ .../ScreenMachine/ScreenObservation.h | 5 +- .../CommonTools/ScreenMachine/StepTrace.cpp | 54 +- .../CommonTools/ScreenMachine/StepTrace.h | 19 +- .../AutoStory/Data/Pokemon_StoryStepJson.cpp | 5 +- .../AutoStory/Data/Pokemon_StoryStepJson.h | 3 +- .../Engine/Pokemon_StoryActionRegistry.cpp | 22 +- .../Engine/Pokemon_StoryActionRegistry.h | 15 +- .../AutoStory/Engine/Pokemon_StoryBackend.cpp | 36 ++ .../AutoStory/Engine/Pokemon_StoryBackend.h | 29 +- .../Engine/Pokemon_StoryBuiltinActions.cpp | 65 ++- .../Engine/Pokemon_StoryBuiltinActions.h | 16 +- .../AutoStory/Engine/Pokemon_StoryEngine.cpp | 166 +++++- .../AutoStory/Engine/Pokemon_StoryEngine.h | 46 +- .../Pokemon_StoryEnginePolicy_Tests.cpp | 6 +- .../Engine/Pokemon_StoryEngineRuns_Tests.cpp | 534 ++++++++++++++++++ .../Engine/Pokemon_StoryEngine_Tests.cpp | 16 +- .../Engine/Pokemon_StoryEngine_Tests.h | 3 + .../Engine/Pokemon_StoryFakeBackend.cpp | 51 +- .../Engine/Pokemon_StoryFakeBackend.h | 29 +- .../AutoStory/Engine/Pokemon_StoryGame.h | 27 +- .../Engine/Pokemon_StoryPoseConcept.h | 38 +- .../Engine/Pokemon_StoryStepRunner.h | 1 + .../AutoStory/Engine/Pokemon_ZonePose.h | 16 + .../AutoStory/Pokemon_AutoStory_Tests.h | 1 + .../AutoStory/Types/Pokemon_StoryActionSpec.h | 4 + SerialPrograms/cmake/SourceFiles.cmake | 2 + 28 files changed, 1198 insertions(+), 111 deletions(-) create mode 100644 SerialPrograms/Source/Pokemon/AutoStory/Engine/Pokemon_StoryBackend.cpp create mode 100644 SerialPrograms/Source/Pokemon/AutoStory/Engine/Pokemon_StoryEngineRuns_Tests.cpp diff --git a/SerialPrograms/Source/CommonTools/ScreenMachine/ScreenMachine.cpp b/SerialPrograms/Source/CommonTools/ScreenMachine/ScreenMachine.cpp index a7c290bc8b..b015506284 100644 --- a/SerialPrograms/Source/CommonTools/ScreenMachine/ScreenMachine.cpp +++ b/SerialPrograms/Source/CommonTools/ScreenMachine/ScreenMachine.cpp @@ -5,6 +5,8 @@ */ #include +#include +#include #include "CommonFramework/ImageTools/ImageDiff.h" #include "ScreenMachine.h" @@ -73,12 +75,23 @@ const ScreenState& read_screen_state( void ScreenMachineChecks::check(const ScreenState& state, VideoSnapshot frame){ + const std::optional found = problem(state, std::move(frame)); + if (found){ + m_trace.fail(*found); + } +} + +std::optional ScreenMachineChecks::problem(const ScreenState& state, const ScreenObservation& observation){ + return problem(state, observation.frame ? *observation.frame : VideoSnapshot()); +} + +std::optional ScreenMachineChecks::problem(const ScreenState& state, VideoSnapshot frame){ const bool same_size = m_last_frame && frame && m_last_frame->width() == frame->width() && m_last_frame->height() == frame->height(); if (same_size && ImageMatch::pixel_RMSD(m_last_frame, frame) < 2.0){ if (++m_unchanged >= MAX_UNCHANGED){ - m_trace.fail("The screen stopped changing: " + std::to_string(MAX_UNCHANGED) + - " steps on \"" + state.name + "\" did nothing."); + return "The screen stopped changing: " + std::to_string(MAX_UNCHANGED) + + " steps on \"" + state.name + "\" did nothing."; } }else{ m_unchanged = 0; @@ -88,18 +101,57 @@ void ScreenMachineChecks::check(const ScreenState& state, VideoSnapshot frame){ if (m_previous != nullptr && m_previous != &state && !m_previous->next.empty() && std::find(m_previous->next.begin(), m_previous->next.end(), state.name) == m_previous->next.end() ){ - m_trace.fail("Unexpected screen after \"" + m_previous->name + "\": \"" + state.name + "\"."); + return "Unexpected screen after \"" + m_previous->name + "\": \"" + state.name + "\"."; } m_in_a_row = m_previous == &state ? m_in_a_row + 1 : 1; if (m_in_a_row > state.max_in_a_row){ - m_trace.fail("Screen \"" + state.name + "\" came up " + std::to_string(m_in_a_row) + - " times in a row: the step for it is not getting anywhere."); + return "Screen \"" + state.name + "\" came up " + std::to_string(m_in_a_row) + + " times in a row: the step for it is not getting anywhere."; } if (++m_visits[state.name] > state.max_visits){ - m_trace.fail("Screen \"" + state.name + "\" came up more than " + - std::to_string(state.max_visits) + " times: the step for it is not working."); + return "Screen \"" + state.name + "\" came up more than " + + std::to_string(state.max_visits) + " times: the step for it is not working."; } m_previous = &state; + return std::nullopt; +} + + +ScreenMachineResult run_screen_machine_on_observations( + const std::function& observe, CancellableScope& scope, StepTrace& trace, + const std::vector& states, Milliseconds timeout +){ + // Looks before the run stops even when nothing else ends it (looks with + // no time, states with no visit limit). + constexpr size_t MAX_LOOKS = 10000; + ScreenMachineChecks checks(trace); + std::optional start; + for (size_t looks = 0; looks < MAX_LOOKS; looks++){ + scope.throw_if_cancelled(); + const ScreenObservation observation = observe(); + if (!start){ + start = observation.when; + } + if (observation.when - *start > timeout){ + return {.terminal = "", .failure = "Did not finish within " + std::to_string(timeout.count() / 1000) + "s."}; + } + const ScreenState* state = match_screen_state(states, observation); + if (state == nullptr){ + return {.terminal = "", .failure = "The screen matches none of the known states."}; + } + trace.screen(state->name); + std::optional found = checks.problem(*state, observation); + if (found){ + return {.terminal = "", .failure = std::move(*found)}; + } + if (state->act){ + state->act(); + } + if (state->terminal){ + return {.terminal = state->name, .failure = ""}; + } + } + return {.terminal = "", .failure = "Did not finish within " + std::to_string(MAX_LOOKS) + " looks."}; } diff --git a/SerialPrograms/Source/CommonTools/ScreenMachine/ScreenMachine.h b/SerialPrograms/Source/CommonTools/ScreenMachine/ScreenMachine.h index 6ac31e0635..31f3c6b658 100644 --- a/SerialPrograms/Source/CommonTools/ScreenMachine/ScreenMachine.h +++ b/SerialPrograms/Source/CommonTools/ScreenMachine/ScreenMachine.h @@ -15,6 +15,7 @@ #include #include #include +#include #include #include #include "Common/Cpp/Time.h" @@ -70,9 +71,16 @@ class ScreenMachineChecks{ ScreenMachineChecks(StepTrace& trace) : m_trace(trace) {} + // Fails through the trace on a problem. void check(const ScreenState& state, VideoSnapshot frame); + // The problem with `state` coming up on `observation`, if any. The + // screen counts as unchanged only when it and the look before both have + // a frame and the frames match. + std::optional problem(const ScreenState& state, const ScreenObservation& observation); private: + std::optional problem(const ScreenState& state, VideoSnapshot frame); + // A step that changes nothing on screen is a dead end (e.g. a menu the states do // not know): fail after a few instead of running out the visit limit. static constexpr size_t MAX_UNCHANGED = 8; @@ -94,6 +102,32 @@ std::string run_screen_machine( const std::vector& states, Milliseconds timeout ); + +// How a run of states over observations ended. +struct ScreenMachineResult{ + // The terminal state that acted; empty when the run failed. + std::string terminal; + // Why it failed: no state matched, an unexpected screen, a state seen too + // often, a stall, or the timeout. + std::string failure; + + bool succeeded() const{ + return failure.empty(); + } +}; + +// The same loop as run_screen_machine() over looks from `observe` instead of +// frames, so it runs on a console and in a simulation alike: each look picks +// the first state whose matches_observation() accepts it (one look, no second +// read: an observation is already settled), the trace records it, the checks +// apply, then the state acts. Time is the looks' own (`when`): the run fails +// once `timeout` has passed since the first look, and after 10000 looks in +// any case. A failure is returned, not thrown. +ScreenMachineResult run_screen_machine_on_observations( + const std::function& observe, CancellableScope& scope, StepTrace& trace, + const std::vector& states, Milliseconds timeout +); + template std::string run_screen_machine( VideoStream& stream, ControllerContext& context, StepTrace& trace, diff --git a/SerialPrograms/Source/CommonTools/ScreenMachine/ScreenObservation.h b/SerialPrograms/Source/CommonTools/ScreenMachine/ScreenObservation.h index 96eccb0df4..6c80b29327 100644 --- a/SerialPrograms/Source/CommonTools/ScreenMachine/ScreenObservation.h +++ b/SerialPrograms/Source/CommonTools/ScreenMachine/ScreenObservation.h @@ -34,6 +34,8 @@ enum class ScreenEvent : uint8_t{ BATTLE, // a battle is showing CAN_MOVE, // the player can move: no box, menu or scene holds them STILL, // nothing moved since the previous look + CHOICE_BOX, // a list of answers to pick from is open + INTERACT_PROMPT, // a prompt to interact with what the player faces ("A Talk") }; // The set of events one look showed. @@ -67,7 +69,8 @@ class ScreenEvents{ struct ScreenObservation{ WallClock when = WallClock::min(); ScreenEvents events = {}; - // Named numbers a reader found: "bag.RARE_CANDY", "facing". + // Named numbers a reader found: "bag.RARE_CANDY", "facing", + // "heading" (degrees clockwise from north, [0, 360)). std::map> readings = {}; // The frame looked at; none in a simulation. A state that needs it // can only run on a console. diff --git a/SerialPrograms/Source/CommonTools/ScreenMachine/StepTrace.cpp b/SerialPrograms/Source/CommonTools/ScreenMachine/StepTrace.cpp index 97503bb1a2..44c32d5596 100644 --- a/SerialPrograms/Source/CommonTools/ScreenMachine/StepTrace.cpp +++ b/SerialPrograms/Source/CommonTools/ScreenMachine/StepTrace.cpp @@ -5,9 +5,12 @@ */ #include +#include +#include #include "Common/Cpp/PrettyPrint.h" #include "Common/Cpp/Filesystem/Filesystem.h" #include "CommonFramework/GlobalAutoPaths.h" +#include "CommonFramework/Exceptions/OperationFailedException.h" #include "CommonFramework/Exceptions/OperationFailedExceptionWithScreenshot.h" #include "CommonFramework/VideoPipeline/VideoFeed.h" #include "StepTrace.h" @@ -16,13 +19,40 @@ namespace PokemonAutomation{ StepTrace::StepTrace(VideoStream& stream, std::string label) - : m_stream(stream) + : m_stream(&stream) , m_label(std::move(label)) , m_folder(SCREENSHOTS_PATH() + "StepTrace/" + now_to_filestring() + "-" + m_label + "/") , m_start(current_time()) { Filesystem::create_directories(Filesystem::Path(m_folder)); - m_stream.log("[" + m_label + "] Trace screenshots: " + m_folder); + log("[" + m_label + "] Trace screenshots: " + m_folder); +} + +StepTrace::StepTrace(std::string label, std::function log) + : m_log(std::move(log)) + , m_label(std::move(label)) + , m_start(current_time()) +{} + +void StepTrace::log(const std::string& line) const{ + if (m_stream != nullptr){ + m_stream->log(line); + }else if (m_log){ + m_log(line); + } +} + +std::string StepTrace::save_screenshot(const std::string& name) const{ + if (m_stream == nullptr){ + return "(no video)"; + } + const std::string path = m_folder + std::format("{:03}-", m_count) + name + ".png"; + VideoSnapshot screen = m_stream->video().snapshot(); + if (!screen){ + return "(no video frame)"; + } + screen.frame->save(path); + return path; } void StepTrace::screen(const std::string& name){ @@ -36,19 +66,13 @@ void StepTrace::screen(const std::string& name){ } m_count++; const double seconds = std::chrono::duration(current_time() - m_start).count(); - std::string path = m_folder + std::format("{:03}-", m_count) + name + ".png"; - VideoSnapshot screen = m_stream.video().snapshot(); - if (screen){ - screen.frame->save(path); - }else{ - path = "(no video frame)"; - } - m_stream.log("[" + m_label + "] screen " + std::to_string(m_count) + ": " + name + + const std::string path = save_screenshot(name); + log("[" + m_label + "] screen " + std::to_string(m_count) + ": " + name + " at " + tostr_fixed(seconds, 1) + "s, " + path); } void StepTrace::action(const std::string& what){ - m_stream.log("[" + m_label + "] " + what); + log("[" + m_label + "] " + what); } std::string StepTrace::recent_screens() const{ @@ -60,10 +84,16 @@ std::string StepTrace::recent_screens() const{ } void StepTrace::fail(const std::string& message) const{ + if (m_stream == nullptr){ + throw OperationFailedException( + ErrorReportMode::NO_ERROR_REPORT, + m_label + ": " + message + " Recent screens: " + recent_screens() + "." + ); + } OperationFailedExceptionWithScreenshot::fire( ErrorReportMode::SEND_ERROR_REPORT, m_label + ": " + message + " Recent screens: " + recent_screens() + ". Trace: " + m_folder, - m_stream + *m_stream ); } diff --git a/SerialPrograms/Source/CommonTools/ScreenMachine/StepTrace.h b/SerialPrograms/Source/CommonTools/ScreenMachine/StepTrace.h index ef266ff69d..7b125a37cf 100644 --- a/SerialPrograms/Source/CommonTools/ScreenMachine/StepTrace.h +++ b/SerialPrograms/Source/CommonTools/ScreenMachine/StepTrace.h @@ -4,7 +4,9 @@ * * A step log for closed-loop routines: every change of recognized screen is * logged and saved as a numbered screenshot, every input is logged, and a - * failure reports the screens that led up to it. + * failure reports the screens that led up to it. A trace of observations + * (ScreenObservation.h), which may come from a simulation, logs the same + * lines with no screenshots. * */ @@ -12,6 +14,7 @@ #define PokemonAutomation_CommonTools_StepTrace_H #include +#include #include #include "Common/Cpp/Time.h" #include "CommonFramework/Tools/VideoStream.h" @@ -25,6 +28,9 @@ class StepTrace{ // Screenshots go to /StepTrace/