t2-demo-parser 1.0.2 → 2.0.0

package/README.md

@@ -1,8 +1,10 @@
 # t2-demo-parser
 
-Parser for Tribes 2 demo recordings (`.rec` files). Extracts game state, player
-movement, ghost object lifecycles, network events, and animation timelines from
-recordings made by the Tribes 2 client (build 25034, Torque engine).
+Parser for Tribes 2 demo recordings (`.rec` files) and live server packet
+streams. Extracts game state, player movement, ghost object lifecycles,
+network events, and animation timelines from recordings made by the Tribes 2
+client (build 25034, Torque engine), and parses the same packet format
+arriving from a live connection (see `createLiveParser`).
 
 Designed for use in browser-based replay viewers. The async API keeps the main
 thread responsive: in browsers, decompression runs in a Web Worker via
@@ -18,14 +20,14 @@ const buffer = new Uint8Array(/* .rec file contents */);
 const parser = new DemoParser(buffer);
 const demo = await parser.parseFullDemo();
 
-console.log(demo.header.demoLengthMs);           // Duration in ms
-console.log(demo.initialBlock.missionName);       // e.g. "Rollercoaster"
-console.log(demo.blocks.length);                  // Total block count
-console.log(demo.initialBlock.dataBlocks.size);   // DataBlock definitions
+console.log(demo.header.demoLengthMs); // Duration in ms
+console.log(demo.initialBlock.missionName); // e.g. "Rollercoaster"
+console.log(demo.blocks.length); // Total block count
+console.log(demo.initialBlock.dataBlocks.size); // DataBlock definitions
 
 const timeline = buildTimeline(demo, parser.getRegistry());
