diff --git a/docs/PROJECT-STRUCTURE.md b/docs/PROJECT-STRUCTURE.md index 4b670f1..a9615a1 100644 --- a/docs/PROJECT-STRUCTURE.md +++ b/docs/PROJECT-STRUCTURE.md @@ -67,6 +67,7 @@ S:\Game Hacking\Eushully\Himegari\ ← workspace root (three siblings) │ ├── global-memory-re.md runtime global observation RE (SHELVED; future starting point) │ ├── remake-architecture-and-roadmap.md THE direction doc (phases A–E) │ ├── phase-a-slice-plan.md the current slice (A0/A1/A2) + │ ├── phase-b-framework.md natural boot/menu/session → first-gameplay framework │ ├── platform-portability.md OS dependencies + future cross-platform readiness │ ├── vm-mapping-plan.md the phased decode plan │ ├── himegari-port-reference.md master reference + engine background diff --git a/docs/phase-b-framework.md b/docs/phase-b-framework.md new file mode 100644 index 0000000..3c38287 --- /dev/null +++ b/docs/phase-b-framework.md @@ -0,0 +1,202 @@ +# Phase B Framework — Natural Boot to First Gameplay + +Phase B broadens the proven ADV vertical slice into a naturally booted, stateful play session and then into +the first narrow gameplay loop. This document is a sequencing framework, not a task-level implementation +plan. Phase A remains active until SC0000 meets its completion criteria. + +The architectural preference is: + +``` +complete SC0000 + -> persistent session and scene coordinator + -> faithful system/data boot + -> title and New Game happy path + -> SC0000 under naturally initialized state + -> natural first-dungeon transition + -> bounded first-dungeon gameplay slice +``` + +This order makes gameplay failures attributable to gameplay rather than to missing boot state, discarded +globals, or manually inherited host state. + +## Entry criteria from Phase A + +Phase B may begin when SC0000 is a reliable presentation baseline: + +- A normal windowed playthrough is visually and audibly coherent from entry to natural exit. +- Reproducible presentation inconsistencies have been resolved or explicitly classified with evidence. +- Every SC0000-executed effectful opcode is implemented, or its lack of a host-visible effect is supported + by native/script evidence. Remaining unrelated corpus gaps do not block entry. +- The run no longer relies on unexplained timing, input, layer, or resource workarounds. +- Automated VM/host regressions and a repeatable manual playthrough form the acceptance baseline. +- SC0000's terminal global state and control-flow boundary can be captured for comparison once natural + scene chaining exists. + +The Phase A implementation/result history remains in `docs/phase-a-slice-plan.md`. + +## Principles + +1. **State correctness before systems breadth.** Dungeon logic depends on initialized unit, item, skill, + progression, configuration, and heroine state. Establish their natural producers before debugging their + consumers. +2. **Follow script control flow.** The bytecode owns game rules. Implement the effectful operations and + lifecycle services it calls; do not replace dungeon/combat logic with a parallel rules engine. +3. **One natural path first.** Boot → title → New Game → SC0000 → first dungeon is the initial spine. + Alternate menu branches and broad gameplay coverage grow from it later. +4. **Persistent session, replaceable scenes.** Globals and game/profile state survive scene changes while + script frames, retained presentation state, and scene-owned resources observe proven lifecycle rules. +5. **Demand-driven opcode work.** Investigate an unknown opcode when the chosen path executes it or evidence + connects it to a reproduced defect. +6. **Bound every slice by an observable transition.** Each stage starts from a known state and ends at a + visible screen, input boundary, scene handoff, or gameplay action. + +## Stage B0 — Ground-truth reconnaissance + +Before changing runtime architecture, record the original game's path from process start through the first +meaningful dungeon interaction. The goal is an answer key, not exhaustive reverse engineering. + +Capture: + +- Script/load order across system boot, title, New Game, SC0000, and first dungeon entry. +- Which initialization scripts run and which global banks or native/profile values they establish. +- Retained graphics/audio state that survives each boundary. +- The title selection and New Game dispatch path. +- SC0000's natural terminal decision and the corresponding next loaded script. +- The first dungeon's executed opcode/call-script families, assets, and obvious state dependencies. + +Detailed progression semantics remain canonical in `docs/scjump-progression.md`; native loader findings +belong in `docs/engine-re.md` and `docs/name-resolution.md`. + +## Stage B1 — Persistent session and scene coordinator + +Replace the single-root-scene assumption with an application-owned session that can run one script scene, +observe its terminal request, and start the next without discarding persistent state. + +Required responsibilities: + +- Own global integer/string banks and any proven external/profile state across scenes. +- Distinguish nested `call-script` frames from top-level scene replacement. +- Define scene-owned versus session-owned host state and tear each down at the correct boundary. +- Preserve intentional system-owned surfaces, configuration, and audio while releasing scene-local state. +- Expose deterministic transition evidence: outgoing scene, reason/decision, incoming scene, and state + summary suitable for tests. + +Completion evidence: a synthetic or small real sequence transitions between two top-level scripts while +preserving selected globals and correctly releasing scene-local presentation state. + +## Stage B2 — Faithful full boot + +Replace `--boot`'s diagnostic seeding and separately injected inherited surfaces with normal boot execution. +First prove the installed game's actual ordering; do not assume the current helper lists are complete. + +The boot path must cover two existing categories: + +- System/session initialization currently approximated by `INITCONFIG`, `INIT2`, and `INIT`, including + host-visible side effects that `CaptureHost` discards. +- Game-data initialization represented by the `*INIT` family used by the headless boot/session tools. + +Completion evidence: + +- A fresh application reaches the same initial title state without `--boot`, `--seed`, or manual surface + injection. +- Required globals come from executed scripts or clearly identified profile/native defaults. +- Inherited retained state has a traceable owner and lifecycle. +- A boot snapshot is reproducible for tests, but the shipped path performs the real boot rather than loading + a developer snapshot. + +This stage may reveal platform/install-selection work; track that separately in +`docs/platform-portability.md` rather than folding cross-platform export into Phase B. + +## Stage B3 — Title and New Game happy path + +Implement only enough menu behavior to choose New Game naturally and enter the story. This is primarily a +state-initialization and dispatch slice, not a mandate to complete every submenu. + +In scope: + +- Title/main-menu presentation required by the executed path. +- Keyboard/mouse selection and the menu-specific coroutine/hotspot forms actually reached. +- Configuration defaults that affect New Game or the subsequent runtime. +- New Game initialization and its transition request. +- Natural empty-save-state behavior when no saves exist. + +Deferred to bounded follow-ups unless the happy path requires them: + +- Full configuration UI and every setting. +- Load/save implementation and save-format reversal. +- Extras, galleries, replay modes, and unrelated submenus. +- Menu visual polish that does not obstruct correct selection or state production. + +Completion evidence: launching the application, selecting New Game, and reaching SC0000 with no manual +state seeds. The resulting SC0000 opening state must match the Phase A visual/audio baseline. + +## Stage B4 — Natural progression through SC0000 + +Run the completed scene inside the persistent session and honor its real terminal transition. This stage +closes the currently unidentified decision-to-scene boundary described in `docs/scjump-progression.md`. + +Completion evidence: + +- Title/New Game reaches SC0000 through actual script/native dispatch. +- SC0000 completes without the developer auto-advance harness. +- The outgoing decision, selected next script, and persistent global changes agree with the original run. +- The first dungeon scene starts without reconstructing the VM or reseeding state. + +## Stage B5 — First-dungeon vertical slice + +Do not scope “gameplay” as maps + units + items + magic + combat + AI + win/loss all at once. After B0 +identifies the first real interaction, select the smallest end-to-end loop that exercises authoritative +script state. A likely target is: + +- Load and render the first map and its initial UI. +- Populate the units required for the opening state. +- Select one unit and display its relevant state. +- Perform one legal move or scripted action. +- Resolve one combat or event interaction if the natural opening reaches one. +- End one player action/turn and return to a stable input boundary. + +The exact acceptance path must follow the installed game's first dungeon rather than forcing this example +shape. Items, skills, magic, AI, win/loss, deployment, and progression are added only as the selected path +requires them. + +Completion evidence combines original-game observation, executed-opcode/call traces, visible map/UI output, +and before/after global-state comparisons for the action. + +## Later Phase B breadth + +Once the natural spine and first gameplay loop are trustworthy, broaden in independent tracks: + +- Remaining title/configuration/load/save branches. +- Save-file format and restoration of a persistent session. +- Map navigation, camera, terrain, deployment, and turn lifecycle. +- Unit statistics, equipment, inventory, skills, magic, heroine forms, and progression. +- Combat resolution presentation, enemy turns/AI services, and win/loss transitions. +- A full chapter of ADV and the scene types encountered between gameplay segments. +- `STINIT` and other data schemas when their runtime consumers make them necessary. + +The high-level Phase B direction remains canonical in `docs/remake-architecture-and-roadmap.md`; this file +only provides the execution framework. + +## Slice record template + +When a stage becomes active, add its concrete plan/results to this document or the then-current slice plan +without pre-planning all later systems. Record: + +- Starting state and exact reproduction path. +- One observable end condition. +- Executed unknown/effectful opcode families. +- Required global/profile/host state and its producer. +- Native/original evidence to capture. +- Explicit non-goals. +- Automated regression gates and manual acceptance check. +- Result, remaining discrepancies, and the next decision gate. + +## Decision gates + +- After B0: confirm or revise the boot/title/SC0000/dungeon sequence using observed load order. +- After B2: decide whether session state is trustworthy enough to remove the diagnostic boot path from + ordinary runs. +- After B3: choose whether save/config work blocks natural SC0000 entry; otherwise defer it. +- After B4: use the actual first-dungeon trace to write the concrete B5 slice rather than guessing its + systems in advance. +- After B5: choose breadth based on the next natural blocker, not opcode coverage percentage alone. diff --git a/docs/remake-architecture-and-roadmap.md b/docs/remake-architecture-and-roadmap.md index 83d1cfd..7944fae 100644 --- a/docs/remake-architecture-and-roadmap.md +++ b/docs/remake-architecture-and-roadmap.md @@ -138,6 +138,8 @@ Forces, and thereby de-risks, every core unknown at once: - Treat the classified no-op markers as skips; validate the tentative-no-op ops via the dialogue diff. ### Phase B — Broaden coverage (playable ADV, then systems) +Execution order and decision gates are tracked in `docs/phase-b-framework.md`; Phase A completion remains +the entry condition. - Implement the remaining effectful ops; Frida sessions for the opaque ones (the shortlist in `build/opcode-coverage.md`); Unicorn for `0x215`-style computational ops. - Grow the **global-var map** (side-task 2.5: `*MES` writers → record-table readers → Frida field