TeslaRel410/dpl3-revive/spec/VELOCIRENDER_PROTOCOL.md

# VelociRender wire protocol (Path A — run the original binary unmodified)

Reverse-engineered from the original DIVISION source on the archive drive
(`sda4/DPL3/`), **not** from disassembly — both ends of the link are present in C:

| Role | File | What it is |
|------|------|-----------|
| Host framing | `sda4/DPL3/VR_COMMS.C` / `VR_COMMS.H` | length-prefixed messaging, byte-sex, boot |
| Host link driver | `sda4/DPL3/LINKIO.C` / `LINKIO.H` | INMOS C012 link-adapter port I/O |
| Host command builder | `sda4/DPL3/DPL_HOST.C` | turns DPL nodes into `vr_action` messages |
| Protocol enum | `sda4/DPL3/VR_PROT.H` | the 24 `vr_action` command tags |
| **Board reference impl** | `sda4/DPL3/VRENDER/VR_REMOT.C` | the i860 message loop we are replacing |
| Board raster/texture | `sda4/DPL3/VRENDER/DNC.C`, `PAZPL5.C` | PixelPlanes-5 backend |

Author throughout: Phil Atkin (PJA), DIVISION Ltd, 1994. Node struct layouts are in
`source-ref/DPLTYPES.H` (already used by the `dpl3-revive` parsers).

**Goal of Path A:** stand up a *virtual VelociRender board* that speaks this protocol,
so `FLYK.EXE` (and the other HPDAVE/DPL3 binaries) run **unmodified** under DOSBox-X.
The board's rendering guts are the pipeline `dpl3-revive` already built.

---

## 1. Transport — the link adapter (what DOSBox-X must emulate)

The host talks to the board through an **INMOS C012 link adapter, IMS-B004 register
layout**, at I/O base `0x150` (default from `getXputer()` / `TRANSPUTER` env var).
`LINKIO.C` `setLA()` fixes the map:

| Port | Register | Access | Semantics |
|------|----------|--------|-----------|
| `0x150` | Input Data | R | next received byte |
| `0x151` | Output Data | W | byte to transmit |
| `0x152` | Input Status | R | **bit0 = 1** → a byte is available to read |
| `0x153` | Output Status | R | **bit0 = 1** → ready to accept a byte |
| `0x160` | Reset / fifo-ok | W / R | reset (write); `fifo_ok_status` reads bit0 |
| `0x161` | Analyse | W | transputer analyse strobe |

Byte primitives (`LINKIO.C`):

- **out byte:** spin until `Output Status bit0`, then write `Output Data`.
- **in byte:** spin until `Input Status bit0`, then read `Input Data`.
- `altRecord()` / `inputReady()` = read `Input Status bit0` (non-blocking poll).
- `reset()` = analyse=0, reset=0, delay, reset=1, delay, clear both status, reset=0.

**Emulation contract for the DOSBox-X device:**
- Output Status bit0 → always ready (we consume host bytes into a message assembler).
- Input Status bit0 → set whenever we have reply bytes queued; host drains via Input Data.
- On `reset` strobe, clear both directions and re-arm the boot handshake.

That is the *entire* hardware surface: six ports, no DMA, no IRQ used by the polled
DOS path. No i860, no transputer, no PixelPlanes silicon is emulated.

---

## 2. Envelope — framing on the wire

Every message, both directions (`velocirender_transmit` / `receive_protocol`), is:

```
+----------------+----------------+---------------------------+
| length_word:4  |   action:4     |   payload : N bytes       |
+----------------+----------------+---------------------------+
        LE               LE            (little-endian structs)
```

- `length_word = flags | (id << 16) | count`, little-endian.
  - **bit31 set** → *iserver* control message (C-runtime service; see §4). **clear** → render command.
  - **bit30 (`0x40000000`)** → set on **every** length word by the shipped Aug-1995 HPDAVE
    build (`FLYK.EXE`), on both vr_net and iserver messages (iserver ⇒ `0xC0000000`). It is
    **absent from the 1994 `VR_COMMS.C` source** — a shipped-vs-snapshot delta found by
    static analysis (`patha/verify_framing.py`: `or ebp,0x40000000` in the transmit path,
    plus a global initialized `mov [..],0x40000000`). Exact receive-side meaning is still
    TBD (routing/epoch flag?); confirm in the dynamic capture. **We mirror it** on replies
    (`vrboard.LW_FLAG`) so our board is byte-identical to the real one; our decoder ignores
    it (masks low-16 for count, tests bit31 for iserver).
  - bits 16–23 = node id; `0xff` = broadcast (host→board render commands always use `0xff`).
  - low 16 bits (`count`) = number of bytes that **follow the length word** = `4 (action) + N`.
    Max 1024; the host caps payloads and fragments (see `velocirender_packetize`, 508-byte chunks).
- `action` = a `vr_action` enum value (§3), int32 LE.
- `payload` = command-specific bytes (§3). Multi-byte fields are LE on the wire;
  the `dpl_little_endian` path sends host memory verbatim (`endian_fix` only matters
  on big-endian hosts, which we are not).

**Reply envelope is identical.** The board handler returns `ret` bytes; `reply()`
re-frames them with the **echoed action** as the first int32. The host
(`velocirender_receive`) reads `action`, then `count-4` payload bytes, and matches
the action to know the reply is for the command it sent.

Synchronous vs. async:
- Most commands that expect data back (`create`, `delete`, `set_geom_verts`,
  `set_texmap_texels`, `init`) do **transmit → receive** and block for the reply.
- `draw_scene` is **async**: the board replies with a bare `vr_draw_scene_action`
  frame-ack later; the host tracks `dpl_frame_replied` and picks it up in
  `velocirender_frameack` / `wait_draw_scene_complete`.

---

## 3. Command set (`vr_action`, VR_PROT.H) and payloads

Enum ordinals are positional (0-based, in declaration order). Payload columns are the
bytes **after** the 4-byte action. "Reply" is what the board sends back (0 = none).

| # | action | payload (host→board) | reply | source |
|--:|--------|----------------------|-------|--------|
| 0 | `vr_init` | init arg string (leftover `DPLARG` opts joined by `\|`, NUL-term) | `int32 = 1` | DPL_HOST.C `ghost_dpl_init` |
| 1 | `vr_create` | `int32 type_check` | `int32 remote` (board handle) | `velocirender_create` |
| 2 | `vr_delete` | `int32 remote, int32 type` | echo | `velocirender_delete` |
| 3 | `vr_flush` | **the node struct body** (see §5) | none | `velocirender_flush` |
| 4 | `vr_sect_pixel` | `dpl_POINT + float x,y` | inst handle (stubbed here) | `ghost_dpl_sectpixel` |
| 5 | `vr_sect_vector` | `dpl_POINT + float x0..z1` | inst handle (stubbed here) | `ghost_dpl_sectvector` |
| 6 | `vr_dcs_nest` | `int32 parent_remote, int32 node_remote` | none | `ghost_dpl_nest_dcs` |
| 7 | `vr_dcs_link` | `int32 bro_remote, int32 sis_remote` | none | `ghost_dpl_link_dcs` |
| 8 | `vr_dcs_prune` | `int32 parent_remote, int32 child_remote` | none | `ghost_dpl_prune_dcs` |
| 9 | `vr_draw_scene` | `int32 double_buffered` | **async** `vr_draw_scene` frame-ack | `ghost_dpl_draw_scene` |
| 10 | `vr_draw_scene_complete` | (poll only, via input status) | — | host-side only |
| 11 | `vr_list_add` | `int32 head_remote, int32 node_remote` | none | `ghost_dpl_add_list_item` |
| 12 | `vr_list_remove` | `int32 head_remote, int32 node_remote` | none | `ghost_dpl_remove_list_item` |
| 13 | `vr_morph` | `int32 morphed,a,b_remote, float32 alpha` | (stub) | `ghost_dpl_morph_object` |
| 14 | `vr_version` | — | version fields (host fills locally) | `ghost_dpl_version` |
| 15 | `vr_statistics` | — | stats record | `velocirender_statistics` |
| 16 | `vr_readpixels` | `x, y, n_pixels` | **pixel data** (see §6) | see §6 |
| 17 | `vr_hspcode` | link addr + 128-byte HSP blocks | — | boot only |
| 18 | `vr_860code` | i860 .text (7-word header + segment) | — | boot only |
| 19 | `vr_860data` | i860 .data segment | — | boot only |
| 20 | `vr_860bss` | i860 .bss size | — | boot only |
| 21 | `vr_860args` | i860 argv string | — | boot only |
| 22 | `vr_set_geom_verts` | header + vertex/connection blocks (§5.2) | `int32` ack | `ghost_dpl_set_geometry_vertices` |
| 23 | `vr_set_texmap_texels` | header + 64-int32 texel blocks (§5.3) | `int32` ack | `ghost_dpl_set_texmap_texels` |

