diff --git a/.github/workflows/cpp-ci-serial-programs-base.yml b/.github/workflows/cpp-ci-serial-programs-base.yml index 412df7d233..c5cfb7f032 100644 --- a/.github/workflows/cpp-ci-serial-programs-base.yml +++ b/.github/workflows/cpp-ci-serial-programs-base.yml @@ -245,9 +245,9 @@ jobs: uses: actions/checkout@v7 if: inputs.run-tests with: - # The fork's fixtures: upstream's plus the SystemKeyboardDetector and HomeTileReader screenshots. + # The fork's fixtures: upstream's plus the SystemKeyboardDetector, HomeTileReader and PLZA AutoStory frames. repository: 'dayfine/CommandLineTests' - ref: 'eae4697738d5fe18975e77c05a4e01216bed68e7' + ref: '0195f3b0c6ffb15bf6df176cfd3a64d781346fcf' path: 'CommandLineTests' # The unit tests assume the downloadable resources they need are already downloaded diff --git a/.github/workflows/story-data.yml b/.github/workflows/story-data.yml index 8576b19548..045f398256 100644 --- a/.github/workflows/story-data.yml +++ b/.github/workflows/story-data.yml @@ -15,7 +15,7 @@ jobs: with: repository: dayfine/PokemonSimulation # Synthetic contract cases, not an approved map/resource pin. - ref: 866613fa03e5c4a5eb7e57c91b59fafb44fc7ee3 + ref: 4e023f3d57022c68018f95f6fc0a4c0722d53adf path: publisher - uses: actions/setup-python@v6 with: @@ -28,3 +28,7 @@ jobs: - 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/CommonTools/ScreenEvents/ScreenEventTypes.h b/SerialPrograms/Source/CommonTools/ScreenEvents/ScreenEventTypes.h index 73b4b12a77..e9d05d5052 100644 --- a/SerialPrograms/Source/CommonTools/ScreenEvents/ScreenEventTypes.h +++ b/SerialPrograms/Source/CommonTools/ScreenEvents/ScreenEventTypes.h @@ -36,6 +36,7 @@ enum class ScreenEvent : uint8_t{ }; // How many ScreenEvent values there are. constexpr size_t SCREEN_EVENT_COUNT = 11; +static_assert((size_t)ScreenEvent::SWITCH_HOME_MENU + 1 == SCREEN_EVENT_COUNT, "SWITCH_HOME_MENU is the last ScreenEvent"); // "dialog box", for the log. std::string screen_event_name(ScreenEvent event); diff --git a/SerialPrograms/Source/CommonTools/ScreenEvents/ScreenEvents.cpp b/SerialPrograms/Source/CommonTools/ScreenEvents/ScreenEvents.cpp index 8269377758..d063dd3c56 100644 --- a/SerialPrograms/Source/CommonTools/ScreenEvents/ScreenEvents.cpp +++ b/SerialPrograms/Source/CommonTools/ScreenEvents/ScreenEvents.cpp @@ -8,6 +8,7 @@ #include #include "CommonFramework/ImageTools/ImageBoxes.h" #include "CommonFramework/ImageTools/ImageStats.h" +#include "CommonTools/Images/SolidColorTest.h" #include "ScreenEventLog.h" #include "ScreenEventTypes.h" #include "ScreenFades.h" @@ -97,12 +98,18 @@ std::string describe(const ScreenEvents& events, std::string_view separator){ } +// Black is is_black() (SolidColorTest, BlackScreenDetector's test) with +// the fade's thresholds. +// White is not is_white(): that also wants an even grey, and a fade to +// white can be tinted. WarpFade fade_of(const ImageStats& middle){ + if (is_black(middle, FADE_MAX_DARK_SUM, FADE_MAX_STDDEV_SUM)){ + return WarpFade::BLACK; + } 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; + return middle.average.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)))); diff --git a/SerialPrograms/Source/CommonTools/ScreenEvents/ScreenEvents_Tests.cpp b/SerialPrograms/Source/CommonTools/ScreenEvents/ScreenEvents_Tests.cpp index 14a1483558..7b61ab9227 100644 --- a/SerialPrograms/Source/CommonTools/ScreenEvents/ScreenEvents_Tests.cpp +++ b/SerialPrograms/Source/CommonTools/ScreenEvents/ScreenEvents_Tests.cpp @@ -11,8 +11,10 @@ #include #include #include +#include "Common/Cpp/Time.h" #include "Common/Cpp/TestRunners/UnitTest.h" #include "CommonFramework/ImageTypes/ImageRGB32.h" +#include "ScreenEventLog.h" #include "ScreenEventTypes.h" #include "ScreenFades.h" #include "ScreenEvents.h" @@ -179,10 +181,99 @@ const ScreenEventsCase SCREEN_EVENTS_CASES[] = { }, }; +namespace{ + +// A stream of frames into a ScreenEventLog, and its describe() text. +struct ScreenEventLogCase{ + struct Frame{ + int ms = 0; + std::vector events; + }; + struct Input{ + size_t capacity = 0; + std::vector frames; + }; + struct Expectation{ + // describe() of the log, times from the first frame. + std::string text; + size_t dropped = 0; + }; + + std::string name; + Input input; + Expectation expectation; +}; + +class Test_ScreenEventLog : public UnitTest{ +public: + explicit Test_ScreenEventLog(ScreenEventLogCase test_case) + : UnitTest(std::format("CommonTools::ScreenEventLog - {}", test_case.name)) + , m_case(std::move(test_case)) + {} + virtual UnitTestResult run(Logger&, CancellableScope&) const override{ + ScreenEventLog log(m_case.input.capacity); + const WallClock origin = current_time(); + for (const ScreenEventLogCase::Frame& frame : m_case.input.frames){ + ScreenEvents events; + for (ScreenEvent event : frame.events){ + events.set(event, true); + } + log.record(events, origin + Milliseconds(frame.ms)); + } + if (log.dropped() != m_case.expectation.dropped){ + return std::format("dropped(): expected {}, got {}", m_case.expectation.dropped, log.dropped()); + } + return expect_equal("describe()", describe(log, origin), m_case.expectation.text); + } + +private: + ScreenEventLogCase m_case; +}; + +} // namespace + +const ScreenEventLogCase SCREEN_EVENT_LOG_CASES[] = { + { + .name = "no frames", + .input = {.capacity = 8, .frames = {}}, + .expectation = {.text = "no changes", .dropped = 0}, + }, + { + .name = "the first frame's events all rise", + .input = {.capacity = 8, .frames = {{.ms = 0, .events = {ScreenEvent::DIALOG_BOX, ScreenEvent::SCREEN_STILL}}}}, + .expectation = {.text = "+0 ms dialog box rose\n+0 ms screen still rose\n", .dropped = 0}, + }, + { + .name = "only changes are kept, rising and falling", + .input = {.capacity = 8, .frames = { + {.ms = 0, .events = {ScreenEvent::PLAYER_CAN_MOVE}}, + {.ms = 100, .events = {ScreenEvent::PLAYER_CAN_MOVE}}, + {.ms = 200, .events = {ScreenEvent::FADE_BLACK}}, + {.ms = 900, .events = {}}, + }}, + .expectation = { + .text = "+0 ms player can move rose\n+200 ms black fade rose\n+200 ms player can move fell\n+900 ms black fade fell\n", + .dropped = 0, + }, + }, + { + .name = "the oldest changes drop past the capacity", + .input = {.capacity = 2, .frames = { + {.ms = 0, .events = {ScreenEvent::DIALOG_BOX}}, + {.ms = 100, .events = {}}, + {.ms = 200, .events = {ScreenEvent::CHOICE_BOX}}, + }}, + .expectation = {.text = "(1 older changes dropped)\n+100 ms dialog box fell\n+200 ms choice box rose\n", .dropped = 1}, + }, +}; + void add_tests_ScreenEvents(UnitTestDatabase& database){ for (const auto& item : SCREEN_EVENTS_CASES){ database.add(item); } + for (const auto& item : SCREEN_EVENT_LOG_CASES){ + database.add(item); + } } diff --git a/SerialPrograms/Source/Pokemon/AutoStory/Data/Pokemon_AuthoredCheckpointJson_Tests.cpp b/SerialPrograms/Source/Pokemon/AutoStory/Data/Pokemon_AuthoredCheckpointJson_Tests.cpp index ae61bbc538..94f31cf0f0 100644 --- a/SerialPrograms/Source/Pokemon/AutoStory/Data/Pokemon_AuthoredCheckpointJson_Tests.cpp +++ b/SerialPrograms/Source/Pokemon/AutoStory/Data/Pokemon_AuthoredCheckpointJson_Tests.cpp @@ -34,8 +34,8 @@ enum class Failure{ }; struct AuthoredCase{ + std::string name; struct Input{ - std::string name; std::string json; std::string game = "frlg"; bool resource = false; @@ -54,21 +54,21 @@ struct AuthoredCase{ }; const AuthoredCase CASES[] = { - {.input = {.name = "FRLG envelope", .json = FRLG}, .expectation = {}}, - {.input = {.name = "BDSP embedded resource", .json = BDSP, .game = "bdsp", .resource = true}, .expectation = { + {.name = "FRLG envelope", .input = {.json = FRLG}, .expectation = {}}, + {.name = "BDSP embedded resource", .input = {.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 = { + {.name = "FRLG embedded resource", .input = {.json = FRLG, .resource = true}, .expectation = {}}, + {.name = "wrong game", .input = {.json = BDSP}, .expectation = {.failure = Failure::PARSE}}, + {.name = "empty expected game", .input = {.json = FRLG, .game = ""}, .expectation = {.failure = Failure::PARSE}}, + {.name = "missing resource", .input = {.json = FRLG, .resource = true, .file = "absent"}, .expectation = {.failure = Failure::MISSING_RESOURCE}}, + {.name = "invalid embedded JSON", .input = {.json = "{", .resource = true}, .expectation = {.failure = Failure::PARSE}}, + {.name = "wrong format", .input = {.json = R"({"format":"future","game":"frlg","checkpoint":{},"execution":{}})"}, .expectation = {.failure = Failure::PARSE}}, + {.name = "missing execution", .input = {.json = R"({"format":"pokesim-authored-checkpoint/1","game":"frlg","checkpoint":{}})"}, .expectation = {.failure = Failure::PARSE}}, + {.name = "same count wrong field", .input = {.json = R"({"format":"pokesim-authored-checkpoint/1","game":"frlg","checkpoint":{},"extra":{}})"}, .expectation = {.failure = Failure::PARSE}}, + {.name = "extra envelope field", .input = {.json = R"({"format":"pokesim-authored-checkpoint/1","game":"frlg","checkpoint":{},"execution":{},"extra":0})"}, .expectation = {.failure = Failure::PARSE}}, + {.name = "execution must be object", .input = {.json = R"({"format":"pokesim-authored-checkpoint/1","game":"frlg","checkpoint":{"id":"x","title":"X","events":[]},"execution":false})"}, .expectation = {.failure = Failure::PARSE}}, + {.name = "invalid common action", .input = {.json = R"({"format":"pokesim-authored-checkpoint/1","game":"frlg","checkpoint":{"id":"x","title":"X","events":[{"id":"bad","kind":"magic"}]},"execution":{}})"}, .expectation = {.failure = Failure::PARSE}}, + {.name = "execution stays game owned", .input = {.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 = {}}}, }; @@ -116,7 +116,7 @@ std::string check_case(const AuthoredCase& test){ Loaded actual; actual.checkpoint = test.input.resource ? load_authored_checkpoint(files, test.input.file, test.input.game, keep_execution(actual.execution)) - : read_authored_checkpoint(parse_json(test.input.json), test.input.game, test.input.name, keep_execution(actual.execution)); + : read_authored_checkpoint(parse_json(test.input.json), test.input.game, test.name, keep_execution(actual.execution)); return check_loaded(actual, test); }catch (const ParseException& error){ return test.expectation.failure == Failure::PARSE ? "" : std::format("Unexpected parse failure: {}", error.message()); @@ -131,7 +131,7 @@ std::string check_case(const AuthoredCase& test){ class AuthoredJsonTest : public UnitTest{ public: explicit AuthoredJsonTest(AuthoredCase test) - : UnitTest(std::format("Pokemon::AuthoredCheckpointJson - {}", test.input.name)) + : UnitTest(std::format("Pokemon::AuthoredCheckpointJson - {}", test.name)) , m_case(std::move(test)) {} @@ -172,7 +172,7 @@ 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'; + std::cout << test.name << ": " << (error.empty() ? "PASS" : error) << '\n'; failed += !error.empty(); } return failed != 0; diff --git a/SerialPrograms/Source/VideoGames/PokemonLZA/Programs/AutoStory/PokemonLZA_AutoStoryDevFiles.cpp b/SerialPrograms/Source/Pokemon/AutoStory/Data/Pokemon_StoryDevFiles.cpp similarity index 55% rename from SerialPrograms/Source/VideoGames/PokemonLZA/Programs/AutoStory/PokemonLZA_AutoStoryDevFiles.cpp rename to SerialPrograms/Source/Pokemon/AutoStory/Data/Pokemon_StoryDevFiles.cpp index 56d4ada553..8da82c99d2 100644 --- a/SerialPrograms/Source/VideoGames/PokemonLZA/Programs/AutoStory/PokemonLZA_AutoStoryDevFiles.cpp +++ b/SerialPrograms/Source/Pokemon/AutoStory/Data/Pokemon_StoryDevFiles.cpp @@ -1,4 +1,4 @@ -/* PokemonLZA AutoStory - Dev checkpoint files +/* Story Dev Files * * From: https://github.com/PokemonAutomation/ * @@ -8,22 +8,23 @@ #include "Common/Cpp/Filesystem/FileIO.h" #include "Common/Cpp/Filesystem/Filesystem.h" #include "CommonFramework/GlobalAutoPaths.h" -#include "PokemonLZA_AutoStoryDevFiles.h" +#include "Pokemon_StoryDevFiles.h" namespace PokemonAutomation{ -namespace NintendoSwitch{ -namespace PokemonLZA{ +namespace Pokemon{ -std::string story_dev_folder(){ - return std::format("{}AutoStoryDev/plza/", USER_FILE_PATH()); +std::string story_dev_folder(std::string_view game){ + return std::format("{}AutoStoryDev/{}/", USER_FILE_PATH(), game); } -std::vector read_story_dev_files(std::string_view folder){ +std::vector read_story_dev_files(std::string_view folder, std::string_view game){ + const Filesystem::Path directory(std::string{folder}); std::vector files; - for (const Filesystem::Path& path : Filesystem::list_directory(Filesystem::Path(std::string(folder)))){ + const std::string prefix = std::format("{}-", game); + for (const Filesystem::Path& path : Filesystem::list_directory(directory)){ const std::string name = path.filename().string(); - if (!name.starts_with("plza-") || !name.ends_with(".plan.json") || !Filesystem::is_regular_file(path)){ + if (!name.starts_with(prefix) || !name.ends_with(".plan.json") || !Filesystem::is_regular_file(path)){ continue; } files.push_back({.name = name, .path = path.string(), .text = file_to_string(path.string())}); @@ -33,6 +34,5 @@ std::vector read_story_dev_files(std::string_view folder){ -} // namespace PokemonLZA -} // namespace NintendoSwitch +} // namespace Pokemon } // namespace PokemonAutomation diff --git a/SerialPrograms/Source/Pokemon/AutoStory/Data/Pokemon_StoryDevFiles.h b/SerialPrograms/Source/Pokemon/AutoStory/Data/Pokemon_StoryDevFiles.h new file mode 100644 index 0000000000..fd572d6567 --- /dev/null +++ b/SerialPrograms/Source/Pokemon/AutoStory/Data/Pokemon_StoryDevFiles.h @@ -0,0 +1,41 @@ +/* Story Dev Files + * + * From: https://github.com/PokemonAutomation/ + * + * For lab tuning: checkpoint files on disk that a run reads in place of + * the built-in ones of the same name (load_story_data() in + * Pokemon_StoryFiles.h), so a walk can be retimed without a rebuild. + * + */ + +#ifndef PokemonAutomation_Pokemon_StoryDevFiles_H +#define PokemonAutomation_Pokemon_StoryDevFiles_H + +#include +#include +#include + +namespace PokemonAutomation{ +namespace Pokemon{ + + +// A checkpoint file read from disk. +struct StoryDevFile{ + std::string name; // "plza-02.01.plan.json" + std::string path; + std::string text; +}; + +// The folder whose checkpoint files replace `game`'s built-in ones: +// /AutoStoryDev// (USER_FILE_PATH()). +std::string story_dev_folder(std::string_view game); + +// The -*.plan.json files in `folder`, by name; none if it does not +// exist. +std::vector read_story_dev_files(std::string_view folder, std::string_view game); + + + +} // namespace Pokemon +} // namespace PokemonAutomation +#endif diff --git a/SerialPrograms/Source/Pokemon/AutoStory/Data/Pokemon_StoryFiles.cpp b/SerialPrograms/Source/Pokemon/AutoStory/Data/Pokemon_StoryFiles.cpp new file mode 100644 index 0000000000..3c958c9feb --- /dev/null +++ b/SerialPrograms/Source/Pokemon/AutoStory/Data/Pokemon_StoryFiles.cpp @@ -0,0 +1,127 @@ +/* Story Files + * + * From: https://github.com/PokemonAutomation/ + * + */ + +#include +#include "Pokemon_StoryFiles.h" + +namespace PokemonAutomation{ +namespace Pokemon{ +namespace detail{ + + +void check_dev_file_names(std::span builtin, std::span dev_files){ + for (const StoryDevFile& dev : dev_files){ + bool known = false; + for (const auto& [name, text] : builtin){ + known |= dev.name == std::format("{}.json", name); + } + if (!known){ + throw ParseException(std::format("{}: no built-in checkpoint file is named {}", dev.path, dev.name)); + } + } +} + +const StoryDevFile* find_dev_file(std::span dev_files, std::string_view builtin_name){ + const std::string file_name = std::format("{}.json", builtin_name); + for (const StoryDevFile& file : dev_files){ + if (file.name == file_name){ + return &file; + } + } + return nullptr; +} + +ParseException naming_path(const ParseException& error, std::string_view path){ + const std::string message = error.message(); + if (message.find(path) != std::string::npos){ + return error; + } + return ParseException(std::format("{}: {}", path, message)); +} + +void check_dev_checkpoint( + std::string_view path, std::string_view id, std::string_view builtin_id, const std::vector& problems +){ + if (id != builtin_id){ + throw ParseException(std::format("{}: checkpoint id {} does not match the built-in {}", path, id, builtin_id)); + } + if (!problems.empty()){ + throw ParseException(std::format("{}: {}", path, problems.front())); + } +} + +void check_in_story_order( + const std::function& in_story_order, std::string_view id, std::string_view source +){ + if (in_story_order && !in_story_order(id)){ + throw ParseException(std::format("{}: checkpoint {} is not in the game's story order", source, id)); + } +} + +namespace{ + +// Which row sequence the reload check applies to. +enum class RunKind{ + DEVELOPER, + USER, +}; + +// Text naming `run` in a reload error. +std::string_view run_suffix(RunKind run){ + switch (run){ + case RunKind::DEVELOPER: + return ""; + case RunKind::USER: + return " in a user's run"; + } + throw InternalProgramError(nullptr, PA_CURRENT_FUNCTION, "Unknown story run kind."); +} + +// Throws ParseException naming `source` unless `previous` ends on the +// game's autosave in `rows`, for `run`. +void check_reload_after( + std::optional previous, const StoryRows& rows, RunKind run, std::string_view source +){ + if (!previous || !rows.autosaves.contains(*previous)){ + throw ParseException(std::format( + "{}: reload_when_chained after a checkpoint that does not end on the game's autosave{}: the reload would load an older save", + source, run_suffix(run) + )); + } +} + +} // namespace + +void add_story_row( + std::string_view id, const StoryRowExecution& execution, RowSave start, + const PreviousRows& previous, std::string_view source, StoryRows& rows +){ + if (execution.reload != StoryReload::NEVER){ + if (start == RowSave::WITHOUT_SAVE){ + throw ParseException(std::format("{}: reload_when_chained on a checkpoint with no save to reload", source)); + } + check_reload_after(previous.in_dev_run, rows, RunKind::DEVELOPER, source); + if (!execution.dev_only && previous.in_user_run != previous.in_dev_run){ + check_reload_after(previous.in_user_run, rows, RunKind::USER, source); + } + rows.reload_when_chained.emplace(id); + } + if (execution.reload == StoryReload::ALWAYS){ + rows.reload_always.emplace(id); + } + if (execution.autosave){ + rows.autosaves.emplace(id); + } + if (execution.dev_only){ + rows.dev_only.emplace(id); + } +} + + + +} // namespace detail +} // namespace Pokemon +} // namespace PokemonAutomation diff --git a/SerialPrograms/Source/Pokemon/AutoStory/Data/Pokemon_StoryFiles.h b/SerialPrograms/Source/Pokemon/AutoStory/Data/Pokemon_StoryFiles.h new file mode 100644 index 0000000000..f6d2b1da3a --- /dev/null +++ b/SerialPrograms/Source/Pokemon/AutoStory/Data/Pokemon_StoryFiles.h @@ -0,0 +1,238 @@ +/* Story Files + * + * From: https://github.com/PokemonAutomation/ + * + * A game's story read from its checkpoint files: the checked-in ones, + * built into the program (cmake/EmbedTextFiles.cmake), each replaced by + * the dev file of the same name if there is one (Pokemon_StoryDevFiles.h), + * so a walk can be retimed on the console without a rebuild. The game + * reads each file into its own checkpoint type; this reads the shared + * execution fields (Pokemon_StoryRowExecution.h) into the rows they mark, + * and checks what holds for every game: a dev file replaces a built-in + * file, keeps its checkpoint's id and passes the game's lint, and a row + * reloads only a save it can count on. + * + */ + +#ifndef PokemonAutomation_Pokemon_StoryFiles_H +#define PokemonAutomation_Pokemon_StoryFiles_H + +#include +#include +#include +#include +#include +#include +#include +#include "Common/Cpp/Exceptions.h" +#include "Pokemon_AuthoredCheckpointJson.h" +#include "Pokemon_StoryDevFiles.h" +#include "Pokemon_StoryRowExecution.h" + +namespace PokemonAutomation{ +namespace Pokemon{ + + +// What a game reads from one checkpoint file. +template +struct StoryFileRow{ + Checkpoint checkpoint; + StoryRowExecution execution; +}; + +// How a game reads its checkpoint files. +template +struct StoryFileReader{ + // The file `text`'s checkpoint and shared execution fields + // (read_story_row_execution()); `source` names the file in errors. + // Throws ParseException when it is malformed. + std::function(std::string_view text, std::string_view source)> read; + // The problems the game finds in a dev file's checkpoint; the first + // one refuses the file. None set: no lint. + std::function(const Checkpoint&)> lint = {}; + // Whether a row starts with no save to load (a new game): it may not + // reload. None set: every row starts from a save. + std::function starts_without_save = {}; + // Whether the game plays checkpoint `a` before `b`, when that is not + // the order of its files' names. None set: file-name order. + std::function plays_before = {}; + // Whether the game's story order lists checkpoint `id`: a file whose + // id it does not list is refused, not skipped or played out of place. + // None set: the game keeps no list, and every id plays. + std::function in_story_order = {}; +}; + + +// The story of the built-in checkpoint files `builtin`, in their order or +// the game's (StoryFileReader::plays_before), each of `dev_files` in place +// of the built-in file of its name. Throws ParseException naming the file +// when a file does not parse, a dev file matches no built-in file, changes +// its checkpoint's id or fails the game's lint, a file's checkpoint id is +// not in the game's story order (StoryFileReader::in_story_order), or a +// row reloads a save it cannot count on in the order the story plays. +template +StoryData load_story_data( + std::span builtin, std::span dev_files, + const StoryFileReader& reader +); + +// Who a run's rows are listed for. +enum class StoryRowsShown{ + USER, // every row but the dev-only ones + DEVELOPER, // every row (the program's Developer Mode) +}; + +// The rows of `story` a run may play, in order. The start and end +// dropdowns list these, so their indices name these rows. +template +std::vector story_rows_for_mode(const StoryData& story, StoryRowsShown shown); + +// The rows a run from `first` to `last` of `rows` plays, in order. Empty +// if `first` comes after `last` or `last` is past the end. +template +std::vector story_run_rows(std::span rows, size_t first, size_t last); + + + +namespace detail{ + +// Throws ParseException naming the dev file that matches no built-in file. +void check_dev_file_names(std::span builtin, std::span dev_files); +// The dev file that replaces the built-in file `builtin_name` (its name +// without ".json"); null if none. +const StoryDevFile* find_dev_file(std::span dev_files, std::string_view builtin_name); +// `error`, its message prefixed with `path` unless it already names it. +ParseException naming_path(const ParseException& error, std::string_view path); +// Throws ParseException naming `path` when the dev file's checkpoint `id` +// is not the built-in file's `builtin_id`, or `problems` is not empty. +void check_dev_checkpoint( + std::string_view path, std::string_view id, std::string_view builtin_id, const std::vector& problems +); + +// Throws ParseException naming `source` and `id` when `in_story_order` +// is set and does not list `id`. +void check_in_story_order( + const std::function& in_story_order, std::string_view id, std::string_view source +); + +// Whether a row starts from a save, which a reload can load. +enum class RowSave{ + FROM_SAVE, + WITHOUT_SAVE, // a new game +}; + +// The rows a row follows in play: in a developer's run, and in a user's, +// which skips the dev-only rows. None for the first row. +struct PreviousRows{ + std::optional in_dev_run; + std::optional in_user_run; +}; + +// Adds row `id` to the sets of `rows`. Throws ParseException naming +// `source` when it reloads and starts WITHOUT_SAVE or a row it follows +// (`previous`: in a developer's run; and in a user's, unless it is +// dev-only itself) does not end on the game's autosave: a reload loads +// the last save, which must be that autosave. +void add_story_row( + std::string_view id, const StoryRowExecution& execution, RowSave start, + const PreviousRows& previous, std::string_view source, StoryRows& rows +); + +// The dev file `dev`'s row, in place of the built-in file `builtin_name`: +// it must parse, keep the built-in checkpoint's id and pass the lint. +template +StoryFileRow read_dev_file( + const StoryDevFile& dev, std::string_view builtin_text, std::string_view builtin_name, + const StoryFileReader& reader +){ + StoryFileRow row; + try{ + row = reader.read(dev.text, dev.path); + }catch (const ParseException& error){ + // Malformed JSON says nothing of where it came from. + throw naming_path(error, dev.path); + } + const std::string builtin_id = reader.read(builtin_text, builtin_name).checkpoint.id; + const std::vector problems = reader.lint ? reader.lint(row.checkpoint) : std::vector{}; + check_dev_checkpoint(dev.path, row.checkpoint.id, builtin_id, problems); + return row; +} + +} // namespace detail + + +template +StoryData load_story_data( + std::span builtin, std::span dev_files, + const StoryFileReader& reader +){ + detail::check_dev_file_names(builtin, dev_files); + StoryData data; + struct SourcedRow{ + StoryFileRow row; + std::string_view source; + }; + std::vector rows; + for (const auto& [name, text] : builtin){ + const StoryDevFile* dev = detail::find_dev_file(dev_files, name); + if (dev == nullptr){ + rows.push_back({reader.read(text, name), name}); + continue; + } + rows.push_back({detail::read_dev_file(*dev, text, name, reader), dev->path}); + data.dev_files.emplace_back(dev->name, dev->path); + } + for (const auto& [row, source] : rows){ + detail::check_in_story_order(reader.in_story_order, row.checkpoint.id, source); + } + if (reader.plays_before){ + std::stable_sort(rows.begin(), rows.end(), [&](const SourcedRow& a, const SourcedRow& b){ + return reader.plays_before(a.row.checkpoint, b.row.checkpoint); + }); + } + // A reload loads the save the row before it in play ends on, in a + // developer's run and in a user's. + std::optional last_user_row; + for (auto& [row, source] : rows){ + const bool new_game = reader.starts_without_save && reader.starts_without_save(row.checkpoint); + const detail::PreviousRows previous{ + .in_dev_run = data.checkpoints.empty() ? std::nullopt : std::optional(data.checkpoints.back().id), + .in_user_run = last_user_row ? std::optional(data.checkpoints[*last_user_row].id) : std::nullopt, + }; + detail::add_story_row( + row.checkpoint.id, row.execution, + new_game ? detail::RowSave::WITHOUT_SAVE : detail::RowSave::FROM_SAVE, + previous, source, data + ); + if (!row.execution.dev_only){ + last_user_row = data.checkpoints.size(); + } + data.checkpoints.push_back(std::move(row.checkpoint)); + } + return data; +} + +template +std::vector story_rows_for_mode(const StoryData& story, StoryRowsShown shown){ + std::vector rows; + for (const Checkpoint& row : story.checkpoints){ + if (shown == StoryRowsShown::DEVELOPER || !story.dev_only.contains(row.id)){ + rows.push_back(row); + } + } + return rows; +} + +template +std::vector story_run_rows(std::span rows, size_t first, size_t last){ + if (first > last || last >= rows.size()){ + return {}; + } + return std::vector(rows.begin() + first, rows.begin() + last + 1); +} + + + +} // namespace Pokemon +} // namespace PokemonAutomation +#endif diff --git a/SerialPrograms/Source/Pokemon/AutoStory/Data/Pokemon_StoryFiles_Tests.cpp b/SerialPrograms/Source/Pokemon/AutoStory/Data/Pokemon_StoryFiles_Tests.cpp new file mode 100644 index 0000000000..ab6a3c5f01 --- /dev/null +++ b/SerialPrograms/Source/Pokemon/AutoStory/Data/Pokemon_StoryFiles_Tests.cpp @@ -0,0 +1,410 @@ +/* Story Files Tests + * + * From: https://github.com/PokemonAutomation/ + * + */ + +#include +#include +#include +#include +#include +#include +#include +#include +#include "Common/Cpp/Exceptions.h" +#include "Common/Cpp/Json/JsonValue.h" +#include "Common/Cpp/TestRunners/UnitTest.h" +#include "Pokemon_StoryFiles.h" +#include "Pokemon_StoryFiles_Tests.h" + +namespace PokemonAutomation{ +namespace Pokemon{ + + +namespace{ + +// A checkpoint file of the test game: {"id", "title", "execution"}, its +// execution the shared fields and the game's own "note". Its lint refuses +// the title "unlinted"; 00.00 is its new game, which starts without a save. +std::string file_text(std::string_view id, std::string_view execution, std::string_view title = "Row"){ + return std::format(R"({{"id": "{}", "title": "{}", "execution": {}}})", id, title, execution); +} + +StoryFileRow read_test_file(std::string_view text, std::string_view source){ + const JsonValue value = parse_json(std::string(text)); + const JsonObject& object = value.to_object_throw(std::string(source)); + StoryFileRow row; + row.checkpoint.id = object.get_string_throw("id", std::string(source)); + row.checkpoint.title = object.get_string_throw("title", std::string(source)); + row.execution = read_story_row_execution(object.get_object_throw("execution", std::string(source)), source, {"note"}); + return row; +} + +const StoryFileReader TEST_READER{ + .read = read_test_file, + .lint = [](const StoryCheckpoint& checkpoint){ + return checkpoint.title == "unlinted" ? std::vector{"title is unlinted"} : std::vector{}; + }, + .starts_without_save = [](const StoryCheckpoint& checkpoint){ + return checkpoint.id == "00.00"; + }, +}; + +// "a b": the strings, space-separated. +std::string joined(const std::vector& texts){ + std::string text; + for (const std::string& part : texts){ + text += (text.empty() ? "" : " ") + part; + } + return text; +} +std::string joined(const std::set>& texts){ + return joined(std::vector(texts.begin(), texts.end())); +} + +std::vector ids(const std::vector& rows){ + std::vector result; + for (const StoryCheckpoint& row : rows){ + result.push_back(row.id); + } + return result; +} + +// "rows 01.00 01.01 | autosave 01.00 | chained 01.01 | always | dev_only | dev x.json" +std::string summary(const StoryData& data){ + std::vector dev; + for (const auto& [name, path] : data.dev_files){ + dev.push_back(std::format("{}@{}", name, path)); + } + std::vector titles; + for (const StoryCheckpoint& row : data.checkpoints){ + titles.push_back(row.title); + } + return std::format( + "rows {} | titles {} | autosave {} | chained {} | always {} | dev_only {} | dev {}", + joined(ids(data.checkpoints)), joined(titles), joined(data.autosaves), joined(data.reload_when_chained), + joined(data.reload_always), joined(data.dev_only), joined(dev) + ); +} + + +struct LoadCase{ + std::string name; + struct Input{ + std::vector builtin; + std::vector dev_files = {}; + // Whether the game plays its rows in id order, not file-name order. + bool ordered_by_id = false; + // The ids the game's story order lists; none: the game lists none. + std::optional> story_order = std::nullopt; + }; + Input input; + struct Expectation{ + // summary() of the story read; none when it fails. + std::optional summary = std::nullopt; + // What the ParseException's message contains when it fails. + std::string error = {}; + }; + Expectation expectation; +}; + +const EmbeddedJsonFile ROW_0 = {"test-01.00.plan", file_text("01.00", R"({"save": "autosave"})")}; +const EmbeddedJsonFile ROW_1 = {"test-01.01.plan", file_text("01.01", R"({"reload_when_chained": true, "note": 1})")}; +const EmbeddedJsonFile ROW_2 = {"test-01.02.plan", file_text("01.02", R"({"dev_only": true, "save": "menu"})")}; + +StoryDevFile dev_file(std::string_view name, std::string text){ + return StoryDevFile{.name = std::string(name), .path = std::format("/dev/{}", name), .text = std::move(text)}; +} + +// Named to come after 01.01 by file name, before it by id. +const EmbeddedJsonFile ROW_0B_MENU = {"test-01.10.plan", file_text("01.00b", R"({"save": "menu"})")}; + +const LoadCase LOAD_CASES[] = { + { + .name = "built-in files in order, their shared execution fields read", + .input = {.builtin = {ROW_0, ROW_1, ROW_2}}, + .expectation = {.summary = "rows 01.00 01.01 01.02 | titles Row Row Row | autosave 01.00 | chained 01.01 | always | dev_only 01.02 | dev "}, + }, + { + .name = "reload_when_chained always", + .input = {.builtin = {ROW_0, {"test-01.01.plan", file_text("01.01", R"({"reload_when_chained": "always"})")}}}, + .expectation = {.summary = "rows 01.00 01.01 | titles Row Row | autosave 01.00 | chained 01.01 | always 01.01 | dev_only | dev "}, + }, + { + .name = "a dev file replaces the built-in file of its name and is named", + .input = { + .builtin = {ROW_0, ROW_1}, + .dev_files = {dev_file("test-01.01.plan.json", file_text("01.01", R"({"reload_when_chained": true})", "Retimed"))}, + }, + .expectation = {.summary = "rows 01.00 01.01 | titles Row Retimed | autosave 01.00 | chained 01.01 | always | dev_only | dev test-01.01.plan.json@/dev/test-01.01.plan.json"}, + }, + { + .name = "a dev file that is not JSON fails naming its path", + .input = {.builtin = {ROW_0}, .dev_files = {dev_file("test-01.00.plan.json", "{ not json")}}, + .expectation = {.error = "/dev/test-01.00.plan.json"}, + }, + { + .name = "a dev file with no built-in file of its name fails", + .input = {.builtin = {ROW_0}, .dev_files = {dev_file("test-09.99.plan.json", file_text("09.99", "{}"))}}, + .expectation = {.error = "/dev/test-09.99.plan.json: no built-in checkpoint file is named test-09.99.plan.json"}, + }, + { + .name = "a dev file that changes its checkpoint's id fails", + .input = {.builtin = {ROW_0}, .dev_files = {dev_file("test-01.00.plan.json", file_text("01.09", R"({"save": "autosave"})"))}}, + .expectation = {.error = "/dev/test-01.00.plan.json: checkpoint id 01.09 does not match the built-in 01.00"}, + }, + { + .name = "a dev file the game's lint refuses fails", + .input = {.builtin = {ROW_0}, .dev_files = {dev_file("test-01.00.plan.json", file_text("01.00", "{}", "unlinted"))}}, + .expectation = {.error = "/dev/test-01.00.plan.json: title is unlinted"}, + }, + { + .name = "an unknown execution field fails", + .input = {.builtin = {{"test-01.00.plan", file_text("01.00", R"({"dev_mode": true})")}}}, + .expectation = {.error = "unknown execution field dev_mode"}, + }, + { + .name = "dev_only false fails", + .input = {.builtin = {{"test-01.00.plan", file_text("01.00", R"({"dev_only": false})")}}}, + .expectation = {.error = "dev_only is true or left out"}, + }, + { + .name = "a save other than autosave or menu fails", + .input = {.builtin = {{"test-01.00.plan", file_text("01.00", R"({"save": "card"})")}}}, + .expectation = {.error = "save is \"autosave\", \"menu\" or left out"}, + }, + { + .name = "reload_when_chained false fails", + .input = {.builtin = {ROW_0, {"test-01.01.plan", file_text("01.01", R"({"reload_when_chained": false})")}}}, + .expectation = {.error = "reload_when_chained is true, \"always\" or left out"}, + }, + { + .name = "reload_when_chained after a row that does not autosave fails", + .input = {.builtin = {{"test-01.00.plan", file_text("01.00", R"({"save": "menu"})")}, ROW_1}}, + .expectation = {.error = "test-01.01.plan: reload_when_chained after a checkpoint that does not end on the game's autosave"}, + }, + { + .name = "a dev-only reload after a dev-only autosave row, the user's row before it not autosaving, loads", + .input = {.builtin = { + {"test-01.00.plan", file_text("01.00", R"({"save": "menu"})")}, + {"test-01.005.plan", file_text("01.005", R"({"dev_only": true, "save": "autosave"})")}, + {"test-01.01.plan", file_text("01.01", R"({"dev_only": true, "reload_when_chained": true})")}, + }}, + .expectation = {.summary = "rows 01.00 01.005 01.01 | titles Row Row Row | autosave 01.005 | chained 01.01 | always | dev_only 01.005 01.01 | dev "}, + }, + { + .name = "reload_when_chained after a dev-only autosave row, the user's row before it not autosaving, fails", + .input = {.builtin = { + {"test-01.00.plan", file_text("01.00", R"({"save": "menu"})")}, + {"test-01.005.plan", file_text("01.005", R"({"dev_only": true, "save": "autosave"})")}, + ROW_1, + }}, + .expectation = {.error = "test-01.01.plan: reload_when_chained after a checkpoint that does not end on the game's autosave in a user's run"}, + }, + { + .name = "reload_when_chained after a dev-only row, both rows before it autosaving", + .input = {.builtin = { + ROW_0, + {"test-01.005.plan", file_text("01.005", R"({"dev_only": true, "save": "autosave"})")}, + ROW_1, + }}, + .expectation = {.summary = "rows 01.00 01.005 01.01 | titles Row Row Row | autosave 01.00 01.005 | chained 01.01 | always | dev_only 01.005 | dev "}, + }, + { + .name = "reload_when_chained on the first row fails", + .input = {.builtin = {ROW_1}}, + .expectation = {.error = "does not end on the game's autosave"}, + }, + { + .name = "reload_when_chained on the new game fails", + .input = {.builtin = {ROW_0, {"test-00.00.plan", file_text("00.00", R"({"reload_when_chained": true})")}}}, + .expectation = {.error = "test-00.00.plan: reload_when_chained on a checkpoint with no save to reload"}, + }, + { + .name = "the game's order, its reload after the autosave row it follows there", + .input = {.builtin = {ROW_1, ROW_0}, .ordered_by_id = true}, + .expectation = {.summary = "rows 01.00 01.01 | titles Row Row | autosave 01.00 | chained 01.01 | always | dev_only | dev "}, + }, + { + .name = "the game's order, its reload after a row that does not autosave there fails", + .input = {.builtin = {ROW_0, ROW_1, ROW_0B_MENU}, .ordered_by_id = true}, + .expectation = {.error = "test-01.01.plan: reload_when_chained after a checkpoint that does not end on the game's autosave"}, + }, + { + .name = "every id in the game's story order loads", + .input = {.builtin = {ROW_0, ROW_1}, .story_order = std::vector{"01.00", "01.01"}}, + .expectation = {.summary = "rows 01.00 01.01 | titles Row Row | autosave 01.00 | chained 01.01 | always | dev_only | dev "}, + }, + { + .name = "a built-in file whose id is not in the game's story order fails naming the file and the id", + .input = {.builtin = {ROW_0, ROW_1}, .story_order = std::vector{"01.00"}}, + .expectation = {.error = "test-01.01.plan: checkpoint 01.01 is not in the game's story order"}, + }, + { + .name = "a dev file in the game's story order replaces the built-in file", + .input = { + .builtin = {ROW_0, ROW_1}, + .dev_files = {dev_file("test-01.01.plan.json", file_text("01.01", R"({"reload_when_chained": true})", "Retimed"))}, + .story_order = std::vector{"01.00", "01.01"}, + }, + .expectation = {.summary = "rows 01.00 01.01 | titles Row Retimed | autosave 01.00 | chained 01.01 | always | dev_only | dev test-01.01.plan.json@/dev/test-01.01.plan.json"}, + }, + { + .name = "a dev file whose id is not in the game's story order fails naming its path and the id", + .input = { + .builtin = {ROW_0}, + .dev_files = {dev_file("test-01.00.plan.json", file_text("01.00", R"({"save": "autosave"})"))}, + .story_order = std::vector{"01.01"}, + }, + .expectation = {.error = "/dev/test-01.00.plan.json: checkpoint 01.00 is not in the game's story order"}, + }, +}; + +UnitTestResult check_load(const LoadCase& test){ + StoryFileReader reader = TEST_READER; + if (test.input.ordered_by_id){ + reader.plays_before = [](const StoryCheckpoint& a, const StoryCheckpoint& b){ + return a.id < b.id; + }; + } + if (test.input.story_order){ + reader.in_story_order = [&order = *test.input.story_order](std::string_view id){ + return std::find(order.begin(), order.end(), id) != order.end(); + }; + } + std::string got; + std::string error; + try{ + got = summary(load_story_data(test.input.builtin, test.input.dev_files, reader)); + }catch (const ParseException& e){ + error = e.message(); + } + if (test.expectation.summary){ + if (!error.empty()){ + return std::format("expected \"{}\", failed: {}", *test.expectation.summary, error); + } + if (got != *test.expectation.summary){ + return std::format("expected \"{}\", got \"{}\"", *test.expectation.summary, got); + } + return true; + } + if (error.find(test.expectation.error) == std::string::npos){ + return std::format("expected a failure with \"{}\", got \"{}\"", test.expectation.error, error.empty() ? got : error); + } + return true; +} + + +struct RowsCase{ + std::string name; + struct Input{ + StoryRowsShown shown = StoryRowsShown::USER; + size_t first = 0; + size_t last = 0; + }; + Input input; + struct Expectation{ + std::string rows = {}; + }; + Expectation expectation; +}; + +// 01.00, 01.01, 01.02 with 01.01 dev-only. +const RowsCase ROWS_CASES[] = { + {.name = "Developer Mode lists every row", .input = {.shown = StoryRowsShown::DEVELOPER, .first = 0, .last = 2}, .expectation = {.rows = "01.00 01.01 01.02"}}, + {.name = "a user's run skips the dev-only rows", .input = {.shown = StoryRowsShown::USER, .first = 0, .last = 1}, .expectation = {.rows = "01.00 01.02"}}, + {.name = "a run from one row to a later one", .input = {.shown = StoryRowsShown::DEVELOPER, .first = 1, .last = 2}, .expectation = {.rows = "01.01 01.02"}}, + {.name = "no rows for a start after the end", .input = {.shown = StoryRowsShown::DEVELOPER, .first = 2, .last = 1}, .expectation = {.rows = ""}}, + {.name = "no rows for an end past the table", .input = {.shown = StoryRowsShown::USER, .first = 0, .last = 2}, .expectation = {.rows = ""}}, +}; + +UnitTestResult check_rows(const RowsCase& test){ + StoryData story; + for (std::string_view id : {"01.00", "01.01", "01.02"}){ + StoryCheckpoint row; + row.id = std::string(id); + story.checkpoints.push_back(std::move(row)); + } + story.dev_only.emplace("01.01"); + const std::vector shown = story_rows_for_mode(story, test.input.shown); + const std::string got = joined(ids(story_run_rows(shown, test.input.first, test.input.last))); + if (got != test.expectation.rows){ + return std::format("expected \"{}\", got \"{}\"", test.expectation.rows, got); + } + return true; +} + + +struct ReloadCase{ + std::string name; + struct Input{ + StoryRunPolicy::BoundaryReload boundary_reload = StoryRunPolicy::BoundaryReload::AT_PLAN_BOUNDARIES; + std::string row = {}; + }; + Input input; + struct Expectation{ + bool reloads = false; + }; + Expectation expectation; +}; + +// 01.01 reloads when chained, 01.02 always. +const ReloadCase RELOAD_CASES[] = { + {.name = "at plan boundaries, a when-chained row reloads", .input = {.boundary_reload = StoryRunPolicy::BoundaryReload::AT_PLAN_BOUNDARIES, .row = "01.01"}, .expectation = {.reloads = true}}, + {.name = "straight through, a when-chained row runs on", .input = {.boundary_reload = StoryRunPolicy::BoundaryReload::STRAIGHT_THROUGH, .row = "01.01"}, .expectation = {.reloads = false}}, + {.name = "straight through, an always row reloads", .input = {.boundary_reload = StoryRunPolicy::BoundaryReload::STRAIGHT_THROUGH, .row = "01.02"}, .expectation = {.reloads = true}}, + {.name = "a row with no reload runs on", .input = {.boundary_reload = StoryRunPolicy::BoundaryReload::AT_PLAN_BOUNDARIES, .row = "01.00"}, .expectation = {.reloads = false}}, +}; + +UnitTestResult check_reload(const ReloadCase& test){ + StoryRows rows; + rows.reload_when_chained = {"01.01", "01.02"}; + rows.reload_always = {"01.02"}; + const bool got = story_reloads_before(rows, test.input.boundary_reload, test.input.row); + if (got != test.expectation.reloads){ + return std::format("expected reloads {}, got {}", test.expectation.reloads, got); + } + return true; +} + + +template +class StoryFilesTest : public UnitTest{ +public: + using Check = UnitTestResult (*)(const Case&); + + StoryFilesTest(std::string_view suite, Case test_case, Check check) + : UnitTest(std::format("Pokemon::StoryFiles - {}: {}", suite, test_case.name)) + , m_case(std::move(test_case)) + , m_check(check) + {} + + virtual UnitTestResult run(Logger&, CancellableScope&) const override{ + return m_check(m_case); + } + +private: + Case m_case; + Check m_check; +}; + +} // namespace + + +void add_tests_StoryFiles(UnitTestDatabase& database){ + for (const LoadCase& test : LOAD_CASES){ + database.add>("load", test, check_load); + } + for (const RowsCase& test : ROWS_CASES){ + database.add>("rows", test, check_rows); + } + for (const ReloadCase& test : RELOAD_CASES){ + database.add>("reload", test, check_reload); + } +} + + + +} // namespace Pokemon +} // namespace PokemonAutomation diff --git a/SerialPrograms/Source/Pokemon/AutoStory/Data/Pokemon_StoryFiles_Tests.h b/SerialPrograms/Source/Pokemon/AutoStory/Data/Pokemon_StoryFiles_Tests.h new file mode 100644 index 0000000000..5f0804951a --- /dev/null +++ b/SerialPrograms/Source/Pokemon/AutoStory/Data/Pokemon_StoryFiles_Tests.h @@ -0,0 +1,24 @@ +/* Story Files Tests + * + * From: https://github.com/PokemonAutomation/ + * + */ + +#ifndef PokemonAutomation_Pokemon_StoryFiles_Tests_H +#define PokemonAutomation_Pokemon_StoryFiles_Tests_H + +#include "Common/Cpp/TestRunners/UnitTestDatabase.h" + +namespace PokemonAutomation{ +namespace Pokemon{ + + +// Registers the tests of a story read from built-in and dev checkpoint +// files, and of the shared execution fields. +void add_tests_StoryFiles(UnitTestDatabase& database); + + + +} // namespace Pokemon +} // namespace PokemonAutomation +#endif diff --git a/SerialPrograms/Source/Pokemon/AutoStory/Data/Pokemon_StoryRowExecution.cpp b/SerialPrograms/Source/Pokemon/AutoStory/Data/Pokemon_StoryRowExecution.cpp new file mode 100644 index 0000000000..1175684067 --- /dev/null +++ b/SerialPrograms/Source/Pokemon/AutoStory/Data/Pokemon_StoryRowExecution.cpp @@ -0,0 +1,105 @@ +/* Story Row Execution + * + * From: https://github.com/PokemonAutomation/ + * + */ + +#include +#include "Common/Cpp/Exceptions.h" +#include "Common/Cpp/Json/JsonValue.h" +#include "Pokemon_StoryRowExecution.h" + +namespace PokemonAutomation{ +namespace Pokemon{ + + +namespace{ + +constexpr std::string_view SHARED_FIELDS[] = {"save", "reload_when_chained", "dev_only"}; + +bool is_known_field(std::string_view key, std::initializer_list game_fields){ + for (std::string_view field : SHARED_FIELDS){ + if (key == field){ + return true; + } + } + for (std::string_view field : game_fields){ + if (key == field){ + return true; + } + } + return false; +} + +// Whether `value` is JSON true. +bool is_true(const JsonValue& value){ + return value.is_boolean() && value.to_boolean_default(); +} + +bool read_autosave(const JsonObject& execution, std::string_view where){ + const JsonValue* save = execution.get_value("save"); + if (save == nullptr){ + return false; + } + const std::string* text = save->to_string(); + if (text == nullptr || (*text != "autosave" && *text != "menu")){ + throw ParseException(std::format("{}: save is \"autosave\", \"menu\" or left out", where)); + } + return *text == "autosave"; +} + +StoryReload read_reload(const JsonObject& execution, std::string_view where){ + const JsonValue* reload = execution.get_value("reload_when_chained"); + if (reload == nullptr){ + return StoryReload::NEVER; + } + if (is_true(*reload)){ + return StoryReload::WHEN_CHAINED; + } + const std::string* text = reload->to_string(); + if (text != nullptr && *text == "always"){ + return StoryReload::ALWAYS; + } + throw ParseException(std::format("{}: reload_when_chained is true, \"always\" or left out", where)); +} + +bool read_dev_only(const JsonObject& execution, std::string_view where){ + const JsonValue* dev_only = execution.get_value("dev_only"); + if (dev_only == nullptr){ + return false; + } + if (!is_true(*dev_only)){ + throw ParseException(std::format("{}: dev_only is true or left out", where)); + } + return true; +} + +} // namespace + + +StoryRowExecution read_story_row_execution( + const JsonObject& execution, std::string_view where, std::initializer_list game_fields +){ + for (const auto& [key, value] : execution){ + if (!is_known_field(key, game_fields)){ + throw ParseException(std::format("{}: unknown execution field {}", where, key)); + } + } + return StoryRowExecution{ + .autosave = read_autosave(execution, where), + .reload = read_reload(execution, where), + .dev_only = read_dev_only(execution, where), + }; +} + +bool story_reloads_before(const StoryRows& rows, StoryRunPolicy::BoundaryReload boundary_reload, std::string_view id){ + if (rows.reload_always.contains(id)){ + return true; + } + return boundary_reload == StoryRunPolicy::BoundaryReload::AT_PLAN_BOUNDARIES && rows.reload_when_chained.contains(id); +} + + + +} // namespace Pokemon +} // namespace PokemonAutomation diff --git a/SerialPrograms/Source/Pokemon/AutoStory/Data/Pokemon_StoryRowExecution.h b/SerialPrograms/Source/Pokemon/AutoStory/Data/Pokemon_StoryRowExecution.h new file mode 100644 index 0000000000..d820f0b6a1 --- /dev/null +++ b/SerialPrograms/Source/Pokemon/AutoStory/Data/Pokemon_StoryRowExecution.h @@ -0,0 +1,104 @@ +/* Story Row Execution + * + * From: https://github.com/PokemonAutomation/ + * + * The execution fields of a checkpoint file (its JSON "execution") that + * every game reads the same way, and the sets of rows they mark: which + * rows end on the game's own autosave, which a run reloads before, and + * which are for lab runs only, and a game's story: its checkpoints and + * those rows. The game reads its other execution fields itself + * (Pokemon_AuthoredCheckpointJson.h); Pokemon_StoryFiles.h loads a story + * from its files. + * + */ + +#ifndef PokemonAutomation_Pokemon_StoryRowExecution_H +#define PokemonAutomation_Pokemon_StoryRowExecution_H + +#include +#include +#include +#include +#include +#include +#include +#include "Common/Cpp/Json/JsonObject.h" + +namespace PokemonAutomation{ +namespace Pokemon{ + + +// When a run reloads the row's save before it, having played the row +// before it too ("reload_when_chained"). +enum class StoryReload{ + NEVER, // left out: the row runs on from where the row before left + WHEN_CHAINED, // true: at plan boundaries (StoryRunPolicy::BoundaryReload) + ALWAYS, // "always": even straight through; only its save starts its walk +}; + +// What a checkpoint file's shared execution fields say. +struct StoryRowExecution{ + // "save": "autosave": the game saves by itself at the row's end, so the + // program does not. "menu" or left out: the program saves, when the + // save policy lets it. + bool autosave = false; + StoryReload reload = StoryReload::NEVER; + // "dev_only": true: a lab walk the story does not need (developer + // mode lists and plays it, a user's run does not). + bool dev_only = false; +}; + +// The shared fields of `execution`: "save", "reload_when_chained" and +// "dev_only", each optional. Throws ParseException naming `where` for a +// malformed one, and for a field that is neither shared nor one of +// `game_fields`, which the game reads itself. +StoryRowExecution read_story_row_execution( + const JsonObject& execution, std::string_view where, std::initializer_list game_fields +); + + +// The rows of a story the shared execution fields mark, by id. +struct StoryRows{ + std::set> autosaves; + // WHEN_CHAINED and ALWAYS rows; each comes after an autosave row, + // whose autosave is its start save. + std::set> reload_when_chained; + // The ALWAYS rows of reload_when_chained. + std::set> reload_always; + std::set> dev_only; + // The dev files that replaced a built-in checkpoint, as (file name, + // path) (Pokemon_StoryDevFiles.h). + std::vector> dev_files; +}; + +// A game's story: its checkpoints in the order it plays them, and the rows +// their execution fields mark. +template +struct StoryData : StoryRows{ + std::vector checkpoints; +}; + +// How a run plays its checkpoints: the attempts each gets, and whether it +// reloads at the plan's boundaries. +struct StoryRunPolicy{ + // Whether a run of several checkpoints reloads the save at a + // WHEN_CHAINED row (AT_PLAN_BOUNDARIES) or runs on from the state the + // row before left (STRAIGHT_THROUGH). ALWAYS rows reload either way, and + // a failed checkpoint's retries reload as usual. + enum class BoundaryReload{ + AT_PLAN_BOUNDARIES, + STRAIGHT_THROUGH, + }; + size_t attempts_per_checkpoint = 1; + BoundaryReload boundary_reload = BoundaryReload::AT_PLAN_BOUNDARIES; +}; + +// Whether a run reloads the save before row `id` of `rows` when it reaches +// it from the row before. +bool story_reloads_before(const StoryRows& rows, StoryRunPolicy::BoundaryReload boundary_reload, std::string_view id); + + + +} // namespace Pokemon +} // namespace PokemonAutomation +#endif diff --git a/SerialPrograms/Source/Pokemon/AutoStory/Data/Pokemon_StoryStepJson.cpp b/SerialPrograms/Source/Pokemon/AutoStory/Data/Pokemon_StoryStepJson.cpp index 3d39269e07..095cbd5014 100644 --- a/SerialPrograms/Source/Pokemon/AutoStory/Data/Pokemon_StoryStepJson.cpp +++ b/SerialPrograms/Source/Pokemon/AutoStory/Data/Pokemon_StoryStepJson.cpp @@ -324,7 +324,9 @@ DeclaredPose read_declared_pose(const JsonValue& value, std::string_view source) } StoryStep read_story_step(const JsonValue& value, std::string_view source, std::span actions){ - const JsonObject& root = fields(value, {"id", "kind", "why", "action", "args", "skip_if", "declared_after"}, source); + const JsonObject& root = fields( + value, {"id", "kind", "why", "action", "args", "skip_if", "declared_after", "once_per_save"}, source + ); StoryStep result; result.name = root.get_string_throw("id"); if (result.name.empty()){ @@ -344,6 +346,9 @@ StoryStep read_story_step(const JsonValue& value, std::string_view source, std:: if (const JsonValue* field = root.get_value("declared_after")){ result.pose_after = read_declared_pose(*field, source); } + if (const JsonValue* field = root.get_value("once_per_save")){ + result.once_per_save = field->to_boolean_throw(std::string(source)); + } return result; } diff --git a/SerialPrograms/Source/Pokemon/AutoStory/Data/Pokemon_StoryStepJson_Tests.cpp b/SerialPrograms/Source/Pokemon/AutoStory/Data/Pokemon_StoryStepJson_Tests.cpp index 69f213ad13..296b300744 100644 --- a/SerialPrograms/Source/Pokemon/AutoStory/Data/Pokemon_StoryStepJson_Tests.cpp +++ b/SerialPrograms/Source/Pokemon/AutoStory/Data/Pokemon_StoryStepJson_Tests.cpp @@ -3,23 +3,29 @@ * From: https://github.com/PokemonAutomation/ * * Each case reads a record from JSON: accepted cases check the values - * read, rejected cases check that the read fails. The Python reader's - * shared case file is checked on the Python side. + * read, rejected cases check that the read fails. The standalone + * StoryDataTests also checks PokemonSimulation's shared case file when given + * its path (devtools/story-data-tests/StoryWireCases.h). * */ +#include #include #include +#include #include #include #include #include #include "Common/Cpp/Exceptions.h" #include "Common/Cpp/Json/JsonValue.h" +#include "Pokemon/AutoStory/Types/Pokemon_DeclaredPose.h" +#include "Pokemon/AutoStory/Types/Pokemon_GridPose.h" +#include "Pokemon/AutoStory/Types/Pokemon_StoryActionArg.h" +#include "Pokemon/AutoStory/Types/Pokemon_StoryCheckpointMetadata.h" +#include "Pokemon/Navigation/Pokemon_Direction.h" #include "Pokemon_StoryStepJson.h" -#ifndef PA_STORY_DATA_STANDALONE #include "Pokemon_StoryStepJson_Tests.h" -#endif namespace PokemonAutomation{ namespace Pokemon{ @@ -44,8 +50,8 @@ using ReadCheck = std::string (*)(const ReadRecord& record); struct WireCase{ // A record to read, and which kind it is. + std::string_view name; struct Input{ - std::string_view name; Record record = Record::STEP; std::string_view json; }; @@ -69,78 +75,84 @@ const StoryStep& step_of(const ReadRecord& record){ } const WireCase CASES[] = { - {.input = {.name = "no args", .json = R"({"id":"talk","kind":"talk"})"}, .expectation = {.check = [](const ReadRecord& record){ + {.name = "no args", .input = {.json = R"({"id":"talk","kind":"talk"})"}, .expectation = {.check = [](const ReadRecord& record){ const StoryStep& step = step_of(record); return expect(step.name == "talk" && step.kind == StoryStepKind::TALK && step.args.empty() && !step.pose_after, "a bare talk step"); }}}, - {.input = {.name = "all shared fields", .json = R"({"id":"all","kind":"game_action","why":"source reason","action":"profile","skip_if":["flag"],"declared_after":{"map":"B","tiles":[[0,0],[1,0]],"facing":"east"}})"}, .expectation = {.check = [](const ReadRecord& record){ + {.name = "all shared fields", .input = {.json = R"({"id":"all","kind":"game_action","why":"source reason","action":"profile","skip_if":["flag"],"declared_after":{"map":"B","tiles":[[0,0],[1,0]],"facing":"east"}})"}, .expectation = {.check = [](const ReadRecord& record){ const StoryStep& step = step_of(record); const DeclaredPose after = TileDeclared{.map = "B", .tiles = {{0, 0}, {1, 0}}, .facing = Direction::EAST}; return expect(step.kind == StoryStepKind::GAME && step.why == "source reason" && step.action == "profile" && step.skip_if == std::vector{"flag"} && step.pose_after == after, "every shared field read"); }}}, - {.input = {.name = "route fills its fallback", .json = R"({"id":"r","kind":"route","args":{"target":{"map":"A","tiles":[[1,2]]}}})"}, .expectation = {.check = [](const ReadRecord& record){ + {.name = "once per save", .input = {.json = R"({"id":"heal","kind":"game_action","action":"profile","once_per_save":true})"}, .expectation = {.check = [](const ReadRecord& record){ + return expect(step_of(record).once_per_save, "a once_per_save step"); + }}}, + {.name = "every time by default", .input = {.json = R"({"id":"heal","kind":"game_action","action":"profile"})"}, .expectation = {.check = [](const ReadRecord& record){ + return expect(!step_of(record).once_per_save, "a step run every time"); + }}}, + {.name = "route fills its fallback", .input = {.json = R"({"id":"r","kind":"route","args":{"target":{"map":"A","tiles":[[1,2]]}}})"}, .expectation = {.check = [](const ReadRecord& record){ const StoryActionArgs expected = {{"fight_wild", false}, {"target", GridPose{.map = "A", .tiles = {{1, 2}}, .facing = std::nullopt}}}; return expect(step_of(record).args == expected, "the target and fight_wild false"); }}}, - {.input = {.name = "legs", .json = R"({"id":"l","kind":"legs","action":"legs","args":{"legs":[{"direction":"south","tiles":2}],"fight_wild":true}})"}, .expectation = {.check = [](const ReadRecord& record){ + {.name = "legs", .input = {.json = R"({"id":"l","kind":"legs","action":"legs","args":{"legs":[{"direction":"south","tiles":2}],"fight_wild":true}})"}, .expectation = {.check = [](const ReadRecord& record){ const StoryActionArgs expected = {{"fight_wild", true}, {"legs", std::vector{{.direction = Direction::SOUTH, .tiles = 2}}}}; return expect(step_of(record).args == expected, "one south leg of 2 tiles"); }}}, - {.input = {.name = "direction", .json = R"({"id":"s","kind":"step","args":{"direction":"west"}})"}, .expectation = {.check = [](const ReadRecord& record){ + {.name = "direction", .input = {.json = R"({"id":"s","kind":"step","args":{"direction":"west"}})"}, .expectation = {.check = [](const ReadRecord& record){ const StoryActionArgs expected = {{"direction", Direction::WEST}}; return expect(step_of(record).args == expected, "direction west"); }}}, - {.input = {.name = "items", .json = R"({"id":"s","kind":"shop","args":{"items":[{"item":"potion","quantity":5}]}})"}, .expectation = {.check = [](const ReadRecord& record){ + {.name = "items", .input = {.json = R"({"id":"s","kind":"shop","args":{"items":[{"item":"potion","quantity":5}]}})"}, .expectation = {.check = [](const ReadRecord& record){ const StoryActionArgs expected = {{"items", std::vector{{.item = "potion", .quantity = 5}}}}; return expect(step_of(record).args == expected, "5 potions"); }}}, - {.input = {.name = "game args", .json = R"({"id":"buy","kind":"game_action","action":"mart","args":{"map":"CeruleanCity_Mart","budget":3000,"if_present":true}})"}, .expectation = {.check = [](const ReadRecord& record){ + {.name = "game args", .input = {.json = R"({"id":"buy","kind":"game_action","action":"mart","args":{"map":"CeruleanCity_Mart","budget":3000,"if_present":true}})"}, .expectation = {.check = [](const ReadRecord& record){ const StoryActionArgs expected = {{"budget", int64_t(3000)}, {"if_present", true}, {"map", std::string("CeruleanCity_Mart")}}; return expect(step_of(record).args == expected, "the Mart args"); }}}, - {.input = {.name = "game words", .json = R"({"id":"buy","kind":"game_action","action":"mart","args":{"map":"M","budget":1,"skip":["a","b"]}})"}, .expectation = {.check = [](const ReadRecord& record){ + {.name = "game words", .input = {.json = R"({"id":"buy","kind":"game_action","action":"mart","args":{"map":"M","budget":1,"skip":["a","b"]}})"}, .expectation = {.check = [](const ReadRecord& record){ const StoryActionArgs expected = {{"budget", int64_t(1)}, {"if_present", false}, {"map", std::string("M")}, {"skip", std::vector{"a", "b"}}}; return expect(step_of(record).args == expected, "the words and if_present false"); }}}, - {.input = {.name = "game integer rows", .json = R"({"id":"w","kind":"game_action","action":"walk","args":{"legs":[[0,4500],[-90,0],[]]}})"}, .expectation = {.check = [](const ReadRecord& record){ + {.name = "game integer rows", .input = {.json = R"({"id":"w","kind":"game_action","action":"walk","args":{"legs":[[0,4500],[-90,0],[]]}})"}, .expectation = {.check = [](const ReadRecord& record){ const StoryActionArgs expected = {{"legs", std::vector>{{0, 4500}, {-90, 0}, {}}}}; return expect(step_of(record).args == expected, "three rows, the last empty"); }}}, - {.input = {.name = "timed legs", .json = R"({"id":"w","kind":"game_action","action":"timed_walk","args":{"legs":[[0,4500],[-90,1200]]}})"}, .expectation = {.check = [](const ReadRecord& record){ + {.name = "timed legs", .input = {.json = R"({"id":"w","kind":"game_action","action":"timed_walk","args":{"legs":[[0,4500],[-90,1200]]}})"}, .expectation = {.check = [](const ReadRecord& record){ const StoryActionArgs expected = {{"legs", std::vector{{.turn = 0, .ms = 4500}, {.turn = -90, .ms = 1200}}}}; return expect(step_of(record).args == expected, "two timed legs"); }}}, - {.input = {.name = "unknown facing stays absent", .record = Record::POSE, .json = R"({"map":"M","tiles":[[0,0]]})"}, .expectation = {.check = [](const ReadRecord& record){ + {.name = "unknown facing stays absent", .input = {.record = Record::POSE, .json = R"({"map":"M","tiles":[[0,0]]})"}, .expectation = {.check = [](const ReadRecord& record){ return expect(std::get(record) == GridPose{.map = "M", .tiles = {{0, 0}}, .facing = std::nullopt}, "one tile, no facing"); }}}, - {.input = {.name = "no tiles", .record = Record::POSE, .json = R"({"map":"M","tiles":[]})"}, .expectation = {.check = [](const ReadRecord& record){ + {.name = "no tiles", .input = {.record = Record::POSE, .json = R"({"map":"M","tiles":[]})"}, .expectation = {.check = [](const ReadRecord& record){ return expect(std::get(record).tiles.empty(), "no tiles"); }}}, - {.input = {.name = "declared tile pose", .record = Record::DECLARED, .json = R"({"map":"M","tiles":[[1,2]],"facing":"north"})"}, .expectation = {.check = [](const ReadRecord& record){ + {.name = "declared tile pose", .input = {.record = Record::DECLARED, .json = R"({"map":"M","tiles":[[1,2]],"facing":"north"})"}, .expectation = {.check = [](const ReadRecord& record){ const DeclaredPose expected = TileDeclared{.map = "M", .tiles = {{1, 2}}, .facing = Direction::NORTH}; return expect(std::get(record) == expected, "a tile pose facing north"); }}}, - {.input = {.name = "declared place", .record = Record::DECLARED, .json = R"({"place":"LumioseCity","spot":"HotelZ","heading":90})"}, .expectation = {.check = [](const ReadRecord& record){ + {.name = "declared place", .input = {.record = Record::DECLARED, .json = R"({"place":"LumioseCity","spot":"HotelZ","heading":90})"}, .expectation = {.check = [](const ReadRecord& record){ const DeclaredPose expected = ZoneDeclared{.place = "LumioseCity", .spot = "HotelZ", .heading = 90}; return expect(std::get(record) == expected, "a zone pose with spot and heading"); }}}, - {.input = {.name = "declared place alone", .record = Record::DECLARED, .json = R"({"place":"HotelZ"})"}, .expectation = {.check = [](const ReadRecord& record){ + {.name = "declared place alone", .input = {.record = Record::DECLARED, .json = R"({"place":"HotelZ"})"}, .expectation = {.check = [](const ReadRecord& record){ const DeclaredPose expected = ZoneDeclared{.place = "HotelZ", .spot = std::nullopt, .heading = std::nullopt}; return expect(std::get(record) == expected, "a zone pose alone"); }}}, - {.input = {.name = "checkpoint starting at a place", .record = Record::CHECKPOINT, .json = R"({"id":"03.01","title":"Lobby","start":{"place":"HotelZ"},"events":[{"id":"down","kind":"scene","declared_after":{"place":"HotelZLobby","heading":180}}]})"}, .expectation = {.check = [](const ReadRecord& record){ + {.name = "checkpoint starting at a place", .input = {.record = Record::CHECKPOINT, .json = R"({"id":"03.01","title":"Lobby","start":{"place":"HotelZ"},"events":[{"id":"down","kind":"scene","declared_after":{"place":"HotelZLobby","heading":180}}]})"}, .expectation = {.check = [](const ReadRecord& record){ const StoryCheckpoint& checkpoint = std::get(record); const DeclaredPose start = ZoneDeclared{.place = "HotelZ", .spot = std::nullopt, .heading = std::nullopt}; return expect(checkpoint.start == start && checkpoint.steps.size() == 1 && checkpoint.steps[0].kind == StoryStepKind::MASH, "a zone start and one scene"); }}}, - {.input = {.name = "ordered checkpoint", .record = Record::CHECKPOINT, .json = R"({"id":"00.05","title":"Parcel","events":[ {"id":"first","kind":"talk"}, {"id":"second","kind":"scene"} ]})"}, .expectation = {.check = [](const ReadRecord& record){ + {.name = "ordered checkpoint", .input = {.record = Record::CHECKPOINT, .json = R"({"id":"00.05","title":"Parcel","events":[ {"id":"first","kind":"talk"}, {"id":"second","kind":"scene"} ]})"}, .expectation = {.check = [](const ReadRecord& record){ const StoryCheckpoint& checkpoint = std::get(record); return expect(checkpoint.id == "00.05" && checkpoint.title == "Parcel" && !checkpoint.start && checkpoint.steps.size() == 2 && checkpoint.steps[0].name == "first" && checkpoint.steps[1].name == "second" && checkpoint.steps_json == R"([{"id":"first","kind":"talk"},{"id":"second","kind":"scene"}])", "two steps in order and their compact JSON"); }}}, - {.input = {.name = "checkpoint postconditions", .record = Record::CHECKPOINT, .json = R"({"id":"x","title":"X","events":[],"metadata":{"phase":"reproduction","postconditions":{"position":{"map":"M","tiles":[[3,4]]},"items":[{"item":"LIFT_KEY","quantity":1}],"flags":["f"]}}})"}, .expectation = {.check = [](const ReadRecord& record){ + {.name = "checkpoint postconditions", .input = {.record = Record::CHECKPOINT, .json = R"({"id":"x","title":"X","events":[],"metadata":{"phase":"reproduction","postconditions":{"position":{"map":"M","tiles":[[3,4]]},"items":[{"item":"LIFT_KEY","quantity":1}],"flags":["f"]}}})"}, .expectation = {.check = [](const ReadRecord& record){ const StoryCheckpoint& checkpoint = std::get(record); const StoryPostconditions& post = checkpoint.postconditions; // Named, not temporaries in the comparison: GCC's -Wdangling-pointer @@ -152,30 +164,30 @@ const WireCase CASES[] = { && post.position == position && post.items == items && post.flags == flags, "the phase, position, item and flag"); }}}, - {.input = {.name = "integer rows, not rows", .json = R"({"id":"w","kind":"game_action","action":"walk","args":{"legs":[0,4500]}})"}, .expectation = {.rejected = true}}, - {.input = {.name = "integer rows, fraction", .json = R"({"id":"w","kind":"game_action","action":"walk","args":{"legs":[[0,4.5]]}})"}, .expectation = {.rejected = true}}, - {.input = {.name = "timed leg of three numbers", .json = R"({"id":"w","kind":"game_action","action":"timed_walk","args":{"legs":[[0,4500,1]]}})"}, .expectation = {.rejected = true}}, - {.input = {.name = "unknown arg", .json = R"({"id":"a","kind":"game_action","action":"mart","args":{"map":"M","budget":1,"budgte":1}})"}, .expectation = {.rejected = true}}, - {.input = {.name = "missing required arg", .json = R"({"id":"a","kind":"game_action","action":"mart","args":{"map":"M"}})"}, .expectation = {.rejected = true}}, - {.input = {.name = "route without target", .json = R"({"id":"a","kind":"route"})"}, .expectation = {.rejected = true}}, - {.input = {.name = "args on a kind with none", .json = R"({"id":"a","kind":"talk","args":{"yes":true}})"}, .expectation = {.rejected = true}}, - {.input = {.name = "game step without action", .json = R"({"id":"a","kind":"game_action"})"}, .expectation = {.rejected = true}}, - {.input = {.name = "unknown action name", .json = R"({"id":"a","kind":"game_action","action":"dance"})"}, .expectation = {.rejected = true}}, - {.input = {.name = "fractional arg", .json = R"({"id":"a","kind":"game_action","action":"mart","args":{"map":"M","budget":1.5}})"}, .expectation = {.rejected = true}}, - {.input = {.name = "args not an object", .json = R"({"id":"a","kind":"game_action","action":"mart","args":["map"]})"}, .expectation = {.rejected = true}}, - {.input = {.name = "old field", .json = R"({"id":"a","kind":"battle","may_lose":true})"}, .expectation = {.rejected = true}}, - {.input = {.name = "old variant", .json = R"({"id":"a","kind":"game_action","variant":"mart"})"}, .expectation = {.rejected = true}}, - {.input = {.name = "unknown field", .json = R"({"id":"a","kind":"talk","mystery":0})"}, .expectation = {.rejected = true}}, - {.input = {.name = "unknown kind", .json = R"({"id":"a","kind":"magic"})"}, .expectation = {.rejected = true}}, - {.input = {.name = "boolean count", .json = R"({"id":"a","kind":"train","args":{"battles":false}})"}, .expectation = {.rejected = true}}, - {.input = {.name = "wrong bool", .json = R"({"id":"a","kind":"answer","args":{"yes":0}})"}, .expectation = {.rejected = true}}, - {.input = {.name = "old pose", .record = Record::POSE, .json = R"({"map":"M","certainty":"unknown","where":{"kind":"unknown"}})"}, .expectation = {.rejected = true}}, - {.input = {.name = "bad coordinate", .record = Record::POSE, .json = R"({"map":"M","tiles":[[0,true]]})"}, .expectation = {.rejected = true}}, - {.input = {.name = "declared map and place", .record = Record::DECLARED, .json = R"({"map":"M","place":"HotelZ"})"}, .expectation = {.rejected = true}}, - {.input = {.name = "declared place with tiles", .record = Record::DECLARED, .json = R"({"place":"HotelZ","tiles":[[1,2]]})"}, .expectation = {.rejected = true}}, - {.input = {.name = "declared map with heading", .record = Record::DECLARED, .json = R"({"map":"M","heading":90})"}, .expectation = {.rejected = true}}, - {.input = {.name = "declared neither", .record = Record::DECLARED, .json = R"({"spot":"Lobby"})"}, .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}}, + {.name = "integer rows, not rows", .input = {.json = R"({"id":"w","kind":"game_action","action":"walk","args":{"legs":[0,4500]}})"}, .expectation = {.rejected = true}}, + {.name = "integer rows, fraction", .input = {.json = R"({"id":"w","kind":"game_action","action":"walk","args":{"legs":[[0,4.5]]}})"}, .expectation = {.rejected = true}}, + {.name = "timed leg of three numbers", .input = {.json = R"({"id":"w","kind":"game_action","action":"timed_walk","args":{"legs":[[0,4500,1]]}})"}, .expectation = {.rejected = true}}, + {.name = "unknown arg", .input = {.json = R"({"id":"a","kind":"game_action","action":"mart","args":{"map":"M","budget":1,"budgte":1}})"}, .expectation = {.rejected = true}}, + {.name = "missing required arg", .input = {.json = R"({"id":"a","kind":"game_action","action":"mart","args":{"map":"M"}})"}, .expectation = {.rejected = true}}, + {.name = "route without target", .input = {.json = R"({"id":"a","kind":"route"})"}, .expectation = {.rejected = true}}, + {.name = "args on a kind with none", .input = {.json = R"({"id":"a","kind":"talk","args":{"yes":true}})"}, .expectation = {.rejected = true}}, + {.name = "game step without action", .input = {.json = R"({"id":"a","kind":"game_action"})"}, .expectation = {.rejected = true}}, + {.name = "unknown action name", .input = {.json = R"({"id":"a","kind":"game_action","action":"dance"})"}, .expectation = {.rejected = true}}, + {.name = "fractional arg", .input = {.json = R"({"id":"a","kind":"game_action","action":"mart","args":{"map":"M","budget":1.5}})"}, .expectation = {.rejected = true}}, + {.name = "args not an object", .input = {.json = R"({"id":"a","kind":"game_action","action":"mart","args":["map"]})"}, .expectation = {.rejected = true}}, + {.name = "old field", .input = {.json = R"({"id":"a","kind":"battle","may_lose":true})"}, .expectation = {.rejected = true}}, + {.name = "old variant", .input = {.json = R"({"id":"a","kind":"game_action","variant":"mart"})"}, .expectation = {.rejected = true}}, + {.name = "unknown field", .input = {.json = R"({"id":"a","kind":"talk","mystery":0})"}, .expectation = {.rejected = true}}, + {.name = "unknown kind", .input = {.json = R"({"id":"a","kind":"magic"})"}, .expectation = {.rejected = true}}, + {.name = "boolean count", .input = {.json = R"({"id":"a","kind":"train","args":{"battles":false}})"}, .expectation = {.rejected = true}}, + {.name = "wrong bool", .input = {.json = R"({"id":"a","kind":"answer","args":{"yes":0}})"}, .expectation = {.rejected = true}}, + {.name = "old pose", .input = {.record = Record::POSE, .json = R"({"map":"M","certainty":"unknown","where":{"kind":"unknown"}})"}, .expectation = {.rejected = true}}, + {.name = "bad coordinate", .input = {.record = Record::POSE, .json = R"({"map":"M","tiles":[[0,true]]})"}, .expectation = {.rejected = true}}, + {.name = "declared map and place", .input = {.record = Record::DECLARED, .json = R"({"map":"M","place":"HotelZ"})"}, .expectation = {.rejected = true}}, + {.name = "declared place with tiles", .input = {.record = Record::DECLARED, .json = R"({"place":"HotelZ","tiles":[[1,2]]})"}, .expectation = {.rejected = true}}, + {.name = "declared map with heading", .input = {.record = Record::DECLARED, .json = R"({"map":"M","heading":90})"}, .expectation = {.rejected = true}}, + {.name = "declared neither", .input = {.record = Record::DECLARED, .json = R"({"spot":"Lobby"})"}, .expectation = {.rejected = true}}, + {.name = "duplicate events", .input = {.record = Record::CHECKPOINT, .json = R"({"id":"x","title":"X","events":[{"id":"a","kind":"talk"},{"id":"a","kind":"talk"}]})"}, .expectation = {.rejected = true}}, }; @@ -200,19 +212,19 @@ std::vector test_actions(){ } -// `input` read. -ReadRecord read_record(const WireCase::Input& input){ +// `input` read, with `source` naming it in parse errors. +ReadRecord read_record(const WireCase::Input& input, std::string_view source){ static const std::vector actions = test_actions(); const JsonValue value = parse_json(std::string(input.json)); switch (input.record){ case Record::POSE: - return read_grid_pose(value, input.name); + return read_grid_pose(value, source); case Record::DECLARED: - return read_declared_pose(value, input.name); + return read_declared_pose(value, source); case Record::STEP: - return read_story_step(value, input.name, actions); + return read_story_step(value, source, actions); case Record::CHECKPOINT: - return read_story_checkpoint(value, input.name, actions); + return read_story_checkpoint(value, source, actions); } throw ParseException("Unknown test record."); } @@ -220,7 +232,7 @@ ReadRecord read_record(const WireCase::Input& input){ // "" when `test` reads as expected, else what differs. std::string check_case(const WireCase& test){ try{ - const ReadRecord record = read_record(test.input); + const ReadRecord record = read_record(test.input, test.name); if (test.expectation.rejected){ return "Expected rejection, read accepted record."; } @@ -236,7 +248,7 @@ std::string check_case(const WireCase& test){ class StoryJsonTest : public UnitTest{ public: explicit StoryJsonTest(WireCase test) - : UnitTest(std::format("Pokemon::StoryStepJson - {}", test.input.name)) + : UnitTest(std::format("Pokemon::StoryStepJson - {}", test.name)) , m_case(test) {} @@ -263,24 +275,21 @@ void add_tests_StoryStepJson(UnitTestDatabase& database){ } } -#endif - - - -} // namespace Pokemon -} // namespace PokemonAutomation - - -#ifdef PA_STORY_DATA_STANDALONE +#else -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'; +size_t run_story_step_json_cases(){ + size_t failed = 0; + for (const WireCase& test : CASES){ + const std::string error = check_case(test); + std::cout << test.name << ": " << (error.empty() ? "PASS" : error) << '\n'; failed += !error.empty(); } - return failed != 0; + return failed; } #endif + + + +} // namespace Pokemon +} // namespace PokemonAutomation diff --git a/SerialPrograms/Source/Pokemon/AutoStory/Data/Pokemon_StoryStepJson_Tests.h b/SerialPrograms/Source/Pokemon/AutoStory/Data/Pokemon_StoryStepJson_Tests.h index 9c4f9565ad..507d670981 100644 --- a/SerialPrograms/Source/Pokemon/AutoStory/Data/Pokemon_StoryStepJson_Tests.h +++ b/SerialPrograms/Source/Pokemon/AutoStory/Data/Pokemon_StoryStepJson_Tests.h @@ -7,6 +7,7 @@ #ifndef PokemonAutomation_Pokemon_StoryStepJson_Tests_H #define PokemonAutomation_Pokemon_StoryStepJson_Tests_H +#include #include "Common/Cpp/TestRunners/UnitTestDatabase.h" namespace PokemonAutomation{ @@ -16,6 +17,12 @@ namespace Pokemon{ // Registers unit tests for the lossless shared story-data wire contract. void add_tests_StoryStepJson(UnitTestDatabase& database); +#ifdef PA_STORY_DATA_STANDALONE +// Standalone StoryDataTests only: runs the built-in cases, prints one line +// per case, returns how many failed. +size_t run_story_step_json_cases(); +#endif + } // namespace Pokemon diff --git a/SerialPrograms/Source/Pokemon/AutoStory/Engine/MIGRATION.md b/SerialPrograms/Source/Pokemon/AutoStory/Engine/MIGRATION.md index c2c674c1bb..eef09ecdc4 100644 --- a/SerialPrograms/Source/Pokemon/AutoStory/Engine/MIGRATION.md +++ b/SerialPrograms/Source/Pokemon/AutoStory/Engine/MIGRATION.md @@ -69,13 +69,13 @@ Each move deletes that game's executor; the last one deletes `StoryStepExecutor` readers. - **PLZA** (ZonePose, in the engine with its instantiations and `observed_state()`): a declared pose (`"start"`, a step's `"declared_after"`) is a place, `{"place": "HotelZ"}` with an - optional `"spot"` and `"heading"` (`ZoneDeclared`, read by - `StoryPoseTraits::from_declared()`). Walks are `TIMED_LEGS` args; tile args fail + optional `"spot"` and `"heading"` (`ZoneDeclared`). The run keeps only the place, as a map + with no tiles; spot and heading wait for a position reader. Walks are `TIMED_LEGS` args; tile args fail the lint. Turns are `stick()` after the camera recenter; the minimap arrow is the `"heading"` reading. A new pose type: a struct with `pose_matches` / `pose_text`, a `StoryPoseTraits` specialization -(`TILE_MOVES`, `Declared`, `from_declared()`), and an explicit instantiation line in each engine +(`TILE_MOVES`, `Declared`), and an explicit instantiation line in each engine `.cpp`. ## Moves in shared code when the last executor goes diff --git a/SerialPrograms/Source/Pokemon/AutoStory/Engine/Pokemon_CoveredWatch.cpp b/SerialPrograms/Source/Pokemon/AutoStory/Engine/Pokemon_CoveredWatch.cpp new file mode 100644 index 0000000000..99fd6d1d54 --- /dev/null +++ b/SerialPrograms/Source/Pokemon/AutoStory/Engine/Pokemon_CoveredWatch.cpp @@ -0,0 +1,55 @@ +/* Covered Watch + * + * From: https://github.com/PokemonAutomation/ + * + */ + +#include "Pokemon_CoveredWatch.h" + +namespace PokemonAutomation{ +namespace Pokemon{ + + +CoveredWatcher::CoveredWatcher( + VisualInferenceCallback& watcher, WallClock start, Milliseconds tail, + std::optional end +) + : VisualInferenceCallback(watcher.label()) + , m_watcher(watcher) + , m_coverage(start) + , m_tail(tail) + , m_end(end) +{} + +void CoveredWatcher::make_overlays(VideoOverlaySet& items) const{ + m_watcher.make_overlays(items); +} + +bool CoveredWatcher::process_frame(const VideoSnapshot& frame){ + if (frame.timestamp < m_coverage.start()){ + return false; + } + m_coverage.record(frame.timestamp); + if (m_watcher.process_frame(frame)){ + m_fired = true; + return true; + } + return m_end && frame.timestamp >= *m_end + m_tail; +} + + +WatchResult watch_for( + VideoStream& stream, CancellableScope& scope, Milliseconds duration, + const WatchLimits& limits, VisualInferenceCallback& watcher +){ + const WallClock start = current_time(); + const WallClock end = start + duration; + CoveredWatcher covered(watcher, start, limits.tail, end); + wait_until(stream, scope, end + limits.tail + limits.cap, {covered}, limits.period); + return judge_watch(covered.fired(), covered.coverage(), end, limits.max_gap); +} + + + +} // namespace Pokemon +} // namespace PokemonAutomation diff --git a/SerialPrograms/Source/Pokemon/AutoStory/Engine/Pokemon_CoveredWatch.h b/SerialPrograms/Source/Pokemon/AutoStory/Engine/Pokemon_CoveredWatch.h new file mode 100644 index 0000000000..38aa9fad0f --- /dev/null +++ b/SerialPrograms/Source/Pokemon/AutoStory/Engine/Pokemon_CoveredWatch.h @@ -0,0 +1,134 @@ +/* Covered Watch + * + * From: https://github.com/PokemonAutomation/ + * + * A watch for a screen that ends in frame time and reports whether its + * frames cover the window (Pokemon_FrameCoverage.h). run_until() and + * wait_until() end a watch in wall time and return -1 for "did not fire" + * whether the watcher inspected a frame every 33 ms or one a second: the + * PLZA 03.08 catch (2026-11-14) read a missed "Registered" banner as "no + * new species". These wrappers keep those routines and the watcher as + * they are, record the capture times of the frames the watcher was + * handed, keep watching past the window's end until a frame captured a + * tail after it has been inspected (bounded by a wall-clock cap), and + * return SEEN, NOT_SEEN or UNKNOWN. + * + * The tail is the watcher's hold. A watcher that must see the screen for + * a hold (DetectorToFinder) fires a hold after the screen shows, so a + * screen that shows in the window's last hold fires only after the window + * ends. A fire in the tail still means the screen showed by the end. + * + */ + +#ifndef PokemonAutomation_Pokemon_CoveredWatch_H +#define PokemonAutomation_Pokemon_CoveredWatch_H + +#include +#include +#include "Common/Cpp/Time.h" +#include "CommonFramework/Tools/VideoStream.h" +#include "CommonFramework/VideoPipeline/VideoFeed.h" +#include "CommonTools/Async/InferenceRoutines.h" +#include "CommonTools/InferenceCallbacks/VisualInferenceCallback.h" +#include "Pokemon_FrameCoverage.h" + +namespace PokemonAutomation{ +namespace Pokemon{ + + +// `watcher` as it is, plus the frames it was handed. Frames captured +// before `start` are not handed to `watcher`: they show the screen before +// the window opened. It stops the session when `watcher` fires, or, once +// the window's end is known, on the first frame captured at or after the +// end plus `tail`. Call end_at() and read fired() and coverage() only +// while no inference routine runs it. +class CoveredWatcher : public VisualInferenceCallback{ +public: + CoveredWatcher( + VisualInferenceCallback& watcher, WallClock start, Milliseconds tail, + std::optional end = std::nullopt + ); + + virtual void make_overlays(VideoOverlaySet& items) const override; + using VisualInferenceCallback::process_frame; + virtual bool process_frame(const VideoSnapshot& frame) override; + + // The window ends at `end`: stop on the first frame captured at or + // after `end` plus the tail. + void end_at(WallClock end){ + m_end = end; + } + bool fired() const{ + return m_fired; + } + const FrameCoverage& coverage() const{ + return m_coverage; + } + +private: + VisualInferenceCallback& m_watcher; + FrameCoverage m_coverage; + Milliseconds m_tail; + std::optional m_end; + bool m_fired = false; +}; + + +// How a covered watch judges and bounds its window. The zero defaults are +// the strictest: no gap is small enough for NOT_SEEN, no tail, no cap. +struct WatchLimits{ + // judge_watch(). + Milliseconds max_gap = Milliseconds(0); + // The watcher's hold: how long past the window's end to keep watching. + Milliseconds tail = Milliseconds(0); + // How much longer than the end plus the tail to wait in wall time for + // a frame captured that late. + Milliseconds cap = Milliseconds(0); + // How often the watcher is handed the newest frame. At most `max_gap`, + // or frames cannot be inspected often enough to cover the window. + Milliseconds period = Milliseconds(50); +}; + + +// Runs `command` with `watcher` live over the window from now to the +// command's end. When the command ends without a fire, keeps watching +// until a frame captured `limits.tail` after that end has been inspected, +// at most `limits.cap` longer in wall time, so the window is judged on +// frames up to its end and a screen that shows just as the command ends +// is still caught. +template +WatchResult run_watched( + VideoStream& stream, ControllerContext& context, + std::function&& command, + const WatchLimits& limits, VisualInferenceCallback& watcher +); + +// Watches with `watcher` for `duration` in frame time: until it fires or a +// frame captured `duration` plus `limits.tail` from now has been +// inspected, at most `limits.cap` longer in wall time. +WatchResult watch_for( + VideoStream& stream, CancellableScope& scope, Milliseconds duration, + const WatchLimits& limits, VisualInferenceCallback& watcher +); + +template +WatchResult run_watched( + VideoStream& stream, ControllerContext& context, + std::function&& command, + const WatchLimits& limits, VisualInferenceCallback& watcher +){ + CoveredWatcher covered(watcher, current_time(), limits.tail); + run_until(stream, context, std::move(command), {covered}, limits.period); + const WallClock end = current_time(); + if (!covered.fired()){ + covered.end_at(end); + wait_until(stream, context, end + limits.tail + limits.cap, {covered}, limits.period); + } + return judge_watch(covered.fired(), covered.coverage(), end, limits.max_gap); +} + + + +} // namespace Pokemon +} // namespace PokemonAutomation +#endif diff --git a/SerialPrograms/Source/Pokemon/AutoStory/Engine/Pokemon_CoveredWatch_Tests.cpp b/SerialPrograms/Source/Pokemon/AutoStory/Engine/Pokemon_CoveredWatch_Tests.cpp new file mode 100644 index 0000000000..06ec9048b8 --- /dev/null +++ b/SerialPrograms/Source/Pokemon/AutoStory/Engine/Pokemon_CoveredWatch_Tests.cpp @@ -0,0 +1,172 @@ +/* Covered Watch Tests + * + * From: https://github.com/PokemonAutomation/ + * + * CoveredWatcher on scripted frames: each case is the capture times of + * the frames the pivot hands over (ms after the watch opened, repeats + * included), when the wrapped watcher fires, where the window ends and + * how long a tail is watched past it, and on which frame the wrapper asks + * the session to stop. A watcher with a hold is scripted as one that fires + * a hold after the screen shows. + * + */ + +#include +#include +#include +#include +#include +#include +#include "Common/Cpp/TestRunners/UnitTest.h" +#include "CommonFramework/ImageTypes/ImageRGB32.h" +#include "Pokemon_CoveredWatch.h" +#include "Pokemon_CoveredWatch_Tests.h" + +namespace PokemonAutomation{ +namespace Pokemon{ + + +namespace{ + + +const WallClock WATCH_START = WallClock() + Milliseconds(1000000); + +WallClock at(int64_t ms){ + return WATCH_START + Milliseconds(ms); +} + + +// Fires on every frame captured at or after `fires_at`, and counts the +// frames handed to it. +class ScriptedWatcher : public VisualInferenceCallback{ +public: + explicit ScriptedWatcher(std::optional fires_at) + : VisualInferenceCallback("ScriptedWatcher") + , m_fires_at(fires_at) + {} + virtual void make_overlays(VideoOverlaySet&) const override{} + using VisualInferenceCallback::process_frame; + virtual bool process_frame(const VideoSnapshot& frame) override{ + m_calls++; + return m_fires_at && frame.timestamp >= *m_fires_at; + } + size_t calls() const{ + return m_calls; + } +private: + std::optional m_fires_at; + size_t m_calls = 0; +}; + + +struct WatchCase{ + struct Input{ + std::vector frames; + std::optional fires_at = std::nullopt; + std::optional end = std::nullopt; + int64_t tail = 0; + }; + struct Expectation{ + // The index of the frame the wrapper stops on; none: it never stops. + std::optional stops_on; + bool fired; + // Distinct frames recorded, up to and including the one it stops on. + size_t frames; + // Frames handed to the wrapped watcher, repeats included. + size_t watcher_calls; + }; + std::string_view name; + Input input; + Expectation expectation; +}; + +const std::vector WATCH_CASES = { + {.name = "the watcher fires", + .input = {.frames = {0, 33, 66, 99}, .fires_at = 66}, + .expectation = {.stops_on = 2, .fired = true, .frames = 3, .watcher_calls = 3}}, + {.name = "a frame at the window's end stops the watch without firing", + .input = {.frames = {0, 33, 66, 99}, .end = 50}, + .expectation = {.stops_on = 2, .fired = false, .frames = 3, .watcher_calls = 3}}, + {.name = "the watcher firing on the end frame counts as fired", + .input = {.frames = {0, 33, 66}, .fires_at = 60, .end = 50}, + .expectation = {.stops_on = 2, .fired = true, .frames = 3, .watcher_calls = 3}}, + {.name = "no end and no fire never stops", + .input = {.frames = {0, 33, 66}}, + .expectation = {.stops_on = std::nullopt, .fired = false, .frames = 3, .watcher_calls = 3}}, + {.name = "old frames handed over again do not reach the end", + .input = {.frames = {0, 10, 10, 10}, .end = 40}, + .expectation = {.stops_on = std::nullopt, .fired = false, .frames = 2, .watcher_calls = 4}}, + {.name = "a screen showing in the window's last hold fires in the tail", + .input = {.frames = {0, 33, 66, 99, 132, 165, 198}, .fires_at = 80 + 100, .end = 100, .tail = 100}, + .expectation = {.stops_on = 6, .fired = true, .frames = 7, .watcher_calls = 7}}, + {.name = "the watch stops a tail after the window's end without a fire", + .input = {.frames = {0, 33, 66, 99, 132, 165, 198, 231, 264}, .end = 100, .tail = 100}, + .expectation = {.stops_on = 7, .fired = false, .frames = 8, .watcher_calls = 8}}, + {.name = "a frame captured before the window opened is not handed to the watcher", + .input = {.frames = {-40, 10}, .fires_at = -100}, + .expectation = {.stops_on = 1, .fired = true, .frames = 1, .watcher_calls = 1}}, +}; + + +std::string check_watch(const WatchCase& test){ + ScriptedWatcher watcher(test.input.fires_at ? std::optional(at(*test.input.fires_at)) : std::nullopt); + CoveredWatcher covered( + watcher, WATCH_START, Milliseconds(test.input.tail), + test.input.end ? std::optional(at(*test.input.end)) : std::nullopt + ); + std::optional stopped; + for (size_t c = 0; c < test.input.frames.size(); c++){ + if (covered.process_frame(VideoSnapshot(ImageRGB32(), at(test.input.frames[c])))){ + stopped = c; + break; + } + } + const WatchCase::Expectation& expected = test.expectation; + if (stopped != expected.stops_on){ + return std::format( + "stops on frame: expected {}, got {}", + expected.stops_on ? std::to_string(*expected.stops_on) : "none", + stopped ? std::to_string(*stopped) : "none" + ); + } + if (covered.fired() != expected.fired){ + return std::format("fired: expected {}, got {}", expected.fired, covered.fired()); + } + if (covered.coverage().frames() != expected.frames){ + return std::format("frames: expected {}, got {}", expected.frames, covered.coverage().frames()); + } + if (watcher.calls() != expected.watcher_calls){ + return std::format("watcher calls: expected {}, got {}", expected.watcher_calls, watcher.calls()); + } + return ""; +} + + +class CoveredWatchTest : public UnitTest{ +public: + explicit CoveredWatchTest(WatchCase test) + : UnitTest(std::format("Pokemon::CoveredWatch - {}", test.name)) + , m_case(std::move(test)) + {} + virtual UnitTestResult run(Logger&, CancellableScope&) const override{ + const std::string error = check_watch(m_case); + return error.empty() ? UnitTestResult(true) : UnitTestResult(error); + } +private: + WatchCase m_case; +}; + + +} // namespace + + +void add_tests_CoveredWatch(UnitTestDatabase& database){ + for (const WatchCase& test : WATCH_CASES){ + database.add(test); + } +} + + + +} // namespace Pokemon +} // namespace PokemonAutomation diff --git a/SerialPrograms/Source/Pokemon/AutoStory/Engine/Pokemon_CoveredWatch_Tests.h b/SerialPrograms/Source/Pokemon/AutoStory/Engine/Pokemon_CoveredWatch_Tests.h new file mode 100644 index 0000000000..0501566ac3 --- /dev/null +++ b/SerialPrograms/Source/Pokemon/AutoStory/Engine/Pokemon_CoveredWatch_Tests.h @@ -0,0 +1,23 @@ +/* Covered Watch Tests + * + * From: https://github.com/PokemonAutomation/ + * + */ + +#ifndef PokemonAutomation_Pokemon_CoveredWatch_Tests_H +#define PokemonAutomation_Pokemon_CoveredWatch_Tests_H + +#include "Common/Cpp/TestRunners/UnitTestDatabase.h" + +namespace PokemonAutomation{ +namespace Pokemon{ + + +// Registers unit tests for the watcher wrapper that records the frames a watch inspected. +void add_tests_CoveredWatch(UnitTestDatabase& database); + + + +} // namespace Pokemon +} // namespace PokemonAutomation +#endif diff --git a/SerialPrograms/Source/Pokemon/AutoStory/Engine/Pokemon_FrameCoverage.cpp b/SerialPrograms/Source/Pokemon/AutoStory/Engine/Pokemon_FrameCoverage.cpp new file mode 100644 index 0000000000..b99e964d21 --- /dev/null +++ b/SerialPrograms/Source/Pokemon/AutoStory/Engine/Pokemon_FrameCoverage.cpp @@ -0,0 +1,91 @@ +/* Frame Coverage + * + * From: https://github.com/PokemonAutomation/ + * + */ + +#include +#include +#include +#include "Pokemon_FrameCoverage.h" + +namespace PokemonAutomation{ +namespace Pokemon{ + + +FrameCoverage::FrameCoverage(WallClock start) + : m_start(start) +{} + +void FrameCoverage::record(WallClock frame){ + if (frame < m_start){ + return; + } + if (!m_frames.empty() && frame <= m_frames.back()){ + return; + } + m_frames.push_back(frame); +} + +std::optional FrameCoverage::last_frame() const{ + if (m_frames.empty()){ + return std::nullopt; + } + return m_frames.back(); +} + +bool FrameCoverage::reached(WallClock deadline) const{ + return !m_frames.empty() && m_frames.back() >= deadline; +} + +Milliseconds FrameCoverage::largest_gap(WallClock end) const{ + WallDuration largest = WallDuration::zero(); + WallClock previous = m_start; + for (WallClock frame : m_frames){ + const WallClock clamped = std::min(frame, end); + largest = std::max(largest, clamped - previous); + previous = clamped; + } + largest = std::max(largest, end - previous); + return std::chrono::ceil(largest); +} + + +WatchResult judge_watch(bool fired, const FrameCoverage& coverage, WallClock end, Milliseconds max_gap){ + WatchResult result; + result.frames = coverage.frames(); + result.largest_gap = coverage.largest_gap(end); + if (fired){ + result.verdict = WatchVerdict::SEEN; + }else if (result.largest_gap <= max_gap){ + result.verdict = WatchVerdict::NOT_SEEN; + }else{ + result.verdict = WatchVerdict::UNKNOWN; + } + return result; +} + +std::string describe(WatchVerdict verdict){ + switch (verdict){ + case WatchVerdict::SEEN: + return "seen"; + case WatchVerdict::NOT_SEEN: + return "not seen"; + case WatchVerdict::UNKNOWN: + return "unknown"; + } + return "unknown"; +} + +std::string describe(const WatchResult& result){ + const double gap_seconds = result.largest_gap.count() / 1000.0; + if (result.verdict == WatchVerdict::UNKNOWN){ + return std::format("unknown: largest gap between frames {:.2f} s over {} frames", gap_seconds, result.frames); + } + return std::format("{} over {} frames, largest gap {:.2f} s", describe(result.verdict), result.frames, gap_seconds); +} + + + +} // namespace Pokemon +} // namespace PokemonAutomation diff --git a/SerialPrograms/Source/Pokemon/AutoStory/Engine/Pokemon_FrameCoverage.h b/SerialPrograms/Source/Pokemon/AutoStory/Engine/Pokemon_FrameCoverage.h new file mode 100644 index 0000000000..4f12dcd5de --- /dev/null +++ b/SerialPrograms/Source/Pokemon/AutoStory/Engine/Pokemon_FrameCoverage.h @@ -0,0 +1,96 @@ +/* Frame Coverage + * + * From: https://github.com/PokemonAutomation/ + * + * Which frames a watch over a window actually inspected, and whether they + * are enough to say a screen did not show. The inference pivot polls a + * watcher every period with the newest converted frame, and that frame + * can be the one it saw last time or one captured a second ago: under CPU + * load (ConvertFrame at 150 ms mean, PLZA 03.08 on 2026-11-14) a watcher + * that polled 160 times over 8 s may have seen a few frames with second-long + * holes between them, and a 2 s "Registered to the Pokedex" banner fell + * into one. So a window is judged on the capture times of the frames + * inspected (VideoSnapshot::timestamp), not on polls or wall time. + * + */ + +#ifndef PokemonAutomation_Pokemon_FrameCoverage_H +#define PokemonAutomation_Pokemon_FrameCoverage_H + +#include +#include +#include +#include +#include "Common/Cpp/Time.h" + +namespace PokemonAutomation{ +namespace Pokemon{ + + +// The distinct frames inspected since a window opened, by capture time. +class FrameCoverage{ +public: + explicit FrameCoverage(WallClock start); + + // A frame captured at `frame` was inspected. A frame captured before + // the window opened, or not after the last one recorded (the pivot + // handing over the same frame again), adds nothing. + void record(WallClock frame); + + // When the window opened. + WallClock start() const{ + return m_start; + } + // How many distinct frames were recorded. + size_t frames() const{ + return m_frames.size(); + } + // The capture time of the newest frame; none before the first. + std::optional last_frame() const; + // Whether a frame captured at or after `deadline` was inspected: the + // window up to `deadline` is over in frame time, not only in wall time. + bool reached(WallClock deadline) const; + // The longest part of [start, `end`] no inspected frame was captured + // in: before the first frame, between two, or after the last. Rounded + // up to whole ms, so a gap a fraction over a limit is over it. + Milliseconds largest_gap(WallClock end) const; + +private: + WallClock m_start; + std::vector m_frames; +}; + + +// What a watch window showed. +enum class WatchVerdict{ + SEEN, // The watcher fired. + NOT_SEEN, // It did not, and the frames cover the window. + UNKNOWN, // It did not, but a gap between frames could hide the screen. +}; + +// A watch window's verdict and the frames it rests on. +struct WatchResult{ + WatchVerdict verdict = WatchVerdict::UNKNOWN; + size_t frames = 0; + Milliseconds largest_gap = Milliseconds(0); +}; + +// SEEN when the watcher fired. Otherwise NOT_SEEN only when no gap in +// [coverage's start, `end`] is longer than `max_gap`, else UNKNOWN: the +// caller looks again or falls back instead of reading "not there". A +// watcher that must see the screen for a hold (DetectorToFinder) needs +// frames at least that often, so `max_gap` is at most the hold, and at +// most how long the screen shows minus the hold. +WatchResult judge_watch(bool fired, const FrameCoverage& coverage, WallClock end, Milliseconds max_gap); + +// "seen", "not seen", "unknown". +std::string describe(WatchVerdict verdict); +// "not seen over 240 frames, largest gap 0.03 s", +// "unknown: largest gap between frames 1.02 s over 220 frames". +std::string describe(const WatchResult& result); + + + +} // namespace Pokemon +} // namespace PokemonAutomation +#endif diff --git a/SerialPrograms/Source/Pokemon/AutoStory/Engine/Pokemon_FrameCoverage_Tests.cpp b/SerialPrograms/Source/Pokemon/AutoStory/Engine/Pokemon_FrameCoverage_Tests.cpp new file mode 100644 index 0000000000..18d8dc8569 --- /dev/null +++ b/SerialPrograms/Source/Pokemon/AutoStory/Engine/Pokemon_FrameCoverage_Tests.cpp @@ -0,0 +1,158 @@ +/* Frame Coverage Tests + * + * From: https://github.com/PokemonAutomation/ + * + * A watch window judged on scripted frame times: each case is the capture + * times of the frames a watcher inspected (ms after the window opened, + * fractions allowed, in the order inspected), whether it fired, and where + * the window ends. + * + */ + +#include +#include +#include +#include +#include +#include +#include "Common/Cpp/TestRunners/UnitTest.h" +#include "Pokemon_FrameCoverage.h" +#include "Pokemon_FrameCoverage_Tests.h" + +namespace PokemonAutomation{ +namespace Pokemon{ + + +namespace{ + + +const WallClock WINDOW_START = WallClock() + Milliseconds(1000000); + +WallClock at(double ms){ + return WINDOW_START + std::chrono::duration_cast(std::chrono::duration(ms)); +} + +// `count` frames `period` ms apart from `first`. +std::vector frames_every(double first, double period, size_t count){ + std::vector out; + for (size_t c = 0; c < count; c++){ + out.push_back(first + period * (double)c); + } + return out; +} + +// `a` then `b`. +std::vector joined(std::vector a, const std::vector& b){ + a.insert(a.end(), b.begin(), b.end()); + return a; +} + + +struct CoverageCase{ + struct Input{ + std::vector frames; + bool fired = false; + double window_end = 8000; + Milliseconds max_gap = Milliseconds(100); + }; + struct Expectation{ + WatchVerdict verdict; + size_t frames; + Milliseconds largest_gap; + // Whether a frame captured at or after the window's end was inspected. + bool reached_end; + }; + std::string_view name; + Input input; + Expectation expectation; +}; + +const std::vector COVERAGE_CASES = { + {.name = "frames every 33 ms, watcher fired", + .input = {.frames = frames_every(10, 33, 100), .fired = true, .window_end = 3000}, + .expectation = {.verdict = WatchVerdict::SEEN, .frames = 100, .largest_gap = Milliseconds(33), .reached_end = true}}, + {.name = "frames every 33 ms through the window, not fired", + .input = {.frames = frames_every(10, 33, 250)}, + .expectation = {.verdict = WatchVerdict::NOT_SEEN, .frames = 250, .largest_gap = Milliseconds(33), .reached_end = true}}, + {.name = "a second of dropped frames mid-window", + .input = {.frames = joined(frames_every(10, 33, 100), frames_every(4300, 33, 120))}, + .expectation = {.verdict = WatchVerdict::UNKNOWN, .frames = 220, .largest_gap = Milliseconds(1023), .reached_end = true}}, + {.name = "no frame inspected", + .input = {.frames = {}}, + .expectation = {.verdict = WatchVerdict::UNKNOWN, .frames = 0, .largest_gap = Milliseconds(8000), .reached_end = false}}, + {.name = "frames stop before the window ends", + .input = {.frames = frames_every(10, 33, 200)}, + .expectation = {.verdict = WatchVerdict::UNKNOWN, .frames = 200, .largest_gap = Milliseconds(1423), .reached_end = false}}, + {.name = "first frame late after the window opened", + .input = {.frames = frames_every(500, 33, 240)}, + .expectation = {.verdict = WatchVerdict::UNKNOWN, .frames = 240, .largest_gap = Milliseconds(500), .reached_end = true}}, + {.name = "the same frame handed over again counts once", + .input = {.frames = {10, 10, 10, 43, 43, 76}, .window_end = 80}, + .expectation = {.verdict = WatchVerdict::NOT_SEEN, .frames = 3, .largest_gap = Milliseconds(33), .reached_end = false}}, + {.name = "a frame captured before the window opened is not evidence", + .input = {.frames = {-40, 60, 93}, .window_end = 90}, + .expectation = {.verdict = WatchVerdict::NOT_SEEN, .frames = 2, .largest_gap = Milliseconds(60), .reached_end = true}}, + {.name = "fired after dropped frames is still seen", + .input = {.frames = {10, 1500, 1533}, .fired = true, .window_end = 2000}, + .expectation = {.verdict = WatchVerdict::SEEN, .frames = 3, .largest_gap = Milliseconds(1490), .reached_end = false}}, + {.name = "gaps of exactly the max gap still cover", + .input = {.frames = frames_every(0, 100, 11), .window_end = 1000}, + .expectation = {.verdict = WatchVerdict::NOT_SEEN, .frames = 11, .largest_gap = Milliseconds(100), .reached_end = true}}, + {.name = "a gap a fraction of a ms over the max gap does not cover", + .input = {.frames = {0, 100.5, 200}, .window_end = 200}, + .expectation = {.verdict = WatchVerdict::UNKNOWN, .frames = 3, .largest_gap = Milliseconds(101), .reached_end = true}}, +}; + + +std::string check_coverage(const CoverageCase& test){ + FrameCoverage coverage(WINDOW_START); + for (double ms : test.input.frames){ + coverage.record(at(ms)); + } + const WallClock end = at(test.input.window_end); + const WatchResult result = judge_watch(test.input.fired, coverage, end, test.input.max_gap); + const CoverageCase::Expectation& expected = test.expectation; + if (result.verdict != expected.verdict){ + return std::format("verdict: expected \"{}\", got \"{}\"", describe(expected.verdict), describe(result)); + } + if (result.frames != expected.frames){ + return std::format("frames: expected {}, got {}", expected.frames, result.frames); + } + if (result.largest_gap != expected.largest_gap){ + return std::format("largest gap: expected {} ms, got {} ms", expected.largest_gap.count(), result.largest_gap.count()); + } + if (coverage.reached(end) != expected.reached_end){ + return std::format("reached the window's end: expected {}, got {}", expected.reached_end, !expected.reached_end); + } + return ""; +} + + +class FrameCoverageTest : public UnitTest{ +public: + explicit FrameCoverageTest(CoverageCase test) + : UnitTest(std::format("Pokemon::FrameCoverage - {}", test.name)) + , m_case(std::move(test)) + {} + virtual UnitTestResult run(Logger&, CancellableScope&) const override{ + const std::string error = check_coverage(m_case); + return error.empty() ? UnitTestResult(true) : UnitTestResult(error); + } +private: + CoverageCase m_case; +}; + + +} // namespace + + +void add_tests_FrameCoverage(UnitTestDatabase& database){ + for (const CoverageCase& test : COVERAGE_CASES){ + database.add(test); + } +} + + + +} // namespace Pokemon +} // namespace PokemonAutomation diff --git a/SerialPrograms/Source/Pokemon/AutoStory/Engine/Pokemon_FrameCoverage_Tests.h b/SerialPrograms/Source/Pokemon/AutoStory/Engine/Pokemon_FrameCoverage_Tests.h new file mode 100644 index 0000000000..96aeb0d42d --- /dev/null +++ b/SerialPrograms/Source/Pokemon/AutoStory/Engine/Pokemon_FrameCoverage_Tests.h @@ -0,0 +1,23 @@ +/* Frame Coverage Tests + * + * From: https://github.com/PokemonAutomation/ + * + */ + +#ifndef PokemonAutomation_Pokemon_FrameCoverage_Tests_H +#define PokemonAutomation_Pokemon_FrameCoverage_Tests_H + +#include "Common/Cpp/TestRunners/UnitTestDatabase.h" + +namespace PokemonAutomation{ +namespace Pokemon{ + + +// Registers unit tests for judging a watch window on the frames it inspected. +void add_tests_FrameCoverage(UnitTestDatabase& database); + + + +} // namespace Pokemon +} // namespace PokemonAutomation +#endif diff --git a/SerialPrograms/Source/Pokemon/AutoStory/Engine/Pokemon_StoryActionNotImplemented.cpp b/SerialPrograms/Source/Pokemon/AutoStory/Engine/Pokemon_StoryActionNotImplemented.cpp new file mode 100644 index 0000000000..d50dccd657 --- /dev/null +++ b/SerialPrograms/Source/Pokemon/AutoStory/Engine/Pokemon_StoryActionNotImplemented.cpp @@ -0,0 +1,21 @@ +/* Story Action Not Implemented + * + * From: https://github.com/PokemonAutomation/ + * + */ + +#include +#include "Pokemon_StoryActionNotImplemented.h" + +namespace PokemonAutomation{ +namespace Pokemon{ + + +StoryActionNotImplemented::StoryActionNotImplemented(std::string message) + : OperationFailedException(ErrorReportMode::NO_ERROR_REPORT, std::move(message)) +{} + + + +} // namespace Pokemon +} // namespace PokemonAutomation diff --git a/SerialPrograms/Source/Pokemon/AutoStory/Engine/Pokemon_StoryActionNotImplemented.h b/SerialPrograms/Source/Pokemon/AutoStory/Engine/Pokemon_StoryActionNotImplemented.h new file mode 100644 index 0000000000..566ade4269 --- /dev/null +++ b/SerialPrograms/Source/Pokemon/AutoStory/Engine/Pokemon_StoryActionNotImplemented.h @@ -0,0 +1,35 @@ +/* Story Action Not Implemented + * + * From: https://github.com/PokemonAutomation/ + * + */ + +#ifndef PokemonAutomation_Pokemon_StoryActionNotImplemented_H +#define PokemonAutomation_Pokemon_StoryActionNotImplemented_H + +#include +#include "CommonFramework/Exceptions/OperationFailedException.h" + +namespace PokemonAutomation{ +namespace Pokemon{ + + +// A story action the game has no code for yet, thrown with what it waits +// for instead of pressing buttons blind. A game's backend lets it end the +// run instead of reloading and trying again, since every attempt would +// fail the same way. +class StoryActionNotImplemented : public OperationFailedException{ +public: + explicit StoryActionNotImplemented(std::string message); + + // code-health: allow char_pointer -- Exception::name() returns a const char pointer in the base class + virtual const char* name() const override{ + return "StoryActionNotImplemented"; + } +}; + + + +} // 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 index a1b502062c..ccfd146863 100644 --- a/SerialPrograms/Source/Pokemon/AutoStory/Engine/Pokemon_StoryEngine.cpp +++ b/SerialPrograms/Source/Pokemon/AutoStory/Engine/Pokemon_StoryEngine.cpp @@ -11,6 +11,7 @@ #include #include "Pokemon/AutoStory/Pokemon_CheckpointAttempts.h" #include "Pokemon/AutoStory/Pokemon_StoryEvents.h" +#include "Pokemon/AutoStory/Pokemon_StoryOutcomeClass.h" #include "Pokemon_StoryEngine.h" namespace PokemonAutomation{ @@ -67,12 +68,12 @@ class RunnerExecutor : public StoryStepExecutor{ // `game` with its SAVE step "save" saving `current` only while `mode` is // PER_CHECKPOINT: a checkpoint under test or verification must not save -// part-way. +// part-way. Sets `saved` when it saves. template StoryGame with_gated_save_step( - StoryGame game, const StorySaveMode& mode, const StoryCheckpoint* const& current + StoryGame game, const StorySaveMode& mode, const StoryCheckpoint* const& current, bool& saved ){ - StoryActionHandler gated = [&mode, ¤t, save = game.save]( + StoryActionHandler gated = [&mode, ¤t, &saved, save = game.save]( StoryBackend& backend, const StoryActionCall&, RunState& ){ if (mode != StorySaveMode::PER_CHECKPOINT){ @@ -82,7 +83,9 @@ StoryGame with_gated_save_step( if (!save || current == nullptr){ return outcome_failed("unsupported_step", "save needs StoryGame::save"); } - return save(backend, *current); + Outcome outcome = save(backend, *current); + saved = saved || outcome.succeeded(); + return outcome; }; game.actions.push_back({.spec = {.kind = StoryStepKind::SAVE, .name = "save", .args = {}}, .handler = std::move(gated)}); return game; @@ -180,7 +183,7 @@ ObservedState observed_state(const Observation& observation){ template StoryEngine::StoryEngine(const StoryGame& game, StoryBackend& backend) - : m_game(with_gated_save_step(game, m_save_mode, m_checkpoint)) + : m_game(with_gated_save_step(game, m_save_mode, m_checkpoint, m_saved_part_way)) , m_backend(backend) , m_registry(m_game) , m_runner(m_registry, backend) @@ -221,7 +224,9 @@ StoryEngineReport StoryEngine::run_once( m_backend.log(report.save.reason); m_save_mode = report.save.mode; m_checkpoint = &checkpoint; + m_saved_part_way = false; report.run = run_steps(checkpoint, state); + report.saved_part_way = m_saved_part_way; m_save_mode = StorySaveMode::NONE; m_checkpoint = nullptr; if (!report.run.completed){ @@ -265,6 +270,13 @@ StoryEngineReport StoryEngine::run_with_retries( if (report.verdict == CheckpointVerdict::PASSED){ return AttemptResult::PASSED; } + if (report.saved_part_way){ + m_backend.log(std::format( + "[Checkpoint] {}: a save step saved part-way, so a reload would not return to its start: no retry", + checkpoint.id + )); + return AttemptResult::FINAL; + } return repeats_on_reload(report.run.failure) ? AttemptResult::FINAL : AttemptResult::FAILED; }, .reset = [&](size_t next_attempt){ @@ -310,7 +322,7 @@ SegmentReport StoryEngine::run_segment( report.failed_checkpoint = checkpoint.id; report.failed_event = result.run.failed_name; report.failure = run_failure(result); - m_backend.log(std::format("[Segment] {}: failed at {}: {}", id, checkpoint.id, to_string(report.failure))); + m_backend.log(std::format("[Segment] {}: failed at {}: {}", id, checkpoint.id, to_string_with_class(report.failure))); return report; } start_saved = result.saved; @@ -350,7 +362,7 @@ VerifyReport StoryEngine::verify_checkpoint(const StoryCheckpoint& che report.saved = result.saved; m_backend.log(std::format( "[Verify] {}: run {}/{} {}", checkpoint.id, run, policy.runs, - passed ? std::string("passed") : std::format("failed: {}", to_string(run_failure(result))) + passed ? std::string("passed") : std::format("failed: {}", to_string_with_class(run_failure(result))) )); if (repeats_on_reload(result.run.failure)){ report.failure = result.run.failure; diff --git a/SerialPrograms/Source/Pokemon/AutoStory/Engine/Pokemon_StoryEngine.h b/SerialPrograms/Source/Pokemon/AutoStory/Engine/Pokemon_StoryEngine.h index e7cabbcf9a..185ab5dc52 100644 --- a/SerialPrograms/Source/Pokemon/AutoStory/Engine/Pokemon_StoryEngine.h +++ b/SerialPrograms/Source/Pokemon/AutoStory/Engine/Pokemon_StoryEngine.h @@ -70,9 +70,10 @@ class StoryEngine{ // `attempts_per_checkpoint` runs, only when a reload returns to the // save it started from: the first checkpoint's, or one the checkpoint // before it saved at its end. In none and after_verification modes - // (#329) that leaves only the first. No reload either for a failure - // every attempt would repeat: a lint, a console_only action, the game - // not running. Logs "[Segment] : ..." lines. + // that leaves only the first. No reload once a SAVE step has saved + // part-way through the attempt (the reload would land there), nor for + // a failure every attempt would repeat: a lint, a console_only action, + // the game not running. Logs "[Segment] : ..." lines. SegmentReport run_segment( std::string_view id, std::span checkpoints, size_t attempts_per_checkpoint, RunState& state @@ -109,9 +110,11 @@ class StoryEngine{ const StoryCheckpoint& checkpoint, SavePoint point, size_t attempts, RunState& state, CheckpointRun& run ); - // Declared first: m_game's save step reads them. + // Declared first: m_game's save step reads them, and sets + // m_saved_part_way when it saves. StorySaveMode m_save_mode = StorySaveMode::NONE; const StoryCheckpoint* m_checkpoint = nullptr; + bool m_saved_part_way = false; StoryGame m_game; StoryBackend& m_backend; StoryActionRegistry m_registry; diff --git a/SerialPrograms/Source/Pokemon/AutoStory/Engine/Pokemon_StoryEnginePolicy.h b/SerialPrograms/Source/Pokemon/AutoStory/Engine/Pokemon_StoryEnginePolicy.h index 0856147d0b..197fce0023 100644 --- a/SerialPrograms/Source/Pokemon/AutoStory/Engine/Pokemon_StoryEnginePolicy.h +++ b/SerialPrograms/Source/Pokemon/AutoStory/Engine/Pokemon_StoryEnginePolicy.h @@ -52,6 +52,9 @@ struct StoryEngineReport{ // Checked after steps that completed. std::optional postconditions = std::nullopt; bool saved = false; + // A SAVE step among its steps saved: a reload now returns there, not + // to the save the checkpoint started from. + bool saved_part_way = false; }; diff --git a/SerialPrograms/Source/Pokemon/AutoStory/Engine/Pokemon_StoryEnginePolicy_Tests.cpp b/SerialPrograms/Source/Pokemon/AutoStory/Engine/Pokemon_StoryEnginePolicy_Tests.cpp index e65b730dbf..c1f7b74094 100644 --- a/SerialPrograms/Source/Pokemon/AutoStory/Engine/Pokemon_StoryEnginePolicy_Tests.cpp +++ b/SerialPrograms/Source/Pokemon/AutoStory/Engine/Pokemon_StoryEnginePolicy_Tests.cpp @@ -131,6 +131,8 @@ const EngineCase ENGINE_CASES[] = { {.name = "failed run never saves", .input = {.phase = "reproduction", .end_map = ""}, .expectation = {.mode = StorySaveMode::PER_CHECKPOINT, .verdict = CheckpointVerdict::FAILED, .saves = 0, .line = "[Save] 00.31: run failed: not saved"}}, + {.name = "save step skipped while testing", .input = {.phase = "testing", .steps = SAVE_STEPS}, + .expectation = {.mode = StorySaveMode::NONE, .saves = 0, .line = "[Save] save step skipped: save mode none"}}, {.name = "save step skipped while verifying", .input = {.phase = "verification", .steps = SAVE_STEPS}, .expectation = {.mode = StorySaveMode::AFTER_VERIFICATION, .saves = 1, .line = "[Save] save step skipped: save mode after_verification"}}, {.name = "save step saves in reproduction", .input = {.phase = "reproduction", .steps = SAVE_STEPS}, diff --git a/SerialPrograms/Source/Pokemon/AutoStory/Engine/Pokemon_StoryEngineRuns_Tests.cpp b/SerialPrograms/Source/Pokemon/AutoStory/Engine/Pokemon_StoryEngineRuns_Tests.cpp index 851f380bcc..9f4a51a3d8 100644 --- a/SerialPrograms/Source/Pokemon/AutoStory/Engine/Pokemon_StoryEngineRuns_Tests.cpp +++ b/SerialPrograms/Source/Pokemon/AutoStory/Engine/Pokemon_StoryEngineRuns_Tests.cpp @@ -5,12 +5,11 @@ * What a game needs from the engine to drop its own workarounds (the PLZA * move, #335): a scripted backend for any pose type, the move stick and * the heading reading, the choice and interact events, a screen machine - * over observations, the step in an action's call, the checkpoint in the - * save, the segment and verify loops, console-only actions, declared poses - * read as the game's pose type, and tile actions only for tile games. + * over observations, the step in an action's call, declared poses of the + * game's kind only, and tile actions only for tile games. * Then what PLZA found on the engine: readers opt in to the postcondition * check, inputs logged by button name, waiting states may stay still, and - * the stick's release. + * the stick's release. It also checks the engine's breakpoints. * */ @@ -60,15 +59,6 @@ bool has_line(const FakeStoryBackend& backend, std::string_view line){ return false; } -template -size_t count_lines(const FakeStoryBackend& backend, std::string_view line){ - size_t count = 0; - for (const std::string& each : backend.lines()){ - count += each == line ? 1 : 0; - } - return count; -} - template std::string expect_inputs(const FakeStoryBackend& backend, std::string_view expected){ const std::string got = joined(backend.inputs()); @@ -98,16 +88,6 @@ StoryCheckpoint checkpoint_of(std::string id, std::vector steps){ return checkpoint; } -// `checkpoint` in `phase`, verified with its steps as they are now. -template -StoryCheckpoint in_phase(StoryCheckpoint checkpoint, StoryPhase phase, const StoryEngine& engine){ - checkpoint.metadata.phase = phase; - checkpoint.metadata.verified = StoryVerification{ - .steps_hash = engine.steps_hash(checkpoint), .build = "abc", .date = "2026-11-10", .runs = "3/3", - }; - return checkpoint; -} - // A GAME action of no args. template StoryAction game_action(std::string name, StoryActionHandler handler){ @@ -517,235 +497,6 @@ std::string handler_sees_step(CancellableScope& scope){ return *seen == "opening / the long intro" ? "" : std::format("expected the step, got \"{}\"", *seen); } -// Gap 6: the save is told its checkpoint, at the end and at a SAVE step. -std::string save_gets_checkpoint(CancellableScope& scope){ - StoryGame game = flaky_game(0); - FakeStoryBackend backend({.looks = {look({ScreenEvent::PLAYER_CAN_MOVE})}}, scope); - StoryEngine engine(game, backend); - StoryStep save; - save.kind = StoryStepKind::SAVE; - save.name = "save_here"; - const StoryCheckpoint checkpoint = in_phase(checkpoint_of("02.01", {game_step("walk", "fine"), save}), StoryPhase::REPRODUCTION, engine); - RunState state; - const StoryEngineReport report = engine.run_checkpoint(checkpoint, SavePoint::CHECKPOINT_END, state); - if (!report.saved){ - return "expected the checkpoint to save at its end"; - } - const size_t saves = count_lines(backend, "[Test] save 02.01"); - return saves == 2 ? "" : std::format("expected 2 saves of 02.01, got {}: {}", saves, joined(backend.lines())); -} - -// Gap 8: a console_only action is refused, before any input, on a backend -// that is no console; it runs on one. -StoryGame console_game(){ - StoryGame game = flaky_game(0); - StoryAction menu = game_action("open_menu", [](StoryBackend& backend, const StoryActionCall&, RunState&){ - backend.press(NintendoSwitch::BUTTON_X, 80ms, 120ms); - return outcome_ok(); - }); - menu.spec.console_only = true; - game.actions.push_back(std::move(menu)); - return game; -} - -std::string console_only_refused(CancellableScope& scope){ - const StoryGame game = console_game(); - const StoryActionRegistry registry(game); - RunState state; - FakeStoryBackend script({}, scope); - const Outcome refused = registry.dispatch(script, game_step("menu", "open_menu"), state); - if (refused.failure != CONSOLE_ONLY || refused.detail != "open_menu runs only on a console, not on a script backend"){ - return std::format("expected console_only, got {}", to_string(refused)); - } - const std::string none = expect_inputs(script, ""); - if (!none.empty()){ - return none; - } - FakeStoryBackend console({.kind = StoryBackendKind::CONSOLE}, scope); - if (!registry.dispatch(console, game_step("menu", "open_menu"), state).succeeded()){ - return "expected the action to run on a console"; - } - return expect_inputs(console, "press X"); -} - -// Gap 7 and 8: no reload for a console_only failure, which every attempt -// would repeat. -std::string segment_no_reload_for_console_only(CancellableScope& scope){ - const StoryGame game = console_game(); - FakeStoryBackend backend({.looks = {look({ScreenEvent::PLAYER_CAN_MOVE})}}, scope); - StoryEngine engine(game, backend); - const std::vector checkpoints{checkpoint_of("01", {game_step("menu", "open_menu")})}; - RunState state; - const SegmentReport report = engine.run_segment("seg", checkpoints, 3, state); - if (report.completed || report.failure.failure != CONSOLE_ONLY || report.failed_event != "menu"){ - return std::format("expected the segment to stop on console_only at menu, got {}", to_string(report.failure)); - } - return count_lines(backend, "[Test] reload") == 0 ? "" : "expected no reload"; -} - -// Gap 7: the first checkpoint is retried after a reload; one after it -// only when the one before saved at its end (#329). -struct SegmentCase{ - struct Input{ - StoryPhase phase; - // Which checkpoint fails once: 0 or 1. - size_t flaky = 0; - }; - - struct Expectation{ - bool completed = false; - size_t reloads = 0; - size_t saves = 0; - }; - - std::string_view name; - Input input; - Expectation expectation; -}; - -const SegmentCase SEGMENT_CASES[] = { - {.name = "first retries while testing", .input = {.phase = StoryPhase::TESTING, .flaky = 0}, - .expectation = {.completed = true, .reloads = 1, .saves = 0}}, - {.name = "second does not retry while testing", .input = {.phase = StoryPhase::TESTING, .flaky = 1}, - .expectation = {.completed = false, .reloads = 0, .saves = 0}}, - {.name = "second does not retry while verifying", .input = {.phase = StoryPhase::VERIFICATION, .flaky = 1}, - .expectation = {.completed = false, .reloads = 0, .saves = 0}}, - {.name = "second retries after a reproduction save", .input = {.phase = StoryPhase::REPRODUCTION, .flaky = 1}, - .expectation = {.completed = true, .reloads = 1, .saves = 2}}, -}; - -std::string check_segment(const SegmentCase& test, CancellableScope& scope){ - const StoryGame game = flaky_game(1); - FakeStoryBackend backend({.looks = {look({ScreenEvent::PLAYER_CAN_MOVE})}}, scope); - StoryEngine engine(game, backend); - std::vector checkpoints; - for (size_t c = 0; c < 2; c++){ - const std::string action = c == test.input.flaky ? "flaky" : "fine"; - checkpoints.push_back(in_phase(checkpoint_of(std::format("0{}", c + 1), {game_step("walk", action)}), test.input.phase, engine)); - } - RunState state; - const SegmentReport report = engine.run_segment("seg", checkpoints, 3, state); - const size_t reloads = count_lines(backend, "[Test] reload"); - const size_t saves = count_lines(backend, "[Test] save 01") + count_lines(backend, "[Test] save 02"); - if (report.completed != test.expectation.completed || reloads != test.expectation.reloads || saves != test.expectation.saves){ - return std::format( - "expected completed {}, {} reloads, {} saves; got {}, {}, {}: {}", - test.expectation.completed, test.expectation.reloads, test.expectation.saves, - report.completed, reloads, saves, joined(backend.lines()) - ); - } - return report.reloads == reloads ? "" : "expected the report to count each reload"; -} - -class StorySegmentTest : public UnitTest{ -public: - explicit StorySegmentTest(SegmentCase test) - : UnitTest(std::format("Pokemon::StoryEngine segment - {}", test.name)) - , m_case(std::move(test)) - {} - virtual UnitTestResult run(Logger&, CancellableScope& scope) const override{ - const std::string error = check_segment(m_case, scope); - return error.empty() ? UnitTestResult(true) : UnitTestResult(error); - } -private: - SegmentCase m_case; -}; - -// The engine's retries run through run_checkpoint_attempts(): the same -// reload and pass lines and attempt counts as its own loop had. -struct RetryCase{ - struct Input{ - // Calls of the checkpoint's action that fail before one passes. - size_t failures = 0; - size_t attempts = 0; - }; - - struct Expectation{ - bool passed = false; - size_t attempts = 0; - // Lines the run writes once each. - std::vector lines; - }; - - std::string_view name; - Input input; - Expectation expectation; -}; - -const RetryCase RETRY_CASES[] = { - {.name = "pass after a reload", .input = {.failures = 1, .attempts = 3}, - .expectation = {.passed = true, .attempts = 2, .lines = { - "[Checkpoint] 01: failed, resetting for attempt 2/3", - "[Test] reload", - "[Checkpoint] 01: passed on attempt 2 (1 reset)", - }}}, - {.name = "stop after the last attempt", .input = {.failures = 5, .attempts = 2}, - .expectation = {.passed = false, .attempts = 2, .lines = { - "[Checkpoint] 01: failed, resetting for attempt 2/2", - "[Test] reload", - }}}, -}; - -std::string check_retry(const RetryCase& test, CancellableScope& scope){ - const StoryGame game = flaky_game(test.input.failures); - FakeStoryBackend backend({.looks = {look({ScreenEvent::PLAYER_CAN_MOVE})}}, scope); - StoryEngine engine(game, backend); - const std::vector checkpoints{checkpoint_of("01", {game_step("walk", "flaky")})}; - RunState state; - const SegmentReport report = engine.run_segment("seg", checkpoints, test.input.attempts, state); - const CheckpointRun& run = report.runs.at(0); - if (run.passed != test.expectation.passed || run.attempts != test.expectation.attempts){ - return std::format( - "expected passed {} after {} attempts, got {} after {}: {}", - test.expectation.passed, test.expectation.attempts, run.passed, run.attempts, joined(backend.lines()) - ); - } - for (std::string_view line : test.expectation.lines){ - if (count_lines(backend, line) != 1){ - return std::format("expected \"{}\" once: {}", line, joined(backend.lines())); - } - } - return ""; -} - -class StoryRetryTest : public UnitTest{ -public: - explicit StoryRetryTest(RetryCase test) - : UnitTest(std::format("Pokemon::StoryEngine retry - {}", test.name)) - , m_case(std::move(test)) - {} - virtual UnitTestResult run(Logger&, CancellableScope& scope) const override{ - const std::string error = check_retry(m_case, scope); - return error.empty() ? UnitTestResult(true) : UnitTestResult(error); - } -private: - RetryCase m_case; -}; - -// Gap 7: verify runs a checkpoint 3 times from one save, saving only at -// the end of the last, and only when every run passed. -std::string verify_saves_after_all_passed(CancellableScope& scope){ - for (size_t failures = 0; failures < 2; failures++){ - const StoryGame game = flaky_game(failures); - FakeStoryBackend backend({.looks = {look({ScreenEvent::PLAYER_CAN_MOVE})}}, scope); - StoryEngine engine(game, backend); - const StoryCheckpoint checkpoint = in_phase(checkpoint_of("00.15b", {game_step("battle", "flaky")}), StoryPhase::VERIFICATION, engine); - RunState state; - const VerifyReport report = engine.verify_checkpoint(checkpoint, VerifyPolicy{.runs = 3, .passes_needed = 2}, state); - const size_t saves = count_lines(backend, "[Test] save 00.15b"); - const size_t reloads = count_lines(backend, "[Test] reload"); - const size_t passes = 3 - failures; - if (!report.verified || report.passes != passes || reloads != 2 || saves != (failures == 0 ? 1 : 0) || report.saved != (failures == 0)){ - return std::format( - "{} failures: expected verified, {} passes, 2 reloads, {} saves; got {}, {}, {}, {}", - failures, passes, failures == 0 ? 1 : 0, report.verified, report.passes, reloads, saves - ); - } - } - return ""; -} - - // A game whose "mark" action records "run " and whose pause hook // records "pause