From 80eb57ea5da37201c80270c3be97d2f9cb1e825c Mon Sep 17 00:00:00 2001 From: dayfine Date: Sun, 15 Nov 2026 00:15:25 -0800 Subject: [PATCH 1/4] AutoStory: the story engine --- .../AutoStory/Engine/Pokemon_StoryEngine.cpp | 436 +++++++++++ .../AutoStory/Engine/Pokemon_StoryEngine.h | 134 ++++ .../Pokemon_StoryEnginePolicy_Tests.cpp | 438 +++++++++++ .../Engine/Pokemon_StoryEnginePolicy_Tests.h | 23 + .../Engine/Pokemon_StoryEngineRuns_Tests.cpp | 700 ++++++++++++++++++ .../Engine/Pokemon_StoryEngineRuns_Tests.h | 24 + .../Pokemon_StoryEngineSaveRetry_Tests.cpp | 442 +++++++++++ .../Pokemon_StoryEngineSaveRetry_Tests.h | 23 + .../AutoStory/Pokemon_AutoStory_Tests.h | 6 + SerialPrograms/cmake/SourceFiles.cmake | 8 + 10 files changed, 2234 insertions(+) create mode 100644 SerialPrograms/Source/Pokemon/AutoStory/Engine/Pokemon_StoryEngine.cpp create mode 100644 SerialPrograms/Source/Pokemon/AutoStory/Engine/Pokemon_StoryEngine.h create mode 100644 SerialPrograms/Source/Pokemon/AutoStory/Engine/Pokemon_StoryEnginePolicy_Tests.cpp create mode 100644 SerialPrograms/Source/Pokemon/AutoStory/Engine/Pokemon_StoryEnginePolicy_Tests.h create mode 100644 SerialPrograms/Source/Pokemon/AutoStory/Engine/Pokemon_StoryEngineRuns_Tests.cpp create mode 100644 SerialPrograms/Source/Pokemon/AutoStory/Engine/Pokemon_StoryEngineRuns_Tests.h create mode 100644 SerialPrograms/Source/Pokemon/AutoStory/Engine/Pokemon_StoryEngineSaveRetry_Tests.cpp create mode 100644 SerialPrograms/Source/Pokemon/AutoStory/Engine/Pokemon_StoryEngineSaveRetry_Tests.h diff --git a/SerialPrograms/Source/Pokemon/AutoStory/Engine/Pokemon_StoryEngine.cpp b/SerialPrograms/Source/Pokemon/AutoStory/Engine/Pokemon_StoryEngine.cpp new file mode 100644 index 0000000000..ccfd146863 --- /dev/null +++ b/SerialPrograms/Source/Pokemon/AutoStory/Engine/Pokemon_StoryEngine.cpp @@ -0,0 +1,436 @@ +/* Story Engine + * + * From: https://github.com/PokemonAutomation/ + * + */ + +#include +#include +#include +#include +#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{ +namespace Pokemon{ + + +namespace{ + + +// The old executor interface over the step runner, so the engine builds +// its events with build_story_checkpoint() (from_save, once_per_save). +// Goes once StoryStepExecutor is deleted and that code moves here. +template +class RunnerExecutor : public StoryStepExecutor{ +public: + RunnerExecutor(StoryStepRunner& runner, const StoryGame& game, StoryPausePoints& pause) + : m_runner(runner) + , m_game(game) + , m_pause(pause) + {} + + virtual void begin_attempt(const StoryCheckpoint& data) override{ + m_checkpoint = &data; + if (m_game.begin_attempt){ + m_game.begin_attempt(data); + } + } + virtual Outcome run(const StoryStep& step, RunState& state) override{ + m_pause.before_step(pause_label(step)); + return m_runner.act(step, state); + } + virtual bool holds(std::string_view condition, RunState& state) override{ + return m_runner.holds(condition, state); + } + +private: + // The step's place in its checkpoint (step names are unique, which the + // lint checks). + std::string pause_label(const StoryStep& step) const{ + size_t index = 0; + if (m_checkpoint != nullptr){ + while (index < m_checkpoint->steps.size() && m_checkpoint->steps[index].name != step.name){ + index++; + } + } + return story_step_pause_label(m_checkpoint == nullptr ? "" : m_checkpoint->id, index, step.name); + } + + StoryStepRunner& m_runner; + const StoryGame& m_game; + StoryPausePoints& m_pause; + const StoryCheckpoint* m_checkpoint = nullptr; +}; + +// `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. Sets `saved` when it saves. +template +StoryGame with_gated_save_step( + StoryGame game, const StorySaveMode& mode, const StoryCheckpoint* const& current, bool& saved +){ + StoryActionHandler gated = [&mode, ¤t, &saved, save = game.save]( + StoryBackend& backend, const StoryActionCall&, RunState& + ){ + if (mode != StorySaveMode::PER_CHECKPOINT){ + backend.log(std::format("[Save] save step skipped: save mode {}", story_save_mode_name(mode))); + return outcome_unchanged(); + } + if (!save || current == nullptr){ + return outcome_failed("unsupported_step", "save needs StoryGame::save"); + } + 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; +} + +// A failure every attempt would repeat: no reload for it. +bool repeats_on_reload(const Outcome& failure){ + return failure.failure == GAME_NOT_RUNNING || failure.failure == CONSOLE_ONLY || failure.failure == "lint_failed"; +} + +// What stopped `report`'s run: its steps' failure, or its postconditions. +Outcome run_failure(const StoryEngineReport& report){ + if (!report.run.completed){ + return report.run.failure; + } + return outcome_failed("postconditions_failed"); +} + + +// The items ("bag.") and flags ("flag.", non-zero is set) of +// `observation`'s readings. +ObservedState observed_readings(const ScreenObservation& observation){ + constexpr std::string_view BAG = "bag."; + constexpr std::string_view FLAG = "flag."; + ObservedState observed; + for (const auto& [name, value] : observation.readings){ + if (name.starts_with(BAG)){ + observed.items[name.substr(BAG.size())] = value < 0 ? 0 : (size_t)value; + }else if (name.starts_with(FLAG)){ + observed.flags[name.substr(FLAG.size())] = value != 0; + } + } + return observed; +} + + +// What checking `checkpoint`'s postconditions needs read: "pose" for an +// end position, "bag." per item, "flag." per flag. +std::vector postcondition_needs(const StoryCheckpoint& checkpoint){ + std::vector needs; + if (checkpoint_end_pose(checkpoint)){ + needs.emplace_back("pose"); + } + for (const StoryItem& item : checkpoint.postconditions.items){ + needs.push_back(std::format("bag.{}", item.item)); + } + for (const std::string& flag : checkpoint.postconditions.flags){ + needs.push_back(std::format("flag.{}", flag)); + } + return needs; +} + +// Whether the postcondition check of a checkpoint that `needs` these runs +// `reader` on a backend of `kind`. +template +bool runs_after_checkpoint(const StoryGameReader& reader, const std::vector& needs, StoryBackendKind kind){ + if (!reader.read || reader.use != StoryReaderUse::AFTER_CHECKPOINT){ + return false; + } + if (reader.console_only && kind != StoryBackendKind::CONSOLE){ + return false; + } + for (const std::string& need : needs){ + if (story_reader_supplies(reader.supplies, need)){ + return true; + } + } + return false; +} + + +} // namespace + + +ObservedState observed_state(const Observation& observation){ + ObservedState observed = observed_readings(observation); + if (observation.pose){ + observed.map = observation.pose->map; + if (observation.pose->tiles.size() == 1){ + observed.tile = observation.pose->tiles[0]; + } + observed.facing = observation.pose->facing; + } + return observed; +} + +ObservedState observed_state(const Observation& observation){ + ObservedState observed = observed_readings(observation); + if (observation.pose){ + observed.map = observation.pose->zone; + } + return observed; +} + + +template +StoryEngine::StoryEngine(const StoryGame& game, StoryBackend& backend) + : 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) +{ + m_registry.pause_points().set_log([&backend](std::string_view line){ + backend.log(line); + }); +} + +template +std::string StoryEngine::steps_hash(const StoryCheckpoint& checkpoint) const{ + return story_steps_hash(checkpoint); +} + +template +StoryEngineReport StoryEngine::run_checkpoint(const StoryCheckpoint& checkpoint, SavePoint point, RunState& state){ + return run_once(checkpoint, point, SaveGate::BY_PHASE, state); +} + +template +StoryEngineReport StoryEngine::run_once( + const StoryCheckpoint& checkpoint, SavePoint point, SaveGate gate, RunState& state +){ + StoryEngineReport report; + const std::vector problems = m_registry.lint(checkpoint); + if (!problems.empty()){ + for (const std::string& problem : problems){ + m_backend.log(std::format("[Lint] {}", problem)); + } + report.run.failure = outcome_failed("lint_failed", problems.front()); + return report; + } + report.save = decide_story_save(checkpoint, steps_hash(checkpoint)); + if (gate == SaveGate::NEVER){ + report.save.mode = StorySaveMode::NONE; + report.save.reason = std::format("[Save] {}: verify run: save mode none", checkpoint.id); + } + 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){ + m_backend.log(std::format("[Save] {}: run failed: not saved", checkpoint.id)); + return report; + } + report.postconditions = check_postconditions(checkpoint); + report.verdict = report.postconditions->count(PostconditionVerdict::FAILED) == 0 + ? CheckpointVerdict::PASSED + : CheckpointVerdict::FAILED; + save_if_allowed(checkpoint, point, report); + return report; +} + +template +Outcome StoryEngine::reload(RunState& state){ + state = RunState{}; + if (!m_game.reload){ + return outcome_failed("reload_failed", "the game has no reload"); + } + const Outcome reloaded = m_game.reload(m_backend); + if (!reloaded.succeeded()){ + return outcome_failed("reload_failed", to_string(reloaded)); + } + if (reloaded.pose){ + state.pose = *reloaded.pose; + } + return outcome_ok(); +} + +template +StoryEngineReport StoryEngine::run_with_retries( + const StoryCheckpoint& checkpoint, SavePoint point, size_t attempts, RunState& state, CheckpointRun& run +){ + StoryEngineReport report; + const CheckpointAttempts loop{ + .max_attempts = attempts, + .run = [&](size_t attempt){ + run.attempts = attempt; + report = run_checkpoint(checkpoint, point, state); + 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){ + m_backend.log(checkpoint_reset_line(checkpoint.id, next_attempt, attempts)); + const Outcome reloaded = reload(state); + if (!reloaded.succeeded()){ + report.run.completed = false; + report.run.failed_name.clear(); + report.run.failure = reloaded; + return false; + } + return true; + }, + .log = [this](const std::string& line){ + m_backend.log(line); + }, + }; + run.passed = run_checkpoint_attempts(checkpoint.id, loop).passed; + return report; +} + +template +SegmentReport StoryEngine::run_segment( + std::string_view id, std::span checkpoints, size_t attempts_per_checkpoint, + RunState& state +){ + SegmentReport report; + m_backend.log(std::format("[Segment] {}: start, {} checkpoints", id, checkpoints.size())); + // Whether a reload returns to the save the next checkpoint starts from. + bool start_saved = true; + for (size_t c = 0; c < checkpoints.size(); c++){ + const StoryCheckpoint& checkpoint = checkpoints[c]; + const SavePoint point = c + 1 == checkpoints.size() ? SavePoint::RUN_END : SavePoint::CHECKPOINT_END; + const size_t attempts = start_saved ? attempts_per_checkpoint : 1; + if (!start_saved && attempts_per_checkpoint > 1){ + m_backend.log(std::format("[Segment] {}: {}: no save at its start, so no reload if it fails", id, checkpoint.id)); + } + report.checkpoints_run++; + report.runs.push_back(CheckpointRun{.id = checkpoint.id}); + const StoryEngineReport result = run_with_retries(checkpoint, point, attempts, state, report.runs.back()); + report.reloads += report.runs.back().attempts - 1; + if (result.verdict != CheckpointVerdict::PASSED){ + 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_with_class(report.failure))); + return report; + } + start_saved = result.saved; + } + report.completed = true; + m_backend.log(std::format("[Segment] {}: done, {} checkpoints", id, report.checkpoints_run)); + return report; +} + +template +VerifyReport StoryEngine::verify_checkpoint(const StoryCheckpoint& checkpoint, const VerifyPolicy& policy, RunState& state){ + VerifyReport report; + report.checkpoint = checkpoint.id; + if (policy.runs == 0 || policy.passes_needed > policy.runs){ + report.failure = outcome_failed("bad_verify_policy", std::format("{} of {} runs", policy.passes_needed, policy.runs)); + m_backend.log(std::format("[Verify] {}: {}", checkpoint.id, to_string(report.failure))); + return report; + } + m_backend.log(std::format("[Verify] {}: start, {} runs from one save, {} must pass", checkpoint.id, policy.runs, policy.passes_needed)); + for (size_t run = 1; run <= policy.runs; run++){ + if (run > 1){ + Outcome reloaded = reload(state); + if (!reloaded.succeeded()){ + m_backend.log(std::format("[Verify] {}: no reload before run {}: {}", checkpoint.id, run, to_string(reloaded))); + report.failure = std::move(reloaded); + break; + } + } + report.runs++; + // Only the last run may save, and only when every run before it passed. + const bool may_save = run == policy.runs && report.passes + 1 == run; + const StoryEngineReport result = run_once( + checkpoint, SavePoint::RUN_END, may_save ? SaveGate::BY_PHASE : SaveGate::NEVER, state + ); + const bool passed = result.verdict == CheckpointVerdict::PASSED; + report.passes += passed ? 1 : 0; + 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_with_class(run_failure(result))) + )); + if (repeats_on_reload(result.run.failure)){ + report.failure = result.run.failure; + break; + } + } + report.verified = report.failure.succeeded() && report.passes >= policy.passes_needed; + m_backend.log(std::format( + "[Verify] {}: {}/{} passed, {} needed: {}", checkpoint.id, report.passes, policy.runs, policy.passes_needed, + report.verified ? "verified" : "not verified" + )); + return report; +} + +template +CheckpointReport StoryEngine::run_steps(const StoryCheckpoint& checkpoint, RunState& state){ + RunnerExecutor executor(m_runner, m_game, m_registry.pause_points()); + Checkpoint events = build_story_checkpoint(checkpoint, executor, &m_prepared); + if (m_game.interrupts){ + events.interrupts = m_game.interrupts(m_backend); + } + EventLogger log = [this](const std::string& line){ + m_backend.log(line); + }; + return Pokemon::run_checkpoint(state, events, log); +} + +template +void StoryEngine::save_if_allowed(const StoryCheckpoint& checkpoint, SavePoint point, StoryEngineReport& report){ + const bool passed = report.verdict == CheckpointVerdict::PASSED; + if (!story_save_allowed(report.save.mode, report.verdict, point)){ + m_backend.log(std::format( + "[Save] {}: not saved: save mode {}, {}", checkpoint.id, + story_save_mode_name(report.save.mode), passed ? "passed" : "postconditions failed" + )); + return; + } + if (!m_game.save){ + m_backend.log(std::format("[Save] {}: not saved: the game has no save", checkpoint.id)); + return; + } + const Outcome saved = m_game.save(m_backend, checkpoint); + report.saved = saved.succeeded(); + m_backend.log(std::format("[Save] {}: {}", checkpoint.id, report.saved ? "saved" : std::format("save failed: {}", to_string(saved)))); +} + +template +PostconditionReport StoryEngine::check_postconditions(const StoryCheckpoint& checkpoint){ + const std::vector needs = postcondition_needs(checkpoint); + Observation observation = m_backend.observe(); + for (const StoryGameReader& reader : m_game.readers){ + if (runs_after_checkpoint(reader, needs, m_backend.kind())){ + reader.read(m_backend, observation); + } + } + PostconditionReport report = Pokemon::check_postconditions(checkpoint, observed_state(observation)); + for (const std::string& line : postcondition_log_lines(report)){ + m_backend.log(line); + } + return report; +} + + +template class StoryEngine; +template class StoryEngine; + + + + +} // namespace Pokemon +} // namespace PokemonAutomation diff --git a/SerialPrograms/Source/Pokemon/AutoStory/Engine/Pokemon_StoryEngine.h b/SerialPrograms/Source/Pokemon/AutoStory/Engine/Pokemon_StoryEngine.h new file mode 100644 index 0000000000..185ab5dc52 --- /dev/null +++ b/SerialPrograms/Source/Pokemon/AutoStory/Engine/Pokemon_StoryEngine.h @@ -0,0 +1,134 @@ +/* Story Engine + * + * From: https://github.com/PokemonAutomation/ + * + * The one story executor, for every game and both backends. A run of a + * checkpoint lints its steps against the game's actions (a problem fails + * the run before any input), runs them through the event layer + * (Pokemon_StoryEvents.h: skip_if, retries, recoveries, interrupts) with + * the step runner, checks the postconditions with the game's readers, and + * saves only as the checkpoint's phase allows (Pokemon_StoryEnginePolicy.h). + * + * See MIGRATION.md in this folder for moving a game onto it. + * + */ + +#ifndef PokemonAutomation_Pokemon_StoryEngine_H +#define PokemonAutomation_Pokemon_StoryEngine_H + +#include +#include +#include +#include +#include +#include "Pokemon/AutoStory/Pokemon_StoryPostconditionCheck.h" +#include "Pokemon/AutoStory/Pokemon_StorySegments.h" +#include "Pokemon/AutoStory/Pokemon_StoryStepExecutor.h" +#include "Pokemon/AutoStory/Types/Pokemon_GridPose.h" +#include "Pokemon/AutoStory/Types/Pokemon_StorySaveMode.h" +#include "Pokemon/AutoStory/Types/Pokemon_StorySegmentTypes.h" +#include "Pokemon_StoryActionRegistry.h" +#include "Pokemon_StoryEnginePolicy.h" +#include "Pokemon_StoryStepRunner.h" + +namespace PokemonAutomation{ +namespace Pokemon{ + + +// What a look at a tile game shows of a checkpoint's postconditions: the +// map, the tile (when the pose is one tile) and the facing from the pose; +// items from "bag." readings; flags from "flag." readings +// (non-zero is set). +ObservedState observed_state(const Observation& observation); + +// The same for a zone game: the map is the zone; no tile or facing. +ObservedState observed_state(const Observation& observation); + +// Runs `game`'s checkpoints on `backend`. Both must outlive it. +template +class StoryEngine{ +public: + StoryEngine(const StoryGame& game, StoryBackend& backend); + StoryEngine(const StoryEngine&) = delete; + StoryEngine& operator=(const StoryEngine&) = delete; + + const StoryActionRegistry& registry() const{ + return m_registry; + } + + // story_steps_hash() of `checkpoint`. + std::string steps_hash(const StoryCheckpoint& checkpoint) const; + + // Runs `checkpoint` from `state`, then checks its postconditions and + // saves if its phase allows a save at `point`. A SAVE step among its + // steps saves only in PER_CHECKPOINT mode. + StoryEngineReport run_checkpoint(const StoryCheckpoint& checkpoint, SavePoint point, RunState& state); + + // `checkpoints` in order from the save the game is on, each run with + // run_checkpoint() (the last at RUN_END), until one does not pass. + // One that fails is run again after a reload (StoryGame::reload), up to + // `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 + // 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 + ); + + // Verify mode: `checkpoint` run `policy.runs` times, each from the save + // the first started from (a reload before each run after the first). + // No run saves, but the last when every run before it passed: it saves + // at RUN_END as the checkpoint's phase allows. `policy.save_mode` is + // not read; the phase decides. Logs "[Verify] : ..." lines. + VerifyReport verify_checkpoint(const StoryCheckpoint& checkpoint, const VerifyPolicy& policy, RunState& state); + + // `checkpoint`'s postconditions against a fresh observation, read by + // the game's readers that opted in (StoryReaderUse::AFTER_CHECKPOINT) + // and supply what they need, but no console_only one off a console; + // logged as "[Postcondition]" lines. + PostconditionReport check_postconditions(const StoryCheckpoint& checkpoint); + +private: + // Whether a run may save at all. + enum class SaveGate{ + BY_PHASE, + NEVER, + }; + + StoryEngineReport run_once(const StoryCheckpoint& checkpoint, SavePoint point, SaveGate gate, RunState& state); + CheckpointReport run_steps(const StoryCheckpoint& checkpoint, RunState& state); + void save_if_allowed(const StoryCheckpoint& checkpoint, SavePoint point, StoryEngineReport& report); + // Empties `state` and reloads the last save; the reload's pose, if it + // says one, goes into `state`. + Outcome reload(RunState& state); + // One checkpoint of a segment until it passes or runs out of attempts. + StoryEngineReport run_with_retries( + const StoryCheckpoint& checkpoint, SavePoint point, size_t attempts, RunState& state, CheckpointRun& run + ); + + // 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; + StoryStepRunner m_runner; + PreparedSteps m_prepared; +}; + +// Instantiated once, in Pokemon_StoryEngine.cpp. +extern template class StoryEngine; +// And for ZonePose (Pokemon_ZonePose.h). +extern template class StoryEngine; + + + +} // namespace Pokemon +} // namespace PokemonAutomation +#endif diff --git a/SerialPrograms/Source/Pokemon/AutoStory/Engine/Pokemon_StoryEnginePolicy_Tests.cpp b/SerialPrograms/Source/Pokemon/AutoStory/Engine/Pokemon_StoryEnginePolicy_Tests.cpp new file mode 100644 index 0000000000..c1f7b74094 --- /dev/null +++ b/SerialPrograms/Source/Pokemon/AutoStory/Engine/Pokemon_StoryEnginePolicy_Tests.cpp @@ -0,0 +1,438 @@ +/* Story Engine Policy Tests + * + * From: https://github.com/PokemonAutomation/ + * + * The engine's whole run of a checkpoint on a scripted backend: the save + * mode from the checkpoint's phase and steps hash, the postconditions + * (passed, failed, not checked) and whether it saved. Then the steps hash + * on its own, the metadata in the JSON, and ScreenMachine states that + * match on an observation. + * + */ + +#include +#include +#include +#include +#include +#include +#include "Common/Cpp/Exceptions.h" +#include "Common/Cpp/Json/JsonValue.h" +#include "Common/Cpp/TestRunners/UnitTest.h" +#include "CommonTools/ScreenMachine/ScreenMachine.h" +#include "Pokemon/AutoStory/Data/Pokemon_StoryStepJson.h" +#include "Pokemon_StoryEngine.h" +#include "Pokemon_StoryFakeBackend.h" +#include "Pokemon_StoryEnginePolicy_Tests.h" + +namespace PokemonAutomation{ +namespace Pokemon{ + + +namespace{ + + +// FRLG 00.31's end in the shared format, its steps given: beside B3F's +// Rare Candy, facing north, with two Rare Candies. +std::string checkpoint_0031(std::string_view phase, std::string_view steps){ + return std::format(R"({{"id": "00.31", "title": "Rocket Hideout", "events": {}, + "metadata": {{"phase": "{}", "source": "test", "postconditions": {{ + "position": {{"map": "RocketHideout_B3F", "tiles": [[12, 13]], "facing": "north"}}, + "items": [{{"item": "RARE_CANDY", "quantity": 2}}] + }}}}}})", steps, phase); +} + +inline constexpr std::string_view TALK_STEPS = R"([{"id": "b3f_rare_candy", "kind": "talk", "why": "the second candy"}])"; +inline constexpr std::string_view SAVE_STEPS = R"([{"id": "b3f_rare_candy", "kind": "talk"}, {"id": "save_here", "kind": "save"}])"; + +// The verification a checkpoint records. +enum class HashRecord{ + MATCHING, // of these steps + STALE, // of other steps + MISSING, // none +}; + +// A look at B3F (12, 13) or wherever `map` is. +Observation end_look(std::string map){ + Observation observation; + observation.events = ScreenEvents{ScreenEvent::PLAYER_CAN_MOVE}; + observation.pose = GridPose{.map = std::move(map), .tiles = {{12, 13}}, .facing = Direction::NORTH}; + return observation; +} + +// A game whose save is recorded as an input, and whose "bag" reader +// reads `candies` Rare Candies (no reader when unset). +StoryGame engine_game(std::optional candies){ + StoryGame game; + game.id = "test"; + game.save = [](StoryBackend& backend, const StoryCheckpoint&){ + backend.wait(Milliseconds(1)); + backend.log("[Test] save"); + return outcome_ok(); + }; + if (candies){ + game.readers.push_back({ + .name = "bag", .supplies = {"bag.*"}, .use = StoryReaderUse::AFTER_CHECKPOINT, .console_only = false, + .read = [count = *candies](StoryBackend&, Observation& observation){ + observation.readings["bag.RARE_CANDY"] = count; + }, + }); + } + return game; +} + + + +struct EngineCase{ + // One engine run of 00.31 in `phase`, the player ending on `end_map`. + struct Input{ + std::string_view phase; + HashRecord hash = HashRecord::MATCHING; + std::string_view steps = TALK_STEPS; + // Where the talk leaves the player; empty: the talk opens no text. + std::string_view end_map = "RocketHideout_B3F"; + std::optional candies = 2; + }; + + // The save mode chosen, the verdict, whether the game saved (each save + // logs "[Test] save") and a line the run logged. + struct Expectation{ + StorySaveMode mode = StorySaveMode::NONE; + CheckpointVerdict verdict = CheckpointVerdict::PASSED; + size_t saves = 0; + std::string_view line = {}; + }; + + std::string_view name; + Input input; + Expectation expectation; +}; + +const EngineCase ENGINE_CASES[] = { + {.name = "testing never saves", .input = {.phase = "testing"}, + .expectation = {.mode = StorySaveMode::NONE, .saves = 0, .line = "[Save] 00.31: phase testing: save mode none"}}, + {.name = "verification saves at the end", .input = {.phase = "verification"}, + .expectation = {.mode = StorySaveMode::AFTER_VERIFICATION, .saves = 1, .line = "[Save] 00.31: saved"}}, + {.name = "reproduction saves", .input = {.phase = "reproduction"}, + .expectation = {.mode = StorySaveMode::PER_CHECKPOINT, .saves = 1, .line = "[Save] 00.31: phase reproduction: save mode per_checkpoint"}}, + {.name = "stale steps_hash is testing", .input = {.phase = "verification", .hash = HashRecord::STALE}, + .expectation = {.mode = StorySaveMode::NONE, .saves = 0, .line = "[Save] 00.31: phase verification but steps_hash mismatch (recorded sha256:old, now "}}, + {.name = "no steps_hash is testing", .input = {.phase = "reproduction", .hash = HashRecord::MISSING}, + .expectation = {.mode = StorySaveMode::NONE, .saves = 0, .line = "[Save] 00.31: phase reproduction but steps_hash mismatch (recorded none, now "}}, + {.name = "B4F false pass fails postconditions", .input = {.phase = "verification", .end_map = "RocketHideout_B4F"}, + .expectation = {.mode = StorySaveMode::AFTER_VERIFICATION, .verdict = CheckpointVerdict::FAILED, .saves = 0, + .line = "[Postcondition] 00.31 map: failed: expected RocketHideout_B3F, read RocketHideout_B4F"}}, + {.name = "unread bag is not checked", .input = {.phase = "verification", .candies = std::nullopt}, + .expectation = {.mode = StorySaveMode::AFTER_VERIFICATION, .saves = 1, + .line = "[Postcondition] 00.31: 3 passed, 0 failed, 1 not checked: incomplete"}}, + {.name = "wrong candy count fails", .input = {.phase = "reproduction", .candies = 1}, + .expectation = {.mode = StorySaveMode::PER_CHECKPOINT, .verdict = CheckpointVerdict::FAILED, .saves = 0, + .line = "[Postcondition] 00.31 item RARE_CANDY: failed: expected 2, read 1"}}, + {.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}, + .expectation = {.mode = StorySaveMode::PER_CHECKPOINT, .saves = 2, .line = "[Step] save_here SAVE/default: ok"}}, +}; + +// A text box, then the overworld on `end_map`; only the overworld when +// `end_map` is empty. +std::vector> engine_looks(std::string_view end_map){ + if (end_map.empty()){ + return {end_look("RocketHideout_B3F")}; + } + Observation text; + text.events = ScreenEvents{ScreenEvent::DIALOG_BOX}; + return {std::move(text), end_look(std::string(end_map))}; +} + +std::string check_engine_lines(const EngineCase& test, const FakeStoryBackend& backend){ + size_t saves = 0; + bool found = false; + for (const std::string& line : backend.lines()){ + saves += line == "[Test] save" ? 1 : 0; + found |= line.starts_with(test.expectation.line); + } + if (saves != test.expectation.saves){ + return std::format("expected {} saves, got {}", test.expectation.saves, saves); + } + return found ? "" : std::format("expected a line starting \"{}\"", test.expectation.line); +} + +std::string check_engine(const EngineCase& test, CancellableScope& scope){ + const StoryGame game = engine_game(test.input.candies); + FakeStoryBackend backend({.looks = engine_looks(test.input.end_map)}, scope); + StoryEngine engine(game, backend); + StoryCheckpoint checkpoint = read_story_checkpoint( + parse_json(checkpoint_0031(test.input.phase, test.input.steps)), test.name, engine.registry().specs() + ); + if (test.input.hash != HashRecord::MISSING){ + checkpoint.metadata.verified = StoryVerification{ + .steps_hash = test.input.hash == HashRecord::MATCHING ? engine.steps_hash(checkpoint) : "sha256:old", + .build = "abc", .date = "2026-11-10", .runs = "3/3", + }; + } + RunState state; + const StoryEngineReport report = engine.run_checkpoint(checkpoint, SavePoint::RUN_END, state); + if (report.save.mode != test.expectation.mode){ + return std::format("expected save mode {}, got {}", story_save_mode_name(test.expectation.mode), story_save_mode_name(report.save.mode)); + } + if (report.verdict != test.expectation.verdict){ + return std::format("expected the checkpoint {}", test.expectation.verdict == CheckpointVerdict::PASSED ? "passed" : "failed"); + } + return check_engine_lines(test, backend); +} + +class StoryEngineSaveTest : public UnitTest{ +public: + explicit StoryEngineSaveTest(EngineCase test) + : UnitTest(std::format("Pokemon::StoryEngine save - {}", test.name)) + , m_case(std::move(test)) + {} + virtual UnitTestResult run(Logger&, CancellableScope& scope) const override{ + const std::string error = check_engine(m_case, scope); + return error.empty() ? UnitTestResult(true) : UnitTestResult(error); + } +private: + EngineCase m_case; +}; + + + +struct HashCase{ + // Two checkpoints' events, hashed with the built-in actions. + struct Input{ + std::string_view a; + std::string_view b; + }; + + // Whether they hash the same, and `a`'s hash when pinned: a change to it + // means every recorded verification goes stale. + struct Expectation{ + bool same = true; + std::optional hash_a = std::nullopt; + }; + + std::string_view name; + Input input; + Expectation expectation; +}; + +inline constexpr std::string_view ROUTE_B3F = R"([{"id": "go", "kind": "route", "args": {"target": {"map": "RocketHideout_B3F", "tiles": [[12, 13]]}}}])"; + +const HashCase HASH_CASES[] = { + {.name = "pinned", .input = {.a = ROUTE_B3F, .b = ROUTE_B3F}, + .expectation = {.same = true, .hash_a = "sha256:13bc877c960a15cd0ed2f37248fa8336308b048a865623dde7654d41ac7147b8"}}, + {.name = "whitespace is not hashed", .input = {.a = R"([{"id": "t", "kind": "talk"}])", .b = R"([ { "id":"t", "kind":"talk" } ])"}, + .expectation = {.same = true}}, + {.name = "why differs", .input = {.a = R"([{"id": "t", "kind": "talk", "why": "a"}])", .b = R"([{"id": "t", "kind": "talk", "why": "b"}])"}, + .expectation = {.same = false}}, + {.name = "written fallback differs", .input = {.a = R"([{"id": "f", "kind": "battle"}])", .b = R"([{"id": "f", "kind": "battle", "args": {"may_lose": false}}])"}, + .expectation = {.same = false}}, + {.name = "another target differs", .input = { .a = ROUTE_B3F, + .b = R"([{"id": "go", "kind": "route", "args": {"target": {"map": "RocketHideout_B3F", "tiles": [[12, 14]]}}}])"}, + .expectation = {.same = false}}, + {.name = "another step name differs", .input = {.a = R"([{"id": "t", "kind": "talk"}])", .b = R"([{"id": "u", "kind": "talk"}])"}, + .expectation = {.same = false}}, +}; + +std::string hash_of(std::string_view events, std::string_view source){ + const std::string json = std::format(R"({{"id": "x", "title": "x", "events": {}}})", events); + return story_steps_hash(read_story_checkpoint(parse_json(json), source)); +} + +std::string check_hash(const HashCase& test){ + const std::string a = hash_of(test.input.a, test.name); + const std::string b = hash_of(test.input.b, test.name); + if ((a == b) != test.expectation.same){ + return std::format("{}{}: {}, {}", "expected the hashes ", (test.expectation.same ? "equal" : "different"), a, b); + } + if (test.expectation.hash_a && a != *test.expectation.hash_a){ + return std::format("expected the pinned hash {}, got {}", *test.expectation.hash_a, a); + } + return ""; +} + +class StoryStepsHashTest : public UnitTest{ +public: + explicit StoryStepsHashTest(HashCase test) + : UnitTest(std::format("Pokemon::StoryEngine steps_hash - {}", test.name)) + , m_case(std::move(test)) + {} + virtual UnitTestResult run(Logger&, CancellableScope&) const override{ + const std::string error = check_hash(m_case); + return error.empty() ? UnitTestResult(true) : UnitTestResult(error); + } +private: + HashCase m_case; +}; + + + +struct MetadataCase{ + // A checkpoint's "metadata", read. + struct Input{ + std::string_view metadata; + }; + + // The error the read throws (contained), or what it read. + struct Expectation{ + std::string_view error = {}; + StoryPhase phase = StoryPhase::TESTING; + std::string_view steps_hash = {}; + size_t items = 0; + }; + + std::string_view name; + Input input; + Expectation expectation; +}; + +const MetadataCase METADATA_CASES[] = { + {.name = "none is testing", .input = {.metadata = ""}, + .expectation = {.phase = StoryPhase::TESTING}}, + {.name = "verified", .input = {.metadata = R"(, "metadata": {"phase": "verification", "verified": {"steps_hash": "sha256:ab", "build": "1", "date": "d", "runs": "3/3"}})"}, + .expectation = {.phase = StoryPhase::VERIFICATION, .steps_hash = "sha256:ab"}}, + {.name = "postconditions", .input = {.metadata = R"(, "metadata": {"phase": "reproduction", "postconditions": {"items": [{"item": "LIFT_KEY", "quantity": 1}]}})"}, + .expectation = {.phase = StoryPhase::REPRODUCTION, .items = 1}}, + {.name = "unknown phase", .input = {.metadata = R"(, "metadata": {"phase": "tested"})"}, + .expectation = {.error = "unknown phase tested"}}, + {.name = "unknown field", .input = {.metadata = R"(, "metadata": {"phase": "testing", "runs": 3})"}, + .expectation = {.error = "unsupported field runs"}}, +}; + +std::string check_metadata(const MetadataCase& test){ + const std::string json = std::format(R"({{"id": "x", "title": "x", "events": []{}}})", test.input.metadata); + StoryCheckpoint checkpoint; + try{ + checkpoint = read_story_checkpoint(parse_json(json), "metadata"); + }catch (const ParseException& error){ + const bool expected = !test.expectation.error.empty() && error.message().find(test.expectation.error) != std::string::npos; + return expected ? "" : std::format("unexpected error: {}", error.message()); + } + if (!test.expectation.error.empty()){ + return std::format("expected the error \"{}\"", test.expectation.error); + } + const std::string hash = checkpoint.metadata.verified ? checkpoint.metadata.verified->steps_hash : ""; + if (checkpoint.metadata.phase != test.expectation.phase || hash != test.expectation.steps_hash){ + return std::format("read phase {}, steps_hash \"{}\"", story_phase_name(checkpoint.metadata.phase), hash); + } + if (checkpoint.postconditions.items.size() != test.expectation.items){ + return std::format("read {} items", checkpoint.postconditions.items.size()); + } + return ""; +} + +class StoryMetadataTest : public UnitTest{ +public: + explicit StoryMetadataTest(MetadataCase test) + : UnitTest(std::format("Pokemon::StoryEngine metadata - {}", test.name)) + , m_case(std::move(test)) + {} + virtual UnitTestResult run(Logger&, CancellableScope&) const override{ + const std::string error = check_metadata(m_case); + return error.empty() ? UnitTestResult(true) : UnitTestResult(error); + } +private: + MetadataCase m_case; +}; + + + +struct ScreenCase{ + // What a look showed, classified by ScreenMachine states that match on + // observations. + struct Input{ + std::vector events; + }; + + // The state matched; none when no state did. + struct Expectation{ + std::optional state = std::nullopt; + }; + + std::string_view name; + Input input; + Expectation expectation; +}; + +const ScreenCase SCREEN_CASES[] = { + {.name = "battle first", .input = {.events = {ScreenEvent::BATTLE_STARTED, ScreenEvent::DIALOG_BOX}}, .expectation = {.state = "battle"}}, + {.name = "text", .input = {.events = {ScreenEvent::DIALOG_BOX}}, .expectation = {.state = "text"}}, + {.name = "overworld", .input = {.events = {ScreenEvent::PLAYER_CAN_MOVE}}, .expectation = {.state = "overworld"}}, + {.name = "image-only state skipped", .input = {.events = {ScreenEvent::FADE_WHITE}}, .expectation = {}}, +}; + +ScreenState observation_state(std::string name, ScreenEvent event){ + ScreenState state; + state.name = std::move(name); + state.matches_observation = [event](const ScreenObservation& observation){ + return observation.events.has(event); + }; + state.max_visits = 10; + return state; +} + +std::string check_screen(const ScreenCase& test){ + std::vector states{ + observation_state("battle", ScreenEvent::BATTLE_STARTED), + observation_state("text", ScreenEvent::DIALOG_BOX), + observation_state("overworld", ScreenEvent::PLAYER_CAN_MOVE), + }; + ScreenState image_only; + image_only.name = "image_only"; + image_only.matches = [](const ImageViewRGB32&){ + return true; + }; + image_only.max_visits = 10; + states.push_back(std::move(image_only)); + ScreenObservation observation; + for (ScreenEvent event : test.input.events){ + observation.events.set(event, true); + } + const ScreenState* state = match_screen_state(states, observation); + const std::string got = state ? state->name : "none"; + return got == test.expectation.state.value_or("none") ? "" : std::format("matched {}", got); +} + +class ScreenObservationTest : public UnitTest{ +public: + explicit ScreenObservationTest(ScreenCase test) + : UnitTest(std::format("Pokemon::StoryEngine screen observation - {}", test.name)) + , m_case(std::move(test)) + {} + virtual UnitTestResult run(Logger&, CancellableScope&) const override{ + const std::string error = check_screen(m_case); + return error.empty() ? UnitTestResult(true) : UnitTestResult(error); + } +private: + ScreenCase m_case; +}; + + +} // namespace + + +void add_tests_StoryEnginePolicy(UnitTestDatabase& database){ + for (const EngineCase& test : ENGINE_CASES){ + database.add(test); + } + for (const HashCase& test : HASH_CASES){ + database.add(test); + } + for (const MetadataCase& test : METADATA_CASES){ + database.add(test); + } + for (const ScreenCase& test : SCREEN_CASES){ + database.add(test); + } +} + + + +} // namespace Pokemon +} // namespace PokemonAutomation diff --git a/SerialPrograms/Source/Pokemon/AutoStory/Engine/Pokemon_StoryEnginePolicy_Tests.h b/SerialPrograms/Source/Pokemon/AutoStory/Engine/Pokemon_StoryEnginePolicy_Tests.h new file mode 100644 index 0000000000..267cbae30b --- /dev/null +++ b/SerialPrograms/Source/Pokemon/AutoStory/Engine/Pokemon_StoryEnginePolicy_Tests.h @@ -0,0 +1,23 @@ +/* Story Engine Policy Tests + * + * From: https://github.com/PokemonAutomation/ + * + */ + +#ifndef PokemonAutomation_Pokemon_StoryEnginePolicy_Tests_H +#define PokemonAutomation_Pokemon_StoryEnginePolicy_Tests_H + +#include "Common/Cpp/TestRunners/UnitTestDatabase.h" + +namespace PokemonAutomation{ +namespace Pokemon{ + + +// Registers unit tests for the engine's save decision, postconditions, steps hash, metadata and observation screens. +void add_tests_StoryEnginePolicy(UnitTestDatabase& database); + + + +} // namespace Pokemon +} // namespace PokemonAutomation +#endif diff --git a/SerialPrograms/Source/Pokemon/AutoStory/Engine/Pokemon_StoryEngineRuns_Tests.cpp b/SerialPrograms/Source/Pokemon/AutoStory/Engine/Pokemon_StoryEngineRuns_Tests.cpp new file mode 100644 index 0000000000..9f4a51a3d8 --- /dev/null +++ b/SerialPrograms/Source/Pokemon/AutoStory/Engine/Pokemon_StoryEngineRuns_Tests.cpp @@ -0,0 +1,700 @@ +/* Story Engine Runs Tests + * + * From: https://github.com/PokemonAutomation/ + * + * 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, 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. It also checks the engine's breakpoints. + * + */ + +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include "Common/Cpp/Json/JsonValue.h" +#include "Common/Cpp/TestRunners/UnitTest.h" +#include "CommonFramework/ImageTypes/ImageRGB32.h" +#include "CommonTools/ScreenMachine/ScreenMachine.h" +#include "Pokemon/AutoStory/Data/Pokemon_StoryStepJson.h" +#include "Pokemon_StoryEngine.h" +#include "Pokemon_StoryFakeBackend.h" +#include "Pokemon_StoryEngineRuns_Tests.h" + +namespace PokemonAutomation{ +namespace Pokemon{ + + +namespace{ + +using namespace std::chrono_literals; + + +std::string joined(const std::vector& items){ + std::string text; + for (const std::string& item : items){ + text += (text.empty() ? "" : ", ") + item; + } + return text; +} + +template +bool has_line(const FakeStoryBackend& backend, std::string_view line){ + for (const std::string& each : backend.lines()){ + if (each == line){ + return true; + } + } + return false; +} + +template +std::string expect_inputs(const FakeStoryBackend& backend, std::string_view expected){ + const std::string got = joined(backend.inputs()); + return got == expected ? "" : std::format("expected inputs \"{}\", got \"{}\"", expected, got); +} + +template +Observation look(std::initializer_list events){ + Observation observation; + observation.events = ScreenEvents(events); + return observation; +} + +StoryStep game_step(std::string name, std::string action, std::string why = ""){ + StoryStep step; + step.kind = StoryStepKind::GAME; + step.name = std::move(name); + step.why = std::move(why); + step.action = std::move(action); + return step; +} + +StoryCheckpoint checkpoint_of(std::string id, std::vector steps){ + StoryCheckpoint checkpoint; + checkpoint.id = std::move(id); + checkpoint.steps = std::move(steps); + return checkpoint; +} + +// A GAME action of no args. +template +StoryAction game_action(std::string name, StoryActionHandler handler){ + return {.spec = {.kind = StoryStepKind::GAME, .name = std::move(name), .args = {}}, .handler = std::move(handler)}; +} + +// A game whose "flaky" action fails its first `failures` calls, whose +// save logs "[Test] save " and whose reload logs "[Test] reload". +template +StoryGame flaky_game(size_t failures){ + StoryGame game; + game.id = "test"; + std::shared_ptr calls = std::make_shared(0); + game.actions.push_back(game_action("flaky", [calls, failures](StoryBackend&, const StoryActionCall&, RunState&){ + return (*calls)++ < failures ? outcome_failed("flaky_failed") : outcome_ok(); + })); + game.actions.push_back(game_action("fine", [](StoryBackend&, const StoryActionCall&, RunState&){ + return outcome_ok(); + })); + game.save = [](StoryBackend& backend, const StoryCheckpoint& checkpoint){ + backend.log(std::format("[Test] save {}", checkpoint.id)); + return outcome_ok(); + }; + game.reload = [](StoryBackend& backend){ + backend.log("[Test] reload"); + return outcome_ok(); + }; + return game; +} + + +// Gap 1 and 9: a zone game's checkpoint read from JSON whose start names +// only its zone, run on the scripted backend of its pose type. +std::string zone_checkpoint_runs(CancellableScope& scope){ + StoryGame game = flaky_game(0); + FakeStoryBackend backend({.looks = {look({ScreenEvent::PLAYER_CAN_MOVE})}}, scope); + StoryEngine engine(game, backend); + const StoryCheckpoint checkpoint = read_story_checkpoint(parse_json(R"({ + "id": "03.01", "title": "Down to the lobby", "start": {"place": "HotelZ", "spot": "Room", "heading": 180}, + "events": [{"id": "walk", "kind": "game_action", "action": "fine", "declared_after": {"place": "HotelZLobby"}}] + })"), "zone", engine.registry().specs()); + RunState state; + const StoryEngineReport report = engine.run_checkpoint(checkpoint, SavePoint::RUN_END, state); + if (report.verdict != CheckpointVerdict::PASSED){ + return std::format("expected a pass, got {}", to_string(report.run.failure)); + } + return state.pose.map == "HotelZLobby" ? "" : std::format("expected the run's pose in HotelZLobby, got \"{}\"", state.pose.map); +} + +// Gap 9: a declared tile pose is no zone. +std::string zone_rejects_tiles(CancellableScope& scope){ + StoryGame game = flaky_game(0); + FakeStoryBackend backend({}, scope); + StoryEngine engine(game, backend); + StoryCheckpoint checkpoint = checkpoint_of("03.01", {game_step("walk", "fine")}); + checkpoint.start = TileDeclared{.map = "HotelZ", .tiles = {{1, 2}}, .facing = std::nullopt}; + const std::vector lint = engine.registry().lint(checkpoint); + if (lint.size() != 1 || !lint[0].starts_with("03.01 start: \"HotelZ\" is a map")){ + return std::format("expected one start problem, got \"{}\"", joined(lint)); + } + RunState state; + const StoryEngineReport report = engine.run_checkpoint(checkpoint, SavePoint::RUN_END, state); + if (report.run.failure.failure != "lint_failed"){ + return std::format("expected lint_failed, got {}", to_string(report.run.failure)); + } + return expect_inputs(backend, ""); +} + +// A tile game's checkpoint that declares a place, at its start or after +// a step, fails the lint. +std::string grid_rejects_places(CancellableScope&){ + const StoryGame game = flaky_game(0); + const StoryActionRegistry registry(game); + StoryCheckpoint checkpoint = checkpoint_of("00.01", {game_step("walk", "fine")}); + checkpoint.start = ZoneDeclared{.place = "PalletTown", .spot = std::nullopt, .heading = std::nullopt}; + checkpoint.steps[0].pose_after = ZoneDeclared{.place = "Route1", .spot = "Gate", .heading = 90}; + const std::string lint = joined(registry.lint(checkpoint)); + const std::string expected = + "00.01 start: \"PalletTown\" is a place, but this game's poses are tiles: declare a map, tiles and a facing, " + "00.01 step 1 walk: declared_after: \"Route1\" is a place, but this game's poses are tiles: declare a map, tiles and a facing"; + return lint == expected ? "" : std::format("expected \"{}\", got \"{}\"", expected, lint); +} + +// A zone game may not use tile args: not in a step (a route's GRID_POSE +// target), not in its own actions (a LEGS arg). Timed legs are fine. +std::string zone_rejects_tile_args(CancellableScope&){ + StoryGame game; + game.actions.push_back({ + .spec = {.kind = StoryStepKind::GAME, .name = "walk", .args = { + {.key = "legs", .type = StoryArgType::LEGS, .required = true, .fallback = std::nullopt, .why = ""}, + }}, + .handler = nullptr, + }); + game.actions.push_back({ + .spec = {.kind = StoryStepKind::GAME, .name = "timed_walk", .args = { + {.key = "legs", .type = StoryArgType::TIMED_LEGS, .required = true, .fallback = std::nullopt, .why = ""}, + }}, + .handler = nullptr, + }); + const StoryActionRegistry registry(game); + StoryStep route; + route.kind = StoryStepKind::ROUTE; + route.name = "route"; + route.args = {{"target", GridPose{.map = "HotelZ", .tiles = {}, .facing = std::nullopt}}}; + StoryStep timed; + timed.kind = StoryStepKind::GAME; + timed.name = "timed"; + timed.action = "timed_walk"; + timed.args = {{"legs", std::vector{{.turn = 90, .ms = 1200}}}}; + const std::string lint = joined(registry.lint(checkpoint_of("03.01", {route, timed}))); + const std::string expected = + "action walk takes a tile argument \"legs\", but this game has no tiles, " + "03.01 step 1 route: argument \"target\" is a tile one, but this game has no tiles"; + return lint == expected ? "" : std::format("expected \"{}\", got \"{}\"", expected, lint); +} + +// Gap 10: no tile actions in a zone game, so a legs step fails the lint; +// a tile game keeps them. +std::string tile_actions_only_with_tiles(CancellableScope&){ + StoryStep legs; + legs.kind = StoryStepKind::LEGS; + legs.name = "legs"; + legs.args = {{"legs", std::vector{{Direction::NORTH, 1}}}}; + StoryStep face; + face.kind = StoryStepKind::STEP; + face.name = "face"; + face.action = "face"; + face.args = {{"direction", Direction::EAST}}; + const StoryGame zone_game; + const StoryActionRegistry zone(zone_game); + if (joined(zone.check(legs)) != "unknown action \"\" for LEGS" || joined(zone.check(face)) != "unknown action \"face\" for STEP"){ + return std::format("expected the zone game to have no legs or face, got \"{}\", \"{}\"", joined(zone.check(legs)), joined(zone.check(face))); + } + const StoryGame grid_game; + const StoryActionRegistry grid(grid_game); + if (!grid.check(legs).empty() || !grid.check(face).empty()){ + return "expected the tile game to keep legs and face"; + } + return ""; +} + +// Gap 2: the move stick at an angle, and the heading reading; a turn lets +// go of the stick for its release. +std::string stick_and_heading(CancellableScope& scope){ + Observation facing_east; + facing_east.readings[std::string(STORY_HEADING)] = 90; + FakeStoryBackend backend({.looks = {facing_east, {}}}, scope); + backend.stick(45, 150ms, 0ms, StoryPace::WALK); + backend.stick(-90, 300ms, 0ms, StoryPace::RUN); + backend.stick(90, 150ms, 300ms, StoryPace::WALK); + if (story_heading(backend.observe()) != 90){ + return "expected the heading 90"; + } + if (story_heading(backend.observe())){ + return "expected no heading where nothing read it"; + } + return expect_inputs(backend, "stick 45deg 150ms walk, stick -90deg 300ms run, stick 90deg 150ms walk, release 300ms"); +} + +// The fake logs each press by the button's name. +std::string buttons_by_name(CancellableScope& scope){ + FakeStoryBackend backend({}, scope); + for (const NintendoSwitch::Button button : { + NintendoSwitch::BUTTON_L, NintendoSwitch::BUTTON_R, NintendoSwitch::BUTTON_PLUS, + NintendoSwitch::BUTTON_A, NintendoSwitch::BUTTON_B, NintendoSwitch::BUTTON_ZL, + }){ + backend.press(button, 80ms, 120ms); + } + return expect_inputs(backend, "press L, press R, press +, press A, press B, press ZL"); +} + +// Gap 3 and 4: a screen machine over observations, its states matching +// the choice and interact events, ends on its terminal state. +std::vector choice_states(std::vector& acted){ + const auto state = [&acted](std::string name, ScreenEvent event){ + ScreenState result; + result.name = name; + result.matches_observation = [event](const ScreenObservation& observation){ + return observation.events.has(event); + }; + result.act = [&acted, name]{ + acted.push_back(name); + }; + result.max_visits = 3; + return result; + }; + std::vector states{ + state("choice", ScreenEvent::CHOICE_BOX), + state("prompt", ScreenEvent::INTERACT_PROMPT), + state("text", ScreenEvent::DIALOG_BOX), + }; + states[0].terminal = true; + return states; +} + +// The machine over `events`, one look each, the last repeating, a second +// apart. +ScreenMachineResult run_on_events( + const std::vector& events, CancellableScope& scope, Milliseconds timeout, + std::vector& acted, std::vector& lines +){ + const std::vector states = choice_states(acted); + StepTrace trace("test", [&lines](const std::string& line){ + lines.push_back(line); + }); + size_t next = 0; + const WallClock start = current_time(); + const std::function observe = [&]{ + ScreenObservation observation; + observation.when = start + std::chrono::seconds(next); + observation.events.set(events[std::min(next, events.size() - 1)], true); + next++; + return observation; + }; + return run_screen_machine_on_observations(observe, scope, states, timeout, trace); +} + +std::string observation_machine_ends(CancellableScope& scope){ + std::vector acted; + std::vector lines; + const ScreenMachineResult result = run_on_events( + {ScreenEvent::INTERACT_PROMPT, ScreenEvent::DIALOG_BOX, ScreenEvent::CHOICE_BOX}, scope, 60s, acted, lines + ); + if (!result.succeeded() || result.terminal != "choice"){ + return std::format("expected the run to end on choice, got \"{}\"", result.failure); + } + if (joined(acted) != "prompt, text, choice"){ + return std::format("expected the states to act in order, got {}", joined(acted)); + } + if (lines.size() != 3 || !lines[0].starts_with("[test] screen 1: prompt at ")){ + return std::format("expected a trace line per screen, got {}", joined(lines)); + } + return ""; +} + +std::string observation_machine_fails(CancellableScope& scope){ + std::vector acted; + std::vector lines; + ScreenMachineResult result = run_on_events({ScreenEvent::BATTLE_STARTED}, scope, 60s, acted, lines); + if (result.failure != "The screen matches none of the known states."){ + return std::format("expected no state to match, got \"{}\"", result.failure); + } + result = run_on_events({ScreenEvent::DIALOG_BOX}, scope, 60s, acted, lines); + if (!result.failure.starts_with("Screen \"text\" came up more than 3 times")){ + return std::format("expected text to come up too often, got \"{}\"", result.failure); + } + result = run_on_events({ScreenEvent::DIALOG_BOX, ScreenEvent::INTERACT_PROMPT, ScreenEvent::DIALOG_BOX}, scope, 1s, acted, lines); + if (result.failure != "Did not finish within 1s."){ + return std::format("expected the looks' time to run out, got \"{}\"", result.failure); + } + return ""; +} + +// A look `seconds` after `start` on a uniform frame of `shade`, showing +// `event`. +Observation framed_look(WallClock start, int seconds, uint32_t shade, ScreenEvent event){ + Observation observation; + observation.when = start + std::chrono::seconds(seconds); + observation.events.set(event, true); + ImageRGB32 image(16, 16); + image.fill(shade); + observation.frame = VideoSnapshot(std::move(image), observation.when); + return observation; +} + +// A fade that waits (still up to 30 s), a box whose step presses A, and +// the overworld that ends the run, over `looks` on a fake backend. +ScreenMachineResult run_still_states(const std::vector>& looks, CancellableScope& scope){ + FakeStoryBackend backend({.looks = looks}, scope); + ScreenState fade; + fade.name = "fade"; + fade.matches_observation = [](const ScreenObservation& observation){ + return observation.events.has(ScreenEvent::FADE_BLACK); + }; + fade.max_visits = SIZE_MAX; + fade.max_still = 30s; + ScreenState text; + text.name = "text"; + text.matches_observation = [](const ScreenObservation& observation){ + return observation.events.has(ScreenEvent::DIALOG_BOX); + }; + text.act = [&backend]{ + backend.press(NintendoSwitch::BUTTON_A, 80ms, 120ms); + }; + text.max_visits = SIZE_MAX; + ScreenState done; + done.name = "done"; + done.matches_observation = [](const ScreenObservation& observation){ + return observation.events.has(ScreenEvent::PLAYER_CAN_MOVE); + }; + done.max_visits = SIZE_MAX; + done.terminal = true; + const std::vector states{fade, text, done}; + StepTrace trace("test", [](const std::string&){}); + const std::function observe = [&backend]() -> ScreenObservation{ + return backend.observe(); + }; + return run_screen_machine_on_observations(observe, scope, states, 600s, trace); +} + +// A waiting state may stay still up to its own limit; a state that +// presses and changes nothing is a stall after 8 looks. +std::string still_states(CancellableScope& scope){ + const WallClock start = current_time(); + std::vector> waits; + for (int second = 0; second < 12; second++){ + waits.push_back(framed_look(start, second, 0xff000000, ScreenEvent::FADE_BLACK)); + } + waits.push_back(framed_look(start, 12, 0xff808080, ScreenEvent::PLAYER_CAN_MOVE)); + ScreenMachineResult result = run_still_states(waits, scope); + if (result.terminal != "done"){ + return std::format("expected a 12 s still fade to end on done, got \"{}\"", result.failure); + } + std::vector> too_long; + for (int second = 0; second < 40; second++){ + too_long.push_back(framed_look(start, second, 0xff000000, ScreenEvent::FADE_BLACK)); + } + result = run_still_states(too_long, scope); + if (result.failure != "The screen stayed still on \"fade\" for more than 30s."){ + return std::format("expected the fade to stay still too long, got \"{}\"", result.failure); + } + std::vector> presses; + for (int second = 0; second < 12; second++){ + presses.push_back(framed_look(start, second, 0xffffffff, ScreenEvent::DIALOG_BOX)); + } + result = run_still_states(presses, scope); + if (result.failure != "The screen stopped changing: 8 steps on \"text\" did nothing."){ + return std::format("expected the box to stall, got \"{}\"", result.failure); + } + return ""; +} + +// A reader that logs "[Test] read " when it runs and fills nothing. +StoryGameReader logging_reader(std::string name, std::vector supplies, StoryReaderUse use){ + StoryGameReader reader; + reader.name = name; + reader.supplies = std::move(supplies); + reader.use = use; + reader.read = [name](StoryBackend& backend, Observation&){ + backend.log(std::format("[Test] read {}", name)); + }; + return reader; +} + +// The readers `checkpoint`'s postcondition check runs on a backend of +// `kind`, as "pose, bag". +std::string readers_run(const StoryCheckpoint& checkpoint, StoryBackendKind kind, CancellableScope& scope){ + StoryGame game; + game.readers.push_back(logging_reader("pose", {"pose"}, StoryReaderUse::AFTER_CHECKPOINT)); + game.readers.push_back(logging_reader("bag", {"bag.*"}, StoryReaderUse::AFTER_CHECKPOINT)); + game.readers.push_back(logging_reader("heading", {"heading"}, StoryReaderUse::ON_REQUEST)); + StoryGameReader flags = logging_reader("flags", {"flag.*"}, StoryReaderUse::AFTER_CHECKPOINT); + flags.console_only = true; + game.readers.push_back(std::move(flags)); + FakeStoryBackend backend({.kind = kind}, scope); + StoryEngine engine(game, backend); + engine.check_postconditions(checkpoint); + std::vector read; + for (const std::string& line : backend.lines()){ + if (line.starts_with("[Test] read ")){ + read.push_back(line.substr(12)); + } + } + return joined(read); +} + +// The postcondition check runs only the readers that opted in and supply +// what it needs, and no console_only one off a console; never the +// heading, which opted out. +std::string readers_opt_in(CancellableScope& scope){ + StoryCheckpoint items = checkpoint_of("01", {}); + items.postconditions.items = {{.item = "POTION", .quantity = 1}}; + std::string read = readers_run(items, StoryBackendKind::SCRIPT, scope); + if (read != "bag"){ + return std::format("expected only the bag read for an item, got \"{}\"", read); + } + StoryCheckpoint place = checkpoint_of("02", {}); + place.postconditions.position = GridPose{.map = "Town", .tiles = {{1, 2}}, .facing = std::nullopt}; + place.postconditions.flags = {"DOOR"}; + read = readers_run(place, StoryBackendKind::SCRIPT, scope); + if (read != "pose"){ + return std::format("expected only the pose read off a console, got \"{}\"", read); + } + read = readers_run(place, StoryBackendKind::CONSOLE, scope); + if (read != "pose, flags"){ + return std::format("expected the pose and the console's flags read, got \"{}\"", read); + } + read = readers_run(checkpoint_of("03", {}), StoryBackendKind::CONSOLE, scope); + return read.empty() ? "" : std::format("expected no reader without postconditions, got \"{}\"", read); +} + +// Gap 5: an action sees its step. +std::string handler_sees_step(CancellableScope& scope){ + StoryGame game; + std::shared_ptr seen = std::make_shared(); + game.actions.push_back(game_action("scene", [seen](StoryBackend&, const StoryActionCall& call, RunState&){ + *seen = std::format("{} / {}", call.step.name, call.step.why); + return outcome_ok(); + })); + const StoryActionRegistry registry(game); + FakeStoryBackend backend({}, scope); + RunState state; + const Outcome outcome = registry.dispatch(backend, game_step("opening", "scene", "the long intro"), state); + if (!outcome.succeeded()){ + return std::format("expected a pass, got {}", to_string(outcome)); + } + return *seen == "opening / the long intro" ? "" : std::format("expected the step, got \"{}\"", *seen); +} + +// A game whose "mark" action records "run " and whose pause hook +// records "pause