1	# REBNO — Rebuild BN Online
2
3	## Current Milestone: v1.1 Map Groundwork
4
5	**Goal:** Stand up the LDtk authoring + fast-deploy + in-game minimap pipeline that unblocks porting all legacy BNO rooms and floor-tile assets.
6
7	**Target features:**
8	- Convert legacy BNO rooms + relevant assets into a single comprehensive LDtk project (decomposed by content category: non-interactive static floor tiles, animated floor tiles, tiles with metadata, interactive tiles, entities)
9	- Confirm conversions import to LDtk in an acceptable, manageable format
10	- Map publish + fast-deploy workflow (edit → push → see live)
11	- Smoke-test the workflow with a minimal layout (basic BORDERED floor tiles only)
12	- In-game minimap UI
13
14	**Editor decision (pre-locked):** LDtk — see `.planning/notes/map-editor-decision.md` for full rationale, alternatives weighed, accepted tradeoffs (~1-task custom Phaser loader, BNCentral split mitigation).
15
16	**Phase numbering:** starts at **Phase 7** (v1.0 ended at 6.8; original Phase 7 Full Parity was relegated to backlog on 2026-05-17 so the number is free).
17
18	**Carry-overs from v1.0 explicitly NOT in v1.1 unless pulled in by requirements:** Phase 06.8 anti-cheat fall trigger, SRV-08 kill -9 verification, Phase 5 HUMAN-UAT Test 5 + 6, CI restoration, D-63 audit script, trace:check placeholder sweep.
19
20	## Previous State (v1.0 MVP shipped 2026-05-17)
21
22	**v1.0 MVP is live on Fly.io staging.** Two real players (`dunsen_uat` + `rebbie_uat`) can log in over WSS, walk around a single MVP room, exchange chat messages, and disconnect/reconnect within the grace window — demonstrated end-to-end in HUMAN-UAT round 2 at commit `1f6073e`. CLI-08 (the entire-rebuild hard milestone) is **cleared**.
23
24	Stack landed as planned: monorepo with `apps/client` (Vite + Phaser 3.90 + TypeScript), `apps/server` (Node 22 + Colyseus 0.17 + Drizzle + Better-Auth + argon2id), shared `packages/protocol` + `packages/game-logic`, SQLite + Litestream → Tigris persistence, deployed on a single Fly.io machine. The original 13-phase plan compressed into 13 phases (11 executed + 2 superseded by a late trust-model pivot in 06.7).
25
26	**Significant mid-flight pivot (Phase 06.7):** player-movement authority flipped from server-authoritative to client-owns-position, eliminating the reconciler-drift bug class that had blocked Phases 06.1 → 06.3 → 06.4. CLAUDE.md Hard Rule 1 carries a narrow movement carve-out. Anti-cheat backstop (`isPositionLegal` + fall-reset) was cut from 06.7 to ship CLI-08 and is now Phase 06.8 in the next milestone.
27
28	## What This Is
29
30	REBNO is a ground-up modernization of *BN Online*, a late-1990s/early-2000s multiplayer game shipped as a GameMaker 5.3a `.gmd` project. v1.0 delivered a working two-player MVP slice (movement + chat) over a deployed authoritative server. Full feature parity with the original (asset pipeline, multi-room, full chat, character migration, modernized admin) is staged for follow-up milestones.
31
32	## Core Value
33
34	**Original BN Online players can open Chrome, log in with their migrated account, walk around, and chat with each other in real time — bug-free.** Validated end-to-end via HUMAN-UAT round 2 at `1f6073e`.
35
36	## Requirements
37
38	### Validated
39
40	#### Extraction (Phase 1, 2026-05-03)
41	- ✓ EXT-01..08 — `tools/extract-gmd` ports LateralGM `GmFileReader` semantics; 157 tests; both `BN Online Client 5-8.gmd` + `BN Online Master 5-4.gmd` parsed end-to-end; byte-identical re-extraction; 13 wire-format bugs documented against LateralGM source; opaque BMP carried forward (Option A pivot).
42
43	#### Client Engine Documentation (Phase 2, 2026-05-04)
44	- ✓ CDOC-01..04 — 11 subsystem MDs + asset catalogue + feature-vs-engine matrix (Phaser 3.90 = 286, Phaser 4.1 = 286, PixiJS 8.18 = 201); ADR 0001 locks Phaser 3.90.0.
45
46	#### Server Documentation & Schemas (Phase 3, 2026-05-05)
47	- ✓ SDOC-01..06 — 11 server subsystem MDs + 39dll opcode table + `.bno`/`.bnb`/`.bnu` field schemas (Drizzle 8-table baseline) + ADR 0002 (SQLite + Litestream) + ADR 0003 (canonical-snapshot) + locked parity checklist.
48
49	#### Server Rebuild MVP (Phase 4, 2026-05-07)
50	- ✓ SRV-01..14 — Node 22 + Colyseus 0.17, 30 Hz fixed-tick, token-bucket rate limiting, Better-Auth + argon2id, legacy-account transparent rehash on first login, signed `RoomRegistry` hot-reload, `lint-no-clipboard-rce` forcing function (SRV-12 anti-port).
51	- ~ SRV-08 partial — SIGTERM grace ✓; kill -9 mid-tick verify deferred to Phase 5 staging (Linux host).
52
53	#### Deploy (Phase 5, 2026-05-08)
54	- ✓ DEP-01..08 — Multi-stage Dockerfile, fly.staging.toml + fly.prod.toml, Litestream + Tigris (RPO sub-second), `/health`, pino + OpenObserve, RESTORE.md drilled.
55	- ⚠ DEP-04 deploy path swapped 2026-05-17 — GH Actions storage exhausted → operator-local `flyctl deploy` per `docs/deploy/LOCAL-DEPLOY.md`.
56
57	#### Client Rebuild — MVP Gate (Phase 6 + 06.1/06.2/06.5/06.6/06.7, 2026-05-17)
58	- ✓ CLI-01..09 + AST-01 — Vite + Phaser 3, login + game scenes, client-prediction + interp, chat HUD, HiDPI integer scale, content-hashed asset manifest.
59	- ✓ **CLI-08 CLEARED** at `1f6073e` (HUMAN-UAT round 2 PASS, two real players, two browser pairs).
60
61	### Active (next milestone candidates — not yet ratified)
62
63	#### Phase 06.8 — anti-cheat illegal-position fall trigger
64	- [ ] Cut from 06.7 to ship CLI-08. Server-side tick-by-tick `isPositionLegal(player.x, player.y, room.walkable_grid)` + grace-window (~250–500 ms) fall-reset to last-known-legal/respawn.
65
66	#### Stage 7 candidates (re-decompose from Full Parity backlog)
67	- [ ] AST-02 vintage-soundfont MIDI→OGG; AST-03 BMP fonts → WOFF2; AST-04 content-hashed cache-bust manifest
68	- [ ] PAR-01 full client surface; PAR-02 full server surface; PAR-03 all rooms imported + pixel-diff verification; PAR-04 full chat (ignore/block/report/profanity/channels/history); PAR-05 transactional `.bnu` character migration; PAR-06 multi-room + presence + whispers + recovery; PAR-07 modernized admin web UI; PAR-08 closed parity checklist drained
69	- [ ] Phase 5 HUMAN-UAT Test 5 (legacy `localList.txt` one-shot import) — still pending
70	- [ ] SRV-08 kill -9 mid-tick verification on Linux staging (procedure in `04-HUMAN-UAT.md` Test 1)
71	- [ ] prod environment provisioning (`rebno-prod` never created)
72	- [ ] CI restoration (GH Actions storage exhausted) OR commit to operator-local deploy permanently
73	- [ ] D-63 HARD-gate `tooling/no-inline-origin.ts` audit script (helper itself shipped; audit deferred from 06.4)
74	- [ ] `pnpm trace:check` placeholder sweep (`REQ-SRV-XX` / `REQ-X` noise in Phase 04 + 06.4 docs)
75
76	### Out of Scope
77
78	Unchanged from v1.0:
79
80	- **Mobile / native ports** — Chrome-first; PWA only.
81	- **GameMaker 5.3a engine emulation** — reimplement game logic, not GM5 runtime.
82	- **Re-running original Windows binary** — preservation belongs in `legacy/`.
83	- **Server-side behavioral anti-cheat** — only authoritative model + fall-reset (06.8); no ML detection in v1/v2.
84	- **Modding API / UGC** — no public mod surface until parity ships.
85	- **3D / VR / new gameplay** — faithful rebuild first.
86	- **Public marketing / asset rights** — legal posture deferred until functional.
87	- **Plaintext / weak password storage** — explicitly rejected per CLAUDE.md hard rule #2.
88	- **"Run clipboard as superuser" admin** — explicitly rejected per CLAUDE.md hard rule #3.
89	- **Federation / multi-server interop** — single canonical server.
90	- **Voice chat** — not core value.
91	- **Public username changes** — identity continuity for migrated accounts.
92	- **Socket.IO transport** — wrong tool; binary WS via Colyseus chosen.
93	- **Lucia auth library** — deprecated March 2025.
94	- **Postgres v1 persistence** — wrong fit for <50 CCU on single Fly machine.
95
96	## Context
97
98	- **Architecture**: pnpm monorepo. `apps/client` (Vite + Phaser 3.90 + TypeScript). `apps/server` (Node 22 + Colyseus 0.17 + Drizzle + Better-Auth + argon2id + better-sqlite3). `apps/obs` (OpenObserve sidecar Fly app). `packages/protocol` (wire types + msgpackr codec, PROTOCOL_VERSION 4). `packages/game-logic` (pure deterministic step + AABB collision + splitmix64). `packages/db` (Drizzle 8-table baseline). `tools/{extract-gmd, asset-pipeline, asset-catalog, protocol-doc, save-format-doc, room-converter, db-schema}`.
99	- **Persistence**: SQLite WAL + Litestream → Tigris S3-compatible bucket on Fly.io. RPO sub-second verified.
100	- **Deploy reality (post-2026-05-17)**: GitHub Actions storage quota exhausted; deploy is operator-local via `flyctl deploy`. `deploy-staging.yml` future-proofed but out of service. Full procedure: `docs/deploy/LOCAL-DEPLOY.md`.
101	- **Hosting**: single Fly.io machine, persistent volume mounted at `/data`. Client static assets split to `/data/client-assets/current` symlink for zero-cost client-only releases (Phase 06.5).
102	- **CCU target v1**: <50.
103	- **Source-of-truth files**: `legacy/open-source-release/BN Online Client 5-8.gmd` + `legacy/open-source-release/BN Online Master 5-4.gmd`. Older revisions in `legacy/source-archive/` + `legacy/servers/` reference-only.
104	- **Coordinate conventions pin** (D-63 from 06.4 helper): legacy GameMaker uses `(0, 0)` top-left for Navi + effects; Phaser uses `(0.5, 1)` bottom-center for Navi. Helper `phaserOriginForLegacyPlayerAttached` at `apps/client/src/render/legacy-origin.ts` is the canonical entry point for player-attached effect ports. Pinned in CLAUDE.md.
105	- **Repo stays private through next admin-UI milestone** — BNO is Capcom-derived (Mega Man Battle Network); legal/IP path deferred.
106
107	## Constraints
108
109	Unchanged from v1.0 (all validated):
110
111	- **Server**: Node 22 + TypeScript + Colyseus 0.17.42 + better-sqlite3 + Drizzle. **Validated.**
112	- **Client**: TypeScript + Vite + Phaser 3.90.0 (ADR 0001). **Validated.** Phaser 4 caveat held — nothing surfaced in v1.0 that required the Pixi fallback.
113	- **Transport**: WebSocket binary frames + msgpackr. **Validated.**
114	- **Movement trust**: client-authoritative (carve-out from Hard Rule 1; introduced 06.7). All other state (chat origin, inventory, scores, room transitions, persistence) remains server-authoritative.
115	- **Persistence**: SQLite + Litestream (ADR 0002). **Validated** at <50 CCU.
116	- **Hosting**: Fly.io single machine + `/data` persistent volume. **Validated.**
117	- **Auth**: Better-Auth + argon2id; legacy accounts rehashed transparently on first login. **Validated.**
118	- **Compatibility — runtime**: Chrome desktop only. **Validated.**
119
120	## Key Decisions
121
122	| Decision | Phase | Outcome |
123	|---|---|---|
124	| Server: Node 22 + TypeScript + Colyseus 0.17 | 3-4 | ✓ Validated — staging stable |
125	| Client: Phaser 3.90.0 (ADR 0001) | 2 | ✓ Validated — Phaser 4 caveat held |
126	| Persistence: SQLite + Litestream (ADR 0002) | 3 | ✓ Validated — RPO sub-second |
127	| Canonical snapshot resolution (ADR 0003) | 3 | ✓ Validated |
128	| Hosting: Fly.io single machine + `/data` | 5 | ✓ Validated |
129	| Transport: WebSocket binary + msgpackr | 4 | ✓ Validated |
130	| Hot-reloadable signed room registry (ADR 0004) | 4 | ✓ Validated |
131	| Persistence layer ADR 0005 / 0006 | 5 | ✓ Validated |
132	| Phaser viewport: Scale.NONE + manual integer setZoom (ADR 0008) | 06.6 | ✓ Validated |
133	| Static client asset split via `/data` symlink swap (Phase 06.5) | 06.5 | ✓ Validated — zero-cost client-only releases |
134	| **Movement trust: client-authoritative (Hard Rule 1 carve-out)** | 06.7 | ✓ Validated — eliminated reconciler-drift bug class; HUMAN-UAT PASS |
135	| Phase 7 Full Parity relegated to backlog | post-06.7 | ✓ Right call — spans many milestones |
136	| **Deploy: operator-local `flyctl deploy`** (GH Actions storage exhausted) | 06.7-09 | ⚠ Revisit — accept permanently OR restore CI in next milestone |
137	| Phase 06.8 anti-cheat fall-reset cut from 06.7 | 06.7 | ⚠ Carry forward — currently no fall-reset backstop on client-trust model |
138
139	## Evolution
140
141	This document evolves at phase transitions and milestone boundaries.
142
143	---
144	*Last updated: 2026-05-18 — v1.1 Map Groundwork milestone started.*
145

