From 8b2df5a0b448fd5d4c205239e85e2a23057f226f Mon Sep 17 00:00:00 2001 From: dayfine Date: Thu, 12 Nov 2026 15:36:34 -0800 Subject: [PATCH 1/5] Design: FRLG path to the Elite Four (story order, gates, scripted mechanics) Records the user's 2026-11-12 decisions: STORY_ORDER instead of renumbering, Lapras and the Master Ball option, no Sevii or Seafoam, the trainer-card badge check, gate tiles for Silph, the Mansion and the Cinnabar Gym, and scripted arrow tiles and boulders. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_013VUubhHeYSMGSSDXZkKZss --- docs/design/AutoStory.md | 58 +++++++++++++++++++++++++++++++++++++--- 1 file changed, 55 insertions(+), 3 deletions(-) diff --git a/docs/design/AutoStory.md b/docs/design/AutoStory.md index 0b225f704e..ee68954ee0 100644 --- a/docs/design/AutoStory.md +++ b/docs/design/AutoStory.md @@ -673,9 +673,9 @@ positions; the decomp is the source of truth. | 04 | Route 9/10 → Rock Tunnel → Lavender → Celadon → Erika; Tea | Flash optional | | 05 | Rocket Hideout (spin tiles, Lift Key, Silph Scope) → Pokémon Tower → Poké Flute | | | 06 | Snorlax (Route 12 or 16) → Fuchsia → Koga → Safari (Surf, Strength) | Safari is a step-limited zone | -| 07 | Saffron: Silph Co. (Card Key, warp pads, rival, Giovanni) → Sabrina | Lapras optional | -| 08 | To Cinnabar (Route 21 by default) → Mansion (Secret Key) → Blaine | Seafoam optional; decline One Island | -| 09 | Giovanni (Viridian) → Route 22 rival → Victory Road (Strength boulders) | | +| 07 | Saffron: Silph Co. (Card Key, warp pads, rival, Giovanni) → Sabrina | Card Key doors are gates (§12.2); Lapras is an RNG gift like Eevee; Master Ball is an option (§12.1) | +| 08 | To Cinnabar (Route 21 by default) → Mansion (Secret Key) → Blaine | Mansion switches and quiz doors are gates, Mansion holes are one-way warps (§12.2); no Seafoam; decline Bill's One Island trip | +| 09 | Giovanni (Viridian) → Route 22 rival → Victory Road (Strength boulders) | arrow tiles and boulders are scripted (§12.3); Route 23 guards: read the badges on the trainer card | | 10 | Elite Four + Champion | reuse `EliteFourFarmer` pieces | | 11 | Sevii post-game: Ruby (Mt. Ember), Sapphire (Dotted Hole), Network Machine | added 2026-10-29 (§9.2) | | 12 | Mew | method to settle (§9.2); likely needs the naming typer | @@ -948,3 +948,55 @@ Step arguments stay one closed variant. Games with no tiles walk by game action of such a game that uses a tile argument (`DIRECTION`, `LEGS`, `GRID_POSE`). PLZA's walk legs, today `INTEGER_ROWS`, move to `TIMED_LEGS` in its own chain. + +## 12. Path to the Elite Four (user, 2026-11-12) + +### 12.1 Order and options + +Checkpoint ids need not follow story order. Different starters reorder +segments anyway, so ids are never renumbered; the table runs in the order of +an explicit `STORY_ORDER` list, and a checkpoint missing from it, or listed +twice, fails to load. + +- Silph Co.: Lapras is an RNG gift, done the same way as the Eevee gift. The + Master Ball from the president is taken by default, as a program option + that SPEEDRUN mode skips. +- After Blaine, decline Bill's trip to One Island. The Sevii Islands are not + part of the run to the Elite Four. +- Cinnabar is reached by Surf down Route 21; Seafoam Islands are not part of + the MVP. +- Route 23: before the badge guards, read the badge count from the trainer + card. + +### 12.2 Gates: doors that open during the story + +Silph Co.'s Card Key doors, the Pokémon Mansion's statue-switch barriers and +the Cinnabar Gym's quiz doors are walls that open during the story. The map +data marks them with one tile kind, `gate`, and each map lists its gates: +their tiles, the flag or variable that opens them, and how (Card Key and A, +a switch, a quiz or a trainer). A Mansion switch toggles a set of gates, so +the map also lists, per switch state, which gates are open. The overlays stay +the record of which flags are set at each point of the story. + +AutoStory keeps the gates as story state: +- The checkpoint records the gates it opened and the Mansion switch state, + and a checkpoint's declared start includes the gate state it expects. +- The planner treats a closed gate as a wall unless the plan opens it; + opening is one action step (face it and press A) that the planner adds. In + the Mansion the switch state is part of the search, and the open gates + follow from it. +- When the state is not known, after a hand recovery for example, it comes + from the story's progress, or else from a shot of a gate tile before + planning. + +Holes that drop to the floor below (the Mansion, some caves) are one-way +warps, and the planner may use them as such. + +### 12.3 Scripted mechanics + +- Viridian Gym's arrow tiles are scripted like the Rocket Hideout's spin + tiles: step onto the arrow without counting tiles, wait for the screen to + settle, then localize from where the slide stopped. +- Victory Road's boulders are not modelled as movable objects. Each push + waits for the screen to settle and then checks that the boulder is still + next to the player in the push direction before the next push. From 9cd16dbc58f7fadce1a0ecc5818c1fc4265bc81b Mon Sep 17 00:00:00 2001 From: dayfine Date: Thu, 12 Nov 2026 20:47:39 -0800 Subject: [PATCH 2/5] FRLG AutoStory: the chain test expects 70 checkpoints (the split's merge counted one twice) Co-Authored-By: Claude Sonnet 5.5 Claude-Session: https://claude.ai/code/session_013VUubhHeYSMGSSDXZkKZss --- .../Programs/AutoStory/PokemonFRLG_AutoStory_Tests.cpp | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/SerialPrograms/Source/VideoGames/PokemonFRLG/Programs/AutoStory/PokemonFRLG_AutoStory_Tests.cpp b/SerialPrograms/Source/VideoGames/PokemonFRLG/Programs/AutoStory/PokemonFRLG_AutoStory_Tests.cpp index 1fea476e03..af78b7d424 100644 --- a/SerialPrograms/Source/VideoGames/PokemonFRLG/Programs/AutoStory/PokemonFRLG_AutoStory_Tests.cpp +++ b/SerialPrograms/Source/VideoGames/PokemonFRLG/Programs/AutoStory/PokemonFRLG_AutoStory_Tests.cpp @@ -292,8 +292,8 @@ UnitTestResult check_checkpoint(const StoryCheckpoint& checkpoint, StoryPose& po // start: starts_after_unauthored_rows()), and adds the plans to `golden`. UnitTestResult chain_story_routes(std::vector& golden){ const std::vector& checkpoints = story_checkpoints(); - if (checkpoints.size() != 69 || checkpoints[0].start){ - return "Expected 69 checkpoints, the first from a new game."; + if (checkpoints.size() != 70 || checkpoints[0].start){ + return "Expected 70 checkpoints, the first from a new game."; } StoryPose pose; for (size_t c = 0; c < checkpoints.size(); c++){ From 040ecadf08919a35e30ab424af2f7ea63ba46153 Mon Sep 17 00:00:00 2001 From: dayfine Date: Thu, 12 Nov 2026 21:53:53 -0800 Subject: [PATCH 3/5] FRLG AutoStory design: segments 07 and 08 in PokeGuy's order after Koga Co-Authored-By: Claude Sonnet 5.5 Claude-Session: https://claude.ai/code/session_013VUubhHeYSMGSSDXZkKZss --- docs/design/AutoStory.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/docs/design/AutoStory.md b/docs/design/AutoStory.md index ee68954ee0..7f44beeeb3 100644 --- a/docs/design/AutoStory.md +++ b/docs/design/AutoStory.md @@ -673,14 +673,16 @@ positions; the decomp is the source of truth. | 04 | Route 9/10 → Rock Tunnel → Lavender → Celadon → Erika; Tea | Flash optional | | 05 | Rocket Hideout (spin tiles, Lift Key, Silph Scope) → Pokémon Tower → Poké Flute | | | 06 | Snorlax (Route 12 or 16) → Fuchsia → Koga → Safari (Surf, Strength) | Safari is a step-limited zone | -| 07 | Saffron: Silph Co. (Card Key, warp pads, rival, Giovanni) → Sabrina | Card Key doors are gates (§12.2); Lapras is an RNG gift like Eevee; Master Ball is an option (§12.1) | -| 08 | To Cinnabar (Route 21 by default) → Mansion (Secret Key) → Blaine | Mansion switches and quiz doors are gates, Mansion holes are one-way warps (§12.2); no Seafoam; decline Bill's One Island trip | +| 07 | To Cinnabar (Route 21 by default) → Mansion (Secret Key) → Blaine | Mansion switches and quiz doors are gates, Mansion holes are one-way warps (§12.2); no Seafoam; decline Bill's One Island trip | +| 08 | Saffron: Silph Co. (Card Key, warp pads, rival, Giovanni) → Sabrina | Card Key doors are gates (§12.2); Lapras is an RNG gift like Eevee; Master Ball is an option (§12.1) | | 09 | Giovanni (Viridian) → Route 22 rival → Victory Road (Strength boulders) | arrow tiles and boulders are scripted (§12.3); Route 23 guards: read the badges on the trainer card | | 10 | Elite Four + Champion | reuse `EliteFourFarmer` pieces | | 11 | Sevii post-game: Ruby (Mt. Ember), Sapphire (Dotted Hole), Network Machine | added 2026-10-29 (§9.2) | | 12 | Mew | method to settle (§9.2); likely needs the naming typer | | opt | Money top-up, leveling loop, gift Pokémon, fossils | config-driven, outside the main order | +The story order after Koga follows PokeGuy's run: Fly to Pallet, Surf down Route 21 to Cinnabar, the Mansion and Blaine (TM14 Blizzard taught over Dig), Fly back to Celadon for Erika, then Silph Co., Sabrina's gym and Viridian's gym (STORY_ORDER in PokemonFRLG_AutoStoryTable.cpp is the exact order). + Estimate ~90–110 checkpoints. Hardest: 00 (keyboard, intro), 05 (spin tiles), 07 (warp pads), 09 (boulders), and leveling before each gym. From 7fa5530ec5ea8fd03a63c9d0d1faf35688e68c40 Mon Sep 17 00:00:00 2001 From: dayfine Date: Sat, 14 Nov 2026 14:39:59 -0800 Subject: [PATCH 4/5] Design FRLG AutoStory dex collection --- docs/design/AutoStory-FRLG-Dex-Collection.md | 583 +++++++++++++++++++ 1 file changed, 583 insertions(+) create mode 100644 docs/design/AutoStory-FRLG-Dex-Collection.md diff --git a/docs/design/AutoStory-FRLG-Dex-Collection.md b/docs/design/AutoStory-FRLG-Dex-Collection.md new file mode 100644 index 0000000000..f523d01edd --- /dev/null +++ b/docs/design/AutoStory-FRLG-Dex-Collection.md @@ -0,0 +1,583 @@ +# FRLG AutoStory: goal-driven Pokédex collection + +Status: **design only**. The actions, readers, catalog and program described +here are not implemented. This design is stacked on the current FRLG AutoStory +design and implementation through the Elite Four. + +## 1. Goal and meaning of completion + +Add a bounded part of FRLG AutoStory that can: + +1. read which species the save has registered as caught; +2. distinguish obtainable, locked, unsupported and unavailable missing species; +3. choose a supported acquisition and a place to perform it; +4. prepare supplies and route there through the existing story actions; +5. run the existing capture machinery; +6. verify the registration, save it, and plan the next target; and +7. finish with an exact completion/blocker report rather than loop forever. + +"Pokédex collection" means **caught registrations**, not keeping one specimen +of every species. A living-dex mode would need a party/PC ownership scan and +retention constraints in addition to the Pokédex state. It should be a later +mode, not an overloaded meaning of this one. + +A FireRed save cannot register every species by itself. Version exclusives, +trade evolutions, mutually exclusive starters and fossils, and event-only +Pokémon remain explicit blockers unless the user enables an acquisition source +that supplies them. "Complete" always names the selected goal and allowed +methods. + +### 1.1 Existing pieces and exact gaps + +| Concern | Reuse | Gap this design adds | +|---|---|---| +| Story execution | [`Pokemon_StoryCheckpoint`](../../SerialPrograms/Source/Pokemon/AutoStory/Types/Pokemon_StoryCheckpoint.h), engine, event logs and retry policy | build one checkpoint at a time from a runtime plan | +| World travel | [`ConnectedMaps`](../../SerialPrograms/Source/Pokemon/Navigation/Pokemon_ConnectedMaps.h), FRLG planner/walker, Fly, Surf and runtime maps | choose a destination and an adjacent wild-tile hunt site from data | +| Wild identity | [`WildEncounterReader`](../../SerialPrograms/Source/VideoGames/PokemonFRLG/Inference/PokemonFRLG_WildEncounterReader.h) | constrain reads to the catalog's species at that site and feed the collection ledger | +| Capture | [`CapturePlan` and `run_capture()`](../../SerialPrograms/Source/VideoGames/PokemonFRLG/Programs/AutoStory/PokemonFRLG_AutoStoryCapture.h) | selected balls, wired opponent HP, durable Pokédex verification and more encounter methods | +| New-registration screen | [`PokedexRegisteredDetector`](../../SerialPrograms/Source/VideoGames/PokemonFRLG/Inference/PokemonFRLG_PokedexRegisteredDetector.h) | read the existing Pokédex list before planning and after a catch | +| Supplies | Mart, bag row reader, heal and PC actions | calculate a ball budget and add supply steps to a generated checkpoint | +| Source data | pinned runtime maps from PokemonSimulation | a pinned acquisition catalog: encounters first, other recipe kinds later | + +The current console capture adapter deliberately cannot weaken a target: +`read_foe_hp()` returns `UNKNOWN`, even though the opponent HP reader now +exists. It also finds only `poke-ball` at the top of the Balls pocket. The +first land-wild pilot can catch full-HP, high-catch-rate species, but a general +collector must close those two gaps instead of hiding them in generous bounds. + +## 2. Shape: a controller that emits ordinary checkpoints + +The collector is goal-driven rather than a static list of 150 story rows: + +```text +read Pokédex + -> missing = goal - caught + -> classify acquisition recipes + -> choose one feasible recipe and hunt site + -> build one acquisition checkpoint + -> run it through the existing story engine + -> verify, return to an anchor and save + -> update the snapshot and repeat +``` + +Do not implement this as one `collect_dex` GAME action. Such an action would +hide routes, shopping, captures, checks and saves inside one event, bypassing +the useful per-step logs, simulator and retry boundary. + +Instead, `DexCollectionController` calls the read-only scan and pure planner, +then `DexCheckpointFactory` builds one normal `Pokemon::StoryCheckpoint`. Its +steps use the same action registry as authored FRLG rows. A typical first-slice +checkpoint is: + +```text +from_save (known Pokémon Center anchor) + -> mart, when the ball budget is not already present + -> heal + -> fly/run to the selected map + -> run to a generated land hunt site + -> capture the selected species + -> dex_entry requires caught + -> fly/run back to a known Pokémon Center anchor + -> heal + -> checkpoint save +``` + +The dynamic checkpoint id should be stable and diagnostic, for example +`dex-025-pikachu-viridian-forest`. The run record then identifies the species, +recipe, destination, budgets and event that failed. + +## 3. Two front ends, one collection routine + +### 3.1 Standalone program first + +Add `PokemonFRLG_DexCollector` under `Programs/DexCollection/` and register it +in the FRLG General panel. It owns only UI options and console setup, then calls +the reusable collector. + +First-slice setup: + +- FireRed, English; +- the game has reached the collection prerequisite selected by the program; +- a save exists at a supported Pokémon Center anchor selected in the UI; +- Fly and its named party user are available when the plan permits Fly; and +- the program loads that save before scanning. + +The required anchor selection avoids pretending that a place name on the save +card proves an arbitrary tile. The first slice may support one anchor, such as +Celadon or Indigo Plateau, before exposing a database of checked Center anchors. + +Suggested options: + +| Option | First slice | Later | +|---|---|---| +| Goal | custom species list; Kanto caught set | named goal resources | +| Allowed sources | land wild encounters | Surf, fishing, Safari, static, gift, evolution, trade | +| Version | FireRed | LeafGreen | +| Start/commit anchor | one checked Center | supported anchor database | +| Route policy | safe/default checks | speed/cost policy | +| Capture bounds | encounters and balls per target | derived reliability target and global budget | +| On blocked species | report and continue | stop/report/skip policy | + +The standalone program is the first console pilot because it can be rerun from +one postgame save without coupling development to a full story run. + +### 3.2 AutoStory integration + +The same `run_dex_collection()` routine can be called by AutoStory after the +main-story range has completed and saved at its final known anchor. Add an +option such as **Continue with Pokédex collection** only after the standalone +controller is proven. + +AutoStory supplies facts it already knows: version, completed story row, +available map flags, expected party roles, start menu, and the exact final +anchor. The collector still scans the Pokédex; it must not infer caught species +from the intended story route. + +This is not initially another static start/end checkpoint range. It is a +goal-driven continuation after the selected linear range. If shared AutoStory +later gains story tracks with goal-driven tracks, this continuation can become +a `dex` track without changing the collector. + +AutoStory must refuse the continuation when its selected end is not a declared +collection entry point. A run ending midway through the story can report what +is currently feasible, but it must not silently assume postgame capabilities. + +### 3.3 Proposed code layout and integration points + +Names are provisional, but ownership should stay separated as follows: + +```text +Inference/Menus/ + PokemonFRLG_PokedexListDetector.{h,cpp} + PokemonFRLG_PokedexListReader.{h,cpp} + +Programs/DexCollection/ + PokemonFRLG_DexCatalog.{h,cpp} resource model and parser + PokemonFRLG_DexState.{h,cpp} goal, snapshot, capabilities, report + PokemonFRLG_DexReader.{h,cpp} menu navigation and full/target reads + PokemonFRLG_DexPlanner.{h,cpp} pure classification and next plan + PokemonFRLG_DexHuntSites.{h,cpp} map-region hunt-site candidates + PokemonFRLG_DexCheckpoint.{h,cpp} ordinary StoryCheckpoint factory + PokemonFRLG_DexController.{h,cpp} scan -> plan -> checkpoint -> repeat + PokemonFRLG_DexCollector.{h,cpp} standalone descriptor/options/program + +Programs/AutoStory/ + PokemonFRLG_AutoStoryDexEntry.{h,cpp} read-only dex_entry GAME action +``` + +The action spec is registered with the other FRLG game-action specs and +dispatched by `StoryExecutor`. Its simulator adapter reads the simulated caught +set. Tests register through `PokemonFRLG_Tests.cpp`; the standalone descriptor +is added to `PokemonFRLG_Panels.cpp`; new sources/resources are added to CMake +in their owning slice. + +`build_checkpoint()` can supply the action dispatch, start check and save, but +its current `keep_next_start_frame()` looks up the next id in the static story +table. A generated row is not in that table. Extract or overload that small +piece so a dynamic checkpoint saves its post-save frame under a stable anchor +key such as `dex-anchor-celadon`. The next generated row checks that anchor key +even though its diagnostic checkpoint id names a different species. Static +story rows keep their current next-row lookup unchanged. + +For AutoStory integration, add the continuation option to `AutoStory` only in +the integration slice. After `run_story_plan()` reports the declared main-story +end, construct `DexCollectionEnvironment` from the existing `StoryEnv`, final +pose and capabilities, then call the same controller as the standalone +program. The controller does not include or call the `AutoStory` program class, +so the dependency stays one way. + +The standalone loader can reuse `StoryPreflight`, `soft_reset()`, save-card +place checks and the existing save routine, but needs its own small session +adapter: the current `story_game()` helper is private to `AutoStory.cpp`. Do not +copy that whole program shell. Extract only a reusable checked-save/session +helper if both callers need the same sequence. + +## 4. State and contracts + +### 4.1 Pokédex state + +```cpp +enum class DexRegistration{ + UNSEEN, + SEEN, + CAUGHT, + UNKNOWN, +}; + +struct DexSnapshot{ + std::map species; + DexMode mode; // Kanto or National + size_t caught_count; +}; +``` + +`UNKNOWN` is not missing. Any goal entry that cannot be read is a scan failure +or an explicit unknown result; it must never cause a blind capture trip. + +Scan the full goal at program start and after loading a save on restart. During +one uninterrupted run, a targeted check after each catch updates the in-memory +snapshot. A periodic full scan at an anchor catches drift without paying for a +150-row scan after every species. + +When the goal contains national entries but the save exposes only the Kanto +Dex, classify those entries as locked on the National Dex prerequisite. Do not +turn absent rows into `UNSEEN` or `UNKNOWN` captures. + +### 4.2 Acquisition catalog + +PokemonSimulation should generate and publish a pinned resource from +`pret/pokefirered`, rather than hand-authoring encounter facts in C++: + +```json +{ + "format": "pokesim-frlg-acquisition-catalog/1", + "source": {"repository": "pret/pokefirered", "revision": "..."}, + "versions": ["firered", "leafgreen"], + "species": [ + { + "slug": "pikachu", + "national_number": 25, + "catch_rate": 190, + "recipes": [ + { + "id": "wild-firered-viridian-forest-land", + "kind": "wild", + "version": "firered", + "map": "ViridianForest", + "method": "land", + "encounter_rate": 10, + "slots": [{"weight": 5, "min_level": 3, "max_level": 5}], + "requires": [] + } + ] + } + ] +} +``` + +Use the exact runtime-map names. Preserve raw slot weights and encounter rate; +the planner can aggregate multiple slots for the same species without losing +source information. Every recipe carries version and capability requirements. + +Later recipe kinds use the same species index: + +- `wild`: land, Surf, fishing, Rock Smash or Safari; +- `static`: an overworld interaction and battle; +- `gift` and `fossil`: a story interaction, possibly mutually exclusive; +- `evolve`: source species, method and level/item/trade requirement; +- `in_game_trade`: requested owned species and NPC interaction; and +- `external_trade` or `event`: disabled unless the user explicitly enables an + external handoff. + +The catalog says where a species can come from. It does not claim that the +current map pack can route there or that the console implements that method. + +### 4.3 Runtime capabilities + +```cpp +struct DexCapabilities{ + GameVersion version; + std::set story_flags; + std::set field_moves; + std::set key_items; + std::set supported_methods; + std::set loaded_maps; +}; +``` + +An AutoStory continuation derives this from its known completed checkpoint and +verified inventory/party checks. A standalone run starts from a named +prerequisite profile, then verifies the facts it can read. Unknown capability +state blocks dependent recipes. + +Do not use the caught Pokédex flag as proof that an evolution or trade source is +still owned. Supporting those recipes requires an owned-party/PC snapshot or a +session ledger rooted in a verified scan. + +## 5. New inference and menu routines + +### 5.1 Pokédex list inference + +Add under `Inference/Menus/`: + +1. `PokemonFRLG_PokedexListDetector`: recognizes the numerical Pokédex list + and rejects the entry/detail page and other menu screens. +2. `PokemonFRLG_PokedexListReader`: reads the list mode, visible national + numbers, cursor/scroll position, and each row's seen/caught marker. +3. `PokemonFRLG_PokedexEntryDetector`: recognizes the selected species entry + when a targeted verification needs stronger evidence than the list marker. + +The reader should identify species by national-number row, not OCR the English +name as its primary identity. Names can be derived from the pinned Pokédex +resource. It must handle caught, seen-only, unseen and unread rows separately. + +Add under `Programs/DexCollection/` or a reusable FRLG menu module: + +- `open_pokedex_list()`: from the overworld through the existing START-menu + cursor navigation, force numerical order and verify the list; +- `read_pokedex_snapshot(goal)`: traverse enough rows to cover the goal, + waiting for each stable list screen, and return to the overworld; +- `read_pokedex_entry(species)`: navigate to one national number, verify its + caught marker, and return to the overworld. + +Each press waits for the screen it needs. There are no fixed-delay page walks. + +Image tests need first/middle/last pages, list scrolling, Kanto/National mode, +caught/seen/unseen rows, an unread marker, and at least two capture-card +profiles. The full-scan control routine gets scripted-screen tests for a missed +press, a repeated page, a mode mismatch and a list that stops advancing. + +### 5.2 Existing inference to reuse + +- `SelectionArrowDetector` and `move_cursor_to_position()` already reach + POKÉDEX from the full START menu. +- `PokedexRegisteredDetector` already recognizes the new-registration screen + during a catch. The AutoStory capture loop does not currently consume it; add + it when recording registration evidence. It is immediate evidence, but the + target list row remains the durable postcondition. +- `WildEncounterReader` already returns the encountered species slug. +- `PokemonFRLG_BattleHpBarReader` already reads the opponent HP fill. The + AutoStory capture adapter currently returns `FoeHp::UNKNOWN`; wire this reader + into it instead of creating another HP detector. +- `ItemListReader` already reads bag rows. Extend ball selection through it + instead of assuming the top row is `poke-ball`. + +## 6. Planner and hunt-site selection + +The pure planner takes a goal, snapshot, catalog, capabilities, current anchor, +maps and policy. It produces either one `DexAcquisitionPlan` or a completion +report. + +```cpp +struct DexAcquisitionPlan{ + std::string species; + std::string recipe_id; + Pokemon::MapPlace hunt_site; + HuntMethod method; + CapturePlan capture; + DexAnchor commit_anchor; + DexPlanCost cost; +}; +``` + +For each missing species, recipes are classified as: + +| State | Meaning | +|---|---| +| `feasible_now` | version, capability, method and map are supported | +| `story_locked` | a badge, item, field move, area or scene is not available yet | +| `unsupported_method` | source exists, but its console action is not implemented | +| `unrouteable_map` | source exists, but the published map/connection graph cannot reach it | +| `unavailable` | wrong version, trade/event excluded, or mutually exclusive choice is gone | +| `unknown_state` | a required observed fact could not be read | + +For a land recipe, enumerate adjacent pairs of tiles in the map's `wild` +region. A valid first-slice hunt site: + +- lets the player step from one encounter tile to the other and back; +- is reachable through the loaded map graph; +- is not a warp, ledge, gate or one-way tile; +- avoids undefeated trainer sight when the story state says one remains; and +- has a route back to the commit anchor. + +The current `CapturePlan::pace` then comes from the chosen pair rather than an +authored row. + +Choose deterministically by a cost such as: + +```text +route to site + route back + + expected encounters / aggregate slot weight + + expected throws from catch rate, level, HP and selected ball + + shopping/healing cost + + policy risk penalties +``` + +The first slice can use conservative fixed encounter/ball bounds and greedy +one-target choice. Later the same contract can batch a location: choose a site +covering several missing species and catch any wanted species encountered there. +Do not start with a world-tour/TSP optimizer. + +## 7. Story actions and capture changes + +### 7.1 New read-only action + +Add one small FRLG GAME action for generated checkpoints: + +```text +dex_entry species= registration=caught +``` + +It calls the targeted Pokédex reader and returns `outcome_unchanged()` on the +required state. A missing, unread or wrong state is a distinct failed outcome. +This gives the checkpoint an explicit postcondition and lets simulation fake it. + +The full `dex_scan` is a controller routine, not a story action: its result is a +large `DexSnapshot`, which does not belong in `Outcome` flags. + +### 7.2 Keep existing actions where they fit + +Generated checkpoints reuse: + +- `run`/`bike` and the connected-map route planner; +- `fly` and `surf` field actions; +- `mart` for balls and healing items; +- `heal` and ordinary checkpoint save; +- `pc` when a later recipe requires party arrangement; and +- `capture` for the first land-wild slice. + +No separate `return_to_anchor`, `buy_balls` or `save_dex_progress` action is +needed. They are ordinary routes, Mart lines and checkpoint save policy. + +### 7.3 Extend capture in reviewable pieces + +The existing capture routine already provides encounter bounds, species reads, +non-target fleeing, shiny hard-stop, party/PC destination handling and catch +bounds. Extend it without changing today's authored capture defaults: + +1. **Ball selection:** add optional `ball=` to `CapturePlan` and the + `capture` action. The console searches the Balls pocket for that row and + selects USE. Omitted keeps today's `poke-ball` behavior. +2. **HP-aware weakening:** map `read_opponent_hp_fill()` to `FoeHp` and enable + the already-designed weakening turns. The plan still names a move and a + maximum; safe-move selection from damage ranges is a separate planner. +3. **Registration evidence:** have the catch result record whether the + registration page appeared. The generated `dex_entry` action remains the + durable check. +4. **Separate encounter finding from a target battle:** extract the current + paced-land finder from the battle/catch actions. This lets fishing, Surf and + static methods reuse species reading, shiny policy, throws and catch exit. +5. **Location batches:** after the single-target slice, allow a set of wanted + species. A non-primary missing species can be caught instead of fled from, + then the controller replans from the updated snapshot. + +Method-specific actions come later, each with its own explicit contract rather +than conditionally valid arguments on `capture`: + +- `fish_capture`: selected rod, facing-water site, hook/battle detection; +- `surf_capture`: a water pacing pair and surfing movement; +- `safari_capture`: Safari steps/balls, no ordinary weakening, and a required + exit before saving; +- `static_capture`: face/interact at a declared object, with no encounter loop; +- `gift_acquire`, `evolve` and `in_game_trade`: non-wild recipes whose effects + are still checked by `dex_entry`. + +## 8. Save, retry and restart contract + +The first reliable version starts and ends every acquisition at a known anchor. +The capture itself is not committed until the checkpoint returns there, +verifies the target and saves. + +- Failure before the save reloads the previous anchor save. If a target was + caught and the return failed, the reset loses that catch and the next attempt + catches it again; the in-memory snapshot must not claim it was committed. +- Success updates the snapshot only after the checkpoint save succeeds. +- A process crash after the save but before the update is recovered by the full + Pokédex scan on restart. +- A shiny preserves today's rule: stop in the battle without pressing anything + and do not reload. +- Safari checkpoints return outside the zone before saving, because its START + menu has no SAVE. + +Returning to an anchor costs time but fits the current save-place/start-frame +contract. Area batching and saves at generated hunt sites can come later only +with a persistent resume record and an independently verified tile pose. + +Do not add a sidecar progress file in the first slice. The game save plus a +fresh Pokédex scan is the source of truth. + +## 9. Completion and blocker report + +The collector ends when the selected goal has no feasible recipe, not when the +missing set is necessarily empty. Report every remaining species once, grouped +by classification, for example: + +```text +Kanto caught goal: 123 / 150 registered + 8 feasible, global collection budget exhausted + 6 LeafGreen/version-exclusive + 4 trade evolutions, external trades disabled + 3 supported by data but not by a console method + 6 locked by the selected story prerequisite +``` + +The on-screen status and notifications should show the current target, recipe, +map, encounter/ball budgets, completed count and blocker count. Stats should +separate wild encounters, targets seen, catches committed, balls thrown, +targets skipped and planner failures. + +## 10. Tests and console pilot + +### Catalog and parser + +- Source pin and resource hash are present. +- Every species/recipe id is unique and every map name is canonical. +- Slot levels and weights are valid; aggregate weights never exceed the source + table. +- Known FireRed/LeafGreen exclusives classify differently. +- Unknown recipe kinds or requirements fail at load. + +### Pure planner + +- Already-caught species are omitted. +- `UNKNOWN` entries are not targeted. +- Version, capability, supported-method and loaded-map filters produce the + right blocker. +- The lower total-cost recipe wins with deterministic ties. +- Hunt sites are adjacent wild tiles, reachable both ways and outside a named + active sight line. +- No feasible species produces a complete blocker report, not a loop. + +### Controller and dynamic checkpoint + +Use injected scan/planner/story-run actions: + +- scan -> catch one -> save -> replan -> complete; +- wrong species are fled and do not change the snapshot; +- a catch whose `dex_entry` check fails is not committed; +- out of balls can select a supply checkpoint or report its bound; +- a failed return reloads and repeats the uncommitted target; +- restart after a successful save recovers from the scanned Dex; +- a shiny stops without a reload; and +- the generated checkpoint passes the normal story-action lint and simulation. + +### Console pilot + +Use a custom three-species goal from one checked postgame save: + +1. one already caught species, which is skipped from the scan; +2. one supported land encounter, which is routed to, caught, verified and + saved; and +3. one version-exclusive or unsupported species, which appears in the final + blocker report. + +Then restart the program from the saved anchor and prove it does not target the +committed species again. Expand to three land species across two maps before +adding another encounter method. + +## 11. Implementation slices + +Keep the design's boundaries as separate reviewable changes: + +1. **Acquisition catalog in PokemonSimulation:** schema, pinned generator, + validation and published Packages resource; no console code. +2. **Pokédex list inference:** detectors/readers and image tests; no presses. +3. **Pokédex navigation:** full and targeted reads through injected screen + actions; no collection planner. +4. **Catalog reader and pure planner:** classification, hunt-site selection and + deterministic costs with table tests. +5. **Capture ball/HP extensions:** defaults preserve existing authored rows. +6. **Dynamic checkpoint factory and controller:** fake story runner and + simulation first. +7. **Standalone land-wild collector:** one anchor, custom goal, console pilot. +8. **AutoStory continuation:** call the proven controller from a declared final + story anchor. +9. **One acquisition method per follow-up:** fishing, Surf, Safari, static, + gifts/evolution/trades, each with its own detectors, actions and console + evidence. +10. **Optimization after correctness:** location batches, opportunistic missing + catches and additional anchors. + +The first usable result is slice 7: it reads actual caught state, chooses among +published FireRed land encounters, routes, catches, verifies, saves and moves to +the next target. It makes no claim about methods added by later slices. From ca35b266ad6f688fc87367c5d85f59ef1e264a93 Mon Sep 17 00:00:00 2001 From: dayfine Date: Sat, 14 Nov 2026 15:21:19 -0800 Subject: [PATCH 5/5] Dex collection design: fix post-credits start, step vocabulary, table lookups, save mode; add open questions --- docs/design/AutoStory-FRLG-Dex-Collection.md | 147 ++++++++++++++++--- 1 file changed, 123 insertions(+), 24 deletions(-) diff --git a/docs/design/AutoStory-FRLG-Dex-Collection.md b/docs/design/AutoStory-FRLG-Dex-Collection.md index f523d01edd..a3828fa310 100644 --- a/docs/design/AutoStory-FRLG-Dex-Collection.md +++ b/docs/design/AutoStory-FRLG-Dex-Collection.md @@ -2,7 +2,11 @@ Status: **design only**. The actions, readers, catalog and program described here are not implemented. This design is stacked on the current FRLG AutoStory -design and implementation through the Elite Four. +design and implementation through the Elite Four. Reviewed 2026-11-14 against +`frlg/stage20-league` (table, actions, capture) and `nav/shared` (failure +classes); decisions that belong to the user are marked **Open question** and +collected in section 12. This work starts after the FRLG story reaches the Hall +of Fame with verified checkpoints; it does not compete with that. ## 1. Goal and meaning of completion @@ -27,6 +31,24 @@ Pokémon remain explicit blockers unless the user enables an acquisition source that supplies them. "Complete" always names the selected goal and allowed methods. +The first goal is the **Kanto caught set** (Kanto Dex, 150 entries). The +National Dex is not a postgame given in FRLG: it needs 60 owned species plus +Celio's Ruby/Sapphire quest on the Sevii Islands, which is +[Architecture.md](AutoStory-Architecture.md) milestone 3 and out of this +design's scope. National entries in a goal are `story_locked` until then. + +### 1.0 What the story already registers + +The story rows own these acquisitions, several as shiny Gift RNG hand-offs the +user asked for: the Magikarp (04.03), the Helix Fossil (04.05; Miguel takes the +Dome), Oddish (05.09) and Pidgey (08.03) captures, Eevee (09.03/09.04), Lapras +(16.03b), and Hitmonchan (15.02/15.03, planned, not authored). The collector +never repeats them: a `gift`, `fossil` or `static` recipe whose story row has +run is `story_owned`, and the mutually exclusive counterparts (Dome Fossil and +Kabuto, Hitmonlee) are `unavailable` on a save that followed the story. Any new +gift or static that the user wants as a shiny stays a story row with its RNG +hand-off, not a collector recipe. + ### 1.1 Existing pieces and exact gaps | Concern | Reuse | Gap this design adds | @@ -72,16 +94,25 @@ checkpoint is: ```text from_save (known Pokémon Center anchor) -> mart, when the ball budget is not already present - -> heal - -> fly/run to the selected map - -> run to a generated land hunt site + -> heal_to_full (center_enter / center_exit variants) + -> field-move step, fly variant, or route steps (run / bike variants) + to the selected map + -> route to a generated land hunt site -> capture the selected species -> dex_entry requires caught - -> fly/run back to a known Pokémon Center anchor - -> heal - -> checkpoint save + -> fly / route back to a known Pokémon Center anchor + -> heal_to_full + -> save (the engine's step; the checkpoint's commit) ``` +These are the table's real words. The FRLG GAME actions registered today are +`capture`, `mart`, `pc`, `teach`, `fossil`, `grind`, `grind_check`, `level`, +`bag_check`, `check_full_hp`, `heal_to_full` and `restore_pp`; movement is the +shared `route` step with `run`/`bike` variants +(`PokemonFRLG_AutoStoryPoses.h`), Fly and Surf are field-move step variants, +and saving is the engine's `save`. There are no `run`, `fly`, `surf` or `heal` +actions, and the factory must not invent them. + The dynamic checkpoint id should be stable and diagnostic, for example `dex-025-pikachu-viridian-forest`. The run record then identifies the species, recipe, destination, budgets and event that failed. @@ -124,9 +155,16 @@ one postgame save without coupling development to a full story run. ### 3.2 AutoStory integration The same `run_dex_collection()` routine can be called by AutoStory after the -main-story range has completed and saved at its final known anchor. Add an -option such as **Continue with Pokédex collection** only after the standalone -controller is proven. +main-story range has completed. Add an option such as **Continue with Pokédex +collection** only after the standalone controller is proven. + +The story does not end at a Center. 20.05 ends in the Hall of Fame (5, 4), the +Hall of Fame saves the game itself, the credits roll, and the game next loads +in the player's bedroom in Pallet Town. The continuation therefore begins from +a declared post-credits start (bedroom, save card PALLET TOWN) and its first +generated checkpoint routes to a Center anchor (Viridian) and saves there +before any catch is attempted. The same start is the standalone program's +"after the Champion" prerequisite profile. AutoStory supplies facts it already knows: version, completed story row, available map flags, expected party roles, start menu, and the exact final @@ -172,12 +210,22 @@ is added to `PokemonFRLG_Panels.cpp`; new sources/resources are added to CMake in their owning slice. `build_checkpoint()` can supply the action dispatch, start check and save, but -its current `keep_next_start_frame()` looks up the next id in the static story -table. A generated row is not in that table. Extract or overload that small -piece so a dynamic checkpoint saves its post-save frame under a stable anchor -key such as `dex-anchor-celadon`. The next generated row checks that anchor key -even though its diagnostic checkpoint id names a different species. Static -story rows keep their current next-row lookup unchanged. +its save hook has two static-table lookups: `keep_next_start_frame()` finds the +next id's start to keep the post-save frame, and `checkpoint_end_map(id)` +(`PokemonFRLG_AutoStorySaveChecks.cpp`) finds the next row's start map for the +save-card place check. A generated row is in neither: `story_checkpoints()` is +loaded from the embedded `StoryData/frlg-.plan.json` files and +`load_frlg_story()` rejects an id outside `STORY_ORDER`. So the factory passes +an explicit end map and a stable next-start key such as `dex-anchor-celadon` +(the next generated row checks that key even though its diagnostic id names a +different species), and builds its `Pokemon::Segment` with one `CheckpointSpec` +directly rather than through `make_story_segment()`. Static story rows keep +their current lookups unchanged. + +A generated row also has no authored `StoryCheckpointMetadata.phase`, which is +what decides whether a run may save (TESTING never, VERIFICATION after 2-3 +passes, REPRODUCTION always). The collector's commit is a save, so the program +carries the save mode itself (section 8) and stamps each generated row with it. For AutoStory integration, add the continuation option to `AutoStory` only in the integration slice. After `run_story_plan()` reports the declared main-story @@ -221,7 +269,9 @@ snapshot. A periodic full scan at an anchor catches drift without paying for a When the goal contains national entries but the save exposes only the Kanto Dex, classify those entries as locked on the National Dex prerequisite. Do not -turn absent rows into `UNSEEN` or `UNKNOWN` captures. +turn absent rows into `UNSEEN` or `UNKNOWN` captures. National number to slug +comes from the existing `Pokemon/Pokedex/Pokedex-National.json` resource +(`load_pokemon_slug_json_list()`), not a new table. ### 4.2 Acquisition catalog @@ -308,8 +358,12 @@ Add under `Inference/Menus/`: when a targeted verification needs stronger evidence than the list marker. The reader should identify species by national-number row, not OCR the English -name as its primary identity. Names can be derived from the pinned Pokédex -resource. It must handle caught, seen-only, unseen and unread rows separately. +name as its primary identity. Names come from `Pokedex-National.json`. It must +handle caught, seen-only, unseen and unread rows separately. The list facts +this relies on (the caught marker is a Poké Ball beside the number, unseen rows +show dashes, numerical order is the default and the SELECT search menu may not +be available before the National Dex) are from memory of the game, not yet +checked on console: slice 2 starts by capturing the real screens. Add under `Programs/DexCollection/` or a reusable FRLG menu module: @@ -365,6 +419,7 @@ For each missing species, recipes are classified as: | State | Meaning | |---|---| | `feasible_now` | version, capability, method and map are supported | +| `story_owned` | a story row acquires it (section 1.0); never planned here | | `story_locked` | a badge, item, field move, area or scene is not available yet | | `unsupported_method` | source exists, but its console action is not implemented | | `unrouteable_map` | source exists, but the published map/connection graph cannot reach it | @@ -372,12 +427,16 @@ For each missing species, recipes are classified as: | `unknown_state` | a required observed fact could not be read | For a land recipe, enumerate adjacent pairs of tiles in the map's `wild` -region. A valid first-slice hunt site: +region (`WILD_REGION` in `PokemonFRLG_OverworldWildTiles.h`). A valid +first-slice hunt site: - lets the player step from one encounter tile to the other and back; - is reachable through the loaded map graph; - is not a warp, ledge, gate or one-way tile; -- avoids undefeated trainer sight when the story state says one remains; and +- avoids undefeated trainer sight when the story state says one remains (the + capture loop already fights a trainer who sees the player while pacing, + `PatchSteps::fight_trainer()`; after the Champion only optional trainers + remain); and - has a route back to the commit anchor. The current `CapturePlan::pace` then comes from the chosen pair rather than an @@ -419,10 +478,10 @@ large `DexSnapshot`, which does not belong in `Outcome` flags. Generated checkpoints reuse: -- `run`/`bike` and the connected-map route planner; -- `fly` and `surf` field actions; +- the `route` step (`run`/`bike` variants) and the connected-map route planner; +- the field-move step's `fly` and `surf` variants; - `mart` for balls and healing items; -- `heal` and ordinary checkpoint save; +- `heal_to_full` with the Center variants, and the engine's `save` step; - `pc` when a later recipe requires party arrangement; and - `capture` for the first land-wild slice. @@ -441,6 +500,11 @@ bounds. Extend it without changing today's authored capture defaults: 2. **HP-aware weakening:** map `read_opponent_hp_fill()` to `FoeHp` and enable the already-designed weakening turns. The plan still names a move and a maximum; safe-move selection from damage ranges is a separate planner. + **Open question:** the PokeGuy team has no move that cannot knock out a + low-level wild, so weakening means a TM (False Swipe) or a caught helper, + which is a TM/team decision for the user. Recommendation: slices 5-7 use no + weakening; they buy Great/Ultra Balls instead and let the planner's + catch-rate filter decide which species are feasible without it. 3. **Registration evidence:** have the catch result record whether the registration page appeared. The generated `dex_entry` action remains the durable check. @@ -486,6 +550,22 @@ with a persistent resume record and an independently verified tile pose. Do not add a sidecar progress file in the first slice. The game save plus a fresh Pokédex scan is the source of truth. +**Save mode.** The program has the same save modes as AutoStory: a testing run +never saves (it catches, checks `dex_entry`, then reloads, so the console pilot +proves the loop without committing), a verification run saves once after 2-3 +passes of the same target, and a reproduction run saves at every anchor. +**Open question:** FRLG has one save slot, so every collector save overwrites +the post-credits save that the 20.x retries also load. Recommendation: run the +collector only once 20.01-20.05 are verified and the user has released that +save; until then testing mode only. + +**Failure names.** Generated checkpoints report through the shared +`StoryFailureClass` list (`Pokemon_StoryFailureClasses.h`): a failed +`dex_entry` is `STATE_CHECK_FAILED`, a ball or encounter bound reached is +`OPERATION_FAILED` with the bound in the message, pacing interrupted by a wild +battle it could not flee is `WILD_BATTLES`. The planner's recipe states +(section 6) are not failure classes; they are a report, not a retry decision. + ## 9. Completion and blocker report The collector ends when the selected goal has no feasible recipe, not when the @@ -581,3 +661,22 @@ Keep the design's boundaries as separate reviewable changes: The first usable result is slice 7: it reads actual caught state, chooses among published FireRed land encounters, routes, catches, verifies, saves and moves to the next target. It makes no claim about methods added by later slices. + +## 12. Open questions for the user + +Each has a recommendation; none is decided here. + +1. **Weakening move / TM spend** (7.3): teach False Swipe or catch a helper, or + none. Recommendation: none in slices 5-7; better balls and a catch-rate + filter instead. +2. **The one save slot** (8): may the collector overwrite the post-credits + save? Recommendation: only after 20.01-20.05 are verified and released; + testing mode (no save) until then. +3. **Goal and version**: Kanto caught set on FireRed only; National Dex and + Sevii are out of scope. Recommendation: accept; LeafGreen and National Dex + are later goals, not options in slice 7. +4. **Pilot anchor**: Viridian (first Center after the credits) or Celadon + (department store, central Fly target). Recommendation: Viridian for the + first checkpoint, Celadon as the working anchor once Fly is confirmed. +5. **External trades and events**: disabled by default. Recommendation: keep + disabled; the blocker report names them.