Skip to content

FRLG authored plans: convert to the v2 step format - #106

Merged
dayfine merged 1 commit into
mainfrom
frlg-plans-v2
Nov 15, 2026
Merged

dayfine merged 1 commit into
mainfrom
frlg-plans-v2

Conversation

@dayfine

@dayfine dayfine commented Nov 15, 2026

Copy link
Copy Markdown
Owner

The FRLG authored plans (data/story/frlg-authored, the Parcel pilot) still used the older record, which Arduino-Source's native reader rejects. A one-off converter in tools/ (with tests) rewrote them as action plus typed args, flattened sections, and moved notes into execution.notes keyed by step id as Arduino-Source keeps them; read_authored_checkpoint and the replay binding now read FRLG plans with read_story_checkpoint against FRLG's actions in data/story/frlg-authored/frlg-actions.json. No behaviour should differ: same steps, new spelling. One thing to check: the action specs come from Arduino-Source 220a483f8 except GRIND's beat and chance, which current Arduino-Source dropped and which are taken from c35b68396; the old readers stay because BDSP's plan and the native captures still use them. Tested with the full Python suite (3.12 with jsonschema, and 3.8 under -I, where only the three CLI tests that already fail on main fail), the converter's tests, and all 36 converted checkpoints accepted with an identical read by the nav/shared C++ reader (b41b3ab7c) through the story wire driver.

The FRLG plans in data/story/frlg-authored/ and the Parcel pilot plan used the
older record (certainty/where poses, per-kind step fields, a free-text variant,
sections and notes), which Arduino-Source's native reader rejects.

- tools/frlg_plans_v2.py (with tests) converts them: the variant becomes the
  action, its words typed args (a Mart's purchases its items, a GRIND's target
  its nurse); sections flatten into events; notes move to execution.notes,
  keyed by step id or "checkpoint", as Arduino-Source's plans keep them.
- data/story/frlg-authored/frlg-actions.json declares the FRLG actions the
  plans use, from Arduino-Source's story_action_specs().
- read_authored_checkpoint reads FRLG checkpoints with read_story_checkpoint
  and those actions; the replay binding reads the Parcel plan the same way.
  BDSP's plan and the native captures keep the older reader.
- The authored-checkpoint schema points FRLG at a new v2 checkpoint schema.

@dayfine dayfine left a comment

Copy link
Copy Markdown
Owner Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Reviewed SHA: 07341fd

Verdict

APPROVED

Correctness review of the FRLG plan conversion to v2 (Python, so no C++ style pass). CI: all 8 checks are green on 07341fd (unittest 3.8 and 3.12, battle, contracts, frlg-source-reproduction, map-consumer, map-resources, item-sources).

What I checked

  • Reproducible: I re-ran tools/frlg_plans_v2.py on main's 35 frlg-authored plans and the Parcel plan. The output is byte-identical to the PR's files.
  • Faithful: I compared the old read_checkpoint read with the new read_story_checkpoint read for every plan, using my own script rather than the converter. Across 326 steps: ids and order match, and so do kind, why, skip_if, once_per_save and declared_after. The start pose matches. Every non-game step's variant became its action. Each old field (target, legs, battles, items, fight_wild, may_lose, yes, direction, with direction defaulting to north as the old reader did) is the same arg, and a GRIND's target is its nurse. The execution block is unchanged apart from notes. 0 mismatches. I also checked all 28 game_action steps by hand, word against arg: mart map/budget/floor/items, teach item/move/slot/forget, pc do/slot/box/if_present, capture, fossil, grind and grind_check including beat and chance, and cut_tree direction. All faithful.
  • Notes: 108 note lines before, 108 after. The 00.28 section notes go to each section's first step.
  • Pin: the Parcel binding sha256 matches the converted plan, since the story tests load it. replay_view turns v2 args back into the fields that FRLG spatial replay allows. Its fallback-filled args don't break the Parcel replay: there, only fight_wild=false would be new, and it is dropped. The other fallbacks (answer yes, battle may_lose, capture turns) only appear on kinds the FRLG replay doesn't bind.
  • Readers from #105: read_authored_checkpoint reads FRLG with read_story_checkpoint(..., frlg_actions()) and checks execution.notes keys against step ids. Correct.
  • Old readers are still needed: read_checkpoint is used by the BDSP path in read_authored_checkpoint, by native_export.py, by the replay_binding path for native captures (data/story/native/frlg-parcel-02.01.json), by test_json_schema's legacy-schema tests and by the checkpoint_wire CLI. spatial_replay.authored_pose correctly takes both pose spellings. Keeping them is right.
  • Locally, story tests (29) and test_json_schema pass, and the converter's 4 tests pass.

Findings

  1. Minor: 00.28's section titles are dropped, not moved. There are 7 titles, e.g. "1F west: Lenny, round Lucas's line to the ladder (20, 13)". route10_south ("Out onto Route 10 south of the tunnel") has no notes, so nothing of it survives. No executor reads them, but they are the plan's only route summaries. Suggestion: prepend each title as the first line of the first step's notes, the same way the section notes are moved (convert_plan, lines = ...).
  2. Minor: the C++ acceptance claim needs a qualifier. wire_driver.cpp takes its action specs from the case file (read_actions(file.get_array_throw("actions"))). So "every converted plan accepted" means accepted by the shared C++ reader with this repo's frlg-actions.json. The FRLG program's own table would not accept them, at any revision: at 220a483f8, beat/chance are unknown args (00.15, 00.24 grind/grind_check); at current Arduino-Source (6829d52dc dropped Mart budget/floor), the 4 Mart steps fail as well. Say this in the PR body and in the source line of frlg-actions.json.
  3. Nit: CI runs discover -s src only, so tools/test_frlg_plans_v2.py never runs in CI. That is fine for a one-off converter; just know it can rot.

Open question: follow current Arduino-Source or stay a snapshot?

Recommendation: keep it a snapshot, as the PR does.

  • These files are #314's 00.xx plans at 3dcf3e8a. Current Arduino-Source renumbered its plans (220a483f8: 01.01 to 20.01a). Its live StoryData no longer contains any of these checkpoints, so there is no current version of them to follow.
  • Removing budget/floor and beat/chance would change what the plans say. The task's bar is "same steps, new spelling".
  • Nothing in pokesim reads those args, so tracking the C++ churn gains nothing.
  • Make the snapshot explicit (finding 2): frlg-actions.json is the spec these plans were authored against, not a mirror of any one Arduino-Source revision.
  • If the sim later needs plans the current FRLG program runs, import Arduino-Source's current StoryData (already v2) as a separate fixture set. Take its action spec from that same revision, and don't edit these.

@dayfine
dayfine marked this pull request as ready for review November 15, 2026 01:03
@dayfine
dayfine merged commit e09ac0d into main Nov 15, 2026
8 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