Board dispatch that a virtual board mirrors: `VR_REMOT.C:remote_velocirender()` —
receive message, `action = data[0]`, `param_data = &data[1]`, switch on action, and
if the handler returns `ret>0`, `reply(ret,...)`.

---

## 4. Boot sequence (must be satisfied before any rendering)

`start_velocirender()` (VR_COMMS.C) runs, in order:

1. `setLA(0x150); initLA();`
2. `reset()` — the analyse/reset strobe sequence on ports 0x160/0x161.
3. `boot_xputer()` — streams the transputer `.BTL` file raw in 2 KB blocks out the link.
4. **3-transaction iserver handshake per i860** (`startup_handshake`): the (real) i860
   C-runtime boots and issues 3 iserver requests (getenv-style); the host services them
   in `iserver_action`. Comment in source: *"relies on the knowledge that the C run-time
   boots up and does 3 iserver transactions before closing down."*
5. `boot_HSP()` — 128-byte HSP microcode blocks via `vr_hspcode`.
6. `boot_860()` — reads the `.MNG`: a 7×int32 header (csize, dsize, bsize, cstart,
   dstart, bstart, entry) sent via `vr_860code`, then code/data/bss segments via
   `vr_860code/860data/860bss`, plus argv via `vr_860args`.
7. `vr_init` with the init arg string; waits for the reply.

**Virtual-board behaviour:** accept and **discard** all boot payloads (BTL/HSP/MNG);
we don't run that firmware. The only thing we must *reproduce* is the handshake shape
so the host proceeds: emit the 3 iserver transactions the host services in step 4, and
reply to `vr_init`. The `iserver_action` cases the host implements (and therefore the
kinds of request it expects from us) are: 40=commandline, 42=version(1.50),
32=getenv, 24=fputblock, 13=fwrite, 16=fflush. For getenv we can reply with empty
strings; the goal is only to advance past the 3-transaction gate.

---

## 5. The node / handle / flush model (the heart of the renderer contract)

DPL is a scene graph of typed nodes (`DPLTYPES.H`): `dpl_DCS` (transform),
`dpl_GEOMETRY`, `dpl_GEOGROUP`, `dpl_LOD`, `dpl_OBJECT`, `dpl_INSTANCE`, `dpl_MATERIAL`,
`dpl_TEXTURE`, `dpl_TEXMAP`, `dpl_LIGHT`, `dpl_LMODEL`, `dpl_RAMP`, `dpl_VIEW`,
`dpl_ZONE`.

**Handles.** Each node has a `remote` field = its board-side identity. `vr_create`
sends the node type; the board allocates the object and returns a handle; the host
stores it in `remote`. All later references use handles, not host pointers. *A virtual
board just hands out unique 32-bit ids and keeps an id→object table.*

**Pointer→handle rewrite (`remotize`).** Before flushing a node, the host swaps every
embedded child pointer for that child's `remote` handle (`DPL_HOST.C` macro
`remotize`), flushes, then restores local pointers. So **on the wire, all inter-node
links are handles** — directly usable by our board's object table.

### 5.1 `vr_flush` — node body upload
`velocirender_flush` sends the node struct starting at the `remote` field for
`sizeof(struct) - delta` bytes (`delta = sizeof(dpl_node) - sizeof(dpl_remote_node)`,
i.e. it skips the local-only header). The board `memcpy`s it over its copy. This is how
transforms (the DCS 4×4 matrix), material colours, LOD ranges, instance refs, view
params, light params, etc. reach the board. **Field layouts come straight from
`DPLTYPES.H`** — the same structs `dpl3-revive/parser` already reads.

### 5.2 `vr_set_geom_verts` — geometry
Header record (5×int32 used): `remote, vert_blox, conn_blox, vertices, connections`,
then `vert_blox` × `sizeof(dpl_VERTEX_LIST)` blocks, then `conn_blox` ×
`sizeof(dpl_CONNECTION_LIST)` blocks (each a linked-list node sent whole). Board
reassembles into its geometry. Reply = int32 ack.

### 5.3 `vr_set_texmap_texels` — textures
Header (5×int32 used of 8 sent): `remote, n_texels(=u*v), u_size, v_size, mode`, then
texels streamed **64 int32 at a time** (`endian_fix=0`, raw). `mode`: `1`=8-bit
(bilinear path, `dN_pxpl5_texture8`), `2`=24-bit FX (`dN_pxpl5_fx_texture24`),
else 24-bit (`dN_pxpl5_texture24`). Texel word format matches the SVT `0BGR`
convention already decoded in `spec/SVT_FORMAT.md`. Reply = int32 ack.

---

## 6. Display path — the one item to pin against `FLYK.EXE`

In **this DPL3 source snapshot**, `velocirender_readpixels`, `sectpixel`, `sectvector`,
and `morph` all `return 0` (stubs): the board rendered to its own PixelPlanes video
output (NTSC/SVGA off the card), so the host never read pixels back.

But the **shipped `FLYK.EXE`** contains active pixel-readback machinery — strings
`_rframebuffer/_gframebuffer/_bframebuffer`, `dump_frame_buffer`, `vr_read_pixels`,
`velocirender received only %d bytes`, `VelociRender flush on 2d display 0x%x`. So the
HPDAVE build is a **later/derived** library where readback *is* implemented and the host
paints its own SVGA/VESA framebuffer from the returned pixels.

This is the ideal seam for Path A and must be confirmed against the binary:

- **If FLYK uses readback (expected):** our virtual board renders a frame (GPU or the
  existing CPU rasterizer) and returns it as `vr_readpixels` payload; the host's own
  SVGA path displays it. We never emulate a video encoder — the host shows the pixels.
- **If any content instead relied on board-direct video:** the virtual board opens its
  own output window rather than returning pixels. (Applies at most to binaries lacking
  the readback strings.)

**Action:** trace `vr_readpixels` in `FLYK.EXE` (its `dpl_readpixels` → the
`DPL.C:3804 ghost_dpl_readpixels` call site, reimplemented in the shipped lib) to nail
the exact request args (`x, y, n_pixels`) and the reply pixel packing (word order,
chunking — likely the same 64-word fragmentation as texels). This is the only payload
whose shipped form isn't fully fixed by the snapshot.

---

## 7. Virtual-board architecture

```
  FLYK.EXE (unmodified, 32-bit Watcom/DOS4G)
        │  port I/O 0x150-0x161  (polled C012)
        ▼
  DOSBox-X custom device  "virtual C012 link adapter"      ← NEW, small
        │  byte stream  ⇄  message assembler (§1,§2)
        ▼
  VelociRender protocol server (§3-§6)                     ← NEW, the real work
        │  id→object table, flush→struct decode, scene graph
        ▼
  Renderer  =  dpl3-revive pipeline (transform/light/cull + raster/GPU)   ← REUSE
        │  rendered RGBA frame
        ▼
  vr_readpixels reply  ─────────────────────────────────►  host SVGA display
```

Work split:
- **New, mechanical:** the DOSBox-X C012 device (six ports + a byte FIFO) and the
  message-envelope assembler. Bounded and testable in isolation.
- **New, substantive:** the protocol server — handle table, the `vr_flush` struct
  decoders (mapping `DPLTYPES.H` structs to our scene objects), and boot-handshake
  emulation. `VR_REMOT.C` is the line-by-line reference.
- **Reused:** geometry/texture ingestion, the DPL instance transform, materials +
  gamma, and rasterization already exist in `dpl3-revive/parser` + `viewer`. The
  protocol server feeds them the *same* data the file parsers produce — it arrives over
  the wire instead of from `.BGF`/`.SVT` files.

