# Phase 2: Client Engine Documentation - Context

**Gathered:** 2026-05-02
**Status:** Ready for planning

<domain>
## Phase Boundary

Read `extracted/client-5-8/` (8307 files: 854 sprites, 12 backgrounds, 198 scripts, 320 objects, 16 rooms, plus sounds/fonts/paths/datafiles/timelines) and produce three deliverables that close out CDOC-01..04:

1. `docs/extracted-engine/` — narrative documentation of every client engine feature, organized by subsystem.
2. `docs/extracted-engine/asset-catalog/` — auto-generated machine + human catalogue of every sprite/background/sound/font/room with rich metadata and cross-references.
3. `docs/extracted-engine/MATRIX.md` + `docs/adr/NNNN-client-engine.md` — feature-vs-engine matrix (Phaser 3 vs PixiJS) and locked engine ADR backed by it.

In scope:
- Hand-authored subsystem narrative + auto-generated indices/cross-refs.
- Asset catalogue auto-generated by `tools/asset-catalog` from `extracted/<src>/**/meta.json`, augmented with derived fields and semantic cross-reference tags.
- Resolution (or explicit deferral with reason) of every Action_ID in `extracted/<src>/UNKNOWN-ACTIONS.md` before docs are considered complete.
- Paper-analysis Phaser-vs-Pixi matrix; ADR locks the engine choice for Phase 6.

