22495d7245
Research only. Nothing implemented, nothing scheduled. Captured now so the
investigation does not have to be repeated when we come back to it.
New file: WINDOWED-MODE.md (repo root), indexed from README.md and the
CLAUDE.md next-steps list.
Goal being assessed
-------------------
Make -window work for every pod configuration, so a full pod (main + radar
+ MFDs, or a cameraship pair) can be tested on a single monitor as a set
of moveable windows. Target order: console (already works), cameraship,
-tmfds 1, -tmfds 4. -tmfds 3 deliberately out of scope.
Headline finding
----------------
-window does NOT fail for the MFD and cameraship modes - it silently
DISABLES them, and the reason is a single line:
MW4Application.cpp:1373
use_shgui = Environment.fullScreen ? 1 : 0;
use_shgui is the master switch for the entire secondary-panel subsystem
and is derived from fullscreen, so with -window it is 0 and
DXRasterizer.cpp:1131 never calls HSH_EnterFullScreen2(). No panel is ever
created. Console mode only appears to work windowed because it has no
panels to lose.
What the document covers
------------------------
* Why it behaves the way it does today, with the exact gating code.
* What already exists in our favour: the main display is a working
windowed reference implementation (primary + clipper + offscreen
backbuffer, presented with Blt); the clipper wrappers are already in
use; and none of the panel DRAWING code would change, because panels
render to an offscreen target and composite - they are indifferent to
whether the present is a Flip or a Blt.
* The six things that must change, with quoted code: decouple use_shgui;
windowed variants of CHSH_Device::InitFirst (DDSCL_NORMAL, no
SetDisplayMode, per-panel HWND) and InitSecond (plain primary + clipper
+ offscreen backbuffer, D3D device on the offscreen); one window per
panel; 8 Flip->Blt sites in WinMain.cpp; and explicit frame pacing.
* Frame pacing is called out as the item that will actually bite: sh_step
advances once per frame and drives MFD channel cycling, so an uncapped
windowed rig would not faithfully represent pod behaviour. Same root
cause as the known mechlab fast-spin bug.
* Reference tables: every panel class with its InitFirst location, device
slot and resolution; the SwapRightState member-swap mechanism that any
windowed work must keep intact; and the full lifecycle/gating map.
* Suggested phasing, with radar-only as the decisive Phase 1 experiment.
The risk that decides it
------------------------
Windowed D3D7 device creation is per-GPU, and this would need four
windowed devices in one process. Precedent runs both ways: the mission
editor hit DDERR_INVALIDOBJECT creating a windowed D3D device on Win11 and
needed DDrawCompat (STEP 8), while the game's own windowed main display
succeeds on the W4100. Nothing has proven four. If it fails, the fallback
means rewriting the panel RENDER path, not just its present - a
substantially bigger job.
Why this may be worth more than a test convenience
--------------------------------------------------
Windowed mode removes exclusive-mode contention entirely, which is the
whole reason dgVoodoo2 is currently mandatory for every multi-display
configuration on Windows 10/11 (STEP 10). If windowed panels work
natively, that is a route to dropping the dgVoodoo2 prerequisite WITHOUT
breaking the XP pods, since it needs no external DLL on either OS. Same
groundwork as the borderless-windowed migration already parked in STEP 10.
Note on citations
-----------------
All 22 file:line references were derived directly and verified to resolve
to the expected symbol. An exploratory pass had produced line numbers that
were substantially wrong (CHSH_Device::InitFirst reported at 717, actually
627; IsMultimonitorAvaliable at 2178, actually 2961), and a claim that the
radar renders at 480x640 rotated - the code passes 640,480 like the
others. Worth knowing before trusting generated citations in a document
intended to outlive the session.
Co-authored-by: Claude Opus 5 (Anthropic) <noreply@anthropic.com>
Co-authored-by: GitHub Copilot <copilot@github.com>
227 lines
15 KiB
Markdown
227 lines
15 KiB
Markdown
# BattleTech: FireStorm
|
||
|
||
Source code, game data, and build toolchain for **BattleTech: FireStorm** — the MechWarrior 4-based
|
||
simulator software for Virtual World Entertainment Tesla II cockpit pods. This is the community-maintained
|
||
continuation of the original 2002–2009 GameLeap / FASA Interactive codebase, currently at **V5.1.x**.
|
||
|
||
> ⚠️ **Setting up a new machine? Read `RECOVERY.md` BEFORE cloning this repo.**
|
||
> The clone only comes out byte-exact if long paths, `core.autocrlf=false`, and Git LFS are
|
||
> configured *first* — cloning without them silently corrupts line endings, truncates deep
|
||
> VC98/MFC paths, and leaves LFS placeholders instead of the real binaries.
|
||
|
||
---
|
||
|
||
## Background
|
||
|
||
### What BattleTech: FireStorm is
|
||
|
||
BattleTech: FireStorm is the game software that runs inside the **Virtual World Entertainment
|
||
Tesla II** cockpit pods — the walk-in BattleMech simulator pods found at arcades, conventions,
|
||
and private venues. Each pod is a fully enclosed cockpit with joysticks, throttle, rudder pedals,
|
||
a primary infinity-optics display, five monochrome auxiliary instrument monitors, and a color map
|
||
display. Up to 16 players battle simultaneously in networked sessions over a LAN, with a dedicated
|
||
console pod managing the match, printing scoresheets, and running a post-game mission review.
|
||
|
||
### History
|
||
|
||
**Origins (1988–1990).** The concept for networked BattleMech cockpit simulators originated with
|
||
**Jordan Weisman** and **L. Ross Babcock** — co-founders of FASA Corporation — who developed it
|
||
under the code name *ESP* ("Environmental Simulations Project"). In 1988 they partnered with
|
||
**Incredible Technologies** to build a prototype: networked cockpits with joysticks, throttle,
|
||
foot pedals, and dual monitors, rendered on custom Amiga and Texas Instruments hardware. The first
|
||
public **BattleTech Center** opened in North Pier Mall, Chicago, in 1990.
|
||
|
||
**Virtual World Entertainment and four hardware generations (1991–2001).** The organization
|
||
rebranded as **Virtual World Entertainment (VWE)** in 1991 and produced four generations of
|
||
cockpit hardware over the following decade: System 1 (custom Amiga/TI graphics, 6 players);
|
||
System 2 (TI TMS 34010 real-time 3D polygons, 8 players, launched in Yokohama and Chicago in
|
||
1992); System 2.5/3 (redesigned "Virtual World Centers" exterior, **Red Planet** added as a second
|
||
game title, SiteLink ISDN networking connecting centers across the US and internationally — over
|
||
**300 cockpits** deployed worldwide at peak); and System 4 / **Tesla** (1996 — entirely PC-based,
|
||
Division Pixel Planes texture-mapped 3D at locked 30 FPS, infinity-optics curved primary display
|
||
surrounded by five monochrome auxiliary monitors and a color map display).
|
||
|
||
In 1996 VWE and FASA Interactive Technologies merged under **Virtual World Entertainment Group**.
|
||
Microsoft purchased the group in 1999, sold VWE to former CFO James Garbarini, and integrated FASA
|
||
Interactive into Microsoft Game Studios. In 2005 all remaining VWE interests were sold to Nickolas
|
||
"PropWash" Smith, with the principal offices moving to Kalamazoo, Michigan.
|
||
|
||
**Tesla II: FireStorm (2002–2016).** Beginning in 2002, VWE partnered with **Microsoft**,
|
||
**Alienware**, and **GameLeap** to upgrade the Tesla cockpits. The Division Pixel Planes cards — no
|
||
longer in production — were replaced with Alienware PCs, and the Macintosh-based console became
|
||
PC-based for the first time in over a decade. The new game software, **BattleTech: FireStorm**,
|
||
was built on the **MechWarrior 4: Mercenaries** engine (GameLeap v5.03) developed by Microsoft /
|
||
FASA Interactive. Software versions progressed through 5.04, 5.07, and finally **5.07D** (the last
|
||
official release, 2016, for LAN-center deployments).
|
||
|
||
**Community continuation (2005–present).** As the original Virtual World Center locations closed
|
||
through the 2000s, pods passed into the hands of private operators, enthusiast venues, and
|
||
convention touring groups. The most prominent continuing venue is **MechCorps Entertainment** in
|
||
Houston, TX (opened November 2005), which operates publicly year-round and tours gaming conventions
|
||
across the US. VWE itself continues to bring pods to conventions from Kalamazoo.
|
||
|
||
The pod-operator community has continued developing the FireStorm software beyond the last official
|
||
release, producing the **V5.1.x** series maintained in this repository.
|
||
|
||
### What's new in V5.1.x (community additions since 5.07D)
|
||
|
||
- **Modern Windows compatibility** — DirectDraw 16-bit shim automation, DirectInput joystick
|
||
enumeration fix, windowed-mode DirectDraw fix for the mission editor (via DDrawCompat)
|
||
- **Multi-monitor MFD support** — four-display mode (`-tmfds 4`) for pods using two separate
|
||
640×480 MFD monitors, plus stutter fix for split-MFD rendering
|
||
- **RIO cockpit hardware** — `-tbaud` switch for replica RIO boards with high-speed UARTs
|
||
- **Automated match configuration** — Load File system for setting up full matches from an `.ini`
|
||
file (game type, map, all 16 pilot slots) without manual console lobby input
|
||
- **Multiplayer fixes** — 16-pilot + cameraship launch fixed; expanded time-limit list (up to 30 min)
|
||
- **Expanded mech roster and loadout corrections** — additional chassis with accurate IS/Clan loadouts
|
||
- **Console lobby** — V5.1.x Super6 rookie rotation, configurable Rookie Mission defaults,
|
||
correct MFD time-limit and radar dropdowns
|
||
- **mw4print v2.0** — MySQL match-data export, configurable banner text
|
||
- **Source cleanup** — all EUC-KR/CP949 Korean developer comments translated to English; Language DLL
|
||
rebuilt from source as the English version (fixes Korean button labels in the GameOS crash dialog)
|
||
- **Full build reconstruction** — the complete toolchain (VC6, DX 7.0a, DX Media 6) is
|
||
self-contained in `build-env\`; the game and editor build from source with 0 errors
|
||
|
||
See `RELEASE-NOTES-5.1.0b_RC1.md` for pod-owner change details, and `CLAUDE.md` for the full
|
||
engineering history.
|
||
|
||
---
|
||
|
||
## Repository layout
|
||
|
||
> Only **three** source trees feed the build; everything else is output (regenerable),
|
||
> design reference, or archived clutter.
|
||
|
||
## Folder map
|
||
|
||
```
|
||
C:\VWE\firestorm\
|
||
├─ Gameleap\ The MW4/Gameleap 5.03 engine + game (the two live trees)
|
||
│ ├─ code\ ⭐ SOURCE CODE — build mw4\Code\MechWarrior4.dsw in VC6
|
||
│ │ ├─ CoreTech\ Reusable engine layer: GameOS, MLR renderer, gosFX,
|
||
│ │ │ GOSScript, Stuff, Network, blade + engine tools
|
||
│ │ ├─ mw4\Code\ The game itself: MW4 lib (AI, mechlab, HUD, shell),
|
||
│ │ │ MW4Application (→MW4.exe), MW4GameEd2 (mission editor),
|
||
│ │ │ scriptstrings/MissionLang (string DLLs), dedicated UI
|
||
│ │ ├─ mw4\Libraries\ mw4-local libs: Adept, stlport (build first), MLR,
|
||
│ │ │ Compost, ImageLib, gosfx, server, stuff …
|
||
│ │ ├─ mw4\Binaries\ 3DS Max export plug-ins (mech/prop .erf pipeline)
|
||
│ │ └─ rel.bin\ pro.bin\ Build OUTPUT: Release (MW4.exe, MW4pro.exe) / Profile
|
||
│ │ arm.bin\ dbg.bin\ (editor MW4Ed2.exe) / Armor / Debug — regenerable
|
||
│ └─ mw4\ ⭐ GAME DATA source tree (editor also runs here in place
|
||
│ │ via run-editor.bat; tool exes MapCreator/Tctd/NFOEditor…)
|
||
│ ├─ Content\ All content sources: Mechs\, Maps\, Missions\, Skies\,
|
||
│ │ Weapons\, WeaponSubsystems\, Subsystems\, Buildings\,
|
||
│ │ Vehicles\, Effects\, textures\, Campaigns\, Tables\,
|
||
│ │ Defines\, ABLScripts\ (mission/AI language),
|
||
│ │ ShellScripts\ (menu/mechlab UI), *.build manifests
|
||
│ ├─ Resource\ Packed .mw4 packages (output of `MW4pro -build`) +
|
||
│ │ Missions\*.nfo (MP registration) + UserMissions\
|
||
│ ├─ hsh\ Loose 2D art loaded at runtime: mech portraits, MFD
|
||
│ │ target images, HUD/radar bitmaps, decals, fonts
|
||
│ ├─ Assets\ Stats\ Runtime support data (cursors, world stats)
|
||
│ └─ Movies\ fonts\ Notes\ Cinematics / font sources / dev notes (not deployed)
|
||
├─ build-env\ ⭐ TOOLCHAIN — self-contained VC6 (VisualStudio6\),
|
||
│ │ DX 7.0a + DX Media 6 SDKs, stlnative\ headers,
|
||
│ │ ddrawcompat\ (editor viewport fix), .reg env files,
|
||
│ │ build/deploy scripts (see below), build logs
|
||
├─ MW4\ Runnable game deploy (output of deploy-mw4.ps1) —
|
||
│ regenerable; copy this to production
|
||
├─ BTFrstrm\ FireStorm design data: MechInfo_5.04.xls (stat source
|
||
│ of truth), scriptaddmech.xls (add-mech row generator)
|
||
├─ Finished HUDS from J&J\ Per-mech HUD source art (MFD + Radar) awaiting
|
||
│ integration, ~13 chassis
|
||
├─ _UNUSED\ Archived clutter — nothing read by the build (EXCEPT
|
||
│ worth knowing: Gameleap\EditorDocs\ = original map/
|
||
│ terrain/NFO/ABL tutorials)
|
||
├─ CLAUDE.md Full build/runtime reconstruction notes (the history)
|
||
├─ README.md This file — orientation + fresh-machine restore
|
||
├─ RECOVERY.md Disaster-recovery notes
|
||
├─ ADDING-A-MECH.md Workflow: add a new 'Mech chassis
|
||
└─ ADDING-A-MAP.md Workflow: add a new map/mission
|
||
└─ WINDOWED-MODE.md Research: making -window work for MFD/cameraship modes
|
||
```
|
||
|
||
## The folders that matter (build inputs)
|
||
|
||
| Folder | Role | Notes |
|
||
|--------|------|-------|
|
||
| **`Gameleap\code\`** | **Source code + compiled binaries** | C++ engine/game source (`mw4\Code`, `CoreTech`, `mw4\Libraries`). Build `mw4\Code\MechWarrior4.dsw` in VC6. Outputs land in `rel.bin\` (Release `MW4.exe`, `MW4pro.exe`), `pro.bin\` (editor `MW4Ed2.exe`), `arm.bin\`/`dbg.bin\`. |
|
||
| **`Gameleap\mw4\`** | **Game data source** | The content tree the resource packer reads (`Content\`, and the generated `resource\*.mw4`, plus `hsh\`, `Assets\`, `Stats\`, runtime DLLs). This is the live data set — **not** `GameleapCode5_03\Content` (that was an old 2005 duplicate, now in `_UNUSED`). |
|
||
| **`build-env\`** | **Toolchain + scripts** | Self-contained VC6 (`VisualStudio6\`), DirectX 7.0a + DX Media 6 SDKs, `stlnative\`, the `.reg` env files, and the deploy scripts. |
|
||
|
||
### Build / deploy scripts (in `build-env\`)
|
||
- **`deploy-mw4.ps1`** — packs resources from source (`build-resources.ps1`) then assembles the
|
||
runnable game into `c:\VWE\firestorm\MW4`. Trims dev bloat, ships only the canonical game packages,
|
||
optimizes mech BMPs to 256-color, applies the DirectDraw compat shim.
|
||
- **`build-resources.ps1`** — (re)packs `resource\*.mw4` from `Gameleap\mw4\Content` using the
|
||
in-exe compiler (`MW4pro.exe -build`). Called by the deploy; can be run standalone.
|
||
- **`deploy-editor.ps1`** — installs the mission editor **in place** into `Gameleap\mw4` (the data
|
||
tree it edits): drops `MW4Ed2.exe` + DDrawCompat there, neutralizes the DDraw-breaking DLLs, sets
|
||
the shim, writes `run-editor.bat`. No separate editor directory. (`build-resources.ps1` moves
|
||
DDrawCompat aside while the builder runs, since it's fatal to `MW4pro.exe`.)
|
||
- **`RESOURCE-BUILD.md`** — how the `.mw4` packaging works.
|
||
|
||
### Outputs (regenerable — safe to delete and rebuild)
|
||
- **`MW4\`** — runnable game deploy (from `deploy-mw4.ps1`). Move/copy this to production.
|
||
- The **editor** has no separate output dir — it runs in place from `Gameleap\mw4` via
|
||
`Gameleap\mw4\run-editor.bat` (installed by `deploy-editor.ps1`).
|
||
|
||
### Design and reference (not build inputs)
|
||
- **`BTFrstrm\`** — FireStorm design data: mech stat workbooks (`MechInfo_*.xls`, `scriptaddmech.xls`),
|
||
mech loadout reference (`mech_loadouts.md`), autoconfig file spec, and test match files.
|
||
- **`Finished HUDS from J&J\`** — per-mech HUD source art (MFD + Radar) for ~13 chassis awaiting integration.
|
||
|
||
### `_UNUSED\` — archived clutter (nothing here is read by the build)
|
||
Moved here to reduce confusion. Safe to delete once comfortable. Contents:
|
||
- `Gameleap\{Archive, Drivers, EditorDocs, Notes, batch, utilities}` — historical utility data
|
||
(the build only ever used `Gameleap\mw4`). Note: `EditorDocs\` = original map/terrain/NFO/ABL tutorials.
|
||
- `GameleapCode5_03\{Content, hsh}` — stale 2005 duplicate data trees, superseded by `Gameleap\mw4`.
|
||
- `resource_fullbak\` — one-off backup from the from-scratch rebuild; redundant now.
|
||
|
||
---
|
||
|
||
## Building from source
|
||
|
||
### Quick build flow
|
||
1. Compile code: VC6 build `Gameleap\code\mw4\Code\MechWarrior4.dsw` → `rel.bin\` / `pro.bin\`.
|
||
2. Deploy game: `build-env\deploy-mw4.ps1` → `MW4\` (packs resources, assembles, optimizes BMPs, applies shim).
|
||
3. (Optional) Install editor: `build-env\deploy-editor.ps1` → runs in place from `Gameleap\mw4\run-editor.bat`.
|
||
|
||
### On a fresh Windows machine
|
||
|
||
1. Install **Git for Windows** (includes Git LFS) — or Git + `git-lfs` separately.
|
||
2. Enable long paths **before** cloning (this tree has deep VC98/MFC paths > 260 chars):
|
||
```
|
||
git config --global core.longpaths true
|
||
git config --global core.autocrlf false
|
||
git lfs install
|
||
```
|
||
Also enable the OS setting: `HKLM\SYSTEM\CurrentControlSet\Control\FileSystem\LongPathsEnabled = 1`.
|
||
3. Clone to `C:\VWE\firestorm` — the toolchain config has this path baked in:
|
||
```
|
||
git clone https://gitea.mysticmachines.com/VWE/firestorm.git C:\VWE\firestorm
|
||
```
|
||
`git clone` pulls LFS objects automatically. If any are missing: `cd C:\VWE\firestorm && git lfs pull`.
|
||
|
||
### After cloning — make it buildable and runnable
|
||
|
||
- **Build toolchain (VC6):** import the registry config (elevated), per `build-env\README.md`:
|
||
```
|
||
reg import C:\VWE\firestorm\build-env\vc6-hklm-registration.reg
|
||
reg import C:\VWE\firestorm\build-env\vc6-directories.reg
|
||
```
|
||
Then build `Gameleap\code\mw4\Code\MechWarrior4.dsw` in VC6 (see `CLAUDE.md` STEPs 1 and 3),
|
||
or use the already-mirrored `rel.bin\` / `pro.bin\` binaries directly.
|
||
- **Deploy the game:** run `build-env\deploy-mw4.ps1` to assemble `C:\VWE\firestorm\MW4` and apply
|
||
the Windows 10/11 DirectDraw compat shim. AppCompat is keyed on the exe *path* — the deploy script
|
||
applies it automatically, but if you copy `MW4\` to a different location you must re-run
|
||
`set-appcompat.bat` from inside that new location.
|
||
- **Editor:** `Gameleap\mw4\run-editor.bat` (installed in place by `deploy-editor.ps1`; see `CLAUDE.md` STEP 9).
|
||
|
||
### Important notes
|
||
- **`core.autocrlf=false`** — line endings are preserved byte-for-byte. Do not change this.
|
||
- The repo includes machine-specific bits (registry exports, AppCompat). These restore the *files*;
|
||
registry state must be re-imported and the AppCompat shim re-applied on each new machine (steps above).
|
||
- See `CLAUDE.md` for the full engineering and build reconstruction history.
|
||
- See `RECOVERY.md` for disaster-recovery procedures. |