arcattackandClaude Opus 5
4736cba1ca
THE SYMPTOM: "after a game ends I push LAUNCH and nothing happens until I reset
the session entirely or reboot the console." The operator also observed the
mirror image, which is the tell: with a STABLE group, relaunching worked fine
several times in a row.
ROOT CAUSE. Two gates, both all-or-nothing, and a UI latch that agreed with
them:
* btconsole.py: the manual LAUNCH branch is guarded on `launches_sent == 0`,
but a finished mission leaves it at 2. The only paths back to 0 were
_check_launch_gate (needs EVERY seat of the last round to re-ACK) and
_maybe_reset_round (needs EVERY pod gone). A games night lives between
those -- most pods rejoin, one player closes their window. Worse, the
"not all seats filled" diagnostic sits INSIDE the `launches_sent == 0`
guard, so in exactly that state NOTHING was printed.
* btoperator.py: the LAUNCH button is gated on `not monitor.launched`, and
`launched` was cleared ONLY by the two relay lines those same gates emit
("WAITING FOR OPERATOR", "round RESET"). So the button was greyed out in
precisely the wedged state -- the click was a no-op by construction.
That is why a stable group worked (everyone re-ACKs -> gate fires) and why only
a session restart recovered (fresh relay process = fresh state).
FIXES
* An explicit operator LAUNCH is now sufficient authority to start a new
round: _rearm_for_new_round() clears the finished round's state and restores
the template roster/egg, KEEPING seats/beacons/connections, so whoever is
here stays here. Triggered on a press while a round is latched.
* New `rearm`/`newround` operator command + a Re-arm button, so recovery never
needs a session restart. Proven live over the control port.
* Every operator command is logged AT RECEIPT with the state that decides its
fate, so "did it arrive or was it ignored?" is answerable from the log.
* A stale End Mission can no longer kill the next mission: _tick_stop consumed
a stop_requested set between rounds by latching it until launches_sent hit 2,
then StopMissioning the new mission in the tick it launched -- also
indistinguishable from "launch did nothing". It is now consumed + announced
while idle. The UI's end_sent likewise reset per round, not per session
(End Mission used to work exactly once a night).
* The UI clears `launched` on "StopMission sent" and on the re-arm line, so the
button returns when the round actually ends, and only greys once a command
has really been written (a dead relay now says so instead of logging
">> sent" into the void -- _console_finished leaves console_proc non-None).
HARDENING (the "reboot the console" half)
* SO_KEEPALIVE on every accepted socket + a last_seen deadline and a reaper:
nothing detected a pod that vanished WITHOUT a FIN (sleeping laptop, dropped
Wi-Fi, killed process, NAT timeout). Such a conn kept acked=True forever,
which permanently blocked the round reset and held a phantom seat. The
reaper stands down while a mission is running.
* Every pod-facing send went blocking with NO timeout on the single-threaded
selector loop, so one wedged peer could freeze the entire relay. All sends
now go through _send_all_guarded (10s timeout, drops the peer on failure).
* _send_egg no longer calls getpeername() on a possibly-dead socket.
REGRESSION I INTRODUCED AND CAUGHT ON THE RIG: the first cut re-armed whenever
launches_sent >= 1, which also matched the NORMAL state between RunMission #1 and
#2 (launch_requested deliberately stays set across the pair). That reset the
pair mid-flight and re-released eggs every tick -- a re-arm storm that kicked
every pod into an identity-resync loop. The re-arm now additionally requires
`launch_at is None`, i.e. no launch sequence in flight. Verified: 0 REJOIN lines
and exactly 1 RE-ARM line across a full 3-mission rig session.
VERIFIED
* scratchpad/test_relay_rearm.py -- 6 groups, all passing: the exact wedge
state recovers; a stale stop is consumed while idle; staging is NOT restarted
under an impatient operator; mid-pair never re-arms; the happy path is
untouched and RunMission still reaches the pods; the reaper drops a silent
conn and keeps a live one, and stands down mid-mission.
* Live 2-pod rig (scratchpad/rig_relay.ps1 + relay_ctl.py over the control
port): two clean back-to-back missions, StopMission, round RESET, a live
`rearm`, and LAUNCH-with-nobody-present now printing why instead of nothing.
NOT reproduced end-to-end: the field wedge needs 3+ pods with staggered rejoins
(this rig's pods re-exec together, so the all-gone reset always fires). The
state itself is covered by the unit test. Awaiting live confirmation on a real
games night.
Co-Authored-By: Claude Opus 5 (1M context) <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.