arcattackandClaude Fable 5
6bb03aed0b
The conviction was empirical, not theoretical: a new write-site trap
(BT_PLANE_AUDIT) in the seven L4VB16 drawing primitives logs any draw whose
color carries bits outside its port's plane mask -- the exact cross-display
corruption condition (Replace ORs an unmasked color; Or/Xor ignore the mask
entirely; And clears foreign planes). A quiet solo session produced 15-30
leaks per minute:
[plane] PORT 'sec' pixmap draw at(0,0) idx 217 entry=0xffffff00 mask=0x3f
[plane] LEAK DrawPixelMap8[table] at(639,0) color=0xffffff00 mask=0x3f leak=0xff00
THE DEFECT: L4GraphicsPort::translationTable[256] is never initialized in the
ctor, and BuildSecondaryTranslation fills only the entries its BitWrangler
reaches -- 2^numberOfBits: 64 for the sec plane (mask 0x3F), 4 for the overlay
(0xC0). Entries above that stay heap garbage. Every draw resolves color
through this table, and the PIXMAP path indexes it with raw pixel values
0..255: the 480x640 radar background carries pixel index 217, whose garbage
entry's high bits (0xFF00 = ALL EIGHT MFD planes) were stamped into the shared
640x480 buffer -- invisible on the culprit page (the in-plane bits happened
dark) and visible as bright fragments at the same coordinates on every OTHER
display. That is the operator's screenshot exactly: the same-position blips
on Mfd1+Mfd2 and the Heat-display block.
FIX (engine, both layers):
* zero translationTable in the L4GraphicsPort ctor (plane-neutral default);
* BuildSecondaryTranslation now cycles the in-plane pattern across entries
[2^bits..255] -- high-index art degrades to its (index mod 2^bits) colour
IN-PLANE and can never leak. The 1995 binary ships the SAME 64-entry fill
and survived on 6-bit art discipline; garbage is not a preservable
behaviour, so the cycle-fill is a guarded PORT deviation (documented).
A/B PROOF: same probe, 60s -- 0 leaks after the fix (15-30/min before).
sim3 3-pod regression: zero crashes.
SECOND real defect found + fixed en route: sessions configure the CAMERA seat
first ("cameraInit" -- which includes the MISSION-REVIEW context:
configure(0, sec, 0, 0x00FF, native, rgb, mrpal.pcc), a DirectColor context
whose translation tables legitimately hold full RGB565 values spanning all 16
plane bits), and the viewpoint swap to the mech re-configured WITHOUT tearing
that tree down (btl4app's s_gaugeTreeBuilt latch treats the mech build as the
first). The orphaned review gauges kept executing through stale DirectColor
ports. BTL4GaugeRenderer::ConfigureForModel now overrides (ConfigureForModel
made virtual in L4GREND.h) and tears the prior entity-bound tree down before
every rebuild -- safe on first build, and the review screen rebuilds the same
way when the seat returns to the camera.
Also logged (open-questions): the review-screen PlayerStatus panels read the
compiled player at RAW BINARY OFFSETS (+0x1FC vehicle / +0x1C8 score /
+0x1C4 alive-dead box) -- the databinding trap, dormant until the review
screen runs; bridge before enabling the review.
Ruled out along the way (with evidence): the pilot-list label/erase geometry
(erase box 128x32 covers the 64x16 name rasters), the radar name labels
(view-level ClipImage clips them), PlayerStatus in-game execution ([ps] probe:
never runs in-game), and the PNAME bitmap dimensions (egg generator emits
64x16 exactly).
Why it "started with the comms feature" (#43): that wave registered the new
gauge classes with the config interpreter, letting more of the authored page
furniture parse and draw than before -- the leaking high-index pixmaps rode in
with it. [T3 correlation detail; the leak + fix are T2 live-verified.]
Diagnostics kept (env-gated): BT_PLANE_AUDIT (the leak trap, now a permanent
regression tripwire), BT_PS_LOG, the port-level pixmap identity trap.
KB: gauges-hud.md (#48 section), decomp-reference.md (BT_PLANE_AUDIT),
open-questions.md (PlayerStatus databinding entry). checkctx CLEAN.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
BattleTech 4.11 (bt411)
A standalone Windows port of Virtual World Entertainment's arcade BattleTech (Tesla platform, release 4.10, ~1995–96), reconstructed on the shared RP411 Windows engine. The game boots, renders, and runs a single-player drive → animate → target → fire → damage → destroy loop across all 8 maps, with two-instance multiplayer entity replication working.
This repo is a clean, self-contained extraction of the BattleTech-specific work from the larger reverse-engineering workspace — engine + game + content + build, with nothing from Red Planet or the raw archive dumps. It builds and runs out of the box.
License: the game content (
content/) and the original binary are proprietary to Virtual World / the pod owner. This repository is private; do not redistribute.
Versioning
4.10 = the 1995 arcade release. 4.11 = this win32 reconstruction. Dev builds are
4.11.<build> where <build> is the git commit count — monotonic and zero-maintenance —
plus the short commit hash (4.11.311 (980c9cd)); a trailing + on the hash means the exe was
built from an uncommitted working tree. The stamp regenerates every build
(tools/btversion.cmake → build/btversion.h) and shows in the boot banner (btl4.log line 2)
and the window title. To identify any player's build, ask for the title bar or the top of their
btl4.log.
Layout
CMakeLists.txt one build: munga_engine lib + bt410_l4 game lib + btl4.exe
engine/
MUNGA/ shared 2007 sim/render engine (149 .cpp + headers)
MUNGA_L4/ Win32/D3D9 HAL + renderer + asset loaders (44 .cpp), incl.
our BT work: bgfload / L4D3D / L4VIDEO + the image codec
shim/ minimal ATL shim (USES_CONVERSION/W2A)
lib/ OpenAL32 / libsndfile import libs + runtime DLLs
game/
reconstructed/ the reconstructed BT game logic (mech, subsystems, HUD, app; ~47 .cpp)
original/BT,BT_L4 surviving original BT source + all BT headers
fwd/ header shims forwarding <NAME.hpp> -> the engine's NAME.h
btl4main.cpp WinMain launcher / entry point
content/ runtime data: BTL4.RES, VIDEO/, GAUGE/, AUDIO/, *.EGG, BTDPL.INI
context/ progressive knowledge graph — 18 on-demand topic files (routed by CLAUDE.md)
docs/ format specs + reconstruction ledgers + PROGRESS_LOG.md (full history)
reference/
decomp/ raw Ghidra pseudocode — source-of-truth for ongoing recon
ghidra_scripts/ the headless decomp exporter
glossary.yaml term / acronym definitions
phases/ restructuring / investigation logs
tools/ btconsole.py (MP console emulator), map/resource scanners
run/ run.cmd helper
CLAUDE.md knowledge-base ROUTER — identity, protocols, quick-lookup, conventions
Prerequisites
- Visual Studio 2019 BuildTools (MSVC v142, x86). The Community install on the original dev box was broken, hence the explicit BuildTools instance in the configure line below; adjust to your install.
- CMake ≥ 3.20.
- Legacy DirectX SDK (June 2010) — the engine uses
d3dx9/dinput/dxerr, removed from the modern Windows SDK. Default pathC:/Program Files (x86)/Microsoft DirectX SDK (June 2010); override with-DDXSDK=<path>. (The installer may throw a harmless S1023 error — dismiss it; the SDK headers/libs install before the failing redist step.)
OpenAL/libsndfile import libs + DLLs are vendored under engine/lib/; the DLLs are copied next to
the exe automatically at build time.
Build (32-bit / Win32)
cmake -S . -B build -G "Visual Studio 16 2019" -A Win32 ^
-DCMAKE_GENERATOR_INSTANCE="C:/Program Files (x86)/Microsoft Visual Studio/2019/BuildTools"
cmake --build build --config Debug
Must be Win32 — the DirectX SDK link libs are Lib/x86. The link uses /FORCE: the 1995
headers define free functions/globals without inline/extern, so identical symbols appear in
many translation units (~124 LNK2005); /FORCE:MULTIPLE keeps the first. UNRESOLVED tolerates
a dead offline-tool factory in mech3.cpp that is never called at runtime. (Cleanup task: move
those definitions to single TUs + neutralize the dead factory, then drop /FORCE.)
Run
run\run.cmd REM boots DEV.EGG (grass / day)
run\run.cmd DBASE.EGG REM any egg in content/
The working directory must be content/ (the engine resolves BTL4.RES, VIDEO\,
BTDPL.INI, and eggs relative to cwd); run.cmd handles that. Maps available in BTL4.RES:
cavern grass rav polar3 polar4 arena1 arena2 dbase — switch via a copied egg's map= field.
Useful env-var flags (default OFF unless noted)
The authentic stack (gait, collision, real controls) is default-on; set =0 to fall back.
Debug/harness flags: BT_FORCE_THROTTLE=1 (auto-walk), BT_SPAWN_ENEMY=1 (spawn a target dummy),
BT_FORCE_FIRE=1 (auto-fire), BT_HEAPCHECK=1 (whole-heap validation — slow), BT_BSL=0 (legacy
texture decode), BT_DEV_GAUGES=1 (render the cockpit MFDs in a dev window), BT_LOG=<file>.
Interactive: WASD drive, A/D turn, Q/E torso twist, R/F torso pitch aim,
Space / 1-4 fire, X all-stop, V view, M control mode. An Xbox-type controller
works out of the box. All bindings are user-editable in content/CONTROLS.MAP (delete it to
restore the compiled-in WASD default; content/CONTROLS_NUMPAD.MAP is an alternate profile). The
complete env-gate table is in context/decomp-reference.md §6 (routed from CLAUDE.md);
controls/pad details in context/pod-hardware.md.
Multiplayer
Modern path (relay + operator console). Pods make ONE outbound connection to a relay/console, so internet play needs no per-player port forwarding and CGNAT-safe LAN discovery just works. Run the operator station:
python tools/btoperator.py # PySide6 GUI: build the mission egg (validated dropdowns),
# start the relay, watch pods arrive, assign seats, LAUNCH,
# end the timed mission, export player join.bat scripts
Players run one universal join.bat (internet, seat assigned by the relay) or join_lan.bat
(same LAN, auto-discovers the console) or play_solo.bat (offline practice) — see players/.
The pod waits patiently if the session isn't up yet. Full architecture, wire format, and the
D1 relay/UDP design: context/multiplayer.md.
Legacy mesh (two instances, one box), still supported:
instance A: btl4.exe -egg MP.EGG -net 1501 (BT_LOG=mp_a.log)
instance B: btl4.exe -net 1601 (BT_LOG=mp_b.log)
console: python tools/btconsole.py MP.EGG 127.0.0.1:1501 127.0.0.1:1601
-net <port> enables networked mode. Verified end-to-end: full entity/movement replication,
cross-pod combat + kills, per-pilot paint + callsigns, timed missions, 4-pod live sessions, and a
spectator/broadcast camera seat (hostType=1 vehicle=camera) with auto-directed coverage and
a live ranking window.
Status & continuing the work
The engine, renderer, audio, HAL, build, locomotion, collision, damage, render fidelity, the full
cockpit gauge / MFD system (every config binding resolves + every widget builds), and the
projectile / missile weapon families are done. Active fronts: per-subsystem polish (the gyroscope
integrator; the 0xBD3 message manager that gates the valve / status-message control routes) and
cross-pod MP combat. reference/decomp/ holds the raw pseudocode every reconstruction is verified
against.
Start with CLAUDE.md — it is the router into the progressive knowledge base: a quick-lookup
table pointing to the context/*.md topic files (loaded on demand), the evidence-tier and
convention rules, and context/open-questions.md for what's deferred / next. The complete
pre-restructure history is preserved verbatim in docs/PROGRESS_LOG.md; docs/*.md holds the
detailed running ledgers.