| # Keyed user-command codec |
|
|
| Scope: RE-393–395 / F-154–156. Evidence: verified disassembly and file-backed mask bytes from both Linux ELF64 engines, recorded in [message-usercmd.json](message-usercmd.json). Reproduce with `python3 scripts/analyze_message_usercmd.py`; verify with `python3 scripts/test_message_usercmd.py`. |
|
|
| ## CMD-001 — Timestamp dispatch and key derivation |
|
|
| `MSG_WriteDeltaUsercmdKey` subtracts baseline time from new time modulo 32 bits and compares the signed result with 255. Values at or below 255 emit a one-bit 1 followed by the low eight delta bits; greater values emit a one-bit 0 followed by the complete new 32-bit time. The reader adds an eight-bit delta to baseline time modulo 32 bits, or takes the full time. This is a signed comparison, not a verified requirement that deltas be nonnegative. |
|
|
| Synthetic -1 delta fixtures therefore decode baseline+255 rather than the supplied new timestamp. A wrap from 0xfffffffe to 1 produces delta 3 and recovers 1. These results describe instruction behavior; actual callers' monotonicity, reset and legal time ranges remain open. |
|
|
| After the timestamp, a one-bit aggregate flag controls the remaining fields. The writer derives the effective key from supplied key XOR **new** timestamp; the reader uses supplied key XOR **decoded** timestamp. Thus a synthetic short-time discrepancy can also change subsequent keyed fields. There are no calls to the scalar keyed-delta helpers in these graphs: field encoding is inlined through WriteBits/ReadBits. |
|
|
| Evidence anchors: writer entries dedicated `0x4422d2`, client `0x453c92`; signed delta comparisons `0x4422e9` / `0x453ca9`. Reader entries `0x44200c` / `0x4539cc`. |
|
|
| ## CMD-002 — Record layout, flags and narrowing |
|
|
| The observed record spans 24 bytes. Semantic labels below are inferred user-command interpretations; offsets, sizes and wire order come directly from native loads/stores and child requests. |
|
|
| | Record offset | Stored bytes | Inferred field | Changed payload bits | Wire order after aggregate flag | |
| | --- | --- | --- | --- | --- | |
| | 0 | 4 | server time | 8-bit delta or full 32-bit time | Before aggregate flag | |
| | 4 | 4 | angle 0 | 16 | 1 | |
| | 8 | 4 | angle 1 | 16 | 2 | |
| | 12 | 4 | angle 2 | 16 | 3 | |
| | 21 | 1 | forward movement | 8 | 4 | |
| | 22 | 1 | right movement | 8 | 5 | |
| | 23 | 1 | up movement | 8 | 6 | |
| | 16 | 4 | buttons | 16 | 7 | |
| | 20 | 1 | weapon | 8 | 8 | |
|
|
| Aggregate equality compares the full word fields, the three movement bytes and the weapon byte. A word load at +20 clears its low byte through XORB to compare movement separately from weapon. Each field then has its own one-bit flag. Equality emits only 0 and copies the complete stored baseline field during reading. Changes emit 1 and the low width bits of new value XOR effective key. Movement bytes are sign-extended before XOR; weapon is zero-extended. |
|
|
| The reader uses actual `kbitmask[8]=0x1ff` and `kbitmask[16]=0x1ffff`, consistent with [keyed scalar findings](MESSAGE_DELTA_KEY.md). The word fields store a full 32-bit result, preserving the extra key bit at bit 16. Changed movement/weapon results store only a byte, discarding bit 8. None of these field paths index mask32; the full timestamp is read directly without the keyed mask. For matching decoded/new timestamps, changed word output is `(new & 0xffff) | (effective_key & 0x10000)`; changed bytes recover the supplied byte. This alone does not establish which high key bits are reachable during gameplay. |
|
|
| File-backed masks: dedicated addresses `0x6cf620` / `0x6cf640`, client `0x7a4680` / `0x7a46a0` for widths 8 / 16. Source identities, mask symbol and file offsets are in the report. If the aggregate flag is zero, the reader retains the decoded timestamp and copies all remaining 20 baseline bytes. |
|
|
| ## CMD-003 — Bounded compressed compositions |
|
|
| Per engine, 102 streams cover deltas 0, 1, 255, 256 and -1; unchanged fields, each of eight individual field changes and all-field changes; keys 0 and 0x10100. Two additional wrap fixtures use keys 0 and 0xffffffff and start at bit 7. This is 204 streams total, using 18 verified graphs across the two images. |
|
|
| The script composes native usercmd, bit and Huffman instruction slices against relocated **MODEL-DERIVED** seeded trees. An independent test oracle builds the timestamp/aggregate/per-field requests, packs raw remainder bits and modeled codewords, and predicts the complete decoded record using separate writer/reader timestamp-derived keys. Checks cover exact bytes, final bit/size/readcount, unchanged source records, destination and buffer canaries, diagnostics and paired engine outcomes. |
|
|
| An unchanged command emits three requests (timestamp flag, timestamp payload, aggregate flag) and then adds seven directly to global `oldsize` (`0x44258a` / `0x453f4a`). A changed command emits eleven plus the number of changed fields. `oldsize` otherwise sums requested widths, rather than compressed lengths; XOR payloads and negative short deltas can increment the existing range diagnostic without setting message overflow in these ample-buffer fixtures. |
|
|
| The shared evaluator adds low-byte XORB support, preserving other register bytes and handling zero-flag dispatch. Its focused check exercises that instruction independently. |
|
|
| ## Remaining work and compatibility limits |
|
|
| No original executable or native callee runs. PUSH/POP and stack save/restores are omitted; synthetic frames and explicit caller-register restoration compose stopped child boundaries. Training remains model-derived, not a complete native seed run. The fixtures use ample initialized buffers and disjoint records. They do not validate truncated/EOF/overflow packets, overlapping pointers, caller key provenance/time invariants, real multiplayer traffic, or other platforms. |
|
|
| RE-392 remains open for broader keyed callers. RE-396 must trace actual usercmd callers and key provenance, confirm field semantics against QVM/native consumers, recover packet bundling/baselines and entity/player/snapshot field tables, establish legal high-key/timestamp behavior, and compare runtime captures before Rust codec compatibility decisions. Bevy/Solari rendering and macOS/Linux game execution remain separate open milestones. |
|
|
| Follow-up: [usercmd callers](USERCMD_CALLERS.md) recovers bounded outer key derivation, count/opcode gates and zero/previous command chains. Producer/time legality, complete packet composition and runtime validation remain open. |
|
|