Out of scope (belongs in later phases):
- New TypeScript outside `tools/` (CLAUDE.md hard rule #6 — extract → document → rewrite).
- Server features, 39dll wire protocol, save formats — Phase 3.
- Asset format conversion (BMP→PNG decode, MIDI→OGG, font→WOFF2) — Phase 6/7 `tools/asset-pipeline` (AST-01..04).
- Modernized admin web UI implementation — Phase 7 (PAR-07). Phase 2 only documents the original surface as anti-port reference.
- UI/HUD client implementation — Phase 6/7.

</domain>

<decisions>
## Implementation Decisions

### Scope of Engine Surface (CDOC-01)

- **D-01:** In-game UI / HUD / menus are documented at the same depth as engine primitives. Subsystem MDs cover Main_Menu, Online_Lobby, Settings_Menu, Online_Command_Screen, inventory UI, message-board reader. Phase 6/7 client must reimplement these; the docs feed planner directly.
- **D-02:** Original admin model (`Ctrl+E` clipboard RCE, `Ctrl+Q` inspect, `,ServerCommands.txt`, `Ctrl+O Codes.txt`) is documented as **anti-port reference** in `docs/extracted-engine/admin-anti-port.md`. Each command/keybind catalogued with original behavior + `REJECTED-AS-PORTED` marker + reason. Forcing function for Phase 7 PAR-07 modernized admin UI: nothing slips through.
- **D-03:** For DnD-only objects/events, engine docs cite the canonical `.dnd.json` descriptor path. Best-effort transcompiled `.gml` may be quoted inline for reader-friendliness, prefixed with `// see descriptor for canonical truth` (consistent with Phase 1 D-09/D-10 — descriptor is canonical, GML transcompile is lossy).
- **D-04:** Each documented feature in CDOC-01 carries an explicit `mvp: yes | no` tag identifying whether it is required for the CLI-08 Phase 6 MVP gate (two players, one room, walk + chat). Phase 6 planner cherry-picks MVP slice without re-reading 320 objects.

### Asset Catalogue (CDOC-02)

- **D-05:** Build `tools/asset-catalog` as a TS Node CLI (same conventions as `tools/extract-gmd`: Node 22, strict TS, headless, CI-runnable). Reads `extracted/<src>/**/meta.json` and emits both `asset-catalog/index.json` (machine-readable) and `asset-catalog/index.md` (human-readable). Re-runnable; pure aggregator with deterministic output.
- **D-06:** Catalogue carries **all three metadata tiers**:
  1. **Aggregator tier** — every field from the extraction `meta.json` (sprites: bbox/origin/mask/frame-count/imageBytes-len; backgrounds: tile dims/transparency; sounds: type/sample-rate/length; fonts: glyph metrics/render bounds; rooms: size/speed/view config).
  2. **Derived/computed tier** — magic-byte-detected formats (BMP via `0x42 0x4D`, audio via WAV/MIDI/MP3 magic), sprite-size buckets, sound-format histograms, room object density, palette derivation if cheap.
  3. **Semantic tag tier** — cross-reference each asset to the objects/scripts/rooms that consume it (script-grep + object meta.sprite/mask references). `used_by: [object_id, script_id, room_id]` per asset. Expensive to build but build-once-run-once: **legacy source is frozen, re-extraction is very unlikely**, so drift cost is low.
  - Reason: User confirmed legacy source will see no further updates. Maximally rich catalog wins; the cross-ref tier is a one-time build that pays Phase 6/7 planner dividends.
- **D-07:** Asset catalogue preserves Phase 1 D-12 revision (Option A): sprite/background/font payloads carried as opaque BMP bytes. Catalogue records `{format: 'bmp' | 'unknown', byteLength: N}` per image asset. **No image decode in Phase 2.** AST-01 (Phase 6/7) owns BMP→PNG conversion.
- **D-08:** `extracted/<src>/UNKNOWN-ACTIONS.md` resolution is a **CDOC-01 prerequisite**. For each unmapped Action_ID: either (a) port the entry from LateralGM source into `tools/extract-gmd/data/action-ids.json` and re-run extraction, or (b) document explicitly as DEFERRED with reason in a new `docs/extracted-engine/unknown-actions-status.md` (consumed by Phase 7 PAR-01 parity scope). CDOC-02 indexes resolution status.

### Doc Structure & Depth (CDOC-01)

- **D-09:** Top-level organization of `docs/extracted-engine/` is **by engine subsystem**, one Markdown per subsystem. Subsystem list (locked):
  - `rendering.md`
  - `input.md`
  - `collision.md`
  - `animation.md`
  - `scene-room-model.md`
  - `save-load.md`
  - `audio.md`
  - `ui-and-menus.md` (covers HUD, Main_Menu, lobby, inventory, message-board reader per D-01)
  - `client-networking.md` (39dll usage from the client side — protocol details proper are Phase 3)
  - `admin-anti-port.md` (per D-02)
  - `unknown-actions-status.md` (per D-08)
  - `MATRIX.md` (per D-12)
  - `README.md` (TOC + reading-order)
  Plus the auto-generated `asset-catalog/` subtree.
- **D-10:** Reverse-engineering depth = **functional clusters with citation + key-script call-out**. Group by behavior ("movement input — see `0006-scroll.gml`, `0044-charmove.gml`"). Quote key 5-30 line snippets inline. Do NOT reverse every line of every script. Most of 198 scripts × 320 object event slots are minor variations; diminishing returns. Subsystem narrative is hand-judged interpretation.
- **D-11:** Authoring split: **hand-authored prose + auto-generated indices/cross-refs**. Subsystem narrative is hand-authored. The script roster, object roster, room manifest, and per-subsystem "scripts referenced" tables are emitted by `tools/asset-catalog` (or a sibling generator) so they don't drift from source. Pattern parallels Phase 1 D-19 (TOOLS.md is a thin wrapper that links into the wiki).

### Phaser-vs-PixiJS Decision (CDOC-03 + CDOC-04)

- **D-12:** `docs/extracted-engine/MATRIX.md` is a **paper-analysis matrix** with weighted scoring. No prototype spike unless a hard-knockout feature surfaces. Per row: CDOC-01 feature → Phaser 3 support note → PixiJS 8 support note → numeric score per engine → weighted total. Weights documented explicitly at the top of the matrix.
- **D-13:** Hard-knockout rule: if the matrix surfaces any CDOC-01 feature where Phaser 3 lacks first-class support and the workaround would be invasive (e.g. a non-standard blit pipeline, GM-style alpha-blend behavior that fights Phaser's render pipeline), the ADR flips to PixiJS. Otherwise the recommendation defaults to Phaser per `research/STACK.md`.
- **D-14:** ADR lives at `docs/adr/0001-client-engine.md` (first ADR in the project). Format: Status / Context / Decision / Consequences. Cites `MATRIX.md` directly for rationale. Locks Phase 6 stack pin.

### Tooling

- **D-15:** `tools/asset-catalog/` is a standalone Node CLI, not yet a workspace package (pnpm workspaces are introduced Phase 4 — same posture as `tools/extract-gmd` per Phase 1 D-17). Invocation: `pnpm tsx tools/asset-catalog/cli.ts <extracted-dir> <out-dir>`. Repo-level script `pnpm catalog:all` runs both client and server (server catalogue is a Phase 3 sibling).
- **D-16:** Catalogue output deterministic per Phase 1 D-15: sorted keys, 2-space JSON indent, LF, no timestamps, no absolute paths. Source enumeration order = the extracted tree's directory order (numeric-prefix sort already applied by Phase 1 emit). Re-runnable, byte-identical given the same input.

### Claude's Discretion

For the gray area NOT explicitly selected (Phaser-vs-Pixi methodology) the decisions above (D-12/D-13/D-14) reflect best judgment grounded in `research/STACK.md` and the CDOC-03/04 acceptance text. Override any of these in planning if needed.

Other discretion items inside selected areas:
- Subsystem MD file list (D-09) is locked but additions are permitted during planning if extraction surfaces a coherent subsystem not on this list.
- Functional-cluster grouping criteria (D-10) — left to the doc-writer's judgment as long as every script and every event is reachable from at least one subsystem doc via the auto-generated cross-ref index.

### Folded Todos

None — todo cross-reference returned no matches for Phase 2 scope.

</decisions>

<canonical_refs>
## Canonical References

**Downstream agents MUST read these before planning or implementing.**

### Project planning
- `.planning/PROJECT.md` — vision, constraints, key decisions, anti-decisions
- `.planning/REQUIREMENTS.md` §"Client Engine Documentation (Stage 2)" — CDOC-01..04 acceptance
- `.planning/ROADMAP.md` §"Phase 2: Client Engine Documentation" — goal + 4 success criteria
- `.planning/research/STACK.md` — Phaser 3.90 vs PixiJS 8.18 positioning, "Phaser fits GM5 paradigm" rationale
- `.planning/research/FEATURES.md` §"MVP-Critical (Stage 6 gate)" — defines what `mvp: yes` means in D-04
- `.planning/research/ARCHITECTURE.md` — three-pipeline topology, where `tools/asset-catalog` fits
- `.planning/research/SUMMARY.md` §"Phase Ordering Rationale" — extract → document → rewrite discipline (CLAUDE.md hard rule #6)
- `.planning/research/PITFALLS.md` §A4, §B1, §D1 — pitfalls Phase 2 must avoid
- `.planning/codebase/CONCERNS.md` — security/legal context for `admin-anti-port.md`
- `.planning/phases/01-extraction/01-CONTEXT.md` — D-09 (DnD descriptor canonical), D-12 (Option A opaque BMP), D-15 (determinism), D-19 (thin-wrapper authoring pattern)

### Phase 1 outputs (consumed as input)
- `extracted/client-5-8/` — primary input: 8307 files (854 sprites, 12 backgrounds, 198 scripts, 320 objects, 16 rooms, sounds/fonts/paths/datafiles/timelines/settings.json)
- `extracted/client-5-8/MANIFEST.sha256` — reproducibility manifest
- `extracted/client-5-8/UNKNOWN-ACTIONS.md` — Phase 2 prerequisite per D-08
- `extracted/client-5-8/settings.json` — game-level engine settings (room_speed, color depth, etc.)
- `tools/extract-gmd/src/types.ts` — canonical extraction shapes (`Sprite`, `Background`, `Sound`, `Font`, `Room`, `GmObject`, etc.) consumed by `tools/asset-catalog`
- `tools/extract-gmd/data/action-ids.json` — DnD Action_ID lookup table; Phase 2 may extend if D-08 path (a) is taken

### Reverse-engineering wiki (decomp/wiki/)
- `decomp/wiki/00-overview.md` — entry point
- `decomp/wiki/03-gmd-format.md` — block layout, ID conventions, errata (per Phase 1 13-bug catalogue)
- `decomp/wiki/04-dnd-serialization.md` — DnD per-node binary, Action_ID lookup, transcompile guidance (informs D-03)
- `decomp/wiki/05-gml-vm.md` — GML stack VM, perf characteristics — feeds `rendering.md` and `animation.md` notes
- `decomp/wiki/06-gml-syntax-5x.md` — 5.x-specific syntax (informs which GML idioms we must port)
- `decomp/wiki/07-gml-core-functions.md` — `collision_line`, `sprite_add_alpha`, `external_define`, `room_*` — feeds every subsystem MD
- `decomp/wiki/08-39dll-networking.md` — drives `client-networking.md`; full protocol is Phase 3
- `decomp/wiki/16-bno-bnb-notes.md` — `.bno`/`.bnu`/`.bnb` save-format strategy; client-side reads documented in `save-load.md`
- `decomp/wiki/quick-reference.md` + `glossary.md` — terminology

### External references
- LateralGM source (`github.com/IsmAvatar/LateralGM`) — Action_ID resolution for D-08; reference parser semantics
- Phaser 3.90 docs (`phaser.io`) — feature support inputs to MATRIX
- PixiJS 8.18 docs (`pixijs.io`) — feature support inputs to MATRIX

### Anti-port reference (legacy artifacts)
- `legacy/open-source-release/,ServerCommands.txt` — original admin keybind list (D-02 input)
- `legacy/servers/enlyzeam-current/Ctrl+O Codes.txt` — operator code reference (D-02 input)
- `legacy/open-source-release/BN Online Message ID's Table.xls` — wire-protocol reference (cross-link only; full reverse is Phase 3)

</canonical_refs>

<code_context>
## Existing Code Insights

### Reusable Assets

- `tools/extract-gmd/` (Phase 1) — `tools/asset-catalog` reuses the same project layout, build/test/typecheck conventions, deterministic-output discipline (D-16), and exported types from `tools/extract-gmd/src/types.ts`.
- `extracted/client-5-8/**/meta.json` — load-bearing input. Each resource carries the structured fields needed by D-06 tier 1.
- `extracted/client-5-8/UNKNOWN-ACTIONS.md` — already exists if any unmapped Action_IDs surfaced; D-08 forcing function.
- `decomp/wiki/` (17 docs) — narrative input for every subsystem MD. Phase 2 docs cross-link to wiki entries rather than duplicating engine background.
- `.planning/research/FEATURES.md` — already inventories MVP-vs-parity at the feature level; D-04 tags reference this taxonomy.

### Established Patterns

- TS-everywhere (PROJECT.md). Tools live at `tools/<tool-name>/`.
- Headless, CI-runnable, no JVM/Windows dependency on the daily-dev path (Phase 1 D-01 pattern).
- Docs live at `docs/`; planning state at `.planning/`; RE wiki at `decomp/wiki/`. Phase 2 introduces `docs/extracted-engine/` and `docs/adr/` (first ADR).
- Reproducibility-first: deterministic output, no timestamps in committed artifacts (Phase 1 D-15).
- Thin-wrapper authoring (Phase 1 D-19): docs link the wiki rather than duplicating it. Apply to subsystem MDs.

### Integration Points

- Input: `extracted/client-5-8/` (Phase 1 output).
- Outputs:
  - `docs/extracted-engine/*.md` (subsystem narrative)
  - `docs/extracted-engine/asset-catalog/index.{json,md}` (auto-generated)
  - `docs/extracted-engine/unknown-actions-status.md` (per D-08)
  - `docs/adr/0001-client-engine.md` (first ADR)
  - `tools/asset-catalog/` (new tool)
- Downstream consumers:
  - Phase 6 client rebuild — reads CDOC-01 + MATRIX + ADR for engine choice; reads `mvp: yes` features for CLI-08 slice; reads asset catalogue to plan AST-01.
  - Phase 7 full parity — reads CDOC-01 + admin-anti-port.md + unknown-actions-status.md for PAR-01 + PAR-07 closed scope.
  - Phase 3 server documentation — references `client-networking.md` for the symmetric server side of 39dll.

</code_context>

<specifics>
## Specific Ideas

- Treat the legacy source as **frozen** (user confirmation, captured in D-06 reasoning). Re-extraction is very unlikely, so up-front investment in rich semantic cross-references in the asset catalogue pays off — drift cost is low.
- The `mvp: yes | no` tag (D-04) should be machine-readable: a YAML front-matter or fenced-block header in each subsystem section, so a future tool can grep MVP-critical features without parsing prose. Format choice deferred to planning.
- `docs/extracted-engine/README.md` should function like `decomp/wiki/README.md` does — a task-keyed jump table ("I want to know how the original game handled X → read Y.md") rather than a flat TOC.
- `MATRIX.md` weights should be captured as data (not just prose) so a Phase 6 sanity-check can re-score if anything in CDOC-01 changes between Phase 2 close and Phase 6 start.
- Auto-generated index sections inside hand-authored MDs should be wrapped in delimited blocks (e.g. `<!-- AUTOGEN:scripts:start -->` … `<!-- AUTOGEN:scripts:end -->`) so the generator can refresh in place without disturbing prose. Pattern works in Phase 1 D-19 style.

</specifics>

<deferred>
## Deferred Ideas

- **Prototype spike for Phaser-vs-Pixi.** Only triggered if D-13 hard-knockout fires. Otherwise paper analysis closes CDOC-04.
- **Full per-script reverse engineering.** D-10 explicitly defers this. If Phase 6 hits an undocumented script during implementation, deepen on demand and back-port the doc.
- **`docs/asset-pipeline/`** for AST-01..04 design notes — Phase 6/7 deliverable, not Phase 2.
- **Modernized admin UI design.** Phase 7 PAR-07. Phase 2 only catalogs the original anti-port surface (D-02).
- **Server engine documentation.** Phase 3 (`docs/extracted-server/`). Phase 2 stays client-only; `client-networking.md` is the only cross-cut.
- **Round-trip doc → schema → doc generators** (e.g. parsing CDOC-01 features into a Phase 4 protocol stub). Premature; would couple Phase 2 doc format to Phase 4 code shape. Reconsider if Phase 4 planning surfaces a need.

### Reviewed Todos (not folded)

None — none surfaced.

</deferred>

---

*Phase: 02-client-engine-documentation*
*Context gathered: 2026-05-02*