From 823f5318d56532c7e286d9f6097494eaaf204e16 Mon Sep 17 00:00:00 2001
From: dayfine <difancpa@gmail.com>
Date: Sat, 31 Oct 2026 21:59:50 -0700
Subject: [PATCH 01/19] Common: add MoveOnlyFunction, a move-only callable
 wrapper

std::function is copyable, so copying one silently forks a stateful
lambda's state, and it can't hold move-only captures.
std::move_only_function fixes both, but Apple Clang's libc++ doesn't have
it yet. MoveOnlyFunction is an alias of std::move_only_function where the
library defines it (GCC, MSVC) and a small fallback elsewhere (macOS),
with copying deleted. Tested with four unit tests on fork CI (Mac runs
the fallback; Ubuntu and Windows clang run the std branch).

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01AKYzhrMnPK61XHWEch4a6E
---
 Common/Cpp/MoveOnlyFunction.h                 | 118 +++++++++++
 Common/Cpp/MoveOnlyFunction_Tests.cpp         | 190 ++++++++++++++++++
 Common/Cpp/MoveOnlyFunction_Tests.h           |  21 ++
 .../ComputerPrograms_UnitTestRunner.cpp       |   2 +
 SerialPrograms/cmake/SourceFiles.cmake        |   3 +
 5 files changed, 334 insertions(+)
 create mode 100644 Common/Cpp/MoveOnlyFunction.h
 create mode 100644 Common/Cpp/MoveOnlyFunction_Tests.cpp
 create mode 100644 Common/Cpp/MoveOnlyFunction_Tests.h

diff --git a/Common/Cpp/MoveOnlyFunction.h b/Common/Cpp/MoveOnlyFunction.h
new file mode 100644
index 0000000000..9cc71f3422
--- /dev/null
+++ b/Common/Cpp/MoveOnlyFunction.h
@@ -0,0 +1,118 @@
+/*  Move-Only Function
+ *
+ *  From: https://github.com/PokemonAutomation/
+ *
+ *  A callable wrapper that can be moved but not copied.
+ *
+ *  Prefer this over std::function for a callback that has one owner.
+ *  Copying a std::function copies its callable, so a stateful lambda
+ *  silently splits into two independent states. And std::function cannot
+ *  hold a lambda that captures a move-only object (e.g. std::unique_ptr).
+ *
+ *  This is std::move_only_function (C++23) where the standard library has
+ *  it. Apple's libc++ (Xcode 26 / Apple Clang 21) does not, so this header
+ *  has a minimal fallback for the plain "R(Args...)" signature. Delete the
+ *  fallback once every supported compiler defines
+ *  __cpp_lib_move_only_function.
+ *
+ */
+
+#ifndef PokemonAutomation_MoveOnlyFunction_H
+#define PokemonAutomation_MoveOnlyFunction_H
+
+#include <version>
+#include <functional>
+
+#ifndef __cpp_lib_move_only_function
+#include <cstddef>
+#include <memory>
+#include <type_traits>
+#include <utility>
+#endif
+
+namespace PokemonAutomation{
+
+
+
+#ifdef __cpp_lib_move_only_function
+
+template <typename Signature>
+using MoveOnlyFunction = std::move_only_function<Signature>;
+
+#else
+
+template <typename Signature>
+class MoveOnlyFunction;
+
+template <typename R, typename... Args>
+class MoveOnlyFunction<R(Args...)>{
+public:
+    MoveOnlyFunction() noexcept = default;
+    MoveOnlyFunction(std::nullptr_t) noexcept {}
+
+    template <typename Function>
+        requires (
+            !std::is_same_v<std::remove_cvref_t<Function>, MoveOnlyFunction> &&
+            std::is_invocable_r_v<R, std::decay_t<Function>&, Args...>
+        )
+    MoveOnlyFunction(Function&& function){
+        using Stored = std::decay_t<Function>;
+        //  Like std::move_only_function, a null function pointer makes an
+        //  empty wrapper.
+        if constexpr (std::is_pointer_v<Stored> || std::is_member_pointer_v<Stored>){
+            if (function == nullptr){
+                return;
+            }
+        }
+        m_callable = std::make_unique<Holder<Stored>>(std::forward<Function>(function));
+    }
+
+    MoveOnlyFunction(MoveOnlyFunction&&) noexcept = default;
+    MoveOnlyFunction& operator=(MoveOnlyFunction&&) noexcept = default;
+    MoveOnlyFunction(const MoveOnlyFunction&) = delete;
+    MoveOnlyFunction& operator=(const MoveOnlyFunction&) = delete;
+
+    explicit operator bool() const noexcept{
+        return m_callable != nullptr;
+    }
+    friend bool operator==(const MoveOnlyFunction& function, std::nullptr_t) noexcept{
+        return !function;
+    }
+
+    //  Calling an empty wrapper is undefined, as for std::move_only_function.
+    R operator()(Args... args){
+        return m_callable->call(std::forward<Args>(args)...);
+    }
+
+
+private:
+    class Callable{
+    public:
+        virtual ~Callable() = default;
+        virtual R call(Args&&... args) = 0;
+    };
+
+    template <typename Stored>
+    class Holder final : public Callable{
+    public:
+        template <typename Source>
+        explicit Holder(Source&& source)
+            : m_stored(std::forward<Source>(source))
+        {}
+        virtual R call(Args&&... args) override{
+            return std::invoke_r<R>(m_stored, std::forward<Args>(args)...);
+        }
+
+    private:
+        Stored m_stored;
+    };
+
+    std::unique_ptr<Callable> m_callable;
+};
+
+#endif
+
+
+
+}
+#endif
diff --git a/Common/Cpp/MoveOnlyFunction_Tests.cpp b/Common/Cpp/MoveOnlyFunction_Tests.cpp
new file mode 100644
index 0000000000..72ed5998ae
--- /dev/null
+++ b/Common/Cpp/MoveOnlyFunction_Tests.cpp
@@ -0,0 +1,190 @@
+/*  Move-Only Function Tests
+ *
+ *  From: https://github.com/PokemonAutomation/
+ *
+ */
+
+#include <memory>
+#include <string>
+#include <type_traits>
+#include <utility>
+#include "TestRunners/UnitTestDatabase.h"
+#include "MoveOnlyFunction.h"
+#include "MoveOnlyFunction_Tests.h"
+
+namespace PokemonAutomation{
+namespace{
+
+
+
+//  Copying would fork a stateful callable, so it must not compile.
+static_assert(!std::is_copy_constructible_v<MoveOnlyFunction<void()>>);
+static_assert(!std::is_copy_assignable_v<MoveOnlyFunction<void()>>);
+static_assert(std::is_nothrow_move_constructible_v<MoveOnlyFunction<void()>>);
+
+
+
+std::string expected_int(const char* what, int expected, int actual){
+    return std::string(what) + ": expected " + std::to_string(expected) +
+        ", got " + std::to_string(actual);
+}
+
+
+
+class Test_MoveOnlyFunction_MoveOnlyCapture : public UnitTest{
+public:
+    Test_MoveOnlyFunction_MoveOnlyCapture()
+        : UnitTest("Common::MoveOnlyFunction - Move-only capture")
+    {}
+
+    virtual UnitTestResult run(Logger& logger, CancellableScope& scope) const override{
+        auto value = std::make_unique<int>(42);
+        MoveOnlyFunction<int(int)> function = [value = std::move(value)](int add){
+            return *value + add;
+        };
+        int actual = function(1);
+        if (actual != 43){
+            return UnitTestResult(expected_int("call with a unique_ptr capture", 43, actual));
+        }
+
+        MoveOnlyFunction<int(int)> moved = std::move(function);
+        actual = moved(2);
+        if (actual != 44){
+            return UnitTestResult(expected_int("call after a move", 44, actual));
+        }
+        return true;
+    }
+};
+
+
+
+class Test_MoveOnlyFunction_StateNotForked : public UnitTest{
+public:
+    Test_MoveOnlyFunction_StateNotForked()
+        : UnitTest("Common::MoveOnlyFunction - Moving keeps one state")
+    {}
+
+    virtual UnitTestResult run(Logger& logger, CancellableScope& scope) const override{
+        MoveOnlyFunction<int()> counter = [count = 0]() mutable{
+            return ++count;
+        };
+        int actual = counter();
+        if (actual != 1){
+            return UnitTestResult(expected_int("first call", 1, actual));
+        }
+
+        //  The moved-to wrapper continues the same count.
+        MoveOnlyFunction<int()> constructed = std::move(counter);
+        actual = constructed();
+        if (actual != 2){
+            return UnitTestResult(expected_int("call after a move construction", 2, actual));
+        }
+
+        MoveOnlyFunction<int()> assigned;
+        assigned = std::move(constructed);
+        actual = assigned();
+        if (actual != 3){
+            return UnitTestResult(expected_int("call after a move assignment", 3, actual));
+        }
+        return true;
+    }
+};
+
+
+
+int return_seven(){
+    return 7;
+}
+
+class Test_MoveOnlyFunction_Empty : public UnitTest{
+public:
+    Test_MoveOnlyFunction_Empty()
+        : UnitTest("Common::MoveOnlyFunction - Empty is false")
+    {}
+
+    virtual UnitTestResult run(Logger& logger, CancellableScope& scope) const override{
+        MoveOnlyFunction<int()> defaulted;
+        if (defaulted){
+            return UnitTestResult("default constructed: expected empty, got non-empty");
+        }
+        MoveOnlyFunction<int()> from_nullptr = nullptr;
+        if (from_nullptr){
+            return UnitTestResult("constructed from nullptr: expected empty, got non-empty");
+        }
+        int (*null_pointer)() = nullptr;
+        MoveOnlyFunction<int()> from_null_pointer = null_pointer;
+        if (from_null_pointer){
+            return UnitTestResult("constructed from a null function pointer: expected empty, got non-empty");
+        }
+
+        MoveOnlyFunction<int()> from_pointer = &return_seven;
+        if (!from_pointer){
+            return UnitTestResult("constructed from a function pointer: expected non-empty, got empty");
+        }
+        int actual = from_pointer();
+        if (actual != 7){
+            return UnitTestResult(expected_int("call through a function pointer", 7, actual));
+        }
+        return true;
+    }
+};
+
+
+
+class Test_MoveOnlyFunction_Reassignment : public UnitTest{
+public:
+    Test_MoveOnlyFunction_Reassignment()
+        : UnitTest("Common::MoveOnlyFunction - Reassignment")
+    {}
+
+    virtual UnitTestResult run(Logger& logger, CancellableScope& scope) const override{
+        //  The use count shows whether the wrapper still holds the first
+        //  callable.
+        auto token = std::make_shared<int>(1);
+        MoveOnlyFunction<int()> function = [token]{
+            return *token;
+        };
+        int actual = function();
+        if (actual != 1){
+            return UnitTestResult(expected_int("first callable", 1, actual));
+        }
+
+        function = []{
+            return 2;
+        };
+        actual = function();
+        if (actual != 2){
+            return UnitTestResult(expected_int("call after reassignment", 2, actual));
+        }
+        actual = (int)token.use_count();
+        if (actual != 1){
+            return UnitTestResult(expected_int("token owners after reassignment", 1, actual));
+        }
+
+        function = nullptr;
+        if (function){
+            return UnitTestResult("assigned nullptr: expected empty, got non-empty");
+        }
+        if (function != nullptr){
+            return UnitTestResult("assigned nullptr: expected == nullptr, got != nullptr");
+        }
+        return true;
+    }
+};
+
+
+
+} // anonymous namespace
+
+
+
+void add_tests_MoveOnlyFunction(UnitTestDatabase& database){
+    database.add<Test_MoveOnlyFunction_MoveOnlyCapture>();
+    database.add<Test_MoveOnlyFunction_StateNotForked>();
+    database.add<Test_MoveOnlyFunction_Empty>();
+    database.add<Test_MoveOnlyFunction_Reassignment>();
+}
+
+
+
+}
diff --git a/Common/Cpp/MoveOnlyFunction_Tests.h b/Common/Cpp/MoveOnlyFunction_Tests.h
new file mode 100644
index 0000000000..c43f518bdc
--- /dev/null
+++ b/Common/Cpp/MoveOnlyFunction_Tests.h
@@ -0,0 +1,21 @@
+/*  Move-Only Function Tests
+ *
+ *  From: https://github.com/PokemonAutomation/
+ *
+ */
+
+#ifndef PokemonAutomation_MoveOnlyFunction_Tests_H
+#define PokemonAutomation_MoveOnlyFunction_Tests_H
+
+#include "Common/Cpp/TestRunners/UnitTestDatabase.h"
+
+namespace PokemonAutomation{
+
+
+
+void add_tests_MoveOnlyFunction(UnitTestDatabase& database);
+
+
+
+}
+#endif
diff --git a/SerialPrograms/Source/ComputerPrograms/ComputerPrograms_UnitTestRunner.cpp b/SerialPrograms/Source/ComputerPrograms/ComputerPrograms_UnitTestRunner.cpp
index 1c19573466..d434036d6e 100644
--- a/SerialPrograms/Source/ComputerPrograms/ComputerPrograms_UnitTestRunner.cpp
+++ b/SerialPrograms/Source/ComputerPrograms/ComputerPrograms_UnitTestRunner.cpp
@@ -5,6 +5,7 @@
  */
 
 #include "Common/Cpp/ListenerSet.h"
+#include "Common/Cpp/MoveOnlyFunction_Tests.h"
 #include "Common/Cpp/ScopeExit.h"
 #include "Common/Cpp/PrettyPrint.h"
 #include "Common/Cpp/TestRunners/TestImageDistortionManager.h"
@@ -51,6 +52,7 @@ UnitTestDatabase make_UNIT_TESTS_ALL(){
     add_tests_QtEventThreadPool(ret, GlobalThreadPools::computation_normal());
     add_tests_BlackBorderDetector(ret);
     add_tests_ListenerSet(ret);
+    add_tests_MoveOnlyFunction(ret);
     add_tests_AudioInfo(ret);
     add_tests_ChannelMixerMatrix(ret);
     add_tests_FFTStreamer(ret);
diff --git a/SerialPrograms/cmake/SourceFiles.cmake b/SerialPrograms/cmake/SourceFiles.cmake
index b0f27c7490..98d84589f1 100644
--- a/SerialPrograms/cmake/SourceFiles.cmake
+++ b/SerialPrograms/cmake/SourceFiles.cmake
@@ -118,6 +118,9 @@ file(GLOB CORE_LIBRARY_SOURCES
     ../Common/Cpp/Logging/MultiOutputLogger.h
     ../Common/Cpp/Logging/TaggedLogger.cpp
     ../Common/Cpp/Logging/TaggedLogger.h
+    ../Common/Cpp/MoveOnlyFunction.h
+    ../Common/Cpp/MoveOnlyFunction_Tests.cpp
+    ../Common/Cpp/MoveOnlyFunction_Tests.h
     ../Common/Cpp/Options/BatchOption.cpp
     ../Common/Cpp/Options/BatchOption.h
     ../Common/Cpp/Options/BooleanCheckBoxOption.cpp

From 3209523a93783ccebe5c2ab5231e9bf4e23f2ab4 Mon Sep 17 00:00:00 2001
From: dayfine <difancpa@gmail.com>
Date: Sat, 31 Oct 2026 22:00:28 -0700
Subject: [PATCH 02/19] Pokemon navigation: grid types and leg planner over a
 game's step model

FRLG and BDSP each built a grid planner for AutoStory, and the two copies
share the same ideas but can't serve each other, because each planner is
tied to its own map type. This adds the part both games plan on: the grid
types (tile positions and directions) and a leg planner that asks the
game's step model what one press does and prefers legs that end at a
wall, tested on a small made-up game. The leg walker, ScreenMachine and
TileGrid/MapSet live with their users in other PRs.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01AKYzhrMnPK61XHWEch4a6E
---
 .../ComputerPrograms_UnitTestRunner.cpp       |   2 +
 .../Pokemon/Navigation/Pokemon_Grid.cpp       |  50 +++
 .../Source/Pokemon/Navigation/Pokemon_Grid.h  |  57 +++
 .../Pokemon/Navigation/Pokemon_LegPlanner.h   | 339 ++++++++++++++++++
 .../Navigation/Pokemon_LegPlanner_Tests.cpp   | 260 ++++++++++++++
 .../Navigation/Pokemon_Navigation_Tests.h     |  22 ++
 SerialPrograms/cmake/SourceFiles.cmake        |   5 +
 7 files changed, 735 insertions(+)
 create mode 100644 SerialPrograms/Source/Pokemon/Navigation/Pokemon_Grid.cpp
 create mode 100644 SerialPrograms/Source/Pokemon/Navigation/Pokemon_Grid.h
 create mode 100644 SerialPrograms/Source/Pokemon/Navigation/Pokemon_LegPlanner.h
 create mode 100644 SerialPrograms/Source/Pokemon/Navigation/Pokemon_LegPlanner_Tests.cpp
 create mode 100644 SerialPrograms/Source/Pokemon/Navigation/Pokemon_Navigation_Tests.h

diff --git a/SerialPrograms/Source/ComputerPrograms/ComputerPrograms_UnitTestRunner.cpp b/SerialPrograms/Source/ComputerPrograms/ComputerPrograms_UnitTestRunner.cpp
index d434036d6e..79b8520da0 100644
--- a/SerialPrograms/Source/ComputerPrograms/ComputerPrograms_UnitTestRunner.cpp
+++ b/SerialPrograms/Source/ComputerPrograms/ComputerPrograms_UnitTestRunner.cpp
@@ -28,6 +28,7 @@
 #include "NintendoSwitch/Inference/NintendoSwitch_UpdatePopupDetector.h"
 #include "NintendoSwitch/Programs/Typewriter/NintendoSwitch_Typewriter_Tests.h"
 
+#include "Pokemon/Navigation/Pokemon_Navigation_Tests.h"
 #include "VideoGames/PokemonHome/PokemonHome_Tests.h"
 #include "VideoGames/PokemonSwSh/PokemonSwSh_Tests.h"
 #include "VideoGames/PokemonLA/PokemonLA_Tests.h"
@@ -60,6 +61,7 @@ UnitTestDatabase make_UNIT_TESTS_ALL(){
     add_tests_AudioFileLoader(ret);
     OCR::add_tests(ret);
     Kernels::add_tests(ret);
+    Pokemon::add_tests_LegPlanner(ret);
     NintendoSwitch::add_tests_CheckOnlineDetector(ret);
     NintendoSwitch::add_tests_FailedToConnectDetector(ret);
     NintendoSwitch::add_tests_UpdatePopupDetector(ret);
diff --git a/SerialPrograms/Source/Pokemon/Navigation/Pokemon_Grid.cpp b/SerialPrograms/Source/Pokemon/Navigation/Pokemon_Grid.cpp
new file mode 100644
index 0000000000..4aaaf62536
--- /dev/null
+++ b/SerialPrograms/Source/Pokemon/Navigation/Pokemon_Grid.cpp
@@ -0,0 +1,50 @@
+/*  Grid
+ *
+ *  From: https://github.com/PokemonAutomation/
+ *
+ */
+
+#include <format>
+#include "Pokemon_Grid.h"
+
+namespace PokemonAutomation{
+namespace Pokemon{
+
+
+const char* direction_name(Direction direction){
+    switch (direction){
+    case Direction::NORTH:
+        return "north";
+    case Direction::EAST:
+        return "east";
+    case Direction::SOUTH:
+        return "south";
+    case Direction::WEST:
+        return "west";
+    }
+    return "?";
+}
+
+
+TilePos TilePos::next(Direction direction) const{
+    switch (direction){
+    case Direction::NORTH:
+        return {x, y - 1};
+    case Direction::EAST:
+        return {x + 1, y};
+    case Direction::SOUTH:
+        return {x, y + 1};
+    case Direction::WEST:
+        return {x - 1, y};
+    }
+    return *this;
+}
+
+std::string to_string(const TilePos& pos){
+    return std::format("({}, {})", pos.x, pos.y);
+}
+
+
+
+}
+}
diff --git a/SerialPrograms/Source/Pokemon/Navigation/Pokemon_Grid.h b/SerialPrograms/Source/Pokemon/Navigation/Pokemon_Grid.h
new file mode 100644
index 0000000000..409e6fe06e
--- /dev/null
+++ b/SerialPrograms/Source/Pokemon/Navigation/Pokemon_Grid.h
@@ -0,0 +1,57 @@
+/*  Grid
+ *
+ *  From: https://github.com/PokemonAutomation/
+ *
+ *  Tiles and directions on an overworld grid, shared by the games that
+ *  move the player a tile at a time.
+ *
+ */
+
+#ifndef PokemonAutomation_Pokemon_Grid_H
+#define PokemonAutomation_Pokemon_Grid_H
+
+#include <cstddef>
+#include <functional>
+#include <string>
+
+namespace PokemonAutomation{
+namespace Pokemon{
+
+
+//  Row 0 is the top of a map, so SOUTH increases y.
+enum class Direction{
+    NORTH,
+    EAST,
+    SOUTH,
+    WEST,
+};
+constexpr Direction ALL_DIRECTIONS[] = {
+    Direction::NORTH, Direction::EAST, Direction::SOUTH, Direction::WEST,
+};
+const char* direction_name(Direction direction);
+
+
+struct TilePos{
+    int x = 0;
+    int y = 0;
+
+    TilePos next(Direction direction) const;
+    bool operator==(const TilePos& other) const = default;
+};
+std::string to_string(const TilePos& pos);
+
+
+
+}
+}
+
+
+template <>
+struct std::hash<PokemonAutomation::Pokemon::TilePos>{
+    size_t operator()(const PokemonAutomation::Pokemon::TilePos& pos) const{
+        return std::hash<long long>()(((long long)pos.x << 32) ^ (unsigned)pos.y);
+    }
+};
+
+
+#endif
diff --git a/SerialPrograms/Source/Pokemon/Navigation/Pokemon_LegPlanner.h b/SerialPrograms/Source/Pokemon/Navigation/Pokemon_LegPlanner.h
new file mode 100644
index 0000000000..c9d49735d9
--- /dev/null
+++ b/SerialPrograms/Source/Pokemon/Navigation/Pokemon_LegPlanner.h
@@ -0,0 +1,339 @@
+/*  Leg Planner
+ *
+ *  From: https://github.com/PokemonAutomation/
+ *
+ *  Plans a walk as straight legs: hold one direction, then the next. The
+ *  game decides what a single press does through its step model; the
+ *  planner searches, joins steps into legs, and prefers legs that end
+ *  against a wall, because the player stops there however long the button
+ *  is held, while a leg that ends in the open depends on timing.
+ *
+ *  A step model is a class with:
+ *
+ *      using State = ...;      //  where the player is and what moves them:
+ *                              //  comparable with ==
+ *      using StateHash = ...;  //  a hash of State, e.g. std::hash<TilePos>
+ *      std::optional<Step<State>> press(const State& state, Direction direction) const;
+ *      bool held_at(const State& state, Direction direction) const;
+ *
+ *  press() is what pressing `direction` once does, or nothing if the player
+ *  can't go that way (a wall, or something the plan must not do). held_at()
+ *  is whether holding `direction` keeps the player on this tile: a wall, but
+ *  not a person who may walk off or an edge to a map that isn't loaded.
+ *
+ */
+
+#ifndef PokemonAutomation_Pokemon_LegPlanner_H
+#define PokemonAutomation_Pokemon_LegPlanner_H
+
+#include <algorithm>
+#include <functional>
+#include <limits>
+#include <optional>
+#include <queue>
+#include <unordered_map>
+#include <utility>
+#include <vector>
+#include "Pokemon_Grid.h"
+
+namespace PokemonAutomation{
+namespace Pokemon{
+
+
+//  What one press does.
+template <typename State>
+struct Step{
+    State next;
+    //  0 for a plain step. Anything else is a step of the game's own kind
+    //  (e.g. starting to Surf), planned as a leg on its own.
+    int action = 0;
+    //  The step can't continue the leg before it, e.g. leaving the water,
+    //  after which the player walks at another speed.
+    bool starts_leg = false;
+    //  No later step continues this leg: the game stops the player, e.g.
+    //  at a warp.
+    bool ends_leg = false;
+    //  The step takes a warp: a door, a ladder, a cave entrance.
+    bool warped = false;
+    //  Which way the player faces afterwards. Usually the pressed direction;
+    //  some warps turn the player.
+    Direction facing = Direction::NORTH;
+    //  Cost on top of LegCosts::per_tile: tall grass, a warp's fade, a dialog.
+    int extra_cost = 0;
+};
+
+
+enum class LegKind{
+    WALK,       //  hold `direction` for `tiles` steps
+    ACTION,     //  one step of the game's own kind, `action`
+    FACE,       //  turn to `direction` without moving
+};
+
+template <typename State>
+struct Leg{
+    LegKind kind = LegKind::WALK;
+    int action = 0;
+    Direction direction = Direction::NORTH;
+    int tiles = 0;
+    //  WALK: the last step takes a warp.
+    bool warps = false;
+    //  WALK: holding on keeps the player on the last tile, so the leg can be
+    //  held for longer than it takes and walked again after an interruption.
+    bool to_wall = false;
+    Direction facing_after = Direction::NORTH;
+    State start;
+    State end;
+};
+
+
+struct LegCosts{
+    int per_tile = 1;
+    //  Extra for a step in a new direction.
+    int per_turn = 2;
+    //  Extra for ending a leg where the player could keep going: it has to
+    //  be timed, and where an interruption leaves the player is a guess.
+    int per_open_stop = 8;
+};
+
+
+//  The cheapest legs from `start` to a state where `at_goal` holds, facing
+//  `goal_facing` if given, or nothing if there is none. `start_facing` is
+//  the way the player faces at the start, if known.
+template <typename Model>
+std::optional<std::vector<Leg<typename Model::State>>> plan_legs(
+    const Model& model,
+    const typename Model::State& start, std::optional<Direction> start_facing,
+    const std::function<bool(const typename Model::State&)>& at_goal,
+    std::optional<Direction> goal_facing,
+    const LegCosts& costs = LegCosts()
+);
+
+
+
+namespace LegPlannerInternal{
+
+//  A search node: the player, the way they face (4: not known), and whether
+//  they are in the middle of a leg that could go on.
+template <typename State>
+struct Node{
+    State state;
+    int facing = 4;
+    bool moving = false;
+
+    bool operator==(const Node& other) const = default;
+};
+
+template <typename State, typename StateHash>
+struct NodeHash{
+    size_t operator()(const Node<State>& node) const{
+        return StateHash()(node.state) * 10 + node.facing * 2 + (node.moving ? 1 : 0);
+    }
+};
+
+template <typename State>
+struct Move{
+    Node<State> from;
+    Direction direction;
+    Step<State> step;
+};
+
+template <typename Model, typename State>
+int stop_cost(const Model& model, const Node<State>& node, const LegCosts& costs){
+    if (!node.moving || model.held_at(node.state, (Direction)node.facing)){
+        return 0;
+    }
+    return costs.per_open_stop;
+}
+
+template <typename Model, typename State>
+std::vector<Leg<State>> join_legs(const Model& model, const State& start, const std::vector<Move<State>>& moves){
+    std::vector<Leg<State>> legs;
+    bool can_extend = false;
+    State before = start;
+    for (const Move<State>& move : moves){
+        const Step<State>& step = move.step;
+        const bool extends = can_extend && step.action == 0 && !step.starts_leg
+            && legs.back().kind == LegKind::WALK && legs.back().direction == move.direction;
+        if (extends){
+            legs.back().tiles++;
+        }else{
+            Leg<State> leg;
+            leg.kind = step.action == 0 ? LegKind::WALK : LegKind::ACTION;
+            leg.action = step.action;
+            leg.direction = move.direction;
+            leg.tiles = 1;
+            leg.start = before;
+            legs.push_back(leg);
+        }
+        Leg<State>& leg = legs.back();
+        leg.warps = step.warped;
+        leg.to_wall = leg.kind == LegKind::WALK && !step.warped && model.held_at(step.next, move.direction);
+        leg.facing_after = step.facing;
+        leg.end = step.next;
+        can_extend = step.action == 0 && !step.ends_leg;
+        before = step.next;
+    }
+    return legs;
+}
+
+//  The search's working set. Nodes are kept in a list and queued by index,
+//  so State needs no ordering.
+template <typename Model>
+struct Search{
+    using State = typename Model::State;
+    using Hash = NodeHash<State, typename Model::StateHash>;
+    using Entry = std::pair<int, size_t>;
+
+    std::unordered_map<Node<State>, int, Hash> distance;
+    std::unordered_map<Node<State>, Move<State>, Hash> came_from;
+    std::vector<Node<State>> nodes;
+    std::priority_queue<Entry, std::vector<Entry>, std::greater<Entry>> queue;
+};
+
+template <typename Model, typename State>
+int distance_of(const Search<Model>& search, const Node<State>& node){
+    auto iter = search.distance.find(node);
+    return iter == search.distance.end() ? std::numeric_limits<int>::max() : iter->second;
+}
+
+//  Records `cost` as the way to `node` if it is cheaper than any so far.
+template <typename Model, typename State>
+void relax(Search<Model>& search, const Node<State>& node, int cost, const Move<State>& move){
+    if (cost >= distance_of(search, node)){
+        return;
+    }
+    search.distance[node] = cost;
+    search.came_from.insert_or_assign(node, move);
+    search.nodes.push_back(node);
+    search.queue.emplace(cost, search.nodes.size() - 1);
+}
+
+//  Queues every press from `current`, reached at `cost`.
+template <typename Model, typename State>
+void expand(
+    const Model& model, Search<Model>& search,
+    const Node<State>& current, int cost, const LegCosts& costs
+){
+    for (Direction direction : ALL_DIRECTIONS){
+        std::optional<Step<State>> step = model.press(current.state, direction);
+        if (!step){
+            continue;
+        }
+        const bool continues = step->action == 0 && !step->ends_leg;
+        const Node<State> next{step->next, (int)step->facing, continues};
+        int step_cost = costs.per_tile + step->extra_cost;
+        if (current.facing != (int)direction){
+            step_cost += costs.per_turn + stop_cost(model, current, costs);
+        }
+        relax(search, next, cost + step_cost, Move<State>{current, direction, *step});
+    }
+}
+
+//  What it costs to end at `node`: stopping there, then turning to
+//  `goal_facing`.
+template <typename Model, typename State>
+int arrival_cost(
+    const Model& model, const Node<State>& node,
+    std::optional<Direction> goal_facing, const LegCosts& costs
+){
+    int cost = stop_cost(model, node, costs);
+    if (goal_facing && node.facing != (int)*goal_facing){
+        cost += costs.per_turn;
+    }
+    return cost;
+}
+
+//  Runs the search from `first` and returns the goal node cheapest to end
+//  at, or nothing if no goal can be reached.
+template <typename Model, typename State>
+std::optional<Node<State>> search_goal(
+    const Model& model, Search<Model>& search, const Node<State>& first,
+    const std::function<bool(const State&)>& at_goal,
+    std::optional<Direction> goal_facing, const LegCosts& costs
+){
+    search.distance[first] = 0;
+    search.nodes.push_back(first);
+    search.queue.emplace(0, 0);
+
+    std::optional<Node<State>> best_end;
+    int best_total = std::numeric_limits<int>::max();
+    while (!search.queue.empty()){
+        const auto [cost, index] = search.queue.top();
+        search.queue.pop();
+        const Node<State> current = search.nodes[index];
+        if (cost != distance_of(search, current)){
+            continue;
+        }
+        if (cost >= best_total){
+            break;
+        }
+        if (!at_goal(current.state)){
+            expand(model, search, current, cost, costs);
+            continue;
+        }
+        const int total = cost + arrival_cost(model, current, goal_facing, costs);
+        if (total < best_total){
+            best_total = total;
+            best_end = current;
+        }
+    }
+    return best_end;
+}
+
+//  The moves from `first` to `end`, in order.
+template <typename Model, typename State>
+std::vector<Move<State>> trace_moves(const Search<Model>& search, const Node<State>& first, const Node<State>& end){
+    std::vector<Move<State>> moves;
+    for (Node<State> node = end; !(node == first); node = search.came_from.at(node).from){
+        moves.push_back(search.came_from.at(node));
+    }
+    std::reverse(moves.begin(), moves.end());
+    return moves;
+}
+
+template <typename State>
+Leg<State> face_leg(const State& state, Direction direction){
+    Leg<State> face;
+    face.kind = LegKind::FACE;
+    face.direction = direction;
+    face.facing_after = direction;
+    face.start = state;
+    face.end = state;
+    return face;
+}
+
+}
+
+
+
+template <typename Model>
+std::optional<std::vector<Leg<typename Model::State>>> plan_legs(
+    const Model& model,
+    const typename Model::State& start, std::optional<Direction> start_facing,
+    const std::function<bool(const typename Model::State&)>& at_goal,
+    std::optional<Direction> goal_facing,
+    const LegCosts& costs
+){
+    using State = typename Model::State;
+    using Node = LegPlannerInternal::Node<State>;
+
+    const Node first{start, start_facing ? (int)*start_facing : 4, false};
+    LegPlannerInternal::Search<Model> search;
+    const std::optional<Node> end = LegPlannerInternal::search_goal(model, search, first, at_goal, goal_facing, costs);
+    if (!end){
+        return std::nullopt;
+    }
+    std::vector<Leg<State>> legs = LegPlannerInternal::join_legs(
+        model, start, LegPlannerInternal::trace_moves(search, first, *end)
+    );
+    if (goal_facing && end->facing != (int)*goal_facing){
+        legs.push_back(LegPlannerInternal::face_leg(end->state, *goal_facing));
+    }
+    return legs;
+}
+
+
+
+}
+}
+#endif
diff --git a/SerialPrograms/Source/Pokemon/Navigation/Pokemon_LegPlanner_Tests.cpp b/SerialPrograms/Source/Pokemon/Navigation/Pokemon_LegPlanner_Tests.cpp
new file mode 100644
index 0000000000..de69a79762
--- /dev/null
+++ b/SerialPrograms/Source/Pokemon/Navigation/Pokemon_LegPlanner_Tests.cpp
@@ -0,0 +1,260 @@
+/*  Leg Planner Tests
+ *
+ *  From: https://github.com/PokemonAutomation/
+ *
+ *  The planner on a small made-up game, with the kinds of tiles the real
+ *  games have: walls, people, tall grass, a one-way tile and a warp.
+ *
+ */
+
+#include <format>
+#include <functional>
+#include <string>
+#include <vector>
+#include "Common/Cpp/TestRunners/UnitTest.h"
+#include "Pokemon_LegPlanner.h"
+#include "Pokemon_Navigation_Tests.h"
+
+namespace PokemonAutomation{
+namespace Pokemon{
+
+
+namespace{
+
+//  '#' wall, '.' floor, '"' tall grass, 'p' a person (blocks, but may walk
+//  off, so not a wall to stop against), 'v' entered only going south, 'W'
+//  a warp to the tile marked 'X'.
+class ToyGame{
+public:
+    using State = TilePos;
+    using StateHash = std::hash<TilePos>;
+
+    explicit ToyGame(std::vector<std::string> rows)
+        : m_rows(std::move(rows))
+    {
+        for (int y = 0; y < (int)m_rows.size(); y++){
+            for (int x = 0; x < (int)m_rows[y].size(); x++){
+                if (m_rows[y][x] == 'X'){
+                    m_warp_to = {x, y};
+                }
+            }
+        }
+    }
+
+    std::optional<Step<State>> press(const State& state, Direction direction) const{
+        const TilePos next = state.next(direction);
+        const char tile = at(next);
+        if (tile == '#' || tile == 'p' || (tile == 'v' && direction != Direction::SOUTH)){
+            return std::nullopt;
+        }
+        Step<State> step;
+        step.next = next;
+        step.facing = direction;
+        if (tile == '"'){
+            step.extra_cost = 5;
+        }
+        if (tile == 'W'){
+            step.next = m_warp_to;
+            step.warped = true;
+            step.ends_leg = true;
+            step.extra_cost = 10;
+        }
+        return step;
+    }
+    bool held_at(const State& state, Direction direction) const{
+        const char tile = at(state.next(direction));
+        return tile == '#' || (tile == 'v' && direction != Direction::SOUTH);
+    }
+
+private:
+    char at(const TilePos& pos) const{
+        if (pos.y < 0 || pos.y >= (int)m_rows.size() || pos.x < 0 || pos.x >= (int)m_rows[pos.y].size()){
+            return '#';
+        }
+        return m_rows[pos.y][pos.x];
+    }
+
+    std::vector<std::string> m_rows;
+    TilePos m_warp_to;
+};
+
+
+std::string describe(const std::vector<Leg<TilePos>>& legs){
+    std::string text;
+    for (const Leg<TilePos>& leg : legs){
+        text += "\n  ";
+        text += leg.kind == LegKind::FACE ? "face " : "walk ";
+        text += direction_name(leg.direction);
+        if (leg.kind == LegKind::WALK){
+            text += std::format(" {}", leg.tiles);
+        }
+        if (leg.to_wall){
+            text += " (to wall)";
+        }
+        if (leg.warps){
+            text += " (warp)";
+        }
+        text += " -> " + to_string(leg.end);
+    }
+    return text;
+}
+
+std::optional<std::vector<Leg<TilePos>>> plan(
+    const ToyGame& game, TilePos from, TilePos to,
+    std::optional<Direction> start_facing = std::nullopt,
+    std::optional<Direction> goal_facing = std::nullopt
+){
+    return plan_legs(game, from, start_facing, std::function<bool(const TilePos&)>([to](const TilePos& pos){ return pos == to; }), goal_facing);
+}
+
+
+UnitTestResult test_prefers_wall_legs(){
+    //  Two ways of equal length: east then south ends both legs in the open;
+    //  south then east ends the last one against the pillar.
+    const ToyGame game({
+        "......",
+        "...#..",
+        "......",
+    });
+    const auto legs = plan(game, {0, 0}, {2, 1});
+    if (!legs || legs->size() != 2){
+        return "Expected 2 legs:" + (legs ? describe(*legs) : std::string(" none"));
+    }
+    if ((*legs)[1].direction != Direction::EAST || !(*legs)[1].to_wall){
+        return "Expected to end going east into the pillar:" + describe(*legs);
+    }
+    return true;
+}
+
+UnitTestResult test_person_is_not_a_wall(){
+    //  The only way ends next to a person, which isn't a wall to stop against.
+    const ToyGame game({
+        "#####",
+        "#..p#",
+        "#####",
+    });
+    const auto legs = plan(game, {1, 1}, {2, 1});
+    if (!legs || legs->size() != 1 || (*legs)[0].to_wall){
+        return "Expected one open leg:" + (legs ? describe(*legs) : std::string(" none"));
+    }
+    return true;
+}
+
+UnitTestResult test_avoids_grass(){
+    //  Straight through the grass is 4 tiles; around it is 8, cheaper with
+    //  5 extra per grass tile.
+    const ToyGame game({
+        ".....",
+        ".\"\"\".",
+        ".....",
+    });
+    const auto legs = plan(game, {0, 1}, {4, 1});
+    if (!legs){
+        return "No route.";
+    }
+    for (const Leg<TilePos>& leg : *legs){
+        if (leg.end.y == 1 && leg.end.x > 0 && leg.end.x < 4){
+            return "Walked into the grass:" + describe(*legs);
+        }
+    }
+    return true;
+}
+
+UnitTestResult test_one_way_tile(){
+    //  The 'v' can only be entered going south, so going back up must go around.
+    const ToyGame game({
+        "#.#.#",
+        "#v#.#",
+        "#...#",
+        "#####",
+    });
+    if (!plan(game, {1, 0}, {1, 2})){
+        return "No route down through the one-way tile.";
+    }
+    const auto up = plan(game, {1, 2}, {1, 0});
+    if (up){
+        return "Went up through the one-way tile:" + describe(*up);
+    }
+    return true;
+}
+
+UnitTestResult test_warp_ends_leg(){
+    //  The warp on the left takes the player to X on the right.
+    const ToyGame game({
+        "#######",
+        "#W.#X.#",
+        "#..#..#",
+        "#######",
+    });
+    const auto legs = plan(game, {2, 2}, {5, 2});
+    if (!legs){
+        return "No route.";
+    }
+    bool warped = false;
+    for (const Leg<TilePos>& leg : *legs){
+        if (leg.warps){
+            warped = true;
+            if (!(leg.end == TilePos{4, 1})){
+                return std::format("The warp leg ends at {}:{}", to_string(leg.end), describe(*legs));
+            }
+        }
+    }
+    if (!warped){
+        return "Expected a warp leg:" + describe(*legs);
+    }
+    return true;
+}
+
+UnitTestResult test_goal_facing(){
+    const ToyGame game({
+        "....",
+    });
+    const auto legs = plan(game, {0, 0}, {2, 0}, std::nullopt, Direction::NORTH);
+    if (!legs || legs->back().kind != LegKind::FACE || legs->back().direction != Direction::NORTH){
+        return "Expected to end facing north:" + (legs ? describe(*legs) : std::string(" none"));
+    }
+    return true;
+}
+
+UnitTestResult test_unreachable(){
+    const ToyGame game({
+        ".#.",
+    });
+    if (plan(game, {0, 0}, {2, 0})){
+        return "Planned through a wall.";
+    }
+    return true;
+}
+
+
+class Test_LegPlanner : public UnitTest{
+public:
+    Test_LegPlanner(std::string name, std::function<UnitTestResult()> body)
+        : UnitTest("Pokemon::LegPlanner - " + std::move(name))
+        , m_body(std::move(body))
+    {}
+    virtual UnitTestResult run(Logger&, CancellableScope&) const override{
+        return m_body();
+    }
+
+private:
+    std::function<UnitTestResult()> m_body;
+};
+
+}
+
+
+void add_tests_LegPlanner(UnitTestDatabase& database){
+    database.add<Test_LegPlanner>("prefers legs that end at a wall", test_prefers_wall_legs);
+    database.add<Test_LegPlanner>("a person is not a wall", test_person_is_not_a_wall);
+    database.add<Test_LegPlanner>("avoids tall grass", test_avoids_grass);
+    database.add<Test_LegPlanner>("one-way tile", test_one_way_tile);
+    database.add<Test_LegPlanner>("a warp ends the leg", test_warp_ends_leg);
+    database.add<Test_LegPlanner>("turns to face the goal", test_goal_facing);
+    database.add<Test_LegPlanner>("nothing through a wall", test_unreachable);
+}
+
+
+
+}
+}
diff --git a/SerialPrograms/Source/Pokemon/Navigation/Pokemon_Navigation_Tests.h b/SerialPrograms/Source/Pokemon/Navigation/Pokemon_Navigation_Tests.h
new file mode 100644
index 0000000000..5919dd56b2
--- /dev/null
+++ b/SerialPrograms/Source/Pokemon/Navigation/Pokemon_Navigation_Tests.h
@@ -0,0 +1,22 @@
+/*  Navigation Tests
+ *
+ *  From: https://github.com/PokemonAutomation/
+ *
+ */
+
+#ifndef PokemonAutomation_Pokemon_Navigation_Tests_H
+#define PokemonAutomation_Pokemon_Navigation_Tests_H
+
+#include "Common/Cpp/TestRunners/UnitTestDatabase.h"
+
+namespace PokemonAutomation{
+namespace Pokemon{
+
+
+void add_tests_LegPlanner(UnitTestDatabase& database);
+
+
+
+}
+}
+#endif
diff --git a/SerialPrograms/cmake/SourceFiles.cmake b/SerialPrograms/cmake/SourceFiles.cmake
index 98d84589f1..5766bd2ebd 100644
--- a/SerialPrograms/cmake/SourceFiles.cmake
+++ b/SerialPrograms/cmake/SourceFiles.cmake
@@ -1438,6 +1438,11 @@ file(GLOB LIBRARY_SOURCES
     Source/Pokemon/Inference/Pokemon_TrainPokemonOCR.h
     Source/Pokemon/Inference/Pokemon_TypeReader.cpp
     Source/Pokemon/Inference/Pokemon_TypeReader.h
+    Source/Pokemon/Navigation/Pokemon_Grid.cpp
+    Source/Pokemon/Navigation/Pokemon_Grid.h
+    Source/Pokemon/Navigation/Pokemon_LegPlanner.h
+    Source/Pokemon/Navigation/Pokemon_LegPlanner_Tests.cpp
+    Source/Pokemon/Navigation/Pokemon_Navigation_Tests.h
     Source/Pokemon/Options/Pokemon_BoxSortingTable.cpp
     Source/Pokemon/Options/Pokemon_BoxSortingTable.h
     Source/Pokemon/Options/Pokemon_EncounterBotOptions.h

From c246d3d56988c3de68dd7713e39903b120b82b55 Mon Sep 17 00:00:00 2001
From: dayfine <difancpa@gmail.com>
Date: Sat, 31 Oct 2026 22:00:49 -0700
Subject: [PATCH 03/19] ScreenMachine: a closed loop over known screens

BDSP's new-game intro runs as a closed loop over the screens it knows:
read the screen, take the one step that screen calls for, read again,
and treat an unexpected screen or a state that keeps coming back as the
sign of a dropped or wrong input. This adds that loop as its own module:
ScreenMachine runs it and StepTrace logs every recognized screen change
with a numbered screenshot and every input, so a failure reports the
screens that led up to it. Nothing here depends on navigation; there are
no tests yet, CI checks that it builds on its own.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01AKYzhrMnPK61XHWEch4a6E
---
 .../ScreenMachine/ScreenMachine.cpp           |  97 ++++++++++++++++
 .../CommonTools/ScreenMachine/ScreenMachine.h | 105 ++++++++++++++++++
 .../CommonTools/ScreenMachine/StepTrace.cpp   |  74 ++++++++++++
 .../CommonTools/ScreenMachine/StepTrace.h     |  53 +++++++++
 SerialPrograms/cmake/SourceFiles.cmake        |   4 +
 5 files changed, 333 insertions(+)
 create mode 100644 SerialPrograms/Source/CommonTools/ScreenMachine/ScreenMachine.cpp
 create mode 100644 SerialPrograms/Source/CommonTools/ScreenMachine/ScreenMachine.h
 create mode 100644 SerialPrograms/Source/CommonTools/ScreenMachine/StepTrace.cpp
 create mode 100644 SerialPrograms/Source/CommonTools/ScreenMachine/StepTrace.h

diff --git a/SerialPrograms/Source/CommonTools/ScreenMachine/ScreenMachine.cpp b/SerialPrograms/Source/CommonTools/ScreenMachine/ScreenMachine.cpp
new file mode 100644
index 0000000000..8d528c4eaa
--- /dev/null
+++ b/SerialPrograms/Source/CommonTools/ScreenMachine/ScreenMachine.cpp
@@ -0,0 +1,97 @@
+/*  Screen Machine
+ *
+ *  From: https://github.com/PokemonAutomation/
+ *
+ */
+
+#include <algorithm>
+#include "CommonFramework/ImageTools/ImageDiff.h"
+#include "ScreenMachine.h"
+
+namespace PokemonAutomation{
+
+using namespace std::chrono_literals;
+
+
+namespace{
+
+const ScreenState* classify(const std::vector<ScreenState>& states, const ImageViewRGB32& screen){
+    for (const ScreenState& state : states){
+        if (state.matches(screen)){
+            return &state;
+        }
+    }
+    return nullptr;
+}
+
+}
+
+
+const ScreenState& read_screen_state(
+    VideoStream& stream, CancellableScope& scope, StepTrace& trace,
+    const std::vector<ScreenState>& states, VideoSnapshot& frame
+){
+    const ScreenState* last = nullptr;
+    WallClock video_lost = WallClock::max();
+    for (size_t c = 0; c < 20; c++){
+        VideoSnapshot screen = stream.video().snapshot();
+        if (!screen){
+            //  The app resets a frozen capture by itself, which takes a second or two.
+            const WallClock now = current_time();
+            video_lost = std::min(video_lost, now);
+            if (now - video_lost > std::chrono::seconds(10)){
+                trace.fail("No video from the capture card for 10s.");
+            }
+            c--;
+            scope.wait_for(500ms);
+            continue;
+        }
+        video_lost = WallClock::max();
+        const ScreenState* now = classify(states, screen);
+        frame = std::move(screen);
+        if (now != nullptr && now == last){
+            return *now;
+        }
+        last = now;
+        scope.wait_for(150ms);
+    }
+    if (last == nullptr){
+        trace.fail("The screen matches none of the known states.");
+    }
+    return *last;   //  Still changing after 3s: go with the latest read.
+}
+
+
+void ScreenMachineChecks::check(const ScreenState& state, VideoSnapshot frame){
+    const bool same_size = m_last_frame && frame &&
+        m_last_frame->width() == frame->width() && m_last_frame->height() == frame->height();
+    if (same_size && ImageMatch::pixel_RMSD(m_last_frame, frame) < 2.0){
+        if (++m_unchanged >= MAX_UNCHANGED){
+            m_trace.fail("The screen stopped changing: " + std::to_string(MAX_UNCHANGED) +
+                " steps on \"" + state.name + "\" did nothing.");
+        }
+    }else{
+        m_unchanged = 0;
+    }
+    m_last_frame = std::move(frame);
+
+    if (m_previous != nullptr && m_previous != &state && !m_previous->next.empty() &&
+        std::find(m_previous->next.begin(), m_previous->next.end(), state.name) == m_previous->next.end()
+    ){
+        m_trace.fail("Unexpected screen after \"" + m_previous->name + "\": \"" + state.name + "\".");
+    }
+    m_in_a_row = m_previous == &state ? m_in_a_row + 1 : 1;
+    if (m_in_a_row > state.max_in_a_row){
+        m_trace.fail("Screen \"" + state.name + "\" came up " + std::to_string(m_in_a_row) +
+            " times in a row: the step for it is not getting anywhere.");
+    }
+    if (++m_visits[state.name] > state.max_visits){
+        m_trace.fail("Screen \"" + state.name + "\" came up more than " +
+            std::to_string(state.max_visits) + " times: the step for it is not working.");
+    }
+    m_previous = &state;
+}
+
+
+
+}
diff --git a/SerialPrograms/Source/CommonTools/ScreenMachine/ScreenMachine.h b/SerialPrograms/Source/CommonTools/ScreenMachine/ScreenMachine.h
new file mode 100644
index 0000000000..f878ff709c
--- /dev/null
+++ b/SerialPrograms/Source/CommonTools/ScreenMachine/ScreenMachine.h
@@ -0,0 +1,105 @@
+/*  Screen Machine
+ *
+ *  From: https://github.com/PokemonAutomation/
+ *
+ *  A closed loop over known screens: read the screen, take the one step that screen
+ *  calls for, read again. Every step follows a read, a screen counts only once two
+ *  frames agree, and each state lists the screens it may lead to, so a dropped or
+ *  wrong input shows up as an unexpected screen or a state that keeps coming back.
+ *
+ */
+
+#ifndef PokemonAutomation_CommonTools_ScreenMachine_H
+#define PokemonAutomation_CommonTools_ScreenMachine_H
+
+#include <stdint.h>
+#include <functional>
+#include <map>
+#include <string>
+#include <vector>
+#include "Common/Cpp/Time.h"
+#include "Common/Cpp/CancellableScope.h"
+#include "CommonFramework/ImageTypes/ImageViewRGB32.h"
+#include "CommonFramework/Tools/VideoStream.h"
+#include "CommonFramework/VideoPipeline/VideoFeed.h"
+#include "StepTrace.h"
+
+namespace PokemonAutomation{
+
+
+struct ScreenState{
+    std::string name;
+    //  Whether this is the screen. States are tried in order; the first match wins, so
+    //  the last state should match anything.
+    std::function<bool(const ImageViewRGB32& screen)> matches;
+    //  The one step to take on this screen.
+    std::function<void()> act;
+    //  The screens the step may lead to besides staying here. Empty: any.
+    std::vector<std::string> next;
+    //  Fail once the screen has been seen this many times.
+    size_t max_visits;
+    //  End the run after this state's step.
+    bool terminal = false;
+    //  Fail once the screen has been seen this many times in a row.
+    size_t max_in_a_row = SIZE_MAX;
+};
+
+
+//  The state on screen, once two frames 150ms apart agree. Waits out a video
+//  gap of up to 10s. Fails through `trace` if no state matches.
+const ScreenState& read_screen_state(
+    VideoStream& stream, CancellableScope& scope, StepTrace& trace,
+    const std::vector<ScreenState>& states, VideoSnapshot& frame
+);
+
+//  The checks between reads: the screen must be one the previous state can lead
+//  to, no state may come up too often, and steps must keep changing the screen.
+class ScreenMachineChecks{
+public:
+    ScreenMachineChecks(StepTrace& trace)
+        : m_trace(trace)
+    {}
+    void check(const ScreenState& state, VideoSnapshot frame);
+
+private:
+    //  A step that changes nothing on screen is a dead end (e.g. a menu the states do
+    //  not know): fail after a few instead of running out the visit limit.
+    static constexpr size_t MAX_UNCHANGED = 8;
+
+    StepTrace& m_trace;
+    std::map<std::string, size_t> m_visits;
+    const ScreenState* m_previous = nullptr;
+    VideoSnapshot m_last_frame;
+    size_t m_unchanged = 0;
+    size_t m_in_a_row = 0;
+};
+
+
+//  Runs the states until a terminal one has acted. Returns its name. Fails through
+//  `trace` on an unexpected screen, a state seen too often, a stall or the timeout.
+template <typename ControllerContext>
+std::string run_screen_machine(
+    VideoStream& stream, ControllerContext& context, StepTrace& trace,
+    const std::vector<ScreenState>& states, Milliseconds timeout
+){
+    ScreenMachineChecks checks(trace);
+    const WallClock deadline = current_time() + timeout;
+    while (current_time() < deadline){
+        context.wait_for_all_requests();
+        VideoSnapshot frame;
+        const ScreenState& state = read_screen_state(stream, context, trace, states, frame);
+        trace.screen(state.name);
+        checks.check(state, std::move(frame));
+        state.act();
+        if (state.terminal){
+            context.wait_for_all_requests();
+            return state.name;
+        }
+    }
+    trace.fail("Did not finish within " + std::to_string(timeout.count() / 1000) + "s.");
+}
+
+
+
+}
+#endif
diff --git a/SerialPrograms/Source/CommonTools/ScreenMachine/StepTrace.cpp b/SerialPrograms/Source/CommonTools/ScreenMachine/StepTrace.cpp
new file mode 100644
index 0000000000..246bac04a0
--- /dev/null
+++ b/SerialPrograms/Source/CommonTools/ScreenMachine/StepTrace.cpp
@@ -0,0 +1,74 @@
+/*  Step Trace
+ *
+ *  From: https://github.com/PokemonAutomation/
+ *
+ */
+
+#include <cstdio>
+#include "Common/Cpp/PrettyPrint.h"
+#include "Common/Cpp/Filesystem/Filesystem.h"
+#include "CommonFramework/GlobalAutoPaths.h"
+#include "CommonFramework/Exceptions/OperationFailedExceptionWithScreenshot.h"
+#include "CommonFramework/VideoPipeline/VideoFeed.h"
+#include "StepTrace.h"
+
+namespace PokemonAutomation{
+
+
+StepTrace::StepTrace(VideoStream& stream, std::string label)
+    : m_stream(stream)
+    , m_label(std::move(label))
+    , m_folder(SCREENSHOTS_PATH() + "StepTrace/" + now_to_filestring() + "-" + m_label + "/")
+    , m_start(current_time())
+{
+    Filesystem::create_directories(Filesystem::Path(m_folder));
+    m_stream.log("[" + m_label + "] Trace screenshots: " + m_folder);
+}
+
+void StepTrace::screen(const std::string& name){
+    if (name == m_last){
+        return;
+    }
+    m_last = name;
+    m_recent.push_back(name);
+    if (m_recent.size() > 12){
+        m_recent.pop_front();
+    }
+    m_count++;
+    const double seconds = std::chrono::duration<double>(current_time() - m_start).count();
+    char prefix[16];
+    std::snprintf(prefix, sizeof(prefix), "%03zu-", m_count);
+    std::string path = m_folder + prefix + name + ".png";
+    VideoSnapshot screen = m_stream.video().snapshot();
+    if (screen){
+        screen.frame->save(path);
+    }else{
+        path = "(no video frame)";
+    }
+    m_stream.log("[" + m_label + "] screen " + std::to_string(m_count) + ": " + name +
+        " at " + tostr_fixed(seconds, 1) + "s, " + path);
+}
+
+void StepTrace::action(const std::string& what){
+    m_stream.log("[" + m_label + "] " + what);
+}
+
+std::string StepTrace::recent_screens() const{
+    std::string text;
+    for (const std::string& name : m_recent){
+        text += (text.empty() ? "" : " -> ") + name;
+    }
+    return text.empty() ? "(none)" : text;
+}
+
+void StepTrace::fail(const std::string& message) const{
+    OperationFailedExceptionWithScreenshot::fire(
+        ErrorReportMode::SEND_ERROR_REPORT,
+        m_label + ": " + message + " Recent screens: " + recent_screens() + ". Trace: " + m_folder,
+        m_stream
+    );
+}
+
+
+
+}
diff --git a/SerialPrograms/Source/CommonTools/ScreenMachine/StepTrace.h b/SerialPrograms/Source/CommonTools/ScreenMachine/StepTrace.h
new file mode 100644
index 0000000000..e0c4db09d0
--- /dev/null
+++ b/SerialPrograms/Source/CommonTools/ScreenMachine/StepTrace.h
@@ -0,0 +1,53 @@
+/*  Step Trace
+ *
+ *  From: https://github.com/PokemonAutomation/
+ *
+ *  A step log for closed-loop routines: every change of recognized screen is
+ *  logged and saved as a numbered screenshot, every input is logged, and a
+ *  failure reports the screens that led up to it.
+ *
+ */
+
+#ifndef PokemonAutomation_CommonTools_StepTrace_H
+#define PokemonAutomation_CommonTools_StepTrace_H
+
+#include <deque>
+#include <string>
+#include "Common/Cpp/Time.h"
+#include "CommonFramework/Tools/VideoStream.h"
+
+namespace PokemonAutomation{
+
+
+class StepTrace{
+public:
+    //  Screenshots go to <Screenshots>/StepTrace/<time>-<label>/.
+    StepTrace(VideoStream& stream, std::string label);
+
+    //  Records the screen the routine recognized. Logs and saves a screenshot only
+    //  when it differs from the previous one.
+    void screen(const std::string& name);
+
+    //  Records an input or decision.
+    void action(const std::string& what);
+
+    //  The last few screens, oldest first, e.g. "dialog -> keyboard -> dialog".
+    std::string recent_screens() const;
+
+    //  Throws OperationFailedExceptionWithScreenshot with the recent screens appended.
+    [[noreturn]] void fail(const std::string& message) const;
+
+private:
+    VideoStream& m_stream;
+    std::string m_label;
+    std::string m_folder;
+    WallClock m_start;
+    size_t m_count = 0;
+    std::string m_last;
+    std::deque<std::string> m_recent;
+};
+
+
+
+}
+#endif
diff --git a/SerialPrograms/cmake/SourceFiles.cmake b/SerialPrograms/cmake/SourceFiles.cmake
index 5766bd2ebd..9aceebcaed 100644
--- a/SerialPrograms/cmake/SourceFiles.cmake
+++ b/SerialPrograms/cmake/SourceFiles.cmake
@@ -887,6 +887,10 @@ file(GLOB LIBRARY_SOURCES
     Source/CommonTools/Options/TrainOCRModeOption.h
     Source/CommonTools/Resources/SpriteDatabase.cpp
     Source/CommonTools/Resources/SpriteDatabase.h
+    Source/CommonTools/ScreenMachine/ScreenMachine.cpp
+    Source/CommonTools/ScreenMachine/ScreenMachine.h
+    Source/CommonTools/ScreenMachine/StepTrace.cpp
+    Source/CommonTools/ScreenMachine/StepTrace.h
     Source/CommonTools/StartupChecks/StartProgramChecks.cpp
     Source/CommonTools/StartupChecks/StartProgramChecks.h
     Source/CommonTools/StartupChecks/VideoResolutionCheck.cpp

From f3a8943a3dae440adfdcf073d75c8e1f676d0eda Mon Sep 17 00:00:00 2001
From: dayfine <difancpa@gmail.com>
Date: Sat, 31 Oct 2026 22:01:48 -0700
Subject: [PATCH 04/19] Pokemon navigation: run story checkpoints as events

AutoStory checkpoints are long C++ functions of walks, presses and
waits, and a checkpoint only notices drift or a missed talk when a later
step fails. This adds the game-neutral runner from the event-model
design: a checkpoint is a list of events with skip_if, require, an
action, expects, a learned pose and named recoveries (wait, then
re-anchor, then stop), plus per-checkpoint interrupts. run_checkpoint()
skips events whose effect already shows, so a reload resumes by
re-checking, and it logs one "[Event] ..." line per event for the lab
watcher. Observation and actuation are MoveOnlyFunctions, so the
Pokemon::StoryEvents unit tests run it against a scripted world; no
game uses it yet.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01AKYzhrMnPK61XHWEch4a6E
---
 .../ComputerPrograms_UnitTestRunner.cpp       |   1 +
 .../Navigation/Pokemon_Navigation_Tests.h     |   1 +
 .../Navigation/Pokemon_StoryEvents.cpp        | 447 ++++++++++++++
 .../Pokemon/Navigation/Pokemon_StoryEvents.h  | 202 +++++++
 .../Navigation/Pokemon_StoryEvents_Tests.cpp  | 550 ++++++++++++++++++
 SerialPrograms/cmake/SourceFiles.cmake        |   3 +
 6 files changed, 1204 insertions(+)
 create mode 100644 SerialPrograms/Source/Pokemon/Navigation/Pokemon_StoryEvents.cpp
 create mode 100644 SerialPrograms/Source/Pokemon/Navigation/Pokemon_StoryEvents.h
 create mode 100644 SerialPrograms/Source/Pokemon/Navigation/Pokemon_StoryEvents_Tests.cpp

diff --git a/SerialPrograms/Source/ComputerPrograms/ComputerPrograms_UnitTestRunner.cpp b/SerialPrograms/Source/ComputerPrograms/ComputerPrograms_UnitTestRunner.cpp
index 79b8520da0..2607f8d0ad 100644
--- a/SerialPrograms/Source/ComputerPrograms/ComputerPrograms_UnitTestRunner.cpp
+++ b/SerialPrograms/Source/ComputerPrograms/ComputerPrograms_UnitTestRunner.cpp
@@ -62,6 +62,7 @@ UnitTestDatabase make_UNIT_TESTS_ALL(){
     OCR::add_tests(ret);
     Kernels::add_tests(ret);
     Pokemon::add_tests_LegPlanner(ret);
+    Pokemon::add_tests_StoryEvents(ret);
     NintendoSwitch::add_tests_CheckOnlineDetector(ret);
     NintendoSwitch::add_tests_FailedToConnectDetector(ret);
     NintendoSwitch::add_tests_UpdatePopupDetector(ret);
diff --git a/SerialPrograms/Source/Pokemon/Navigation/Pokemon_Navigation_Tests.h b/SerialPrograms/Source/Pokemon/Navigation/Pokemon_Navigation_Tests.h
index 5919dd56b2..e6d709afce 100644
--- a/SerialPrograms/Source/Pokemon/Navigation/Pokemon_Navigation_Tests.h
+++ b/SerialPrograms/Source/Pokemon/Navigation/Pokemon_Navigation_Tests.h
@@ -14,6 +14,7 @@ namespace Pokemon{
 
 
 void add_tests_LegPlanner(UnitTestDatabase& database);
+void add_tests_StoryEvents(UnitTestDatabase& database);
 
 
 
diff --git a/SerialPrograms/Source/Pokemon/Navigation/Pokemon_StoryEvents.cpp b/SerialPrograms/Source/Pokemon/Navigation/Pokemon_StoryEvents.cpp
new file mode 100644
index 0000000000..2d3448a679
--- /dev/null
+++ b/SerialPrograms/Source/Pokemon/Navigation/Pokemon_StoryEvents.cpp
@@ -0,0 +1,447 @@
+/*  Story Events
+ *
+ *  From: https://github.com/PokemonAutomation/
+ *
+ */
+
+#include <format>
+#include <utility>
+#include "Pokemon_StoryEvents.h"
+
+namespace PokemonAutomation{
+namespace Pokemon{
+
+
+const char* certainty_name(PoseCertainty certainty){
+    switch (certainty){
+    case PoseCertainty::TILE:
+        return "tile";
+    case PoseCertainty::COLUMN:
+        return "column";
+    case PoseCertainty::ROW:
+        return "row";
+    case PoseCertainty::SET:
+        return "set";
+    case PoseCertainty::UNKNOWN:
+        return "unknown";
+    }
+    return "?";
+}
+
+bool certainty_covers(PoseCertainty have, PoseCertainty need){
+    switch (need){
+    case PoseCertainty::UNKNOWN:
+        return true;
+    case PoseCertainty::SET:
+        return have != PoseCertainty::UNKNOWN;
+    case PoseCertainty::COLUMN:
+    case PoseCertainty::ROW:
+        return have == need || have == PoseCertainty::TILE;
+    case PoseCertainty::TILE:
+        return have == PoseCertainty::TILE;
+    }
+    return false;
+}
+
+std::string to_string(const Pose& pose){
+    std::string text = pose.map.empty() ? "?" : pose.map;
+    for (const TilePos& tile : pose.tiles){
+        text += " " + to_string(tile);
+    }
+    if (pose.facing){
+        text += std::string(" facing ") + direction_name(*pose.facing);
+    }
+    return text + " (" + certainty_name(pose.certainty) + ")";
+}
+
+
+bool Outcome::succeeded() const{
+    return failure.empty();
+}
+Outcome outcome_ok(){
+    return Outcome{};
+}
+Outcome outcome_failed(std::string failure, std::string detail){
+    return Outcome{std::move(failure), std::move(detail)};
+}
+
+Condition condition(std::string name, Check check){
+    return Condition{std::move(name), std::move(check)};
+}
+
+Condition pose_known(std::string map, PoseCertainty need){
+    std::string name = std::string("pose ") + certainty_name(need) + (map.empty() ? "" : " on " + map);
+    return condition(std::move(name), [map = std::move(map), need](RunState& state){
+        return (map.empty() || state.pose.map == map) && certainty_covers(state.pose.certainty, need);
+    });
+}
+
+const char* recovery_name(RecoveryKind kind){
+    switch (kind){
+    case RecoveryKind::WAIT:
+        return "wait";
+    case RecoveryKind::REANCHOR:
+        return "re-anchor";
+    case RecoveryKind::STOP:
+        return "stop";
+    }
+    return "?";
+}
+
+
+std::string event_log_line(const std::string& checkpoint, size_t number, const std::string& event, const std::string& status){
+    return std::format("[Event] {}/{} {}: {}", checkpoint, number, event, status);
+}
+
+
+namespace{
+
+std::string describe(const Outcome& outcome){
+    return outcome.detail.empty() ? outcome.failure : outcome.failure + ": " + outcome.detail;
+}
+
+//  The name of the first condition that does not hold.
+std::optional<std::string> first_failing(std::vector<Condition>& conditions, RunState& state){
+    for (Condition& item : conditions){
+        if (!item.check(state)){
+            return item.name;
+        }
+    }
+    return std::nullopt;
+}
+
+bool already_done(Event& event, RunState& state){
+    return !event.skip_if.empty() && !first_failing(event.skip_if, state);
+}
+
+Outcome check_expects(Event& event, RunState& state){
+    std::optional<std::string> failing = first_failing(event.expect, state);
+    if (failing){
+        return outcome_failed("expect_failed", *failing);
+    }
+    if (event.pose_learned){
+        state.pose = *event.pose_learned;
+    }
+    return outcome_ok();
+}
+
+Outcome attempt_event(Event& event, RunState& state){
+    std::optional<std::string> failing = first_failing(event.require, state);
+    if (failing){
+        return outcome_failed("require_failed", *failing);
+    }
+    Outcome outcome = event.act(state);
+    if (!outcome.succeeded()){
+        return outcome;
+    }
+    return check_expects(event, state);
+}
+
+void apply_interrupt_pose(Pose& pose, InterruptPose effect){
+    switch (effect){
+    case InterruptPose::UNCHANGED:
+        return;
+    case InterruptPose::INEXACT:
+        if (pose.certainty != PoseCertainty::UNKNOWN){
+            pose.certainty = PoseCertainty::SET;
+        }
+        return;
+    case InterruptPose::LOST:
+        pose.tiles.clear();
+        pose.facing.reset();
+        pose.certainty = PoseCertainty::UNKNOWN;
+        return;
+    }
+}
+
+
+//  One event being run, with what it has used up.
+struct EventRun{
+    Checkpoint& checkpoint;
+    size_t number;
+    Event& event;
+    RunState& state;
+    EventLogger& log;
+    std::vector<size_t> recoveries_used;
+    size_t interrupts = 0;
+};
+
+void log_status(EventRun& run, const std::string& status){
+    run.log(event_log_line(run.checkpoint.id, run.number, run.event.name, status));
+}
+
+
+//  What the interrupts showing after an action ask for.
+struct InterruptResult{
+    bool fired = false;
+    ResumePolicy resume = ResumePolicy::RECHECK_EXPECT;
+    Outcome outcome;
+};
+
+//  The policy that asks for more: STOP over RETRY_EVENT over RECHECK_EXPECT.
+ResumePolicy stronger(ResumePolicy x, ResumePolicy y){
+    if (x == ResumePolicy::STOP || y == ResumePolicy::STOP){
+        return ResumePolicy::STOP;
+    }
+    if (x == ResumePolicy::RETRY_EVENT || y == ResumePolicy::RETRY_EVENT){
+        return ResumePolicy::RETRY_EVENT;
+    }
+    return ResumePolicy::RECHECK_EXPECT;
+}
+
+//  Clears every interrupt showing.
+InterruptResult clear_interrupts(EventRun& run){
+    InterruptResult result;
+    for (Interrupt& interrupt : run.checkpoint.interrupts){
+        if (!interrupt.detect(run.state)){
+            continue;
+        }
+        run.interrupts++;
+        log_status(run, "interrupt: " + interrupt.name);
+        if (run.interrupts > run.checkpoint.max_interrupts_per_event){
+            result.outcome = outcome_failed("too_many_interrupts", interrupt.name);
+            return result;
+        }
+        if (interrupt.handle){
+            Outcome handled = interrupt.handle(run.state);
+            if (!handled.succeeded()){
+                result.outcome = outcome_failed("interrupt_failed", interrupt.name + ": " + describe(handled));
+                return result;
+            }
+        }
+        apply_interrupt_pose(run.state.pose, interrupt.pose);
+        result.resume = result.fired ? stronger(result.resume, interrupt.resume) : interrupt.resume;
+        result.fired = true;
+    }
+    return result;
+}
+
+
+//  The next recovery for `failure`, using up one of its attempts.
+Recovery* next_recovery(EventRun& run, const std::string& failure){
+    std::vector<Recovery>& recoveries = run.event.recoveries;
+    for (size_t c = 0; c < recoveries.size(); c++){
+        Recovery& recovery = recoveries[c];
+        if (!recovery.on.empty() && recovery.on != failure){
+            continue;
+        }
+        if (recovery.kind != RecoveryKind::STOP && run.recoveries_used[c] >= recovery.attempts){
+            continue;
+        }
+        run.recoveries_used[c]++;
+        return &recovery;
+    }
+    return nullptr;
+}
+
+//  Answers `failure` with the event's recoveries. Returns nothing to try the
+//  event again, or the failure that stops it. A recovery that fails itself
+//  is answered in turn, so escalation goes on from there.
+std::optional<Outcome> recover(EventRun& run, Outcome failure){
+    while (true){
+        Recovery* recovery = next_recovery(run, failure.failure);
+        if (recovery == nullptr){
+            return failure;
+        }
+        std::string line = std::string("recover: ") + recovery_name(recovery->kind) + " (" + failure.failure + ")";
+        log_status(run, recovery->why.empty() ? line : line + ": " + recovery->why);
+        if (recovery->kind == RecoveryKind::STOP){
+            return failure;
+        }
+        if (!recovery->prepare){
+            return std::nullopt;
+        }
+        Outcome prepared = recovery->prepare(run.state);
+        if (prepared.succeeded()){
+            return std::nullopt;
+        }
+        failure = std::move(prepared);
+    }
+}
+
+
+enum class Next{
+    DONE,
+    RETRY,
+    RECOVER,
+    STOP,
+};
+
+//  After one attempt: what the interrupts showing and the outcome call for.
+//  `outcome` becomes the failure to recover from or stop on.
+Next after_attempt(EventRun& run, Outcome& outcome){
+    InterruptResult interrupted = clear_interrupts(run);
+    if (!interrupted.outcome.succeeded()){
+        outcome = std::move(interrupted.outcome);
+        return Next::STOP;
+    }
+    if (interrupted.fired){
+        switch (interrupted.resume){
+        case ResumePolicy::STOP:
+            outcome = outcome_failed("interrupted", "stopped by an interrupt");
+            return Next::STOP;
+        case ResumePolicy::RETRY_EVENT:
+            return Next::RETRY;
+        case ResumePolicy::RECHECK_EXPECT:
+            outcome = check_expects(run.event, run.state);
+            return outcome.succeeded() ? Next::DONE : Next::RETRY;
+        }
+    }
+    return outcome.succeeded() ? Next::DONE : Next::RECOVER;
+}
+
+//  Runs one event to success or to the failure that stops it.
+Outcome run_event(EventRun& run){
+    log_status(run, "start");
+    for (bool first = true; ; first = false){
+        if (!first && already_done(run.event, run.state)){
+            log_status(run, "done: already showing");
+            return outcome_ok();
+        }
+        Outcome outcome = attempt_event(run.event, run.state);
+        Next next = after_attempt(run, outcome);
+        if (next == Next::DONE){
+            log_status(run, "done");
+            return outcome_ok();
+        }
+        if (next == Next::RETRY){
+            continue;
+        }
+        if (next == Next::RECOVER){
+            std::optional<Outcome> stop = recover(run, std::move(outcome));
+            if (!stop){
+                continue;
+            }
+            outcome = std::move(*stop);
+        }
+        log_status(run, "failed: " + describe(outcome));
+        return outcome;
+    }
+}
+
+
+CheckpointReport stop_checkpoint(CheckpointReport& report, EventLogger& log, const std::string& id, Outcome failure){
+    std::string where = report.failed_event == 0
+        ? ""
+        : std::format(" at {} {}", report.failed_event, report.failed_name);
+    log(std::format("[Checkpoint] {}: failed{}: {}", id, where, describe(failure)));
+    report.failure = std::move(failure);
+    return report;
+}
+
+Outcome finish_checkpoint(RunState& state, Checkpoint& checkpoint){
+    std::optional<std::string> failing = first_failing(checkpoint.end, state);
+    if (failing){
+        return outcome_failed("end_failed", *failing);
+    }
+    if (!checkpoint.save){
+        return outcome_ok();
+    }
+    Outcome saved = checkpoint.save(state);
+    return saved.succeeded() ? saved : outcome_failed("save_failed", describe(saved));
+}
+
+}
+
+
+CheckpointReport run_checkpoint(RunState& state, Checkpoint& checkpoint, EventLogger& log){
+    CheckpointReport report;
+    const std::string& id = checkpoint.id;
+    log(std::format("[Checkpoint] {}: start, {} events", id, checkpoint.events.size()));
+    std::optional<std::string> failing = first_failing(checkpoint.start, state);
+    if (failing){
+        return stop_checkpoint(report, log, id, outcome_failed("start_failed", *failing));
+    }
+    for (size_t c = 0; c < checkpoint.events.size(); c++){
+        Event& event = checkpoint.events[c];
+        EventRun run{checkpoint, c + 1, event, state, log, std::vector<size_t>(event.recoveries.size(), 0), 0};
+        if (already_done(event, state)){
+            log_status(run, "skipped");
+            report.events_skipped++;
+            continue;
+        }
+        report.events_run++;
+        Outcome outcome = run_event(run);
+        if (!outcome.succeeded()){
+            report.failed_event = c + 1;
+            report.failed_name = event.name;
+            return stop_checkpoint(report, log, id, std::move(outcome));
+        }
+    }
+    Outcome finished = finish_checkpoint(state, checkpoint);
+    if (!finished.succeeded()){
+        return stop_checkpoint(report, log, id, std::move(finished));
+    }
+    report.completed = true;
+    log(std::format("[Checkpoint] {}: done, {} run, {} skipped", id, report.events_run, report.events_skipped));
+    return report;
+}
+
+
+namespace{
+
+void lint_conditions(std::vector<std::string>& problems, const std::string& where, const std::vector<Condition>& conditions){
+    for (const Condition& item : conditions){
+        if (item.name.empty() || !item.check){
+            problems.emplace_back(where + ": a condition without a name or a check");
+        }
+    }
+}
+
+void lint_recoveries(std::vector<std::string>& problems, const Event& event){
+    RecoveryKind last = RecoveryKind::WAIT;
+    for (const Recovery& recovery : event.recoveries){
+        if ((int)recovery.kind < (int)last){
+            problems.emplace_back(event.name + ": recovery " + recovery_name(recovery.kind) + " after " + recovery_name(last));
+        }
+        if (recovery.kind != RecoveryKind::STOP && recovery.attempts == 0){
+            problems.emplace_back(event.name + ": recovery " + recovery_name(recovery.kind) + " with no attempts");
+        }
+        last = recovery.kind;
+    }
+}
+
+void lint_event(std::vector<std::string>& problems, std::set<std::string>& names, const Event& event){
+    if (event.name.empty()){
+        problems.emplace_back("an event without a name");
+    }else if (!names.insert(event.name).second){
+        problems.emplace_back(event.name + ": two events with this name");
+    }
+    if (!event.act){
+        problems.emplace_back(event.name + ": no action");
+    }
+    lint_conditions(problems, event.name + " skip_if", event.skip_if);
+    lint_conditions(problems, event.name + " require", event.require);
+    lint_conditions(problems, event.name + " expect", event.expect);
+    lint_recoveries(problems, event);
+}
+
+}
+
+
+std::vector<std::string> lint_checkpoint(const Checkpoint& checkpoint){
+    std::vector<std::string> problems;
+    if (checkpoint.id.empty()){
+        problems.emplace_back("a checkpoint without an id");
+    }
+    if (checkpoint.events.empty()){
+        problems.emplace_back(checkpoint.id + ": no events");
+    }
+    std::set<std::string> names;
+    for (const Event& event : checkpoint.events){
+        lint_event(problems, names, event);
+    }
+    for (const Interrupt& interrupt : checkpoint.interrupts){
+        if (interrupt.name.empty() || !interrupt.detect){
+            problems.emplace_back("an interrupt without a name or a detector");
+        }
+    }
+    lint_conditions(problems, checkpoint.id + " start", checkpoint.start);
+    lint_conditions(problems, checkpoint.id + " end", checkpoint.end);
+    return problems;
+}
+
+
+
+}
+}
diff --git a/SerialPrograms/Source/Pokemon/Navigation/Pokemon_StoryEvents.h b/SerialPrograms/Source/Pokemon/Navigation/Pokemon_StoryEvents.h
new file mode 100644
index 0000000000..c70f2f72f2
--- /dev/null
+++ b/SerialPrograms/Source/Pokemon/Navigation/Pokemon_StoryEvents.h
@@ -0,0 +1,202 @@
+/*  Story Events
+ *
+ *  From: https://github.com/PokemonAutomation/
+ *
+ *  A story checkpoint as a list of events. Each event states what must hold
+ *  before it (require), does one thing (act), and checks what the game shows
+ *  afterwards (expect). An event whose effect is already on screen (skip_if)
+ *  is skipped, so resuming a checkpoint after a reload re-checks instead of
+ *  replaying. A failed event is answered by its named recoveries, in order
+ *  of escalation (wait, then re-anchor, then stop), and anything without a
+ *  recovery stops the checkpoint with the event and the reason.
+ *
+ *  Interrupts (a wild battle, a trainer, a scene) are declared once per
+ *  checkpoint: after each action the runner asks whether one is showing,
+ *  clears it, marks what it did to the pose and resumes as it says.
+ *
+ *  Observation and actuation are callables the game supplies, so this file
+ *  knows nothing of any one game or console, and the runner can be tested
+ *  against a scripted world. See docs/design/AutoStory-Event-Model.md.
+ *
+ */
+
+#ifndef PokemonAutomation_Pokemon_StoryEvents_H
+#define PokemonAutomation_Pokemon_StoryEvents_H
+
+#include <cstddef>
+#include <optional>
+#include <set>
+#include <string>
+#include <vector>
+#include "Common/Cpp/MoveOnlyFunction.h"
+#include "Pokemon_Grid.h"
+
+namespace PokemonAutomation{
+namespace Pokemon{
+
+
+//  How much of the pose is known. COLUMN and ROW pin one axis (a wall, a
+//  door); SET means one of `tiles`.
+enum class PoseCertainty{
+    TILE,
+    COLUMN,
+    ROW,
+    SET,
+    UNKNOWN,
+};
+const char* certainty_name(PoseCertainty certainty);
+
+//  Whether a pose known to `have` is good enough for an event that needs `need`.
+bool certainty_covers(PoseCertainty have, PoseCertainty need);
+
+//  Where the player is believed to be. The screen is read; the pose is
+//  tracked, and only an anchor (a wall, a door, an NPC who answered) makes
+//  it certain.
+struct Pose{
+    std::string map;
+    std::vector<TilePos> tiles;
+    std::optional<Direction> facing;
+    PoseCertainty certainty = PoseCertainty::UNKNOWN;
+};
+std::string to_string(const Pose& pose);
+
+
+//  What a run knows. Flags are set only by confirmed effects and are lost
+//  on a reload.
+struct RunState{
+    Pose pose;
+    std::set<std::string> flags;
+};
+
+
+//  How an action or a check ended: empty `failure` is success; otherwise a
+//  name that recoveries match (e.g. "probe_exhausted").
+struct Outcome{
+    std::string failure;
+    std::string detail;
+
+    bool succeeded() const;
+};
+Outcome outcome_ok();
+Outcome outcome_failed(std::string failure, std::string detail = "");
+
+
+using Act = MoveOnlyFunction<Outcome(RunState& state)>;
+using Check = MoveOnlyFunction<bool(RunState& state)>;
+
+//  A question the screen (or the run state) answers, named for the log.
+struct Condition{
+    std::string name;
+    Check check;
+};
+Condition condition(std::string name, Check check);
+
+//  Holds while the pose is on `map` (any map if empty) and at least as
+//  certain as `need`.
+Condition pose_known(std::string map, PoseCertainty need);
+
+
+enum class RecoveryKind{
+    WAIT,       //  Something transient (a wanderer, a slow scene): wait, try again.
+    REANCHOR,   //  The pose is in doubt: confirm it on a landmark, try again.
+    STOP,       //  Nothing to do: stop the checkpoint.
+};
+const char* recovery_name(RecoveryKind kind);
+
+//  Answers a failure named `on` (any failure if empty): runs `prepare`, if
+//  any, and tries the event again, up to `attempts` times.
+struct Recovery{
+    std::string on;
+    RecoveryKind kind = RecoveryKind::STOP;
+    Act prepare;
+    size_t attempts = 1;
+    std::string why;
+};
+
+
+struct Event{
+    std::string name;
+    std::string why;
+    //  Skipped when all of these hold (and there is at least one).
+    std::vector<Condition> skip_if;
+    //  Must hold before `act`; a failure is "require_failed".
+    std::vector<Condition> require;
+    Act act;
+    //  Must hold after `act`; a failure is "expect_failed".
+    std::vector<Condition> expect;
+    //  Written to the run's pose once the event succeeds. An action that
+    //  learns its pose as it goes (the row that answered) writes it itself.
+    std::optional<Pose> pose_learned;
+    //  In order of escalation.
+    std::vector<Recovery> recoveries;
+};
+
+
+enum class InterruptPose{
+    UNCHANGED,  //  Cleared where we stood (a talk-only trainer).
+    INEXACT,    //  Moved an unknown part of a leg: one of the tiles we had.
+    LOST,       //  Anywhere.
+};
+enum class ResumePolicy{
+    RETRY_EVENT,    //  Run the event again, from its skip_if.
+    RECHECK_EXPECT, //  The action may have finished: done if its expects hold, else retry.
+    STOP,           //  Stop the checkpoint.
+};
+
+//  Something that can stop an action part-way.
+struct Interrupt{
+    std::string name;
+    Check detect;
+    Act handle;
+    InterruptPose pose = InterruptPose::UNCHANGED;
+    ResumePolicy resume = ResumePolicy::RETRY_EVENT;
+};
+
+
+struct Checkpoint{
+    std::string id;
+    //  Must hold before the first event (the save it starts from).
+    std::vector<Condition> start;
+    std::vector<Interrupt> interrupts;
+    std::vector<Event> events;
+    //  Must hold after the last event.
+    std::vector<Condition> end;
+    //  Saves the game after the end check, if set.
+    Act save;
+    size_t max_interrupts_per_event = 5;
+};
+
+
+struct CheckpointReport{
+    bool completed = false;
+    //  1-based number of the event that failed; 0 for the start or end check
+    //  or the save, or when nothing failed.
+    size_t failed_event = 0;
+    std::string failed_name;
+    Outcome failure;
+    size_t events_run = 0;
+    size_t events_skipped = 0;
+};
+
+using EventLogger = MoveOnlyFunction<void(const std::string& line)>;
+
+
+//  One log line, in a format the lab watcher parses:
+//      [Event] 00.04/3 talk_mom: start
+//      [Event] 00.04/3 talk_mom: failed: expect_failed: has_parcel
+std::string event_log_line(const std::string& checkpoint, size_t number, const std::string& event, const std::string& status);
+
+//  Problems an author should fix before running: unnamed or empty events,
+//  missing actions, recoveries out of escalation order.
+std::vector<std::string> lint_checkpoint(const Checkpoint& checkpoint);
+
+//  Runs the checkpoint's events in order, from the first. Events whose
+//  effect is already showing are skipped, so after a reload this resumes.
+//  Logs each event's start and end through `log`.
+CheckpointReport run_checkpoint(RunState& state, Checkpoint& checkpoint, EventLogger& log);
+
+
+
+}
+}
+#endif
diff --git a/SerialPrograms/Source/Pokemon/Navigation/Pokemon_StoryEvents_Tests.cpp b/SerialPrograms/Source/Pokemon/Navigation/Pokemon_StoryEvents_Tests.cpp
new file mode 100644
index 0000000000..433065884f
--- /dev/null
+++ b/SerialPrograms/Source/Pokemon/Navigation/Pokemon_StoryEvents_Tests.cpp
@@ -0,0 +1,550 @@
+/*  Story Events Tests
+ *
+ *  From: https://github.com/PokemonAutomation/
+ *
+ *  The checkpoint runner against a scripted world: a few fields that the
+ *  events' actions change and their checks read, instead of a console.
+ *
+ */
+
+#include <algorithm>
+#include <functional>
+#include <string>
+#include <utility>
+#include <vector>
+#include "Common/Cpp/TestRunners/UnitTest.h"
+#include "Pokemon_StoryEvents.h"
+#include "Pokemon_Navigation_Tests.h"
+
+namespace PokemonAutomation{
+namespace Pokemon{
+
+
+namespace{
+
+//  A small slice of Route 201/202 and the player's house.
+struct World{
+    std::string map = "Route 202";
+    int potions = 0;
+    bool parcel = false;
+    bool dialogue_open = false;
+    bool battle_showing = false;
+    //  Talks that open nothing before the NPC answers (she is wandering).
+    int talks_before_answer = 0;
+    //  Rows between us and Mom; a talk from a row off reaches nobody.
+    int rows_off = 0;
+    //  Walks that fail before one gets through.
+    int walk_failures = 0;
+    std::vector<std::string> trace;
+};
+
+struct Lines{
+    std::vector<std::string> lines;
+
+    EventLogger logger(){
+        return [this](const std::string& line){ lines.push_back(line); };
+    }
+    bool has(const std::string& line) const{
+        return std::find(lines.begin(), lines.end(), line) != lines.end();
+    }
+    std::string all() const{
+        std::string text;
+        for (const std::string& line : lines){
+            text += "\n" + line;
+        }
+        return text;
+    }
+};
+
+Event make_event(std::string name, Act act){
+    Event event;
+    event.name = std::move(name);
+    event.act = std::move(act);
+    return event;
+}
+
+Act record(World& world, std::string what){
+    return [&world, what = std::move(what)](RunState&){
+        world.trace.push_back(what);
+        return outcome_ok();
+    };
+}
+
+Condition has_potions(World& world){
+    return condition("potions in the Bag", [&world](RunState&){ return world.potions > 0; });
+}
+
+Condition dialogue_opened(World& world){
+    return condition("dialogue opened", [&world](RunState&){ return world.dialogue_open; });
+}
+
+//  The Poke Mart lady: answers once she has wandered back, gives 10 Potions.
+Event talk_to_lady(World& world){
+    Event event = make_event("talk_poke_mart_lady", [&world](RunState&){
+        world.trace.push_back("talk");
+        if (world.talks_before_answer > 0){
+            world.talks_before_answer--;
+            return outcome_ok();
+        }
+        world.dialogue_open = true;
+        world.potions += 10;
+        return outcome_ok();
+    });
+    event.skip_if.push_back(has_potions(world));
+    event.expect.push_back(dialogue_opened(world));
+    return event;
+}
+
+Recovery recovery(std::string on, RecoveryKind kind, size_t attempts, Act prepare = nullptr){
+    Recovery recovery;
+    recovery.on = std::move(on);
+    recovery.kind = kind;
+    recovery.attempts = attempts;
+    recovery.prepare = std::move(prepare);
+    return recovery;
+}
+
+Checkpoint make_checkpoint(){
+    Checkpoint checkpoint;
+    checkpoint.id = "00.04";
+    return checkpoint;
+}
+
+
+UnitTestResult test_runs_events_in_order(){
+    World world;
+    Checkpoint checkpoint = make_checkpoint();
+    checkpoint.events.push_back(make_event("walk_to_corner", record(world, "walk")));
+    checkpoint.events.push_back(make_event("talk_lady", record(world, "talk")));
+    checkpoint.events.push_back(make_event("save", record(world, "save")));
+    RunState state;
+    Lines lines;
+    EventLogger log = lines.logger();
+    const CheckpointReport report = run_checkpoint(state, checkpoint, log);
+    const std::vector<std::string> expected = {
+        "[Checkpoint] 00.04: start, 3 events",
+        "[Event] 00.04/1 walk_to_corner: start",
+        "[Event] 00.04/1 walk_to_corner: done",
+        "[Event] 00.04/2 talk_lady: start",
+        "[Event] 00.04/2 talk_lady: done",
+        "[Event] 00.04/3 save: start",
+        "[Event] 00.04/3 save: done",
+        "[Checkpoint] 00.04: done, 3 run, 0 skipped",
+    };
+    if (!report.completed || lines.lines != expected){
+        return "Unexpected log:" + lines.all();
+    }
+    if (world.trace != std::vector<std::string>{"walk", "talk", "save"}){
+        return "Events ran out of order.";
+    }
+    return true;
+}
+
+UnitTestResult test_skips_done_event(){
+    World world;
+    world.potions = 10;
+    Checkpoint checkpoint = make_checkpoint();
+    checkpoint.events.push_back(talk_to_lady(world));
+    RunState state;
+    Lines lines;
+    EventLogger log = lines.logger();
+    const CheckpointReport report = run_checkpoint(state, checkpoint, log);
+    if (!report.completed || report.events_skipped != 1 || report.events_run != 0){
+        return "Expected the event skipped.";
+    }
+    if (!world.trace.empty() || !lines.has("[Event] 00.04/1 talk_poke_mart_lady: skipped")){
+        return "The skipped event should not act:" + lines.all();
+    }
+    return true;
+}
+
+UnitTestResult test_expect_failure_waited_out(){
+    World world;
+    world.talks_before_answer = 2;
+    Checkpoint checkpoint = make_checkpoint();
+    checkpoint.events.push_back(talk_to_lady(world));
+    checkpoint.events.back().recoveries.push_back(recovery("expect_failed", RecoveryKind::WAIT, 2));
+    RunState state;
+    Lines lines;
+    EventLogger log = lines.logger();
+    const CheckpointReport report = run_checkpoint(state, checkpoint, log);
+    if (!report.completed || world.trace.size() != 3 || world.potions != 10){
+        return "Expected three talks, the last answered:" + lines.all();
+    }
+    if (!lines.has("[Event] 00.04/1 talk_poke_mart_lady: recover: wait (expect_failed)")){
+        return "Expected the wait logged:" + lines.all();
+    }
+    return true;
+}
+
+//  Mom: a talk from the wrong row reaches nobody. Waiting does not help;
+//  confirming the row on a landmark does.
+Event talk_to_mom(World& world){
+    Event event = make_event("talk_mom", [&world](RunState&){
+        world.trace.push_back("talk");
+        world.dialogue_open = world.rows_off == 0;
+        return outcome_ok();
+    });
+    event.expect.push_back(dialogue_opened(world));
+    event.recoveries.push_back(recovery("expect_failed", RecoveryKind::WAIT, 1, record(world, "wait")));
+    event.recoveries.push_back(recovery("expect_failed", RecoveryKind::REANCHOR, 1, [&world](RunState& state){
+        world.trace.push_back("anchor");
+        world.rows_off = 0;
+        state.pose.certainty = PoseCertainty::TILE;
+        return outcome_ok();
+    }));
+    event.recoveries.push_back(recovery("", RecoveryKind::STOP, 0));
+    event.recoveries.back().why = "four rows cover the mat to the TV";
+    return event;
+}
+
+UnitTestResult test_escalates_to_reanchor(){
+    World world;
+    world.rows_off = 1;
+    Checkpoint checkpoint = make_checkpoint();
+    checkpoint.events.push_back(talk_to_mom(world));
+    RunState state;
+    Lines lines;
+    EventLogger log = lines.logger();
+    const CheckpointReport report = run_checkpoint(state, checkpoint, log);
+    const std::vector<std::string> expected = {"talk", "wait", "talk", "anchor", "talk"};
+    if (!report.completed || world.trace != expected){
+        return "Expected wait, then re-anchor:" + lines.all();
+    }
+    if (state.pose.certainty != PoseCertainty::TILE){
+        return "The re-anchor should have fixed the pose.";
+    }
+    return true;
+}
+
+UnitTestResult test_stop_names_failed_event(){
+    World world;
+    world.rows_off = 1;
+    Checkpoint checkpoint = make_checkpoint();
+    checkpoint.events.push_back(make_event("enter_home", record(world, "enter")));
+    checkpoint.events.push_back(talk_to_mom(world));
+    checkpoint.events.back().recoveries[1].prepare = record(world, "anchor");     //  An anchor that does not help.
+    checkpoint.events.push_back(make_event("mom_dialogue", record(world, "dialogue")));
+    RunState state;
+    Lines lines;
+    EventLogger log = lines.logger();
+    const CheckpointReport report = run_checkpoint(state, checkpoint, log);
+    if (report.completed || report.failed_event != 2 || report.failed_name != "talk_mom"){
+        return "Expected event 2 reported:" + lines.all();
+    }
+    if (report.failure.failure != "expect_failed" || report.failure.detail != "dialogue opened"){
+        return "Expected the failing expect reported.";
+    }
+    if (std::count(world.trace.begin(), world.trace.end(), "dialogue") != 0){
+        return "Nothing after the failed event should run.";
+    }
+    if (!lines.has("[Event] 00.04/2 talk_mom: recover: stop (expect_failed): four rows cover the mat to the TV")
+        || lines.lines.back() != "[Checkpoint] 00.04: failed at 2 talk_mom: expect_failed: dialogue opened"
+    ){
+        return "Unexpected log:" + lines.all();
+    }
+    return true;
+}
+
+UnitTestResult test_unmatched_failure_stops(){
+    World world;
+    Checkpoint checkpoint = make_checkpoint();
+    checkpoint.events.push_back(make_event("probe_for_mom", [&world](RunState&){
+        world.trace.push_back("probe");
+        return outcome_failed("probe_exhausted", "4 rows");
+    }));
+    checkpoint.events.back().recoveries.push_back(recovery("blocked", RecoveryKind::WAIT, 3));
+    RunState state;
+    Lines lines;
+    EventLogger log = lines.logger();
+    const CheckpointReport report = run_checkpoint(state, checkpoint, log);
+    if (report.completed || report.failure.failure != "probe_exhausted" || world.trace.size() != 1){
+        return "A failure no recovery names should stop at once:" + lines.all();
+    }
+    if (!lines.has("[Event] 00.04/1 probe_for_mom: failed: probe_exhausted: 4 rows")){
+        return "Unexpected log:" + lines.all();
+    }
+    return true;
+}
+
+Interrupt wild_battle(World& world, ResumePolicy resume){
+    Interrupt interrupt;
+    interrupt.name = "wild_battle";
+    interrupt.detect = [&world](RunState&){ return world.battle_showing; };
+    interrupt.handle = [&world](RunState&){
+        world.trace.push_back("flee");
+        world.battle_showing = false;
+        return outcome_ok();
+    };
+    interrupt.pose = InterruptPose::INEXACT;
+    interrupt.resume = resume;
+    return interrupt;
+}
+
+//  A walk through grass: the first try meets a wild battle half-way.
+Event walk_through_grass(World& world){
+    Event event = make_event("walk_to_corner", [&world](RunState&){
+        world.trace.push_back("walk");
+        if (world.walk_failures > 0){
+            world.walk_failures--;
+            world.battle_showing = true;
+            return outcome_failed("walk_stopped");
+        }
+        world.map = "Route 201";
+        return outcome_ok();
+    });
+    event.require.push_back(pose_known("Route 202", PoseCertainty::TILE));
+    event.expect.push_back(condition("on Route 201", [&world](RunState&){ return world.map == "Route 201"; }));
+    Pose corner;
+    corner.map = "Route 201";
+    corner.tiles = {TilePos{42, 3}};
+    corner.certainty = PoseCertainty::TILE;
+    event.pose_learned = corner;
+    event.recoveries.push_back(recovery("require_failed", RecoveryKind::REANCHOR, 1, [&world](RunState& state){
+        world.trace.push_back("anchor");
+        state.pose.certainty = PoseCertainty::TILE;
+        return outcome_ok();
+    }));
+    return event;
+}
+
+RunState at_catch_spot(){
+    RunState state;
+    state.pose.map = "Route 202";
+    state.pose.tiles = {TilePos{10, 20}};
+    state.pose.certainty = PoseCertainty::TILE;
+    return state;
+}
+
+UnitTestResult test_interrupt_mid_event(){
+    World world;
+    world.walk_failures = 1;
+    Checkpoint checkpoint = make_checkpoint();
+    checkpoint.interrupts.push_back(wild_battle(world, ResumePolicy::RETRY_EVENT));
+    checkpoint.events.push_back(walk_through_grass(world));
+    RunState state = at_catch_spot();
+    Lines lines;
+    EventLogger log = lines.logger();
+    const CheckpointReport report = run_checkpoint(state, checkpoint, log);
+    //  The battle leaves the pose inexact, so the retry first re-anchors.
+    const std::vector<std::string> expected = {"walk", "flee", "anchor", "walk"};
+    if (!report.completed || world.trace != expected){
+        return "Expected flee, re-anchor, walk again:" + lines.all();
+    }
+    if (!lines.has("[Event] 00.04/1 walk_to_corner: interrupt: wild_battle")){
+        return "Expected the interrupt logged:" + lines.all();
+    }
+    if (state.pose.map != "Route 201" || state.pose.tiles.size() != 1 || state.pose.tiles[0] != TilePos{42, 3}){
+        return "Expected the learned pose: " + to_string(state.pose);
+    }
+    return true;
+}
+
+UnitTestResult test_interrupt_recheck_expect(){
+    World world;
+    Checkpoint checkpoint = make_checkpoint();
+    Interrupt interrupt = wild_battle(world, ResumePolicy::RECHECK_EXPECT);
+    interrupt.pose = InterruptPose::UNCHANGED;
+    checkpoint.interrupts.push_back(std::move(interrupt));
+    //  A talk-only trainer stops us on the last step: we arrived anyway.
+    checkpoint.events.push_back(make_event("walk_to_exit", [&world](RunState&){
+        world.trace.push_back("walk");
+        world.map = "Route 201";
+        world.battle_showing = true;
+        return outcome_failed("walk_stopped");
+    }));
+    checkpoint.events.back().expect.push_back(condition("on Route 201", [&world](RunState&){ return world.map == "Route 201"; }));
+    RunState state;
+    Lines lines;
+    EventLogger log = lines.logger();
+    const CheckpointReport report = run_checkpoint(state, checkpoint, log);
+    if (!report.completed || world.trace != std::vector<std::string>{"walk", "flee"}){
+        return "Expected done without walking again:" + lines.all();
+    }
+    return true;
+}
+
+UnitTestResult test_too_many_interrupts(){
+    World world;
+    Checkpoint checkpoint = make_checkpoint();
+    checkpoint.max_interrupts_per_event = 2;
+    checkpoint.interrupts.push_back(wild_battle(world, ResumePolicy::RETRY_EVENT));
+    checkpoint.events.push_back(make_event("walk", [&world](RunState&){
+        world.battle_showing = true;
+        return outcome_failed("walk_stopped");
+    }));
+    RunState state;
+    Lines lines;
+    EventLogger log = lines.logger();
+    const CheckpointReport report = run_checkpoint(state, checkpoint, log);
+    if (report.completed || report.failure.failure != "too_many_interrupts"){
+        return "Expected to give up after 2 interrupts:" + lines.all();
+    }
+    return true;
+}
+
+
+//  00.04 after the catch, shortened: Potions, save, then a walk north that
+//  fails on the first run. The reload restores the world as saved.
+Checkpoint post_catch(World& world, World& saved){
+    Checkpoint checkpoint = make_checkpoint();
+    checkpoint.events.push_back(talk_to_lady(world));
+    Event save = make_event("save_on_202", [&world, &saved](RunState&){
+        world.trace.push_back("save");
+        world.map = "Route 202";
+        saved = world;
+        return outcome_ok();
+    });
+    save.skip_if.push_back(has_potions(world));
+    save.skip_if.push_back(condition("on Route 202", [&world](RunState&){ return world.map == "Route 202"; }));
+    checkpoint.events.push_back(std::move(save));
+    checkpoint.events.push_back(make_event("train", record(world, "train")));
+    checkpoint.events.push_back(make_event("walk_north", [&world](RunState&){
+        world.trace.push_back("walk");
+        if (world.walk_failures > 0){
+            world.walk_failures--;
+            return outcome_failed("blocked_unexplained");
+        }
+        world.map = "Jubilife City";
+        return outcome_ok();
+    }));
+    checkpoint.end.push_back(condition("in Jubilife", [&world](RunState&){ return world.map == "Jubilife City"; }));
+    return checkpoint;
+}
+
+UnitTestResult test_resume_after_reload(){
+    World world;
+    world.map = "Route 201";
+    world.walk_failures = 1;
+    World saved;
+    Checkpoint checkpoint = post_catch(world, saved);
+    RunState state;
+    Lines lines;
+    EventLogger log = lines.logger();
+    const CheckpointReport first = run_checkpoint(state, checkpoint, log);
+    if (first.completed || first.failed_event != 4){
+        return "Expected the first run to fail at the walk:" + lines.all();
+    }
+    world = saved;      //  Reload: the save has the Potions and stands on Route 202.
+    world.walk_failures = 0;    //  Whatever blocked the walk has moved on.
+    world.trace.clear();
+    RunState reloaded;
+    const CheckpointReport second = run_checkpoint(reloaded, checkpoint, log);
+    if (!second.completed || second.events_skipped != 2 || second.events_run != 2){
+        return "Expected the Potions and the save skipped:" + lines.all();
+    }
+    if (world.trace != std::vector<std::string>{"train", "walk"} || world.potions != 10){
+        return "Expected only the training and the walk again.";
+    }
+    return true;
+}
+
+UnitTestResult test_start_end_and_save(){
+    World world;
+    Checkpoint checkpoint = make_checkpoint();
+    checkpoint.start.push_back(has_potions(world));
+    checkpoint.events.push_back(make_event("walk", record(world, "walk")));
+    checkpoint.end.push_back(condition("parcel in the Bag", [&world](RunState&){ return world.parcel; }));
+    checkpoint.save = record(world, "save");
+    RunState state;
+    Lines lines;
+    EventLogger log = lines.logger();
+    CheckpointReport report = run_checkpoint(state, checkpoint, log);
+    if (report.completed || report.failure.failure != "start_failed" || !world.trace.empty()){
+        return "Expected the start check to stop before any event.";
+    }
+    world.potions = 1;
+    report = run_checkpoint(state, checkpoint, log);
+    if (report.completed || report.failure.failure != "end_failed" || world.trace.size() != 1){
+        return "Expected the end check to fail without a save.";
+    }
+    world.parcel = true;
+    report = run_checkpoint(state, checkpoint, log);
+    if (!report.completed || world.trace.back() != "save"){
+        return "Expected a save after the end check.";
+    }
+    return true;
+}
+
+UnitTestResult test_pose_certainty(){
+    if (!certainty_covers(PoseCertainty::TILE, PoseCertainty::COLUMN)
+        || certainty_covers(PoseCertainty::ROW, PoseCertainty::COLUMN)
+        || certainty_covers(PoseCertainty::SET, PoseCertainty::ROW)
+        || !certainty_covers(PoseCertainty::SET, PoseCertainty::SET)
+        || certainty_covers(PoseCertainty::UNKNOWN, PoseCertainty::SET)
+        || !certainty_covers(PoseCertainty::UNKNOWN, PoseCertainty::UNKNOWN)
+    ){
+        return "Wrong certainty order.";
+    }
+    RunState state = at_catch_spot();
+    state.pose.facing = Direction::NORTH;
+    if (to_string(state.pose) != "Route 202 (10, 20) facing north (tile)"){
+        return "Unexpected pose text: " + to_string(state.pose);
+    }
+    Condition known = pose_known("Route 201", PoseCertainty::SET);
+    if (known.check(state)){
+        return "The pose is on another map.";
+    }
+    return true;
+}
+
+UnitTestResult test_lint(){
+    World world;
+    Checkpoint checkpoint = make_checkpoint();
+    checkpoint.events.push_back(talk_to_mom(world));
+    if (!lint_checkpoint(checkpoint).empty()){
+        return "A good checkpoint should lint clean.";
+    }
+    checkpoint.events.push_back(make_event("talk_mom", nullptr));
+    checkpoint.events.back().recoveries.push_back(recovery("", RecoveryKind::STOP, 0));
+    checkpoint.events.back().recoveries.push_back(recovery("", RecoveryKind::WAIT, 0));
+    const std::vector<std::string> problems = lint_checkpoint(checkpoint);
+    //  Duplicate name, no action, wait after stop, wait with no attempts.
+    if (problems.size() != 4){
+        std::string text;
+        for (const std::string& problem : problems){
+            text += "\n" + problem;
+        }
+        return "Expected 4 problems:" + text;
+    }
+    return true;
+}
+
+
+class Test_StoryEvents : public UnitTest{
+public:
+    Test_StoryEvents(std::string name, std::function<UnitTestResult()> body)
+        : UnitTest("Pokemon::StoryEvents - " + std::move(name))
+        , m_body(std::move(body))
+    {}
+    virtual UnitTestResult run(Logger&, CancellableScope&) const override{
+        return m_body();
+    }
+
+private:
+    std::function<UnitTestResult()> m_body;
+};
+
+}
+
+
+void add_tests_StoryEvents(UnitTestDatabase& database){
+    database.add<Test_StoryEvents>("events run in order", test_runs_events_in_order);
+    database.add<Test_StoryEvents>("a done event is skipped", test_skips_done_event);
+    database.add<Test_StoryEvents>("a failed expect is waited out", test_expect_failure_waited_out);
+    database.add<Test_StoryEvents>("recoveries escalate to a re-anchor", test_escalates_to_reanchor);
+    database.add<Test_StoryEvents>("a stop names the failed event", test_stop_names_failed_event);
+    database.add<Test_StoryEvents>("an unanswered failure stops", test_unmatched_failure_stops);
+    database.add<Test_StoryEvents>("an interrupt mid-event", test_interrupt_mid_event);
+    database.add<Test_StoryEvents>("an interrupt rechecks the expects", test_interrupt_recheck_expect);
+    database.add<Test_StoryEvents>("too many interrupts", test_too_many_interrupts);
+    database.add<Test_StoryEvents>("resume after a reload", test_resume_after_reload);
+    database.add<Test_StoryEvents>("start, end and save", test_start_end_and_save);
+    database.add<Test_StoryEvents>("pose certainty", test_pose_certainty);
+    database.add<Test_StoryEvents>("lint", test_lint);
+}
+
+
+
+}
+}
diff --git a/SerialPrograms/cmake/SourceFiles.cmake b/SerialPrograms/cmake/SourceFiles.cmake
index 9aceebcaed..b8208f48d2 100644
--- a/SerialPrograms/cmake/SourceFiles.cmake
+++ b/SerialPrograms/cmake/SourceFiles.cmake
@@ -1447,6 +1447,9 @@ file(GLOB LIBRARY_SOURCES
     Source/Pokemon/Navigation/Pokemon_LegPlanner.h
     Source/Pokemon/Navigation/Pokemon_LegPlanner_Tests.cpp
     Source/Pokemon/Navigation/Pokemon_Navigation_Tests.h
+    Source/Pokemon/Navigation/Pokemon_StoryEvents.cpp
+    Source/Pokemon/Navigation/Pokemon_StoryEvents.h
+    Source/Pokemon/Navigation/Pokemon_StoryEvents_Tests.cpp
     Source/Pokemon/Options/Pokemon_BoxSortingTable.cpp
     Source/Pokemon/Options/Pokemon_BoxSortingTable.h
     Source/Pokemon/Options/Pokemon_EncounterBotOptions.h

From 19a0303744a7e7693e991038450946ad8602bcf9 Mon Sep 17 00:00:00 2001
From: dayfine <difancpa@gmail.com>
Date: Sat, 31 Oct 2026 23:23:58 -0700
Subject: [PATCH 05/19] Pokemon navigation: story events take a game-defined
 position

Scarlet/Violet will run story checkpoints on map points and fly points, so
the engine's Pose can no longer be tiles and a facing. The engine now keeps
only the map, the certainty and an opaque Position the game supplies and the
engine only prints; the tile pose moves to Pokemon_TilePose.h for the 2D
games, and InterruptPose::INEXACT becomes WITHIN_SET. No behavior change:
the log text for a tile pose is the same as before.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01AKYzhrMnPK61XHWEch4a6E
---
 .../Navigation/Pokemon_StoryEvents.cpp        | 15 ++--
 .../Pokemon/Navigation/Pokemon_StoryEvents.h  | 23 ++++--
 .../Navigation/Pokemon_StoryEvents_Tests.cpp  | 79 +++++++++++++++++--
 .../Pokemon/Navigation/Pokemon_TilePose.cpp   | 38 +++++++++
 .../Pokemon/Navigation/Pokemon_TilePose.h     | 42 ++++++++++
 SerialPrograms/cmake/SourceFiles.cmake        |  2 +
 6 files changed, 178 insertions(+), 21 deletions(-)
 create mode 100644 SerialPrograms/Source/Pokemon/Navigation/Pokemon_TilePose.cpp
 create mode 100644 SerialPrograms/Source/Pokemon/Navigation/Pokemon_TilePose.h

diff --git a/SerialPrograms/Source/Pokemon/Navigation/Pokemon_StoryEvents.cpp b/SerialPrograms/Source/Pokemon/Navigation/Pokemon_StoryEvents.cpp
index 2d3448a679..2a9cceb345 100644
--- a/SerialPrograms/Source/Pokemon/Navigation/Pokemon_StoryEvents.cpp
+++ b/SerialPrograms/Source/Pokemon/Navigation/Pokemon_StoryEvents.cpp
@@ -45,11 +45,11 @@ bool certainty_covers(PoseCertainty have, PoseCertainty need){
 
 std::string to_string(const Pose& pose){
     std::string text = pose.map.empty() ? "?" : pose.map;
-    for (const TilePos& tile : pose.tiles){
-        text += " " + to_string(tile);
-    }
-    if (pose.facing){
-        text += std::string(" facing ") + direction_name(*pose.facing);
+    if (pose.where){
+        const std::string where = pose.where->describe();
+        if (!where.empty()){
+            text += " " + where;
+        }
     }
     return text + " (" + certainty_name(pose.certainty) + ")";
 }
@@ -141,14 +141,13 @@ void apply_interrupt_pose(Pose& pose, InterruptPose effect){
     switch (effect){
     case InterruptPose::UNCHANGED:
         return;
-    case InterruptPose::INEXACT:
+    case InterruptPose::WITHIN_SET:
         if (pose.certainty != PoseCertainty::UNKNOWN){
             pose.certainty = PoseCertainty::SET;
         }
         return;
     case InterruptPose::LOST:
-        pose.tiles.clear();
-        pose.facing.reset();
+        pose.where.reset();
         pose.certainty = PoseCertainty::UNKNOWN;
         return;
     }
diff --git a/SerialPrograms/Source/Pokemon/Navigation/Pokemon_StoryEvents.h b/SerialPrograms/Source/Pokemon/Navigation/Pokemon_StoryEvents.h
index c70f2f72f2..92540d41c3 100644
--- a/SerialPrograms/Source/Pokemon/Navigation/Pokemon_StoryEvents.h
+++ b/SerialPrograms/Source/Pokemon/Navigation/Pokemon_StoryEvents.h
@@ -24,19 +24,19 @@
 #define PokemonAutomation_Pokemon_StoryEvents_H
 
 #include <cstddef>
+#include <memory>
 #include <optional>
 #include <set>
 #include <string>
 #include <vector>
 #include "Common/Cpp/MoveOnlyFunction.h"
-#include "Pokemon_Grid.h"
 
 namespace PokemonAutomation{
 namespace Pokemon{
 
 
 //  How much of the pose is known. COLUMN and ROW pin one axis (a wall, a
-//  door); SET means one of `tiles`.
+//  door); SET means one of the positions the pose holds.
 enum class PoseCertainty{
     TILE,
     COLUMN,
@@ -49,14 +49,25 @@ const char* certainty_name(PoseCertainty certainty);
 //  Whether a pose known to `have` is good enough for an event that needs `need`.
 bool certainty_covers(PoseCertainty have, PoseCertainty need);
 
+//  Where on a map the player is, in the game's own terms: tiles and a
+//  facing in a 2D game (Pokemon_TilePose.h), a map point or a fly point in
+//  an open-world one. The engine only carries and prints it; the game's
+//  actions read it back.
+struct Position{
+    virtual ~Position() = default;
+    //  The text after the map in a log line, e.g. "(10, 20) facing north".
+    virtual std::string describe() const = 0;
+};
+
 //  Where the player is believed to be. The screen is read; the pose is
 //  tracked, and only an anchor (a wall, a door, an NPC who answered) makes
-//  it certain.
+//  it certain. `where` is null until the game learns a position and after
+//  the pose is lost; it is shared because poses are copied (an event's
+//  learned pose into the run) and never changed in place.
 struct Pose{
     std::string map;
-    std::vector<TilePos> tiles;
-    std::optional<Direction> facing;
     PoseCertainty certainty = PoseCertainty::UNKNOWN;
+    std::shared_ptr<const Position> where;
 };
 std::string to_string(const Pose& pose);
 
@@ -134,7 +145,7 @@ struct Event{
 
 enum class InterruptPose{
     UNCHANGED,  //  Cleared where we stood (a talk-only trainer).
-    INEXACT,    //  Moved an unknown part of a leg: one of the tiles we had.
+    WITHIN_SET, //  Moved an unknown part of a leg: still within the position we had, no longer exactly where.
     LOST,       //  Anywhere.
 };
 enum class ResumePolicy{
diff --git a/SerialPrograms/Source/Pokemon/Navigation/Pokemon_StoryEvents_Tests.cpp b/SerialPrograms/Source/Pokemon/Navigation/Pokemon_StoryEvents_Tests.cpp
index 433065884f..fde6e83001 100644
--- a/SerialPrograms/Source/Pokemon/Navigation/Pokemon_StoryEvents_Tests.cpp
+++ b/SerialPrograms/Source/Pokemon/Navigation/Pokemon_StoryEvents_Tests.cpp
@@ -8,12 +8,15 @@
  */
 
 #include <algorithm>
+#include <format>
 #include <functional>
+#include <memory>
 #include <string>
 #include <utility>
 #include <vector>
 #include "Common/Cpp/TestRunners/UnitTest.h"
 #include "Pokemon_StoryEvents.h"
+#include "Pokemon_TilePose.h"
 #include "Pokemon_Navigation_Tests.h"
 
 namespace PokemonAutomation{
@@ -276,7 +279,7 @@ Interrupt wild_battle(World& world, ResumePolicy resume){
         world.battle_showing = false;
         return outcome_ok();
     };
-    interrupt.pose = InterruptPose::INEXACT;
+    interrupt.pose = InterruptPose::WITHIN_SET;
     interrupt.resume = resume;
     return interrupt;
 }
@@ -297,8 +300,8 @@ Event walk_through_grass(World& world){
     event.expect.push_back(condition("on Route 201", [&world](RunState&){ return world.map == "Route 201"; }));
     Pose corner;
     corner.map = "Route 201";
-    corner.tiles = {TilePos{42, 3}};
     corner.certainty = PoseCertainty::TILE;
+    corner.where = std::make_shared<const TilePose>(std::vector<TilePos>{TilePos{42, 3}});
     event.pose_learned = corner;
     event.recoveries.push_back(recovery("require_failed", RecoveryKind::REANCHOR, 1, [&world](RunState& state){
         world.trace.push_back("anchor");
@@ -308,11 +311,11 @@ Event walk_through_grass(World& world){
     return event;
 }
 
-RunState at_catch_spot(){
+RunState at_catch_spot(std::optional<Direction> facing = std::nullopt){
     RunState state;
     state.pose.map = "Route 202";
-    state.pose.tiles = {TilePos{10, 20}};
     state.pose.certainty = PoseCertainty::TILE;
+    state.pose.where = std::make_shared<const TilePose>(std::vector<TilePos>{TilePos{10, 20}}, facing);
     return state;
 }
 
@@ -334,7 +337,7 @@ UnitTestResult test_interrupt_mid_event(){
     if (!lines.has("[Event] 00.04/1 walk_to_corner: interrupt: wild_battle")){
         return "Expected the interrupt logged:" + lines.all();
     }
-    if (state.pose.map != "Route 201" || state.pose.tiles.size() != 1 || state.pose.tiles[0] != TilePos{42, 3}){
+    if (state.pose.map != "Route 201" || tiles_of(state.pose) != std::vector<TilePos>{TilePos{42, 3}}){
         return "Expected the learned pose: " + to_string(state.pose);
     }
     return true;
@@ -476,8 +479,7 @@ UnitTestResult test_pose_certainty(){
     ){
         return "Wrong certainty order.";
     }
-    RunState state = at_catch_spot();
-    state.pose.facing = Direction::NORTH;
+    RunState state = at_catch_spot(Direction::NORTH);
     if (to_string(state.pose) != "Route 202 (10, 20) facing north (tile)"){
         return "Unexpected pose text: " + to_string(state.pose);
     }
@@ -488,6 +490,68 @@ UnitTestResult test_pose_certainty(){
     return true;
 }
 
+//  A game without tiles: a point on its map, as Scarlet/Violet would give.
+struct PointPose : public Position{
+    int x = 0;
+    int y = 0;
+
+    PointPose(int x, int y) : x(x), y(y){}
+    virtual std::string describe() const override{
+        return std::format("({}, {})", x, y);
+    }
+};
+
+Pose at_point(std::string map, int x, int y){
+    Pose pose;
+    pose.map = std::move(map);
+    pose.certainty = PoseCertainty::TILE;
+    pose.where = std::make_shared<const PointPose>(x, y);
+    return pose;
+}
+
+//  The engine carries whatever position the game gives it: a battle leaves
+//  it within the set, a lost pose drops it, a learned pose replaces it.
+UnitTestResult test_position_is_the_games(){
+    World world;
+    world.walk_failures = 1;
+    Checkpoint checkpoint = make_checkpoint();
+    checkpoint.interrupts.push_back(wild_battle(world, ResumePolicy::RETRY_EVENT));
+    Event ride = make_event("ride_to_mesagoza", [&world](RunState&){
+        world.trace.push_back("ride");
+        if (world.walk_failures > 0){
+            world.walk_failures--;
+            world.battle_showing = true;
+            return outcome_failed("walk_stopped");
+        }
+        return outcome_ok();
+    });
+    ride.require.push_back(pose_known("South Province", PoseCertainty::SET));
+    ride.pose_learned = at_point("Mesagoza", 7, 8);
+    checkpoint.events.push_back(std::move(ride));
+    RunState state;
+    state.pose = at_point("South Province", 3, 4);
+    Lines lines;
+    EventLogger log = lines.logger();
+    const CheckpointReport report = run_checkpoint(state, checkpoint, log);
+    if (!report.completed || world.trace != std::vector<std::string>{"ride", "flee", "ride"}){
+        return "Expected the ride retried after the battle:" + lines.all();
+    }
+    if (to_string(state.pose) != "Mesagoza (7, 8) (tile)"){
+        return "Expected the learned point: " + to_string(state.pose);
+    }
+    Interrupt lost = wild_battle(world, ResumePolicy::RETRY_EVENT);
+    lost.pose = InterruptPose::LOST;
+    checkpoint.interrupts[0] = std::move(lost);
+    world.walk_failures = 1;
+    checkpoint.events[0].pose_learned.reset();
+    checkpoint.events[0].require.clear();
+    run_checkpoint(state, checkpoint, log);
+    if (state.pose.where || to_string(state.pose) != "Mesagoza (unknown)"){
+        return "Expected the lost pose to drop its position: " + to_string(state.pose);
+    }
+    return true;
+}
+
 UnitTestResult test_lint(){
     World world;
     Checkpoint checkpoint = make_checkpoint();
@@ -541,6 +605,7 @@ void add_tests_StoryEvents(UnitTestDatabase& database){
     database.add<Test_StoryEvents>("resume after a reload", test_resume_after_reload);
     database.add<Test_StoryEvents>("start, end and save", test_start_end_and_save);
     database.add<Test_StoryEvents>("pose certainty", test_pose_certainty);
+    database.add<Test_StoryEvents>("the position is the game's", test_position_is_the_games);
     database.add<Test_StoryEvents>("lint", test_lint);
 }
 
diff --git a/SerialPrograms/Source/Pokemon/Navigation/Pokemon_TilePose.cpp b/SerialPrograms/Source/Pokemon/Navigation/Pokemon_TilePose.cpp
new file mode 100644
index 0000000000..78bd0ef666
--- /dev/null
+++ b/SerialPrograms/Source/Pokemon/Navigation/Pokemon_TilePose.cpp
@@ -0,0 +1,38 @@
+/*  Tile Pose
+ *
+ *  From: https://github.com/PokemonAutomation/
+ *
+ */
+
+#include <utility>
+#include "Pokemon_TilePose.h"
+
+namespace PokemonAutomation{
+namespace Pokemon{
+
+
+TilePose::TilePose(std::vector<TilePos> tiles, std::optional<Direction> facing)
+    : tiles(std::move(tiles))
+    , facing(facing)
+{}
+
+std::string TilePose::describe() const{
+    std::string text;
+    for (const TilePos& tile : tiles){
+        text += (text.empty() ? "" : " ") + to_string(tile);
+    }
+    if (facing){
+        text += (text.empty() ? "facing " : " facing ") + std::string(direction_name(*facing));
+    }
+    return text;
+}
+
+std::vector<TilePos> tiles_of(const Pose& pose){
+    const TilePose* tile_pose = dynamic_cast<const TilePose*>(pose.where.get());
+    return tile_pose ? tile_pose->tiles : std::vector<TilePos>{};
+}
+
+
+
+}
+}
diff --git a/SerialPrograms/Source/Pokemon/Navigation/Pokemon_TilePose.h b/SerialPrograms/Source/Pokemon/Navigation/Pokemon_TilePose.h
new file mode 100644
index 0000000000..34f0d18adc
--- /dev/null
+++ b/SerialPrograms/Source/Pokemon/Navigation/Pokemon_TilePose.h
@@ -0,0 +1,42 @@
+/*  Tile Pose
+ *
+ *  From: https://github.com/PokemonAutomation/
+ *
+ *  The position a 2D tile game (BDSP, FRLG) gives the story-event engine:
+ *  the tiles the player may stand on and the way they face. The engine
+ *  (Pokemon_StoryEvents.h) does not know tiles; games include this header.
+ *
+ */
+
+#ifndef PokemonAutomation_Pokemon_TilePose_H
+#define PokemonAutomation_Pokemon_TilePose_H
+
+#include <optional>
+#include <string>
+#include <vector>
+#include "Pokemon_Grid.h"
+#include "Pokemon_StoryEvents.h"
+
+namespace PokemonAutomation{
+namespace Pokemon{
+
+
+//  One of `tiles`, facing `facing` if known.
+struct TilePose : public Position{
+    std::vector<TilePos> tiles;
+    std::optional<Direction> facing;
+
+    explicit TilePose(std::vector<TilePos> tiles, std::optional<Direction> facing = std::nullopt);
+    //  "(10, 20) facing north": the tiles, then the facing, each after a space.
+    virtual std::string describe() const override;
+};
+
+//  The tiles of a pose: empty when the pose holds no position, or one that
+//  is not a tile pose.
+std::vector<TilePos> tiles_of(const Pose& pose);
+
+
+
+}
+}
+#endif
diff --git a/SerialPrograms/cmake/SourceFiles.cmake b/SerialPrograms/cmake/SourceFiles.cmake
index b8208f48d2..b2d5fa2d64 100644
--- a/SerialPrograms/cmake/SourceFiles.cmake
+++ b/SerialPrograms/cmake/SourceFiles.cmake
@@ -1450,6 +1450,8 @@ file(GLOB LIBRARY_SOURCES
     Source/Pokemon/Navigation/Pokemon_StoryEvents.cpp
     Source/Pokemon/Navigation/Pokemon_StoryEvents.h
     Source/Pokemon/Navigation/Pokemon_StoryEvents_Tests.cpp
+    Source/Pokemon/Navigation/Pokemon_TilePose.cpp
+    Source/Pokemon/Navigation/Pokemon_TilePose.h
     Source/Pokemon/Options/Pokemon_BoxSortingTable.cpp
     Source/Pokemon/Options/Pokemon_BoxSortingTable.h
     Source/Pokemon/Options/Pokemon_EncounterBotOptions.h

From 6549f9810625d5894df9260814741779f99cdfc0 Mon Sep 17 00:00:00 2001
From: dayfine <difancpa@gmail.com>
Date: Sun, 1 Nov 2026 00:12:37 -0700
Subject: [PATCH 06/19] Pokemon navigation: a segment is a table of event
 checkpoints

A story segment is now a Segment: rows of CheckpointSpec, each with an id,
a title, whether the segment saves after it, and a factory that builds the
checkpoint fresh for every attempt. run_segment() runs a range of rows in
order through SegmentHooks (save, reload, log); a failed checkpoint is
reloaded, rebuilt and run again up to SegmentPolicy's attempts, then the
report names the checkpoint, the event and the reason. Actions no longer
write the run's pose: a succeeded Outcome carries the pose and the runner
writes it before the expects. describe() dumps a checkpoint or a segment as
text for review, covered by a golden-string test.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01AKYzhrMnPK61XHWEch4a6E
---
 .../ComputerPrograms_UnitTestRunner.cpp       |   1 +
 .../Navigation/Pokemon_Navigation_Tests.h     |   1 +
 .../Navigation/Pokemon_StoryEvents.cpp        |  96 +++++-
 .../Pokemon/Navigation/Pokemon_StoryEvents.h  |  20 +-
 .../Navigation/Pokemon_StoryEvents_Tests.cpp  |  45 ++-
 .../Navigation/Pokemon_StorySegments.cpp      | 173 ++++++++++
 .../Navigation/Pokemon_StorySegments.h        |  99 ++++++
 .../Pokemon_StorySegments_Tests.cpp           | 314 ++++++++++++++++++
 SerialPrograms/cmake/SourceFiles.cmake        |   3 +
 9 files changed, 735 insertions(+), 17 deletions(-)
 create mode 100644 SerialPrograms/Source/Pokemon/Navigation/Pokemon_StorySegments.cpp
 create mode 100644 SerialPrograms/Source/Pokemon/Navigation/Pokemon_StorySegments.h
 create mode 100644 SerialPrograms/Source/Pokemon/Navigation/Pokemon_StorySegments_Tests.cpp

diff --git a/SerialPrograms/Source/ComputerPrograms/ComputerPrograms_UnitTestRunner.cpp b/SerialPrograms/Source/ComputerPrograms/ComputerPrograms_UnitTestRunner.cpp
index 2607f8d0ad..b0253c967e 100644
--- a/SerialPrograms/Source/ComputerPrograms/ComputerPrograms_UnitTestRunner.cpp
+++ b/SerialPrograms/Source/ComputerPrograms/ComputerPrograms_UnitTestRunner.cpp
@@ -63,6 +63,7 @@ UnitTestDatabase make_UNIT_TESTS_ALL(){
     Kernels::add_tests(ret);
     Pokemon::add_tests_LegPlanner(ret);
     Pokemon::add_tests_StoryEvents(ret);
+    Pokemon::add_tests_StorySegments(ret);
     NintendoSwitch::add_tests_CheckOnlineDetector(ret);
     NintendoSwitch::add_tests_FailedToConnectDetector(ret);
     NintendoSwitch::add_tests_UpdatePopupDetector(ret);
diff --git a/SerialPrograms/Source/Pokemon/Navigation/Pokemon_Navigation_Tests.h b/SerialPrograms/Source/Pokemon/Navigation/Pokemon_Navigation_Tests.h
index e6d709afce..c8f2b4cefc 100644
--- a/SerialPrograms/Source/Pokemon/Navigation/Pokemon_Navigation_Tests.h
+++ b/SerialPrograms/Source/Pokemon/Navigation/Pokemon_Navigation_Tests.h
@@ -15,6 +15,7 @@ namespace Pokemon{
 
 void add_tests_LegPlanner(UnitTestDatabase& database);
 void add_tests_StoryEvents(UnitTestDatabase& database);
+void add_tests_StorySegments(UnitTestDatabase& database);
 
 
 
diff --git a/SerialPrograms/Source/Pokemon/Navigation/Pokemon_StoryEvents.cpp b/SerialPrograms/Source/Pokemon/Navigation/Pokemon_StoryEvents.cpp
index 2a9cceb345..1f3abf5007 100644
--- a/SerialPrograms/Source/Pokemon/Navigation/Pokemon_StoryEvents.cpp
+++ b/SerialPrograms/Source/Pokemon/Navigation/Pokemon_StoryEvents.cpp
@@ -61,8 +61,19 @@ bool Outcome::succeeded() const{
 Outcome outcome_ok(){
     return Outcome{};
 }
+Outcome outcome_ok(Pose pose){
+    Outcome outcome;
+    outcome.pose = std::move(pose);
+    return outcome;
+}
 Outcome outcome_failed(std::string failure, std::string detail){
-    return Outcome{std::move(failure), std::move(detail)};
+    Outcome outcome;
+    outcome.failure = std::move(failure);
+    outcome.detail = std::move(detail);
+    return outcome;
+}
+std::string to_string(const Outcome& outcome){
+    return outcome.detail.empty() ? outcome.failure : outcome.failure + ": " + outcome.detail;
 }
 
 Condition condition(std::string name, Check check){
@@ -96,8 +107,14 @@ std::string event_log_line(const std::string& checkpoint, size_t number, const s
 
 namespace{
 
-std::string describe(const Outcome& outcome){
-    return outcome.detail.empty() ? outcome.failure : outcome.failure + ": " + outcome.detail;
+//  Runs an action; if it succeeded knowing where it left the player, that
+//  becomes the run's pose.
+Outcome run_act(Act& act, RunState& state){
+    Outcome outcome = act(state);
+    if (outcome.succeeded() && outcome.pose){
+        state.pose = *outcome.pose;
+    }
+    return outcome;
 }
 
 //  The name of the first condition that does not hold.
@@ -130,7 +147,7 @@ Outcome attempt_event(Event& event, RunState& state){
     if (failing){
         return outcome_failed("require_failed", *failing);
     }
-    Outcome outcome = event.act(state);
+    Outcome outcome = run_act(event.act, state);
     if (!outcome.succeeded()){
         return outcome;
     }
@@ -202,9 +219,9 @@ InterruptResult clear_interrupts(EventRun& run){
             return result;
         }
         if (interrupt.handle){
-            Outcome handled = interrupt.handle(run.state);
+            Outcome handled = run_act(interrupt.handle, run.state);
             if (!handled.succeeded()){
-                result.outcome = outcome_failed("interrupt_failed", interrupt.name + ": " + describe(handled));
+                result.outcome = outcome_failed("interrupt_failed", interrupt.name + ": " + to_string(handled));
                 return result;
             }
         }
@@ -250,7 +267,7 @@ std::optional<Outcome> recover(EventRun& run, Outcome failure){
         if (!recovery->prepare){
             return std::nullopt;
         }
-        Outcome prepared = recovery->prepare(run.state);
+        Outcome prepared = run_act(recovery->prepare, run.state);
         if (prepared.succeeded()){
             return std::nullopt;
         }
@@ -313,7 +330,7 @@ Outcome run_event(EventRun& run){
             }
             outcome = std::move(*stop);
         }
-        log_status(run, "failed: " + describe(outcome));
+        log_status(run, "failed: " + to_string(outcome));
         return outcome;
     }
 }
@@ -323,7 +340,7 @@ CheckpointReport stop_checkpoint(CheckpointReport& report, EventLogger& log, con
     std::string where = report.failed_event == 0
         ? ""
         : std::format(" at {} {}", report.failed_event, report.failed_name);
-    log(std::format("[Checkpoint] {}: failed{}: {}", id, where, describe(failure)));
+    log(std::format("[Checkpoint] {}: failed{}: {}", id, where, to_string(failure)));
     report.failure = std::move(failure);
     return report;
 }
@@ -336,8 +353,8 @@ Outcome finish_checkpoint(RunState& state, Checkpoint& checkpoint){
     if (!checkpoint.save){
         return outcome_ok();
     }
-    Outcome saved = checkpoint.save(state);
-    return saved.succeeded() ? saved : outcome_failed("save_failed", describe(saved));
+    Outcome saved = run_act(checkpoint.save, state);
+    return saved.succeeded() ? saved : outcome_failed("save_failed", to_string(saved));
 }
 
 }
@@ -441,6 +458,63 @@ std::vector<std::string> lint_checkpoint(const Checkpoint& checkpoint){
 }
 
 
+namespace{
+
+std::string names_of(const std::vector<Condition>& conditions){
+    std::string text;
+    for (const Condition& item : conditions){
+        text += (text.empty() ? "" : ", ") + item.name;
+    }
+    return text;
+}
+
+void describe_line(std::string& text, const std::string& indent, const std::string& label, const std::string& value){
+    if (!value.empty()){
+        text += std::format("{}{}: {}\n", indent, label, value);
+    }
+}
+
+void describe_event(std::string& text, size_t number, const Event& event){
+    text += std::format("  event {} {}{}\n", number, event.name, event.why.empty() ? "" : ": " + event.why);
+    describe_line(text, "    ", "skip_if", names_of(event.skip_if));
+    describe_line(text, "    ", "require", names_of(event.require));
+    describe_line(text, "    ", "expect", names_of(event.expect));
+    if (event.pose_learned){
+        describe_line(text, "    ", "pose_learned", to_string(*event.pose_learned));
+    }
+    for (const Recovery& recovery : event.recoveries){
+        text += std::format(
+            "    recovery: {} on {}{}{}\n",
+            recovery_name(recovery.kind),
+            recovery.on.empty() ? "any failure" : recovery.on,
+            recovery.kind == RecoveryKind::STOP ? "" : std::format(" x{}", recovery.attempts),
+            recovery.why.empty() ? "" : ": " + recovery.why
+        );
+    }
+}
+
+}
+
+
+std::string describe(const Checkpoint& checkpoint){
+    std::string text = std::format("checkpoint {}: {} events\n", checkpoint.id, checkpoint.events.size());
+    describe_line(text, "  ", "start", names_of(checkpoint.start));
+    std::string interrupts;
+    for (const Interrupt& interrupt : checkpoint.interrupts){
+        interrupts += (interrupts.empty() ? "" : ", ") + interrupt.name;
+    }
+    describe_line(text, "  ", "interrupts", interrupts);
+    for (size_t c = 0; c < checkpoint.events.size(); c++){
+        describe_event(text, c + 1, checkpoint.events[c]);
+    }
+    describe_line(text, "  ", "end", names_of(checkpoint.end));
+    if (checkpoint.save){
+        text += "  saves\n";
+    }
+    return text;
+}
+
+
 
 }
 }
diff --git a/SerialPrograms/Source/Pokemon/Navigation/Pokemon_StoryEvents.h b/SerialPrograms/Source/Pokemon/Navigation/Pokemon_StoryEvents.h
index 92540d41c3..b2cfc568a0 100644
--- a/SerialPrograms/Source/Pokemon/Navigation/Pokemon_StoryEvents.h
+++ b/SerialPrograms/Source/Pokemon/Navigation/Pokemon_StoryEvents.h
@@ -14,6 +14,10 @@
  *  checkpoint: after each action the runner asks whether one is showing,
  *  clears it, marks what it did to the pose and resumes as it says.
  *
+ *  The run state is the runner's to change. An action that knows where it
+ *  left the player says so in its Outcome, and the runner writes that into
+ *  the pose once the action has succeeded.
+ *
  *  Observation and actuation are callables the game supplies, so this file
  *  knows nothing of any one game or console, and the runner can be tested
  *  against a scripted world. See docs/design/AutoStory-Event-Model.md.
@@ -81,15 +85,21 @@ struct RunState{
 
 
 //  How an action or a check ended: empty `failure` is success; otherwise a
-//  name that recoveries match (e.g. "probe_exhausted").
+//  name that recoveries match (e.g. "probe_exhausted"). A succeeded action
+//  that knows where it left the player sets `pose`; the runner writes it
+//  into the run before the event's expects are checked.
 struct Outcome{
     std::string failure;
     std::string detail;
+    std::optional<Pose> pose;
 
     bool succeeded() const;
 };
 Outcome outcome_ok();
+Outcome outcome_ok(Pose pose);
 Outcome outcome_failed(std::string failure, std::string detail = "");
+//  "probe_exhausted: 4 rows": the failure and its detail, if any.
+std::string to_string(const Outcome& outcome);
 
 
 using Act = MoveOnlyFunction<Outcome(RunState& state)>;
@@ -136,7 +146,8 @@ struct Event{
     //  Must hold after `act`; a failure is "expect_failed".
     std::vector<Condition> expect;
     //  Written to the run's pose once the event succeeds. An action that
-    //  learns its pose as it goes (the row that answered) writes it itself.
+    //  learns its pose as it goes (the row that answered) returns it in
+    //  its Outcome instead.
     std::optional<Pose> pose_learned;
     //  In order of escalation.
     std::vector<Recovery> recoveries;
@@ -201,6 +212,11 @@ std::string event_log_line(const std::string& checkpoint, size_t number, const s
 //  missing actions, recoveries out of escalation order.
 std::vector<std::string> lint_checkpoint(const Checkpoint& checkpoint);
 
+//  A readable dump for review, one line per item: the checkpoint's start,
+//  interrupts and end by name, each event with its why, its conditions'
+//  names, its learned pose and its recoveries. Nothing runs.
+std::string describe(const Checkpoint& checkpoint);
+
 //  Runs the checkpoint's events in order, from the first. Events whose
 //  effect is already showing are skipped, so after a reload this resumes.
 //  Logs each event's start and end through `log`.
diff --git a/SerialPrograms/Source/Pokemon/Navigation/Pokemon_StoryEvents_Tests.cpp b/SerialPrograms/Source/Pokemon/Navigation/Pokemon_StoryEvents_Tests.cpp
index fde6e83001..64b6bfb44e 100644
--- a/SerialPrograms/Source/Pokemon/Navigation/Pokemon_StoryEvents_Tests.cpp
+++ b/SerialPrograms/Source/Pokemon/Navigation/Pokemon_StoryEvents_Tests.cpp
@@ -66,6 +66,13 @@ Event make_event(std::string name, Act act){
     return event;
 }
 
+//  The pose, confirmed on a landmark.
+Pose anchored(const Pose& pose){
+    Pose anchored = pose;
+    anchored.certainty = PoseCertainty::TILE;
+    return anchored;
+}
+
 Act record(World& world, std::string what){
     return [&world, what = std::move(what)](RunState&){
         world.trace.push_back(what);
@@ -193,8 +200,7 @@ Event talk_to_mom(World& world){
     event.recoveries.push_back(recovery("expect_failed", RecoveryKind::REANCHOR, 1, [&world](RunState& state){
         world.trace.push_back("anchor");
         world.rows_off = 0;
-        state.pose.certainty = PoseCertainty::TILE;
-        return outcome_ok();
+        return outcome_ok(anchored(state.pose));
     }));
     event.recoveries.push_back(recovery("", RecoveryKind::STOP, 0));
     event.recoveries.back().why = "four rows cover the mat to the TV";
@@ -305,8 +311,7 @@ Event walk_through_grass(World& world){
     event.pose_learned = corner;
     event.recoveries.push_back(recovery("require_failed", RecoveryKind::REANCHOR, 1, [&world](RunState& state){
         world.trace.push_back("anchor");
-        state.pose.certainty = PoseCertainty::TILE;
-        return outcome_ok();
+        return outcome_ok(anchored(state.pose));
     }));
     return event;
 }
@@ -552,6 +557,37 @@ UnitTestResult test_position_is_the_games(){
     return true;
 }
 
+//  An action that learns where it ends up returns the pose; the runner
+//  writes it before the expects, and only when the action succeeded.
+UnitTestResult test_outcome_pose(){
+    World world;
+    Checkpoint checkpoint = make_checkpoint();
+    Event probe = make_event("probe_for_mom", [&world](RunState&){
+        world.trace.push_back("probe");
+        Pose found;
+        found.map = "Player's House";
+        found.certainty = PoseCertainty::ROW;
+        found.where = std::make_shared<const TilePose>(std::vector<TilePos>{TilePos{4, 6}, TilePos{5, 6}});
+        return world.rows_off == 0 ? outcome_ok(found) : outcome_failed("probe_exhausted", "4 rows");
+    });
+    probe.expect.push_back(pose_known("Player's House", PoseCertainty::ROW));
+    checkpoint.events.push_back(std::move(probe));
+    RunState state = at_catch_spot();
+    Lines lines;
+    EventLogger log = lines.logger();
+    CheckpointReport report = run_checkpoint(state, checkpoint, log);
+    if (!report.completed || to_string(state.pose) != "Player's House (4, 6) (5, 6) (row)"){
+        return "Expected the found pose written before the expect: " + to_string(state.pose) + lines.all();
+    }
+    world.rows_off = 1;
+    state = at_catch_spot();
+    report = run_checkpoint(state, checkpoint, log);
+    if (report.completed || state.pose.map != "Route 202"){
+        return "A failed action should leave the pose alone: " + to_string(state.pose);
+    }
+    return true;
+}
+
 UnitTestResult test_lint(){
     World world;
     Checkpoint checkpoint = make_checkpoint();
@@ -606,6 +642,7 @@ void add_tests_StoryEvents(UnitTestDatabase& database){
     database.add<Test_StoryEvents>("start, end and save", test_start_end_and_save);
     database.add<Test_StoryEvents>("pose certainty", test_pose_certainty);
     database.add<Test_StoryEvents>("the position is the game's", test_position_is_the_games);
+    database.add<Test_StoryEvents>("an action returns its pose", test_outcome_pose);
     database.add<Test_StoryEvents>("lint", test_lint);
 }
 
diff --git a/SerialPrograms/Source/Pokemon/Navigation/Pokemon_StorySegments.cpp b/SerialPrograms/Source/Pokemon/Navigation/Pokemon_StorySegments.cpp
new file mode 100644
index 0000000000..e80ff4915f
--- /dev/null
+++ b/SerialPrograms/Source/Pokemon/Navigation/Pokemon_StorySegments.cpp
@@ -0,0 +1,173 @@
+/*  Story Segments
+ *
+ *  From: https://github.com/PokemonAutomation/
+ *
+ */
+
+#include <format>
+#include <utility>
+#include "Pokemon_StorySegments.h"
+
+namespace PokemonAutomation{
+namespace Pokemon{
+
+
+namespace{
+
+std::optional<size_t> index_of(const Segment& segment, const std::string& id){
+    for (size_t c = 0; c < segment.checkpoints.size(); c++){
+        if (segment.checkpoints[c].id == id){
+            return c;
+        }
+    }
+    return std::nullopt;
+}
+
+//  The rows `range` names, both inclusive, or the failure that stops the
+//  segment before it starts.
+struct Selected{
+    size_t first = 0;
+    size_t last = 0;
+    Outcome failure;
+};
+
+Selected select(const Segment& segment, const SegmentRange& range){
+    Selected selected;
+    if (segment.checkpoints.empty()){
+        selected.failure = outcome_failed("empty_segment");
+        return selected;
+    }
+    selected.last = segment.checkpoints.size() - 1;
+    if (range.from){
+        const std::optional<size_t> index = index_of(segment, *range.from);
+        if (!index){
+            selected.failure = outcome_failed("unknown_checkpoint", *range.from);
+            return selected;
+        }
+        selected.first = *index;
+    }
+    if (range.to){
+        const std::optional<size_t> index = index_of(segment, *range.to);
+        if (!index){
+            selected.failure = outcome_failed("unknown_checkpoint", *range.to);
+            return selected;
+        }
+        selected.last = *index;
+    }
+    if (selected.first > selected.last){
+        selected.failure = outcome_failed("bad_range", *range.from + " is after " + *range.to);
+    }
+    return selected;
+}
+
+CheckpointReport failed_report(Outcome failure){
+    CheckpointReport report;
+    report.failure = std::move(failure);
+    return report;
+}
+
+//  Empties the run state and reloads the last save; the reload says where
+//  the player stands.
+Outcome reload(RunState& state, SegmentHooks& hooks){
+    state = RunState{};
+    if (!hooks.reload){
+        return outcome_failed("reload_failed", "no reload hook");
+    }
+    Outcome reloaded = hooks.reload(state);
+    if (!reloaded.succeeded()){
+        return outcome_failed("reload_failed", to_string(reloaded));
+    }
+    if (reloaded.pose){
+        state.pose = *reloaded.pose;
+    }
+    return outcome_ok();
+}
+
+//  One row to success, reloading and rebuilding after each failed attempt.
+//  Returns the last attempt's report, or the reload's failure.
+CheckpointReport run_row(
+    RunState& state, const Segment& segment, CheckpointSpec& spec,
+    const SegmentPolicy& policy, SegmentHooks& hooks, SegmentReport& report
+){
+    for (size_t attempt = 1; ; attempt++){
+        Checkpoint checkpoint = spec.build();
+        if (spec.saves && !checkpoint.save){
+            checkpoint.save = [&hooks](RunState& state){
+                return hooks.save ? hooks.save(state) : outcome_failed("no_save_hook");
+            };
+        }
+        CheckpointReport result = run_checkpoint(state, checkpoint, hooks.log);
+        if (result.completed || attempt >= policy.attempts_per_checkpoint){
+            return result;
+        }
+        hooks.log(std::format(
+            "[Segment] {}: {} failed, reloading for attempt {}/{}",
+            segment.id, spec.id, attempt + 1, policy.attempts_per_checkpoint
+        ));
+        report.reloads++;
+        Outcome reloaded = reload(state, hooks);
+        if (!reloaded.succeeded()){
+            return failed_report(std::move(reloaded));
+        }
+    }
+}
+
+SegmentReport stop_segment(SegmentReport& report, SegmentHooks& hooks, const std::string& id, Outcome failure){
+    std::string where;
+    if (!report.failed_checkpoint.empty()){
+        where = " at " + report.failed_checkpoint;
+        if (!report.failed_event.empty()){
+            where += " " + report.failed_event;
+        }
+    }
+    hooks.log(std::format("[Segment] {}: failed{}: {}", id, where, to_string(failure)));
+    report.failure = std::move(failure);
+    return report;
+}
+
+}
+
+
+SegmentReport run_segment(
+    RunState& state, Segment& segment, const SegmentRange& range,
+    const SegmentPolicy& policy, SegmentHooks& hooks
+){
+    SegmentReport report;
+    const Selected selected = select(segment, range);
+    if (!selected.failure.succeeded()){
+        return stop_segment(report, hooks, segment.id, selected.failure);
+    }
+    hooks.log(std::format("[Segment] {}: start, {} checkpoints", segment.id, selected.last - selected.first + 1));
+    for (size_t c = selected.first; c <= selected.last; c++){
+        CheckpointSpec& spec = segment.checkpoints[c];
+        report.checkpoints_run++;
+        CheckpointReport result = run_row(state, segment, spec, policy, hooks, report);
+        if (!result.completed){
+            report.failed_checkpoint = spec.id;
+            report.failed_event = result.failed_name;
+            return stop_segment(report, hooks, segment.id, std::move(result.failure));
+        }
+    }
+    report.completed = true;
+    hooks.log(std::format("[Segment] {}: done, {} checkpoints", segment.id, report.checkpoints_run));
+    return report;
+}
+
+
+std::string describe(Segment& segment){
+    std::string text = std::format("segment {}: {} checkpoints\n", segment.id, segment.checkpoints.size());
+    for (const CheckpointSpec& spec : segment.checkpoints){
+        text += std::format("  {} \"{}\"{}\n", spec.id, spec.title, spec.saves ? ", saves" : "");
+    }
+    for (CheckpointSpec& spec : segment.checkpoints){
+        if (spec.build){
+            text += describe(spec.build());
+        }
+    }
+    return text;
+}
+
+
+
+}
+}
diff --git a/SerialPrograms/Source/Pokemon/Navigation/Pokemon_StorySegments.h b/SerialPrograms/Source/Pokemon/Navigation/Pokemon_StorySegments.h
new file mode 100644
index 0000000000..69e181ef57
--- /dev/null
+++ b/SerialPrograms/Source/Pokemon/Navigation/Pokemon_StorySegments.h
@@ -0,0 +1,99 @@
+/*  Story Segments
+ *
+ *  From: https://github.com/PokemonAutomation/
+ *
+ *  A story segment as a table of checkpoints. Each row names a checkpoint
+ *  and holds a factory that builds it, so every attempt runs a checkpoint
+ *  built fresh, with nothing the last attempt used up. The runner takes the
+ *  checkpoints in order from a save; a checkpoint that fails is answered
+ *  the one way the event model has no recovery for: the game is reloaded
+ *  to its last save, the checkpoint is rebuilt and run again, up to the
+ *  policy's attempts. Then the segment stops and the report names the
+ *  checkpoint, the event and the reason.
+ *
+ */
+
+#ifndef PokemonAutomation_Pokemon_StorySegments_H
+#define PokemonAutomation_Pokemon_StorySegments_H
+
+#include <cstddef>
+#include <optional>
+#include <string>
+#include <vector>
+#include "Common/Cpp/MoveOnlyFunction.h"
+#include "Pokemon_StoryEvents.h"
+
+namespace PokemonAutomation{
+namespace Pokemon{
+
+
+//  One row of a segment. `build` makes the checkpoint anew for each attempt.
+//  `saves` has the segment save the game (SegmentHooks::save) after the
+//  checkpoint's end check, when the checkpoint has no save of its own.
+struct CheckpointSpec{
+    std::string id;
+    std::string title;
+    bool saves = false;
+    MoveOnlyFunction<Checkpoint()> build;
+};
+
+struct Segment{
+    std::string id;
+    std::vector<CheckpointSpec> checkpoints;
+};
+
+
+//  What the game lends the runner: how to save, how to reload the last save
+//  (the run state is emptied first; the reload's Outcome says where the
+//  player stands), and where to log.
+struct SegmentHooks{
+    Act save;
+    Act reload;
+    EventLogger log;
+};
+
+struct SegmentPolicy{
+    //  Runs of one checkpoint, reloading between them, before the segment stops.
+    size_t attempts_per_checkpoint = 3;
+};
+
+//  The checkpoints to run, by id, both inclusive. An unset end is the
+//  segment's first or last checkpoint.
+struct SegmentRange{
+    std::optional<std::string> from;
+    std::optional<std::string> to;
+};
+
+
+struct SegmentReport{
+    bool completed = false;
+    //  Both empty when nothing failed; the event is empty when a start
+    //  check, an end check, a save or a reload failed.
+    std::string failed_checkpoint;
+    std::string failed_event;
+    Outcome failure;
+    size_t checkpoints_run = 0;
+    //  Reloads after failed attempts.
+    size_t reloads = 0;
+};
+
+//  Runs the checkpoints in `range`, in order. Logs through `hooks.log`,
+//  around the checkpoint lines:
+//      [Segment] 00: start, 3 checkpoints
+//      [Segment] 00: 00.02 failed, reloading for attempt 2/3
+//      [Segment] 00: done, 3 checkpoints
+//      [Segment] 00: failed at 00.02 talk_mom: expect_failed: dialogue opened
+SegmentReport run_segment(
+    RunState& state, Segment& segment, const SegmentRange& range,
+    const SegmentPolicy& policy, SegmentHooks& hooks
+);
+
+//  A readable dump for review: the rows, then each checkpoint built once
+//  and described as describe(const Checkpoint&) does. Nothing runs.
+std::string describe(Segment& segment);
+
+
+
+}
+}
+#endif
diff --git a/SerialPrograms/Source/Pokemon/Navigation/Pokemon_StorySegments_Tests.cpp b/SerialPrograms/Source/Pokemon/Navigation/Pokemon_StorySegments_Tests.cpp
new file mode 100644
index 0000000000..d367e27f02
--- /dev/null
+++ b/SerialPrograms/Source/Pokemon/Navigation/Pokemon_StorySegments_Tests.cpp
@@ -0,0 +1,314 @@
+/*  Story Segments Tests
+ *
+ *  From: https://github.com/PokemonAutomation/
+ *
+ *  The segment runner against a scripted world with a save slot: a few
+ *  fields the checkpoints' events change, saved and reloaded by the hooks.
+ *
+ */
+
+#include <algorithm>
+#include <functional>
+#include <memory>
+#include <string>
+#include <utility>
+#include <vector>
+#include "Common/Cpp/TestRunners/UnitTest.h"
+#include "Pokemon_StoryEvents.h"
+#include "Pokemon_StorySegments.h"
+#include "Pokemon_TilePose.h"
+#include "Pokemon_Navigation_Tests.h"
+
+namespace PokemonAutomation{
+namespace Pokemon{
+
+
+namespace{
+
+//  Twinleaf Town to Sandgem Town, shortened.
+struct World{
+    std::string map = "Twinleaf Town";
+    bool parcel = false;
+    //  Walks south that fail before one gets through.
+    int walk_failures = 0;
+    std::vector<std::string> trace;
+};
+
+Pose at_home_door(){
+    Pose pose;
+    pose.map = "Twinleaf Town";
+    pose.certainty = PoseCertainty::TILE;
+    pose.where = std::make_shared<const TilePose>(std::vector<TilePos>{TilePos{5, 9}}, Direction::SOUTH);
+    return pose;
+}
+
+//  The world, its save slot, and the log.
+struct Lab{
+    World world;
+    World saved;
+    std::vector<std::string> lines;
+
+    SegmentHooks hooks(){
+        SegmentHooks hooks;
+        hooks.save = [this](RunState&){
+            world.trace.push_back("save");
+            saved = world;
+            saved.trace.clear();
+            return outcome_ok();
+        };
+        hooks.reload = [this](RunState&){
+            //  Whatever blocked a walk has moved on by the reload.
+            const int failures = world.walk_failures;
+            std::vector<std::string> trace = std::move(world.trace);
+            world = saved;
+            world.walk_failures = failures;
+            world.trace = std::move(trace);
+            world.trace.push_back("reload");
+            return outcome_ok(at_home_door());
+        };
+        hooks.log = [this](const std::string& line){ lines.push_back(line); };
+        return hooks;
+    }
+    bool has(const std::string& line) const{
+        return std::find(lines.begin(), lines.end(), line) != lines.end();
+    }
+    std::string all() const{
+        std::string text;
+        for (const std::string& line : lines){
+            text += "\n" + line;
+        }
+        return text;
+    }
+};
+
+Event make_event(std::string name, Act act){
+    Event event;
+    event.name = std::move(name);
+    event.act = std::move(act);
+    return event;
+}
+
+Condition on_map(World& world, std::string map){
+    return condition("on " + map, [&world, map](RunState&){ return world.map == map; });
+}
+
+CheckpointSpec leave_home(World& world){
+    CheckpointSpec spec;
+    spec.id = "00.01";
+    spec.title = "Leave the house";
+    spec.saves = true;
+    spec.build = [&world]{
+        Checkpoint checkpoint;
+        checkpoint.id = "00.01";
+        Event walk = make_event("walk_out", [&world](RunState&){
+            world.trace.push_back("walk_out");
+            world.map = "Route 201";
+            return outcome_ok();
+        });
+        walk.why = "the story starts outside";
+        walk.skip_if.push_back(on_map(world, "Route 201"));
+        checkpoint.events.push_back(std::move(walk));
+        checkpoint.end.push_back(on_map(world, "Route 201"));
+        return checkpoint;
+    };
+    return spec;
+}
+
+CheckpointSpec walk_to_sandgem(World& world){
+    CheckpointSpec spec;
+    spec.id = "00.02";
+    spec.title = "Walk to Sandgem Town";
+    spec.build = [&world]{
+        Checkpoint checkpoint;
+        checkpoint.id = "00.02";
+        Event walk = make_event("walk_south", [&world](RunState&){
+            world.trace.push_back("walk_south");
+            if (world.walk_failures > 0){
+                world.walk_failures--;
+                return outcome_failed("blocked", "a wanderer on the path");
+            }
+            world.map = "Sandgem Town";
+            return outcome_ok();
+        });
+        walk.require.push_back(on_map(world, "Route 201"));
+        walk.expect.push_back(on_map(world, "Sandgem Town"));
+        Recovery stop;
+        stop.kind = RecoveryKind::STOP;
+        stop.why = "the path is one tile wide";
+        walk.recoveries.push_back(std::move(stop));
+        checkpoint.events.push_back(std::move(walk));
+        return checkpoint;
+    };
+    return spec;
+}
+
+CheckpointSpec get_parcel(World& world){
+    CheckpointSpec spec;
+    spec.id = "00.03";
+    spec.title = "Get the Parcel";
+    spec.build = [&world]{
+        Checkpoint checkpoint;
+        checkpoint.id = "00.03";
+        Event talk = make_event("talk_clerk", [&world](RunState&){
+            world.trace.push_back("talk_clerk");
+            world.parcel = true;
+            return outcome_ok();
+        });
+        talk.expect.push_back(condition("parcel in the Bag", [&world](RunState&){ return world.parcel; }));
+        talk.pose_learned = at_home_door();
+        checkpoint.events.push_back(std::move(talk));
+        return checkpoint;
+    };
+    return spec;
+}
+
+Segment twinleaf_to_sandgem(World& world){
+    Segment segment;
+    segment.id = "00";
+    segment.checkpoints.push_back(leave_home(world));
+    segment.checkpoints.push_back(walk_to_sandgem(world));
+    segment.checkpoints.push_back(get_parcel(world));
+    return segment;
+}
+
+
+UnitTestResult test_runs_checkpoints_in_order(){
+    Lab lab;
+    Segment segment = twinleaf_to_sandgem(lab.world);
+    SegmentHooks hooks = lab.hooks();
+    RunState state;
+    const SegmentReport report = run_segment(state, segment, SegmentRange{}, SegmentPolicy{}, hooks);
+    const std::vector<std::string> expected = {"walk_out", "save", "walk_south", "talk_clerk"};
+    if (!report.completed || report.checkpoints_run != 3 || lab.world.trace != expected){
+        return "Expected three checkpoints, saved after the first:" + lab.all();
+    }
+    if (!lab.has("[Segment] 00: start, 3 checkpoints") || lab.lines.back() != "[Segment] 00: done, 3 checkpoints"){
+        return "Unexpected log:" + lab.all();
+    }
+    if (lab.saved.map != "Route 201"){
+        return "The save should hold the world after the first checkpoint.";
+    }
+    return true;
+}
+
+UnitTestResult test_reloads_a_failed_checkpoint(){
+    Lab lab;
+    lab.world.walk_failures = 1;
+    Segment segment = twinleaf_to_sandgem(lab.world);
+    SegmentHooks hooks = lab.hooks();
+    RunState state;
+    const SegmentReport report = run_segment(state, segment, SegmentRange{}, SegmentPolicy{}, hooks);
+    const std::vector<std::string> expected = {"walk_out", "save", "walk_south", "reload", "walk_south", "talk_clerk"};
+    if (!report.completed || report.reloads != 1 || lab.world.trace != expected){
+        return "Expected a reload, then the walk again:" + lab.all();
+    }
+    if (!lab.has("[Segment] 00: 00.02 failed, reloading for attempt 2/3")){
+        return "Expected the reload logged:" + lab.all();
+    }
+    return true;
+}
+
+UnitTestResult test_gives_up_and_names_the_failure(){
+    Lab lab;
+    lab.world.walk_failures = 10;
+    Segment segment = twinleaf_to_sandgem(lab.world);
+    SegmentHooks hooks = lab.hooks();
+    RunState state;
+    const SegmentReport report = run_segment(state, segment, SegmentRange{}, SegmentPolicy{.attempts_per_checkpoint = 2}, hooks);
+    if (report.completed || report.failed_checkpoint != "00.02" || report.failed_event != "walk_south"){
+        return "Expected the failed checkpoint and event named:" + lab.all();
+    }
+    if (report.failure.failure != "blocked" || report.reloads != 1 || report.checkpoints_run != 2){
+        return "Expected two attempts with one reload between them:" + lab.all();
+    }
+    if (lab.world.parcel || lab.lines.back() != "[Segment] 00: failed at 00.02 walk_south: blocked: a wanderer on the path"){
+        return "Nothing after the failed checkpoint should run:" + lab.all();
+    }
+    if (state.pose.map != "Twinleaf Town" || state.pose.certainty != PoseCertainty::TILE){
+        return "The reload should have set the pose: " + to_string(state.pose);
+    }
+    return true;
+}
+
+UnitTestResult test_range(){
+    Lab lab;
+    lab.world.map = "Route 201";
+    Segment segment = twinleaf_to_sandgem(lab.world);
+    SegmentHooks hooks = lab.hooks();
+    RunState state;
+    SegmentReport report = run_segment(state, segment, SegmentRange{.from = "00.02", .to = "00.02"}, SegmentPolicy{}, hooks);
+    if (!report.completed || lab.world.trace != std::vector<std::string>{"walk_south"}){
+        return "Expected only the second checkpoint:" + lab.all();
+    }
+    report = run_segment(state, segment, SegmentRange{.from = "00.09", .to = std::nullopt}, SegmentPolicy{}, hooks);
+    if (report.completed || report.failure.failure != "unknown_checkpoint" || report.failure.detail != "00.09"){
+        return "Expected the unknown id reported:" + lab.all();
+    }
+    report = run_segment(state, segment, SegmentRange{.from = "00.03", .to = "00.01"}, SegmentPolicy{}, hooks);
+    if (report.completed || report.failure.failure != "bad_range"){
+        return "Expected the reversed range reported:" + lab.all();
+    }
+    return true;
+}
+
+UnitTestResult test_describe(){
+    Lab lab;
+    Segment segment = twinleaf_to_sandgem(lab.world);
+    const std::string expected =
+        "segment 00: 3 checkpoints\n"
+        "  00.01 \"Leave the house\", saves\n"
+        "  00.02 \"Walk to Sandgem Town\"\n"
+        "  00.03 \"Get the Parcel\"\n"
+        "checkpoint 00.01: 1 events\n"
+        "  event 1 walk_out: the story starts outside\n"
+        "    skip_if: on Route 201\n"
+        "  end: on Route 201\n"
+        "checkpoint 00.02: 1 events\n"
+        "  event 1 walk_south\n"
+        "    require: on Route 201\n"
+        "    expect: on Sandgem Town\n"
+        "    recovery: stop on any failure: the path is one tile wide\n"
+        "checkpoint 00.03: 1 events\n"
+        "  event 1 talk_clerk\n"
+        "    expect: parcel in the Bag\n"
+        "    pose_learned: Twinleaf Town (5, 9) facing south (tile)\n";
+    const std::string text = describe(segment);
+    if (text != expected){
+        return "Unexpected description:\n" + text;
+    }
+    if (!lab.world.trace.empty()){
+        return "Describing a segment should run nothing.";
+    }
+    return true;
+}
+
+
+class Test_StorySegments : public UnitTest{
+public:
+    Test_StorySegments(std::string name, std::function<UnitTestResult()> body)
+        : UnitTest("Pokemon::StorySegments - " + std::move(name))
+        , m_body(std::move(body))
+    {}
+    virtual UnitTestResult run(Logger&, CancellableScope&) const override{
+        return m_body();
+    }
+
+private:
+    std::function<UnitTestResult()> m_body;
+};
+
+}
+
+
+void add_tests_StorySegments(UnitTestDatabase& database){
+    database.add<Test_StorySegments>("checkpoints run in order", test_runs_checkpoints_in_order);
+    database.add<Test_StorySegments>("a failed checkpoint is reloaded", test_reloads_a_failed_checkpoint);
+    database.add<Test_StorySegments>("gives up and names the failure", test_gives_up_and_names_the_failure);
+    database.add<Test_StorySegments>("a range of checkpoints", test_range);
+    database.add<Test_StorySegments>("describe", test_describe);
+}
+
+
+
+}
+}
diff --git a/SerialPrograms/cmake/SourceFiles.cmake b/SerialPrograms/cmake/SourceFiles.cmake
index 90b690951d..c93b05a880 100644
--- a/SerialPrograms/cmake/SourceFiles.cmake
+++ b/SerialPrograms/cmake/SourceFiles.cmake
@@ -1450,6 +1450,9 @@ file(GLOB LIBRARY_SOURCES
     Source/Pokemon/Navigation/Pokemon_StoryEvents.cpp
     Source/Pokemon/Navigation/Pokemon_StoryEvents.h
     Source/Pokemon/Navigation/Pokemon_StoryEvents_Tests.cpp
+    Source/Pokemon/Navigation/Pokemon_StorySegments.cpp
+    Source/Pokemon/Navigation/Pokemon_StorySegments.h
+    Source/Pokemon/Navigation/Pokemon_StorySegments_Tests.cpp
     Source/Pokemon/Navigation/Pokemon_TilePose.cpp
     Source/Pokemon/Navigation/Pokemon_TilePose.h
     Source/Pokemon/Options/Pokemon_BoxSortingTable.cpp

From d94af62c3cf0faf8fb972fbcce6a9e2cdf35cbb3 Mon Sep 17 00:00:00 2001
From: dayfine <difancpa@gmail.com>
Date: Sun, 1 Nov 2026 00:18:57 -0700
Subject: [PATCH 07/19] Pokemon navigation: one JSON map schema and loader for
 both games

BDSP and FRLG each read their own map files with their own parser. This
adds a game-neutral MapData and parse_map() in Pokemon/Navigation, with one
schema: a name, the decompilation source (file, revision, date), tiles as
rows of glyphs, named points, warps to a point of another map, objects
(npc, item, sign, with a facing and a wander box), connections to the
neighbouring maps, and patches of tiles measured on the console applied
on top. The reader generalises FRLG's read_map(): errors name the source
and the JSON path, and anything placed outside the tiles is an error.
Grid<Cell> moves into Pokemon_Grid.h for it. No game reads these yet.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01AKYzhrMnPK61XHWEch4a6E
---
 .../ComputerPrograms_UnitTestRunner.cpp       |   1 +
 .../Source/Pokemon/Navigation/Pokemon_Grid.h  |  21 ++
 .../Pokemon/Navigation/Pokemon_MapData.cpp    | 337 ++++++++++++++++++
 .../Pokemon/Navigation/Pokemon_MapData.h      | 140 ++++++++
 .../Navigation/Pokemon_MapData_Tests.cpp      | 210 +++++++++++
 .../Navigation/Pokemon_Navigation_Tests.h     |   1 +
 SerialPrograms/cmake/SourceFiles.cmake        |   3 +
 7 files changed, 713 insertions(+)
 create mode 100644 SerialPrograms/Source/Pokemon/Navigation/Pokemon_MapData.cpp
 create mode 100644 SerialPrograms/Source/Pokemon/Navigation/Pokemon_MapData.h
 create mode 100644 SerialPrograms/Source/Pokemon/Navigation/Pokemon_MapData_Tests.cpp

diff --git a/SerialPrograms/Source/ComputerPrograms/ComputerPrograms_UnitTestRunner.cpp b/SerialPrograms/Source/ComputerPrograms/ComputerPrograms_UnitTestRunner.cpp
index b0253c967e..2e17398c46 100644
--- a/SerialPrograms/Source/ComputerPrograms/ComputerPrograms_UnitTestRunner.cpp
+++ b/SerialPrograms/Source/ComputerPrograms/ComputerPrograms_UnitTestRunner.cpp
@@ -62,6 +62,7 @@ UnitTestDatabase make_UNIT_TESTS_ALL(){
     OCR::add_tests(ret);
     Kernels::add_tests(ret);
     Pokemon::add_tests_LegPlanner(ret);
+    Pokemon::add_tests_MapData(ret);
     Pokemon::add_tests_StoryEvents(ret);
     Pokemon::add_tests_StorySegments(ret);
     NintendoSwitch::add_tests_CheckOnlineDetector(ret);
diff --git a/SerialPrograms/Source/Pokemon/Navigation/Pokemon_Grid.h b/SerialPrograms/Source/Pokemon/Navigation/Pokemon_Grid.h
index 409e6fe06e..9d4b232579 100644
--- a/SerialPrograms/Source/Pokemon/Navigation/Pokemon_Grid.h
+++ b/SerialPrograms/Source/Pokemon/Navigation/Pokemon_Grid.h
@@ -13,6 +13,7 @@
 #include <cstddef>
 #include <functional>
 #include <string>
+#include <vector>
 
 namespace PokemonAutomation{
 namespace Pokemon{
@@ -41,6 +42,26 @@ struct TilePos{
 std::string to_string(const TilePos& pos);
 
 
+//  One value per tile of a map, row by row from the top.
+template <typename Cell>
+struct Grid{
+    int width = 0;
+    int height = 0;
+    std::vector<Cell> cells;
+
+    bool contains(const TilePos& pos) const{
+        return 0 <= pos.x && pos.x < width && 0 <= pos.y && pos.y < height;
+    }
+    //  `pos` must be inside the grid.
+    const Cell& at(const TilePos& pos) const{
+        return cells[(size_t)pos.y * width + pos.x];
+    }
+    Cell& at(const TilePos& pos){
+        return cells[(size_t)pos.y * width + pos.x];
+    }
+};
+
+
 
 }
 }
diff --git a/SerialPrograms/Source/Pokemon/Navigation/Pokemon_MapData.cpp b/SerialPrograms/Source/Pokemon/Navigation/Pokemon_MapData.cpp
new file mode 100644
index 0000000000..3121ee4d94
--- /dev/null
+++ b/SerialPrograms/Source/Pokemon/Navigation/Pokemon_MapData.cpp
@@ -0,0 +1,337 @@
+/*  Map Data
+ *
+ *  From: https://github.com/PokemonAutomation/
+ *
+ */
+
+#include <format>
+#include <utility>
+#include "Common/Cpp/Exceptions.h"
+#include "Common/Cpp/Json/JsonArray.h"
+#include "Common/Cpp/Json/JsonObject.h"
+#include "Pokemon_MapData.h"
+
+namespace PokemonAutomation{
+namespace Pokemon{
+
+
+namespace{
+
+constexpr std::pair<char, TileKind> GLYPHS[] = {
+    {'#', TileKind::WALL},
+    {'.', TileKind::OPEN},
+    {'~', TileKind::TALL_GRASS},
+    {'w', TileKind::WATER},
+    {'^', TileKind::LEDGE_NORTH},
+    {'v', TileKind::LEDGE_SOUTH},
+    {'<', TileKind::LEDGE_WEST},
+    {'>', TileKind::LEDGE_EAST},
+    {'D', TileKind::DOOR},
+    {'S', TileKind::SIGN},
+};
+
+}
+
+std::optional<TileKind> tile_from_glyph(char glyph){
+    for (const auto& [known, tile] : GLYPHS){
+        if (known == glyph){
+            return tile;
+        }
+    }
+    return std::nullopt;
+}
+
+char glyph_of(TileKind tile){
+    for (const auto& [glyph, known] : GLYPHS){
+        if (known == tile){
+            return glyph;
+        }
+    }
+    return '?';
+}
+
+
+namespace{
+
+//  The readers take `where`, the source and the path to the object being
+//  read (e.g. "Maps/TestTown.json: warps[2]."), and name the field in what
+//  they throw.
+
+const JsonObject& as_object(const JsonValue& value, const std::string& where){
+    const JsonObject* object = value.to_object();
+    if (object == nullptr){
+        throw ParseException(where + " is not a JSON object.");
+    }
+    return *object;
+}
+
+const JsonValue& read_field(const JsonObject& object, const std::string& key, const std::string& where){
+    const JsonValue* value = object.get_value(key);
+    if (value == nullptr){
+        throw ParseException(where + key + " is missing.");
+    }
+    return *value;
+}
+
+int read_int(const JsonObject& object, const std::string& key, const std::string& where){
+    const JsonValue& value = read_field(object, key, where);
+    if (!value.is_integer()){
+        throw ParseException(where + key + " is not an integer.");
+    }
+    return (int)value.to_integer_default();
+}
+
+std::string read_string(const JsonObject& object, const std::string& key, const std::string& where){
+    const std::string* text = read_field(object, key, where).to_string();
+    if (text == nullptr){
+        throw ParseException(where + key + " is not a string.");
+    }
+    return *text;
+}
+
+TilePos read_pos(const JsonObject& object, const std::string& where){
+    return TilePos{read_int(object, "x", where), read_int(object, "y", where)};
+}
+
+Direction read_direction(const JsonObject& object, const std::string& key, const std::string& where){
+    const std::string name = read_string(object, key, where);
+    for (Direction candidate : ALL_DIRECTIONS){
+        if (name == direction_name(candidate)){
+            return candidate;
+        }
+    }
+    throw ParseException(std::format("{}{} \"{}\" is not north, east, south or west.", where, key, name));
+}
+
+//  The list `key`, or nothing when the map leaves it out.
+const JsonArray* optional_array(const JsonObject& object, const std::string& key, const std::string& where){
+    const JsonValue* value = object.get_value(key);
+    if (value == nullptr){
+        return nullptr;
+    }
+    const JsonArray* array = value->to_array();
+    if (array == nullptr){
+        throw ParseException(where + key + " is not an array.");
+    }
+    return array;
+}
+
+const JsonObject* optional_object(const JsonObject& object, const std::string& key, const std::string& where){
+    const JsonValue* value = object.get_value(key);
+    if (value == nullptr){
+        return nullptr;
+    }
+    return &as_object(*value, where + key);
+}
+
+template <typename Item>
+std::vector<Item> read_list(
+    const JsonObject& object, const std::string& key, const std::string& where,
+    Item (*read_item)(const JsonObject& object, const std::string& where)
+){
+    std::vector<Item> items;
+    const JsonArray* array = optional_array(object, key, where);
+    if (array == nullptr){
+        return items;
+    }
+    for (size_t c = 0; c < array->size(); c++){
+        const std::string item_where = std::format("{}{}[{}]", where, key, c);
+        items.push_back(read_item(as_object((*array)[c], item_where), item_where + "."));
+    }
+    return items;
+}
+
+
+MapSource read_source(const JsonObject& root, const std::string& where){
+    const std::string key = "source";
+    const JsonObject& object = as_object(read_field(root, key, where), where + key);
+    const std::string source_where = where + key + ".";
+    MapSource source;
+    source.decomp_file = read_string(object, "decomp_file", source_where);
+    source.revision = read_string(object, "revision", source_where);
+    source.date = read_string(object, "date", source_where);
+    return source;
+}
+
+//  Rows of glyphs, all as wide as the first.
+Grid<TileKind> read_tiles(const JsonObject& root, const std::string& where){
+    const std::string key = "tiles";
+    const JsonValue& value = read_field(root, key, where);
+    const JsonArray* rows = value.to_array();
+    if (rows == nullptr){
+        throw ParseException(where + key + " is not an array.");
+    }
+    if (rows->empty()){
+        throw ParseException(where + key + " has no rows.");
+    }
+    const std::string* first = (*rows)[0].to_string();
+    const size_t width = first == nullptr ? 0 : first->size();
+    if (width == 0){
+        throw ParseException(where + key + "[0] is not a string of glyphs.");
+    }
+    Grid<TileKind> grid{(int)width, (int)rows->size(), {}};
+    for (size_t y = 0; y < rows->size(); y++){
+        const std::string row_where = std::format("{}{}[{}]", where, key, y);
+        const std::string* row = (*rows)[y].to_string();
+        if (row == nullptr || row->size() != width){
+            throw ParseException(std::format("{} is not a string of {} glyphs.", row_where, width));
+        }
+        for (size_t x = 0; x < width; x++){
+            const std::optional<TileKind> tile = tile_from_glyph((*row)[x]);
+            if (!tile){
+                throw ParseException(std::format(
+                    "{} has unknown glyph '{}' at {}.", row_where, (*row)[x], to_string(TilePos{(int)x, (int)y})
+                ));
+            }
+            grid.cells.push_back(*tile);
+        }
+    }
+    return grid;
+}
+
+std::map<std::string, TilePos> read_points(const JsonObject& root, const std::string& where){
+    std::map<std::string, TilePos> points;
+    const JsonObject* object = optional_object(root, "points", where);
+    if (object == nullptr){
+        return points;
+    }
+    for (const auto& [name, value] : *object){
+        const JsonArray* pair = value.to_array();
+        if (pair == nullptr || pair->size() != 2 || !(*pair)[0].is_integer() || !(*pair)[1].is_integer()){
+            throw ParseException(std::format("{}points.{} is not [x, y].", where, name));
+        }
+        points[name] = TilePos{(int)(*pair)[0].to_integer_default(), (int)(*pair)[1].to_integer_default()};
+    }
+    return points;
+}
+
+MapWarp read_warp(const JsonObject& object, const std::string& where){
+    MapWarp warp;
+    const TilePos pos = read_pos(object, where);
+    warp.x = pos.x;
+    warp.y = pos.y;
+    warp.to_map = read_string(object, "to_map", where);
+    warp.to_point = read_string(object, "to_point", where);
+    return warp;
+}
+
+ObjectKind read_object_kind(const JsonObject& object, const std::string& where){
+    const std::string kind = read_string(object, "kind", where);
+    if (kind == "npc"){
+        return ObjectKind::NPC;
+    }
+    if (kind == "item"){
+        return ObjectKind::ITEM;
+    }
+    if (kind == "sign"){
+        return ObjectKind::SIGN;
+    }
+    throw ParseException(std::format("{}kind \"{}\" is not npc, item or sign.", where, kind));
+}
+
+WanderBox read_wander(const JsonObject& object, const std::string& where){
+    WanderBox box;
+    box.x0 = read_int(object, "x0", where);
+    box.y0 = read_int(object, "y0", where);
+    box.x1 = read_int(object, "x1", where);
+    box.y1 = read_int(object, "y1", where);
+    if (box.x0 > box.x1 || box.y0 > box.y1){
+        throw ParseException(where.substr(0, where.size() - 1) + " is not a box (x0 <= x1, y0 <= y1).");
+    }
+    return box;
+}
+
+MapObject read_object(const JsonObject& object, const std::string& where){
+    MapObject map_object;
+    map_object.name = read_string(object, "name", where);
+    map_object.kind = read_object_kind(object, where);
+    const TilePos pos = read_pos(object, where);
+    map_object.x = pos.x;
+    map_object.y = pos.y;
+    if (object.get_value("facing") != nullptr){
+        map_object.facing = read_direction(object, "facing", where);
+    }
+    if (const JsonObject* wander = optional_object(object, "wander", where)){
+        map_object.wander = read_wander(*wander, where + "wander.");
+    }
+    return map_object;
+}
+
+MapConnection read_connection(const JsonObject& object, const std::string& where){
+    MapConnection connection;
+    connection.side = read_direction(object, "side", where);
+    connection.to_map = read_string(object, "to_map", where);
+    connection.offset = read_int(object, "offset", where);
+    return connection;
+}
+
+MapPatch read_patch(const JsonObject& object, const std::string& where){
+    MapPatch patch;
+    const TilePos pos = read_pos(object, where);
+    patch.x = pos.x;
+    patch.y = pos.y;
+    const std::string glyph = read_string(object, "glyph", where);
+    const std::optional<TileKind> tile = glyph.size() == 1 ? tile_from_glyph(glyph[0]) : std::nullopt;
+    if (!tile){
+        throw ParseException(std::format("{}glyph \"{}\" is not a tile glyph.", where, glyph));
+    }
+    patch.glyph = *tile;
+    patch.measured_by = read_string(object, "measured_by", where);
+    return patch;
+}
+
+
+void check_inside(const Grid<TileKind>& tiles, const TilePos& pos, const std::string& where){
+    if (!tiles.contains(pos)){
+        throw ParseException(std::format("{} {} is outside the {}x{} map.", where, to_string(pos), tiles.width, tiles.height));
+    }
+}
+
+//  Everything with a place on the map has it inside the tiles.
+void check_places(const MapData& map, const std::string& where){
+    for (const auto& [name, pos] : map.points){
+        check_inside(map.tiles, pos, where + "points." + name);
+    }
+    for (size_t c = 0; c < map.warps.size(); c++){
+        check_inside(map.tiles, TilePos{map.warps[c].x, map.warps[c].y}, std::format("{}warps[{}]", where, c));
+    }
+    for (size_t c = 0; c < map.objects.size(); c++){
+        const MapObject& object = map.objects[c];
+        check_inside(map.tiles, TilePos{object.x, object.y}, std::format("{}objects[{}]", where, c));
+        if (object.wander){
+            const std::string wander_where = std::format("{}objects[{}].wander", where, c);
+            check_inside(map.tiles, TilePos{object.wander->x0, object.wander->y0}, wander_where);
+            check_inside(map.tiles, TilePos{object.wander->x1, object.wander->y1}, wander_where);
+        }
+    }
+    for (size_t c = 0; c < map.patches.size(); c++){
+        check_inside(map.tiles, TilePos{map.patches[c].x, map.patches[c].y}, std::format("{}patches[{}]", where, c));
+    }
+}
+
+}
+
+
+MapData parse_map(const JsonValue& json, const std::string& source_name){
+    const JsonObject& root = as_object(json, source_name);
+    const std::string where = source_name + ": ";
+    MapData map;
+    map.name = read_string(root, "name", where);
+    map.source = read_source(root, where);
+    map.tiles = read_tiles(root, where);
+    map.points = read_points(root, where);
+    map.warps = read_list<MapWarp>(root, "warps", where, read_warp);
+    map.objects = read_list<MapObject>(root, "objects", where, read_object);
+    map.connections = read_list<MapConnection>(root, "connections", where, read_connection);
+    map.patches = read_list<MapPatch>(root, "patches", where, read_patch);
+    check_places(map, where);
+    for (const MapPatch& patch : map.patches){
+        map.tiles.at(TilePos{patch.x, patch.y}) = patch.glyph;
+    }
+    return map;
+}
+
+
+
+}
+}
diff --git a/SerialPrograms/Source/Pokemon/Navigation/Pokemon_MapData.h b/SerialPrograms/Source/Pokemon/Navigation/Pokemon_MapData.h
new file mode 100644
index 0000000000..766182714b
--- /dev/null
+++ b/SerialPrograms/Source/Pokemon/Navigation/Pokemon_MapData.h
@@ -0,0 +1,140 @@
+/*  Map Data
+ *
+ *  From: https://github.com/PokemonAutomation/
+ *
+ *  A map as a navigation program sees it, read from the one JSON schema the
+ *  tile games (BDSP, FRLG) share: the tiles as rows of glyphs, the named
+ *  points routes start and end at, the warps, the objects standing on the
+ *  map, the connections to neighbouring maps, and patches that put tiles
+ *  measured on the console on top of the decompilation's data.
+ *
+ *      {
+ *          "name": "TestTown",
+ *          "source": {"decomp_file": "data/maps/TestTown/map.json", "revision": "abc123", "date": "2026-10-31"},
+ *          "tiles": ["####", "#..~", ...],             //  rows of glyphs, all the same length
+ *          "points": {"door": [1, 2], ...},
+ *          "warps": [{"x": 1, "y": 2, "to_map": "TestHouse", "to_point": "exit"}, ...],
+ *          "objects": [{"name": "mom", "kind": "npc", "x": 2, "y": 1,
+ *                       "facing": "south", "wander": {"x0": 1, "y0": 1, "x1": 2, "y1": 2}}, ...],
+ *          "connections": [{"side": "east", "to_map": "Route 1", "offset": 0}, ...],
+ *          "patches": [{"x": 2, "y": 1, "glyph": "#", "measured_by": "run 3, 2026-10-30"}, ...]
+ *      }
+ *
+ *  `name`, `source` and `tiles` are required; the lists may be left out.
+ *  Which game's planner reads these maps, and how, is the game's business.
+ *
+ */
+
+#ifndef PokemonAutomation_Pokemon_MapData_H
+#define PokemonAutomation_Pokemon_MapData_H
+
+#include <cstdint>
+#include <map>
+#include <optional>
+#include <string>
+#include <vector>
+#include "Common/Cpp/Json/JsonValue.h"
+#include "Pokemon_Grid.h"
+
+namespace PokemonAutomation{
+namespace Pokemon{
+
+
+//  What a tile is, for walking. The map files write each as one glyph.
+enum class TileKind : uint8_t{
+    WALL,           //  '#'
+    OPEN,           //  '.'
+    TALL_GRASS,     //  '~'  open, with wild encounters
+    WATER,          //  'w'
+    LEDGE_NORTH,    //  '^'  a wall, except that walking into it the arrow's
+    LEDGE_SOUTH,    //  'v'  way hops the player over it
+    LEDGE_WEST,     //  '<'
+    LEDGE_EAST,     //  '>'
+    DOOR,           //  'D'  a door or warp tile
+    SIGN,           //  'S'  a sign, read by facing it
+};
+//  The tile a glyph stands for, or nothing if it isn't one.
+std::optional<TileKind> tile_from_glyph(char glyph);
+char glyph_of(TileKind tile);
+
+
+//  Where the tiles came from: the decompilation file, at which revision,
+//  read when.
+struct MapSource{
+    std::string decomp_file;
+    std::string revision;
+    std::string date;
+};
+
+//  Stepping onto (x, y) puts the player at point `to_point` of `to_map`.
+struct MapWarp{
+    int x = 0;
+    int y = 0;
+    std::string to_map;
+    std::string to_point;
+};
+
+enum class ObjectKind{
+    NPC,
+    ITEM,
+    SIGN,
+};
+
+//  The tiles a wanderer may stand on, both corners inclusive.
+struct WanderBox{
+    int x0 = 0;
+    int y0 = 0;
+    int x1 = 0;
+    int y1 = 0;
+};
+
+//  Something standing on a tile, which blocks it. A person who wanders may
+//  stand anywhere in `wander`.
+struct MapObject{
+    std::string name;
+    ObjectKind kind = ObjectKind::NPC;
+    int x = 0;
+    int y = 0;
+    std::optional<Direction> facing;
+    std::optional<WanderBox> wander;
+};
+
+//  Walking off the map's `side` continues on `to_map`, whose tiles are
+//  shifted by `offset` along that side.
+struct MapConnection{
+    Direction side = Direction::NORTH;
+    std::string to_map;
+    int offset = 0;
+};
+
+//  A tile measured on the console that differs from the decompilation's.
+struct MapPatch{
+    int x = 0;
+    int y = 0;
+    TileKind glyph = TileKind::WALL;
+    std::string measured_by;
+};
+
+struct MapData{
+    std::string name;
+    MapSource source;
+    //  With the patches applied.
+    Grid<TileKind> tiles;
+    std::map<std::string, TilePos> points;
+    std::vector<MapWarp> warps;
+    std::vector<MapObject> objects;
+    std::vector<MapConnection> connections;
+    std::vector<MapPatch> patches;
+};
+
+//  Reads a map from its parsed JSON. `source_name` names it in errors.
+//  Throws ParseException, naming the source and the JSON path (e.g.
+//  "Maps/TestTown.json: warps[2].x is missing."), when a field is missing,
+//  doesn't fit the schema, or places something outside the tiles.
+MapData parse_map(const JsonValue& json, const std::string& source_name);
+
+
+
+}
+}
+#endif
diff --git a/SerialPrograms/Source/Pokemon/Navigation/Pokemon_MapData_Tests.cpp b/SerialPrograms/Source/Pokemon/Navigation/Pokemon_MapData_Tests.cpp
new file mode 100644
index 0000000000..6ea7ad110b
--- /dev/null
+++ b/SerialPrograms/Source/Pokemon/Navigation/Pokemon_MapData_Tests.cpp
@@ -0,0 +1,210 @@
+/*  Map Data Tests
+ *
+ *  From: https://github.com/PokemonAutomation/
+ *
+ *  parse_map() on a small synthetic map: the good map, a map with only the
+ *  required fields, and one row per error class.
+ *
+ */
+
+#include <functional>
+#include <string>
+#include <utility>
+#include <vector>
+#include "Common/Cpp/Exceptions.h"
+#include "Common/Cpp/Json/JsonValue.h"
+#include "Common/Cpp/TestRunners/UnitTest.h"
+#include "Pokemon_MapData.h"
+#include "Pokemon_Navigation_Tests.h"
+
+namespace PokemonAutomation{
+namespace Pokemon{
+
+
+namespace{
+
+const char* const VALID_MAP = R"({
+    "name": "TestTown",
+    "source": {"decomp_file": "data/maps/TestTown/map.json", "revision": "abc123", "date": "2026-10-31"},
+    "tiles": ["####", "#..~", "#D.S", "w^v#"],
+    "points": {"door": [1, 2], "sign": [3, 2]},
+    "warps": [{"x": 1, "y": 2, "to_map": "TestHouse", "to_point": "exit"}],
+    "objects": [
+        {"name": "mom", "kind": "npc", "x": 2, "y": 1, "facing": "south", "wander": {"x0": 1, "y0": 1, "x1": 2, "y1": 2}},
+        {"name": "potion", "kind": "item", "x": 2, "y": 2}
+    ],
+    "connections": [{"side": "east", "to_map": "Route 1", "offset": 0}],
+    "patches": [{"x": 2, "y": 1, "glyph": "#", "measured_by": "run 3, 2026-10-30"}]
+})";
+
+//  The valid map with `find` replaced by `replacement`; empty when `find`
+//  is not in it.
+std::string edited(const std::string& find, const std::string& replacement){
+    std::string json = VALID_MAP;
+    const size_t at = json.find(find);
+    if (at == std::string::npos){
+        return "";
+    }
+    return json.replace(at, find.size(), replacement);
+}
+
+//  The ParseException that parsing `json` throws, or empty if it doesn't.
+std::string parse_error(const std::string& json){
+    try{
+        parse_map(parse_json(json), "Test.json");
+    }catch (ParseException& e){
+        return e.message();
+    }
+    return "";
+}
+
+//  Whether `text` contains every one of `parts`.
+bool mentions(const std::string& text, const std::vector<const char*>& parts){
+    for (const char* part : parts){
+        if (text.find(part) == std::string::npos){
+            return false;
+        }
+    }
+    return true;
+}
+
+
+UnitTestResult test_valid_map(){
+    const MapData map = parse_map(parse_json(VALID_MAP), "Test.json");
+    if (map.name != "TestTown" || map.source.decomp_file != "data/maps/TestTown/map.json"
+        || map.source.revision != "abc123" || map.source.date != "2026-10-31"
+    ){
+        return "Wrong name or source.";
+    }
+    if (map.tiles.width != 4 || map.tiles.height != 4
+        || map.tiles.at({3, 1}) != TileKind::TALL_GRASS || map.tiles.at({1, 2}) != TileKind::DOOR
+        || map.tiles.at({3, 2}) != TileKind::SIGN || map.tiles.at({0, 3}) != TileKind::WATER
+        || map.tiles.at({1, 3}) != TileKind::LEDGE_NORTH || map.tiles.at({2, 3}) != TileKind::LEDGE_SOUTH
+    ){
+        return "Wrong tiles.";
+    }
+    if (map.tiles.at({2, 1}) != TileKind::WALL || map.patches.size() != 1 || map.patches[0].measured_by != "run 3, 2026-10-30"){
+        return "The patch should have made (2, 1) a wall.";
+    }
+    if (map.points.size() != 2 || map.points.at("door") != TilePos{1, 2} || map.points.at("sign") != TilePos{3, 2}){
+        return "Wrong points.";
+    }
+    if (map.warps.size() != 1 || map.warps[0].x != 1 || map.warps[0].y != 2
+        || map.warps[0].to_map != "TestHouse" || map.warps[0].to_point != "exit"
+    ){
+        return "Wrong warps.";
+    }
+    if (map.objects.size() != 2 || map.objects[0].name != "mom" || map.objects[0].kind != ObjectKind::NPC
+        || map.objects[0].facing != Direction::SOUTH || !map.objects[0].wander
+        || map.objects[0].wander->x0 != 1 || map.objects[0].wander->y1 != 2
+        || map.objects[1].kind != ObjectKind::ITEM || map.objects[1].facing || map.objects[1].wander
+    ){
+        return "Wrong objects.";
+    }
+    if (map.connections.size() != 1 || map.connections[0].side != Direction::EAST
+        || map.connections[0].to_map != "Route 1" || map.connections[0].offset != 0
+    ){
+        return "Wrong connections.";
+    }
+    return true;
+}
+
+UnitTestResult test_lists_may_be_left_out(){
+    const MapData map = parse_map(parse_json(R"({
+        "name": "Cave",
+        "source": {"decomp_file": "f", "revision": "r", "date": "d"},
+        "tiles": ["#.#"]
+    })"), "Cave.json");
+    if (map.tiles.width != 3 || map.tiles.height != 1 || !map.points.empty() || !map.warps.empty()
+        || !map.objects.empty() || !map.connections.empty() || !map.patches.empty()
+    ){
+        return "Expected a 3x1 map with nothing on it.";
+    }
+    return true;
+}
+
+UnitTestResult test_glyphs_round_trip(){
+    for (char glyph : std::string("#.~wv^<>DS")){
+        const std::optional<TileKind> tile = tile_from_glyph(glyph);
+        if (!tile || glyph_of(*tile) != glyph){
+            return std::string("Glyph '") + glyph + "' does not round-trip.";
+        }
+    }
+    if (tile_from_glyph('?')){
+        return "'?' is not a glyph.";
+    }
+    return true;
+}
+
+struct BadMap{
+    const char* name;
+    std::string json;
+    std::vector<const char*> mentions;
+};
+
+UnitTestResult test_each_error_class(){
+    const std::vector<BadMap> rows = {
+        {.name = "not an object", .json = "[]", .mentions = {"Test.json", "not a JSON object"}},
+        {.name = "missing name", .json = edited("\"name\": \"TestTown\"", "\"title\": \"TestTown\""), .mentions = {"Test.json", "name is missing"}},
+        {.name = "name not a string", .json = edited("\"name\": \"TestTown\"", "\"name\": 7"), .mentions = {"name is not a string"}},
+        {.name = "source missing a field", .json = edited("\"revision\": \"abc123\"", "\"rev\": \"abc123\""), .mentions = {"source.revision is missing"}},
+        {.name = "tiles without rows", .json = edited("\"tiles\": [\"####\", \"#..~\", \"#D.S\", \"w^v#\"]", "\"tiles\": []"), .mentions = {"tiles has no rows"}},
+        {.name = "ragged row", .json = edited("\"#..~\"", "\"#..~.\""), .mentions = {"tiles[1]", "string of 4 glyphs"}},
+        {.name = "unknown glyph", .json = edited("\"#..~\"", "\"#.?~\""), .mentions = {"tiles[1]", "unknown glyph '?'", "(2, 1)"}},
+        {.name = "point not a pair", .json = edited("\"door\": [1, 2]", "\"door\": [1]"), .mentions = {"points.door", "[x, y]"}},
+        {.name = "point outside", .json = edited("\"sign\": [3, 2]", "\"sign\": [4, 2]"), .mentions = {"points.sign", "(4, 2)", "outside the 4x4 map"}},
+        {.name = "warp missing a field", .json = edited("\"to_point\": \"exit\"", "\"to\": \"exit\""), .mentions = {"warps[0].to_point is missing"}},
+        {.name = "warp field of the wrong type", .json = edited("{\"x\": 1, \"y\": 2, \"to_map\"", "{\"x\": \"1\", \"y\": 2, \"to_map\""), .mentions = {"warps[0].x is not an integer"}},
+        {.name = "object kind unknown", .json = edited("\"kind\": \"item\"", "\"kind\": \"boss\""), .mentions = {"objects[1].kind", "boss", "npc, item or sign"}},
+        {.name = "object facing unknown", .json = edited("\"facing\": \"south\"", "\"facing\": \"down\""), .mentions = {"objects[0].facing", "down", "north, east, south or west"}},
+        {.name = "wander not a box", .json = edited("\"x1\": 2, \"y1\": 2", "\"x1\": 0, \"y1\": 2"), .mentions = {"objects[0].wander is not a box"}},
+        {.name = "wander outside", .json = edited("\"x1\": 2, \"y1\": 2", "\"x1\": 2, \"y1\": 7"), .mentions = {"objects[0].wander", "(2, 7)", "outside"}},
+        {.name = "connection side unknown", .json = edited("\"side\": \"east\"", "\"side\": \"up\""), .mentions = {"connections[0].side", "up"}},
+        {.name = "patch glyph unknown", .json = edited("\"glyph\": \"#\"", "\"glyph\": \"?\""), .mentions = {"patches[0].glyph", "?", "not a tile glyph"}},
+        {.name = "patch outside", .json = edited("{\"x\": 2, \"y\": 1, \"glyph\"", "{\"x\": 2, \"y\": 9, \"glyph\""), .mentions = {"patches[0]", "(2, 9)", "outside"}},
+    };
+    for (const BadMap& row : rows){
+        if (row.json.empty()){
+            return std::string(row.name) + ": the text to edit is not in the valid map.";
+        }
+        const std::string error = parse_error(row.json);
+        if (!mentions(error, row.mentions)){
+            return std::string(row.name) + ": expected an error naming " + row.mentions.back() + ", got: \"" + error + "\"";
+        }
+    }
+    return true;
+}
+
+
+class Test_MapData : public UnitTest{
+public:
+    Test_MapData(std::string name, std::function<UnitTestResult()> body)
+        : UnitTest("Pokemon::MapData - " + std::move(name))
+        , m_body(std::move(body))
+    {}
+    virtual UnitTestResult run(Logger&, CancellableScope&) const override{
+        try{
+            return m_body();
+        }catch (Exception& e){
+            return std::string(e.name()) + ": " + e.message();
+        }
+    }
+
+private:
+    std::function<UnitTestResult()> m_body;
+};
+
+}
+
+
+void add_tests_MapData(UnitTestDatabase& database){
+    database.add<Test_MapData>("the valid map", test_valid_map);
+    database.add<Test_MapData>("lists may be left out", test_lists_may_be_left_out);
+    database.add<Test_MapData>("glyphs round-trip", test_glyphs_round_trip);
+    database.add<Test_MapData>("each error class", test_each_error_class);
+}
+
+
+
+}
+}
diff --git a/SerialPrograms/Source/Pokemon/Navigation/Pokemon_Navigation_Tests.h b/SerialPrograms/Source/Pokemon/Navigation/Pokemon_Navigation_Tests.h
index c8f2b4cefc..90ff8edd27 100644
--- a/SerialPrograms/Source/Pokemon/Navigation/Pokemon_Navigation_Tests.h
+++ b/SerialPrograms/Source/Pokemon/Navigation/Pokemon_Navigation_Tests.h
@@ -14,6 +14,7 @@ namespace Pokemon{
 
 
 void add_tests_LegPlanner(UnitTestDatabase& database);
+void add_tests_MapData(UnitTestDatabase& database);
 void add_tests_StoryEvents(UnitTestDatabase& database);
 void add_tests_StorySegments(UnitTestDatabase& database);
 
diff --git a/SerialPrograms/cmake/SourceFiles.cmake b/SerialPrograms/cmake/SourceFiles.cmake
index c93b05a880..05657bdfcc 100644
--- a/SerialPrograms/cmake/SourceFiles.cmake
+++ b/SerialPrograms/cmake/SourceFiles.cmake
@@ -1446,6 +1446,9 @@ file(GLOB LIBRARY_SOURCES
     Source/Pokemon/Navigation/Pokemon_Grid.h
     Source/Pokemon/Navigation/Pokemon_LegPlanner.h
     Source/Pokemon/Navigation/Pokemon_LegPlanner_Tests.cpp
+    Source/Pokemon/Navigation/Pokemon_MapData.cpp
+    Source/Pokemon/Navigation/Pokemon_MapData.h
+    Source/Pokemon/Navigation/Pokemon_MapData_Tests.cpp
     Source/Pokemon/Navigation/Pokemon_Navigation_Tests.h
     Source/Pokemon/Navigation/Pokemon_StoryEvents.cpp
     Source/Pokemon/Navigation/Pokemon_StoryEvents.h

From 5e315056584d46a600a5a59bf856e66759de239f Mon Sep 17 00:00:00 2001
From: dayfine <difancpa@gmail.com>
Date: Sun, 1 Nov 2026 00:26:04 -0700
Subject: [PATCH 08/19] Pokemon navigation: name the map source's JSON path for
 GCC

GCC's -Wdangling-reference flagged the source object bound from as_object()
with a temporary path string. Naming the path first silences it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01AKYzhrMnPK61XHWEch4a6E
---
 .../Source/Pokemon/Navigation/Pokemon_MapData.cpp           | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

diff --git a/SerialPrograms/Source/Pokemon/Navigation/Pokemon_MapData.cpp b/SerialPrograms/Source/Pokemon/Navigation/Pokemon_MapData.cpp
index 3121ee4d94..963a7fc496 100644
--- a/SerialPrograms/Source/Pokemon/Navigation/Pokemon_MapData.cpp
+++ b/SerialPrograms/Source/Pokemon/Navigation/Pokemon_MapData.cpp
@@ -143,9 +143,11 @@ std::vector<Item> read_list(
 
 
 MapSource read_source(const JsonObject& root, const std::string& where){
+    //  Named, since GCC warns of a reference returned for a temporary path.
     const std::string key = "source";
-    const JsonObject& object = as_object(read_field(root, key, where), where + key);
-    const std::string source_where = where + key + ".";
+    const std::string path = where + key;
+    const JsonObject& object = as_object(read_field(root, key, where), path);
+    const std::string source_where = path + ".";
     MapSource source;
     source.decomp_file = read_string(object, "decomp_file", source_where);
     source.revision = read_string(object, "revision", source_where);

From 7008f8c67259d09a85513625a87cdfe4f2d11a06 Mon Sep 17 00:00:00 2001
From: dayfine <difancpa@gmail.com>
Date: Sun, 1 Nov 2026 09:08:51 -0800
Subject: [PATCH 09/19] Pokemon navigation: weigh open stops after a wild step

A step can be marked wild (the walk may be interrupted there, e.g. by a
wild battle in tall grass). The planner tracks per step whether the leg in
progress has a wild step, marks such legs wild, and adds
LegCosts::per_open_wild_stop when one of them ends in the open: after an
interruption a leg to a wall is simply walked again, while how far an open
one got is a guess. The weight defaults to 0, so games that don't set it
plan as before.

Moved here from frlg/walk-interrupt-recount (b4d1976a3), which added it
for FRLG's Route 1. Tests on the planner's toy grid: a leg through grass is
wild, an open stop after grass is weighed, the weight needs a wild step,
and a new leg starts out not wild.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01AKYzhrMnPK61XHWEch4a6E
---
 .../Pokemon/Navigation/Pokemon_LegPlanner.h   |  32 +++--
 .../Navigation/Pokemon_LegPlanner_Tests.cpp   | 110 +++++++++++++++++-
 2 files changed, 133 insertions(+), 9 deletions(-)

diff --git a/SerialPrograms/Source/Pokemon/Navigation/Pokemon_LegPlanner.h b/SerialPrograms/Source/Pokemon/Navigation/Pokemon_LegPlanner.h
index c9d49735d9..e4c64949c1 100644
--- a/SerialPrograms/Source/Pokemon/Navigation/Pokemon_LegPlanner.h
+++ b/SerialPrograms/Source/Pokemon/Navigation/Pokemon_LegPlanner.h
@@ -6,7 +6,11 @@
  *  game decides what a single press does through its step model; the
  *  planner searches, joins steps into legs, and prefers legs that end
  *  against a wall, because the player stops there however long the button
- *  is held, while a leg that ends in the open depends on timing.
+ *  is held, while a leg that ends in the open depends on timing. It can
+ *  weigh more heavily a leg ending in the open that went through tiles
+ *  where the walk is likely to be interrupted (tall grass): after an
+ *  interruption a leg to a wall is simply walked again, while how far an
+ *  open one got is a guess.
  *
  *  A step model is a class with:
  *
@@ -60,6 +64,9 @@ struct Step{
     Direction facing = Direction::NORTH;
     //  Cost on top of LegCosts::per_tile: tall grass, a warp's fade, a dialog.
     int extra_cost = 0;
+    //  The walk can be interrupted on this step, e.g. by a wild battle in
+    //  tall grass. See LegCosts::per_open_wild_stop.
+    bool wild = false;
 };
 
 
@@ -80,6 +87,8 @@ struct Leg{
     //  WALK: holding on keeps the player on the last tile, so the leg can be
     //  held for longer than it takes and walked again after an interruption.
     bool to_wall = false;
+    //  A step of the leg is wild (Step::wild).
+    bool wild = false;
     Direction facing_after = Direction::NORTH;
     State start;
     State end;
@@ -93,6 +102,9 @@ struct LegCosts{
     //  Extra for ending a leg where the player could keep going: it has to
     //  be timed, and where an interruption leaves the player is a guess.
     int per_open_stop = 8;
+    //  Extra again when that leg has a wild step, where an interruption is
+    //  likely.
+    int per_open_wild_stop = 0;
 };
 
 
@@ -112,13 +124,15 @@ std::optional<std::vector<Leg<typename Model::State>>> plan_legs(
 
 namespace LegPlannerInternal{
 
-//  A search node: the player, the way they face (4: not known), and whether
-//  they are in the middle of a leg that could go on.
+//  A search node: the player, the way they face (4: not known), whether
+//  they are in the middle of a leg that could go on, and whether that leg
+//  had a wild step.
 template <typename State>
 struct Node{
     State state;
     int facing = 4;
     bool moving = false;
+    bool wild = false;
 
     bool operator==(const Node& other) const = default;
 };
@@ -126,7 +140,7 @@ struct Node{
 template <typename State, typename StateHash>
 struct NodeHash{
     size_t operator()(const Node<State>& node) const{
-        return StateHash()(node.state) * 10 + node.facing * 2 + (node.moving ? 1 : 0);
+        return StateHash()(node.state) * 20 + node.facing * 4 + (node.moving ? 2 : 0) + (node.wild ? 1 : 0);
     }
 };
 
@@ -142,7 +156,7 @@ int stop_cost(const Model& model, const Node<State>& node, const LegCosts& costs
     if (!node.moving || model.held_at(node.state, (Direction)node.facing)){
         return 0;
     }
-    return costs.per_open_stop;
+    return costs.per_open_stop + (node.wild ? costs.per_open_wild_stop : 0);
 }
 
 template <typename Model, typename State>
@@ -156,12 +170,14 @@ std::vector<Leg<State>> join_legs(const Model& model, const State& start, const
             && legs.back().kind == LegKind::WALK && legs.back().direction == move.direction;
         if (extends){
             legs.back().tiles++;
+            legs.back().wild |= step.wild;
         }else{
             Leg<State> leg;
             leg.kind = step.action == 0 ? LegKind::WALK : LegKind::ACTION;
             leg.action = step.action;
             leg.direction = move.direction;
             leg.tiles = 1;
+            leg.wild = step.wild;
             leg.start = before;
             legs.push_back(leg);
         }
@@ -220,7 +236,9 @@ void expand(
             continue;
         }
         const bool continues = step->action == 0 && !step->ends_leg;
-        const Node<State> next{step->next, (int)step->facing, continues};
+        const bool extends = current.moving && current.facing == (int)direction
+            && step->action == 0 && !step->starts_leg;
+        const Node<State> next{step->next, (int)step->facing, continues, (extends && current.wild) || step->wild};
         int step_cost = costs.per_tile + step->extra_cost;
         if (current.facing != (int)direction){
             step_cost += costs.per_turn + stop_cost(model, current, costs);
@@ -317,7 +335,7 @@ std::optional<std::vector<Leg<typename Model::State>>> plan_legs(
     using State = typename Model::State;
     using Node = LegPlannerInternal::Node<State>;
 
-    const Node first{start, start_facing ? (int)*start_facing : 4, false};
+    const Node first{start, start_facing ? (int)*start_facing : 4, false, false};
     LegPlannerInternal::Search<Model> search;
     const std::optional<Node> end = LegPlannerInternal::search_goal(model, search, first, at_goal, goal_facing, costs);
     if (!end){
diff --git a/SerialPrograms/Source/Pokemon/Navigation/Pokemon_LegPlanner_Tests.cpp b/SerialPrograms/Source/Pokemon/Navigation/Pokemon_LegPlanner_Tests.cpp
index de69a79762..b95c36c1f9 100644
--- a/SerialPrograms/Source/Pokemon/Navigation/Pokemon_LegPlanner_Tests.cpp
+++ b/SerialPrograms/Source/Pokemon/Navigation/Pokemon_LegPlanner_Tests.cpp
@@ -52,6 +52,7 @@ class ToyGame{
         step.facing = direction;
         if (tile == '"'){
             step.extra_cost = 5;
+            step.wild = true;
         }
         if (tile == 'W'){
             step.next = m_warp_to;
@@ -91,6 +92,9 @@ std::string describe(const std::vector<Leg<TilePos>>& legs){
         if (leg.to_wall){
             text += " (to wall)";
         }
+        if (leg.wild){
+            text += " (wild)";
+        }
         if (leg.warps){
             text += " (warp)";
         }
@@ -102,9 +106,18 @@ std::string describe(const std::vector<Leg<TilePos>>& legs){
 std::optional<std::vector<Leg<TilePos>>> plan(
     const ToyGame& game, TilePos from, TilePos to,
     std::optional<Direction> start_facing = std::nullopt,
-    std::optional<Direction> goal_facing = std::nullopt
+    std::optional<Direction> goal_facing = std::nullopt,
+    const LegCosts& costs = LegCosts()
 ){
-    return plan_legs(game, from, start_facing, std::function<bool(const TilePos&)>([to](const TilePos& pos){ return pos == to; }), goal_facing);
+    return plan_legs(game, from, start_facing, std::function<bool(const TilePos&)>([to](const TilePos& pos){ return pos == to; }), goal_facing, costs);
+}
+
+//  The open-stop weight after a wild step, high enough to outweigh any detour
+//  in these grids.
+LegCosts wild_stop_costs(){
+    LegCosts costs;
+    costs.per_open_wild_stop = 300;
+    return costs;
 }
 
 
@@ -216,6 +229,95 @@ UnitTestResult test_goal_facing(){
     return true;
 }
 
+UnitTestResult test_wild_leg(){
+    //  The only way crosses the grass: that leg is wild. One that doesn't isn't.
+    const ToyGame grass({
+        ".\"\".",
+    });
+    const auto through = plan(grass, {0, 0}, {3, 0});
+    if (!through || through->size() != 1 || !(*through)[0].wild){
+        return "Expected one wild leg:" + (through ? describe(*through) : std::string(" none"));
+    }
+    const ToyGame floor({
+        "....",
+    });
+    const auto across = plan(floor, {0, 0}, {3, 0});
+    if (!across || across->size() != 1 || (*across)[0].wild){
+        return "Expected one leg that isn't wild:" + (across ? describe(*across) : std::string(" none"));
+    }
+    return true;
+}
+
+UnitTestResult test_open_wild_stop(){
+    //  Two ways down to the goal at (3, 2): turn south right after the
+    //  grass, stopping in the open, or walk on to the wall and come back
+    //  along the bottom row. The first is shorter by more than an open stop
+    //  costs, but its open stop follows grass, so with the open-wild-stop
+    //  weight the second wins.
+    const ToyGame game({
+        ".\"\"..........",
+        "###.########.",
+        "###..........",
+    });
+    const auto plain = plan(game, {0, 0}, {3, 2});
+    if (!plain || plain->empty() || (*plain)[0].to_wall || !(*plain)[0].wild || (*plain)[0].end.x != 3){
+        return "Without the weight, expected a wild leg east to stop in the open at x = 3:" + (plain ? describe(*plain) : std::string(" none"));
+    }
+    const auto weighed = plan(game, {0, 0}, {3, 2}, std::nullopt, std::nullopt, wild_stop_costs());
+    if (!weighed || weighed->empty() || !(*weighed)[0].to_wall){
+        return "With the weight, expected to walk east to the wall:" + (weighed ? describe(*weighed) : std::string(" none"));
+    }
+    return true;
+}
+
+UnitTestResult test_open_stop_without_grass(){
+    //  The same map without grass: the weight changes nothing.
+    const ToyGame game({
+        ".............",
+        "###.########.",
+        "###..........",
+    });
+    const auto legs = plan(game, {0, 0}, {3, 2}, std::nullopt, std::nullopt, wild_stop_costs());
+    if (!legs || legs->empty() || (*legs)[0].to_wall || (*legs)[0].wild || (*legs)[0].end.x != 3){
+        return "Expected to stop in the open at x = 3:" + (legs ? describe(*legs) : std::string(" none"));
+    }
+    return true;
+}
+
+UnitTestResult test_wild_ends_with_leg(){
+    //  East through the grass to the wall, then south. The south leg has no
+    //  wild step, so it still stops in the open at (2, 2) to turn east to
+    //  the goal at (4, 2), rather than going around by the bottom row.
+    const ToyGame game({
+        ".\"\"###",
+        "##.###",
+        "##...#",
+        "##.#.#",
+        "##.#.#",
+        "##.#.#",
+        "##.#.#",
+        "##.#.#",
+        "##.#.#",
+        "##.#.#",
+        "##.#.#",
+        "##.#.#",
+        "##...#",
+    });
+    const auto legs = plan(game, {0, 0}, {4, 2}, std::nullopt, std::nullopt, wild_stop_costs());
+    if (!legs || legs->size() != 3){
+        return "Expected 3 legs:" + (legs ? describe(*legs) : std::string(" none"));
+    }
+    const Leg<TilePos>& east = (*legs)[0];
+    const Leg<TilePos>& south = (*legs)[1];
+    if (!east.wild || !east.to_wall){
+        return "Expected a wild leg east to the wall:" + describe(*legs);
+    }
+    if (south.wild || south.to_wall || !(south.end == TilePos{2, 2})){
+        return "Expected the south leg to stop in the open at (2, 2):" + describe(*legs);
+    }
+    return true;
+}
+
 UnitTestResult test_unreachable(){
     const ToyGame game({
         ".#.",
@@ -252,6 +354,10 @@ void add_tests_LegPlanner(UnitTestDatabase& database){
     database.add<Test_LegPlanner>("a warp ends the leg", test_warp_ends_leg);
     database.add<Test_LegPlanner>("turns to face the goal", test_goal_facing);
     database.add<Test_LegPlanner>("nothing through a wall", test_unreachable);
+    database.add<Test_LegPlanner>("a leg through grass is wild", test_wild_leg);
+    database.add<Test_LegPlanner>("an open stop after grass is weighed", test_open_wild_stop);
+    database.add<Test_LegPlanner>("the weight needs a wild step", test_open_stop_without_grass);
+    database.add<Test_LegPlanner>("a new leg is not wild", test_wild_ends_with_leg);
 }
 
 

From b426f749f93a3354a4749e26971697db24e7be15 Mon Sep 17 00:00:00 2001
From: dayfine <difancpa@gmail.com>
Date: Sun, 1 Nov 2026 09:40:25 -0800
Subject: [PATCH 10/19] CMake: build data files into the program as text
 (pa_embed_text_files)

Map tests need their maps in CI, which has none of Packages' map files, and
reviewers should see the maps as plain .json files. pa_embed_text_files()
reads a folder's *.json at configure time and writes a C++ file to the build
folder that returns each file's name and text; nothing generated is
committed. Each text is split into raw string literals of at most 16000
bytes, under MSVC's limit. Adding or changing a file reruns CMake.

Its test reads back two maps in Pokemon/Navigation/TestMaps, one longer
than a single literal may be, and parses them with parse_map().

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01AKYzhrMnPK61XHWEch4a6E
---
 SerialPrograms/CMakeLists.txt                 |   5 +
 .../Navigation/Pokemon_MapData_Tests.cpp      |  27 ++++
 .../Navigation/Pokemon_Navigation_Tests.h     |   7 +
 .../Pokemon/Navigation/TestMaps/BigField.json | 140 ++++++++++++++++++
 .../Pokemon/Navigation/TestMaps/Cave.json     |  11 ++
 SerialPrograms/cmake/EmbedTextFiles.cmake     |  85 +++++++++++
 6 files changed, 275 insertions(+)
 create mode 100644 SerialPrograms/Source/Pokemon/Navigation/TestMaps/BigField.json
 create mode 100644 SerialPrograms/Source/Pokemon/Navigation/TestMaps/Cave.json
 create mode 100644 SerialPrograms/cmake/EmbedTextFiles.cmake

diff --git a/SerialPrograms/CMakeLists.txt b/SerialPrograms/CMakeLists.txt
index 35bb597e32..d0966df32f 100644
--- a/SerialPrograms/CMakeLists.txt
+++ b/SerialPrograms/CMakeLists.txt
@@ -193,6 +193,11 @@ include(cmake/CoreLib.cmake)
 # Create the GUI library
 add_library(SerialProgramsLib STATIC ${CORE_LIBRARY_SOURCES} ${LIBRARY_SOURCES})
 
+# Data files built into the program (see cmake/EmbedTextFiles.cmake).
+include(cmake/EmbedTextFiles.cmake)
+pa_embed_text_files(SerialProgramsLib Source/Pokemon/Navigation/TestMaps
+    Pokemon/Navigation/Pokemon_Navigation_Tests.h PokemonAutomation::Pokemon navigation_test_map_json)
+
 
 # Create binary target
 if (APPLE)
diff --git a/SerialPrograms/Source/Pokemon/Navigation/Pokemon_MapData_Tests.cpp b/SerialPrograms/Source/Pokemon/Navigation/Pokemon_MapData_Tests.cpp
index 6ea7ad110b..6d5eee680f 100644
--- a/SerialPrograms/Source/Pokemon/Navigation/Pokemon_MapData_Tests.cpp
+++ b/SerialPrograms/Source/Pokemon/Navigation/Pokemon_MapData_Tests.cpp
@@ -194,6 +194,32 @@ class Test_MapData : public UnitTest{
     std::function<UnitTestResult()> m_body;
 };
 
+//  The maps in TestMaps/, read back from the program: the small one, and one
+//  longer than a string literal may be, which the build splits.
+UnitTestResult test_built_in_maps(){
+    const std::vector<std::pair<std::string, std::string>>& files = navigation_test_map_json();
+    if (files.size() != 2 || files[0].first != "BigField" || files[1].first != "Cave"){
+        return "Expected BigField and Cave, sorted by name.";
+    }
+    const MapData big = parse_map(parse_json(files[0].second), "BigField.json");
+    if (files[0].second.size() <= 16000 || big.tiles.width != 130 || big.tiles.height != 130){
+        return "Expected BigField's 130x130 tiles, over 16000 bytes of text.";
+    }
+    for (int y = 0; y < 130; y++){
+        for (int x = 0; x < 130; x++){
+            const bool border = x == 0 || y == 0 || x == 129 || y == 129;
+            if (big.tiles.at(TilePos{x, y}) != (border ? TileKind::WALL : TileKind::OPEN)){
+                return "BigField's tile (" + std::to_string(x) + ", " + std::to_string(y) + ") is wrong.";
+            }
+        }
+    }
+    const MapData cave = parse_map(parse_json(files[1].second), "Cave.json");
+    if (cave.tiles.width != 3 || cave.tiles.height != 1){
+        return "Expected Cave's 3x1 tiles.";
+    }
+    return true;
+}
+
 }
 
 
@@ -202,6 +228,7 @@ void add_tests_MapData(UnitTestDatabase& database){
     database.add<Test_MapData>("lists may be left out", test_lists_may_be_left_out);
     database.add<Test_MapData>("glyphs round-trip", test_glyphs_round_trip);
     database.add<Test_MapData>("each error class", test_each_error_class);
+    database.add<Test_MapData>("maps built into the program", test_built_in_maps);
 }
 
 
diff --git a/SerialPrograms/Source/Pokemon/Navigation/Pokemon_Navigation_Tests.h b/SerialPrograms/Source/Pokemon/Navigation/Pokemon_Navigation_Tests.h
index 90ff8edd27..73eac9841a 100644
--- a/SerialPrograms/Source/Pokemon/Navigation/Pokemon_Navigation_Tests.h
+++ b/SerialPrograms/Source/Pokemon/Navigation/Pokemon_Navigation_Tests.h
@@ -7,6 +7,9 @@
 #ifndef PokemonAutomation_Pokemon_Navigation_Tests_H
 #define PokemonAutomation_Pokemon_Navigation_Tests_H
 
+#include <string>
+#include <utility>
+#include <vector>
 #include "Common/Cpp/TestRunners/UnitTestDatabase.h"
 
 namespace PokemonAutomation{
@@ -18,6 +21,10 @@ void add_tests_MapData(UnitTestDatabase& database);
 void add_tests_StoryEvents(UnitTestDatabase& database);
 void add_tests_StorySegments(UnitTestDatabase& database);
 
+//  (name, JSON text) of each map in Pokemon/Navigation/TestMaps/, built into
+//  the program by pa_embed_text_files() (cmake/EmbedTextFiles.cmake).
+const std::vector<std::pair<std::string, std::string>>& navigation_test_map_json();
+
 
 
 }
diff --git a/SerialPrograms/Source/Pokemon/Navigation/TestMaps/BigField.json b/SerialPrograms/Source/Pokemon/Navigation/TestMaps/BigField.json
new file mode 100644
index 0000000000..84cafdb5f2
--- /dev/null
+++ b/SerialPrograms/Source/Pokemon/Navigation/TestMaps/BigField.json
@@ -0,0 +1,140 @@
+{
+    "name": "BigField",
+    "source": {
+        "decomp_file": "none: a test map for pa_embed_text_files()",
+        "revision": "none",
+        "date": "2026-11-01"
+    },
+    "tiles": [
+        "##################################################################################################################################",
+        "#................................................................................................................................#",
+        "#................................................................................................................................#",
+        "#................................................................................................................................#",
+        "#................................................................................................................................#",
+        "#................................................................................................................................#",
+        "#................................................................................................................................#",
+        "#................................................................................................................................#",
+        "#................................................................................................................................#",
+        "#................................................................................................................................#",
+        "#................................................................................................................................#",
+        "#................................................................................................................................#",
+        "#................................................................................................................................#",
+        "#................................................................................................................................#",
+        "#................................................................................................................................#",
+        "#................................................................................................................................#",
+        "#................................................................................................................................#",
+        "#................................................................................................................................#",
+        "#................................................................................................................................#",
+        "#................................................................................................................................#",
+        "#................................................................................................................................#",
+        "#................................................................................................................................#",
+        "#................................................................................................................................#",
+        "#................................................................................................................................#",
+        "#................................................................................................................................#",
+        "#................................................................................................................................#",
+        "#................................................................................................................................#",
+        "#................................................................................................................................#",
+        "#................................................................................................................................#",
+        "#................................................................................................................................#",
+        "#................................................................................................................................#",
+        "#................................................................................................................................#",
+        "#................................................................................................................................#",
+        "#................................................................................................................................#",
+        "#................................................................................................................................#",
+        "#................................................................................................................................#",
+        "#................................................................................................................................#",
+        "#................................................................................................................................#",
+        "#................................................................................................................................#",
+        "#................................................................................................................................#",
+        "#................................................................................................................................#",
+        "#................................................................................................................................#",
+        "#................................................................................................................................#",
+        "#................................................................................................................................#",
+        "#................................................................................................................................#",
+        "#................................................................................................................................#",
+        "#................................................................................................................................#",
+        "#................................................................................................................................#",
+        "#................................................................................................................................#",
+        "#................................................................................................................................#",
+        "#................................................................................................................................#",
+        "#................................................................................................................................#",
+        "#................................................................................................................................#",
+        "#................................................................................................................................#",
+        "#................................................................................................................................#",
+        "#................................................................................................................................#",
+        "#................................................................................................................................#",
+        "#................................................................................................................................#",
+        "#................................................................................................................................#",
+        "#................................................................................................................................#",
+        "#................................................................................................................................#",
+        "#................................................................................................................................#",
+        "#................................................................................................................................#",
+        "#................................................................................................................................#",
+        "#................................................................................................................................#",
+        "#................................................................................................................................#",
+        "#................................................................................................................................#",
+        "#................................................................................................................................#",
+        "#................................................................................................................................#",
+        "#................................................................................................................................#",
+        "#................................................................................................................................#",
+        "#................................................................................................................................#",
+        "#................................................................................................................................#",
+        "#................................................................................................................................#",
+        "#................................................................................................................................#",
+        "#................................................................................................................................#",
+        "#................................................................................................................................#",
+        "#................................................................................................................................#",
+        "#................................................................................................................................#",
+        "#................................................................................................................................#",
+        "#................................................................................................................................#",
+        "#................................................................................................................................#",
+        "#................................................................................................................................#",
+        "#................................................................................................................................#",
+        "#................................................................................................................................#",
+        "#................................................................................................................................#",
+        "#................................................................................................................................#",
+        "#................................................................................................................................#",
+        "#................................................................................................................................#",
+        "#................................................................................................................................#",
+        "#................................................................................................................................#",
+        "#................................................................................................................................#",
+        "#................................................................................................................................#",
+        "#................................................................................................................................#",
+        "#................................................................................................................................#",
+        "#................................................................................................................................#",
+        "#................................................................................................................................#",
+        "#................................................................................................................................#",
+        "#................................................................................................................................#",
+        "#................................................................................................................................#",
+        "#................................................................................................................................#",
+        "#................................................................................................................................#",
+        "#................................................................................................................................#",
+        "#................................................................................................................................#",
+        "#................................................................................................................................#",
+        "#................................................................................................................................#",
+        "#................................................................................................................................#",
+        "#................................................................................................................................#",
+        "#................................................................................................................................#",
+        "#................................................................................................................................#",
+        "#................................................................................................................................#",
+        "#................................................................................................................................#",
+        "#................................................................................................................................#",
+        "#................................................................................................................................#",
+        "#................................................................................................................................#",
+        "#................................................................................................................................#",
+        "#................................................................................................................................#",
+        "#................................................................................................................................#",
+        "#................................................................................................................................#",
+        "#................................................................................................................................#",
+        "#................................................................................................................................#",
+        "#................................................................................................................................#",
+        "#................................................................................................................................#",
+        "#................................................................................................................................#",
+        "#................................................................................................................................#",
+        "#................................................................................................................................#",
+        "#................................................................................................................................#",
+        "#................................................................................................................................#",
+        "#................................................................................................................................#",
+        "##################################################################################################################################"
+    ]
+}
diff --git a/SerialPrograms/Source/Pokemon/Navigation/TestMaps/Cave.json b/SerialPrograms/Source/Pokemon/Navigation/TestMaps/Cave.json
new file mode 100644
index 0000000000..c4fe9bf2a6
--- /dev/null
+++ b/SerialPrograms/Source/Pokemon/Navigation/TestMaps/Cave.json
@@ -0,0 +1,11 @@
+{
+    "name": "Cave",
+    "source": {
+        "decomp_file": "none: a test map for pa_embed_text_files()",
+        "revision": "none",
+        "date": "2026-11-01"
+    },
+    "tiles": [
+        "#.#"
+    ]
+}
diff --git a/SerialPrograms/cmake/EmbedTextFiles.cmake b/SerialPrograms/cmake/EmbedTextFiles.cmake
new file mode 100644
index 0000000000..3bf5f4ae91
--- /dev/null
+++ b/SerialPrograms/cmake/EmbedTextFiles.cmake
@@ -0,0 +1,85 @@
+# pa_embed_text_files(): builds the text of data files into the program.
+#
+#     pa_embed_text_files(<target> <folder> <header> <namespace> <function>)
+#
+# Reads every <folder>/*.json (relative to the calling CMakeLists.txt) and
+# writes a C++ file to the build folder, compiled into <target>, that defines
+# in <namespace>
+#
+#     const std::vector<std::pair<std::string, std::string>>& <function>();
+#
+# returning (file name without ".json", file text) for each file, sorted by
+# name. <header>, an include path, declares that function. The files stay
+# plain files in the repo; nothing generated is committed. Adding, removing or
+# changing a file reruns CMake at the next build.
+#
+# Each text is split into raw string literals of at most 16000 bytes, joined
+# at run time, so no literal exceeds MSVC's limit of 16380 bytes.
+
+function(pa_embed_text_files TARGET FOLDER HEADER NAMESPACE FUNCTION)
+    file(GLOB FILES CONFIGURE_DEPENDS "${CMAKE_CURRENT_SOURCE_DIR}/${FOLDER}/*.json")
+    if(NOT FILES)
+        message(FATAL_ERROR "pa_embed_text_files(): no .json files in ${FOLDER}.")
+    endif()
+    list(SORT FILES)
+    set_property(DIRECTORY APPEND PROPERTY CMAKE_CONFIGURE_DEPENDS ${FILES})
+
+    set(ENTRIES "")
+    foreach(FILE IN LISTS FILES)
+        get_filename_component(NAME "${FILE}" NAME_WLE)
+        file(READ "${FILE}" TEXT)
+        string(FIND "${TEXT}" ")json\"" CLOSE)
+        string(LENGTH "${TEXT}" LENGTH)
+        if(NOT CLOSE EQUAL -1 OR LENGTH EQUAL 0)
+            message(FATAL_ERROR "pa_embed_text_files(): ${FILE} is empty or contains )json\".")
+        endif()
+        set(PARTS "")
+        set(START 0)
+        while(START LESS LENGTH)
+            string(SUBSTRING "${TEXT}" ${START} 16000 PART)
+            string(APPEND PARTS "\n            R\"json(${PART})json\",")
+            math(EXPR START "${START} + 16000")
+        endwhile()
+        string(APPEND ENTRIES "        {\"${NAME}\", join({${PARTS}\n        })},\n")
+    endforeach()
+
+    set(OUTPUT "${CMAKE_CURRENT_BINARY_DIR}/EmbeddedText/${FUNCTION}.cpp")
+    file(WRITE "${OUTPUT}.new"
+"//  Generated by SerialPrograms/cmake/EmbedTextFiles.cmake from
+//  ${FOLDER}/*.json. Do not edit.
+
+#include <initializer_list>
+#include <string>
+#include <utility>
+#include <vector>
+#include \"${HEADER}\"
+
+namespace ${NAMESPACE}{
+
+
+namespace{
+
+std::string join(std::initializer_list<const char*> parts){
+    std::string text;
+    for (const char* part : parts){
+        text += part;
+    }
+    return text;
+}
+
+}
+
+
+const std::vector<std::pair<std::string, std::string>>& ${FUNCTION}(){
+    static const std::vector<std::pair<std::string, std::string>> FILES{
+${ENTRIES}    };
+    return FILES;
+}
+
+
+}
+")
+    #   Copied only if it changed, so an unchanged file isn't recompiled.
+    configure_file("${OUTPUT}.new" "${OUTPUT}" COPYONLY)
+    target_sources(${TARGET} PRIVATE "${OUTPUT}")
+endfunction()

From c7a2136f1472d94eb7f73b32ea75b49827ec9be0 Mon Sep 17 00:00:00 2001
From: dayfine <difancpa@gmail.com>
Date: Sun, 1 Nov 2026 11:08:11 -0800
Subject: [PATCH 11/19] Pokemon navigation: the route log lines, shared by the
 games' walkers

BDSP AutoStory's route lines (the plan, each leg as it starts, a replan
where the player was seen, a trainer stopping us, the arrival), lifted
from PokemonBDSP_AutoStory_RouteWalk.cpp so that every game's walker logs
the same lines, with what other games need: tiles of named maps rather
than BDSP's world tiles, one tile or a set, legs onto a warp, Surf and
turns, and two new lines: where a leg ended and how that is known
(walked, assumed after an interrupt, unknown), and where the player was
found again after a stop.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01AKYzhrMnPK61XHWEch4a6E
---
 .../ComputerPrograms_UnitTestRunner.cpp       |   1 +
 .../Navigation/Pokemon_Navigation_Tests.h     |   1 +
 .../Pokemon/Navigation/Pokemon_RouteLog.cpp   |  98 +++++++++++
 .../Pokemon/Navigation/Pokemon_RouteLog.h     | 120 +++++++++++++
 .../Navigation/Pokemon_RouteLog_Tests.cpp     | 162 ++++++++++++++++++
 SerialPrograms/cmake/SourceFiles.cmake        |   3 +
 6 files changed, 385 insertions(+)
 create mode 100644 SerialPrograms/Source/Pokemon/Navigation/Pokemon_RouteLog.cpp
 create mode 100644 SerialPrograms/Source/Pokemon/Navigation/Pokemon_RouteLog.h
 create mode 100644 SerialPrograms/Source/Pokemon/Navigation/Pokemon_RouteLog_Tests.cpp

diff --git a/SerialPrograms/Source/ComputerPrograms/ComputerPrograms_UnitTestRunner.cpp b/SerialPrograms/Source/ComputerPrograms/ComputerPrograms_UnitTestRunner.cpp
index 2e17398c46..a3a4cc2fcd 100644
--- a/SerialPrograms/Source/ComputerPrograms/ComputerPrograms_UnitTestRunner.cpp
+++ b/SerialPrograms/Source/ComputerPrograms/ComputerPrograms_UnitTestRunner.cpp
@@ -63,6 +63,7 @@ UnitTestDatabase make_UNIT_TESTS_ALL(){
     Kernels::add_tests(ret);
     Pokemon::add_tests_LegPlanner(ret);
     Pokemon::add_tests_MapData(ret);
+    Pokemon::add_tests_RouteLog(ret);
     Pokemon::add_tests_StoryEvents(ret);
     Pokemon::add_tests_StorySegments(ret);
     NintendoSwitch::add_tests_CheckOnlineDetector(ret);
diff --git a/SerialPrograms/Source/Pokemon/Navigation/Pokemon_Navigation_Tests.h b/SerialPrograms/Source/Pokemon/Navigation/Pokemon_Navigation_Tests.h
index 73eac9841a..3d51443174 100644
--- a/SerialPrograms/Source/Pokemon/Navigation/Pokemon_Navigation_Tests.h
+++ b/SerialPrograms/Source/Pokemon/Navigation/Pokemon_Navigation_Tests.h
@@ -18,6 +18,7 @@ namespace Pokemon{
 
 void add_tests_LegPlanner(UnitTestDatabase& database);
 void add_tests_MapData(UnitTestDatabase& database);
+void add_tests_RouteLog(UnitTestDatabase& database);
 void add_tests_StoryEvents(UnitTestDatabase& database);
 void add_tests_StorySegments(UnitTestDatabase& database);
 
diff --git a/SerialPrograms/Source/Pokemon/Navigation/Pokemon_RouteLog.cpp b/SerialPrograms/Source/Pokemon/Navigation/Pokemon_RouteLog.cpp
new file mode 100644
index 0000000000..3fbf5bb16f
--- /dev/null
+++ b/SerialPrograms/Source/Pokemon/Navigation/Pokemon_RouteLog.cpp
@@ -0,0 +1,98 @@
+/*  Route Log
+ *
+ *  From: https://github.com/PokemonAutomation/
+ *
+ */
+
+#include <format>
+#include "Pokemon_RouteLog.h"
+
+namespace PokemonAutomation{
+namespace Pokemon{
+
+
+std::string to_string(const RouteTile& tile){
+    return tile.map + " " + to_string(tile.pos);
+}
+
+std::string describe(const std::vector<RouteTile>& tiles){
+    if (tiles.empty()){
+        return "an unknown tile";
+    }
+    std::string out;
+    for (const RouteTile& tile : tiles){
+        out += (out.empty() ? "" : ", ") + to_string(tile);
+    }
+    return out;
+}
+
+std::string to_string(const RouteLogLeg& leg){
+    const std::string direction = direction_name(leg.direction);
+    switch (leg.action){
+    case RouteLegAction::SURF:
+        return "surf " + direction;
+    case RouteLegAction::FACE:
+        return "face " + direction;
+    case RouteLegAction::WALK:
+        break;
+    }
+    const char* end = leg.end == RouteLegEnd::WALL ? " (to wall)" : leg.end == RouteLegEnd::WARP ? " (warp)" : " (open)";
+    return direction + " " + std::to_string(leg.tiles) + end;
+}
+
+const char* basis_name(EndBasis basis){
+    switch (basis){
+    case EndBasis::WALKED:
+        return "walked";
+    case EndBasis::ASSUMED:
+        return "assumed";
+    case EndBasis::UNKNOWN:
+        return "unknown";
+    }
+    return "?";
+}
+
+
+std::string route_plan_line(const std::string& label, const std::vector<RouteTile>& from, const std::vector<PlannedRouteLeg>& legs){
+    std::string text = label + ": plan from " + describe(from) + ":";
+    for (const PlannedRouteLeg& leg : legs){
+        text += "\n    " + to_string(leg.leg) + " to " + describe(leg.after);
+    }
+    return text;
+}
+
+std::string route_leg_line(size_t number, size_t count, const PlannedRouteLeg& leg){
+    return std::format("Leg {}/{}: {} to {}", number, count, to_string(leg.leg), describe(leg.after));
+}
+
+std::string route_leg_end_line(
+    const std::string& label, const RouteLogLeg& leg,
+    const std::vector<RouteTile>& at, EndBasis basis, const std::string& why
+){
+    const std::string how = why.empty() ? basis_name(basis) : std::string(basis_name(basis)) + ": " + why;
+    return std::format("{}: {}: ended at {} ({}).", label, to_string(leg), describe(at), how);
+}
+
+std::string route_replan_line(
+    const std::string& label, const RouteLogLeg& leg,
+    const std::string& what, const std::vector<RouteTile>& at
+){
+    return std::format("{}: {}: {}, at {}; planning again.", label, to_string(leg), what, describe(at));
+}
+
+std::string route_found_line(const std::string& label, const std::vector<RouteTile>& at, size_t holds){
+    return std::format("{}: found again at {}, after {} hold(s).", label, describe(at), holds);
+}
+
+std::string route_trainer_line(const std::string& label, const std::string& who, const std::vector<RouteTile>& at){
+    return label + ": " + who + " stopped us about " + describe(at) + ".";
+}
+
+std::string route_arrived_line(const std::string& label, const std::vector<RouteTile>& at){
+    return label + ": arrived at " + describe(at) + ".";
+}
+
+
+
+}
+}
diff --git a/SerialPrograms/Source/Pokemon/Navigation/Pokemon_RouteLog.h b/SerialPrograms/Source/Pokemon/Navigation/Pokemon_RouteLog.h
new file mode 100644
index 0000000000..5f5d4f09a4
--- /dev/null
+++ b/SerialPrograms/Source/Pokemon/Navigation/Pokemon_RouteLog.h
@@ -0,0 +1,120 @@
+/*  Route Log
+ *
+ *  From: https://github.com/PokemonAutomation/
+ *
+ *  The log lines a route walk writes, shared by the games' walkers so that
+ *  every game's log reads the same and devtools/maps can draw any run's
+ *  routes from it. These are BDSP AutoStory's route lines, lifted from
+ *  PokemonBDSP_AutoStory_RouteWalk.cpp, with what the other games need:
+ *
+ *      [Route] To the grass: plan from Route 202 (15, 25), Route 202 (16, 25):
+ *          east 15 (to wall) to Route 202 (23, 25), Route 202 (30, 26)
+ *          north 5 (to wall) to Route 202 (23, 24)
+ *      [Route] Leg 1/2: east 15 (to wall) to Route 202 (23, 25), Route 202 (30, 26)
+ *      [Route] To the grass: east 15 (to wall): ended at Route 202 (23, 25) (walked).
+ *      [Route] To the grass: north 5 (to wall): stopped early after about 2 tiles, at Route 202 (23, 23); planning again.
+ *      [Route] To the grass: found again at Route 202 (22, 24), after 2 holds.
+ *      [Route] To the grass: arrived at Route 202 (23, 24).
+ *
+ *  A position is a set of tiles: BDSP plans from every tile the player may
+ *  be on, FRLG from the one it is on. A leg's end says how it is known:
+ *  walked (as planned, or seen), assumed (taken to have ended as planned
+ *  after something interrupted it), or unknown.
+ *
+ *  The functions return a line without the "[Route] " tag, which
+ *  ROUTE_LOG_TAG holds; the caller logs it.
+ *
+ */
+
+#ifndef PokemonAutomation_Pokemon_RouteLog_H
+#define PokemonAutomation_Pokemon_RouteLog_H
+
+#include <cstddef>
+#include <string>
+#include <vector>
+#include "Pokemon_Grid.h"
+
+namespace PokemonAutomation{
+namespace Pokemon{
+
+
+inline constexpr const char* ROUTE_LOG_TAG = "[Route] ";
+
+//  A tile of a named map.
+struct RouteTile{
+    std::string map;
+    TilePos pos;
+};
+//  "Route 202 (23, 25)".
+std::string to_string(const RouteTile& tile);
+//  The tiles, comma-separated; "an unknown tile" for none.
+std::string describe(const std::vector<RouteTile>& tiles);
+
+
+enum class RouteLegAction{
+    WALK,
+    SURF,
+    FACE,
+};
+
+//  How a leg ends: at a wall, on a warp, or where it is timed to.
+enum class RouteLegEnd{
+    OPEN,
+    WALL,
+    WARP,
+};
+
+struct RouteLogLeg{
+    RouteLegAction action = RouteLegAction::WALK;
+    Direction direction = Direction::NORTH;
+    size_t tiles = 0;
+    RouteLegEnd end = RouteLegEnd::OPEN;
+};
+//  "east 15 (to wall)", "south 4 (open)", "north 1 (warp)", "surf east",
+//  "face west".
+std::string to_string(const RouteLogLeg& leg);
+
+//  A planned leg and the tiles it may end on.
+struct PlannedRouteLeg{
+    RouteLogLeg leg;
+    std::vector<RouteTile> after;
+};
+
+//  How the end of a walked leg is known.
+enum class EndBasis{
+    WALKED,     //  walked as planned, or seen
+    ASSUMED,    //  taken to have ended as planned after an interrupt
+    UNKNOWN,    //  stopped somewhere on the way
+};
+const char* basis_name(EndBasis basis);
+
+
+//  "<label>: plan from <tiles>:", then a line per leg.
+std::string route_plan_line(const std::string& label, const std::vector<RouteTile>& from, const std::vector<PlannedRouteLeg>& legs);
+//  "Leg <number>/<count>: <leg> to <tiles>", as the leg starts.
+std::string route_leg_line(size_t number, size_t count, const PlannedRouteLeg& leg);
+//  "<label>: <leg>: ended at <tiles> (<basis>).", or "(<basis>: <why>)".
+std::string route_leg_end_line(
+    const std::string& label, const RouteLogLeg& leg,
+    const std::vector<RouteTile>& at, EndBasis basis, const std::string& why
+);
+//  "<label>: <leg>: <what>, at <tiles>; planning again.": the leg stopped
+//  short, where the player was seen to be, and the route is planned again
+//  from there.
+std::string route_replan_line(
+    const std::string& label, const RouteLogLeg& leg,
+    const std::string& what, const std::vector<RouteTile>& at
+);
+//  "<label>: found again at <tiles>, after <holds> hold(s).": after a stop
+//  where the player wasn't seen, holds to walls found them.
+std::string route_found_line(const std::string& label, const std::vector<RouteTile>& at, size_t holds);
+//  "<label>: <who> stopped us about <tiles>."
+std::string route_trainer_line(const std::string& label, const std::string& who, const std::vector<RouteTile>& at);
+//  "<label>: arrived at <tiles>."
+std::string route_arrived_line(const std::string& label, const std::vector<RouteTile>& at);
+
+
+
+}
+}
+#endif
diff --git a/SerialPrograms/Source/Pokemon/Navigation/Pokemon_RouteLog_Tests.cpp b/SerialPrograms/Source/Pokemon/Navigation/Pokemon_RouteLog_Tests.cpp
new file mode 100644
index 0000000000..6841138f63
--- /dev/null
+++ b/SerialPrograms/Source/Pokemon/Navigation/Pokemon_RouteLog_Tests.cpp
@@ -0,0 +1,162 @@
+/*  Route Log Tests
+ *
+ *  From: https://github.com/PokemonAutomation/
+ *
+ *  The route log lines, word for word: BDSP-style position sets (several
+ *  tiles, map names with spaces) and FRLG-style single tiles.
+ *
+ */
+
+#include <functional>
+#include <string>
+#include <utility>
+#include <vector>
+#include "Common/Cpp/Exceptions.h"
+#include "Common/Cpp/TestRunners/UnitTest.h"
+#include "Pokemon_Navigation_Tests.h"
+#include "Pokemon_RouteLog.h"
+
+namespace PokemonAutomation{
+namespace Pokemon{
+
+
+namespace{
+
+class Test_RouteLog : public UnitTest{
+public:
+    Test_RouteLog(std::string name, std::function<UnitTestResult()> body)
+        : UnitTest("Pokemon::RouteLog - " + std::move(name))
+        , m_body(std::move(body))
+    {}
+    virtual UnitTestResult run(Logger&, CancellableScope&) const override{
+        try{
+            return m_body();
+        }catch (Exception& e){
+            return std::string(e.name()) + ": " + e.message();
+        }
+    }
+
+private:
+    std::function<UnitTestResult()> m_body;
+};
+
+//  A BDSP-style position: every tile the player may be on.
+const std::vector<RouteTile> BDSP_FROM{{"Route 202", {15, 25}}, {"Route 202", {16, 25}}};
+const std::vector<RouteTile> BDSP_WALL{{"Route 202", {23, 25}}, {"Route 202", {30, 26}}};
+//  An FRLG-style position: the one tile.
+const std::vector<RouteTile> FRLG_TILE{{"Route1", {12, 21}}};
+
+const RouteLogLeg EAST_TO_WALL{.action = RouteLegAction::WALK, .direction = Direction::EAST, .tiles = 15, .end = RouteLegEnd::WALL};
+const RouteLogLeg NORTH_OPEN{.action = RouteLegAction::WALK, .direction = Direction::NORTH, .tiles = 8, .end = RouteLegEnd::OPEN};
+
+struct LineCase{
+    const char* name;
+    std::string line;
+    const char* expected;
+};
+
+std::vector<LineCase> line_cases(){
+    return {
+        {.name = "leg to a wall", .line = to_string(EAST_TO_WALL), .expected = "east 15 (to wall)"},
+        {.name = "open leg", .line = to_string(NORTH_OPEN), .expected = "north 8 (open)"},
+        {
+            .name = "leg onto a warp",
+            .line = to_string(RouteLogLeg{.action = RouteLegAction::WALK, .direction = Direction::SOUTH, .tiles = 1, .end = RouteLegEnd::WARP}),
+            .expected = "south 1 (warp)",
+        },
+        {
+            .name = "surf",
+            .line = to_string(RouteLogLeg{.action = RouteLegAction::SURF, .direction = Direction::EAST, .tiles = 0, .end = RouteLegEnd::OPEN}),
+            .expected = "surf east",
+        },
+        {
+            .name = "face",
+            .line = to_string(RouteLogLeg{.action = RouteLegAction::FACE, .direction = Direction::WEST, .tiles = 0, .end = RouteLegEnd::OPEN}),
+            .expected = "face west",
+        },
+        {
+            .name = "plan from a set of tiles",
+            .line = route_plan_line("To the grass", BDSP_FROM, {
+                {.leg = EAST_TO_WALL, .after = BDSP_WALL},
+                {.leg = NORTH_OPEN, .after = {{"Route 202", {23, 17}}}},
+            }),
+            .expected =
+                "To the grass: plan from Route 202 (15, 25), Route 202 (16, 25):\n"
+                "    east 15 (to wall) to Route 202 (23, 25), Route 202 (30, 26)\n"
+                "    north 8 (open) to Route 202 (23, 17)",
+        },
+        {
+            .name = "plan from one tile",
+            .line = route_plan_line("00.05/2 below_mart_door", FRLG_TILE, {{.leg = NORTH_OPEN, .after = {{"Route1", {12, 13}}}}}),
+            .expected =
+                "00.05/2 below_mart_door: plan from Route1 (12, 21):\n"
+                "    north 8 (open) to Route1 (12, 13)",
+        },
+        {
+            .name = "plan from an unknown tile",
+            .line = route_plan_line("x", {}, {}),
+            .expected = "x: plan from an unknown tile:",
+        },
+        {
+            .name = "leg as it starts",
+            .line = route_leg_line(1, 5, {.leg = EAST_TO_WALL, .after = BDSP_WALL}),
+            .expected = "Leg 1/5: east 15 (to wall) to Route 202 (23, 25), Route 202 (30, 26)",
+        },
+        {
+            .name = "leg walked",
+            .line = route_leg_end_line("To the grass", EAST_TO_WALL, BDSP_WALL, EndBasis::WALKED, ""),
+            .expected = "To the grass: east 15 (to wall): ended at Route 202 (23, 25), Route 202 (30, 26) (walked).",
+        },
+        {
+            .name = "leg assumed",
+            .line = route_leg_end_line("r", NORTH_OPEN, FRLG_TILE, EndBasis::ASSUMED, "after a wild battle"),
+            .expected = "r: north 8 (open): ended at Route1 (12, 21) (assumed: after a wild battle).",
+        },
+        {
+            .name = "leg end unknown",
+            .line = route_leg_end_line("r", NORTH_OPEN, {}, EndBasis::UNKNOWN, "stopped by a wild battle"),
+            .expected = "r: north 8 (open): ended at an unknown tile (unknown: stopped by a wild battle).",
+        },
+        {
+            .name = "replan where seen",
+            .line = route_replan_line("To the grass", EAST_TO_WALL, "stopped early after about 3 tiles", BDSP_FROM),
+            .expected = "To the grass: east 15 (to wall): stopped early after about 3 tiles, at Route 202 (15, 25), Route 202 (16, 25); planning again.",
+        },
+        {
+            .name = "found again",
+            .line = route_found_line("r", FRLG_TILE, 2),
+            .expected = "r: found again at Route1 (12, 21), after 2 hold(s).",
+        },
+        {
+            .name = "trainer",
+            .line = route_trainer_line("To the grass", "Youngster Tristan", {{"Route 202", {20, 10}}}),
+            .expected = "To the grass: Youngster Tristan stopped us about Route 202 (20, 10).",
+        },
+        {
+            .name = "arrived",
+            .line = route_arrived_line("To the grass", {{"Route 202", {20, 25}}}),
+            .expected = "To the grass: arrived at Route 202 (20, 25).",
+        },
+    };
+}
+
+UnitTestResult test_lines(){
+    for (const LineCase& c : line_cases()){
+        if (c.line != c.expected){
+            return std::string(c.name) + ": expected \"" + c.expected + "\", got \"" + c.line + "\".";
+        }
+    }
+    return true;
+}
+
+}
+
+
+void add_tests_RouteLog(UnitTestDatabase& database){
+    database.add<Test_RouteLog>("lines, word for word", test_lines);
+}
+
+
+
+}
+}
diff --git a/SerialPrograms/cmake/SourceFiles.cmake b/SerialPrograms/cmake/SourceFiles.cmake
index 05657bdfcc..c34d85693a 100644
--- a/SerialPrograms/cmake/SourceFiles.cmake
+++ b/SerialPrograms/cmake/SourceFiles.cmake
@@ -1450,6 +1450,9 @@ file(GLOB LIBRARY_SOURCES
     Source/Pokemon/Navigation/Pokemon_MapData.h
     Source/Pokemon/Navigation/Pokemon_MapData_Tests.cpp
     Source/Pokemon/Navigation/Pokemon_Navigation_Tests.h
+    Source/Pokemon/Navigation/Pokemon_RouteLog.cpp
+    Source/Pokemon/Navigation/Pokemon_RouteLog.h
+    Source/Pokemon/Navigation/Pokemon_RouteLog_Tests.cpp
     Source/Pokemon/Navigation/Pokemon_StoryEvents.cpp
     Source/Pokemon/Navigation/Pokemon_StoryEvents.h
     Source/Pokemon/Navigation/Pokemon_StoryEvents_Tests.cpp

From 716bb5ae027e7e3fbc1df78dc825f636543c4154 Mon Sep 17 00:00:00 2001
From: dayfine <difancpa@gmail.com>
Date: Sun, 1 Nov 2026 11:14:27 -0800
Subject: [PATCH 12/19] Pokemon navigation: route log tests as small tables,
 for the function size limits

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01AKYzhrMnPK61XHWEch4a6E
---
 .../Navigation/Pokemon_RouteLog_Tests.cpp     | 117 +++++++++---------
 1 file changed, 61 insertions(+), 56 deletions(-)

diff --git a/SerialPrograms/Source/Pokemon/Navigation/Pokemon_RouteLog_Tests.cpp b/SerialPrograms/Source/Pokemon/Navigation/Pokemon_RouteLog_Tests.cpp
index 6841138f63..243f427e51 100644
--- a/SerialPrograms/Source/Pokemon/Navigation/Pokemon_RouteLog_Tests.cpp
+++ b/SerialPrograms/Source/Pokemon/Navigation/Pokemon_RouteLog_Tests.cpp
@@ -45,115 +45,120 @@ const std::vector<RouteTile> BDSP_FROM{{"Route 202", {15, 25}}, {"Route 202", {1
 const std::vector<RouteTile> BDSP_WALL{{"Route 202", {23, 25}}, {"Route 202", {30, 26}}};
 //  An FRLG-style position: the one tile.
 const std::vector<RouteTile> FRLG_TILE{{"Route1", {12, 21}}};
+const std::vector<RouteTile> BDSP_GRASS{{"Route 202", {23, 17}}};
+const std::vector<RouteTile> FRLG_NORTH{{"Route1", {12, 13}}};
+const std::vector<RouteTile> TRAINER_SEEN{{"Route 202", {20, 10}}};
+const std::vector<RouteTile> ARRIVED{{"Route 202", {20, 25}}};
 
 const RouteLogLeg EAST_TO_WALL{.action = RouteLegAction::WALK, .direction = Direction::EAST, .tiles = 15, .end = RouteLegEnd::WALL};
 const RouteLogLeg NORTH_OPEN{.action = RouteLegAction::WALK, .direction = Direction::NORTH, .tiles = 8, .end = RouteLegEnd::OPEN};
 
+const RouteLogLeg SOUTH_WARP{.action = RouteLegAction::WALK, .direction = Direction::SOUTH, .tiles = 1, .end = RouteLegEnd::WARP};
+const RouteLogLeg SURF_EAST{.action = RouteLegAction::SURF, .direction = Direction::EAST, .tiles = 0, .end = RouteLegEnd::OPEN};
+const RouteLogLeg FACE_WEST{.action = RouteLegAction::FACE, .direction = Direction::WEST, .tiles = 0, .end = RouteLegEnd::OPEN};
+
 struct LineCase{
     const char* name;
     std::string line;
     const char* expected;
 };
 
-std::vector<LineCase> line_cases(){
-    return {
-        {.name = "leg to a wall", .line = to_string(EAST_TO_WALL), .expected = "east 15 (to wall)"},
-        {.name = "open leg", .line = to_string(NORTH_OPEN), .expected = "north 8 (open)"},
-        {
-            .name = "leg onto a warp",
-            .line = to_string(RouteLogLeg{.action = RouteLegAction::WALK, .direction = Direction::SOUTH, .tiles = 1, .end = RouteLegEnd::WARP}),
-            .expected = "south 1 (warp)",
-        },
-        {
-            .name = "surf",
-            .line = to_string(RouteLogLeg{.action = RouteLegAction::SURF, .direction = Direction::EAST, .tiles = 0, .end = RouteLegEnd::OPEN}),
-            .expected = "surf east",
-        },
-        {
-            .name = "face",
-            .line = to_string(RouteLogLeg{.action = RouteLegAction::FACE, .direction = Direction::WEST, .tiles = 0, .end = RouteLegEnd::OPEN}),
-            .expected = "face west",
-        },
+UnitTestResult check(const std::vector<LineCase>& cases){
+    for (const LineCase& c : cases){
+        if (c.line != c.expected){
+            return std::string(c.name) + ": expected \"" + c.expected + "\", got \"" + c.line + "\".";
+        }
+    }
+    return true;
+}
+
+UnitTestResult test_legs(){
+    return check({
+        {.name = "to a wall", .line = to_string(EAST_TO_WALL), .expected = "east 15 (to wall)"},
+        {.name = "open", .line = to_string(NORTH_OPEN), .expected = "north 8 (open)"},
+        {.name = "onto a warp", .line = to_string(SOUTH_WARP), .expected = "south 1 (warp)"},
+        {.name = "surf", .line = to_string(SURF_EAST), .expected = "surf east"},
+        {.name = "face", .line = to_string(FACE_WEST), .expected = "face west"},
+    });
+}
+
+UnitTestResult test_plans(){
+    const std::vector<PlannedRouteLeg> bdsp_legs{
+        {.leg = EAST_TO_WALL, .after = BDSP_WALL},
+        {.leg = NORTH_OPEN, .after = BDSP_GRASS},
+    };
+    const std::vector<PlannedRouteLeg> frlg_legs{{.leg = NORTH_OPEN, .after = FRLG_NORTH}};
+    return check({
         {
             .name = "plan from a set of tiles",
-            .line = route_plan_line("To the grass", BDSP_FROM, {
-                {.leg = EAST_TO_WALL, .after = BDSP_WALL},
-                {.leg = NORTH_OPEN, .after = {{"Route 202", {23, 17}}}},
-            }),
-            .expected =
-                "To the grass: plan from Route 202 (15, 25), Route 202 (16, 25):\n"
+            .line = route_plan_line("To the grass", BDSP_FROM, bdsp_legs),
+            .expected = "To the grass: plan from Route 202 (15, 25), Route 202 (16, 25):\n"
                 "    east 15 (to wall) to Route 202 (23, 25), Route 202 (30, 26)\n"
                 "    north 8 (open) to Route 202 (23, 17)",
         },
         {
             .name = "plan from one tile",
-            .line = route_plan_line("00.05/2 below_mart_door", FRLG_TILE, {{.leg = NORTH_OPEN, .after = {{"Route1", {12, 13}}}}}),
-            .expected =
-                "00.05/2 below_mart_door: plan from Route1 (12, 21):\n"
-                "    north 8 (open) to Route1 (12, 13)",
-        },
-        {
-            .name = "plan from an unknown tile",
-            .line = route_plan_line("x", {}, {}),
-            .expected = "x: plan from an unknown tile:",
+            .line = route_plan_line("00.05/2 below_mart_door", FRLG_TILE, frlg_legs),
+            .expected = "00.05/2 below_mart_door: plan from Route1 (12, 21):\n    north 8 (open) to Route1 (12, 13)",
         },
+        {.name = "plan from an unknown tile", .line = route_plan_line("x", {}, {}), .expected = "x: plan from an unknown tile:"},
         {
             .name = "leg as it starts",
-            .line = route_leg_line(1, 5, {.leg = EAST_TO_WALL, .after = BDSP_WALL}),
+            .line = route_leg_line(1, 5, bdsp_legs[0]),
             .expected = "Leg 1/5: east 15 (to wall) to Route 202 (23, 25), Route 202 (30, 26)",
         },
+    });
+}
+
+UnitTestResult test_leg_ends(){
+    return check({
         {
-            .name = "leg walked",
+            .name = "walked",
             .line = route_leg_end_line("To the grass", EAST_TO_WALL, BDSP_WALL, EndBasis::WALKED, ""),
             .expected = "To the grass: east 15 (to wall): ended at Route 202 (23, 25), Route 202 (30, 26) (walked).",
         },
         {
-            .name = "leg assumed",
+            .name = "assumed",
             .line = route_leg_end_line("r", NORTH_OPEN, FRLG_TILE, EndBasis::ASSUMED, "after a wild battle"),
             .expected = "r: north 8 (open): ended at Route1 (12, 21) (assumed: after a wild battle).",
         },
         {
-            .name = "leg end unknown",
+            .name = "unknown",
             .line = route_leg_end_line("r", NORTH_OPEN, {}, EndBasis::UNKNOWN, "stopped by a wild battle"),
             .expected = "r: north 8 (open): ended at an unknown tile (unknown: stopped by a wild battle).",
         },
+    });
+}
+
+UnitTestResult test_events(){
+    return check({
         {
             .name = "replan where seen",
             .line = route_replan_line("To the grass", EAST_TO_WALL, "stopped early after about 3 tiles", BDSP_FROM),
             .expected = "To the grass: east 15 (to wall): stopped early after about 3 tiles, at Route 202 (15, 25), Route 202 (16, 25); planning again.",
         },
-        {
-            .name = "found again",
-            .line = route_found_line("r", FRLG_TILE, 2),
-            .expected = "r: found again at Route1 (12, 21), after 2 hold(s).",
-        },
+        {.name = "found again", .line = route_found_line("r", FRLG_TILE, 2), .expected = "r: found again at Route1 (12, 21), after 2 hold(s)."},
         {
             .name = "trainer",
-            .line = route_trainer_line("To the grass", "Youngster Tristan", {{"Route 202", {20, 10}}}),
+            .line = route_trainer_line("To the grass", "Youngster Tristan", TRAINER_SEEN),
             .expected = "To the grass: Youngster Tristan stopped us about Route 202 (20, 10).",
         },
         {
             .name = "arrived",
-            .line = route_arrived_line("To the grass", {{"Route 202", {20, 25}}}),
+            .line = route_arrived_line("To the grass", ARRIVED),
             .expected = "To the grass: arrived at Route 202 (20, 25).",
         },
-    };
-}
-
-UnitTestResult test_lines(){
-    for (const LineCase& c : line_cases()){
-        if (c.line != c.expected){
-            return std::string(c.name) + ": expected \"" + c.expected + "\", got \"" + c.line + "\".";
-        }
-    }
-    return true;
+    });
 }
 
 }
 
 
 void add_tests_RouteLog(UnitTestDatabase& database){
-    database.add<Test_RouteLog>("lines, word for word", test_lines);
+    database.add<Test_RouteLog>("legs", test_legs);
+    database.add<Test_RouteLog>("plans, from a set of tiles or one", test_plans);
+    database.add<Test_RouteLog>("leg ends: walked, assumed, unknown", test_leg_ends);
+    database.add<Test_RouteLog>("replans, finds, trainers, arrivals", test_events);
 }
 
 

From a38e45766e41e71638b591983b03d0386d623ecc Mon Sep 17 00:00:00 2001
From: dayfine <difancpa@gmail.com>
Date: Sun, 1 Nov 2026 11:19:25 -0800
Subject: [PATCH 13/19] Pokemon navigation: the leg walker, with its stop hooks

The leg walker and its tests, moved here from the FRLG PRs (#117 added
it, #119 dropped the tile-at-a-time walk and added the stop hooks), so
that the shared navigation code lives in one PR. Unchanged from #119's
version: it walks one leg with a game's mover, clears interrupts on the
way, and stops an open leg at an interrupt or a leg to a wall that is
interrupted again at once.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01AKYzhrMnPK61XHWEch4a6E
---
 .../ComputerPrograms_UnitTestRunner.cpp       |   1 +
 .../Pokemon/Navigation/Pokemon_LegWalker.cpp  |  91 +++++++
 .../Pokemon/Navigation/Pokemon_LegWalker.h    | 224 ++++++++++++++++++
 .../Navigation/Pokemon_LegWalker_Tests.cpp    | 206 ++++++++++++++++
 .../Navigation/Pokemon_Navigation_Tests.h     |   1 +
 SerialPrograms/cmake/SourceFiles.cmake        |   3 +
 6 files changed, 526 insertions(+)
 create mode 100644 SerialPrograms/Source/Pokemon/Navigation/Pokemon_LegWalker.cpp
 create mode 100644 SerialPrograms/Source/Pokemon/Navigation/Pokemon_LegWalker.h
 create mode 100644 SerialPrograms/Source/Pokemon/Navigation/Pokemon_LegWalker_Tests.cpp

diff --git a/SerialPrograms/Source/ComputerPrograms/ComputerPrograms_UnitTestRunner.cpp b/SerialPrograms/Source/ComputerPrograms/ComputerPrograms_UnitTestRunner.cpp
index a3a4cc2fcd..592144c1f1 100644
--- a/SerialPrograms/Source/ComputerPrograms/ComputerPrograms_UnitTestRunner.cpp
+++ b/SerialPrograms/Source/ComputerPrograms/ComputerPrograms_UnitTestRunner.cpp
@@ -62,6 +62,7 @@ UnitTestDatabase make_UNIT_TESTS_ALL(){
     OCR::add_tests(ret);
     Kernels::add_tests(ret);
     Pokemon::add_tests_LegPlanner(ret);
+    Pokemon::add_tests_LegWalker(ret);
     Pokemon::add_tests_MapData(ret);
     Pokemon::add_tests_RouteLog(ret);
     Pokemon::add_tests_StoryEvents(ret);
diff --git a/SerialPrograms/Source/Pokemon/Navigation/Pokemon_LegWalker.cpp b/SerialPrograms/Source/Pokemon/Navigation/Pokemon_LegWalker.cpp
new file mode 100644
index 0000000000..fbb88051fb
--- /dev/null
+++ b/SerialPrograms/Source/Pokemon/Navigation/Pokemon_LegWalker.cpp
@@ -0,0 +1,91 @@
+/*  Leg Walker
+ *
+ *  From: https://github.com/PokemonAutomation/
+ *
+ */
+
+#include <format>
+#include "Pokemon_LegWalker.h"
+
+namespace PokemonAutomation{
+namespace Pokemon{
+
+
+std::string to_string(const LegSpec& leg){
+    return std::format("{} {}{}", direction_name(leg.direction), leg.tiles, leg.to_wall ? " (to wall)" : "");
+}
+
+
+Milliseconds leg_hold(const LegSpec& leg, int tiles){
+    if (leg.to_wall){
+        return leg.tile_time * (tiles + 2);
+    }
+    return leg.tile_time * (tiles - 1) + leg.tile_time / 2;
+}
+
+int tiles_before_interrupt(const LegSpec& leg, Milliseconds elapsed, Milliseconds detection_delay, int remaining){
+    const Milliseconds since_first_step = elapsed - detection_delay + leg.tile_time / 2;
+    if (since_first_step.count() <= 0){
+        return 0;
+    }
+    return std::clamp((int)(since_first_step / leg.tile_time), 0, remaining);
+}
+
+
+namespace{
+
+//  Whether `leg` stops at the interrupt just cleared: an open leg asked to
+//  stop at any, or a leg to a wall interrupted again within three tiles of
+//  being held again (a message there lags the step by about two tiles).
+bool stops_here(const LegSpec& leg, const LegResult& result, const HoldOutcome& outcome){
+    if (!leg.to_wall){
+        return leg.stop_on_interrupt;
+    }
+    return leg.stop_if_blocked && result.interruptions > 1 && outcome.elapsed < leg.tile_time * 3;
+}
+
+}
+
+
+LegResult walk_leg_with(const LegSpec& leg, const LegCalls& calls, size_t max_interruptions){
+    LegResult result;
+    int remaining = leg.tiles;
+    while (true){
+        const std::optional<HoldOutcome> outcome = calls.hold_watching(leg_hold(leg, remaining));
+        if (!outcome){
+            result.tiles = leg.tiles;
+            return result;
+        }
+        result.interruptions++;
+        if (result.interruptions > max_interruptions){
+            calls.fail(std::format("Interrupted {} times on: {}", result.interruptions, to_string(leg)));
+        }
+        calls.clear(outcome->interrupt);
+        const std::string seen = std::format("{} after {}ms", calls.name(outcome->interrupt), outcome->elapsed.count());
+        if (stops_here(leg, result, *outcome)){
+            calls.log(seen + ", stopping the leg.");
+            result.exact = false;
+            result.stopped = true;
+            return result;
+        }
+        if (leg.to_wall){
+            //  The wall stops the player on the leg's last tile however far
+            //  they got, so the leg is simply held again.
+            calls.log(seen + ", walking to the wall again.");
+            continue;
+        }
+        const int walked = tiles_before_interrupt(leg, outcome->elapsed, calls.detection_delay(outcome->interrupt), remaining);
+        remaining -= walked;
+        result.exact = false;
+        calls.log(std::format("{}, about {} tiles walked, {} to go.", seen, walked, remaining));
+        if (remaining <= 0){
+            result.tiles = leg.tiles;
+            return result;
+        }
+    }
+}
+
+
+
+}
+}
diff --git a/SerialPrograms/Source/Pokemon/Navigation/Pokemon_LegWalker.h b/SerialPrograms/Source/Pokemon/Navigation/Pokemon_LegWalker.h
new file mode 100644
index 0000000000..0c8018e8ed
--- /dev/null
+++ b/SerialPrograms/Source/Pokemon/Navigation/Pokemon_LegWalker.h
@@ -0,0 +1,224 @@
+/*  Leg Walker
+ *
+ *  From: https://github.com/PokemonAutomation/
+ *
+ *  Walks one leg of a plan: holds a direction for the leg's tiles while
+ *  watching for whatever can stop the player part-way (a wild battle, a
+ *  message, a trainer). Each of those is a LegInterrupt the game supplies.
+ *  When one shows, the hold stops, the game clears it, and the rest of the
+ *  leg is walked: a leg to a wall is simply held again, since the wall stops
+ *  the player on its tile; for an open leg, how far the player got is worked
+ *  out from when the interrupt was seen.
+ *
+ *  How a direction is held (D-pad or stick) and how long a tile takes are
+ *  the game's too, through LegMover. Templated on the console and the
+ *  controller context, like run_until(), so this stays free of any one
+ *  console's types.
+ *
+ */
+
+#ifndef PokemonAutomation_Pokemon_LegWalker_H
+#define PokemonAutomation_Pokemon_LegWalker_H
+
+#include <algorithm>
+#include <format>
+#include <functional>
+#include <memory>
+#include <optional>
+#include <string>
+#include <vector>
+#include "Common/Cpp/Time.h"
+#include "CommonFramework/Exceptions/OperationFailedExceptionWithScreenshot.h"
+#include "CommonTools/Async/InferenceRoutines.h"
+#include "CommonTools/InferenceCallbacks/VisualInferenceCallback.h"
+#include "Pokemon_Grid.h"
+
+namespace PokemonAutomation{
+namespace Pokemon{
+
+
+//  Something that stops the player part-way through a leg.
+template <typename Console, typename Context>
+class LegInterrupt{
+public:
+    virtual ~LegInterrupt() = default;
+
+    virtual std::string name() const = 0;
+
+    //  A new watcher for the screen the interruption brings up.
+    virtual std::unique_ptr<VisualInferenceCallback> make_watcher() const = 0;
+
+    //  How long after the step that set it off the watcher fires. The games
+    //  only interrupt between steps, so from this the walker works out how
+    //  many tiles of an open leg were walked.
+    virtual Milliseconds detection_delay() const = 0;
+
+    //  Clears it, leaving the player standing on the overworld, on the same
+    //  tile and facing the same way.
+    virtual void clear(Console& console, Context& context) const = 0;
+};
+
+template <typename Console, typename Context>
+using LegInterrupts = std::vector<std::unique_ptr<LegInterrupt<Console, Context>>>;
+
+
+//  How the game moves the player.
+template <typename Context>
+class LegMover{
+public:
+    virtual ~LegMover() = default;
+    //  Holds `direction` for `duration`, then lets go.
+    virtual void hold(Context& context, Direction direction, Milliseconds duration) const = 0;
+};
+
+
+//  A straight leg, for a player standing still and facing its way.
+struct LegSpec{
+    Direction direction = Direction::NORTH;
+    int tiles = 0;
+    //  A wall stops the player after the last tile.
+    bool to_wall = false;
+    //  How long one tile takes, for this leg's direction and way of moving.
+    Milliseconds tile_time{0};
+    //  An open leg stops at its first interrupt, once cleared, instead of
+    //  walking on from an estimate; the caller finds the player again.
+    bool stop_on_interrupt = false;
+    //  A leg to a wall stops when, held again after an interrupt, it is
+    //  interrupted again right away: something on the way, like a sign,
+    //  interrupts every hold, so the wall is never reached.
+    bool stop_if_blocked = false;
+};
+std::string to_string(const LegSpec& leg);
+
+struct LegResult{
+    //  Tiles walked, which is `tiles` unless the leg gave up.
+    int tiles = 0;
+    //  Whether `tiles` is certain: an interrupted open leg is an estimate.
+    bool exact = true;
+    size_t interruptions = 0;
+    //  The leg stopped at an interrupt (stop_on_interrupt, stop_if_blocked):
+    //  the player is somewhere along it, and `tiles` is not known.
+    bool stopped = false;
+};
+
+
+//  How long to hold for `tiles` tiles: an open leg lets go half a tile before
+//  the last step would end, so the step under way finishes and no other
+//  starts; a leg to a wall is held two tiles longer than it takes.
+Milliseconds leg_hold(const LegSpec& leg, int tiles);
+
+//  How many tiles an open leg had walked when an interrupt was seen
+//  `elapsed` into its hold, given the interrupt's detection delay. Steps end
+//  a whole number of tiles into the hold, so this rounds to the nearest.
+int tiles_before_interrupt(const LegSpec& leg, Milliseconds elapsed, Milliseconds detection_delay, int remaining);
+
+
+//  What one hold reported: nothing if it ran out, or which interrupt showed
+//  and how long into the hold.
+struct HoldOutcome{
+    size_t interrupt = 0;
+    Milliseconds elapsed{0};
+};
+
+//  The leg's bookkeeping, with the console side passed in, so it can be
+//  tested with scripted outcomes. `hold_watching` holds for the duration and
+//  reports the first interrupt seen; `clear` clears interrupt i;
+//  `detection_delay` is interrupt i's delay; `log` reports progress; `fail`
+//  throws, and is called after more than `max_interruptions`.
+struct LegCalls{
+    std::function<std::optional<HoldOutcome>(Milliseconds hold)> hold_watching;
+    std::function<void(size_t interrupt)> clear;
+    std::function<Milliseconds(size_t interrupt)> detection_delay;
+    std::function<std::string(size_t interrupt)> name;
+    std::function<void(const std::string& message)> log;
+    std::function<void(const std::string& message)> fail;
+};
+LegResult walk_leg_with(const LegSpec& leg, const LegCalls& calls, size_t max_interruptions);
+
+
+//  Walks `leg`. Throws OperationFailedException if it is interrupted more
+//  than `max_interruptions` times.
+template <typename Console, typename Context>
+LegResult walk_leg(
+    Console& console, Context& context,
+    const LegMover<Context>& mover,
+    const LegInterrupts<Console, Context>& interrupts,
+    const LegSpec& leg,
+    size_t max_interruptions = 5
+){
+    auto hold_watching = [&](Milliseconds hold) -> std::optional<HoldOutcome>{
+        std::vector<std::unique_ptr<VisualInferenceCallback>> watchers;
+        std::vector<PeriodicInferenceCallback> callbacks;
+        for (const auto& interrupt : interrupts){
+            watchers.emplace_back(interrupt->make_watcher());
+            callbacks.emplace_back(*watchers.back());
+        }
+        context.wait_for_all_requests();
+        WallClock start = current_time();
+        const int ret = run_until<Context>(
+            console, context,
+            [&](Context& context){
+                start = current_time();
+                mover.hold(context, leg.direction, hold);
+            },
+            callbacks
+        );
+        if (ret < 0){
+            return std::nullopt;
+        }
+        return HoldOutcome{(size_t)ret, std::chrono::duration_cast<Milliseconds>(current_time() - start)};
+    };
+    LegCalls calls;
+    calls.hold_watching = hold_watching;
+    calls.clear = [&](size_t index){ interrupts[index]->clear(console, context); };
+    calls.detection_delay = [&](size_t index){ return interrupts[index]->detection_delay(); };
+    calls.name = [&](size_t index){ return interrupts[index]->name(); };
+    calls.log = [&](const std::string& message){ console.log("Leg: " + message, COLOR_ORANGE); };
+    calls.fail = [&](const std::string& message){
+        OperationFailedExceptionWithScreenshot::fire(ErrorReportMode::SEND_ERROR_REPORT, message, console);
+    };
+    return walk_leg_with(leg, calls, max_interruptions);
+}
+
+
+//  After a leg: waits `watch` for an interrupt the last step set off, which
+//  shows after the hold has ended, and clears it. Returns how many it
+//  cleared. Throws OperationFailedException after `max_interruptions` in a
+//  row.
+template <typename Console, typename Context>
+size_t clear_late_interrupts(
+    Console& console, Context& context,
+    const LegInterrupts<Console, Context>& interrupts,
+    Milliseconds watch,
+    size_t max_interruptions = 5
+){
+    for (size_t count = 0; ; count++){
+        std::vector<std::unique_ptr<VisualInferenceCallback>> watchers;
+        std::vector<PeriodicInferenceCallback> callbacks;
+        for (const auto& interrupt : interrupts){
+            watchers.emplace_back(interrupt->make_watcher());
+            callbacks.emplace_back(*watchers.back());
+        }
+        context.wait_for_all_requests();
+        const int ret = wait_until(console, context, watch, callbacks);
+        if (ret < 0){
+            return count;
+        }
+        if (count >= max_interruptions){
+            OperationFailedExceptionWithScreenshot::fire(
+                ErrorReportMode::SEND_ERROR_REPORT,
+                std::format("Interrupted {} times in a row after a leg.", count),
+                console
+            );
+        }
+        console.log("Leg: " + interrupts[ret]->name() + " at the end of the leg.", COLOR_ORANGE);
+        interrupts[ret]->clear(console, context);
+    }
+}
+
+
+
+
+}
+}
+#endif
diff --git a/SerialPrograms/Source/Pokemon/Navigation/Pokemon_LegWalker_Tests.cpp b/SerialPrograms/Source/Pokemon/Navigation/Pokemon_LegWalker_Tests.cpp
new file mode 100644
index 0000000000..667fb55d64
--- /dev/null
+++ b/SerialPrograms/Source/Pokemon/Navigation/Pokemon_LegWalker_Tests.cpp
@@ -0,0 +1,206 @@
+/*  Leg Walker Tests
+ *
+ *  From: https://github.com/PokemonAutomation/
+ *
+ *  The leg walker's bookkeeping, with holds that report scripted
+ *  interruptions instead of a console.
+ *
+ */
+
+#include <deque>
+#include <format>
+#include <functional>
+#include <stdexcept>
+#include <string>
+#include <vector>
+#include "Common/Cpp/TestRunners/UnitTest.h"
+#include "Pokemon_LegWalker.h"
+#include "Pokemon_Navigation_Tests.h"
+
+namespace PokemonAutomation{
+namespace Pokemon{
+
+
+namespace{
+
+using namespace std::chrono_literals;
+
+constexpr Milliseconds TILE = 267ms;
+constexpr Milliseconds DELAY = 300ms;
+
+//  Holds that report the scripted outcomes in order, then run out.
+struct ScriptedLeg{
+    std::deque<std::optional<HoldOutcome>> outcomes;
+    std::vector<Milliseconds> holds;
+    std::vector<size_t> cleared;
+
+    LegCalls calls(){
+        LegCalls calls;
+        calls.hold_watching = [this](Milliseconds hold) -> std::optional<HoldOutcome>{
+            holds.push_back(hold);
+            if (outcomes.empty()){
+                return std::nullopt;
+            }
+            std::optional<HoldOutcome> outcome = outcomes.front();
+            outcomes.pop_front();
+            return outcome;
+        };
+        calls.clear = [this](size_t index){ cleared.push_back(index); };
+        calls.detection_delay = [](size_t){ return DELAY; };
+        calls.name = [](size_t){ return std::string("a battle"); };
+        calls.log = [](const std::string&){};
+        calls.fail = [](const std::string& message){ throw std::runtime_error(message); };
+        return calls;
+    }
+};
+
+//  An interrupt set off by step `step`, seen DELAY after it ends.
+HoldOutcome after_step(int step){
+    return HoldOutcome{0, TILE * step + DELAY};
+}
+
+
+UnitTestResult test_hold_times(){
+    const LegSpec open{Direction::EAST, 4, false, TILE};
+    const LegSpec wall{Direction::EAST, 4, true, TILE};
+    if (leg_hold(open, 4) != TILE * 3 + TILE / 2){
+        return std::format("Open leg: {}ms", leg_hold(open, 4).count());
+    }
+    if (leg_hold(wall, 4) != TILE * 6){
+        return std::format("Wall leg: {}ms", leg_hold(wall, 4).count());
+    }
+    return true;
+}
+
+UnitTestResult test_tiles_before_interrupt(){
+    const LegSpec leg{Direction::EAST, 8, false, TILE};
+    for (int step = 0; step <= 8; step++){
+        for (Milliseconds jitter : {-100ms, 0ms, 100ms}){
+            const int walked = tiles_before_interrupt(leg, TILE * step + DELAY + jitter, DELAY, 8);
+            if (walked != step){
+                return std::format("Step {} seen {}ms off read as {}", step, jitter.count(), walked);
+            }
+        }
+    }
+    if (tiles_before_interrupt(leg, 50ms, DELAY, 8) != 0){
+        return "An interrupt from before the leg should count no tiles.";
+    }
+    if (tiles_before_interrupt(leg, TILE * 20, DELAY, 3) != 3){
+        return "Should not count more tiles than remain.";
+    }
+    return true;
+}
+
+UnitTestResult test_wall_leg_walked_again(){
+    ScriptedLeg script;
+    script.outcomes = {after_step(2)};
+    const LegSpec leg{Direction::NORTH, 6, true, TILE};
+    const LegResult result = walk_leg_with(leg, script.calls(), 5);
+    if (script.holds.size() != 2 || script.holds[1] != leg_hold(leg, 6)){
+        return "Expected the whole leg held again.";
+    }
+    if (!result.exact || result.interruptions != 1 || script.cleared.size() != 1){
+        return "Expected an exact result after one interruption.";
+    }
+    return true;
+}
+
+UnitTestResult test_open_leg_rest_walked(){
+    ScriptedLeg script;
+    script.outcomes = {after_step(2)};
+    const LegSpec leg{Direction::NORTH, 6, false, TILE};
+    const LegResult result = walk_leg_with(leg, script.calls(), 5);
+    if (script.holds.size() != 2 || script.holds[1] != leg_hold(leg, 4)){
+        return "Expected the remaining 4 tiles held.";
+    }
+    if (result.exact){
+        return "An interrupted open leg is an estimate.";
+    }
+    return true;
+}
+
+UnitTestResult test_open_leg_interrupted_at_end(){
+    ScriptedLeg script;
+    script.outcomes = {after_step(6)};
+    const LegSpec leg{Direction::NORTH, 6, false, TILE};
+    walk_leg_with(leg, script.calls(), 5);
+    if (script.holds.size() != 1){
+        return "Nothing was left to walk after the last step.";
+    }
+    return true;
+}
+
+//  An open leg set to stop at an interrupt doesn't walk on from a guess.
+UnitTestResult test_open_leg_stops(){
+    ScriptedLeg script;
+    script.outcomes = {after_step(2)};
+    LegSpec leg{Direction::NORTH, 6, false, TILE};
+    leg.stop_on_interrupt = true;
+    const LegResult result = walk_leg_with(leg, script.calls(), 5);
+    if (script.holds.size() != 1 || !result.stopped || result.exact || script.cleared.size() != 1){
+        return "Expected one hold, the interrupt cleared, and the leg stopped.";
+    }
+    return true;
+}
+
+//  Console B, 2026-11-01, run 16: held south into a sign, the leg to a wall
+//  was interrupted by its message 600ms into every hold, six times.
+UnitTestResult test_wall_leg_blocked(){
+    ScriptedLeg script;
+    script.outcomes = {HoldOutcome{0, 2200ms}, HoldOutcome{0, 600ms}, HoldOutcome{0, 600ms}};
+    LegSpec leg{Direction::SOUTH, 23, true, TILE};
+    leg.stop_if_blocked = true;
+    const LegResult result = walk_leg_with(leg, script.calls(), 5);
+    if (script.holds.size() != 2 || !result.stopped){
+        return std::format("Expected the leg stopped after 2 holds, got {}.", script.holds.size());
+    }
+    return true;
+}
+
+UnitTestResult test_too_many_interruptions(){
+    ScriptedLeg script;
+    for (int c = 0; c < 4; c++){
+        script.outcomes.push_back(after_step(0));
+    }
+    const LegSpec leg{Direction::NORTH, 6, true, TILE};
+    try{
+        walk_leg_with(leg, script.calls(), 3);
+    }catch (std::runtime_error&){
+        return true;
+    }
+    return "Expected to give up after 3 interruptions.";
+}
+
+
+class Test_LegWalker : public UnitTest{
+public:
+    Test_LegWalker(std::string name, std::function<UnitTestResult()> body)
+        : UnitTest("Pokemon::LegWalker - " + std::move(name))
+        , m_body(std::move(body))
+    {}
+    virtual UnitTestResult run(Logger&, CancellableScope&) const override{
+        return m_body();
+    }
+
+private:
+    std::function<UnitTestResult()> m_body;
+};
+
+}
+
+
+void add_tests_LegWalker(UnitTestDatabase& database){
+    database.add<Test_LegWalker>("hold times", test_hold_times);
+    database.add<Test_LegWalker>("tiles before an interrupt", test_tiles_before_interrupt);
+    database.add<Test_LegWalker>("a wall leg is walked again", test_wall_leg_walked_again);
+    database.add<Test_LegWalker>("an open leg walks the rest", test_open_leg_rest_walked);
+    database.add<Test_LegWalker>("an open leg interrupted at its end", test_open_leg_interrupted_at_end);
+    database.add<Test_LegWalker>("gives up after too many interruptions", test_too_many_interruptions);
+    database.add<Test_LegWalker>("an open leg stops at an interrupt", test_open_leg_stops);
+    database.add<Test_LegWalker>("a wall leg blocked by a sign stops", test_wall_leg_blocked);
+}
+
+
+
+}
+}
diff --git a/SerialPrograms/Source/Pokemon/Navigation/Pokemon_Navigation_Tests.h b/SerialPrograms/Source/Pokemon/Navigation/Pokemon_Navigation_Tests.h
index 3d51443174..35bf6d1891 100644
--- a/SerialPrograms/Source/Pokemon/Navigation/Pokemon_Navigation_Tests.h
+++ b/SerialPrograms/Source/Pokemon/Navigation/Pokemon_Navigation_Tests.h
@@ -17,6 +17,7 @@ namespace Pokemon{
 
 
 void add_tests_LegPlanner(UnitTestDatabase& database);
+void add_tests_LegWalker(UnitTestDatabase& database);
 void add_tests_MapData(UnitTestDatabase& database);
 void add_tests_RouteLog(UnitTestDatabase& database);
 void add_tests_StoryEvents(UnitTestDatabase& database);
diff --git a/SerialPrograms/cmake/SourceFiles.cmake b/SerialPrograms/cmake/SourceFiles.cmake
index c34d85693a..a97fc4ebb0 100644
--- a/SerialPrograms/cmake/SourceFiles.cmake
+++ b/SerialPrograms/cmake/SourceFiles.cmake
@@ -1446,6 +1446,9 @@ file(GLOB LIBRARY_SOURCES
     Source/Pokemon/Navigation/Pokemon_Grid.h
     Source/Pokemon/Navigation/Pokemon_LegPlanner.h
     Source/Pokemon/Navigation/Pokemon_LegPlanner_Tests.cpp
+    Source/Pokemon/Navigation/Pokemon_LegWalker.cpp
+    Source/Pokemon/Navigation/Pokemon_LegWalker.h
+    Source/Pokemon/Navigation/Pokemon_LegWalker_Tests.cpp
     Source/Pokemon/Navigation/Pokemon_MapData.cpp
     Source/Pokemon/Navigation/Pokemon_MapData.h
     Source/Pokemon/Navigation/Pokemon_MapData_Tests.cpp

From 84093b021dc75b40848fc7a371d3756933d8a0e5 Mon Sep 17 00:00:00 2001
From: dayfine <difancpa@gmail.com>
Date: Sun, 1 Nov 2026 14:13:43 -0800
Subject: [PATCH 14/19] Pokemon AutoStory: the story engine moves out of
 Pokemon/Navigation

Navigation is moving the player (grids, maps, legs, the walker, the route
log); AutoStory is the story. StoryEvents, StorySegments and TilePose (the
story's pose on a tile map) move unchanged to Pokemon/AutoStory, next to
the select database and stats, with their tests registered from a new
Pokemon_AutoStory_Tests.h. Navigation includes nothing from AutoStory.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01AKYzhrMnPK61XHWEch4a6E
---
 .../ComputerPrograms_UnitTestRunner.cpp       |  1 +
 .../AutoStory/Pokemon_AutoStory_Tests.h       | 25 +++++++++++++++++++
 .../Pokemon_StoryEvents.cpp                   |  0
 .../Pokemon_StoryEvents.h                     |  0
 .../Pokemon_StoryEvents_Tests.cpp             |  2 +-
 .../Pokemon_StorySegments.cpp                 |  0
 .../Pokemon_StorySegments.h                   |  0
 .../Pokemon_StorySegments_Tests.cpp           |  2 +-
 .../Pokemon_TilePose.cpp                      |  0
 .../Pokemon_TilePose.h                        |  2 +-
 .../Navigation/Pokemon_Navigation_Tests.h     |  2 --
 SerialPrograms/cmake/SourceFiles.cmake        | 17 +++++++------
 12 files changed, 38 insertions(+), 13 deletions(-)
 create mode 100644 SerialPrograms/Source/Pokemon/AutoStory/Pokemon_AutoStory_Tests.h
 rename SerialPrograms/Source/Pokemon/{Navigation => AutoStory}/Pokemon_StoryEvents.cpp (100%)
 rename SerialPrograms/Source/Pokemon/{Navigation => AutoStory}/Pokemon_StoryEvents.h (100%)
 rename SerialPrograms/Source/Pokemon/{Navigation => AutoStory}/Pokemon_StoryEvents_Tests.cpp (97%)
 rename SerialPrograms/Source/Pokemon/{Navigation => AutoStory}/Pokemon_StorySegments.cpp (100%)
 rename SerialPrograms/Source/Pokemon/{Navigation => AutoStory}/Pokemon_StorySegments.h (100%)
 rename SerialPrograms/Source/Pokemon/{Navigation => AutoStory}/Pokemon_StorySegments_Tests.cpp (96%)
 rename SerialPrograms/Source/Pokemon/{Navigation => AutoStory}/Pokemon_TilePose.cpp (100%)
 rename SerialPrograms/Source/Pokemon/{Navigation => AutoStory}/Pokemon_TilePose.h (92%)

diff --git a/SerialPrograms/Source/ComputerPrograms/ComputerPrograms_UnitTestRunner.cpp b/SerialPrograms/Source/ComputerPrograms/ComputerPrograms_UnitTestRunner.cpp
index 10be85b75f..3613ccaa3c 100644
--- a/SerialPrograms/Source/ComputerPrograms/ComputerPrograms_UnitTestRunner.cpp
+++ b/SerialPrograms/Source/ComputerPrograms/ComputerPrograms_UnitTestRunner.cpp
@@ -30,6 +30,7 @@
 #include "NintendoSwitch/Inference/NintendoSwitch_UpdatePopupDetector.h"
 #include "NintendoSwitch/Programs/Typewriter/NintendoSwitch_Typewriter_Tests.h"
 
+#include "Pokemon/AutoStory/Pokemon_AutoStory_Tests.h"
 #include "Pokemon/Navigation/Pokemon_Navigation_Tests.h"
 #include "VideoGames/PokemonHome/PokemonHome_Tests.h"
 #include "VideoGames/PokemonSwSh/PokemonSwSh_Tests.h"
diff --git a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_AutoStory_Tests.h b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_AutoStory_Tests.h
new file mode 100644
index 0000000000..29e4dd765e
--- /dev/null
+++ b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_AutoStory_Tests.h
@@ -0,0 +1,25 @@
+/*  AutoStory Tests
+ *
+ *  From: https://github.com/PokemonAutomation/
+ *
+ *  The unit tests of the shared story engine (Pokemon/AutoStory).
+ *
+ */
+
+#ifndef PokemonAutomation_Pokemon_AutoStory_Tests_H
+#define PokemonAutomation_Pokemon_AutoStory_Tests_H
+
+#include "Common/Cpp/TestRunners/UnitTestDatabase.h"
+
+namespace PokemonAutomation{
+namespace Pokemon{
+
+
+void add_tests_StoryEvents(UnitTestDatabase& database);
+void add_tests_StorySegments(UnitTestDatabase& database);
+
+
+
+}
+}
+#endif
diff --git a/SerialPrograms/Source/Pokemon/Navigation/Pokemon_StoryEvents.cpp b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryEvents.cpp
similarity index 100%
rename from SerialPrograms/Source/Pokemon/Navigation/Pokemon_StoryEvents.cpp
rename to SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryEvents.cpp
diff --git a/SerialPrograms/Source/Pokemon/Navigation/Pokemon_StoryEvents.h b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryEvents.h
similarity index 100%
rename from SerialPrograms/Source/Pokemon/Navigation/Pokemon_StoryEvents.h
rename to SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryEvents.h
diff --git a/SerialPrograms/Source/Pokemon/Navigation/Pokemon_StoryEvents_Tests.cpp b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryEvents_Tests.cpp
similarity index 97%
rename from SerialPrograms/Source/Pokemon/Navigation/Pokemon_StoryEvents_Tests.cpp
rename to SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryEvents_Tests.cpp
index 64b6bfb44e..92b472eb4f 100644
--- a/SerialPrograms/Source/Pokemon/Navigation/Pokemon_StoryEvents_Tests.cpp
+++ b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryEvents_Tests.cpp
@@ -17,7 +17,7 @@
 #include "Common/Cpp/TestRunners/UnitTest.h"
 #include "Pokemon_StoryEvents.h"
 #include "Pokemon_TilePose.h"
-#include "Pokemon_Navigation_Tests.h"
+#include "Pokemon_AutoStory_Tests.h"
 
 namespace PokemonAutomation{
 namespace Pokemon{
diff --git a/SerialPrograms/Source/Pokemon/Navigation/Pokemon_StorySegments.cpp b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StorySegments.cpp
similarity index 100%
rename from SerialPrograms/Source/Pokemon/Navigation/Pokemon_StorySegments.cpp
rename to SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StorySegments.cpp
diff --git a/SerialPrograms/Source/Pokemon/Navigation/Pokemon_StorySegments.h b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StorySegments.h
similarity index 100%
rename from SerialPrograms/Source/Pokemon/Navigation/Pokemon_StorySegments.h
rename to SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StorySegments.h
diff --git a/SerialPrograms/Source/Pokemon/Navigation/Pokemon_StorySegments_Tests.cpp b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StorySegments_Tests.cpp
similarity index 96%
rename from SerialPrograms/Source/Pokemon/Navigation/Pokemon_StorySegments_Tests.cpp
rename to SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StorySegments_Tests.cpp
index d367e27f02..1fa7b4bdd1 100644
--- a/SerialPrograms/Source/Pokemon/Navigation/Pokemon_StorySegments_Tests.cpp
+++ b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StorySegments_Tests.cpp
@@ -17,7 +17,7 @@
 #include "Pokemon_StoryEvents.h"
 #include "Pokemon_StorySegments.h"
 #include "Pokemon_TilePose.h"
-#include "Pokemon_Navigation_Tests.h"
+#include "Pokemon_AutoStory_Tests.h"
 
 namespace PokemonAutomation{
 namespace Pokemon{
diff --git a/SerialPrograms/Source/Pokemon/Navigation/Pokemon_TilePose.cpp b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_TilePose.cpp
similarity index 100%
rename from SerialPrograms/Source/Pokemon/Navigation/Pokemon_TilePose.cpp
rename to SerialPrograms/Source/Pokemon/AutoStory/Pokemon_TilePose.cpp
diff --git a/SerialPrograms/Source/Pokemon/Navigation/Pokemon_TilePose.h b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_TilePose.h
similarity index 92%
rename from SerialPrograms/Source/Pokemon/Navigation/Pokemon_TilePose.h
rename to SerialPrograms/Source/Pokemon/AutoStory/Pokemon_TilePose.h
index 34f0d18adc..62e0b0dea6 100644
--- a/SerialPrograms/Source/Pokemon/Navigation/Pokemon_TilePose.h
+++ b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_TilePose.h
@@ -14,7 +14,7 @@
 #include <optional>
 #include <string>
 #include <vector>
-#include "Pokemon_Grid.h"
+#include "Pokemon/Navigation/Pokemon_Grid.h"
 #include "Pokemon_StoryEvents.h"
 
 namespace PokemonAutomation{
diff --git a/SerialPrograms/Source/Pokemon/Navigation/Pokemon_Navigation_Tests.h b/SerialPrograms/Source/Pokemon/Navigation/Pokemon_Navigation_Tests.h
index 35bf6d1891..06084295e8 100644
--- a/SerialPrograms/Source/Pokemon/Navigation/Pokemon_Navigation_Tests.h
+++ b/SerialPrograms/Source/Pokemon/Navigation/Pokemon_Navigation_Tests.h
@@ -20,8 +20,6 @@ void add_tests_LegPlanner(UnitTestDatabase& database);
 void add_tests_LegWalker(UnitTestDatabase& database);
 void add_tests_MapData(UnitTestDatabase& database);
 void add_tests_RouteLog(UnitTestDatabase& database);
-void add_tests_StoryEvents(UnitTestDatabase& database);
-void add_tests_StorySegments(UnitTestDatabase& database);
 
 //  (name, JSON text) of each map in Pokemon/Navigation/TestMaps/, built into
 //  the program by pa_embed_text_files() (cmake/EmbedTextFiles.cmake).
diff --git a/SerialPrograms/cmake/SourceFiles.cmake b/SerialPrograms/cmake/SourceFiles.cmake
index 8dfdb300db..ff36ebb054 100644
--- a/SerialPrograms/cmake/SourceFiles.cmake
+++ b/SerialPrograms/cmake/SourceFiles.cmake
@@ -1465,14 +1465,6 @@ file(GLOB LIBRARY_SOURCES
     Source/Pokemon/Navigation/Pokemon_RouteLog.cpp
     Source/Pokemon/Navigation/Pokemon_RouteLog.h
     Source/Pokemon/Navigation/Pokemon_RouteLog_Tests.cpp
-    Source/Pokemon/Navigation/Pokemon_StoryEvents.cpp
-    Source/Pokemon/Navigation/Pokemon_StoryEvents.h
-    Source/Pokemon/Navigation/Pokemon_StoryEvents_Tests.cpp
-    Source/Pokemon/Navigation/Pokemon_StorySegments.cpp
-    Source/Pokemon/Navigation/Pokemon_StorySegments.h
-    Source/Pokemon/Navigation/Pokemon_StorySegments_Tests.cpp
-    Source/Pokemon/Navigation/Pokemon_TilePose.cpp
-    Source/Pokemon/Navigation/Pokemon_TilePose.h
     Source/Pokemon/Options/Pokemon_BoxSortingTable.cpp
     Source/Pokemon/Options/Pokemon_BoxSortingTable.h
     Source/Pokemon/Options/Pokemon_EncounterBotOptions.h
@@ -1488,6 +1480,15 @@ file(GLOB LIBRARY_SOURCES
     Source/Pokemon/Options/Pokemon_StatsHuntFilter.h
     Source/Pokemon/AutoStory/Pokemon_AutoStorySelect.h
     Source/Pokemon/AutoStory/Pokemon_AutoStoryStats.h
+    Source/Pokemon/AutoStory/Pokemon_AutoStory_Tests.h
+    Source/Pokemon/AutoStory/Pokemon_StoryEvents.cpp
+    Source/Pokemon/AutoStory/Pokemon_StoryEvents.h
+    Source/Pokemon/AutoStory/Pokemon_StoryEvents_Tests.cpp
+    Source/Pokemon/AutoStory/Pokemon_StorySegments.cpp
+    Source/Pokemon/AutoStory/Pokemon_StorySegments.h
+    Source/Pokemon/AutoStory/Pokemon_StorySegments_Tests.cpp
+    Source/Pokemon/AutoStory/Pokemon_TilePose.cpp
+    Source/Pokemon/AutoStory/Pokemon_TilePose.h
     Source/Pokemon/Pokemon_AdvRng.cpp
     Source/Pokemon/Pokemon_AdvRng.h
     Source/Pokemon/Pokemon_BdspRng.cpp

From a6a0920b99aae4e1c9e2b56c5fcf2c6c53ba38d4 Mon Sep 17 00:00:00 2001
From: dayfine <difancpa@gmail.com>
Date: Sun, 1 Nov 2026 14:30:03 -0800
Subject: [PATCH 15/19] Pokemon navigation: the class shapes code health asks
 for

Grid is a plain value whose methods only read: a cell is changed through
the free function cell_at(). The leg walker's mover is a callable
(LegMover = std::function) instead of a one-method interface. Position
keeps its virtual describe(), now with a default, since games extend it
with their own data and read it back by type (TilePose).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01AKYzhrMnPK61XHWEch4a6E
---
 .../Pokemon/AutoStory/Pokemon_StoryEvents.h       |  7 +++++--
 .../Source/Pokemon/Navigation/Pokemon_Grid.h      |  9 ++++++---
 .../Source/Pokemon/Navigation/Pokemon_LegWalker.h | 15 ++++++---------
 .../Source/Pokemon/Navigation/Pokemon_MapData.cpp |  2 +-
 4 files changed, 18 insertions(+), 15 deletions(-)

diff --git a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryEvents.h b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryEvents.h
index b2cfc568a0..6ff7dd4141 100644
--- a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryEvents.h
+++ b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryEvents.h
@@ -59,8 +59,11 @@ bool certainty_covers(PoseCertainty have, PoseCertainty need);
 //  actions read it back.
 struct Position{
     virtual ~Position() = default;
-    //  The text after the map in a log line, e.g. "(10, 20) facing north".
-    virtual std::string describe() const = 0;
+    //  The text after the map in a log line, e.g. "(10, 20) facing north";
+    //  none for a game that has nothing to say beyond the map.
+    virtual std::string describe() const{
+        return "";
+    }
 };
 
 //  Where the player is believed to be. The screen is read; the pose is
diff --git a/SerialPrograms/Source/Pokemon/Navigation/Pokemon_Grid.h b/SerialPrograms/Source/Pokemon/Navigation/Pokemon_Grid.h
index 9d4b232579..160b406dfd 100644
--- a/SerialPrograms/Source/Pokemon/Navigation/Pokemon_Grid.h
+++ b/SerialPrograms/Source/Pokemon/Navigation/Pokemon_Grid.h
@@ -56,10 +56,13 @@ struct Grid{
     const Cell& at(const TilePos& pos) const{
         return cells[(size_t)pos.y * width + pos.x];
     }
-    Cell& at(const TilePos& pos){
-        return cells[(size_t)pos.y * width + pos.x];
-    }
 };
+//  The cell at `pos` of `grid`, to change it; `pos` must be inside the grid.
+//  A free function, so that Grid stays a plain value whose methods only read.
+template <typename Cell>
+Cell& cell_at(Grid<Cell>& grid, const TilePos& pos){
+    return grid.cells[(size_t)pos.y * grid.width + pos.x];
+}
 
 
 
diff --git a/SerialPrograms/Source/Pokemon/Navigation/Pokemon_LegWalker.h b/SerialPrograms/Source/Pokemon/Navigation/Pokemon_LegWalker.h
index 0c8018e8ed..ca694db900 100644
--- a/SerialPrograms/Source/Pokemon/Navigation/Pokemon_LegWalker.h
+++ b/SerialPrograms/Source/Pokemon/Navigation/Pokemon_LegWalker.h
@@ -26,6 +26,7 @@
 #include <memory>
 #include <optional>
 #include <string>
+#include <type_traits>
 #include <vector>
 #include "Common/Cpp/Time.h"
 #include "CommonFramework/Exceptions/OperationFailedExceptionWithScreenshot.h"
@@ -62,14 +63,10 @@ template <typename Console, typename Context>
 using LegInterrupts = std::vector<std::unique_ptr<LegInterrupt<Console, Context>>>;
 
 
-//  How the game moves the player.
+//  How the game moves the player: holds `direction` for `duration`, then
+//  lets go.
 template <typename Context>
-class LegMover{
-public:
-    virtual ~LegMover() = default;
-    //  Holds `direction` for `duration`, then lets go.
-    virtual void hold(Context& context, Direction direction, Milliseconds duration) const = 0;
-};
+using LegMover = std::function<void(Context& context, Direction direction, Milliseconds duration)>;
 
 
 //  A straight leg, for a player standing still and facing its way.
@@ -141,7 +138,7 @@ LegResult walk_leg_with(const LegSpec& leg, const LegCalls& calls, size_t max_in
 template <typename Console, typename Context>
 LegResult walk_leg(
     Console& console, Context& context,
-    const LegMover<Context>& mover,
+    const std::type_identity_t<LegMover<Context>>& mover,
     const LegInterrupts<Console, Context>& interrupts,
     const LegSpec& leg,
     size_t max_interruptions = 5
@@ -159,7 +156,7 @@ LegResult walk_leg(
             console, context,
             [&](Context& context){
                 start = current_time();
-                mover.hold(context, leg.direction, hold);
+                mover(context, leg.direction, hold);
             },
             callbacks
         );
diff --git a/SerialPrograms/Source/Pokemon/Navigation/Pokemon_MapData.cpp b/SerialPrograms/Source/Pokemon/Navigation/Pokemon_MapData.cpp
index 963a7fc496..0005f1a176 100644
--- a/SerialPrograms/Source/Pokemon/Navigation/Pokemon_MapData.cpp
+++ b/SerialPrograms/Source/Pokemon/Navigation/Pokemon_MapData.cpp
@@ -328,7 +328,7 @@ MapData parse_map(const JsonValue& json, const std::string& source_name){
     map.patches = read_list<MapPatch>(root, "patches", where, read_patch);
     check_places(map, where);
     for (const MapPatch& patch : map.patches){
-        map.tiles.at(TilePos{patch.x, patch.y}) = patch.glyph;
+        cell_at(map.tiles, TilePos{patch.x, patch.y}) = patch.glyph;
     }
     return map;
 }

From af1b526cbf72d63cb5c3a3fd63ed8809170e0680 Mon Sep 17 00:00:00 2001
From: dayfine <difancpa@gmail.com>
Date: Sun, 1 Nov 2026 15:10:50 -0800
Subject: [PATCH 16/19] Pokemon AutoStory: story lines on the overlay; an event
 that throws is logged

The [Segment], [Checkpoint] and [Event] lines went only to the program's
log, and an event whose game step threw left the runner with no "failed"
line. SegmentHooks gains an optional status sink that gets every line
again without its tag ("00.03/2 below_oaks_trigger: start"), for the
video overlay and, once run records land (#132), for the run's events.
An exception out of an event is logged as "[Event] ... failed: <what>"
and "[Checkpoint] ... failed at <n> <event>: <what>", then rethrown.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01AKYzhrMnPK61XHWEch4a6E
---
 .../Pokemon/AutoStory/Pokemon_StoryEvents.cpp | 31 +++++++++-
 .../AutoStory/Pokemon_StorySegments.cpp       | 30 ++++++++--
 .../Pokemon/AutoStory/Pokemon_StorySegments.h |  5 ++
 .../AutoStory/Pokemon_StorySegments_Tests.cpp | 60 +++++++++++++++++++
 4 files changed, 120 insertions(+), 6 deletions(-)

diff --git a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryEvents.cpp b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryEvents.cpp
index 1f3abf5007..fcbada5a5a 100644
--- a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryEvents.cpp
+++ b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryEvents.cpp
@@ -4,8 +4,10 @@
  *
  */
 
+#include <exception>
 #include <format>
 #include <utility>
+#include "Common/Cpp/Exceptions.h"
 #include "Pokemon_StoryEvents.h"
 
 namespace PokemonAutomation{
@@ -336,6 +338,33 @@ Outcome run_event(EventRun& run){
 }
 
 
+//  What the exception being handled says, for a log line.
+std::string current_exception_text(){
+    try{
+        throw;
+    }catch (Exception& e){
+        return std::string(e.name()) + ": " + e.message();
+    }catch (std::exception& e){
+        return e.what();
+    }catch (...){
+        return "unknown exception";
+    }
+}
+
+//  run_event(), logging the event and its checkpoint as failed before an
+//  exception from the game's steps leaves the runner. The exception goes
+//  on: the game decides what it means.
+Outcome run_event_logging_throws(EventRun& run){
+    try{
+        return run_event(run);
+    }catch (...){
+        const std::string what = current_exception_text();
+        log_status(run, "failed: " + what);
+        run.log(std::format("[Checkpoint] {}: failed at {} {}: {}", run.checkpoint.id, run.number, run.event.name, what));
+        throw;
+    }
+}
+
 CheckpointReport stop_checkpoint(CheckpointReport& report, EventLogger& log, const std::string& id, Outcome failure){
     std::string where = report.failed_event == 0
         ? ""
@@ -377,7 +406,7 @@ CheckpointReport run_checkpoint(RunState& state, Checkpoint& checkpoint, EventLo
             continue;
         }
         report.events_run++;
-        Outcome outcome = run_event(run);
+        Outcome outcome = run_event_logging_throws(run);
         if (!outcome.succeeded()){
             report.failed_event = c + 1;
             report.failed_name = event.name;
diff --git a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StorySegments.cpp b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StorySegments.cpp
index e80ff4915f..eccb26da2c 100644
--- a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StorySegments.cpp
+++ b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StorySegments.cpp
@@ -14,6 +14,25 @@ namespace Pokemon{
 
 namespace{
 
+//  "[Event] 00.03/2 x: start" as "00.03/2 x: start", for the status sink.
+std::string without_tag(const std::string& line){
+    if (line.empty() || line[0] != '['){
+        return line;
+    }
+    const size_t end = line.find("] ");
+    return end == std::string::npos ? line : line.substr(end + 2);
+}
+
+//  A line for the log, and without its tag for the status sink, if set.
+void say(SegmentHooks& hooks, const std::string& line){
+    if (hooks.log){
+        hooks.log(line);
+    }
+    if (hooks.status){
+        hooks.status(without_tag(line));
+    }
+}
+
 std::optional<size_t> index_of(const Segment& segment, const std::string& id){
     for (size_t c = 0; c < segment.checkpoints.size(); c++){
         if (segment.checkpoints[c].id == id){
@@ -96,11 +115,12 @@ CheckpointReport run_row(
                 return hooks.save ? hooks.save(state) : outcome_failed("no_save_hook");
             };
         }
-        CheckpointReport result = run_checkpoint(state, checkpoint, hooks.log);
+        EventLogger log = [&hooks](const std::string& line){ say(hooks, line); };
+        CheckpointReport result = run_checkpoint(state, checkpoint, log);
         if (result.completed || attempt >= policy.attempts_per_checkpoint){
             return result;
         }
-        hooks.log(std::format(
+        say(hooks, std::format(
             "[Segment] {}: {} failed, reloading for attempt {}/{}",
             segment.id, spec.id, attempt + 1, policy.attempts_per_checkpoint
         ));
@@ -120,7 +140,7 @@ SegmentReport stop_segment(SegmentReport& report, SegmentHooks& hooks, const std
             where += " " + report.failed_event;
         }
     }
-    hooks.log(std::format("[Segment] {}: failed{}: {}", id, where, to_string(failure)));
+    say(hooks, std::format("[Segment] {}: failed{}: {}", id, where, to_string(failure)));
     report.failure = std::move(failure);
     return report;
 }
@@ -137,7 +157,7 @@ SegmentReport run_segment(
     if (!selected.failure.succeeded()){
         return stop_segment(report, hooks, segment.id, selected.failure);
     }
-    hooks.log(std::format("[Segment] {}: start, {} checkpoints", segment.id, selected.last - selected.first + 1));
+    say(hooks, std::format("[Segment] {}: start, {} checkpoints", segment.id, selected.last - selected.first + 1));
     for (size_t c = selected.first; c <= selected.last; c++){
         CheckpointSpec& spec = segment.checkpoints[c];
         report.checkpoints_run++;
@@ -149,7 +169,7 @@ SegmentReport run_segment(
         }
     }
     report.completed = true;
-    hooks.log(std::format("[Segment] {}: done, {} checkpoints", segment.id, report.checkpoints_run));
+    say(hooks, std::format("[Segment] {}: done, {} checkpoints", segment.id, report.checkpoints_run));
     return report;
 }
 
diff --git a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StorySegments.h b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StorySegments.h
index 69e181ef57..e7bf2e7468 100644
--- a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StorySegments.h
+++ b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StorySegments.h
@@ -50,6 +50,11 @@ struct SegmentHooks{
     Act save;
     Act reload;
     EventLogger log;
+    //  Optional: each [Segment], [Checkpoint] and [Event] line again,
+    //  without its tag ("00.03/2 below_oaks_trigger: start"), for the video
+    //  overlay, so whoever watches the stream sees the step under way; and,
+    //  once run records land (#132), for the run's events.
+    EventLogger status;
 };
 
 struct SegmentPolicy{
diff --git a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StorySegments_Tests.cpp b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StorySegments_Tests.cpp
index 1fa7b4bdd1..7e014117b5 100644
--- a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StorySegments_Tests.cpp
+++ b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StorySegments_Tests.cpp
@@ -10,6 +10,7 @@
 #include <algorithm>
 #include <functional>
 #include <memory>
+#include <stdexcept>
 #include <string>
 #include <utility>
 #include <vector>
@@ -251,6 +252,63 @@ UnitTestResult test_range(){
     return true;
 }
 
+//  The status sink gets every log line again, without its tag, for the
+//  video overlay.
+UnitTestResult test_status_lines(){
+    Lab lab;
+    Segment segment = twinleaf_to_sandgem(lab.world);
+    SegmentHooks hooks = lab.hooks();
+    std::vector<std::string> status;
+    hooks.status = [&status](const std::string& line){ status.push_back(line); };
+    RunState state;
+    run_segment(state, segment, SegmentRange{}, SegmentPolicy{}, hooks);
+    if (status.size() != lab.lines.size() || status.empty()){
+        return "Expected a status line per log line:" + lab.all();
+    }
+    for (size_t c = 0; c < status.size(); c++){
+        const std::string& line = lab.lines[c];
+        if (line.size() <= status[c].size() || line.compare(line.size() - status[c].size(), status[c].size(), status[c]) != 0){
+            return "Status \"" + status[c] + "\" isn't log line \"" + line + "\" without its tag.";
+        }
+    }
+    if (std::find(status.begin(), status.end(), "00.01/1 walk_out: start") == status.end()){
+        return "Expected \"00.01/1 walk_out: start\" on the overlay.";
+    }
+    return true;
+}
+
+//  An event that throws (a console step failing deep down) is logged as
+//  failed, with its checkpoint, and the exception goes on to the game.
+UnitTestResult test_throwing_event_is_logged(){
+    Lab lab;
+    Segment segment;
+    segment.id = "00";
+    CheckpointSpec spec;
+    spec.id = "00.09";
+    spec.build = []{
+        Checkpoint checkpoint;
+        checkpoint.id = "00.09";
+        checkpoint.events.push_back(make_event("brock", [](RunState&) -> Outcome{
+            throw std::runtime_error("the console vanished");
+        }));
+        return checkpoint;
+    };
+    segment.checkpoints.push_back(std::move(spec));
+    SegmentHooks hooks = lab.hooks();
+    RunState state;
+    try{
+        run_segment(state, segment, SegmentRange{}, SegmentPolicy{}, hooks);
+    }catch (std::runtime_error&){
+        if (!lab.has("[Event] 00.09/1 brock: failed: the console vanished")
+            || !lab.has("[Checkpoint] 00.09: failed at 1 brock: the console vanished")
+        ){
+            return "Expected the event and checkpoint logged as failed:" + lab.all();
+        }
+        return true;
+    }
+    return "Expected the exception to go on to the game.";
+}
+
 UnitTestResult test_describe(){
     Lab lab;
     Segment segment = twinleaf_to_sandgem(lab.world);
@@ -306,6 +364,8 @@ void add_tests_StorySegments(UnitTestDatabase& database){
     database.add<Test_StorySegments>("gives up and names the failure", test_gives_up_and_names_the_failure);
     database.add<Test_StorySegments>("a range of checkpoints", test_range);
     database.add<Test_StorySegments>("describe", test_describe);
+    database.add<Test_StorySegments>("status lines for the overlay", test_status_lines);
+    database.add<Test_StorySegments>("a throwing event is logged, then goes on", test_throwing_event_is_logged);
 }
 
 

From b0ebe0b9d092ace834cbfc875d367a3264fd6c1b Mon Sep 17 00:00:00 2001
From: dayfine <difancpa@gmail.com>
Date: Sun, 1 Nov 2026 16:23:57 -0800
Subject: [PATCH 17/19] Pokemon MapData: the fields BDSP and FRLG maps need

All optional in the JSON, so today's maps parse unchanged:
- world: a map's place on a world grid shared with other maps.
- regions: named, ordered tile lists (replacing numbered points).
- tiles: ' ' off the game's map; '8' '2' '4' '6' one-sided walls.
- elevation: rows of hex digits, the size of the tiles.
- warps: how they are entered (walk_into, step_on, cave_entrance,
  walk_<direction> for mats), and a destination that may be left out
  for a map not loaded; warp_at() finds the warp on a tile.
- objects: trainer sight and the ways a trainer looks; hide_flag.
- triggers: coord-event boxes, with the story state they fire in.
- flag_sets: flags set together, by name.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01AKYzhrMnPK61XHWEch4a6E
---
 .../Pokemon/Navigation/Pokemon_MapData.cpp    | 242 ++++++++++++++++--
 .../Pokemon/Navigation/Pokemon_MapData.h      | 105 ++++++--
 .../Navigation/Pokemon_MapData_Tests.cpp      | 232 +++++++++++++++--
 3 files changed, 531 insertions(+), 48 deletions(-)

diff --git a/SerialPrograms/Source/Pokemon/Navigation/Pokemon_MapData.cpp b/SerialPrograms/Source/Pokemon/Navigation/Pokemon_MapData.cpp
index 0005f1a176..4143fafe48 100644
--- a/SerialPrograms/Source/Pokemon/Navigation/Pokemon_MapData.cpp
+++ b/SerialPrograms/Source/Pokemon/Navigation/Pokemon_MapData.cpp
@@ -4,7 +4,9 @@
  *
  */
 
+#include <cctype>
 #include <format>
+#include <string_view>
 #include <utility>
 #include "Common/Cpp/Exceptions.h"
 #include "Common/Cpp/Json/JsonArray.h"
@@ -28,6 +30,21 @@ constexpr std::pair<char, TileKind> GLYPHS[] = {
     {'>', TileKind::LEDGE_EAST},
     {'D', TileKind::DOOR},
     {'S', TileKind::SIGN},
+    {' ', TileKind::OUTSIDE},
+    {'8', TileKind::CLOSED_NORTH},
+    {'2', TileKind::CLOSED_SOUTH},
+    {'4', TileKind::CLOSED_WEST},
+    {'6', TileKind::CLOSED_EAST},
+};
+
+constexpr std::pair<const char*, WarpEntry> WARP_ENTRIES[] = {
+    {"walk_into", WarpEntry::WALK_INTO},
+    {"step_on", WarpEntry::STEP_ON},
+    {"cave_entrance", WarpEntry::CAVE_ENTRANCE},
+    {"walk_north", WarpEntry::WALK_NORTH},
+    {"walk_south", WarpEntry::WALK_SOUTH},
+    {"walk_west", WarpEntry::WALK_WEST},
+    {"walk_east", WarpEntry::WALK_EAST},
 };
 
 }
@@ -89,18 +106,29 @@ std::string read_string(const JsonObject& object, const std::string& key, const
     return *text;
 }
 
+//  The string `key`, or nothing when the map leaves it out.
+std::optional<std::string> optional_string(const JsonObject& object, const std::string& key, const std::string& where){
+    if (object.get_value(key) == nullptr){
+        return std::nullopt;
+    }
+    return read_string(object, key, where);
+}
+
 TilePos read_pos(const JsonObject& object, const std::string& where){
     return TilePos{read_int(object, "x", where), read_int(object, "y", where)};
 }
 
-Direction read_direction(const JsonObject& object, const std::string& key, const std::string& where){
-    const std::string name = read_string(object, key, where);
+Direction parse_direction(const std::string& name, const std::string& where){
     for (Direction candidate : ALL_DIRECTIONS){
         if (name == direction_name(candidate)){
             return candidate;
         }
     }
-    throw ParseException(std::format("{}{} \"{}\" is not north, east, south or west.", where, key, name));
+    throw ParseException(std::format("{} \"{}\" is not north, east, south or west.", where, name));
+}
+
+Direction read_direction(const JsonObject& object, const std::string& key, const std::string& where){
+    return parse_direction(read_string(object, key, where), where + key);
 }
 
 //  The list `key`, or nothing when the map leaves it out.
@@ -155,6 +183,18 @@ MapSource read_source(const JsonObject& root, const std::string& where){
     return source;
 }
 
+std::optional<MapWorld> read_world(const JsonObject& root, const std::string& where){
+    const JsonObject* object = optional_object(root, "world", where);
+    if (object == nullptr){
+        return std::nullopt;
+    }
+    const std::string world_where = where + "world.";
+    return MapWorld{
+        .name = read_string(*object, "name", world_where),
+        .offset = read_pos(*object, world_where),
+    };
+}
+
 //  Rows of glyphs, all as wide as the first.
 Grid<TileKind> read_tiles(const JsonObject& root, const std::string& where){
     const std::string key = "tiles";
@@ -191,6 +231,68 @@ Grid<TileKind> read_tiles(const JsonObject& root, const std::string& where){
     return grid;
 }
 
+TilePos read_pair(const JsonValue& value, const std::string& where){
+    const JsonArray* pair = value.to_array();
+    if (pair == nullptr || pair->size() != 2 || !(*pair)[0].is_integer() || !(*pair)[1].is_integer()){
+        throw ParseException(where + " is not [x, y].");
+    }
+    return TilePos{(int)(*pair)[0].to_integer_default(), (int)(*pair)[1].to_integer_default()};
+}
+
+//  Rows of hex digits, one per tile.
+std::optional<Grid<uint8_t>> read_elevation(const JsonObject& root, const Grid<TileKind>& tiles, const std::string& where){
+    const std::string key = "elevation";
+    const JsonArray* rows = optional_array(root, key, where);
+    if (rows == nullptr){
+        return std::nullopt;
+    }
+    if ((int)rows->size() != tiles.height){
+        throw ParseException(std::format("{}{} has {} rows, not the tiles' {}.", where, key, rows->size(), tiles.height));
+    }
+    Grid<uint8_t> grid{tiles.width, tiles.height, {}};
+    for (size_t y = 0; y < rows->size(); y++){
+        const std::string row_where = std::format("{}{}[{}]", where, key, y);
+        const std::string* row = (*rows)[y].to_string();
+        if (row == nullptr || (int)row->size() != tiles.width){
+            throw ParseException(std::format("{} is not a string of {} hex digits.", row_where, tiles.width));
+        }
+        for (size_t x = 0; x < row->size(); x++){
+            const char digit = (*row)[x];
+            const size_t value = std::string_view("0123456789abcdef").find((char)std::tolower((unsigned char)digit));
+            if (value == std::string_view::npos){
+                throw ParseException(std::format("{} has '{}' at {}, not a hex digit.", row_where, digit, to_string(TilePos{(int)x, (int)y})));
+            }
+            grid.cells.push_back((uint8_t)value);
+        }
+    }
+    return grid;
+}
+
+//  Each flag set is a list of flag names.
+std::map<std::string, std::set<std::string>> read_flag_sets(const JsonObject& root, const std::string& where){
+    std::map<std::string, std::set<std::string>> sets;
+    const JsonObject* object = optional_object(root, "flag_sets", where);
+    if (object == nullptr){
+        return sets;
+    }
+    for (const auto& [name, value] : *object){
+        const std::string set_where = std::format("{}flag_sets.{}", where, name);
+        const JsonArray* flags = value.to_array();
+        if (flags == nullptr){
+            throw ParseException(set_where + " is not a list of flags.");
+        }
+        std::set<std::string>& set = sets[name];
+        for (size_t c = 0; c < flags->size(); c++){
+            const std::string* flag = (*flags)[c].to_string();
+            if (flag == nullptr){
+                throw ParseException(std::format("{}[{}] is not a string.", set_where, c));
+            }
+            set.insert(*flag);
+        }
+    }
+    return sets;
+}
+
 std::map<std::string, TilePos> read_points(const JsonObject& root, const std::string& where){
     std::map<std::string, TilePos> points;
     const JsonObject* object = optional_object(root, "points", where);
@@ -198,22 +300,65 @@ std::map<std::string, TilePos> read_points(const JsonObject& root, const std::st
         return points;
     }
     for (const auto& [name, value] : *object){
-        const JsonArray* pair = value.to_array();
-        if (pair == nullptr || pair->size() != 2 || !(*pair)[0].is_integer() || !(*pair)[1].is_integer()){
-            throw ParseException(std::format("{}points.{} is not [x, y].", where, name));
-        }
-        points[name] = TilePos{(int)(*pair)[0].to_integer_default(), (int)(*pair)[1].to_integer_default()};
+        points[name] = read_pair(value, std::format("{}points.{}", where, name));
     }
     return points;
 }
 
+//  Each region is a non-empty list of [x, y].
+std::map<std::string, std::vector<TilePos>> read_regions(const JsonObject& root, const std::string& where){
+    std::map<std::string, std::vector<TilePos>> regions;
+    const JsonObject* object = optional_object(root, "regions", where);
+    if (object == nullptr){
+        return regions;
+    }
+    for (const auto& [name, value] : *object){
+        const std::string region_where = std::format("{}regions.{}", where, name);
+        const JsonArray* tiles = value.to_array();
+        if (tiles == nullptr || tiles->empty()){
+            throw ParseException(region_where + " is not a non-empty list of [x, y].");
+        }
+        std::vector<TilePos>& region = regions[name];
+        for (size_t c = 0; c < tiles->size(); c++){
+            region.push_back(read_pair((*tiles)[c], std::format("{}[{}]", region_where, c)));
+        }
+    }
+    return regions;
+}
+
+WarpEntry read_warp_entry(const JsonObject& object, const std::string& where){
+    const std::optional<std::string> name = optional_string(object, "enter", where);
+    if (!name){
+        return WarpEntry::WALK_INTO;
+    }
+    for (const auto& [known, entry] : WARP_ENTRIES){
+        if (*name == known){
+            return entry;
+        }
+    }
+    throw ParseException(std::format(
+        "{}enter \"{}\" is not walk_into, step_on, cave_entrance or walk_<direction>.", where, *name
+    ));
+}
+
+//  `to_map` and `to_point` come together, or neither does.
 MapWarp read_warp(const JsonObject& object, const std::string& where){
     MapWarp warp;
     const TilePos pos = read_pos(object, where);
     warp.x = pos.x;
     warp.y = pos.y;
-    warp.to_map = read_string(object, "to_map", where);
-    warp.to_point = read_string(object, "to_point", where);
+    warp.enter = read_warp_entry(object, where);
+    const bool has_map = object.get_value("to_map") != nullptr;
+    const bool has_point = object.get_value("to_point") != nullptr;
+    if (has_map != has_point){
+        throw ParseException(where + (has_map ? "to_point" : "to_map") + " is missing.");
+    }
+    if (has_map){
+        warp.to = WarpDestination{
+            .map = read_string(object, "to_map", where),
+            .point = read_string(object, "to_point", where),
+        };
+    }
     return warp;
 }
 
@@ -231,8 +376,8 @@ ObjectKind read_object_kind(const JsonObject& object, const std::string& where){
     throw ParseException(std::format("{}kind \"{}\" is not npc, item or sign.", where, kind));
 }
 
-WanderBox read_wander(const JsonObject& object, const std::string& where){
-    WanderBox box;
+TileBox read_box(const JsonObject& object, const std::string& where){
+    TileBox box;
     box.x0 = read_int(object, "x0", where);
     box.y0 = read_int(object, "y0", where);
     box.x1 = read_int(object, "x1", where);
@@ -243,6 +388,32 @@ WanderBox read_wander(const JsonObject& object, const std::string& where){
     return box;
 }
 
+//  `looks` defaults to the trainer's facing.
+MapTrainer read_trainer(const JsonObject& object, const std::optional<Direction>& facing, const std::string& where){
+    MapTrainer trainer;
+    trainer.sight = read_int(object, "sight", where);
+    if (trainer.sight < 1){
+        throw ParseException(std::format("{}sight {} is not at least 1.", where, trainer.sight));
+    }
+    const JsonArray* looks = optional_array(object, "looks", where);
+    if (looks == nullptr){
+        if (!facing){
+            throw ParseException(where + "looks is missing, and the object has no facing.");
+        }
+        trainer.looks.push_back(*facing);
+        return trainer;
+    }
+    for (size_t c = 0; c < looks->size(); c++){
+        const std::string item_where = std::format("{}looks[{}]", where, c);
+        const std::string* name = (*looks)[c].to_string();
+        if (name == nullptr){
+            throw ParseException(item_where + " is not a string.");
+        }
+        trainer.looks.push_back(parse_direction(*name, item_where));
+    }
+    return trainer;
+}
+
 MapObject read_object(const JsonObject& object, const std::string& where){
     MapObject map_object;
     map_object.name = read_string(object, "name", where);
@@ -254,11 +425,25 @@ MapObject read_object(const JsonObject& object, const std::string& where){
         map_object.facing = read_direction(object, "facing", where);
     }
     if (const JsonObject* wander = optional_object(object, "wander", where)){
-        map_object.wander = read_wander(*wander, where + "wander.");
+        map_object.wander = read_box(*wander, where + "wander.");
     }
+    if (const JsonObject* trainer = optional_object(object, "trainer", where)){
+        map_object.trainer = read_trainer(*trainer, map_object.facing, where + "trainer.");
+    }
+    map_object.hide_flag = optional_string(object, "hide_flag", where);
     return map_object;
 }
 
+MapTrigger read_trigger(const JsonObject& object, const std::string& where){
+    MapTrigger trigger;
+    trigger.name = read_string(object, "name", where);
+    //  Named, since GCC warns of a reference returned for a temporary path.
+    const std::string key = "box";
+    trigger.box = read_box(as_object(read_field(object, key, where), where + key), where + key + ".");
+    trigger.when = optional_string(object, "when", where);
+    return trigger;
+}
+
 MapConnection read_connection(const JsonObject& object, const std::string& where){
     MapConnection connection;
     connection.side = read_direction(object, "side", where);
@@ -289,11 +474,21 @@ void check_inside(const Grid<TileKind>& tiles, const TilePos& pos, const std::st
     }
 }
 
+void check_box_inside(const Grid<TileKind>& tiles, const TileBox& box, const std::string& where){
+    check_inside(tiles, TilePos{box.x0, box.y0}, where);
+    check_inside(tiles, TilePos{box.x1, box.y1}, where);
+}
+
 //  Everything with a place on the map has it inside the tiles.
 void check_places(const MapData& map, const std::string& where){
     for (const auto& [name, pos] : map.points){
         check_inside(map.tiles, pos, where + "points." + name);
     }
+    for (const auto& [name, region] : map.regions){
+        for (size_t c = 0; c < region.size(); c++){
+            check_inside(map.tiles, region[c], std::format("{}regions.{}[{}]", where, name, c));
+        }
+    }
     for (size_t c = 0; c < map.warps.size(); c++){
         check_inside(map.tiles, TilePos{map.warps[c].x, map.warps[c].y}, std::format("{}warps[{}]", where, c));
     }
@@ -301,11 +496,12 @@ void check_places(const MapData& map, const std::string& where){
         const MapObject& object = map.objects[c];
         check_inside(map.tiles, TilePos{object.x, object.y}, std::format("{}objects[{}]", where, c));
         if (object.wander){
-            const std::string wander_where = std::format("{}objects[{}].wander", where, c);
-            check_inside(map.tiles, TilePos{object.wander->x0, object.wander->y0}, wander_where);
-            check_inside(map.tiles, TilePos{object.wander->x1, object.wander->y1}, wander_where);
+            check_box_inside(map.tiles, *object.wander, std::format("{}objects[{}].wander", where, c));
         }
     }
+    for (size_t c = 0; c < map.triggers.size(); c++){
+        check_box_inside(map.tiles, map.triggers[c].box, std::format("{}triggers[{}].box", where, c));
+    }
     for (size_t c = 0; c < map.patches.size(); c++){
         check_inside(map.tiles, TilePos{map.patches[c].x, map.patches[c].y}, std::format("{}patches[{}]", where, c));
     }
@@ -320,10 +516,15 @@ MapData parse_map(const JsonValue& json, const std::string& source_name){
     MapData map;
     map.name = read_string(root, "name", where);
     map.source = read_source(root, where);
+    map.world = read_world(root, where);
     map.tiles = read_tiles(root, where);
+    map.elevation = read_elevation(root, map.tiles, where);
     map.points = read_points(root, where);
+    map.regions = read_regions(root, where);
     map.warps = read_list<MapWarp>(root, "warps", where, read_warp);
     map.objects = read_list<MapObject>(root, "objects", where, read_object);
+    map.triggers = read_list<MapTrigger>(root, "triggers", where, read_trigger);
+    map.flag_sets = read_flag_sets(root, where);
     map.connections = read_list<MapConnection>(root, "connections", where, read_connection);
     map.patches = read_list<MapPatch>(root, "patches", where, read_patch);
     check_places(map, where);
@@ -333,6 +534,15 @@ MapData parse_map(const JsonValue& json, const std::string& source_name){
     return map;
 }
 
+const MapWarp* warp_at(const MapData& map, const TilePos& pos){
+    for (const MapWarp& warp : map.warps){
+        if (warp.x == pos.x && warp.y == pos.y){
+            return &warp;
+        }
+    }
+    return nullptr;
+}
+
 
 
 }
diff --git a/SerialPrograms/Source/Pokemon/Navigation/Pokemon_MapData.h b/SerialPrograms/Source/Pokemon/Navigation/Pokemon_MapData.h
index 766182714b..06470fa251 100644
--- a/SerialPrograms/Source/Pokemon/Navigation/Pokemon_MapData.h
+++ b/SerialPrograms/Source/Pokemon/Navigation/Pokemon_MapData.h
@@ -4,24 +4,33 @@
  *
  *  A map as a navigation program sees it, read from the one JSON schema the
  *  tile games (BDSP, FRLG) share: the tiles as rows of glyphs, the named
- *  points routes start and end at, the warps, the objects standing on the
- *  map, the connections to neighbouring maps, and patches that put tiles
- *  measured on the console on top of the decompilation's data.
+ *  points and regions routes start and end at, the warps, the objects
+ *  standing on the map, the scenes that start on stepping somewhere, the
+ *  connections to neighbouring maps, and patches that put tiles measured on
+ *  the console on top of the decompilation's data.
  *
  *      {
  *          "name": "TestTown",
  *          "source": {"decomp_file": "data/maps/TestTown/map.json", "revision": "abc123", "date": "2026-10-31"},
+ *          "world": {"name": "Sinnoh", "x": 96, "y": 864},
  *          "tiles": ["####", "#..~", ...],             //  rows of glyphs, all the same length
+ *          "elevation": ["3333", "3300", ...],         //  one hex digit per tile
  *          "points": {"door": [1, 2], ...},
- *          "warps": [{"x": 1, "y": 2, "to_map": "TestHouse", "to_point": "exit"}, ...],
+ *          "regions": {"lawn": [[1, 1], [2, 1]], ...},
+ *          "warps": [{"x": 1, "y": 2, "enter": "walk_into", "to_map": "TestHouse", "to_point": "exit"}, ...],
  *          "objects": [{"name": "mom", "kind": "npc", "x": 2, "y": 1,
- *                       "facing": "south", "wander": {"x0": 1, "y0": 1, "x1": 2, "y1": 2}}, ...],
+ *                       "facing": "south", "wander": {"x0": 1, "y0": 1, "x1": 2, "y1": 2},
+ *                       "trainer": {"sight": 4, "looks": ["south", "west"]},
+ *                       "hide_flag": "FLAG_HIDE_MOM"}, ...],
+ *          "triggers": [{"name": "mom_warning", "box": {"x0": 1, "y0": 2, "x1": 1, "y1": 2}, "when": "00.01"}, ...],
+ *          "flag_sets": {"after_00.01": ["FLAG_HIDE_MOM", ...], ...},
  *          "connections": [{"side": "east", "to_map": "Route 1", "offset": 0}, ...],
  *          "patches": [{"x": 2, "y": 1, "glyph": "#", "measured_by": "run 3, 2026-10-30"}, ...]
  *      }
  *
- *  `name`, `source` and `tiles` are required; the lists may be left out.
- *  Which game's planner reads these maps, and how, is the game's business.
+ *  `name`, `source` and `tiles` are required; everything else may be left
+ *  out. Which game's planner reads these maps, and how, is the game's
+ *  business.
  *
  */
 
@@ -31,6 +40,7 @@
 #include <cstdint>
 #include <map>
 #include <optional>
+#include <set>
 #include <string>
 #include <vector>
 #include "Common/Cpp/Json/JsonValue.h"
@@ -50,8 +60,14 @@ enum class TileKind : uint8_t{
     LEDGE_SOUTH,    //  'v'  way hops the player over it
     LEDGE_WEST,     //  '<'
     LEDGE_EAST,     //  '>'
-    DOOR,           //  'D'  a door or warp tile
+    DOOR,           //  'D'  a door or warp tile walked into
     SIGN,           //  'S'  a sign, read by facing it
+    OUTSIDE,        //  ' '  no map of the game's here (a map's rectangle
+                    //       reaching past the game's own)
+    CLOSED_NORTH,   //  '8'  open, but not crossed through its named side:
+    CLOSED_SOUTH,   //  '2'  not entered from it, nor left through it (the
+    CLOSED_WEST,    //  '4'  number pad's arrows)
+    CLOSED_EAST,    //  '6'
 };
 //  The tile a glyph stands for, or nothing if it isn't one.
 std::optional<TileKind> tile_from_glyph(char glyph);
@@ -66,12 +82,41 @@ struct MapSource{
     std::string date;
 };
 
-//  Stepping onto (x, y) puts the player at point `to_point` of `to_map`.
+//  Where the map lies on a world grid that several maps share (a BDSP map
+//  matrix): its tile (0, 0) is tile `offset` of world `name`. Maps on the
+//  same world join where they meet.
+struct MapWorld{
+    std::string name;
+    TilePos offset;
+};
+
+//  Where a warp puts the player: point `point` of map `map`.
+struct WarpDestination{
+    std::string map;
+    std::string point;
+};
+
+//  How the player takes a warp, as the map file writes it.
+enum class WarpEntry{
+    WALK_INTO,      //  "walk_into": a door or cave mouth, walked into
+    STEP_ON,        //  "step_on": stepping onto the tile (ladders,
+                    //  escalators, BDSP's warp tiles)
+    CAVE_ENTRANCE,  //  "cave_entrance": stepping onto the tile; the game
+                    //  walks a player arriving on it a tile south
+    WALK_NORTH,     //  "walk_north" ...: standing on the tile and walking
+    WALK_SOUTH,     //  that way (exit mats, stairs at the side of a room)
+    WALK_WEST,
+    WALK_EAST,
+};
+
+//  A warp from (x, y), taken as `enter` says. `to` is left out for a warp
+//  to a map that is not loaded: the warp is still there, for routes to keep
+//  off.
 struct MapWarp{
     int x = 0;
     int y = 0;
-    std::string to_map;
-    std::string to_point;
+    WarpEntry enter = WarpEntry::WALK_INTO;
+    std::optional<WarpDestination> to;
 };
 
 enum class ObjectKind{
@@ -80,23 +125,41 @@ enum class ObjectKind{
     SIGN,
 };
 
-//  The tiles a wanderer may stand on, both corners inclusive.
-struct WanderBox{
+//  A box of tiles, both corners inclusive.
+struct TileBox{
     int x0 = 0;
     int y0 = 0;
     int x1 = 0;
     int y1 = 0;
 };
 
+//  A trainer sees `sight` tiles ahead in each direction of `looks` (their
+//  facing, unless the map says otherwise).
+struct MapTrainer{
+    int sight = 0;
+    std::vector<Direction> looks;
+};
+
 //  Something standing on a tile, which blocks it. A person who wanders may
-//  stand anywhere in `wander`.
+//  stand anywhere in `wander`. The game hides the object while `hide_flag`
+//  is set (an event flag, or a story state the game's code sets).
 struct MapObject{
     std::string name;
     ObjectKind kind = ObjectKind::NPC;
     int x = 0;
     int y = 0;
     std::optional<Direction> facing;
-    std::optional<WanderBox> wander;
+    std::optional<TileBox> wander;
+    std::optional<MapTrainer> trainer;
+    std::optional<std::string> hide_flag;
+};
+
+//  A scene that starts when the player steps into `box` while the story is
+//  in `when` (any time, if left out): the decompilation's coord events.
+struct MapTrigger{
+    std::string name;
+    TileBox box;
+    std::optional<std::string> when;
 };
 
 //  Walking off the map's `side` continues on `to_map`, whose tiles are
@@ -118,11 +181,20 @@ struct MapPatch{
 struct MapData{
     std::string name;
     MapSource source;
+    std::optional<MapWorld> world;
     //  With the patches applied.
     Grid<TileKind> tiles;
+    //  The same size as `tiles`. FRLG reads a map without it as all ground
+    //  (elevation 3); what the values mean is the game's business.
+    std::optional<Grid<uint8_t>> elevation;
     std::map<std::string, TilePos> points;
+    //  Named sets of tiles, in the order the map lists them.
+    std::map<std::string, std::vector<TilePos>> regions;
     std::vector<MapWarp> warps;
     std::vector<MapObject> objects;
+    std::vector<MapTrigger> triggers;
+    //  Flags set together, by name (e.g. "after_hall_of_fame").
+    std::map<std::string, std::set<std::string>> flag_sets;
     std::vector<MapConnection> connections;
     std::vector<MapPatch> patches;
 };
@@ -133,6 +205,9 @@ struct MapData{
 //  doesn't fit the schema, or places something outside the tiles.
 MapData parse_map(const JsonValue& json, const std::string& source_name);
 
+//  The warp on `pos`, or nullptr if there is none.
+const MapWarp* warp_at(const MapData& map, const TilePos& pos);
+
 
 
 }
diff --git a/SerialPrograms/Source/Pokemon/Navigation/Pokemon_MapData_Tests.cpp b/SerialPrograms/Source/Pokemon/Navigation/Pokemon_MapData_Tests.cpp
index 6d5eee680f..8048f65224 100644
--- a/SerialPrograms/Source/Pokemon/Navigation/Pokemon_MapData_Tests.cpp
+++ b/SerialPrograms/Source/Pokemon/Navigation/Pokemon_MapData_Tests.cpp
@@ -3,11 +3,15 @@
  *  From: https://github.com/PokemonAutomation/
  *
  *  parse_map() on a small synthetic map: the good map, a map with only the
- *  required fields, and one row per error class.
+ *  required fields, and one row per error class; and on a map shaped like
+ *  each game's (BDSP, FRLG), for the fields only that game writes today.
  *
  */
 
+#include <format>
 #include <functional>
+#include <optional>
+#include <set>
 #include <string>
 #include <utility>
 #include <vector>
@@ -37,16 +41,66 @@ const char* const VALID_MAP = R"({
     "patches": [{"x": 2, "y": 1, "glyph": "#", "measured_by": "run 3, 2026-10-30"}]
 })";
 
-//  The valid map with `find` replaced by `replacement`; empty when `find`
-//  is not in it.
-std::string edited(const std::string& find, const std::string& replacement){
-    std::string json = VALID_MAP;
+//  A map shaped like BDSP's: on a world grid, with tiles off the game's
+//  map, a region, a warp tile stood on, trainers, a person the story hides
+//  and scene triggers.
+const char* const BDSP_MAP = R"({
+    "name": "Route 201",
+    "source": {"decomp_file": "pret/pokediamond: land_data narc_0000.bin", "revision": "default branch", "date": "2026-11-01"},
+    "world": {"name": "Sinnoh", "x": 96, "y": 839},
+    "tiles": ["  ###", " #..#", "#.~..", "#..v#"],
+    "points": {"save_spot": [2, 1]},
+    "regions": {"lawn": [[3, 2], [1, 2], [1, 3]]},
+    "warps": [{"x": 4, "y": 2, "enter": "step_on"}],
+    "objects": [
+        {"name": "youngster_tristan", "kind": "npc", "x": 3, "y": 1, "facing": "west", "trainer": {"sight": 2}},
+        {"name": "lass_natalie", "kind": "npc", "x": 1, "y": 3, "facing": "north", "trainer": {"sight": 3, "looks": ["north", "east"]}},
+        {"name": "rowan", "kind": "npc", "x": 2, "y": 3, "hide_flag": "story_after_00.03"}
+    ],
+    "triggers": [
+        {"name": "barry_warning", "box": {"x0": 2, "y0": 1, "x1": 3, "y1": 1}, "when": "00.02"},
+        {"name": "border_sign", "box": {"x0": 1, "y0": 2, "x1": 1, "y1": 2}}
+    ]
+})";
+
+//  A map shaped like FRLG's: elevations, one-sided walls, warps of every
+//  entry to per-warp points (one to a map not loaded), a person hidden by
+//  an event flag, and a flag set.
+const char* const FRLG_MAP = R"({
+    "name": "CeruleanCave_1F",
+    "source": {"decomp_file": "data/maps/CeruleanCave_1F/map.json", "revision": "ce6406d8c2ea", "date": "2026-11-01"},
+    "width": 4,
+    "tiles": ["#..#", "8.2#", "4.6."],
+    "elevation": ["3303", "3F03", "0a33"],
+    "points": {"warp_0": [1, 0]},
+    "warps": [
+        {"x": 1, "y": 0, "enter": "cave_entrance", "to_map": "CeruleanCity", "to_point": "warp_6"},
+        {"x": 2, "y": 0, "enter": "step_on"},
+        {"x": 1, "y": 1, "enter": "walk_north", "to_map": "CeruleanCave_2F", "to_point": "warp_0"},
+        {"x": 2, "y": 1, "enter": "walk_south", "to_map": "CeruleanCave_2F", "to_point": "warp_1"},
+        {"x": 1, "y": 2, "enter": "walk_west", "to_map": "CeruleanCave_2F", "to_point": "warp_2"},
+        {"x": 3, "y": 2, "enter": "walk_east", "to_map": "CeruleanCave_2F", "to_point": "warp_3"}
+    ],
+    "objects": [
+        {"name": "cooltrainer_m_1", "kind": "npc", "x": 1, "y": 1, "hide_flag": "FLAG_HIDE_CERULEAN_CAVE_GUARD",
+         "wander": {"x0": 1, "y0": 1, "x1": 2, "y1": 1}}
+    ],
+    "flag_sets": {"after_hall_of_fame": ["FLAG_B", "FLAG_HIDE_CERULEAN_CAVE_GUARD", "FLAG_B"]}
+})";
+
+//  `base` with `find` replaced by `replacement`; empty when `find` is not
+//  in it.
+std::string edited(const char* base, const std::string& find, const std::string& replacement){
+    std::string json = base;
     const size_t at = json.find(find);
     if (at == std::string::npos){
         return "";
     }
     return json.replace(at, find.size(), replacement);
 }
+std::string edited(const std::string& find, const std::string& replacement){
+    return edited(VALID_MAP, find, replacement);
+}
 
 //  The ParseException that parsing `json` throws, or empty if it doesn't.
 std::string parse_error(const std::string& json){
@@ -90,7 +144,8 @@ UnitTestResult test_valid_map(){
         return "Wrong points.";
     }
     if (map.warps.size() != 1 || map.warps[0].x != 1 || map.warps[0].y != 2
-        || map.warps[0].to_map != "TestHouse" || map.warps[0].to_point != "exit"
+        || map.warps[0].enter != WarpEntry::WALK_INTO || !map.warps[0].to
+        || map.warps[0].to->map != "TestHouse" || map.warps[0].to->point != "exit"
     ){
         return "Wrong warps.";
     }
@@ -115,8 +170,9 @@ UnitTestResult test_lists_may_be_left_out(){
         "source": {"decomp_file": "f", "revision": "r", "date": "d"},
         "tiles": ["#.#"]
     })"), "Cave.json");
-    if (map.tiles.width != 3 || map.tiles.height != 1 || !map.points.empty() || !map.warps.empty()
-        || !map.objects.empty() || !map.connections.empty() || !map.patches.empty()
+    if (map.tiles.width != 3 || map.tiles.height != 1 || map.world || map.elevation
+        || !map.points.empty() || !map.regions.empty() || !map.warps.empty() || !map.objects.empty()
+        || !map.triggers.empty() || !map.flag_sets.empty() || !map.connections.empty() || !map.patches.empty()
     ){
         return "Expected a 3x1 map with nothing on it.";
     }
@@ -124,7 +180,7 @@ UnitTestResult test_lists_may_be_left_out(){
 }
 
 UnitTestResult test_glyphs_round_trip(){
-    for (char glyph : std::string("#.~wv^<>DS")){
+    for (char glyph : std::string("#.~wv^<>DS 8246")){
         const std::optional<TileKind> tile = tile_from_glyph(glyph);
         if (!tile || glyph_of(*tile) != glyph){
             return std::string("Glyph '") + glyph + "' does not round-trip.";
@@ -142,6 +198,20 @@ struct BadMap{
     std::vector<const char*> mentions;
 };
 
+//  The first row whose map doesn't fail as it says, or true.
+UnitTestResult first_wrong_error(const std::vector<BadMap>& rows){
+    for (const BadMap& row : rows){
+        if (row.json.empty()){
+            return std::string(row.name) + ": the text to edit is not in its map.";
+        }
+        const std::string error = parse_error(row.json);
+        if (!mentions(error, row.mentions)){
+            return std::string(row.name) + ": expected an error naming " + row.mentions.back() + ", got: \"" + error + "\"";
+        }
+    }
+    return true;
+}
+
 UnitTestResult test_each_error_class(){
     const std::vector<BadMap> rows = {
         {.name = "not an object", .json = "[]", .mentions = {"Test.json", "not a JSON object"}},
@@ -153,7 +223,9 @@ UnitTestResult test_each_error_class(){
         {.name = "unknown glyph", .json = edited("\"#..~\"", "\"#.?~\""), .mentions = {"tiles[1]", "unknown glyph '?'", "(2, 1)"}},
         {.name = "point not a pair", .json = edited("\"door\": [1, 2]", "\"door\": [1]"), .mentions = {"points.door", "[x, y]"}},
         {.name = "point outside", .json = edited("\"sign\": [3, 2]", "\"sign\": [4, 2]"), .mentions = {"points.sign", "(4, 2)", "outside the 4x4 map"}},
-        {.name = "warp missing a field", .json = edited("\"to_point\": \"exit\"", "\"to\": \"exit\""), .mentions = {"warps[0].to_point is missing"}},
+        {.name = "warp missing to_point", .json = edited("\"to_point\": \"exit\"", "\"to\": \"exit\""), .mentions = {"warps[0].to_point is missing"}},
+        {.name = "warp missing to_map", .json = edited("\"to_map\": \"TestHouse\"", "\"map\": \"TestHouse\""), .mentions = {"warps[0].to_map is missing"}},
+        {.name = "warp entry unknown", .json = edited("\"to_map\": \"TestHouse\"", "\"enter\": \"jump\", \"to_map\": \"TestHouse\""), .mentions = {"warps[0].enter", "jump", "walk_into"}},
         {.name = "warp field of the wrong type", .json = edited("{\"x\": 1, \"y\": 2, \"to_map\"", "{\"x\": \"1\", \"y\": 2, \"to_map\""), .mentions = {"warps[0].x is not an integer"}},
         {.name = "object kind unknown", .json = edited("\"kind\": \"item\"", "\"kind\": \"boss\""), .mentions = {"objects[1].kind", "boss", "npc, item or sign"}},
         {.name = "object facing unknown", .json = edited("\"facing\": \"south\"", "\"facing\": \"down\""), .mentions = {"objects[0].facing", "down", "north, east, south or west"}},
@@ -163,18 +235,141 @@ UnitTestResult test_each_error_class(){
         {.name = "patch glyph unknown", .json = edited("\"glyph\": \"#\"", "\"glyph\": \"?\""), .mentions = {"patches[0].glyph", "?", "not a tile glyph"}},
         {.name = "patch outside", .json = edited("{\"x\": 2, \"y\": 1, \"glyph\"", "{\"x\": 2, \"y\": 9, \"glyph\""), .mentions = {"patches[0]", "(2, 9)", "outside"}},
     };
-    for (const BadMap& row : rows){
-        if (row.json.empty()){
-            return std::string(row.name) + ": the text to edit is not in the valid map.";
-        }
-        const std::string error = parse_error(row.json);
-        if (!mentions(error, row.mentions)){
-            return std::string(row.name) + ": expected an error naming " + row.mentions.back() + ", got: \"" + error + "\"";
+    return first_wrong_error(rows);
+}
+
+//  One value read from a parsed map, and what it should be, both as text.
+struct Expected{
+    const char* what;
+    std::string expected;
+    std::string read;
+};
+
+//  The first row whose value was read wrong, or true.
+UnitTestResult first_wrong(const std::vector<Expected>& rows){
+    for (const Expected& row : rows){
+        if (row.read != row.expected){
+            return std::format("{}: expected \"{}\", read \"{}\".", row.what, row.expected, row.read);
         }
     }
     return true;
 }
 
+std::string text(const std::optional<std::string>& value){
+    return value ? *value : "(none)";
+}
+std::string text(const std::vector<TilePos>& tiles){
+    std::string out;
+    for (const TilePos& pos : tiles){
+        out += to_string(pos);
+    }
+    return out;
+}
+std::string text(const std::optional<MapTrainer>& trainer){
+    if (!trainer){
+        return "(none)";
+    }
+    std::string out = std::format("sight {}, looks", trainer->sight);
+    for (Direction direction : trainer->looks){
+        out += std::string(" ") + direction_name(direction);
+    }
+    return out;
+}
+std::string text(const TileBox& box){
+    return std::format("({}, {})..({}, {})", box.x0, box.y0, box.x1, box.y1);
+}
+std::string text(const MapWarp* warp){
+    if (warp == nullptr){
+        return "(none)";
+    }
+    const std::string to = warp->to ? warp->to->map + "." + warp->to->point : "(not loaded)";
+    return std::format("{} {} -> {}", to_string(TilePos{warp->x, warp->y}), (int)warp->enter, to);
+}
+std::string text(const std::set<std::string>& flags){
+    std::string out;
+    for (const std::string& flag : flags){
+        out += flag + " ";
+    }
+    return out;
+}
+
+UnitTestResult test_bdsp_shaped_map(){
+    const MapData map = parse_map(parse_json(BDSP_MAP), "Route201.json");
+    const std::string world = map.world ? map.world->name + " " + to_string(map.world->offset) : "(none)";
+    return first_wrong({
+        {.what = "world", .expected = "Sinnoh (96, 839)", .read = world},
+        {.what = "tile (0, 0)", .expected = "' '", .read = std::format("'{}'", glyph_of(map.tiles.at({0, 0})))},
+        {.what = "tile (0, 1) is off the map", .expected = "1", .read = std::to_string(map.tiles.at({0, 1}) == TileKind::OUTSIDE)},
+        {.what = "region lawn, in order", .expected = "(3, 2)(1, 2)(1, 3)", .read = text(map.regions.at("lawn"))},
+        {.what = "warp_at (4, 2)", .expected = std::format("(4, 2) {} -> (not loaded)", (int)WarpEntry::STEP_ON), .read = text(warp_at(map, {4, 2}))},
+        {.what = "warp_at (3, 2)", .expected = "(none)", .read = text(warp_at(map, {3, 2}))},
+        {.what = "Tristan, sight along his facing", .expected = "sight 2, looks west", .read = text(map.objects[0].trainer)},
+        {.what = "Natalie, sight both ways", .expected = "sight 3, looks north east", .read = text(map.objects[1].trainer)},
+        {.what = "Rowan is no trainer", .expected = "(none)", .read = text(map.objects[2].trainer)},
+        {.what = "Rowan's hide flag", .expected = "story_after_00.03", .read = text(map.objects[2].hide_flag)},
+        {.what = "Tristan's hide flag", .expected = "(none)", .read = text(map.objects[0].hide_flag)},
+        {.what = "trigger 0", .expected = "barry_warning (2, 1)..(3, 1) 00.02", .read = std::format(
+            "{} {} {}", map.triggers[0].name, text(map.triggers[0].box), text(map.triggers[0].when)
+        )},
+        {.what = "trigger 1, any time", .expected = "border_sign (none)", .read = map.triggers[1].name + " " + text(map.triggers[1].when)},
+    });
+}
+
+UnitTestResult test_frlg_shaped_map(){
+    const MapData map = parse_map(parse_json(FRLG_MAP), "CeruleanCave_1F.json");
+    if (!map.elevation || map.elevation->width != 4 || map.elevation->height != 3){
+        return "Expected 4x3 elevations.";
+    }
+    const auto tile = [&](const TilePos& pos){
+        return std::format("'{}'", glyph_of(map.tiles.at(pos)));
+    };
+    const auto elevation = [&](const TilePos& pos){
+        return std::to_string(map.elevation->at(pos));
+    };
+    const auto warp = [&](WarpEntry enter, const TilePos& pos, const char* to){
+        return std::format("{} {} -> {}", to_string(pos), (int)enter, to);
+    };
+    return first_wrong({
+        {.what = "closed north", .expected = "'8'", .read = tile({0, 1})},
+        {.what = "closed south", .expected = "'2'", .read = tile({2, 1})},
+        {.what = "closed west", .expected = "'4'", .read = tile({0, 2})},
+        {.what = "closed east", .expected = "'6'", .read = tile({2, 2})},
+        {.what = "elevation (2, 0)", .expected = "0", .read = elevation({2, 0})},
+        {.what = "elevation (1, 1), upper case", .expected = "15", .read = elevation({1, 1})},
+        {.what = "elevation (1, 2), lower case", .expected = "10", .read = elevation({1, 2})},
+        {.what = "cave entrance", .expected = warp(WarpEntry::CAVE_ENTRANCE, {1, 0}, "CeruleanCity.warp_6"), .read = text(warp_at(map, {1, 0}))},
+        {.what = "ladder to a map not loaded", .expected = warp(WarpEntry::STEP_ON, {2, 0}, "(not loaded)"), .read = text(warp_at(map, {2, 0}))},
+        {.what = "mat north", .expected = warp(WarpEntry::WALK_NORTH, {1, 1}, "CeruleanCave_2F.warp_0"), .read = text(warp_at(map, {1, 1}))},
+        {.what = "mat south", .expected = warp(WarpEntry::WALK_SOUTH, {2, 1}, "CeruleanCave_2F.warp_1"), .read = text(warp_at(map, {2, 1}))},
+        {.what = "mat west", .expected = warp(WarpEntry::WALK_WEST, {1, 2}, "CeruleanCave_2F.warp_2"), .read = text(warp_at(map, {1, 2}))},
+        {.what = "mat east", .expected = warp(WarpEntry::WALK_EAST, {3, 2}, "CeruleanCave_2F.warp_3"), .read = text(warp_at(map, {3, 2}))},
+        {.what = "the guard's hide flag", .expected = "FLAG_HIDE_CERULEAN_CAVE_GUARD", .read = text(map.objects[0].hide_flag)},
+        {.what = "flag set, each flag once", .expected = "FLAG_B FLAG_HIDE_CERULEAN_CAVE_GUARD ", .read = text(map.flag_sets.at("after_hall_of_fame"))},
+    });
+}
+
+UnitTestResult test_each_error_class_of_game_fields(){
+    return first_wrong_error({
+        {.name = "world missing a field", .json = edited(BDSP_MAP, "\"name\": \"Sinnoh\"", "\"grid\": \"Sinnoh\""), .mentions = {"world.name is missing"}},
+        {.name = "unknown glyph", .json = edited(BDSP_MAP, "\"  ###\"", "\"  #9#\""), .mentions = {"tiles[0]", "unknown glyph '9'"}},
+        {.name = "region empty", .json = edited(BDSP_MAP, "[[3, 2], [1, 2], [1, 3]]", "[]"), .mentions = {"regions.lawn", "non-empty"}},
+        {.name = "region tile not a pair", .json = edited(BDSP_MAP, "[[3, 2], [1, 2]", "[[3, 2], [1]"), .mentions = {"regions.lawn[1]", "[x, y]"}},
+        {.name = "region tile outside", .json = edited(BDSP_MAP, "[[3, 2], [1, 2]", "[[3, 2], [9, 2]"), .mentions = {"regions.lawn[1]", "(9, 2)", "outside"}},
+        {.name = "trainer with no way to look", .json = edited(BDSP_MAP, "\"facing\": \"west\", ", ""), .mentions = {"objects[0].trainer.looks is missing"}},
+        {.name = "trainer sight below 1", .json = edited(BDSP_MAP, "\"sight\": 2", "\"sight\": 0"), .mentions = {"objects[0].trainer.sight 0", "at least 1"}},
+        {.name = "trainer looks unknown", .json = edited(BDSP_MAP, "[\"north\", \"east\"]", "[\"north\", \"up\"]"), .mentions = {"objects[1].trainer.looks[1]", "up"}},
+        {.name = "hide flag not a string", .json = edited(BDSP_MAP, "\"story_after_00.03\"", "3"), .mentions = {"objects[2].hide_flag is not a string"}},
+        {.name = "trigger missing its box", .json = edited(BDSP_MAP, "\"box\": {\"x0\": 2", "\"area\": {\"x0\": 2"), .mentions = {"triggers[0].box is missing"}},
+        {.name = "trigger outside", .json = edited(BDSP_MAP, "\"x1\": 3, \"y1\": 1", "\"x1\": 7, \"y1\": 1"), .mentions = {"triggers[0].box", "(7, 1)", "outside"}},
+        {.name = "warp entry unknown", .json = edited(FRLG_MAP, "\"step_on\"", "\"fly\""), .mentions = {"warps[1].enter", "fly"}},
+        {.name = "elevation rows missing", .json = edited(FRLG_MAP, ", \"0a33\"]", "]"), .mentions = {"elevation has 2 rows", "tiles' 3"}},
+        {.name = "elevation row short", .json = edited(FRLG_MAP, "\"3F03\"", "\"3F0\""), .mentions = {"elevation[1]", "4 hex digits"}},
+        {.name = "elevation not hex", .json = edited(FRLG_MAP, "\"3F03\"", "\"3G03\""), .mentions = {"elevation[1]", "'G'", "not a hex digit"}},
+        {.name = "flag set not a list", .json = edited(FRLG_MAP, "[\"FLAG_B\", \"FLAG_HIDE_CERULEAN_CAVE_GUARD\", \"FLAG_B\"]", "\"FLAG_B\""), .mentions = {"flag_sets.after_hall_of_fame", "not a list"}},
+        {.name = "flag not a string", .json = edited(FRLG_MAP, "[\"FLAG_B\", ", "[7, "), .mentions = {"flag_sets.after_hall_of_fame[0] is not a string"}},
+    });
+}
+
 
 class Test_MapData : public UnitTest{
 public:
@@ -228,6 +423,9 @@ void add_tests_MapData(UnitTestDatabase& database){
     database.add<Test_MapData>("lists may be left out", test_lists_may_be_left_out);
     database.add<Test_MapData>("glyphs round-trip", test_glyphs_round_trip);
     database.add<Test_MapData>("each error class", test_each_error_class);
+    database.add<Test_MapData>("a map shaped like BDSP's", test_bdsp_shaped_map);
+    database.add<Test_MapData>("a map shaped like FRLG's", test_frlg_shaped_map);
+    database.add<Test_MapData>("each error class of the game fields", test_each_error_class_of_game_fields);
     database.add<Test_MapData>("maps built into the program", test_built_in_maps);
 }
 

From 16e8456f70c27e6343c192256ddb7dcd84ffb2b3 Mon Sep 17 00:00:00 2001
From: dayfine <difancpa@gmail.com>
Date: Mon, 2 Nov 2026 19:29:18 -0800
Subject: [PATCH 18/19] Pokemon MapData: allow_running, for maps where the
 player can't run

FRLG's indoor maps, the Pokemon Centers among them, don't let the player
run (pokefirered's map header allow_running): B held there still walks,
so a walker timing a run would stop short. A map file that leaves the
field out allows running.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01AKYzhrMnPK61XHWEch4a6E
---
 .../Source/Pokemon/Navigation/Pokemon_MapData.cpp   | 13 +++++++++++++
 .../Source/Pokemon/Navigation/Pokemon_MapData.h     |  5 +++++
 .../Pokemon/Navigation/Pokemon_MapData_Tests.cpp    |  7 +++++--
 3 files changed, 23 insertions(+), 2 deletions(-)

diff --git a/SerialPrograms/Source/Pokemon/Navigation/Pokemon_MapData.cpp b/SerialPrograms/Source/Pokemon/Navigation/Pokemon_MapData.cpp
index 4143fafe48..99d8f61168 100644
--- a/SerialPrograms/Source/Pokemon/Navigation/Pokemon_MapData.cpp
+++ b/SerialPrograms/Source/Pokemon/Navigation/Pokemon_MapData.cpp
@@ -106,6 +106,18 @@ std::string read_string(const JsonObject& object, const std::string& key, const
     return *text;
 }
 
+//  The boolean `key`, or `fallback` when the map leaves it out.
+bool optional_bool(const JsonObject& object, const std::string& key, bool fallback, const std::string& where){
+    const JsonValue* value = object.get_value(key);
+    if (value == nullptr){
+        return fallback;
+    }
+    if (!value->is_boolean()){
+        throw ParseException(where + key + " is not true or false.");
+    }
+    return value->to_boolean_default(fallback);
+}
+
 //  The string `key`, or nothing when the map leaves it out.
 std::optional<std::string> optional_string(const JsonObject& object, const std::string& key, const std::string& where){
     if (object.get_value(key) == nullptr){
@@ -517,6 +529,7 @@ MapData parse_map(const JsonValue& json, const std::string& source_name){
     map.name = read_string(root, "name", where);
     map.source = read_source(root, where);
     map.world = read_world(root, where);
+    map.allow_running = optional_bool(root, "allow_running", true, where);
     map.tiles = read_tiles(root, where);
     map.elevation = read_elevation(root, map.tiles, where);
     map.points = read_points(root, where);
diff --git a/SerialPrograms/Source/Pokemon/Navigation/Pokemon_MapData.h b/SerialPrograms/Source/Pokemon/Navigation/Pokemon_MapData.h
index 06470fa251..52d0a7c4d2 100644
--- a/SerialPrograms/Source/Pokemon/Navigation/Pokemon_MapData.h
+++ b/SerialPrograms/Source/Pokemon/Navigation/Pokemon_MapData.h
@@ -13,6 +13,7 @@
  *          "name": "TestTown",
  *          "source": {"decomp_file": "data/maps/TestTown/map.json", "revision": "abc123", "date": "2026-10-31"},
  *          "world": {"name": "Sinnoh", "x": 96, "y": 864},
+ *          "allow_running": false,                     //  left out: true
  *          "tiles": ["####", "#..~", ...],             //  rows of glyphs, all the same length
  *          "elevation": ["3333", "3300", ...],         //  one hex digit per tile
  *          "points": {"door": [1, 2], ...},
@@ -182,6 +183,10 @@ struct MapData{
     std::string name;
     MapSource source;
     std::optional<MapWorld> world;
+    //  Whether the game lets the player run here. FRLG's indoor maps, such as
+    //  the Pokemon Centers, don't (pokefirered's map header allow_running):
+    //  B held there still walks.
+    bool allow_running = true;
     //  With the patches applied.
     Grid<TileKind> tiles;
     //  The same size as `tiles`. FRLG reads a map without it as all ground
diff --git a/SerialPrograms/Source/Pokemon/Navigation/Pokemon_MapData_Tests.cpp b/SerialPrograms/Source/Pokemon/Navigation/Pokemon_MapData_Tests.cpp
index 8048f65224..eddda7daf0 100644
--- a/SerialPrograms/Source/Pokemon/Navigation/Pokemon_MapData_Tests.cpp
+++ b/SerialPrograms/Source/Pokemon/Navigation/Pokemon_MapData_Tests.cpp
@@ -69,6 +69,7 @@ const char* const BDSP_MAP = R"({
 const char* const FRLG_MAP = R"({
     "name": "CeruleanCave_1F",
     "source": {"decomp_file": "data/maps/CeruleanCave_1F/map.json", "revision": "ce6406d8c2ea", "date": "2026-11-01"},
+    "allow_running": false,
     "width": 4,
     "tiles": ["#..#", "8.2#", "4.6."],
     "elevation": ["3303", "3F03", "0a33"],
@@ -170,11 +171,11 @@ UnitTestResult test_lists_may_be_left_out(){
         "source": {"decomp_file": "f", "revision": "r", "date": "d"},
         "tiles": ["#.#"]
     })"), "Cave.json");
-    if (map.tiles.width != 3 || map.tiles.height != 1 || map.world || map.elevation
+    if (map.tiles.width != 3 || map.tiles.height != 1 || map.world || !map.allow_running || map.elevation
         || !map.points.empty() || !map.regions.empty() || !map.warps.empty() || !map.objects.empty()
         || !map.triggers.empty() || !map.flag_sets.empty() || !map.connections.empty() || !map.patches.empty()
     ){
-        return "Expected a 3x1 map with nothing on it.";
+        return "Expected a 3x1 map with nothing on it, where the player may run.";
     }
     return true;
 }
@@ -345,6 +346,7 @@ UnitTestResult test_frlg_shaped_map(){
         {.what = "mat east", .expected = warp(WarpEntry::WALK_EAST, {3, 2}, "CeruleanCave_2F.warp_3"), .read = text(warp_at(map, {3, 2}))},
         {.what = "the guard's hide flag", .expected = "FLAG_HIDE_CERULEAN_CAVE_GUARD", .read = text(map.objects[0].hide_flag)},
         {.what = "flag set, each flag once", .expected = "FLAG_B FLAG_HIDE_CERULEAN_CAVE_GUARD ", .read = text(map.flag_sets.at("after_hall_of_fame"))},
+        {.what = "no running", .expected = "false", .read = map.allow_running ? "true" : "false"},
     });
 }
 
@@ -367,6 +369,7 @@ UnitTestResult test_each_error_class_of_game_fields(){
         {.name = "elevation not hex", .json = edited(FRLG_MAP, "\"3F03\"", "\"3G03\""), .mentions = {"elevation[1]", "'G'", "not a hex digit"}},
         {.name = "flag set not a list", .json = edited(FRLG_MAP, "[\"FLAG_B\", \"FLAG_HIDE_CERULEAN_CAVE_GUARD\", \"FLAG_B\"]", "\"FLAG_B\""), .mentions = {"flag_sets.after_hall_of_fame", "not a list"}},
         {.name = "flag not a string", .json = edited(FRLG_MAP, "[\"FLAG_B\", ", "[7, "), .mentions = {"flag_sets.after_hall_of_fame[0] is not a string"}},
+        {.name = "allow_running not a boolean", .json = edited(FRLG_MAP, "\"allow_running\": false", "\"allow_running\": 0"), .mentions = {"allow_running is not true or false"}},
     });
 }
 

From acf85aa2411a125ea1088908e66d4eff93351f1f Mon Sep 17 00:00:00 2001
From: dayfine <difancpa@gmail.com>
Date: Tue, 3 Nov 2026 05:14:36 -0800
Subject: [PATCH 19/19] Pokemon AutoStory: verify a checkpoint, N runs from one
 save

verify_checkpoint() runs one checkpoint a set number of times, each from
the save the first started from, never saving at its end, and passes it
when enough runs pass (3 runs, 2 passes by default). Each run logs a
[Verify] line, then the summary. For battles that lost twice or more: they
get their own checkpoint, saved right before, verified this way.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01AKYzhrMnPK61XHWEch4a6E
---
 .../AutoStory/Pokemon_StorySegments.cpp       | 73 +++++++++++++++++++
 .../Pokemon/AutoStory/Pokemon_StorySegments.h | 35 +++++++++
 .../AutoStory/Pokemon_StorySegments_Tests.cpp | 68 +++++++++++++++++
 3 files changed, 176 insertions(+)

diff --git a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StorySegments.cpp b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StorySegments.cpp
index eccb26da2c..a0e538d318 100644
--- a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StorySegments.cpp
+++ b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StorySegments.cpp
@@ -174,6 +174,79 @@ SegmentReport run_segment(
 }
 
 
+namespace{
+
+//  One verify run: the checkpoint built fresh, without its end save.
+//  Returns true if it passed.
+bool verify_run(
+    RunState& state, CheckpointSpec& spec, size_t run, const VerifyPolicy& policy, SegmentHooks& hooks
+){
+    Checkpoint checkpoint = spec.build();
+    checkpoint.save = nullptr;
+    EventLogger log = [&hooks](const std::string& line){ say(hooks, line); };
+    const CheckpointReport result = run_checkpoint(state, checkpoint, log);
+    if (result.completed){
+        say(hooks, std::format("[Verify] {}: run {}/{} passed", spec.id, run, policy.runs));
+        return true;
+    }
+    say(hooks, std::format(
+        "[Verify] {}: run {}/{} failed{}: {}",
+        spec.id, run, policy.runs,
+        result.failed_name.empty() ? "" : " at " + result.failed_name,
+        to_string(result.failure)
+    ));
+    return false;
+}
+
+VerifyReport verify_summary(VerifyReport& report, const VerifyPolicy& policy, SegmentHooks& hooks){
+    report.verified = report.failure.succeeded() && report.passes >= policy.passes_needed;
+    say(hooks, std::format(
+        "[Verify] {}: {}/{} passed, {} needed: {}",
+        report.checkpoint, report.passes, policy.runs, policy.passes_needed,
+        report.verified ? "verified" : "not verified"
+    ));
+    return report;
+}
+
+}
+
+
+VerifyReport verify_checkpoint(
+    RunState& state, Segment& segment, const std::string& id,
+    const VerifyPolicy& policy, SegmentHooks& hooks
+){
+    VerifyReport report;
+    report.checkpoint = id;
+    const std::optional<size_t> index = index_of(segment, id);
+    if (!index){
+        report.failure = outcome_failed("unknown_checkpoint", id);
+    }else 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));
+    }
+    if (!report.failure.succeeded()){
+        say(hooks, std::format("[Verify] {}: {}", id, to_string(report.failure)));
+        return report;
+    }
+    CheckpointSpec& spec = segment.checkpoints[*index];
+    say(hooks, std::format(
+        "[Verify] {}: start, {} runs from one save, {} must pass", id, policy.runs, policy.passes_needed
+    ));
+    for (size_t run = 1; run <= policy.runs; run++){
+        if (run > 1){
+            Outcome reloaded = reload(state, hooks);
+            if (!reloaded.succeeded()){
+                say(hooks, std::format("[Verify] {}: no reload before run {}: {}", id, run, to_string(reloaded)));
+                report.failure = std::move(reloaded);
+                break;
+            }
+        }
+        report.runs++;
+        report.passes += verify_run(state, spec, run, policy, hooks) ? 1 : 0;
+    }
+    return verify_summary(report, policy, hooks);
+}
+
+
 std::string describe(Segment& segment){
     std::string text = std::format("segment {}: {} checkpoints\n", segment.id, segment.checkpoints.size());
     for (const CheckpointSpec& spec : segment.checkpoints){
diff --git a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StorySegments.h b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StorySegments.h
index e7bf2e7468..eb9b039f1a 100644
--- a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StorySegments.h
+++ b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StorySegments.h
@@ -93,6 +93,41 @@ SegmentReport run_segment(
     const SegmentPolicy& policy, SegmentHooks& hooks
 );
 
+
+//  Verify mode, for a checkpoint that must be shown to hold up (a battle
+//  lost twice or more gets its own checkpoint, saved right before it, and is
+//  verified this way): the checkpoint run `runs` times, each from the same
+//  save. The checkpoint never saves at its end, so each run after the first
+//  reloads the save the first started from.
+struct VerifyPolicy{
+    size_t runs = 3;
+    //  Passing runs the checkpoint needs to be verified.
+    size_t passes_needed = 2;
+};
+
+struct VerifyReport{
+    std::string checkpoint;
+    size_t runs = 0;
+    size_t passes = 0;
+    //  At least VerifyPolicy::passes_needed runs passed.
+    bool verified = false;
+    //  What stopped the runs early: an unknown checkpoint, a bad policy or
+    //  a failed reload. Runs that fail are counted, not stopped at.
+    Outcome failure;
+};
+
+//  Runs checkpoint `id` of `segment` as `policy` says, from the save the
+//  game is on. No retries, no in-place recoveries and no save at its end.
+//  Logs through `hooks.log`, after each run's checkpoint lines:
+//      [Verify] 00.15b: start, 3 runs from one save, 2 must pass
+//      [Verify] 00.15b: run 1/3 passed
+//      [Verify] 00.15b: run 2/3 failed at rival_battle: battle_lost
+//      [Verify] 00.15b: 2/3 passed, 2 needed: verified
+VerifyReport verify_checkpoint(
+    RunState& state, Segment& segment, const std::string& id,
+    const VerifyPolicy& policy, SegmentHooks& hooks
+);
+
 //  A readable dump for review: the rows, then each checkpoint built once
 //  and described as describe(const Checkpoint&) does. Nothing runs.
 std::string describe(Segment& segment);
diff --git a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StorySegments_Tests.cpp b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StorySegments_Tests.cpp
index 7e014117b5..bde8ba8aa8 100644
--- a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StorySegments_Tests.cpp
+++ b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StorySegments_Tests.cpp
@@ -309,6 +309,71 @@ UnitTestResult test_throwing_event_is_logged(){
     return "Expected the exception to go on to the game.";
 }
 
+//  Verify mode: every run starts from the save the first started from, a
+//  failed run is counted, not retried, and 2 of 3 passes verify it.
+UnitTestResult test_verify_runs_from_one_save(){
+    Lab lab;
+    lab.world.map = "Route 201";
+    lab.saved = lab.world;
+    lab.world.walk_failures = 1;
+    Segment segment = twinleaf_to_sandgem(lab.world);
+    SegmentHooks hooks = lab.hooks();
+    RunState state;
+    const VerifyReport report = verify_checkpoint(state, segment, "00.02", VerifyPolicy{}, hooks);
+    const std::vector<std::string> expected = {"walk_south", "reload", "walk_south", "reload", "walk_south"};
+    if (!report.verified || report.runs != 3 || report.passes != 2 || lab.world.trace != expected){
+        return "Expected three runs, reloading between them, two passing:" + lab.all();
+    }
+    if (!lab.has("[Verify] 00.02: start, 3 runs from one save, 2 must pass")
+        || !lab.has("[Verify] 00.02: run 1/3 failed at walk_south: blocked: a wanderer on the path")
+        || !lab.has("[Verify] 00.02: run 2/3 passed")
+        || lab.lines.back() != "[Verify] 00.02: 2/3 passed, 2 needed: verified"
+    ){
+        return "Expected a line per run, then the summary:" + lab.all();
+    }
+    return true;
+}
+
+//  A checkpoint that saves at its end doesn't in verify mode: the next run
+//  would start after it.
+UnitTestResult test_verify_skips_the_end_save(){
+    Lab lab;
+    Segment segment = twinleaf_to_sandgem(lab.world);
+    SegmentHooks hooks = lab.hooks();
+    RunState state;
+    const VerifyReport report = verify_checkpoint(state, segment, "00.01", VerifyPolicy{.runs = 2, .passes_needed = 2}, hooks);
+    const std::vector<std::string> expected = {"walk_out", "reload", "walk_out"};
+    if (!report.verified || lab.world.trace != expected || lab.saved.map != "Twinleaf Town"){
+        return "Expected two runs from Twinleaf Town and no save:" + lab.all();
+    }
+    return true;
+}
+
+UnitTestResult test_verify_too_few_passes(){
+    Lab lab;
+    lab.world.map = "Route 201";
+    lab.saved = lab.world;
+    lab.world.walk_failures = 2;
+    Segment segment = twinleaf_to_sandgem(lab.world);
+    SegmentHooks hooks = lab.hooks();
+    RunState state;
+    const VerifyReport report = verify_checkpoint(state, segment, "00.02", VerifyPolicy{}, hooks);
+    if (report.verified || report.runs != 3 || report.passes != 1
+        || lab.lines.back() != "[Verify] 00.02: 1/3 passed, 2 needed: not verified"
+    ){
+        return "Expected 1 of 3, not verified:" + lab.all();
+    }
+    VerifyReport bad = verify_checkpoint(state, segment, "00.02", VerifyPolicy{.runs = 2, .passes_needed = 3}, hooks);
+    if (bad.verified || bad.runs != 0 || bad.failure.failure != "bad_verify_policy"){
+        return "Expected more passes than runs refused:" + lab.all();
+    }
+    bad = verify_checkpoint(state, segment, "00.09", VerifyPolicy{}, hooks);
+    if (bad.verified || bad.runs != 0 || bad.failure.failure != "unknown_checkpoint"){
+        return "Expected an unknown checkpoint refused:" + lab.all();
+    }
+    return true;
+}
+
 UnitTestResult test_describe(){
     Lab lab;
     Segment segment = twinleaf_to_sandgem(lab.world);
@@ -366,6 +431,9 @@ void add_tests_StorySegments(UnitTestDatabase& database){
     database.add<Test_StorySegments>("describe", test_describe);
     database.add<Test_StorySegments>("status lines for the overlay", test_status_lines);
     database.add<Test_StorySegments>("a throwing event is logged, then goes on", test_throwing_event_is_logged);
+    database.add<Test_StorySegments>("verify: runs from one save", test_verify_runs_from_one_save);
+    database.add<Test_StorySegments>("verify: no save at the end", test_verify_skips_the_end_save);
+    database.add<Test_StorySegments>("verify: too few passes", test_verify_too_few_passes);
 }