### Why Path A is now cheap
The two things that usually make "run the original binary" expensive — reversing an
undocumented protocol, and rebuilding the renderer — are both already solved here: the
protocol is in source (this doc), and the renderer is the project we've been building.
Path A is mostly *plumbing the existing renderer behind a wire protocol*, plus a tiny
emulated link card.

### Relationship to the reimplementation track
Roadmap items 6–7 (port the geometry pipeline; GPU rasterizer) reimplement DPL3 as a
standalone viewer and discard the EXE. Path A instead keeps the **original host binary**
(its scene scripting, `.EVT` event timing, game logic, input, frame pacing) and
substitutes only the renderer. The two share the same rendering core; Path A adds the
link device + protocol server on top.

---

## 8. Open items / next steps

1. **Confirm the readback display path in `FLYK.EXE`** (§6) — decides whether the board
   returns pixels or self-displays. Highest priority; everything else assumes readback.
2. **Pull the exact `vr_readpixels` request/reply layout** from the shipped lib
   (`DPL.C` readpixels path) — the only payload not fully fixed by the snapshot.
3. **Lock struct sizes** for `vr_flush` bodies and the vertex/connection blocks against
   `DPLTYPES.H` on this exact build (watch Watcom struct packing/alignment).
4. **Prototype the DOSBox-X device** headless first: log the boot handshake +
   `vr_init` from a real `FLYK.EXE` run, verify our assembler frames the messages, then
   add rendering.
5. Decide host: DOSBox-X custom device (C++ in the emulator) vs. a shim DLL — DOSBox-X
   is the right home because the app does **direct port I/O**, with no driver hook point.

---

## 9. Validation status

**Static (patha/verify_framing.py, vs the shipped `FLYK.EXE` code object).** Found, as
literals in the transmit/link code: the `0x00FF0000` broadcast mask, the `0x80000000`
iserver bit, the `0x1FC` (508) packetize chunk, the `0x150` link base, and C012 port I/O.
Disassembly of the length-word construction confirmed the structure — and revealed the
shipped-build **bit30 `0x40000000`** flag absent from the 1994 source (§2), now mirrored.

**Dynamic (real `FLYK.EXE` under stock DOSBox-X 2026.07.02, no responder).** FLYK boots,
drives the link at 0x150, streams the transputer boot, then blocks in the handshake
awaiting the board. The unmapped port reads `0xFFFFFFFF`, and FLYK prints:

```
Protocol error : length 65535 too big, length_word 0xffffffff
+++ERROR : rcv_protocol fail during iserver handling, xmits=0
```

This is exactly `receive_protocol` (`nb = length_word & 0xffff` = 65535 > 1040 → reject)
called from `handle_iserver_stuff` during `startup_handshake` — confirming, against the
real binary, that the length word is 4 bytes with the count in the low 16 bits, and that
the *only* thing missing is a board that answers. Two more benign shipped-vs-snapshot
deltas surfaced: the shipped error strings additionally print `length_word` and `xmits`
(same framing). A responder that satisfies the 3-transaction handshake (§4) will let FLYK
proceed into the framed HSP/860/init/scene traffic.