# REBNO — Rebuild BN Online

## Current Milestone: v1.1 Map Groundwork

**Goal:** Stand up the LDtk authoring + fast-deploy + in-game minimap pipeline that unblocks porting all legacy BNO rooms and floor-tile assets.

**Target features:**
- Convert legacy BNO rooms + relevant assets into a single comprehensive LDtk project (decomposed by content category: non-interactive static floor tiles, animated floor tiles, tiles with metadata, interactive tiles, entities)
- Confirm conversions import to LDtk in an acceptable, manageable format
- Map publish + fast-deploy workflow (edit → push → see live)
- Smoke-test the workflow with a minimal layout (basic BORDERED floor tiles only)
- In-game minimap UI

**Editor decision (pre-locked):** LDtk — see `.planning/notes/map-editor-decision.md` for full rationale, alternatives weighed, accepted tradeoffs (~1-task custom Phaser loader, BNCentral split mitigation).

**Phase numbering:** starts at **Phase 7** (v1.0 ended at 6.8; original Phase 7 Full Parity was relegated to backlog on 2026-05-17 so the number is free).

**Carry-overs from v1.0 explicitly NOT in v1.1 unless pulled in by requirements:** Phase 06.8 anti-cheat fall trigger, SRV-08 kill -9 verification, Phase 5 HUMAN-UAT Test 5 + 6, CI restoration, D-63 audit script, trace:check placeholder sweep.

