diff --git a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryPreflight.cpp b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryPreflight.cpp new file mode 100644 index 0000000000..2b56c6b435 --- /dev/null +++ b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryPreflight.cpp @@ -0,0 +1,102 @@ +/* AutoStory Story Preflight + * + * From: https://github.com/PokemonAutomation/ + * + */ + +#include +#include +#include +#include "Common/Cpp/Time.h" +#include "CommonFramework/ImageTools/FloatPixel.h" +#include "CommonFramework/ImageTools/ImageBoxes.h" +#include "CommonFramework/ImageTools/ImageStats.h" +#include "CommonFramework/VideoPipeline/VideoFeed.h" +#include "CommonTools/Images/SolidColorTest.h" +#include "NintendoSwitch/Inference/NintendoSwitch_HomeMenuDetector.h" +#include "Pokemon_StoryPreflight.h" + +namespace PokemonAutomation{ +namespace Pokemon{ + +using namespace std::chrono_literals; + + +namespace{ + +// Color bars are seven flat vertical stripes of different colors. +constexpr size_t BAR_COUNT = 7; +// A stripe flatter than this (stddev sum) is one solid color. +constexpr double BAR_MAX_STDDEV = 30; +// Two stripes this far apart (RGB distance) are different bars. +constexpr double BAR_MIN_DISTANCE = 60; +// A frame older than this is a stalled feed. +constexpr auto FRAME_MAX_AGE = 2000ms; + +bool shows_color_bars(const ImageViewRGB32& frame){ + std::array bars; + for (size_t c = 0; c < BAR_COUNT; c++){ + const double width = 1.0 / BAR_COUNT; + const ImageFloatBox stripe(c * width + width * 0.25, 0.1, width * 0.5, 0.5); + const ImageStats stats = image_stats(extract_box_reference(frame, stripe)); + if (stats.stddev.sum() > BAR_MAX_STDDEV){ + return false; + } + bars[c] = stats.average; + } + for (size_t c = 1; c < BAR_COUNT; c++){ + if (euclidean_distance(bars[c - 1], bars[c]) < BAR_MIN_DISTANCE){ + return false; + } + } + return true; +} + +bool frame_shows_picture(const ImageViewRGB32& frame){ + if (!frame){ + return false; + } + if (is_black(frame)){ + return false; + } + return !shows_color_bars(frame); +} + +} // namespace + +StoryPreflight StoryPreflight::read(NintendoSwitch::ConsoleHandle& console, NintendoSwitch::ProControllerContext& context){ + StoryPreflight preflight; + preflight.controller_ready = context.controller().is_ready(); + const VideoSnapshot snapshot = console.video().snapshot(); + const bool fresh = snapshot && current_time() - snapshot.timestamp < FRAME_MAX_AGE; + preflight.video_alive = fresh && frame_shows_picture(snapshot); + preflight.game_running = preflight.video_alive + && !NintendoSwitch::HomeMenuDetector(console, COLOR_RED).detect(snapshot); + return preflight; +} + + +Outcome StoryPreflight::check() const{ + std::string failed; + auto add = [&failed](bool ok, std::string_view what){ + if (ok){ + return; + } + if (!failed.empty()){ + failed += "; "; + } + failed += what; + }; + add(video_alive, "no live video"); + add(controller_ready, "the controller is not ready"); + add(game_running, "the game is not running"); + if (failed.empty()){ + return outcome_ok(); + } + return outcome_failed(std::string(FAILURE), failed); +} + + + +} // namespace Pokemon +} // namespace PokemonAutomation diff --git a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryPreflight.h b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryPreflight.h new file mode 100644 index 0000000000..d9aa65f158 --- /dev/null +++ b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryPreflight.h @@ -0,0 +1,50 @@ +/* AutoStory Story Preflight + * + * From: https://github.com/PokemonAutomation/ + * + * What the story run's preflight hook (StoryGameHooks::preflight) reads + * off the console before anything is pressed, and its verdict. The same + * for every game, so BDSP and FRLG lend the same reader. The start + * sequence that runs it is in Pokemon_StoryRun.h. + * + */ + +#ifndef PokemonAutomation_Pokemon_StoryPreflight_H +#define PokemonAutomation_Pokemon_StoryPreflight_H + +#include +#include "NintendoSwitch/NintendoSwitch_ConsoleHandle.h" +#include "NintendoSwitch/Controllers/Procon/NintendoSwitch_ProController.h" +#include "Pokemon_StoryOutcome.h" + +namespace PokemonAutomation{ +namespace Pokemon{ + + +// What a game reads off the console before a run presses anything. +struct StoryPreflight{ + // The failure of a preflight that failed: the console or its setup, + // not the story. Nothing answers it with a reload or a recovery. + static constexpr std::string_view FAILURE = "precondition_failed"; + + // Frames are arriving and show a picture (not black, not color bars). + bool video_alive = false; + bool controller_ready = false; + // The game is on screen, not the Switch's HOME menu. + bool game_running = false; + + // outcome_ok() when every check passed, else FAILURE naming each + // check that failed. + Outcome check() const; + + // Reads the console: a frame newer than two seconds that shows a + // picture (not black, not the capture card's color bars), the + // controller ready, and that frame not the HOME menu. Presses nothing. + static StoryPreflight read(NintendoSwitch::ConsoleHandle& console, NintendoSwitch::ProControllerContext& context); +}; + + + +} // namespace Pokemon +} // namespace PokemonAutomation +#endif diff --git a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryRun.cpp b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryRun.cpp index 7e7ff7c736..01f939df17 100644 --- a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryRun.cpp +++ b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryRun.cpp @@ -15,6 +15,19 @@ namespace Pokemon{ namespace{ +// "its save", "a new game", "the game as it is": for the start line. +std::string_view story_start_name(StoryStart start){ + switch (start){ + case StoryStart::NEW_GAME: + return "a new game"; + case StoryStart::LIVE: + return "the game as it is"; + case StoryStart::FROM_SAVE: + return "its save"; + } + return "?"; +} + void log_line(const std::string& line, StoryGameHooks& game){ if (game.log){ game.log(line); @@ -37,6 +50,18 @@ std::string story_verify_summary(std::string_view checkpoint, const VerifyPolicy ); } +Outcome run_story_preflight(StoryGameHooks& game){ + if (!game.preflight){ + log_line("[Story] preflight: not checked: the game has no preflight", game); + return outcome_ok(); + } + const Outcome outcome = game.preflight().check(); + if (!outcome.succeeded()){ + log_line(std::format("[Story] preflight failed, nothing pressed: {}", outcome.detail), game); + } + return outcome; +} + Outcome load_story_save(std::string_view reason, StoryGameHooks& game, RunState& state){ log_line(std::format("[Story] {}: loading the save", reason), game); Outcome outcome = game.load_save(state); @@ -58,6 +83,11 @@ Outcome load_story_save(std::string_view reason, StoryGameHooks& game, RunState& } // namespace Outcome prepare_story_start(std::string_view checkpoint, StoryStart start, StoryGameHooks& game, RunState& state){ + log_line(std::format("[Story] start: checkpoint {}, from {}", checkpoint, story_start_name(start)), game); + const Outcome preflight = run_story_preflight(game); + if (!preflight.succeeded()){ + return preflight; + } switch (start){ case StoryStart::NEW_GAME: log_line(std::format("[Story] {}: starts a new game, no save to load", checkpoint), game); diff --git a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryRun.h b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryRun.h index cfbeca7696..9215d63a1c 100644 --- a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryRun.h +++ b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryRun.h @@ -8,9 +8,19 @@ * A game lends only what really differs: how it loads its save (BDSP * resets from HOME, FRLG soft-resets) and how it checks where the save is. * - * Two rules hold for every game: + * These rules hold for every game: + * - Before anything is pressed, the game's preflight must see the video + * alive, the controller ready and the game running (not HOME). One + * that fails is the setup's failure, not the story's: nothing is + * touched. * - A run that starts at a checkpoint with a save loads that save first, - * so it never walks from wherever the game was left. + * so it never walks from wherever the game was left. There is no + * "just loaded" shortcut: a load or place check that fails stops the + * run before anything is saved. + * - The first checkpoint's own save at its start runs only for a new + * game: after a load the save is already there, and from the game as + * it is the place is unconfirmed (console B, 2026-11-11: a run on the + * HOME menu "saved" first). * - A failure leaves the game where it failed. Nothing here closes the * game; the user (or the next run from the save) resumes from there. * @@ -26,23 +36,18 @@ #include "Pokemon_StoryCheckpointTypes.h" #include "Pokemon_StoryOutcome.h" #include "Pokemon_StorySegments.h" +#include "Pokemon_StoryPreflight.h" +#include "Types/Pokemon_StoryStart.h" namespace PokemonAutomation{ namespace Pokemon{ -// How the game reaches the start checkpoint. -enum class StoryStart{ - // A new game from the title screen: there is no save. - NEW_GAME, - // The game as another program left it: nothing is loaded. - LIVE, - // The checkpoint's save, loaded first. - FROM_SAVE, -}; - // What a game lends the story run. struct StoryGameHooks{ + // Reads the console before anything else (see StoryPreflight). Without + // it the run logs that nothing was checked. + MoveOnlyFunction preflight; // Loads the last save: the game reset (from HOME or soft) and back in // the overworld. A failed Outcome says why. Act load_save; @@ -63,8 +68,11 @@ struct StoryGameHooks{ inline constexpr std::string_view STORY_LEFT_WHERE_FAILED = "AutoStory failed: the game stays where it failed."; // Gets the game to where checkpoint `checkpoint` starts, as `start` says. -// FROM_SAVE always loads the save (logging "[Story] 00.04b: loading the -// save"), checks its place and rereads it, and sets the "save_loaded" flag. +// First logs the checkpoint starting ("[Story] start: checkpoint 00.04b, +// from its save") and runs the game's preflight; one that fails returns +// StoryPreflight::FAILURE with nothing pressed. FROM_SAVE then always +// loads the save (logging "[Story] 00.04b: loading the save"), checks its +// place and rereads it, and sets the "save_loaded" flag. Outcome prepare_story_start(std::string_view checkpoint, StoryStart start, StoryGameHooks& game, RunState& state); // The runner's hooks: reload is load_story_save(); save, log and status diff --git a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryRun_Tests.cpp b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryRun_Tests.cpp index dd5ecc7a33..a45f39b5a4 100644 --- a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryRun_Tests.cpp +++ b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryRun_Tests.cpp @@ -19,6 +19,7 @@ namespace{ // A game that records what the story run asked of it. struct FakeGame{ + StoryPreflight preflight{.video_alive = true, .controller_ready = true, .game_running = true}; std::string place_error; size_t loads = 0; size_t rereads = 0; @@ -27,6 +28,9 @@ struct FakeGame{ StoryGameHooks hooks(){ StoryGameHooks game; + game.preflight = [this]{ + return preflight; + }; game.load_save = [this](RunState&){ loads++; return outcome_ok(); @@ -58,39 +62,70 @@ struct FakeGame{ }; // A start as the program asks for it, and what the game must have done. -struct StartCase{ +struct StartInput{ std::string name; StoryStart start; std::string place_error; + StoryPreflight preflight; +}; +struct StartExpectation{ bool succeeds; size_t loads; size_t rereads; bool save_loaded; }; +struct StartCase{ + StartInput input; + StartExpectation expectation; +}; + +constexpr StoryPreflight READY{.video_alive = true, .controller_ready = true, .game_running = true}; +constexpr StoryPreflight ON_HOME{.video_alive = true, .controller_ready = true, .game_running = false}; +constexpr StoryPreflight NO_VIDEO{.video_alive = false, .controller_ready = true, .game_running = true}; +constexpr StoryPreflight NO_CONTROLLER{.video_alive = true, .controller_ready = false, .game_running = true}; + +std::string_view start_name(StoryStart start){ + switch (start){ + case StoryStart::NEW_GAME: + return "a new game"; + case StoryStart::LIVE: + return "the game as it is"; + case StoryStart::FROM_SAVE: + return "its save"; + } + return "?"; +} class Test_StoryStart : public UnitTest{ public: Test_StoryStart(StartCase test_case) - : UnitTest(std::format("Pokemon::StoryRun - start: {}", test_case.name)) + : UnitTest(std::format("Pokemon::StoryRun - start: {}", test_case.input.name)) , m_case(std::move(test_case)) {} virtual UnitTestResult run(Logger&, CancellableScope&) const override{ FakeGame fake; - fake.place_error = m_case.place_error; + fake.place_error = m_case.input.place_error; + fake.preflight = m_case.input.preflight; StoryGameHooks game = fake.hooks(); RunState state; - const Outcome outcome = prepare_story_start("00.04b", m_case.start, game, state); + const Outcome outcome = prepare_story_start("00.04b", m_case.input.start, game, state); const bool save_loaded = state.flags.contains("save_loaded"); - if (outcome.succeeded() != m_case.succeeds || fake.loads != m_case.loads - || fake.rereads != m_case.rereads || save_loaded != m_case.save_loaded + if (outcome.succeeded() != m_case.expectation.succeeds || fake.loads != m_case.expectation.loads + || fake.rereads != m_case.expectation.rereads || save_loaded != m_case.expectation.save_loaded ){ return std::format( "Expected ok={} loads={} rereads={} save_loaded={}, got {} {} {} {} ({})", - m_case.succeeds, m_case.loads, m_case.rereads, m_case.save_loaded, + m_case.expectation.succeeds, m_case.expectation.loads, m_case.expectation.rereads, m_case.expectation.save_loaded, outcome.succeeded(), fake.loads, fake.rereads, save_loaded, to_string(outcome) ); } + if (!fake.logged(std::format("[Story] start: checkpoint 00.04b, from {}", start_name(m_case.input.start)))){ + return "Expected the line naming the checkpoint that starts"; + } + if (!m_case.input.preflight.game_running && outcome.failure != StoryPreflight::FAILURE){ + return std::format("Expected {}, got {}", StoryPreflight::FAILURE, to_string(outcome)); + } return true; } @@ -101,10 +136,126 @@ class Test_StoryStart : public UnitTest{ const StartCase START_CASES[] = { // Console B, 2026-11-11: a BDSP run started at 00.04b with the game // left at 00.04d walked from 00.04d's position. - {"a checkpoint with a save loads it first", StoryStart::FROM_SAVE, "", true, 1, 1, true}, - {"a save in the wrong place fails before rereading it", StoryStart::FROM_SAVE, "The save is in Pewter City.", false, 1, 0, false}, - {"a new game loads nothing", StoryStart::NEW_GAME, "", true, 0, 0, false}, - {"a live start loads nothing", StoryStart::LIVE, "", true, 0, 0, false}, + { + .input = {.name = "a checkpoint with a save loads it first", .start = StoryStart::FROM_SAVE, .place_error = "", .preflight = READY}, + .expectation = {.succeeds = true, .loads = 1, .rereads = 1, .save_loaded = true}, + }, + { + .input = {.name = "a save in the wrong place fails before rereading it", .start = StoryStart::FROM_SAVE, .place_error = "The save is in Pewter City.", .preflight = READY}, + .expectation = {.succeeds = false, .loads = 1, .rereads = 0, .save_loaded = false}, + }, + { + .input = {.name = "a new game loads nothing", .start = StoryStart::NEW_GAME, .place_error = "", .preflight = READY}, + .expectation = {.succeeds = true, .loads = 0, .rereads = 0, .save_loaded = false}, + }, + { + .input = {.name = "a live start loads nothing", .start = StoryStart::LIVE, .place_error = "", .preflight = READY}, + .expectation = {.succeeds = true, .loads = 0, .rereads = 0, .save_loaded = false}, + }, + // Console B, 2026-11-11 13:32: the game was on HOME; the run saved, + // pressed X/R/ZL on HOME, then "loaded" nothing. The preflight stops it + // before any press. + { + .input = {.name = "the HOME menu stops the run before the load", .start = StoryStart::FROM_SAVE, .place_error = "", .preflight = ON_HOME}, + .expectation = {.succeeds = false, .loads = 0, .rereads = 0, .save_loaded = false}, + }, + { + .input = {.name = "the HOME menu stops a live start", .start = StoryStart::LIVE, .place_error = "", .preflight = ON_HOME}, + .expectation = {.succeeds = false, .loads = 0, .rereads = 0, .save_loaded = false}, + }, + { + .input = {.name = "dead video stops the run before the load", .start = StoryStart::FROM_SAVE, .place_error = "", .preflight = NO_VIDEO}, + .expectation = {.succeeds = false, .loads = 0, .rereads = 0, .save_loaded = false}, + }, + { + .input = {.name = "a controller not ready stops the run before the load", .start = StoryStart::FROM_SAVE, .place_error = "", .preflight = NO_CONTROLLER}, + .expectation = {.succeeds = false, .loads = 0, .rereads = 0, .save_loaded = false}, + }, +}; + + +// A preflight's checks, and the failure it reads as: the setup's, not +// the story's, naming every check that failed. +struct PreflightInput{ + std::string name; + StoryPreflight preflight; +}; +struct PreflightExpectation{ + std::string outcome; +}; +struct PreflightCase{ + PreflightInput input; + PreflightExpectation expectation; +}; + +class Test_StoryPreflight : public UnitTest{ +public: + Test_StoryPreflight(PreflightCase test_case) + : UnitTest(std::format("Pokemon::StoryRun - preflight: {}", test_case.input.name)) + , m_case(std::move(test_case)) + {} + + virtual UnitTestResult run(Logger&, CancellableScope&) const override{ + const std::string got = to_string(m_case.input.preflight.check()); + if (got != m_case.expectation.outcome){ + return std::format("Expected \"{}\", got \"{}\"", m_case.expectation.outcome, got); + } + return true; + } + +private: + const PreflightCase m_case; +}; + +const PreflightCase PREFLIGHT_CASES[] = { + {.input = {.name = "a ready console passes", .preflight = READY}, .expectation = {.outcome = ""}}, + { + .input = {.name = "the HOME menu", .preflight = ON_HOME}, + .expectation = {.outcome = "precondition_failed: the game is not running"}, + }, + { + .input = {.name = "every check failed", .preflight = StoryPreflight{}}, + .expectation = {.outcome = "precondition_failed: no live video; the controller is not ready; the game is not running"}, + }, +}; + + +// Whether the first checkpoint saves at its start: only a new game's. After +// a load the save is already there; from the game as it is the place is +// unconfirmed (console B, 2026-11-11: "save" ran first on HOME). +struct FirstSaveInput{ + StoryStart start; +}; +struct FirstSaveExpectation{ + bool saves; +}; +struct FirstSaveCase{ + FirstSaveInput input; + FirstSaveExpectation expectation; +}; + +class Test_StoryFirstSave : public UnitTest{ +public: + Test_StoryFirstSave(FirstSaveCase test_case) + : UnitTest(std::format("Pokemon::StoryRun - first save: {}", start_name(test_case.input.start))) + , m_case(test_case) + {} + + virtual UnitTestResult run(Logger&, CancellableScope&) const override{ + if (story_first_save_allowed(m_case.input.start) != m_case.expectation.saves){ + return std::format("Expected saves={} from {}", m_case.expectation.saves, start_name(m_case.input.start)); + } + return true; + } + +private: + const FirstSaveCase m_case; +}; + +const FirstSaveCase FIRST_SAVE_CASES[] = { + {.input = {.start = StoryStart::NEW_GAME}, .expectation = {.saves = true}}, + {.input = {.start = StoryStart::FROM_SAVE}, .expectation = {.saves = false}}, + {.input = {.start = StoryStart::LIVE}, .expectation = {.saves = false}}, }; @@ -224,6 +375,12 @@ void add_tests_StoryRun(UnitTestDatabase& database){ for (const StartCase& test_case : START_CASES){ database.add(test_case); } + for (const PreflightCase& test_case : PREFLIGHT_CASES){ + database.add(test_case); + } + for (const FirstSaveCase& test_case : FIRST_SAVE_CASES){ + database.add(test_case); + } database.add(); database.add(); database.add(); diff --git a/SerialPrograms/Source/Pokemon/AutoStory/Types/Pokemon_StoryStart.h b/SerialPrograms/Source/Pokemon/AutoStory/Types/Pokemon_StoryStart.h new file mode 100644 index 0000000000..33ba6d9489 --- /dev/null +++ b/SerialPrograms/Source/Pokemon/AutoStory/Types/Pokemon_StoryStart.h @@ -0,0 +1,38 @@ +/* AutoStory Story Start + * + * From: https://github.com/PokemonAutomation/ + * + * How a story run reaches its start checkpoint, and what that allows. + * The start sequence itself is prepare_story_start() in Pokemon_StoryRun.h. + * + */ + +#ifndef PokemonAutomation_Pokemon_StoryStart_H +#define PokemonAutomation_Pokemon_StoryStart_H + +namespace PokemonAutomation{ +namespace Pokemon{ + + +// How the game reaches the start checkpoint. +enum class StoryStart{ + // A new game from the title screen: there is no save. + NEW_GAME, + // The game as another program left it: nothing is loaded. + LIVE, + // The checkpoint's save, loaded first. + FROM_SAVE, +}; + +// Whether the first checkpoint's own save at its start may run: only a +// new game's. After a load the save is already there, and from the game +// as it is the place is unconfirmed. +inline bool story_first_save_allowed(StoryStart start){ + return start == StoryStart::NEW_GAME; +} + + + +} // namespace Pokemon +} // namespace PokemonAutomation +#endif diff --git a/SerialPrograms/cmake/SourceFiles.cmake b/SerialPrograms/cmake/SourceFiles.cmake index 9c4fe82434..cd4fc4c225 100644 --- a/SerialPrograms/cmake/SourceFiles.cmake +++ b/SerialPrograms/cmake/SourceFiles.cmake @@ -1550,6 +1550,8 @@ file(GLOB LIBRARY_SOURCES Source/Pokemon/AutoStory/Pokemon_StoryRun.h Source/Pokemon/AutoStory/Pokemon_StoryRun_Tests.cpp Source/Pokemon/AutoStory/Pokemon_StoryRun_Tests.h + Source/Pokemon/AutoStory/Pokemon_StoryPreflight.cpp + Source/Pokemon/AutoStory/Pokemon_StoryPreflight.h Source/Pokemon/AutoStory/Pokemon_AutoStoryStats.cpp Source/Pokemon/AutoStory/Pokemon_AutoStoryStats.h Source/Pokemon/AutoStory/Pokemon_AutoStoryStats_Tests.cpp @@ -1632,6 +1634,7 @@ file(GLOB LIBRARY_SOURCES Source/Pokemon/AutoStory/Types/Pokemon_StorySaveMode.h Source/Pokemon/AutoStory/Types/Pokemon_StorySegmentTypes.cpp Source/Pokemon/AutoStory/Types/Pokemon_StorySegmentTypes.h + Source/Pokemon/AutoStory/Types/Pokemon_StoryStart.h Source/Pokemon/AutoStory/Types/Pokemon_StoryStep.h Source/Pokemon/AutoStory/Types/Pokemon_StoryStepKind.cpp Source/Pokemon/AutoStory/Types/Pokemon_StoryStepKind.h