**Live (custom DOSBox-X build + our C012 bridge + real FLYK.EXE).** A custom DOSBox-X was
built with `src/hardware/vrlink.cpp` (the C012 bridge, ports 0x150–0x161 → TCP 127.0.0.1:8620,
enabled by env `VRLINK=1`; init hooked next to `GLIDE_Init` in `sdlmain.cpp`). Running real
FLYK against a **quiet capture board** (patha/vrcapture.py) captured 80,909 bytes:
`00 52 53 45 54` ×3 (FLYK's `reset()` strobing port 0x160 three times) + the **full 80,894-byte
transputer boot stream** (`f0 b4 d1 d1 d1 24 …` = VRENDMON.BTL verbatim). FLYK then printed:

```
timeout in inRecord
velocirender_receive timed out - sends_wo_rcv=0
velocirender_input failed in start_velocirender
```

— a *clean* timeout (not the stock garbage-read), i.e. the bridge faithfully carries the
protocol and FLYK is now waiting for the board to answer. **The whole path is proven:
custom build → C012 ports → socket → Python board.** Iteration from here needs **no rebuild**
(board logic is pure Python).

**Next blocker (precisely located): the post-BTL boot handshake.** After the boot download the
shipped `start_velocirender` calls `velocirender_input` expecting the board to send the first
message (the transputer/i860 C-runtime startup handshake — the 1994 source's "3 iserver
transactions", but the shipped flow differs and uses `velocirender_input`/`sends_wo_rcv`). An
unknown iserver tag makes the host `exit(666)`, so the exact expected bytes should be nailed by
disassembling shipped FLYK's `velocirender_input` path (or careful empirical bring-up), not
guessed. Once the handshake passes, FLYK proceeds to the framed `vr_860*` MNG download → `vr_init`
→ scene traffic → `draw_scene`/`readpixels`.

---

## 10. END-TO-END ACHIEVED — FLYK.EXE runs its full render loop through the board

Custom DOSBox-X (`src/hardware/vrlink.cpp`, env `VRLINK=1`) + `patha/vrrun.py` board +
real `FLYK.EXE`. FLYK now runs unmodified through the entire protocol into its main loop,
with **no errors**:

1. Transputer `.BTL` boot streamed (byte writes to 0x151); board sends one vr_net frame to
   satisfy `velocirender_input` (§4).
2. i860 `.MNG` firmware downloaded as framed `vr_860code/data/bss/args` (833 msgs) — discarded.
3. `vr_init` (real argv) → board replies.
4. **Full SHARKS scene graph built** (~69 nodes): `create` (fire-and-forget, host-assigned
   handle in payload word 2 — not the 1994 reply model), `flush` (struct bodies), `dcs_link`,
   `list_add`; loads geometry/texture/material search paths, sfx, fog.
5. **Main loop**: `draw_scene` per frame (board async-acks) + per-frame `0x1d` (56B). `0x2a`
   (8B) is the **velocirender_sync barrier** (echo-ack it); `0x1c`/`0x1d` are fire-and-forget.

### C012 FIFO wire protocol (definitive, from vrlink port logging)
Framed message = two channels, **body first**:
- **Body** (action+payload) → **port 0x154**, 16-bit `rep outsw` words (padded to even; the
  length word's `count` is the true unpadded length).
- **Trailing length word** (`0x40ff00NN`, 4 bytes) → **port 0x151**, byte writes (commits it).
- Replies read **byte-wise from port 0x150** as serial `[length_word][body]`.
- Boot `.BTL` streams byte-wise to 0x151 (no body pending → raw passthrough).
`vrlink.cpp` demuxes and re-emits length-first `[length_word][body(count)]` to the board.

### Shipped-vs-1994 deltas
- Length word always sets **bit30 (0x40000000)**.
- **FIFO transport** (0x154 word body + 0x151 trailing length) vs source's serial byte path.
- `create` **fire-and-forget**, **host-assigned handle** (payload word 2), no reply.
- New actions: **0x2a** = `velocirender_sync` (echo-ack), **0x1c/0x1d** = fire-and-forget
  data / per-frame ops (geometry/camera — not yet decoded).

### Remaining = RENDERING (not protocol)
FLYK spins `draw_scene` with no wait (instant ack) and issues **no `vr_readpixels`** in this
scene. To see the demo: decode the geometry/material carried by `flush` bodies + `0x1c/0x1d`,
feed the dpl3-revive renderer, present frames (return via `vr_readpixels` if FLYK pulls them,
else a board-side window), and pace `draw_scene` acks to ~60 Hz for real-time animation.

---

## 11. Rendering phase — live scene-graph decode (patha/analyze_scene.py)

What FLYK streams (decoded from the framed capture of a SHARKS.SCN run):

| Data | Carrier | Notes |
|------|---------|-------|
| Camera | `flush` body, type 3 (view) | matrix + 832×512 screen + clip + fog + back_color(0.4,0.6,0.9) |
| Transforms | `flush` bodies, type 5 (dcs) ×26 | 4×4 `dpl_MATRIX` each |
| Placements | `flush` bodies, type 4 (instance) ×22 | `dcs`,`object`,`f_material`… handles (`dpl_INSTANCE`) |
| Materials | `flush` body, type 12 ×1 | emissive/ambient/diffuse/opacity/specular (`dpl_MATERIAL`) |
| **Per-frame animation** | **action 0x1d** (2×/frame, 56B) | transform/camera update — drives the flythrough |
| **SPECIALFX particles** | **action 0x1c** (80B) | matches SHARKS.SCN SPECIALFX params (11.0,360,0.9,-19,0.99…) |
| Geometry meshes | **referenced by name → files** | NOT on the wire — no `set_geom_verts`/object/geometry creates; loaded board-side from the geometry/texture search paths. dpl3-revive already parses these (`.BGF`/`.SVT`). |

Flush body layout = `[remote:4][type_check:4][struct fields after dpl_node]` (flush starts at
`&node->remote`). Struct field offsets per `source-ref/DPLTYPES.H` (mind the `#if REMOTE` fields).

**Key finding:** the whole *scene graph and animation* come over the wire; only the *geometry*
is by-reference (file-loaded). And FLYK issues **no `vr_readpixels`** — the real board drove
video directly — so frames must be presented board-side, not returned to FLYK.

### Rendering approaches (design fork)
- **A — Hybrid (fastest to visible):** take the live camera + per-frame `0x1d` animation from the
  protocol; render the SHARKS scene's geometry/placements from files via the existing dpl3-revive
  pipeline; present in a board-side window. FLYK drives camera/timing; sidesteps the
  instance→object→file handle mapping (which isn't on the wire).
- **B — Faithful (purist):** additionally decode instance→object references and reproduce exact
  placements/materials/sfx from the wire, using files only for the raw meshes. More decode work
  (resolve how object handles map to geometry files board-side).

Either way the renderer core is the dpl3-revive pipeline; pace `draw_scene` acks to ~60 Hz so
FLYK animates at real speed instead of spinning.

### Hybrid render achieved (patha/hybrid_render.py -> patha/flyk_render.png)
First visible frame: the SHARKS.SCN reef FLYK.EXE is running, assembled from files by the
dpl3-revive pipeline and viewed from an in-scene (diver) camera — a textured shark in the reef.
The fish cluster (-220,225,-350) matches FLYK's live 0x1d translations (y~230, z~-200),
confirming the wire animation targets the same content. Camera *projection/fog/back_color* are
taken from the decoded VIEW body (§11); the *pose* is a DCS (animated by 0x1d).

---

## 12. FULL PATH B ACHIEVED — geometry on the wire, live board-side window (2026-07-04, session 2)

**The §11 "geometry is file-loaded board-side" conclusion was wrong — it was an artifact of a
broken run.** Root cause chain, proven by live iteration:

1. `HPDAVE\SHARKS.SCN` searches `..\geometry`, `..\sharks`, `..\texture` — none of which exist
   beside `sda4\HPDAVE`. FLYK **fails object loads silently** (the "Failed to load object" print
   only fires when `dpl_NewObject` returns NULL, not when the file is missing) and builds an
   empty world: every instance flushed with `object=NULL`, no geometry/texture traffic. That was
   the capture §11 analyzed.
2. The shipped FLYK registers object-load extensions `.bgf .bmf .bsl .tga .vtx` (strings in the
   EXE) — **not** `.b2z/.svt`. But its `dpl_bgfRead` validates the same `DIV-BIZ2` container the
   `.B2Z` files hold ("`dpl_bgfRead "%s" is not a valid biz file`").
3. **Fix = staging** (`patha/stage_assets.py` → `c:\temp\flykc`, mounted as C: by
   `patha/flyk_vr.conf`): copy `HPDAVE`, copy `DPL3\GEOMETRY` exposing `*.B2Z` as `*.BGF`, decode
   `DPL3\TEXTURE\*.SVT` (raw xBGR 32-bit) to `*.TGA`. With that, FLYK loads the reef and
   **uploads everything over the link**. (`fishes`, `banner`, and the `sharks:*` textures have no
   surviving source files anywhere on the drive — those entities stay object-less; the i860
   firmware has no file I/O, so nothing was ever board-loaded.)

### Shipped wire protocol, geometry phase (all decoded live)
- **Shipped node type ids differ from 1994 from 7 up**: 2=zone 3=view 4=instance 5=dcs 6=lmodel
  **7=object 8=lod 9=geogroup 0xa=geometry 0xb=material 0xc=texmap** (1994 order was
  object=8…material=12).
- **Action 0x17** (1994 `set_texmap_texels`) = **bulk vertex upload**. Header 36B =
  `[geom_handle][0][n_verts][stride_words][n_conns][vert_type][geo_type][conn_sz][GEOMSCALE:f32]`,
  then framed data fragments (≤508B); **one ack** (echo action, int32 1) after
  `n_verts*stride*4` bytes. Vertex strides: `vtype 0x13` = `[x y z nx ny nz u v]`,
  `vtype 0x15` = `[x y z r g b a u v]`. `gtype 5` = pmesh, `gtype 2` = implicit single polygon
  (no connectivity follows). **Wire positions are divided by GEOMSCALE; the header's float
  restores model units** (verified against raw .B2Z bounds).
- **Action 0x19** = **add connections**. Header 16B = `[geom_handle][n_conns][indices_per_conn]
  [flags]`, then `n_conns*per` int32 indices; one ack. (Ocean quad = `[1][4]` + `0,1,3,2`;
  fish pmesh = `[70][3]` + 70 triangles.)
- **Graph refs in flush bodies** (wire-payload word indices, where word0=remote):
  instance word6 = object handle; geogroup words16/17 = f/b material; DCS matrix words4–19
  (4×4 row-major, translation in row 3), word20 = parent DCS (instance DCSs → world DCS 0x3;
  camera tree uses explicit `dcs_link` 0x1→0x2, 0x1→0x3 instead). object→lod→geogroup→geometry
  attach via `list_add`. Repeated STATICs share objects (host object file cache).
- **VIEW body** (104B, projection only, no matrix): wire float idx 6..17 =
  `x0 y0 x1 y1 zeye x_size y_size hither yon back_rgb[3]`, idx18 = fog_enable,
  idx19..23 = fog `[near far r g b]`. SHARKS: ±1 × ±0.615 image plane at zeye=1.3, 832×512,
  clip 8..4500, back (0.4,0.6,0.9), fog 500..4000 (0.05,0.1,0.12).
- **Action 0x1d** = per-frame DCS transform (shipped `flush_artics`):
  `[dcs_type=1 (matrix)][dcs_handle][3×3][tx ty tz]`, fire-and-forget, 2/frame in
  SHARKS: handle 0x1 (root, constant identity+t(0,5,5) when idle) and the DYNAMIC shark's DCS
  (spline path from SHARK1.SPL, scale 8 baked into the 3×3). **The 0x1d 3×3 is row-vector
  convention, same as the flush matrices** — proven by `patha/heading_test.py`: across ~7000
  records, model −Z tracks the swim velocity (dot ≈ −1, 95% of samples); a transpose mirrors
  the yaw (user-visible as reversed turning). Corollary: **the spline animation is built for
  nose-along−Z models.** The original `..\sharks` shark (lost) was authored that way; the
  surviving stand-in `DPL3\GEOMETRY\SHARK.B2Z` is nose-along-+X, so the renderer applies a
  +90° yaw model correction (X→−Z) to dynamically animated instances only.
- **Camera** = inverse of (M_dcs0x2 · M_dcs0x1); look −Z, row-vector convention (p′ = p·M),
  child→parent composition. 0x1d on 0x1 = head motion (joystick when a pilot is present).

### Board-side real-time window (Path A/B complete)
`patha/vrview.py` (numpy rasterizer + pygame, ~18–30 fps at 640×400) renders straight from the
live board state: wire geometry, DCS graph, VIEW projection + fog + back color, 0x1d animation.
`python vrrun.py <prefix> --view` presents each `draw_scene` and paces the ack (≤60 Hz), so the
unmodified FLYK.EXE runs its demo in real time against the virtual board — swimming shark, fish
cluster, kelp, ocean planes, all from the wire. Offline proof/debug: `patha/test_view.py`
(replay a capture → PNG; `flyk_live_render2.png` = the shark mid-swim), `patha/census.py`,
`patha/decode_anim.py`.

### Run recipe (session 2)
1. `python patha/stage_assets.py` (once; rebuilds `c:\temp\flykc`)
2. `python patha/vrrun.py cap --view`
3. `$env:VRLINK='1'; G:\DOSBox-X\dosbox-x-vrlink.exe -conf patha\flyk_vr.conf`

### SDEMO findings (2026-07-04, session 2 continued — the full Hull Pressure demo)
Nearly all HPDAVE scenes point their GEOMETRY path at `.\video`, which **survives intact**
(201 files) — SHARKS.SCN was the worst-provisioned scene on the drive. `stage_assets.py` now
stages `HPDAVE\VIDEO`; `run_demo.py <SCENE>` selects scene/exe via `C:\RUNSCN.BAT`. SDEMO
(144 entities, 41 objects, 12 splines) runs live end-to-end and decoded more of the protocol:

- **Action 0x1a = set_texmap_texels** (1994 layout): header 32B
  `[texmap][n_texels][u][v][mode][3 junk words]`, then 64-int32 (256B) chunks; ONE ack.
  Texel word = `[pad,B,G,R]` (confirmed against DNC.C `dN_pxpl5_fx_texels`).
- **mode 1** = 8-bit intensity (grayscale replicated across B,G,R) — decodes clean.
- **mode 0** = **BSL bit-slice pack**: the page holds up to eight 4-bit monochrome textures,
  one per nibble plane of the 32-bit texel word (verified: planes of SDEMO's texmap 0x3e are
  distinct coherent sub-interior textures; a 256×256 page holds the VW logo + a mural in
  different byte lanes). Each dpl_TEXTURE node sharing the texmap carries a small-int slice
  selector late in its flush body (values 0x14–0x1a observed) — exact value→nibble mapping
  not yet pinned. Matches the b2z `bitslice` tag (0x018) and the `.BSL` files in VIDEO.
- **More vertex formats** on 0x17 uploads: vtype 0x01 stride 3 `[xyz]`, vtype 0x11 stride 5
  `[xyz uv]`, vtype 0x41 stride 4 (gtype 0xa, spheres/points?), in addition to 0x13/0x15.
- **Offset vertex updates**: 0x17 header word1 = first-vertex index, word7 = total vertex
  count (word1+count ≤ word7) — `dpl_UpdateGeometryVertices`, used for vertex animation.
  The board must merge uploads into the full array, not replace.
- **Geometry flush body references its texmap directly** (stored word 3), simpler than the
  geogroup→material→texture→texmap chain.
- **Corrected type ids: 0xc = texture, 0xd = texmap** (earlier §12 guess had them swapped).
- Per-frame traffic: heavy **vr_morph** (action 13 — fish-school vertex morphing, .V2Z),
  **0x1b** (72B, periodic), **0x22** (8B), 0x1c SPECIALFX — all currently discarded.

### Cross-product runs (session 2 continued): KLNGVID (Star Trek), BLADE (Red Planet)
Other products stage at the mount root (their scenes use absolute `\STDAVE\VIDEO`-style
paths) with the HPDAVE FLYK runner copied in (`stage_assets.py stage_product`). Decoded:

- **Material flush body** (0xb, wire words): texture@2, **emissive@5-7, ambient@8-10,
  diffuse@11-13, opacity@14-16, specular@17-20** (stored-body idx −1). Applied in vrview.
  **Exact ambient=(1,0,0) AND diffuse=(1,0,0) is the shipped build's UNSET-material
  marker, not a colour** — every .B2Z-default material (all of SHARKS) and the Trek star
  materials carry it; render as white. (Found as a red-reef regression during the SHARKS
  re-validation run.)
- **dpl_TEXTURE flush body word 14 (stored 13) = BSL bit-slice selector** (0x14…0x1a).
- **0x1d COMPOSES with the flushed DCS matrix** (M_flush · M_anim, row-vector): the DCS
  holds model scale (KLNGVID klngn 0.1), the spline pose rides on top. SHARKS' identity
  base matrix had made replace-vs-compose indistinguishable.
- **Action 13 (vr_morph)** = `[morphed][geomA][geomB][alpha:f][flags]` — board-side vertex
  blend a→b into the morphed geometry (SDEMO fish schools). Implemented.
- **Action 0x1b** = `[zone][dcs][4×4]` occasional zone-root matrix refresh; identity 3×3 +
  uninitialized row-3 junk when the host DCS is identity-flagged — ignore those.
- **SCHILD/DCHILD effect attachments** (Trek shield bubbles, invisible-until-hit) carry a
  nonzero hierarchy pointer at wire word 21 of their DCS body — vrview skips them.
- **Shipped FLYK quirks**: KLNGVID's `START x y z` parses z wrong (camera got y duplicated
  into z — authentic shipped behavior); `TRACKER KEYBOARD` input path not yet working under
  DOSBox (keys don't move the camera — investigate how the tracker reads the keyboard).
- **MAPS\*.SCN files are a different key=value dialect** (`viewangle=60.0`) that hangs
  FLYK's parser — stage SCENES\ versions, never MAPS.
- **BLADE.SCN runs**: 770 geometry uploads, 29 texture pages, 200+ instances — the Mars
  canal city renders fully textured (RPDAVE pages are full-color, no BSL packing).

### Completeness batch (session 2 close-out) — all five scenes regression-PASS
Implemented and validated by `patha/regress.py` (replays every scene capture, renders,
reports; zero handler errors across SHARKS/SDEMO/KLNGVID/BLADE/FXTEST):

- **Wire lighting**: lmodel (0x6) / light (0xe) bodies = `[dcs@2][light_type@3][r g b @4..6]`
  (stored words); type 2 = ambient, type 3 = directional with aim = the light-DCS's Z row
  (SHARKS: sun (0,1,0) from rx=−90 ✓). Renderer uses scene ambient + suns, double-sided.
- **LOD range selection**: lod body stored words 15/16 = switch_in/switch_out; renderer
  picks by eye distance (fallback LOD 0).
- **SCROLL**: board-side autonomous texture animation from the texture body's
  u0/v0/du/dv (stored floats 8..11), du/dv per second.
- **BILLBOARD**: instance stored word 3 == 2 (vs 3 normal) — camera-facing spherical
  billboard (FXTEST `flamebig`).
- **Sphere lists** (vtype 0x41, `[x y z r]`): shaded screen-space discs.
- **sect_vector**: real Möller–Trumbore picking over live world triangles; reply =
  int32 instance handle. Self-test: an upward underwater ray correctly hits the ocean
  surface quad. (sect_pixel still needs camera unprojection of board 832×512 coords.)
- **vr_readpixels**: experimental reply — `[pad,B,G,R]` pixel words from the last
  rendered frame, 508B fragments; no shipped binary has exercised it yet.
- **Action 0x22** = name binding `[handle][0x8000xxxx name id]` (board createName;
  fire-and-forget; stored in board.names — GEOMETRIZE 0x8000005a-style refs resolve here).
- **BSL slice mapping**: rank-based (sorted texture-node selectors → content nibble
  planes in order). No more rainbow; exact selector→nibble encoding still unproven.

### SPECIALFX (action 0x1c = install_sfx) — decoded + ambient sim implemented
Payload (80B): `[code][texture ref][type][velocity][size][off_y][bias][cook_r g b]
[variance][gravity][o_cool][cool][frags][rpt][4 host ptrs]` — exactly the .SCN
SPECIALFX columns. Defs are *installed* at scene load; two trigger models:
- **Ambient** (SHARKS bubbles/marine snow): the board steps installed defs
  autonomously. Implemented in vrview `_particles`: per-def pools (frags×rpt),
  spawned in a camera-centred volume at bias/off_y height, rise at `velocity`
  with `variance` jitter and `gravity`, fade by `o_cool^age`, lifetime 1/`cool`;
  soft-blended discs, no z-write. Regression stays green on all five scenes.
- **Event-triggered** (`PSFX \fx\*.pfx` lines in .EVT scripts, MORPH_OBJ/MORPH_MTL
  events): confirmed in FXTEST that *nothing* fires without the input path — not
  even the t=0.2 morph — so runtime FX triggering is **blocked on the keyboard
  tracker**, not on the protocol. The .PFX emitter format is self-documented in
  the files (position/velocity/radius/colour-in-out/duration + variances).

### Input SOLVED — joystick flight via the game-port (THRUSTMASTER) tracker
FLYK's `TRACKER KEYBOARD` is inert under DOSBox (no key ever moved the camera), but
`TRACKER THRUSTMASTER <gain> <gain>` reads the DOS game port, which DOSBox maps from
the physical joystick — **verified live: BLADE flown with a Logitech Extreme 3D Pro**,
camera 0x1d translations tracking the stick on the wire. `run_demo.py` now rewrites any
scene's TRACKER line to `THRUSTMASTER 4.0 0.3` before launch (`--no-joystick` to keep
the original). FLYK's input layer is joystick-first throughout (`joystick_read`,
DIVISION game-port calibration, `joystick.cal`).

### Fire control (action 0x23) + calibration notes
- **Stale joystick.cal = constant-velocity camera drift** (stick center offset reads as
  permanent deflection). Fix: delete the staged cal; FLYK runs its RE-CALIBRATION flow
  (wiggle to full scale) and writes a fresh one matched to the DOSBox-mapped stick.
- **Action 0x23** = fire/pick event on joystick trigger: `[u:f][v:f][host ptr][-1]`,
  (0.5, 0.5) = crosshair center. **CONFIRMED fire-and-forget** — replying desyncs the
  host stream (tested both ways: unanswered 0x23s are harmless; one reply stalled the
  run). The board still resolves the pick internally (pick_screen: VIEW-frustum
  unproject → Möller–Trumbore) for telemetry; FLYK's own hit/FX consequences must be
  computed host-side or armed by a mechanism still undecoded (the .EVT `PSFX` chain
  never fired in any FXTEST run).

### Protocol edges closed (session 3)
- **Action 0x18 = get_geom_vertices** — found by static hunt (LE fixup-table parse +
  capstone over shipped FLYK: `mov eax,0x18` into velocirender_transmit, 0x28-byte
  request, reply must echo action 0x18 into a 0x100-byte receive buffer). Board replies
  with the geometry's merged current vertex floats (request word0 = handle, words 1/2
  honored as vertex0/count when sane) in ≤240B echoed-action frames. Regression:
  byte-exact round-trip of an uploaded quad. `patha/hunt_actions.py` is the reusable
  hunt tool. `get_geom_numconns` exists only in the game binaries (RPL4OPT etc.), which
  are Borland **PE** images (32RTM DPMI), not Watcom LE — needs a PE-based hunt, filed
  under the MUNGA campaign.
- **sect_pixel** — wired to pick_screen (auto-normalizes board-pixel vs 0..1 coords);
  crosshair self-test picks a live instance.
- **statistics** — 1994 reply (int32 1) per VR_REMOT.C. **version** confirmed
  board-silent (host-local; not in the board dispatch switch).
- **readpixels** — self-tested: correct echoed-action fragmentation (100 px → 1 frame,
  400B). Still awaiting a real caller for final validation.
- Regression suite extended with all of the above; 5 scenes + 6 protocol self-tests PASS.

### Rendering fidelity batch (session 3)
- **BSL slice encoding DECODED EXACTLY** (`patha/bsl_pair.py`): wire selector 0 = file
  bitslice 0 (unsliced), selector 0x13+b = file bitslice b (1..8) — proven by the GENS
  pack whose nine wire selectors {0,0x14..0x18,0x1a,0x1b,+dup 0} match its file
  bitslices {0,1,2,3,4,5,0,7,8} one-for-one, duplicate included. **Nibble plane =
  bitslice + 2** (pad byte owns planes 0-1; GENH's six textures = exactly content
  planes 2..7). b ≥ 6 clamps to plane 7 (only the 9-texture packs; residual). On a
  sliced pack, selector-0 textures read plane 2; on plain pages selector 0 = the
  full-colour texture. b2z tag 0x018 (`bitslice`) is the authoritative file-side value.
- **Transparency**: texture-body alpha flag (stored word 4) → near-black texel cutout;
  material opacity < 1 (`DITHER n` = n%) → 2×2 ordered screen-door.
- **Specular** from material specular[4] (rgb + exponent), per-sun highlight.
- **NOVIEWMATRIX / HUD zones**: instance DCS whose parent word references a ZONE node
  renders in camera space (view matrix skipped) — SHARKS banner, SDEMO fcard.
- **RETRACE n** honored: run_demo parses the scene divider → board paces draw_scene
  acks at 60/n Hz (SHARKS 30 Hz, FXTEST 20 Hz — authentic animation speed).
- Regression: 5 scenes + 6 protocol self-tests all PASS; SDEMO interior now renders
  as coherent monochrome sub panels under scene lighting.

### DCS topology corrected — camera-motion cancellation bug (session 3)
`vr_dcs_link` is a **SIBLING** link (1994 payload `[bro, sis]`) and the DCS flush-body
word at stored offset 76 is the **sibling pointer**, not a parent: FLYK's top-level
DCSs (head 0x1, view-holder 0x2, and every instance DCS) form a flat sibling ring.
Treating either as parentage had chained the whole world through the tracker-animated
head DCS, so camera motion cancelled exactly (title-bar pose moved, view didn't —
also the fxjoy "frozen screen while drifting to (−1036,605)" symptom). Correct model:
instance chains follow **vr_dcs_nest edges only** (flat roots in all scenes so far);
camera pose = M(view's DCS) · M(head 0x1). Verified: the drift capture now renders
dramatically different frames along the flight path.
Ambient SPECIALFX sim is now **opt-in** (`run_demo --sfx` / VRVIEW_SFX=1): most scenes
install their defs for event use only — simulating them ambiently put bubbles in
scenes that never show them. Launchers enable it for the underwater HPDAVE set.

### Software-rasterizer optimization pass (session 3)
Vectorized pre-culling: whole-mesh early-out (nothing in front / screen bbox miss),
per-triangle batch rejection (clip, off-screen, degenerate) before the Python loop,
and **far-plane (yon) culling** — the big one for open scenes (BLADE's yon is 600 in a
6 km canal). Measured: BLADE 769→368 ms, SDEMO 883→466 ms (~2×), KLNGVID 249→224,
small scenes unchanged. `VRVIEW_SIZE=WxH` env (e.g. 384x240) trades resolution for
another ~1.7×. The remaining cost is per-visible-triangle Python overhead + numpy
fill — the endpoint is the **moderngl GPU backend** (mesh cache maps directly to
static VBOs; only matrices change per frame), targeted at 832×512 @ 60 Hz.

### GPU backend (session 4, 2026-07-04) — moderngl, 832×512 @ 60 Hz ACHIEVED
`patha/vrview_gl.py` = `GLRenderer(vrview.Renderer)`: SceneCache, DCS chain math,
picking, and view/material/SCROLL parsing are inherited; only the draw path is
replaced with moderngl (GL 3.3 core). The software rasterizer stays intact as the
debugging reference — `vrrun --view --soft` / `run_demo --soft` / `VRVIEW_SOFT=1`
select it; any GL failure auto-falls-back with a message.

Architecture facts:
- **SceneCache._mesh() results = static VBOs.** The VBO cache is keyed on the mesh
  dict's *identity* — `_mesh` already version-caches per handle (uploads, offset
  vertex updates, morph alpha), so a new dict means re-upload, same dict means zero
  per-frame work. Interleaved layout `[pos3 nrm3 col3 uv2]` + uint32 index buffer
  (fan-triangulated connections, unchanged). Morphing geometries re-upload per
  alpha change (small meshes; negligible).
- **Row-vector convention needs no transposes**: numpy row-major mat4 bytes are
  read column-major by GLSL, i.e. the shader sees Mᵀ, so `u_m * v` in GLSL IS
  `p @ M`. Projection is a row-vector frustum built from the VIEW body
  (x0/x1/y0/y1 at zeye, near=hither, far=yon·1.05) matching the software mapping
  exactly; instance matrices (chain, FIX yaw-90, billboard, HUD/NOVIEWMATRIX,
  LOD select by ‖T‖) are computed CPU-side identically to the software path.
- **Shaders replicate the software formulas 1:1**: per-vertex lighting (wire
  ambient + Σ|n·L|·suncol double-sided, per-sun specular rgb+exp, 0.7/sun
  no-normal fallback, 0.35/0.65 default rig when no wire lights), vertex-color
  modulate, clamp, texture×(base·1.275) (= software's texel·base/200), SCROLL
  uv offset (u0+du·t from the texture body, per frame), alpha cutout
  (texel sum ≤ 24/255 discard), DITHER 2×2 screen-door discard vs opacity,
  per-vertex linear fog mixed after texturing, sphere lists + SPECIALFX pools as
  depth-tested point sprites (particles: blend (ONE, 1−SRC_ALPHA) with
  rgb=cook·0.75·fade, a=0.6·fade ≡ the software soft blend; no depth write).
- **Linear FBO + gamma present pass**: the scene renders linear into an offscreen
  832×512 FBO; a fullscreen present pass applies the Division DAC gamma
  (out = in^(1/1.25)) — same single-application point as the software path.
  `last_frame` (readpixels replies) reads the FBO back post-gamma on demand,
  cached per rendered frame. Headless (`SDL_VIDEODRIVER=dummy`, regress) uses a
  standalone WGL context — no window needed.
- Textures: nearest + repeat (matches the software point sampler); uploaded once
  per SceneCache texture array (BSL slices included), cached by array identity.

Validation (RTX 3080 Ti):
- `regress.py` now runs both backends: software 45–447 ms/frame vs **GL 0.6–8.7
  ms/frame at 832×512** (SHARKS 1509 fps, SDEMO 272, KLNGVID 446, BLADE 115,
  FXTEST 1431) — 60 Hz with ≥2× headroom on the heaviest scene. PNGs
  `regress_gl_*.png`; mean-abs-diff vs the software reference: BLADE 4.5/255,
  KLNGVID 6.5/255 (near-identical). SHARKS/SDEMO/FXTEST diff higher for a
  KNOWN benign reason: the software pre-cull drops any triangle with a vertex
  behind hither/beyond yon, which kills huge ground/ocean planes; **GL clips
  properly and renders them** (FXTEST arena floor, SHARKS sea floor + surface
  horizon appear only in GL — GL is the more correct image).
- Live (real FLYK.EXE through DOSBox): SDEMO ran 3300+ frames (zero errors,
  RETRACE 2 → 30 Hz pacing honored, wire rate ~37 fps burst); **BLADE ran live
  at 65.7 fps** (900 frames / 13.7 s, 2400+ frames total, zero errors, a
  joystick-trigger 0x23 fire resolved a pick against the live scene) — full
  60 Hz on the heaviest scene. Windowed replay paces at 60.0 fps with 9 ms
  render. Adaptive frame-skip now never engages (skip stays 1 below
  50 ms/frame) — as predicted, it's vestigial on GPU.

## 13. MUNGA GAME BRING-UP — the real Red Planet runs (2026-07-05, session 5)

**`rpl4opt.exe -egg test.egg` (Red Planet v1.2.0.1) runs its full engine loop
against the virtual board**: 892 geometry uploads, 22 texture pages, 308
instances, 63 objects, 4 lights — the whole Mars canal city + the player's
starting hangar — with the attract-mode flight rendering live at ~90 fps in the
GL window. Staging: `stage_assets.py --game RPDAVE` (adds MAPS/MODELS/SOLIDS/
CAMERAS/GAUGE/SCENES + `32RTM.EXE` **and `DPMI32VM.OVL`** borrowed from BTDAVE
— 32rtm refuses to start without its DPMI overlay). Launcher: `run_game.py`
(mirrors RP.BAT: `SETENV.BAT t s n n` → `32rtm -x` → exe → `32rtm -u`).
`hunt_pe.py` = the PE-format static hunt (Borland PE sections + capstone),
counterpart of the LE hunt_actions.py.

### The MUNGA wire dialect (all proven live + by disasm)
- **Dialect detection: the first vr_sync action id.** The init argv is BYTE-
  IDENTICAL between shipped FLYK and rpl4opt (`/device~0x150~/video~svga~/pipes
  ~1~/qual~0x14~/system_tex~0~`) — sniffing it misclassified FLYK and yawed
  every demo camera (caught by regress diffs; the numbers, not the PASS flag).
  0x2d = MUNGA, 0x2a = FLYK; the flag flips on the first 0x2d.
- **vr_sync = action 0x2d** (FLYK's 0x2a moved). Disasm of rpl4opt's vr_sync
  (0x497080): the reply ACTION is never checked; the reply PAYLOAD word0 must
  echo the request's word0 (a cookie; mismatch → "unexpected action %d returned
  in velocirender_sync" printing the unrelated action + exit 9). FLYK's 0x2a
  cookie is 0, so the old zero-payload echo was accidentally correct.
- **The sync cookie is the action id being synchronized** (create → cookie 1,
  texel upload → cookie 0x1a): **MUNGA bulk ops are ACK-LESS** — 0x17/0x19/0x1a
  completions must NOT be acked (the sync echo is the ack; an extra upload ack
  desyncs the receive stream by one frame). FLYK keeps its per-upload acks.
- **create stays fire-and-forget** (host-assigned handle in payload word2; the
  1994 "unexpected action %d in velocirender_create" strings are absent from
  the PE — an experimental create-ack desynced the stream).
- **Action 0x1f = batched flush_artics**, replacing 0x1d entirely:
  `[n_records]` then n × `[handle][payload]` where a DCS handle carries
  3×3 row-major + t (12 floats) and non-DCS handles (HUD gauge nodes) carry 5
  floats (sin/cos-like; skipped). **Poses are ABSOLUTE** — the first record
  duplicates the flushed matrix exactly; composing (the FLYK 0x1d rule) doubles
  the transform. Stored in `board.anim_abs` (replace) vs `anim` (compose).
- **Camera rig via dcs_link parentage** (MUNGA ONLY): vehicle DCS —link→
  cockpit —link→ head DCS, view re-`list_add`ed onto the head (0xb5c); world
  pose lives in the 0x1f-animated vehicle DCS (0xaa1). The camera chain follows
  link edges in MUNGA; FLYK's links are flat sibling rings (following them
  relocated every demo camera). Instance chains stay nest-only in both.
- **MUNGA vehicles fly nose-along-+Z** — straight-fast-flight samples of the
  RAW vehicle 0x1f records put local velocity 3.8° off +Z (459 samples). An
  earlier composed-chain heading test read +X (+0.79) — that was BIAS from the
  attract head-yaw swinging ±54° in the cockpit DCS; measure the vehicle DCS
  alone. The renderer applies a camera-only yaw(180) (`cam_matrix`) mapping
  render-forward (−Z) onto vehicle +Z (the raw chain rendered 180° backward;
  the interim yaw(−90) guess showed as "flying sideways", user-confirmed).
- **Material body is 88B (FLYK 84B): every stored offset shifts +1**
  (emissive@5-7, ambient@8-10, diffuse@11-13, opacity@14-16, specular@17-20 +
  exponent). Misparse rendered the whole world green with a global DITHER
  screen-door (opacity read 0.815). lmodel (0x6) light bodies parse with the
  FLYK layout unchanged; the four type-0xe 32B bodies (vehicle lamps?) fail the
  sanity filter and are ignored.
- **Fire-and-forget unknowns** (don't block anything): 0x29 (8B, one word ≈ a
  high node handle) and 0x2b (140B, `[handle][1][2][0x1d]...` + floats — HUD/
  gauge displaylist-shaped). Undecoded; game runs without replies.
- First-boot trap: `32rtm error: Can't find DPMI32VM.OVL` — the overlay must
  sit beside 32RTM.EXE on the path.

Regression: all five FLYK scenes byte-identical to baseline after the dialect
fix (36.8/33.6/6.5/4.5/89.5 diff signature); MUNGA runs live: hangar + canal
render in correct Mars tans/reds, camera tracks the attract flight.

### BattleTech (BTL4OPT v1.1.0.4) bring-up — session 5 continued
Runs the same MUNGA dialect end-to-end (arena + mechs on the board, 1800+
frames, ~100-130 fps GL). Asset chain findings:
- **BTDAVE's VIDEO tree is empty of the video\geo|mat|tex sets** its BTDPL.INI
  searches — GETVID.BAT fetched video.zip from a dead resource server. Symptom:
  "Unable to cache tsphere.bgf", "couldn't find texture btfx:...", then
  "L4VIDEO.cpp couldn't load object plit.bgf" → NULL instance → exit.
- **BTLIVE** (the pod's live snapshot) has the complete 1585-file VIDEO
  (GEO/MAT/TEX subdirs, .BSL packs) but its BTL4.RES is REJECTED by its own
  exe ("btl4.res v1.0.1.2 is obsolete!"). Working combination = **BTDAVE build
  + BTLIVE VIDEO graft** (stage_assets.py --game BTDAVE does this; --game also
  now copies product root files + VIDEO recursively; ANIMS staged: 634 files).
- Keyboard/controls: same keyjoy.map Thrustmaster synthesis applies.

**0x1f record structure CORRECTED (BT broke the fixed-size guess):**
`[n_records]` then n × `[dcs handle][payload]` where payload = 12f full pose
(absolute 3×3+t) OR a **joint angle record [sin, cos]** — 2 floats in BTL4
v1.1, 5 floats (sin,cos,0,0,0) in RPL4 v1.2. Version-dependent sizes → the
board parses by BACKTRACKING (each record starts with a valid DCS handle;
float bit patterns don't collide with small handle ints; misparse symptom was
det=0 matrices corrupting the camera chain — "landscape rendered, then flipped
to garbage" when per-frame updates began). Joint records = the mech
articulation stream (torso/leg joints, e.g. BT camera chain runs 11 DCS deep
through the mech rig: torso 0xdf1 world pose → ... → cockpit 0xe4a). Joint
sin/cos → local axis semantics still undecoded; flushed matrices stand, so
mech limbs don't articulate yet.

New fire-and-forget unknowns in BT: 0x24 (frequent), 0x20, 0x26 (once each).

Rendering findings from the BT bring-up (apply to all products):
- **Per-geometry texture refs**: MUNGA geometry bodies reference their TEXTURE
  node directly (word 2; some also their material) — resolving only through
  the geogroup→material chain assigned one shared page (every BT terrain tile
  got the cloud texture). SceneCache now prefers per-geometry texture/material
  refs, geogroup chain as fallback. Side effect: SDEMO's interior sub-panels
  now resolve their own BSL slices (visibly richer, wood/teal panels).
- **vtype 0x15 field 6 is NOT alpha**: values run −3.75..1.0 across products
  (a blend experiment made SHARKS' kelp ghostly). Stored as mesh['alpha'] data;
  semantics undecoded. How the BT cloud/sky layers blended on the real board
  is an open question (their 64×64 gray cloud page + SCROLL dv=−1.3 confirmed).
- **BT's parked view is fog-dominated**: its VIEW fog is near=150 far=1250
  color (0.32,0.30,0.65) — the purple "walls" are ground tiles (Y=75, camera
  11 above) and the 4000×4000 sky deck (Y=150) fogging to saturation. The
  view-body layout is IDENTICAL across FLYK/RP/BT (fog_enable word17=0x5).
- **"Waiting for translocation!"** — BTL4OPT parks the mech at the map edge in
  a LOBBY state until the pod network translocates it into the arena
  (NETNUB.EXE / BTNET.BAT are the network hub). This is BT's mission-start
  path; the RP equivalent is still undecoded. The arena itself (snow/rock
  textured terrain, mountains, structures) renders correctly — verified with
  the debug chase camera.
- **VRVIEW_CHASE=1|2** (env): debug chase camera in vrview.cam_matrix — follows
  the most-traveled 0x1f-animated DCS from behind-above; =1 turns with the
  target's nose, =2 keeps a world-locked offset (no spin). Use to see the
  world when the cockpit is fog-bound or a rig is undecoded.
- **MUNGA texture-body floats 10/11 are a STATIC uv offset**, not FLYK's
  du/dv-per-second SCROLL — animating them drifted the BT terrain texture
  across its mesh "like clouds" (user-observed). Board renders them as a
  fixed offset in the MUNGA dialect (semantics inference; FLYK SCROLL
  unchanged and regression-validated).
- **Instance stored word 3 = DISPLAY MODE: 3 normal, 2 billboard, 1/0 HIDDEN
  until armed.** Census: RP's exactly-4 w3=1 instances are the vehicle's
  effect attachments (rendered, they block the cockpit lens); BT's 11 are the
  PLAYER MECH awaiting translocation; SHARKS' single w3=0 is the null-object
  'fishes'. The renderer skips w3 ∉ {2,3} in all dialects (regression green;
  SDEMO −1 instance). Corollary: the mech is SUPPOSED to be invisible until
  translocation re-arms it — expect a re-flush with w3=3 as part of the
  translocation sequence (a decode hook for game-start).
- **MUNGA instance chains follow dcs_link parentage** (like the camera): mech/
  vehicle part instances hang off the 0x1f-animated rig via link edges —
  nest-only chains rendered them at world origin. FLYK stays nest-only.
- **SCHILD skip is FLYK-only**: MUNGA rig DCSs carry host pointers in the same
  stored-word-20 slot (skipping on it hid legit vehicle parts); MUNGA hiding
  is governed by instance w3 instead.
- **Texture filtering: the board POINT-SAMPLED** — proven in the i860 source:
  the texture inner loop (VRENDER/AS860/SCANLINE.SS, .txinner_loop) issues
  exactly one `fld.l texbase(reg)` per pixel from the interpolated u,v; no
  four-tap fetch exists. The GL backend's NEAREST default is authentic;
  VRVIEW_FILTER=linear opts into bilinear for modern taste.

### Translocation / mission-start (session 5 close) — network stack UP, needs a peer
BattleTech's "Waiting for translocation!" is a **multi-node network gate**, not a
local flag. The full 1996 pod LAN now runs inside DOSBox-X (run_game.py --netnub):
- `[ne2000] ne2000=true nicbase=300 nicirq=3 backend=auto` in flyk_vr.conf.
- `Z:\SYSTEM\NE2000.COM 0x60 3 0x300` — DOSBox-X's embedded Crynwr packet driver
  (registered under Z:\SYSTEM\ only when ne2000=true). The drive's era ODI stack
  (LSL+NE2000 MLID+ODIPKT) does NOT work — "An MLID could not be found" — use the
  built-in one. WATTCP.CFG (my_ip=200.0.0.86, from the egg) beside the exe.
- BTNET.BAT wrapper: `NETNUB.EXE -f btl4opt.exe -a -egg <egg>.egg` (netnub -f runs
  the game, -a forwards args). Netnub hosts wattcp, launches the game with
  `-net <shared_mem_addr>`, prints "Communicating through interrupt vector 0x61".
- Result: game becomes a live network client (further than standalone ever got)
  but still draws 0 frames — no peer sends the translocation message.

**Egg format decoded** (TEST.EGG = plain INI): `[mission] adventure/map=polar3/
scenario=freeforall/time/weather/temperature/length`, `[pilots] pilot=<ip>`,
`[<ip>] hostType=0 vehicle=thor dropzone=one name=Milo bitmapindex badge...`,
`[ordinals]`/`[largebitmap]` = HUD digit + pilot-portrait bitmaps (hex rows).
hostType 1/2/3 variants tested standalone — all still park (translocation is the
gate, not hostType). BTL4OPT strings confirm the ladder from AUDIO/SYMBOLS.SCP:
**BTPlayer states DropZoneAcquired(1) → VehicleTranslocated(2) → MissionStarting(3)**.
Translocation is the network event moving the mech from staging into the arena
(POVTranslocateRenderable) — expect the hidden w3=1 mech instances to re-flush
w3=3 when it fires.

Two paths forward (user decision): (A) reconstruct the mission HOST — BTL4D2S.EXE
(spooling/server build) or `netnub -t` master mode, two networked DOSBox nodes;
(B) hunt_pe.py the state check in BTL4OPT and patch past DropZoneAcquired →
MissionStarting (single-node bypass). RP's mission start is the analogous
undecoded gate. hunt_pe.py located the wait at 0x45d1e0 (state byte at [ebx+0x88],
values 2/9 branch to the print).

### Remaining to "100%"
- ramp colorization when a scene uses one (unseen on wire so far).
- MUNGA: joint-record axis semantics (mech articulation!), 0x29/0x2b HUD
  gauges, 0x24/0x20/0x26, get_geom_numconns (hunt_pe.py ready), mission start
  (translocation — host node or binary patch; see above).
- SDEMO VIEWSPLINE camera attach; .EVT arming; .SKL mech articulation test;
  validation vs RENDERS/pod video.