## Previous State (v1.0 MVP shipped 2026-05-17)

**v1.0 MVP is live on Fly.io staging.** Two real players (`dunsen_uat` + `rebbie_uat`) can log in over WSS, walk around a single MVP room, exchange chat messages, and disconnect/reconnect within the grace window — demonstrated end-to-end in HUMAN-UAT round 2 at commit `1f6073e`. CLI-08 (the entire-rebuild hard milestone) is **cleared**.

Stack landed as planned: monorepo with `apps/client` (Vite + Phaser 3.90 + TypeScript), `apps/server` (Node 22 + Colyseus 0.17 + Drizzle + Better-Auth + argon2id), shared `packages/protocol` + `packages/game-logic`, SQLite + Litestream → Tigris persistence, deployed on a single Fly.io machine. The original 13-phase plan compressed into 13 phases (11 executed + 2 superseded by a late trust-model pivot in 06.7).

**Significant mid-flight pivot (Phase 06.7):** player-movement authority flipped from server-authoritative to client-owns-position, eliminating the reconciler-drift bug class that had blocked Phases 06.1 → 06.3 → 06.4. CLAUDE.md Hard Rule 1 carries a narrow movement carve-out. Anti-cheat backstop (`isPositionLegal` + fall-reset) was cut from 06.7 to ship CLI-08 and is now Phase 06.8 in the next milestone.

## What This Is

REBNO is a ground-up modernization of *BN Online*, a late-1990s/early-2000s multiplayer game shipped as a GameMaker 5.3a `.gmd` project. v1.0 delivered a working two-player MVP slice (movement + chat) over a deployed authoritative server. Full feature parity with the original (asset pipeline, multi-room, full chat, character migration, modernized admin) is staged for follow-up milestones.

## Core Value

**Original BN Online players can open Chrome, log in with their migrated account, walk around, and chat with each other in real time — bug-free.** Validated end-to-end via HUMAN-UAT round 2 at `1f6073e`.

## Requirements

### Validated

#### Extraction (Phase 1, 2026-05-03)
- ✓ EXT-01..08 — `tools/extract-gmd` ports LateralGM `GmFileReader` semantics; 157 tests; both `BN Online Client 5-8.gmd` + `BN Online Master 5-4.gmd` parsed end-to-end; byte-identical re-extraction; 13 wire-format bugs documented against LateralGM source; opaque BMP carried forward (Option A pivot).

#### Client Engine Documentation (Phase 2, 2026-05-04)
- ✓ CDOC-01..04 — 11 subsystem MDs + asset catalogue + feature-vs-engine matrix (Phaser 3.90 = 286, Phaser 4.1 = 286, PixiJS 8.18 = 201); ADR 0001 locks Phaser 3.90.0.

#### Server Documentation & Schemas (Phase 3, 2026-05-05)
- ✓ SDOC-01..06 — 11 server subsystem MDs + 39dll opcode table + `.bno`/`.bnb`/`.bnu` field schemas (Drizzle 8-table baseline) + ADR 0002 (SQLite + Litestream) + ADR 0003 (canonical-snapshot) + locked parity checklist.

#### Server Rebuild MVP (Phase 4, 2026-05-07)
- ✓ SRV-01..14 — Node 22 + Colyseus 0.17, 30 Hz fixed-tick, token-bucket rate limiting, Better-Auth + argon2id, legacy-account transparent rehash on first login, signed `RoomRegistry` hot-reload, `lint-no-clipboard-rce` forcing function (SRV-12 anti-port).
- ~ SRV-08 partial — SIGTERM grace ✓; kill -9 mid-tick verify deferred to Phase 5 staging (Linux host).

#### Deploy (Phase 5, 2026-05-08)
- ✓ DEP-01..08 — Multi-stage Dockerfile, fly.staging.toml + fly.prod.toml, Litestream + Tigris (RPO sub-second), `/health`, pino + OpenObserve, RESTORE.md drilled.
- ⚠ DEP-04 deploy path swapped 2026-05-17 — GH Actions storage exhausted → operator-local `flyctl deploy` per `docs/deploy/LOCAL-DEPLOY.md`.

#### Client Rebuild — MVP Gate (Phase 6 + 06.1/06.2/06.5/06.6/06.7, 2026-05-17)
- ✓ CLI-01..09 + AST-01 — Vite + Phaser 3, login + game scenes, client-prediction + interp, chat HUD, HiDPI integer scale, content-hashed asset manifest.
- ✓ **CLI-08 CLEARED** at `1f6073e` (HUMAN-UAT round 2 PASS, two real players, two browser pairs).

### Active (next milestone candidates — not yet ratified)

#### Phase 06.8 — anti-cheat illegal-position fall trigger
- [ ] Cut from 06.7 to ship CLI-08. Server-side tick-by-tick `isPositionLegal(player.x, player.y, room.walkable_grid)` + grace-window (~250–500 ms) fall-reset to last-known-legal/respawn.

#### Stage 7 candidates (re-decompose from Full Parity backlog)
- [ ] AST-02 vintage-soundfont MIDI→OGG; AST-03 BMP fonts → WOFF2; AST-04 content-hashed cache-bust manifest
- [ ] PAR-01 full client surface; PAR-02 full server surface; PAR-03 all rooms imported + pixel-diff verification; PAR-04 full chat (ignore/block/report/profanity/channels/history); PAR-05 transactional `.bnu` character migration; PAR-06 multi-room + presence + whispers + recovery; PAR-07 modernized admin web UI; PAR-08 closed parity checklist drained
- [ ] Phase 5 HUMAN-UAT Test 5 (legacy `localList.txt` one-shot import) — still pending
- [ ] SRV-08 kill -9 mid-tick verification on Linux staging (procedure in `04-HUMAN-UAT.md` Test 1)
- [ ] prod environment provisioning (`rebno-prod` never created)
- [ ] CI restoration (GH Actions storage exhausted) OR commit to operator-local deploy permanently
- [ ] D-63 HARD-gate `tooling/no-inline-origin.ts` audit script (helper itself shipped; audit deferred from 06.4)
- [ ] `pnpm trace:check` placeholder sweep (`REQ-SRV-XX` / `REQ-X` noise in Phase 04 + 06.4 docs)

### Out of Scope

Unchanged from v1.0:

- **Mobile / native ports** — Chrome-first; PWA only.
- **GameMaker 5.3a engine emulation** — reimplement game logic, not GM5 runtime.
- **Re-running original Windows binary** — preservation belongs in `legacy/`.
- **Server-side behavioral anti-cheat** — only authoritative model + fall-reset (06.8); no ML detection in v1/v2.
- **Modding API / UGC** — no public mod surface until parity ships.
- **3D / VR / new gameplay** — faithful rebuild first.
- **Public marketing / asset rights** — legal posture deferred until functional.
- **Plaintext / weak password storage** — explicitly rejected per CLAUDE.md hard rule #2.
- **"Run clipboard as superuser" admin** — explicitly rejected per CLAUDE.md hard rule #3.
- **Federation / multi-server interop** — single canonical server.
- **Voice chat** — not core value.
- **Public username changes** — identity continuity for migrated accounts.
- **Socket.IO transport** — wrong tool; binary WS via Colyseus chosen.
- **Lucia auth library** — deprecated March 2025.
- **Postgres v1 persistence** — wrong fit for <50 CCU on single Fly machine.

## Context

- **Architecture**: pnpm monorepo. `apps/client` (Vite + Phaser 3.90 + TypeScript). `apps/server` (Node 22 + Colyseus 0.17 + Drizzle + Better-Auth + argon2id + better-sqlite3). `apps/obs` (OpenObserve sidecar Fly app). `packages/protocol` (wire types + msgpackr codec, PROTOCOL_VERSION 4). `packages/game-logic` (pure deterministic step + AABB collision + splitmix64). `packages/db` (Drizzle 8-table baseline). `tools/{extract-gmd, asset-pipeline, asset-catalog, protocol-doc, save-format-doc, room-converter, db-schema}`.
- **Persistence**: SQLite WAL + Litestream → Tigris S3-compatible bucket on Fly.io. RPO sub-second verified.
- **Deploy reality (post-2026-05-17)**: GitHub Actions storage quota exhausted; deploy is operator-local via `flyctl deploy`. `deploy-staging.yml` future-proofed but out of service. Full procedure: `docs/deploy/LOCAL-DEPLOY.md`.
- **Hosting**: single Fly.io machine, persistent volume mounted at `/data`. Client static assets split to `/data/client-assets/current` symlink for zero-cost client-only releases (Phase 06.5).
- **CCU target v1**: <50.
- **Source-of-truth files**: `legacy/open-source-release/BN Online Client 5-8.gmd` + `legacy/open-source-release/BN Online Master 5-4.gmd`. Older revisions in `legacy/source-archive/` + `legacy/servers/` reference-only.
- **Coordinate conventions pin** (D-63 from 06.4 helper): legacy GameMaker uses `(0, 0)` top-left for Navi + effects; Phaser uses `(0.5, 1)` bottom-center for Navi. Helper `phaserOriginForLegacyPlayerAttached` at `apps/client/src/render/legacy-origin.ts` is the canonical entry point for player-attached effect ports. Pinned in CLAUDE.md.
- **Repo stays private through next admin-UI milestone** — BNO is Capcom-derived (Mega Man Battle Network); legal/IP path deferred.

## Constraints

Unchanged from v1.0 (all validated):

- **Server**: Node 22 + TypeScript + Colyseus 0.17.42 + better-sqlite3 + Drizzle. **Validated.**
- **Client**: TypeScript + Vite + Phaser 3.90.0 (ADR 0001). **Validated.** Phaser 4 caveat held — nothing surfaced in v1.0 that required the Pixi fallback.
- **Transport**: WebSocket binary frames + msgpackr. **Validated.**
- **Movement trust**: client-authoritative (carve-out from Hard Rule 1; introduced 06.7). All other state (chat origin, inventory, scores, room transitions, persistence) remains server-authoritative.
- **Persistence**: SQLite + Litestream (ADR 0002). **Validated** at <50 CCU.
- **Hosting**: Fly.io single machine + `/data` persistent volume. **Validated.**
- **Auth**: Better-Auth + argon2id; legacy accounts rehashed transparently on first login. **Validated.**
- **Compatibility — runtime**: Chrome desktop only. **Validated.**

## Key Decisions

