# pod-launch

The supervising launch **entry-point** for the two DOSBox titles (BattleTech /
Red Planet 4.10). TeslaConsole → TeslaLauncher invokes this exe in the game dir
with args selecting game/mode; it is the single authoritative handle for the
whole session. See [`../DEPLOYMENT-PLAN.md`](../DEPLOYMENT-PLAN.md).

## Why an exe, not a batch/script

The entry-point must **own** the child processes' lifetime, not hand off and
exit. `pod-launch`:

1. Creates a **Windows Job Object** with `JOB_OBJECT_LIMIT_KILL_ON_JOB_CLOSE`.
2. Launches **DOSBox-X** and the **render bridge** *into* the job.
3. **Blocks** on DOSBox for the whole mission.

Kill this process (TeslaLauncher force-killing a hung DOSBox on a console
command) → the job's last handle closes → the **kernel** kills DOSBox + the
renderer. This holds even on a hard `TerminateProcess`, where no cooperative
shutdown can run. When DOSBox exits on its own (mission end) the supervisor
tears the job down and returns DOSBox's exit code.

A batch file / `cmd.exe` / `start` / `Start-Process` can't do this: they decouple
from the child, which then survives the parent. Verified: hard-killing the
supervisor reaps its child via the kernel (see the job-object cascade test).

## Build

Dev (needs the .NET 8 runtime present):

```
dotnet build -c Release
```

Deploy — self-contained single-file, so the air-gapped pod needs no .NET runtime
installed:

```
dotnet publish -c Release -r win-x64 --self-contained true -p:PublishSingleFile=true -p:IncludeNativeLibrariesForSelfExtract=true
```

## Usage

```
pod-launch [mode] [options]
```

**Modes** (the console's ExitCodeID vocabulary → a launch): `bt` → `net_loop.conf`,
`rp` → `net_rp.conf` (supported). `bt`/`rp` also serve the **camera ship** and
**live mission-review** roles — the console assigns those per-IP via the egg
`hostType`, so they're *not* separate modes (see `../CAMERA-REVIEW-NOTES.md`).
`review` (playback of `last.spl`) and the diagnostics (`test-plasma`,
`reset-rio`, `audio-test`) are recognized but fail clean (exit 3 + reason) until
their DOS launch mechanics are confirmed.

Paths resolve relative to `--root` (default: the exe's own dir = the deployed
game dir), with dev fallbacks so the same exe runs against the `emulator/` tree:

```
pod-launch bt --root C:\VWE\TeslaRel410\emulator --dry-run
```

`--dry-run` prints the resolved plan (dosbox / conf / renderer / work / layout)
without launching — use it to validate a rig's layout. Key flags: `--layout
cockpit|explode`, `--no-sound`, `--mipmap`, `--dosbox-xy x,y`, `--bridge-pos
x,y`, `--renderer <exe>` (frozen renderer; else falls back to `pyw
live_bridge.py`). `-h` for the full list.

## Deploy layout it expects (under the game dir / `--root`)

```
pod-launch.exe        dosbox-x.exe        net_loop.conf  net_rp.conf
renderer.exe (frozen) roms\awe32.raw      <game content + net-boot drivers>
```

`postinstall.bat` lays this out and renders the `net_*.conf` (paths, `realnic`,
`WATTCP my_ip = bayIP+100`). This exe just selects + launches.

## TODO (tracked in DEPLOYMENT-PLAN.md OPEN items)

- Wire the distinct non-networked modes once their DOS launch args are
  confirmed: `review` (playback app + `last.spl`) and the diagnostics. (The mode
  table in `Modes.cs` is the single place to add each.)
- Swap the dev `pyw live_bridge.py` for the frozen renderer exe once packaging
  is decided (freeze vs embedded Python — with David).
- Per-rig cockpit head RECTS (currently the `pod_deploy.ps1` defaults).