-console.log(timeline.controlObject.length);       // Player position keyframes
-console.log(timeline.ghostInstances.length);      // Networked object lifecycles
+console.log(timeline.controlObject.length); // Player position keyframes
+console.log(timeline.ghostInstances.length); // Networked object lifecycles
 ```
 
 ## CLI
@@ -124,21 +126,21 @@ interface DemoFile {
 
 #### Properties
 
-| Property | Type | Description |
-|---|---|---|
-| `loaded` | `boolean` | Whether `load()` has been called. |
-| `header` | `DemoHeader` | File header (throws if not loaded). |
-| `initialBlock` | `InitialBlockData` | Initial game state (throws if not loaded). |
-| `blockCount` | `number` | Total blocks in the stream. Lazily computed on first access by scanning the decompressed buffer. |
-| `blockCursor` | `number` | Number of blocks consumed so far. |
+| Property       | Type               | Description                                                                                      |
+| -------------- | ------------------ | ------------------------------------------------------------------------------------------------ |
+| `loaded`       | `boolean`          | Whether `load()` has been called.                                                                |
+| `header`       | `DemoHeader`       | File header (throws if not loaded).                                                              |
+| `initialBlock` | `InitialBlockData` | Initial game state (throws if not loaded).                                                       |
+| `blockCount`   | `number`           | Total blocks in the stream. Lazily computed on first access by scanning the decompressed buffer. |
+| `blockCursor`  | `number`           | Number of blocks consumed so far.                                                                |
 
 #### Accessors
 
-| Method | Returns | Description |
-|---|---|---|
-| `getRegistry()` | `ClassRegistry` | Parser registry with all bindings. |
-| `getGhostTracker()` | `GhostTracker` | Current ghost state (mutated by `nextBlock()`). |
-| `getPacketParser()` | `PacketParser` | Packet parser with parse statistics. |
+| Method              | Returns         | Description                                     |
+| ------------------- | --------------- | ----------------------------------------------- |
+| `getRegistry()`     | `ClassRegistry` | Parser registry with all bindings.              |
+| `getGhostTracker()` | `GhostTracker`  | Current ghost state (mutated by `nextBlock()`). |
+| `getPacketParser()` | `PacketParser`  | Packet parser with parse statistics.            |
 
 ---
 
@@ -146,10 +148,10 @@ interface DemoFile {
 
 ```typescript
 interface DemoHeader {
-  identString: string;        // "Tribes2 Recording"
-  protocolVersion: number;    // 0x330004
-  demoLengthMs: number;       // Total recording duration in milliseconds
-  initialBlockSize: number;   // Byte size of the initial block
+  identString: string; // "Tribes2 Recording"
+  protocolVersion: number; // 0x330004
+  demoLengthMs: number; // Total recording duration in milliseconds
+  initialBlockSize: number; // Byte size of the initial block
 }
 ```
 
@@ -162,7 +164,7 @@ Snapshot of the game state at the moment recording started.
 ```typescript
 interface InitialBlockData {
   // DataBlocks (static game definitions)
-  dataBlocks: Map<number, ParsedDataBlock>;   // objectId → parsed DataBlock
+  dataBlocks: Map<number, ParsedDataBlock>; // objectId → parsed DataBlock
   dataBlockCount: number;
   dataBlockHeaders: DataBlockHeader[];
 
@@ -181,8 +183,11 @@ interface InitialBlockData {
   initialEvents: NetEventInfo[];
 
   // Control object (the recording player)
-  controlObjectGhostIndex: number;    // -1 if none
+  controlObjectGhostIndex: number; // -1 if none
   controlObjectData?: Record<string, unknown>;
+  // Compression point established by the control object's state (its
+  // position), seeding compressed-point decodes in the first packets.
+  initialCompressionPoint?: { x: number; y: number; z: number };
   firstPerson: boolean;
 
   // Mission info
@@ -215,10 +220,10 @@ A single block from the compressed block stream.
 ```typescript
 interface DemoBlock {
   index: number;
-  type: number;       // BlockTypePacket (0), BlockTypeSendPacket (1),
-                      // BlockTypeMove (2), or BlockTypeInfo (3)
-  size: number;       // Payload size in bytes
-  data: Uint8Array;   // Raw payload
+  type: number; // BlockTypePacket (0), BlockTypeSendPacket (1),
+  // BlockTypeMove (2), or BlockTypeInfo (3)
+  size: number; // Payload size in bytes
+  data: Uint8Array; // Raw payload
   parsed?: PacketData | Move | InfoBlock;
 }
 ```
@@ -251,6 +256,8 @@ interface GameState {
   pinged: boolean;
   jammed: boolean;
   controlObjectGhostIndex?: number;
+  controlObjectDataStart?: number; // Bit offsets of the control object
+  controlObjectDataEnd?: number; // update within the packet
   controlObjectData?: Record<string, unknown>;
   compressionPoint?: { x: number; y: number; z: number };
   cameraFov?: number;
@@ -273,12 +280,12 @@ A create, update, or delete operation on a ghost object.
 
 ```typescript
 interface GhostUpdate {
-  index: number;                          // Ghost slot (0–1023)
+  index: number; // Ghost slot (0–1023)
   type: "create" | "update" | "delete";
-  classId?: number;                       // Set on create
+  classId?: number; // Set on create
   updateBitsStart: number;
   updateBitsEnd: number;
-  parsedData?: Record<string, unknown>;   // Class-specific parsed fields
+  parsedData?: Record<string, unknown>; // Class-specific parsed fields
 }
 ```
 
@@ -290,10 +297,13 @@ A network event received from the server.
 interface NetEventInfo {
   classId: number;
   guaranteed: boolean;
-  sequenceNumber?: number;
+  sequenceNumber?: number; // 7-bit wire sequence (guaranteed events)
+  absoluteSequenceNumber?: number; // Unwrapped full sequence
   dataBitsStart: number;
   dataBitsEnd: number;
   parsedData?: Record<string, unknown>;
+  failed?: boolean; // Event could not be parsed; stream
+  // position after it is unreliable
 }
 ```
 
@@ -305,14 +315,24 @@ Raw 64-byte player input struct (from type 2 blocks).
 
 ```typescript
 interface Move {
-  x: number; y: number; z: number;           // Acceleration
-  yaw: number; pitch: number; roll: number;   // Rotation
-  px: number; py: number; pz: number;         // Previous acceleration
-  pyaw: number; ppitch: number; proll: number;
+  x: number;
+  y: number;
+  z: number; // Movement input per axis (float)
+  yaw: number;
+  pitch: number;
+  roll: number; // Rotation deltas in radians
+  // (server adds them each tick)
+  px: number;
+  py: number;
+  pz: number; // Packed integer forms of x/y/z
+  pyaw: number;
+  ppitch: number;
+  proll: number; // Packed rotation: fractional
+  // turns × 65536 (16-bit range)
   id: number;
   sendCount: number;
   freeLook: boolean;
-  trigger: boolean[];   // 6 trigger keys (fire, jet, jump, etc.)
+  trigger: boolean[]; // 6 trigger keys (fire, jet, jump, etc.)
 }
 ```
 
@@ -325,9 +345,9 @@ A static game object definition parsed from the initial block.
 ```typescript
 interface ParsedDataBlock {
   classId: number;
-  className: string;      // e.g. "PlayerData", "WheeledVehicleData"
+  className: string; // e.g. "PlayerData", "WheeledVehicleData"
   objectId: number;
-  data: Record<string, unknown>;  // Class-specific fields (shapeName, etc.)
+  data: Record<string, unknown>; // Class-specific fields (shapeName, etc.)
 }
 ```
 
@@ -375,7 +395,11 @@ with position data are included.
 interface ExportTimeline {
   durationMs: number;
   tickIntervalMs: number;
-  controlObject: { t: number; p?: [number, number, number]; v?: [number, number, number] }[];
+  controlObject: {
+    t: number;
+    p?: [number, number, number];
+    v?: [number, number, number];
+  }[];
   ghosts: ExportGhostInstance[];
   events: GameEvent[];
 }
@@ -439,22 +463,40 @@ interface ControlObjectKeyframe {
 
 Available via `parser.getPacketParser()`. Exposes parse statistics.
 
-| Property | Type | Description |
-|---|---|---|
-| `packetsParsed` | `number` | Total packets successfully parsed. |
-| `ghostCreatesParsed` | `number` | Ghost create operations parsed. |
-| `ghostUpdatesParsed` | `number` | Ghost update operations parsed. |
-| `ghostDeletes` | `number` | Ghost delete operations. |
-| `ghostsFailed` | `number` | Ghost operations that failed to parse. |
-| `ghostsTrackerDiverged` | `number` | Ghost tracker inconsistencies detected. |
-| `eventsParsed` | `number` | Events parsed. |
-| `eventsFailed` | `number` | Events that failed to parse. |
-| `controlObjectParsed` | `number` | Control object updates parsed. |
-| `controlObjectFailed` | `number` | Control object updates that failed. |
+| Property                | Type     | Description                                                     |
+| ----------------------- | -------- | --------------------------------------------------------------- |
+| `packetsParsed`         | `number` | Total packets successfully parsed.                              |
+| `ghostCreatesParsed`    | `number` | Ghost create operations parsed.                                 |
+| `ghostUpdatesParsed`    | `number` | Ghost update operations parsed.                                 |
+| `ghostDeletes`          | `number` | Ghost delete operations.                                        |
+| `ghostsFailed`          | `number` | Ghost operations that failed to parse.                          |
+| `ghostsTrackerDiverged` | `number` | Ghost tracker inconsistencies detected.                         |
+| `eventsParsed`          | `number` | Events parsed.                                                  |
+| `eventsFailed`          | `number` | Events that failed to parse.                                    |
+| `controlObjectParsed`   | `number` | Control object updates parsed.                                  |
+| `controlObjectFailed`   | `number` | Control object updates that failed.                             |
+| `protocolRejected`      | `number` | Packets rejected by the dnet protocol window.                   |
+| `protocolNoDispatch`    | `number` | Packets accepted but not dispatched (duplicates/out-of-window). |
+
+#### State export (for seeding another parser)
+
+These getters capture **all cross-packet parser state**, so a second parser
+seeded with the same values (plus the ghost tracker contents and datablock
+map) continues the stream in bit-lockstep with this one — the basis for
+late-joiner catch-up in live streaming.
+
+| Method                              | Returns                                          |
+| ----------------------------------- | ------------------------------------------------ |
+| `getConnectionProtocolState()`      | `ConnectionProtocolState` (dnet sequence window) |
+| `getNextRecvEventSeq()`             | `number`                                         |
+| `getPendingGuaranteedEvents()`      | Out-of-order guaranteed events awaiting dispatch |
+| `getCompressionPoint()`             | `{ x, y, z }`                                    |
+| `getDataBlockDataMap()`             | `Map<number, ParsedData> \| undefined`           |
+| `setConnectionProtocolState(state)` | — (also a constructor option)                    |
 
 ---
 
-### `createLiveParser(): LiveParserKit`
+### `createLiveParser(seed?): LiveParserKit`
 
 Create a parser stack for live server connections. Sets up the same deterministic
 registry bindings as `DemoParser` but without requiring a `.rec` file. Useful for
@@ -475,6 +517,69 @@ interface LiveParserKit {
 }
 ```
 
+With a **seed**, the stack resumes an in-progress stream from another
+parser's exported state, continuing at a packet boundary in bit-lockstep
+with the exporter (the late-joiner catch-up scenario — see
+`GhostStateAccumulator` below for producing the ghost seeds):
+
+```typescript
+interface LiveParserSeed {
+  dataBlocks?: Iterable<[number, ParsedData]>; // objectId → parsed datablock
+  ghosts?: Iterable<{ index: number; classId: number }>;
+  connectionProtocolState?: ConnectionProtocolState;
+  nextRecvEventSeq?: number;
+  compressionPoint?: { x: number; y: number; z: number };
+  pendingGuaranteedEvents?: Array<{
+    absoluteSequenceNumber: number;
+    event: NetEventInfo;
+  }>;
+}
+```
+
+### `passiveObserverProtocolState(firstPacketByte): ConnectionProtocolState`
+
+Protocol state for a parser that passively observes the server→client
+stream while something else (e.g. a relay) owns the client→server side.
+Sets `lastSendSeq` high so ack validation never rejects packets that ack
+sequences the observer didn't send. Intended for the first packets of a
+connection; to attach mid-stream, seed `connectionProtocolState` from the
+exporting parser instead.
+
+```typescript
+import { createLiveParser, passiveObserverProtocolState } from "t2-demo-parser";
+
+const { packetParser } = createLiveParser();
+// On the first received packet:
+packetParser.setConnectionProtocolState(passiveObserverProtocolState(data[0]));
+```
+
+---
+
+### `GhostStateAccumulator`
+
+Maintains one merged full `parsedData` per live ghost by folding each
+packet's creates/updates/deletes (plus `GhostAlwaysObjectEvent` creates and
+EndGhosting clears). `toInitialGhosts()` yields entries shaped like a demo
+recording's `initialGhosts` — the full-state ghost list a `.rec` starts
+with when recorded mid-match — for hydrating a late joiner.
+
+```typescript
+import { GhostStateAccumulator, mergeGhostParsedData } from "t2-demo-parser";
+
+const accumulator = new GhostStateAccumulator();
+// After each parsed packet:
+accumulator.applyPacket(packetData);
+
+accumulator.toInitialGhosts(); // GhostUpdate[] with full merged parsedData
+accumulator.getGhostSeeds(); // { index, classId }[] for createLiveParser
+accumulator.size();
+accumulator.clear();
+```
+
+`mergeGhostParsedData(base, update)` is the underlying merge rule: arrays
+whose entries carry a numeric `index` (threads, images, sounds) merge
+sparsely by index; other values are last-write-wins.
+
 ---
 
 ### `BitStream`
@@ -500,9 +605,9 @@ Tracks the live state of all ghost objects. Available via
 
 ```typescript
 const tracker = parser.getGhostTracker();
-const ghost = tracker.getGhost(index);  // GhostEntry | undefined
-const all = tracker.getAllGhosts();      // Map<number, GhostEntry>
-tracker.size();                          // Number of active ghosts
+const ghost = tracker.getGhost(index); // GhostEntry | undefined
+const all = tracker.getAllGhosts(); // Map<number, GhostEntry>
+tracker.size(); // Number of active ghosts
 ```
 
 ```typescript
@@ -521,10 +626,10 @@ Block type constants for filtering `DemoBlock.type`:
 
 ```typescript
 import {
-  BlockTypePacket,       // 0 — network packet
-  BlockTypeSendPacket,   // 1 — send-packet trigger (no data)
-  BlockTypeMove,         // 2 — 64-byte player input
-  BlockTypeInfo,         // 3 — 8-byte timing/FOV
+  BlockTypePacket, // 0 — network packet
+  BlockTypeSendPacket, // 1 — send-packet trigger (no data)
+  BlockTypeMove, // 2 — 64-byte player input
+  BlockTypeInfo, // 3 — 8-byte timing/FOV
 } from "t2-demo-parser";
 ```
 
@@ -532,20 +637,22 @@ Network protocol constants are also exported:
 
 ```typescript
 import {
-  MaxGhostCount,            // 1024
-  GhostIdBitSize,           // 10
+  MaxGhostCount, // 1024
+  GhostIdBitSize, // 10
   NetStringTableMaxStrings, // 4096
-  StringIdBitSize,          // 12
-  NetEventClassBitSize,     // 6
-  NetEventClassFirst,       // 255
-  NetObjectClassBitSize,    // 7
-  NetObjectClassFirst,      // 0
-  MaxPacketDataSize,        // 1500
-  MaxTriggerKeys,           // 6
-  DataBlockObjectIdFirst,   // 3
+  StringIdBitSize, // 12
+  NetEventClassBitSize, // 6
+  NetEventClassFirst, // 255
+  NetObjectClassBitSize, // 7
+  NetObjectClassFirst, // 0
+  MaxPacketDataSize, // 1500
+  MaxTriggerKeys, // 6
+  MoveCountBits, // 5
+  MaxMoveCount, // 30
+  DataBlockObjectIdFirst, // 3
   DataBlockObjectIdBitSize, // 10
-  DataBlockClassFirst,      // 128
-  DataBlockClassBitSize,    // 7
+  DataBlockClassFirst, // 128
+  DataBlockClassBitSize, // 7
 } from "t2-demo-parser";
 ```
 
@@ -554,9 +661,9 @@ assignment order):
 
 ```typescript
 import {
-  NetObjectClassNames,   // 53 ghost class names
-  DataBlockClassNames,   // 54 DataBlock class names
-  NetEventClassNames,    // 26 event class names
+  NetObjectClassNames, // 53 ghost class names
+  DataBlockClassNames, // 54 DataBlock class names
+  NetEventClassNames, // 26 event class names
 } from "t2-demo-parser";
 ```
 
@@ -576,11 +683,14 @@ const { header, initialBlock } = await parser.load();
 
 // Duration
 const durationMs = header.demoLengthMs;
-const durationStr = `${Math.floor(durationMs / 60000)}m${
-  Math.floor((durationMs % 60000) / 1000).toString().padStart(2, "0")}s`;
+const durationStr = `${Math.floor(durationMs / 60000)}m${Math.floor(
+  (durationMs % 60000) / 1000,
+)
+  .toString()
+  .padStart(2, "0")}s`;
 
 // Mission / map name
-const mission = initialBlock.missionName;  // e.g. "Rollercoaster"
+const mission = initialBlock.missionName; // e.g. "Rollercoaster"
 
 // Game mode / mission type — look in DemoValues
 // $DemoValue_0 is typically the game mode (e.g. "CTFGame")
@@ -588,7 +698,9 @@ const gameMode = initialBlock.demoValues[0];
 
 // Teams and players
 for (const score of initialBlock.scoreEntries) {
-  console.log(`Team ${score.teamId}: client ${score.clientId}, score ${score.score}`);
+  console.log(
+    `Team ${score.teamId}: client ${score.clientId}, score ${score.score}`,
+  );
 }
 
 // Player names from the target table
@@ -650,10 +762,10 @@ function seekTo(targetMs: number) {
     if (block.type === BlockTypeMove) moveCount++;
     if (moveCount * 32 >= targetMs) break;
   }
-  return moveCount * 32;  // Actual time reached
+  return moveCount * 32; // Actual time reached
 }
 
-const actualMs = seekTo(60000);  // Seek to ~1 minute
+const actualMs = seekTo(60000); // Seek to ~1 minute
 // Ghost tracker now reflects state at that point.
 // Continue calling nextBlock() to play forward from here.
 ```
@@ -680,7 +792,9 @@ console.log(`${stats.ghostsWithPosition} with position data`);
 
 // Iterate ghost lifecycles
 for (const inst of timeline.ghostInstances) {
-  console.log(`${inst.className} #${inst.ghostIndex}: ${inst.keyframes.length} keyframes`);
+  console.log(
+    `${inst.className} #${inst.ghostIndex}: ${inst.keyframes.length} keyframes`,
+  );
   for (const kf of inst.keyframes) {
     if (kf.position) {
       // Feed into Three.js KeyframeTrack...
@@ -713,7 +827,7 @@ parser.reset();
 while (parser.nextBlock()) {}
 const stats2 = parser.getPacketParser().packetsParsed;
 
-console.log(stats1 === stats2);  // true
+console.log(stats1 === stats2); // true
 ```
 
 ### Access parse statistics
@@ -747,7 +861,7 @@ const registry = parser.getRegistry();
 // From a ghost update in a packet:
 if (ghost.type === "create" && ghost.classId !== undefined) {
   const entry = registry.getGhostParser(ghost.classId);
-  console.log(entry?.name);  // e.g. "Player", "Turret", "LinearProjectile"
+  console.log(entry?.name); // e.g. "Player", "Turret", "LinearProjectile"
 }
 
 // From the ghost tracker (live state):

package/dist/DataBlockParsers.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"DataBlockParsers.d.ts","sourceRoot":"","sources":["../src/DataBlockParsers.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AA0uExD,wBAAgB,wBAAwB,CAAC,QAAQ,EAAE,aAAa,GAAG,IAAI,CA2NtE"}
+{"version":3,"file":"DataBlockParsers.d.ts","sourceRoot":"","sources":["../src/DataBlockParsers.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAkvExD,wBAAgB,wBAAwB,CAAC,QAAQ,EAAE,aAAa,GAAG,IAAI,CA2NtE"}

package/dist/DataBlockParsers.js

@@ -440,23 +440,25 @@ function playerDataUnpack(bs) {
         splashEmitters.push(readDataBlockRef(bs));
     }
     result.splashEmitters = splashEmitters;
-    // 17. 11× F32 for ground impact shake (offsets 0x3fc-0x424)
-    // V12 has 9 fields; binary has 11 (2 extra Tribes 2-specific)
-    result.groundImpactMinSpeed = bs.readF32(); // 0x3fc
+    // 17. 11× F32 (offsets 0x3fc-0x424). Names binary-verified against
+    // initPersistFields: the two leading fields are the Tribes 2 heat
+    // signature rates (retail player.cs: 1/4 and 1/3), then the ground
+    // impact shake block. Demo values confirm: 0.25, 0.333…
+    result.heatDecayPerSec = bs.readF32(); // 0x3fc
+    result.heatIncreasePerSec = bs.readF32(); // 0x400
+    result.groundImpactMinSpeed = bs.readF32(); // 0x404
     result.groundImpactShakeFreq = {
-        x: bs.readF32(), // 0x400
-        y: bs.readF32(), // 0x404
-        z: bs.readF32(), // 0x408
+        x: bs.readF32(), // 0x408
+        y: bs.readF32(), // 0x40c
+        z: bs.readF32(), // 0x410
     };
     result.groundImpactShakeAmp = {
-        x: bs.readF32(), // 0x40c
-        y: bs.readF32(), // 0x410
-        z: bs.readF32(), // 0x414
+        x: bs.readF32(), // 0x414
+        y: bs.readF32(), // 0x418
+        z: bs.readF32(), // 0x41c
     };
-    result.groundImpactShakeDuration = bs.readF32(); // 0x418
-    result.groundImpactShakeFalloff = bs.readF32(); // 0x41c
-    result.boundingRadius = bs.readF32(); // 0x420 (Tribes 2 extra)
-    result.moveBubbleSize = bs.readF32(); // 0x424 (Tribes 2 extra)
+    result.groundImpactShakeDuration = bs.readF32(); // 0x420
+    result.groundImpactShakeFalloff = bs.readF32(); // 0x424
     return result;
 }
 // ============================================================
@@ -479,6 +481,8 @@ function vehicleDataUnpack(bs) {
     result.softImpactSpeed = bs.readF32(); // 0x380
     result.hardImpactSpeed = bs.readF32(); // 0x384 (900 dec)
     result.minRollSpeed = bs.readF32(); // 0x388
+    // Registered in the retail binary as "maxSteerinAngle" (engine typo);
+    // we keep the corrected spelling.
     result.maxSteeringAngle = bs.readF32(); // 0x38c
     result.maxDrag = bs.readF32(); // 0x3a4
     result.minDrag = bs.readF32(); // 0x3a0
@@ -1222,9 +1226,10 @@ function debrisDataUnpack(bs) {
     result.gravModifier = bs.readF32(); // 0x78
     result.terminalVelocity = bs.readF32(); // 0x7c
     result.ignoreWater = readBool(bs); // 0x80 (8-bit bool)
-    // 2 readString
-    result.shapeFileName = bs.readString(); // 0x8c
-    result.skinName = bs.readString(); // 0x84
+    // 2 readString — names binary-verified: 0x8c is registered as
+    // `texture`, 0x84 as `shapeName` (read in that wire order)
+    result.texture = bs.readString(); // 0x8c
+    result.shapeName = bs.readString(); // 0x84
     // 2 emitter refs (loop at 0xa4, 0xa8) + 1 explosion ref (0x94)
     result.emitter0 = readDataBlockRef(bs);
     result.emitter1 = readDataBlockRef(bs);
@@ -1502,15 +1507,17 @@ function audioEnvironmentUnpack(bs) {
         result.reflectionsDelay = readRangedF32(bs, 0, 0.3, 9); // 0x5c
         result.reverbDelay = readRangedF32(bs, 0, 0.1, 7); // 0x60
         result.roomVolume = readRangedS32(bs, -10000, 0); // 0x64
-        result.effectVolume = readRangedF32(bs, 0, 1, 9); // 0x6c (9 bits, confirmed in binary)
-        result.damping = readRangedF32(bs, 0, 2, 10); // 0x70 (10 bits, confirmed in binary)
-        result.environmentSize = readRangedF32(bs, 1, 100, 8); // 0x74 (8 bits, confirmed in binary)
-        result.environmentDiffusion = readRangedF32(bs, 0, 1, 10); // 0x78 (10 bits, confirmed in binary)
-        // NOTE: No airAbsorption field in binary (V12 has it, Tribes 2 binary does not)
+        // Names binary-verified: initPersistFields maps 0x6c damping,
+        // 0x70 environmentSize, 0x74 environmentDiffusion, 0x78 airAbsorption.
+        result.damping = readRangedF32(bs, 0, 1, 9); // 0x6c (9 bits, confirmed in binary)
+        result.environmentSize = readRangedF32(bs, 0, 2, 10); // 0x70 (10 bits, confirmed in binary)
+        result.environmentDiffusion = readRangedF32(bs, 1, 100, 8); // 0x74 (8 bits, confirmed in binary)
+        result.airAbsorption = readRangedF32(bs, 0, 1, 10); // 0x78 (10 bits, confirmed in binary)
         result.flags = bs.readInt(6); // 0x7c
     }
-    // Trailing field: always present after both branches (binary line 23471, offset 0x68)
-    result.effectVolumeHF = readRangedF32(bs, 0, 1, 8);
+    // Trailing field: always present after both branches (offset 0x68 =
+    // effectVolume per initPersistFields)
+    result.effectVolume = readRangedF32(bs, 0, 1, 8);
     return result;
 }
 // ============================================================
@@ -1697,20 +1704,22 @@ function stationFXVehicleDataUnpack(bs) {
         y: bs.readF32(), // 0x90
         z: bs.readF32(), // 0x94
     };
-    // 11 strings
-    result.glowTexture = bs.readString(); // 0x98
-    // 4×(2 readString) — pad textures
-    result.padTexture00 = bs.readString();
-    result.padTexture01 = bs.readString();
-    result.padTexture10 = bs.readString();
-    result.padTexture11 = bs.readString();
-    result.padTexture20 = bs.readString();
-    result.padTexture21 = bs.readString();
-    result.padTexture30 = bs.readString();
-    result.padTexture31 = bs.readString();
+    // 11 strings — names binary-verified (initPersistFields: 0x98
+    // glowNodeName, 0x9c leftNodeName[4], 0xac rightNodeName[4], 0xbc
+    // texture[2]) and demo-verified ("GLOWFX", LFX1/RFX1…, stationGlow).
+    result.glowNodeName = bs.readString(); // 0x98
+    // 4×(left, right) node name pairs, interleaved on the wire
+    result.leftNodeName0 = bs.readString();
+    result.rightNodeName0 = bs.readString();
+    result.leftNodeName1 = bs.readString();
+    result.rightNodeName1 = bs.readString();
+    result.leftNodeName2 = bs.readString();
+    result.rightNodeName2 = bs.readString();
+    result.leftNodeName3 = bs.readString();
+    result.rightNodeName3 = bs.readString();
     // 2 readString
-    result.lightStartColor = bs.readString();
-    result.lightEndColor = bs.readString();
+    result.texture0 = bs.readString();
+    result.texture1 = bs.readString();
     return result;
 }
 // ============================================================
@@ -1729,12 +1738,12 @@ function stationFXPersonalDataUnpack(bs) {
     result.bottomAlpha = bs.readF32();
     result.glowSpeed = bs.readF32();
     result.scrollSpeed = bs.readF32();
-    // 2 readString
-    result.glowTexture = bs.readString();
-    result.padTexture = bs.readString();
-    // 2 readString
-    result.lightStartColor = bs.readString();
-    result.lightEndColor = bs.readString();
+    // 4 strings — demo-verified ("FX1", "FX2", "special/stationLight"):
+    // the two attach node names, then texture[2]
+    result.leftNodeName = bs.readString();
+    result.rightNodeName = bs.readString();
+    result.texture0 = bs.readString();
+    result.texture1 = bs.readString();
     return result;
 }
 // ============================================================