| Decision | Phase | Outcome |
|---|---|---|
| Server: Node 22 + TypeScript + Colyseus 0.17 | 3-4 | ✓ Validated — staging stable |
| Client: Phaser 3.90.0 (ADR 0001) | 2 | ✓ Validated — Phaser 4 caveat held |
| Persistence: SQLite + Litestream (ADR 0002) | 3 | ✓ Validated — RPO sub-second |
| Canonical snapshot resolution (ADR 0003) | 3 | ✓ Validated |
| Hosting: Fly.io single machine + `/data` | 5 | ✓ Validated |
| Transport: WebSocket binary + msgpackr | 4 | ✓ Validated |
| Hot-reloadable signed room registry (ADR 0004) | 4 | ✓ Validated |
| Persistence layer ADR 0005 / 0006 | 5 | ✓ Validated |
| Phaser viewport: Scale.NONE + manual integer setZoom (ADR 0008) | 06.6 | ✓ Validated |
| Static client asset split via `/data` symlink swap (Phase 06.5) | 06.5 | ✓ Validated — zero-cost client-only releases |
| **Movement trust: client-authoritative (Hard Rule 1 carve-out)** | 06.7 | ✓ Validated — eliminated reconciler-drift bug class; HUMAN-UAT PASS |
| Phase 7 Full Parity relegated to backlog | post-06.7 | ✓ Right call — spans many milestones |
| **Deploy: operator-local `flyctl deploy`** (GH Actions storage exhausted) | 06.7-09 | ⚠ Revisit — accept permanently OR restore CI in next milestone |
| Phase 06.8 anti-cheat fall-reset cut from 06.7 | 06.7 | ⚠ Carry forward — currently no fall-reset backstop on client-trust model |

## Evolution

This document evolves at phase transitions and milestone boundaries.

---
*Last updated: 2026-05-18 — v1.1 Map Groundwork milestone started.*


1	---
2	gsd_state_version: 1.0
3	milestone: v1.1
4	milestone_name: Map Groundwork
5	status: executing
6	last_updated: "2026-05-20T09:37:06.591Z"
7	last_activity: 2026-05-20 -- Phase 07 execution started
8	progress:
9	  total_phases: 6
10	  completed_phases: 0
11	  total_plans: 8
12	  completed_plans: 0
13	  percent: 0
14	---
15
16	# State: REBNO
17
18	**Initialized:** 2026-05-01
19	**Last updated:** 2026-05-19 — v1.1 phases renumbered to flat 7..12 (matches project sequential phase_naming convention; sub-decimals were carryover from v1.0 mid-flight insertions)
20
21	## Project Reference
22
23	See: `.planning/PROJECT.md` (updated 2026-05-18 for v1.1 open)
24
25	- **Core Value:** Original BN Online players can open Chrome, log in with their migrated account, walk around, and chat with each other in real time — bug-free. **VALIDATED** at `1f6073e` (v1.0).
26	- **v1.1 Milestone Goal:** Stand up the LDtk authoring + fast-deploy + in-game minimap pipeline that unblocks porting all legacy BNO rooms and floor-tile assets.
27	- **Current Focus:** Phase 07 — workflow-smoke-convention-locks
28	- **Last shipped:** v1.0 MVP (tag `v1.0`, commit `e6b6c47` after milestone close commits).
29
30	## Current Position
31
32	Phase: 07 (workflow-smoke-convention-locks) — EXECUTING
33	Plan: 1 of 8
34	Status: Executing Phase 07
35	Last activity: 2026-05-20 -- Phase 07 execution started
36
37	## v1.1 Phase Summary (6 phases, 18 reqs)
38
39	| Phase | Goal | Reqs | Research-flagged |
40	|-------|------|------|-------------------|
41	| 7 Workflow Smoke + Convention Locks | Lock HARD-gate decisions before any `.ldtk` lands | MAP-02, MAP-15, HYG-01, HYG-02 | yes |
42	| 8 Map-Loader + Phaser LdtkLoader + TestBed_001 | Prove LDtk→Phaser load path; retire v1.0 synth room | MAP-01 | yes |
43	| 9 Room-Converter ldtk-import + Runtime Metadata | All 5 categories convert losslessly; runtime processors share schemas | MAP-03..09, MAP-16 | yes |
44	| 10 Map-Deploy Pipeline | "Edit → push → see live" via generalized client-release.sh | MAP-10, MAP-11 | no |
45	| 11 MinimapHUD | RenderTexture overlay; <0.5ms steady-state | MAP-12, MAP-13 | no |
46	| 12 First Real Imported Zone + HUMAN-UAT | Online_Lobby end-to-end; two-player UAT | MAP-14 | no |
47
48	## Open Items (carry into next milestone)
49
50	### Deferred from v1.0 (recorded in MILESTONES.md Known Gaps)
51
52	- **SRV-08 kill -9 mid-tick verification** — Linux-only manual procedure in `milestones/v1.0-phases/phases/04-server-rebuild-mvp/04-HUMAN-UAT.md` Test 1.
53	- **Phase 5 HUMAN-UAT Test 5** — legacy `localList.txt` one-shot import — ⬜ pending.
54	- **Phase 5 HUMAN-UAT Test 6** — prod environment never provisioned (`rebno-prod`).
55	- **Phase 06.8** — anti-cheat illegal-position fall trigger; cut from 06.7 to ship CLI-08. `packages/map-loader.deriveWalkable()` (built in Phase 8) will be ready for 5-line server wire-up.
56	- **CI restoration** — GH Actions storage exhausted 2026-05-17; deploy is operator-local via `flyctl deploy` per `docs/deploy/LOCAL-DEPLOY.md`. v1.1 substitutes `pnpm preflight` (Phase 7); permanent decision deferred again.
57	- **D-63 HARD-gate audit script** — `tooling/no-inline-origin.ts` — PULLED INTO v1.1 SCOPE as HYG-01 (Phase 7).
58	- **`pnpm trace:check` placeholder sweep** — `REQ-SRV-XX` / `REQ-X` illustrative placeholders in Phase 04 + 06.4 docs — PULLED INTO v1.1 SCOPE as HYG-02 (Phase 7).
59	- **`docs/LEGACY_FEATURE_REFERENCE.md`** — untracked file from v1.0 window; consumed by Phase 9 conversion work.
60
61	### Full Parity Backlog (relegated from the original v1.0 "Phase 7 Full Parity" on 2026-05-17 — distinct from the new v1.1 Phase 7 "Workflow Smoke")
62
63	11 v1 reqs preserved in `.planning/todos/pending/2026-05-17-phase-7-full-parity-backlog.md`. Re-decompose into focused phases when v1.1 lands and admin-UI / chat-parity milestones can be sequenced.
64
65	### Carried out of v1.1 scope (revisit at v1.2)
66
67	- BNCentral chunked import (full ~16-zone catalogue)
68	- HEXPORTER/WARP creationCode parsing expansion beyond v1.1 typed coverage
69	- Fog-of-war / visited-area persistence design
70	- Multi-zone overworld minimap promote to P1 (gated on Phase 11 margin)
71	- CI restoration decision
72
73	## Next Step
74
75	Run `/gsd:plan-phase 7 --research-phase` to decompose Phase 7 (Workflow Smoke + Convention Locks) into executable plans. Phases 7, 8, 9 are research-flagged at the roadmap level.
76

---
gsd_state_version: 1.0
milestone: v1.1
milestone_name: Map Groundwork
status: executing
last_updated: "2026-05-20T09:37:06.591Z"
last_activity: 2026-05-20 -- Phase 07 execution started
progress:
  total_phases: 6
  completed_phases: 0
  total_plans: 8
  completed_plans: 0
  percent: 0
---

# State: REBNO

**Initialized:** 2026-05-01
**Last updated:** 2026-05-19 — v1.1 phases renumbered to flat 7..12 (matches project sequential phase_naming convention; sub-decimals were carryover from v1.0 mid-flight insertions)

## Project Reference

See: `.planning/PROJECT.md` (updated 2026-05-18 for v1.1 open)

- **Core Value:** Original BN Online players can open Chrome, log in with their migrated account, walk around, and chat with each other in real time — bug-free. **VALIDATED** at `1f6073e` (v1.0).
- **v1.1 Milestone Goal:** Stand up the LDtk authoring + fast-deploy + in-game minimap pipeline that unblocks porting all legacy BNO rooms and floor-tile assets.
- **Current Focus:** Phase 07 — workflow-smoke-convention-locks
- **Last shipped:** v1.0 MVP (tag `v1.0`, commit `e6b6c47` after milestone close commits).

## Current Position

Phase: 07 (workflow-smoke-convention-locks) — EXECUTING
Plan: 1 of 8
Status: Executing Phase 07
Last activity: 2026-05-20 -- Phase 07 execution started

## v1.1 Phase Summary (6 phases, 18 reqs)

| Phase | Goal | Reqs | Research-flagged |
|-------|------|------|-------------------|
| 7 Workflow Smoke + Convention Locks | Lock HARD-gate decisions before any `.ldtk` lands | MAP-02, MAP-15, HYG-01, HYG-02 | yes |
| 8 Map-Loader + Phaser LdtkLoader + TestBed_001 | Prove LDtk→Phaser load path; retire v1.0 synth room | MAP-01 | yes |
| 9 Room-Converter ldtk-import + Runtime Metadata | All 5 categories convert losslessly; runtime processors share schemas | MAP-03..09, MAP-16 | yes |
| 10 Map-Deploy Pipeline | "Edit → push → see live" via generalized client-release.sh | MAP-10, MAP-11 | no |
| 11 MinimapHUD | RenderTexture overlay; <0.5ms steady-state | MAP-12, MAP-13 | no |
| 12 First Real Imported Zone + HUMAN-UAT | Online_Lobby end-to-end; two-player UAT | MAP-14 | no |

## Open Items (carry into next milestone)

### Deferred from v1.0 (recorded in MILESTONES.md Known Gaps)

- **SRV-08 kill -9 mid-tick verification** — Linux-only manual procedure in `milestones/v1.0-phases/phases/04-server-rebuild-mvp/04-HUMAN-UAT.md` Test 1.
- **Phase 5 HUMAN-UAT Test 5** — legacy `localList.txt` one-shot import — ⬜ pending.
- **Phase 5 HUMAN-UAT Test 6** — prod environment never provisioned (`rebno-prod`).
- **Phase 06.8** — anti-cheat illegal-position fall trigger; cut from 06.7 to ship CLI-08. `packages/map-loader.deriveWalkable()` (built in Phase 8) will be ready for 5-line server wire-up.
- **CI restoration** — GH Actions storage exhausted 2026-05-17; deploy is operator-local via `flyctl deploy` per `docs/deploy/LOCAL-DEPLOY.md`. v1.1 substitutes `pnpm preflight` (Phase 7); permanent decision deferred again.
- **D-63 HARD-gate audit script** — `tooling/no-inline-origin.ts` — PULLED INTO v1.1 SCOPE as HYG-01 (Phase 7).
- **`pnpm trace:check` placeholder sweep** — `REQ-SRV-XX` / `REQ-X` illustrative placeholders in Phase 04 + 06.4 docs — PULLED INTO v1.1 SCOPE as HYG-02 (Phase 7).
- **`docs/LEGACY_FEATURE_REFERENCE.md`** — untracked file from v1.0 window; consumed by Phase 9 conversion work.

### Full Parity Backlog (relegated from the original v1.0 "Phase 7 Full Parity" on 2026-05-17 — distinct from the new v1.1 Phase 7 "Workflow Smoke")

11 v1 reqs preserved in `.planning/todos/pending/2026-05-17-phase-7-full-parity-backlog.md`. Re-decompose into focused phases when v1.1 lands and admin-UI / chat-parity milestones can be sequenced.

### Carried out of v1.1 scope (revisit at v1.2)

- BNCentral chunked import (full ~16-zone catalogue)
- HEXPORTER/WARP creationCode parsing expansion beyond v1.1 typed coverage
- Fog-of-war / visited-area persistence design
- Multi-zone overworld minimap promote to P1 (gated on Phase 11 margin)
- CI restoration decision

## Next Step

Run `/gsd:plan-phase 7 --research-phase` to decompose Phase 7 (Workflow Smoke + Convention Locks) into executable plans. Phases 7, 8, 9 are research-flagged at the roadmap level.


1	# 00 — Overview & Scope
2
3	## Engine identity
4
5	- **GameMaker 5.3a**: final 5.x release before structural overhaul in 6.0.
6	- Authored by Mark Overmars (working title "Animo", late 1990s).
7	- IDE + runner written in **Delphi 5** (native Win32).
8	- IDE ~25,000 LOC (2003).
9	- Targets **Windows XP** kernels (Win95 support dropped in 5.x).
10
11	## Why 5.3a is its own problem
12
13	5.3a sits between two paradigms and doesn't match either:
14
15	- **Pre-4.0 (`.gmr`)**: standalone archives + separate runner (Java-jar style).
16	- **4.0 → 5.3a**: appended payload onto Delphi runner stub. *(this doc)*
17	- **6.0+ (`.gm6`/`.gmk`)**: heavier secondary encryption, anti-decompile.
18	- **Studio (GMS1/GMS2)**: chunk-based `data.win`/`runner.data`, FORM headers, YYC native compile.
19
20	Modern reverse-engineering tools target Studio. They cannot read 5.3a. See [13-modern-tool-incompat](13-modern-tool-incompat.md).
21
22	## Source-of-truth file
23
24	Project source = `.gmd` (GameMaker Design). Monolithic binary, sequential serialization, ZLIB-compressed asset blocks, light XOR obfuscation when appended to runner. See [03-gmd-format](03-gmd-format.md).
25
26	## Reverse-engineering goals
27
28	1. Detach appended payload from runner stub.
29	2. Bypass XOR obfuscation.
30	3. Reconstruct editable `.gmd`.
31	4. Parse `.gmd` to recover GML scripts, DnD logic, assets, room layouts.
32
33	Once GML is recovered, *project-specific* proprietary formats (e.g. `.bno`, `.bnb` for save states) become transparent — the parsing logic is in the recovered GML. See [16-bno-bnb-notes](16-bno-bnb-notes.md).
34
35	## Scope of this wiki
36
37	- Binary specs (`.gmd`, DnD nodes, runner EOF model).
38	- Era-appropriate decompiler tooling.
39	- GML 5.x syntax constraints (re-injection requires period-correct syntax).
40	- Network code (39dll only — no native sockets in 5.3a).
41	- Backup recovery via `.gb1`–`.gb9`.
42	- Ranked extraction pipeline.
43
44	Out of scope: GMS1/GMS2 internals, YYC, modern build pipelines.
45
46	## See also
47
48	- [01-runner-architecture](01-runner-architecture.md)
49	- [15-extraction-pipeline](15-extraction-pipeline.md)
50	- [glossary](glossary.md)
51

# 00 — Overview & Scope

## Engine identity

- **GameMaker 5.3a**: final 5.x release before structural overhaul in 6.0.
- Authored by Mark Overmars (working title "Animo", late 1990s).
- IDE + runner written in **Delphi 5** (native Win32).
- IDE ~25,000 LOC (2003).
- Targets **Windows XP** kernels (Win95 support dropped in 5.x).

## Why 5.3a is its own problem

5.3a sits between two paradigms and doesn't match either:

- **Pre-4.0 (`.gmr`)**: standalone archives + separate runner (Java-jar style).
- **4.0 → 5.3a**: appended payload onto Delphi runner stub. *(this doc)*
- **6.0+ (`.gm6`/`.gmk`)**: heavier secondary encryption, anti-decompile.
- **Studio (GMS1/GMS2)**: chunk-based `data.win`/`runner.data`, FORM headers, YYC native compile.

Modern reverse-engineering tools target Studio. They cannot read 5.3a. See [13-modern-tool-incompat](13-modern-tool-incompat.md).

## Source-of-truth file

Project source = `.gmd` (GameMaker Design). Monolithic binary, sequential serialization, ZLIB-compressed asset blocks, light XOR obfuscation when appended to runner. See [03-gmd-format](03-gmd-format.md).

## Reverse-engineering goals

1. Detach appended payload from runner stub.
2. Bypass XOR obfuscation.
3. Reconstruct editable `.gmd`.
4. Parse `.gmd` to recover GML scripts, DnD logic, assets, room layouts.

Once GML is recovered, *project-specific* proprietary formats (e.g. `.bno`, `.bnb` for save states) become transparent — the parsing logic is in the recovered GML. See [16-bno-bnb-notes](16-bno-bnb-notes.md).

## Scope of this wiki

- Binary specs (`.gmd`, DnD nodes, runner EOF model).
- Era-appropriate decompiler tooling.
- GML 5.x syntax constraints (re-injection requires period-correct syntax).
- Network code (39dll only — no native sockets in 5.3a).
- Backup recovery via `.gb1`–`.gb9`.
- Ranked extraction pipeline.

Out of scope: GMS1/GMS2 internals, YYC, modern build pipelines.

## See also

- [01-runner-architecture](01-runner-architecture.md)
- [15-extraction-pipeline](15-extraction-pipeline.md)
- [glossary](glossary.md)


/grill-with-docs to find a mutual understanding around the general ideas, mechanics, and features of battle network online (the legacy project) and what's making it into ReBNO


Strong grounding now. One more — the features research + legacy glossary, so I question from knowledge not ignorance.


1	# Glossary
2
3	| Term | Definition |
4	|---|---|
5	| **5.3a** | Final iterative release of GameMaker 5.x cycle. Last build before structural overhaul in 6.0. |
6	| **`.bno` / `.bnb`** | Project-specific proprietary save / data formats. No public spec — recover by reading the project's own GML. See [16-bno-bnb-notes](16-bno-bnb-notes.md). |
7	| **`.gb1` – `.gb9`** | Auto-backup files created by IDE on save. Byte-identical copies of prior `.gmd`. See [14-gb1-backups](14-gb1-backups.md). |
8	| **`.gmd`** | GameMaker Design — canonical editable source format for GM 4.x and 5.x. Monolithic binary. See [03-gmd-format](03-gmd-format.md). |
9	| **`.gmk` / `.gm6` / `.gm81`** | Successor formats (GM 6 / 7 / 8.1). Add secondary structural encryption. Out of scope for 5.3a but parseable by [LateralGM](11-tool-lateralgm.md). |
10	| **`.gmr`** | Pre-4.0 standalone archive format. Required separate runner. Replaced by appended payload model in 4.0. |
11	| **`.gmspr`** | Internal sprite serialization format used inside the `.gmd` Sprites block. ZLIB-compressed pixel data + collision matrix. |
12	| **`.gmx`** | XML-based modern GameMaker source format. LateralGM exports `.gmd` to `.gmx` for migration to GMS. |
13	| **39dll** | Third-party `39dll.dll` providing TCP/UDP sockets to 5.3a (which has zero native networking). See [08-39dll-networking](08-39dll-networking.md). |
14	| **Altar.NET** | GMS data.win unpacker. **Incompatible with 5.3a.** See [13-modern-tool-incompat](13-modern-tool-incompat.md). |
15	| **Appended payload** | Compilation model where serialized project data is XOR-obfuscated, ZLIB-compressed, and concatenated to the EOF of a Delphi runner stub. See [01-runner-architecture](01-runner-architecture.md). |
16	| **`data.win` / `runner.data`** | GMS chunk-based asset archive. Parsed via FORM magic header. Not present in 5.3a. |
17	| **Delphi 5** | Native compiler/IDE used to build the GameMaker 5.3a runner stub itself. |
18	| **DnD** | Drag-and-Drop visual scripting. Stored as binary action nodes inside Object events. See [04-dnd-serialization](04-dnd-serialization.md). |
19	| **`external_define`** | GML function binding an external DLL function into runtime scope. Sole bridge to non-VM functionality. See [07-gml-core-functions](07-gml-core-functions.md). |
20	| **FORM header** | Magic header marking start of GMS chunk archive. Hunting for this in 5.3a fails by design. |
21	| **GMD-Recovery** | VBGAMER45's VB6 dynamic-memory decompiler for 4.3–5.3a. See [09-tool-gmd-recovery](09-tool-gmd-recovery.md). |
22	| **GM Decompiler v2.1** | Java-based static decompiler covering 5.3a–7.0. See [10-tool-gm-decompiler-v21](10-tool-gm-decompiler-v21.md). |
23	| **GmkSplitter** | Tool that disassembles `.gmk`/`.gm81` into VCS-friendly tree. Pattern applicable to `.gmd`. See [12-tool-gmksplitter](12-tool-gmksplitter.md). |
24	| **GML** | GameMaker Language. Custom scripting language interpreted by the runner's stack VM. See [05-gml-vm](05-gml-vm.md). |
25	| **LateralGM** | Open-source Java IDE / parser for legacy GameMaker formats. See [11-tool-lateralgm](11-tool-lateralgm.md). |
26	| **`LibReader.java`** | Canonical `.gmd` parser inside LateralGM. Reference implementation. |
27	| **Runner / runner stub** | Pre-compiled Delphi 5 `.exe` to which the `.gmd` payload is appended at export. |
28	| **Runner-as-oracle** | The flaw that the runner must decrypt its own payload at runtime, exposing key + plaintext in RAM. See [02-encryption](02-encryption.md). |
29	| **UndertaleModTool (UTMT)** | GMS reverse-engineering tool. **Incompatible with 5.3a.** See [13-modern-tool-incompat](13-modern-tool-incompat.md). |
30	| **YYC** | YoYo Compiler. Modern GameMaker option that transcompiles GML → C++ → native binary. Not present in 5.3a (interpreter-only). |
31	| **ZLIB** | Compression algorithm used for asset blocks (sprites, backgrounds) inside `.gmd` and for the appended payload. |
32
33	## See also
34
35	- [README](README.md) — full file index + task router
36	- [quick-reference](quick-reference.md)
37

