From d449a2fe1e04d9a7ce9c2f59832b17ca035ffc2f Mon Sep 17 00:00:00 2001 From: gamer147 Date: Fri, 24 Jul 2026 09:33:55 -0400 Subject: [PATCH] Document append bootstrap sequence --- docs/asset-resolution-re.md | 22 ++++++++++++++++++++++ docs/engine-re.md | 10 ++++++++++ docs/name-resolution.md | 10 ++++++++++ docs/phase-b-framework.md | 11 +++++++++++ 4 files changed, 53 insertions(+) diff --git a/docs/asset-resolution-re.md b/docs/asset-resolution-re.md index 2296ab8..eadfbc0 100644 --- a/docs/asset-resolution-re.md +++ b/docs/asset-resolution-re.md @@ -222,6 +222,28 @@ scene-local numeric addressing mode. the earlier pointer in the native loop; no base/append name replacement occurs. Native extracts the selector with arithmetic `SAR 24`; the port rejects sign-bit selectors rather than guessing behavior for ids that would index before AGE's mount table. + + **Append bootstrap/data sequence (static content verified 2026-07-24; native launch boundary open).** + Installed `APPEND01` contains 81 records, including 39 SYS4 scripts. Record zero is + `$1$AUTORUN.BIN` (`0x01000000`), a clean 43-instruction script. Its first 22 instructions call packed + records `0x01000001..0x01000016` in exact order: append fragments for EBINIT, CNINIT, ITINIT, SKINIT, + ILINIT, AFINIT, TRINIT, MAINIT, ALINIT, CDINIT2, MPINIT, LAINIT, OBINIT, STINIT2, RTINIT, CGINIT, + SPINIT, CTINIT, CVINIT, CIINIT, VIINIT, and SCINIT. It then marks append state and installs + `$1$CCINIT.BIN` at `0x01000017`, `$1$SCJUMP.BIN` at `0x01000018`, and the packed + READY/CLOSE/ROUND and message handlers through `0x01000029` into existing dispatch globals. The + called INIT fragments populate references to the append graphics and six append scenario scripts. + + These INIT fragments are additive bytecode, not same-name catalog overlays. In particular, + `$1$EBINIT.BIN` (`0x01000001`) writes directly into the established EBINIT global arrays and adds + sparse unit-definition rows 81 and 900..905; `$1$CNINIT.BIN` adds their display names and voice-family + mappings. Mounting an AAI therefore only makes its packed records addressable. Executing its AUTORUN + is the separate operation that materializes append data and registers append control flow. + + The base/loose script corpus contains no reference to packed id `0x01000000`. The shipped game must + therefore enter the append AUTORUN outside the visible base script call graph, but the exact native + launcher and its ordering relative to SYSTEM4/INIT2 have not yet been reversed. The current port can + resolve and execute append scripts when given their packed ids, but natural SYSTEM4 boot does not yet + launch mounted AUTORUNs. Do not treat VFS-B mount completion as append gameplay/bootstrap completion. 3. **AGF decoder (VFS-C DONE).** `Age.Engine/Sys4/AgfDecoder.cs` decodes an opened AGF payload directly to a tightly packed, top-down width/height + RGBA8 surface. The MIT-licensed GARbro `ArcFormats/Eushully/ImageAGF.cs` provides a compact reference: `ACGF` (or zero) signature, type 1/2, diff --git a/docs/engine-re.md b/docs/engine-re.md index c5564de..01bc3d5 100644 --- a/docs/engine-re.md +++ b/docs/engine-re.md @@ -2172,6 +2172,16 @@ The callers pass their operands unchanged: `script_frame_load_resource@0x40e980` fetches operand 1 and immediately forwards it to that helper. Thus scene-local and raw-fallback are not native modes: ordinary resource operands are already universal packed SYS4INI/AAI ids. +**Unresolved append execution boundary (2026-07-24).** Static inspection now separates catalog mount +from append initialization. Installed selector 1 record zero is `$1$AUTORUN.BIN` at packed id +`0x01000000`; it calls the 22 append INIT fragments at `0x01000001..0x01000016`, then installs append +dispatch scripts/resources. No base or loose script contains a call to `0x01000000`, so append startup is +owned outside the visible base-script graph. The native function that chooses and launches mounted +AUTORUN records, and its exact ordering relative to SYSTEM4/INIT2, remain unnamed/unproven. A follow-up +should trace script-frame creation for packed id `0x01000000` during cold boot, then rename/comment and +save the responsible `/v2` function. Until then, “AAI mounted” must not be used as evidence that append +INIT deltas ran. + SC0010 supplies a clean corpus proof outside SC0000's base-zero coincidence. Its `set-texture 0x21` must open raw entry `0x21` (`SO013A.AGF`); adding SC0010's catalog position `0x11e` instead selects unrelated `COL0023.OGG`. Its `play-voice 0x120/0x121/0x122` operands directly select diff --git a/docs/name-resolution.md b/docs/name-resolution.md index 50ed5ca..24fae10 100644 --- a/docs/name-resolution.md +++ b/docs/name-resolution.md @@ -724,6 +724,16 @@ The v1 map labels *shapes and tables*; the next increments add *meaning*, cheape known value in-game (take damage, gain XP), watch which global moves → definitive `field@X = "HP"`. Reserve for the fields that matter; this is the last mile. +**Append semantic-coverage caveat (2026-07-24).** The current `paths.scripts()` corpus and +`extract_init.py` resolution path include DATA1 plus loose root overrides, but not selector-keyed AAI +records. Consequently generated `build/data/EBINIT.json` describes the base/loose EBINIT only. Installed +`$1$AUTORUN.BIN` calls additive append INIT fragments; `$1$EBINIT.BIN` adds unit rows 81 and 900..905 to +the same global schema, and `$1$CNINIT.BIN` supplies the companion names/voice families. A future append +semantic pass should enumerate packed scripts from the runtime catalog, preserve `(pack selector, raw +index)` provenance, extract each INIT fragment with the existing schemas, and merge base/append assignments +only after the native AUTORUN ordering is proven. The AAI format and verified internal call sequence are +canonical in `docs/asset-resolution-re.md`. + Re-run `tools/global_map.py` after each increment; `sys4load` picks up the new labels automatically (it reads `build/global-var-map.json` at load). diff --git a/docs/phase-b-framework.md b/docs/phase-b-framework.md index 18f7239..4710a85 100644 --- a/docs/phase-b-framework.md +++ b/docs/phase-b-framework.md @@ -90,6 +90,14 @@ coverage is 100% for all 23 data initializers, CALCARR, and TUNE; the remaining SYSTEM4-rooted path visible and interactive in Godot, then investigate only the gaps actually reached on that route instead of treating every static gap as a prerequisite. +**Append boot caveat (2026-07-24).** The sequence and coverage above describe only the base/loose script +graph. Mounted `APPEND01` has a separate `$1$AUTORUN.BIN` at packed id `0x01000000`; that script calls 22 +append INIT deltas and registers the append's class-change, SCJUMP, message, stage, and scenario resources. +The base corpus never references that packed id, and natural port boot currently mounts the catalog without +executing AUTORUN. Stage B2 is therefore not append-complete until native RE identifies the engine-owned +launch boundary and the port reproduces its ordering. The verified append-internal sequence and remaining +native question are canonical in `docs/asset-resolution-re.md` and `docs/engine-re.md`. + **Godot root landing (2026-07-20).** The no-argument Godot/run-godot path now starts SYSTEM4 directly and does not apply the direct-SC0000 layout/surface bootstrap or the diagnostic `--boot` prefix. A windowed run reaches and renders TITLE using SYSTEM4-owned retained state. A real-script integration test drives TITLE's @@ -316,6 +324,9 @@ 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. +- Mounted append initialization: execute each native-selected packed AUTORUN at the proven boot boundary, + preserving base-versus-append order and provenance rather than treating same-suffix INIT fragments as + filename replacements. Completion evidence: