Skip to content

Design: FRLG AutoStory goal-driven Pokedex collection - #489

Merged
dayfine merged 2 commits into
frlg/design-2026-11-12from
design/frlg-dex-collection
Nov 14, 2026
Merged

dayfine merged 2 commits into
frlg/design-2026-11-12from
design/frlg-dex-collection

Conversation

@dayfine

@dayfine dayfine commented Nov 14, 2026

Copy link
Copy Markdown
Owner

Stacked on fork PR #435 (frlg/design-2026-11-12). The diff contains only this new design document.

Problem

FRLG AutoStory can run authored captures, routes, shops, field moves and checkpoint retries, but it cannot read the save's caught Pokédex state, choose an obtainable missing species and location, or repeat that process durably.

Design

Specify a goal-driven collection controller that scans the Pokédex, plans from a pinned acquisition catalog and the runtime maps, emits one ordinary AutoStory checkpoint per target, verifies the caught entry, returns to a known anchor, saves, and replans.

The document names the proposed readers, detectors, routines and code layout; separates a standalone pilot from later AutoStory continuation; records capture extensions and method-specific actions; and defines blocker reporting, retry semantics, tests and implementation slices. It also calls out existing pieces to reuse and current gaps such as ball selection, dynamic start-frame keys and the unwired opponent HP reader.

Validation

  • git diff --check passes.
  • Documentation only; no build or console run performed.
  • The pre-push code-health hook reported 166 existing stacked-branch findings relative to main; this change adds no C++.

@dayfine

dayfine commented Nov 14, 2026

Copy link
Copy Markdown
Owner Author

Review of 7fa5530 against frlg/stage20-league (FRLG table and actions), nav/shared (failure classes) and the agents-branch FRLG notes. The direction is right: a controller that emits ordinary checkpoints, a pure planner, a pinned catalog and a standalone pilot before AutoStory integration. The citations in section 1.1 and 5.2 all resolve (read_foe_hp() returns UNKNOWN, open_ball_pocket() accepts only a top row of poke-ball, CapturePlan already carries weaken_move/max_weaken_turns, PokedexRegisteredDetector is unused by the capture loop). Findings, most important first:

  1. The post-story anchor is wrong. 20.05 ends in the Hall of Fame (5, 4); the Hall of Fame saves the game itself and the credits follow, so the game next loads in the player's bedroom in Pallet Town, not at "its final known anchor" (a Center). The AutoStory continuation has to start from a declared post-credits start (Pallet Town bedroom) and its first generated checkpoint must reach a Center anchor before anything is committed. Also the National Dex is not a postgame given: it needs 60 owned species plus Celio's Ruby/Sapphire quest on the Sevii Islands (Architecture.md milestone 3), so the first goal is the Kanto caught set only.

  2. The step vocabulary does not match the FRLG table. There are no run, bike, fly, surf or heal GAME actions. Movement is the shared route step with run/bike variants (PokemonFRLG_AutoStoryPoses.h); Fly and Surf are field-move step variants (FLY_VARIANT, SURF_VARIANT); healing is heal_to_full plus the center_enter/center_exit variants; saving is the engine's save. Registered FRLG GAME actions today: capture, mart, pc, teach, fossil, grind, grind_check, level, bag_check, check_full_hp, heal_to_full, restore_pp. The checkpoint sketch in section 2 and the list in 7.2 are written in the wrong words.

  3. A second static-table dependency. Besides keep_next_start_frame(), the save hook in build_checkpoint() calls checkpoint_end_map(id) (PokemonFRLG_AutoStorySaveChecks.cpp), which looks up the next row's start map for the save-card place check. And story_checkpoints() is loaded from the embedded StoryData/frlg-<id>.plan.json files; load_frlg_story() rejects any id outside STORY_ORDER, so a generated row can never go through the table or make_story_segment(). The factory needs an explicit end map and next-start key, and must build its Pokemon::Segment with one CheckpointSpec directly.

  4. Save policy and the one save slot are not addressed. StoryCheckpointMetadata.phase decides whether a run may save (TESTING never; VERIFICATION after 2-3 passes; REPRODUCTION always), and a generated row has no authored phase. The collector's commit is a save, so the design has to say which program-level save mode applies and that the pilot runs without saving first. FRLG has one save slot: every collector save overwrites the post-credits save, which is also what the 20.x retries load. That needs the user's call (my recommendation is in the doc).

  5. Story-owned acquisitions and user rules. The story already registers Magikarp (04.03), the Helix Fossil (04.05), Oddish (05.09), Pidgey (08.03), Eevee (09.03/09.04), Lapras (16.03b) and plans Hitmonchan (15.02/15.03, not authored yet) as shiny RNG gifts or captures. The catalog's gift/fossil recipes for these must be classified as story-owned (never re-run by the collector) and their mutually exclusive counterparts (Dome Fossil/Kabuto, Hitmonlee) as unavailable on a save that followed the story. HP-aware weakening needs a move that cannot KO a low-level wild; the PokeGuy team has none, so it means a TM (False Swipe) or a caught helper, which is a TM/team decision for the user, not a design default. The first slice should use no weakening and better balls instead.

Smaller points: map failures to the shared StoryFailureClass list (STATE_CHECK_FAILED for a failed dex_entry, WILD_BATTLES, OPERATION_FAILED) instead of new names; Pokemon/Pokedex/Pokedex-National.json already maps national numbers to slugs; WILD_REGION = "wild" already exists in PokemonFRLG_OverworldWildTiles.h; PatchSteps::fight_trainer() already fights a trainer who sees the player while pacing; the Pokédex list facts (caught marker, SELECT search menu availability) are unverified on console and should be marked so.

I am pushing a revision of the doc that fixes these and collects the user decisions in an "Open questions" section, then merging per the brief.

@dayfine
dayfine marked this pull request as ready for review November 14, 2026 23:22
@dayfine
dayfine merged commit f0ee979 into frlg/design-2026-11-12 Nov 14, 2026
14 of 16 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant