TeslaSuite/FIRESTORM-CTCL.md

Commanding FireStorm from TeslaConsole — CTCL research

Researched 2026-07-28. Status: parked. No code was written; this is the record of what CTCL is, what integrating it would cost, and which option we'd take if we ever pick it up.

BT4 and RP4 speak Munga (TCP 1501) — the protocol the console already drives via the vendored Munga Net.dll. BattleTech FireStorm is a MechWarrior 4 total conversion and speaks something else entirely: CTCL, the coin-op / LAN-centre control layer the Korean team added to the MW4 engine (every call site is bracketed // jcem - begin / // jcem - end; the acronym is never expanded in the source).

Source for everything below is the FireStorm repo at C:\VWE\firestorm (gitea.mysticmachines.com/VWE/firestorm.git). Paths in this document are relative to firestorm/. That repo's LAUNCHER-AND-MW4.md already documents the launcher link; the game link (the mission handshake on port 1001) is documented here for the first time.

---

Where we are today

The console can already launch FireStorm on a pod — it is a product in Console/RedPlanet/Apps.xml, pointing at C:\Games\MW4\launcher.exe. So today a FireStorm pod runs:

TeslaLauncher (ours, TCP 53290)
   └─ launcher.exe        (MW4's CTCL agent, listens TCP 1000)
        └─ MW4.exe -ctcltype 2   (the game, listens TCP 1001)   ← started from c:\ctcl.ini [config] run=

What the console cannot do is build or run a mission. That is the gap.

---

CTCL in one page

Roles (Gameleap/code/ctcls/ctcl_params.h:28-33)

Value	Role	Who	Listens
_ECTCL_Launcher = 0	pod agent	Launcher.exe	1000
_ECTCL_Console = 1	operator console	MW4.exe with no -ctcltype	— (dials out)
_ECTCL_Game = 2	pod running the game	MW4.exe -ctcltype 2	1001
_ECTCL_CameraShip = 3	spectator / camera pod	MW4.exe -ctcltype 3	1001
_ECTCL_None = 4	CTCL disabled	MW4.exe -dragon	—

The console is the same binary as the game. It reads c:\ctcl.ini [teslas] for the pod list and opens two sockets per pod (1000 + 1001). Pods listen; the console never does.

Framing (Gameleap/code/Launcher/mugSocs.cpp)

A tiny hand-rolled "MUG" socket library. Frame is:

uint16 length (big-endian, = 1 + payload)   uint8 cmd   payload…

Payload fields are described by printf-style format strings (CPacket::vAssemble, mugSocs.cpp:1078):

code	meaning
b B	uint8
w W	uint16, network byte order
n d D	uint32, network byte order
f / F / 6	float / double / int64 (host order)
s	NUL-terminated string, inline
S	uint16 length + NUL-terminated string
x	uint16 length + raw bytes
X	raw bytes, no length prefix

Messages (Gameleap/code/Launcher/ctcl.h:73-91)

id	name	direction	notes
1	C_GameInfo / S_GameInfo	console ↔ launcher (:1000)	poll ~1 Hz; reply is applType, applState, gameState, gameTime, isServer
10	C_OrderAppl	console → launcher or game	routed by value: ≥100 → :1000, <100 → :1001
19	C_ErrorStartGame	console → all	abort, back to main menu
20	C_ReadyStartGame	console → each pod (:1001)	the big one — NMP blob + that pod's player record
21	C_BOTS	console → server pod only	full roster incl. bots; doubles as "you are the host, create it"
22	C_SetMechs	console → clients only	"join now"
23	C_GetReady	—	declared but dead — no handler in any packet map
24	C_DoLaunch	console → server	drop
30	S_GameReturn	game → console	progress / error, _EGR_* codes
40	C_SendFile / S_SendFile	both ways	print + mission-review file notifications only
50	C_InviteCOOP / S_InviteCOOP	both ways	coin-op invite; irrelevant to console-run games

Orders (ctcl_params.h:40-46)

order	value	handled by	effect
_CTCL_Order_Terminate	0	game	gos_TerminateApplication()
_CTCL_Order_EndMission	1	game	drop out of the mission
_CTCL_Order_Launch	100	launcher	RunExec() the c:\ctcl.ini [games] command line
_CTCL_Order_Shutdown	101	launcher	ExitWindowsEx(EWX_POWEROFF)
_CTCL_Order_Reboot	102	launcher	ExitWindowsEx(EWX_REBOOT)
_CTCL_Order_Unload	103	launcher	PostQuitMessage(0) — quit the launcher

Pod state (ctcl_params.h:1-26)

The launcher has no visibility into the game process; it reads five ints out of ctcls.dll's .SHARED_DATA section (a process-spanning shared segment the game writes): applType (_EAT_MW4), applState (PreLaunch/Launched/PostLaunch), gameState (Idle/Preparing/Running/Closing), gameTime (seconds), isServer.

---

The mission handshake

Who hosts — the console decides, there is no election

While validating the player list (Gameleap/code/mw4/Code/MW4/MW4Shell.cpp:13492-13504) the console records the first cameraship pod (:13421) and the first ordinary pilot pod (:13432), then:

if (nCameraship != -1)  g_nServer = nCameraship;   // cameraship hosts if one is playing
else                    g_nServer = n1stTesla;     // otherwise the topmost pilot pod

The server designation is positional — whatever pilot ordering the operator UI shows is the host-selection UI. The original console offered no explicit control over it.

Each pod learns its role from one byte in C_ReadyStartGame (mw4/Code/MW4Application/ctcl.cpp:1544); the receiver sets g_bIsServer = (bType == 1) (:822). The server's IP travels in the same packet but is discarded on arrival (MW4Shell/MWApplication.cpp:18534 — PI.m_dwAddr = 0; // dwAddr;).

Rendezvous is by name, not address

The console generates g_guidGameDatas = gos_GenerateUniqueGUID() per mission and ships it in C_ReadyStartGame; every pod formats it identically into g_szGameName (ctcl.cpp:824-827).

• Server (CTCL_DoCreateGame, MW4Application.cpp:1708): gos_NetStartGame → PreConnect → CTCL_DefaultHostSetup(0) → Mech4CreateGame(g_szGameName, pilot, NULL). AdvertiseThisGame = 0 — LAN enumeration only, never published to the Zone.
• Clients (CTCL_DoJoinGame :1745 → CTCL_CheckJoinGame :1768): open the LAN browser, poll gos_GameIsExist(g_szGameName) until it appears, then gos_JoinGame(...). 25-second timeout.

The sequence (mw4/Code/MW4Application/ctcl.cpp:1486-1670, state var g_nMech4Comm)

Its whole purpose is to serialize create-before-join — a client that browses before the host exists just burns its timeout.

console sends	waits for	pod does
C_ReadyStartGame → all pods	every pod → _EGR_PreparingStarted	stores roster + NMP
C_BOTS → server only	server → _EGR_OkCreateSession	CTCL_DoCreateGame
C_SetMechs → clients only	server → _EGR_OkLaunchReady	CTCL_DoJoinGame, browse + join
(operator presses Launch)
C_DoLaunch → server		everyone drops

Failures come back as _EGR_ErrCreateSession / _EGR_ErrJoinSession on S_GameReturn; the console responds by broadcasting C_ErrorStartGame (ctcl.cpp:1520-1533).

---

The three blockers

1. The NMP blob

C_ReadyStartGame carries an opaque byte array the console produces by calling the MW4 engine's own MWNetMissionParameters::SaveParameters() (mw4/Code/MW4/MWApplication.cpp:749-864) — a bit-packed stream: ~60 fields at widths of 1, 2, 3, 5, 7, 8, 16, 32 and 64 bits, then 8 × TeamParameters (:513-535, another 10 × 32-bit allow-masks each), a byte-align, then eight length-prefixed strings.

Reproducing it in C# means porting Stuff::DynamicMemoryStream::WriteBits bit-for-bit and getting every field width right. A one-bit drift silently corrupts every field after it, and the layout changes whenever the FireStorm codebase adds a parameter — the existing // MSL 5.05 Advance Mode / // MSL 5.06 Armor Mode markers in that function are exactly that happening twice already.

2. Content-derived identifiers

The CTCL console is a full MW4 install because it needs game data:

• m_nMechIndex / m_fileID / m_recordID come from the console's own sorted mech resource table (shl->m_mechIDs, built from the installed .erf content).
• m_mapID indexes the console's scenarios[] table.
• m_mapClientCRC is a 64-bit CRC of the map's .mw4 file (MWApplication.cpp:7048) which every pod recomputes and compares (:7538-7553); a mismatch makes the pod decide it doesn't have the map.

So console and pods must run byte-identical content, and any external console needs that table regenerated per FireStorm build.

3. No telemetry

CTCL gives the console gameState and gameTime (seconds) and nothing else — no kills, no damage, no scores. The whole BTGame/RPGame model (live scoreboard, BTMissionRecorder, BTPrintDocument) has no CTCL equivalent.

FireStorm results instead land as files on the pod: the game writes {guid}.pr (print) and {guid}.mr (mission review) into \mw4files (mw4/Code/MW4/recscore.cpp:246-249). S_SendFile is only a notification; the console reads the file over SMB as \\<pod>\mw4files\{guid}.pr and hands it to the mw4print helper via WM_COPYDATA. Mission review is replayed by sending the path to the cameraship pod flagged m_bMissionReview.

Also free, for the same reason: plasma displays and the RIO board are the game's own business on FireStorm pods (PLASMA_Do, mw4/Code/MW4/CRIOMAIN.CPP:468, gated by -noplasma). The console does not drive them, unlike BT4/RP4.

---

Options considered, and the decision

A — Pure C# CTCL client in TeslaConsole. Port the protocol and the bit-packed NMP serializer and a per-build content-table extractor. No game-side change. Rejected: the NMP layout is engine-internal and unversioned, so this would need reworking every time the FireStorm codebase changes. Maintenance nightmare for the value returned.

B — Teach MW4 a console-friendly protocol. We have a working VC6 build environment for FireStorm (build-env/, with a verified Release build in rel.bin/). Add a message on :1001 that accepts a plain mission spec (map name, rules, per-player mech names) and let the server pod build the NMP locally with the engine's own serializer. The console then never touches bit-packing, map CRCs or resource IDs. Viable — this is the option if we ever do it. Cost is a FireStorm rebuild and a redeploy to every pod.

C — Pod-level control only (C_GameInfo + C_OrderAppl: state, launch, terminate, end mission, shutdown, reboot). Not needed. Site Management already gives us reboot/shutdown/launch/kill through our own TeslaLauncher; those same functions being built into MW4's launcher.exe is redundant with what we already use. And if mission parameters still have to be set on the MW4 console, there is no reason to come back to the TeslaConsole just to start and stop the mission — the operator is already sitting at the machine that can do it.

---

If B is ever picked up

Rough shape of the work:

1. Game side (C++/VC6). New packet id on :1001 carrying a text/JSON mission spec. Handler calls the existing CTCL_DefaultHostSetup + the MW4Shell parameter setters (MAP_ID_PARAMETER etc. — they already recompute m_mapClientCRC and the mech ResourceIDs locally), then enters the normal g_nMech4Comm path. Reuse C_ReadyStartGame/C_BOTS/C_SetMechs/C_DoLaunch unchanged between pods. Remember: ctcl.cpp exists as four hand-copied siblings (Launcher, MW4Application, MW4GameEd2, Tools\AnimScript) — change every copy.
2. Console side (C#). A CtclGame sibling to Console/TeslaConsole/MungaGame.cs — same connect/poll/own shape, ~400 lines — plus a FSGame pane modelled on BTGame, minus everything telemetry-driven. Pod/Site/AppRegistry and the TeslaLauncher RPC are already protocol-agnostic and need no change.
3. vPOD. A CTCL mode: listen on 1000/1001, answer C_GameInfo, walk the _EGR_* ladder. Without it none of this is testable off-cockpit.
4. Results. Decide whether to parse .pr files ourselves or keep shelling out to mw4print.

Open questions

• Which FireStorm build is canonical? FS Build V4H, FS507C_20160909 and FS507D_20161015 are all on this machine; content tables and map CRCs differ per build.
• ctcl.ini ownership. CTCL's pod list is hardcoded to c:\ctcl.ini and uses the 2005-era 200.0.0.x scheme; TeslaConsole owns pod addressing via Site. Either the console writes ctcl.ini at Install Product time, or the pod list becomes console-side only (pods only ever read [games] + [config]).
• Server designation UI. Positional today; worth making explicit if pods differ in spec.
• Known shipped bug (Gameleap/code/Launcher/ctcl.cpp:1310): the remote-launch table looks up the cameraship command under key #1, but every shipped ini writes *1. A console Launch aimed at a cameraship pod silently does nothing. Cameraships were evidently autostarted, not console-launched.
• _EAT_RP = 2 exists in ctcl_params.h alongside _EAT_MW4 = 1 — CTCL had a Red Planet application type. Vestigial as far as this repo is concerned; the second [games] slot.

Source map

Thing	Where (relative to C:\VWE\firestorm)
Protocol + manager, game copy	Gameleap/code/mw4/Code/MW4Application/ctcl.cpp
Protocol + manager, launcher copy	Gameleap/code/Launcher/ctcl.cpp (built /D CTCL_LAUNCHER)
Constants (roles, orders, states)	ctcl_params.h (four copies)
Message ids + structs	ctcl.h
Socket library / framing	Gameleap/code/Launcher/mugSocs.cpp, mugsocs.h
Shared-state DLL	Gameleap/code/ctcls/ctcls.cpp
NMP serialization	Gameleap/code/mw4/Code/MW4/MWApplication.cpp:749-864
Session create/join	Gameleap/code/mw4/Code/MW4Application/MW4Application.cpp:1708-1800
Console mission build	Gameleap/code/mw4/Code/MW4/MW4Shell.cpp:13369-13548
Console UI (shell script)	Gameleap/mw4/Content/ShellScripts/ConLobby.script
Launcher link (already documented)	LAUNCHER-AND-MW4.md