# Glossary

| Term | Definition |
|---|---|
| **5.3a** | Final iterative release of GameMaker 5.x cycle. Last build before structural overhaul in 6.0. |
| **`.bno` / `.bnb`** | Project-specific proprietary save / data formats. No public spec — recover by reading the project's own GML. See [16-bno-bnb-notes](16-bno-bnb-notes.md). |
| **`.gb1` – `.gb9`** | Auto-backup files created by IDE on save. Byte-identical copies of prior `.gmd`. See [14-gb1-backups](14-gb1-backups.md). |
| **`.gmd`** | GameMaker Design — canonical editable source format for GM 4.x and 5.x. Monolithic binary. See [03-gmd-format](03-gmd-format.md). |
| **`.gmk` / `.gm6` / `.gm81`** | Successor formats (GM 6 / 7 / 8.1). Add secondary structural encryption. Out of scope for 5.3a but parseable by [LateralGM](11-tool-lateralgm.md). |
| **`.gmr`** | Pre-4.0 standalone archive format. Required separate runner. Replaced by appended payload model in 4.0. |
| **`.gmspr`** | Internal sprite serialization format used inside the `.gmd` Sprites block. ZLIB-compressed pixel data + collision matrix. |
| **`.gmx`** | XML-based modern GameMaker source format. LateralGM exports `.gmd` to `.gmx` for migration to GMS. |
| **39dll** | Third-party `39dll.dll` providing TCP/UDP sockets to 5.3a (which has zero native networking). See [08-39dll-networking](08-39dll-networking.md). |
| **Altar.NET** | GMS data.win unpacker. **Incompatible with 5.3a.** See [13-modern-tool-incompat](13-modern-tool-incompat.md). |
| **Appended payload** | Compilation model where serialized project data is XOR-obfuscated, ZLIB-compressed, and concatenated to the EOF of a Delphi runner stub. See [01-runner-architecture](01-runner-architecture.md). |
| **`data.win` / `runner.data`** | GMS chunk-based asset archive. Parsed via FORM magic header. Not present in 5.3a. |
| **Delphi 5** | Native compiler/IDE used to build the GameMaker 5.3a runner stub itself. |
| **DnD** | Drag-and-Drop visual scripting. Stored as binary action nodes inside Object events. See [04-dnd-serialization](04-dnd-serialization.md). |
| **`external_define`** | GML function binding an external DLL function into runtime scope. Sole bridge to non-VM functionality. See [07-gml-core-functions](07-gml-core-functions.md). |
| **FORM header** | Magic header marking start of GMS chunk archive. Hunting for this in 5.3a fails by design. |
| **GMD-Recovery** | VBGAMER45's VB6 dynamic-memory decompiler for 4.3–5.3a. See [09-tool-gmd-recovery](09-tool-gmd-recovery.md). |
| **GM Decompiler v2.1** | Java-based static decompiler covering 5.3a–7.0. See [10-tool-gm-decompiler-v21](10-tool-gm-decompiler-v21.md). |
| **GmkSplitter** | Tool that disassembles `.gmk`/`.gm81` into VCS-friendly tree. Pattern applicable to `.gmd`. See [12-tool-gmksplitter](12-tool-gmksplitter.md). |
| **GML** | GameMaker Language. Custom scripting language interpreted by the runner's stack VM. See [05-gml-vm](05-gml-vm.md). |
| **LateralGM** | Open-source Java IDE / parser for legacy GameMaker formats. See [11-tool-lateralgm](11-tool-lateralgm.md). |
| **`LibReader.java`** | Canonical `.gmd` parser inside LateralGM. Reference implementation. |
| **Runner / runner stub** | Pre-compiled Delphi 5 `.exe` to which the `.gmd` payload is appended at export. |
| **Runner-as-oracle** | The flaw that the runner must decrypt its own payload at runtime, exposing key + plaintext in RAM. See [02-encryption](02-encryption.md). |
| **UndertaleModTool (UTMT)** | GMS reverse-engineering tool. **Incompatible with 5.3a.** See [13-modern-tool-incompat](13-modern-tool-incompat.md). |
| **YYC** | YoYo Compiler. Modern GameMaker option that transcompiles GML → C++ → native binary. Not present in 5.3a (interpreter-only). |
| **ZLIB** | Compression algorithm used for asset blocks (sprites, backgrounds) inside `.gmd` and for the appended payload. |

## See also

- [README](README.md) — full file index + task router
- [quick-reference](quick-reference.md)