CydandClaude Opus 4.8
73b597df35
Emulate the cockpit RIO board natively inside the DOSBox-X fork, driven by
an SDL game controller + host keyboard -- no external vRIO process and no
named pipe. The game<->board round trip runs in-process at the emulated
UART's own cadence, so the serial round-trip dropouts (livelock, TXMAXIDLE,
rxburst, 15s retry) can't occur.
- serialrio.{cpp,h}: RIO 9600-8N1 device state machine + protocol codec +
input mapping, transcribed from the vRIO app (VRioDevice + Protocol +
InputRouter/BindingProfileFormat), minus transport/pacer/UI/locks.
B0 = gamepad (5 axes + joystick column). B1 = keyboard field: MFD banks on
the letter rows, F-keys = Secondary/Screen, numpad = flight controls,
LShift/LCtrl throttle slew; PAUSE/ScrollLock toggle panel<->DOS; vRIO-
grammar bindings file via bindings:/VWE_RIO_BINDINGS.
- vpx-device/README.md: device notes + apply steps (the DOSBox-X src tree is
git-ignored, so this dir is the tracked source of truth; the three sdlmain
keyboard-hook edits are documented there).
- net_{loop,rp}_rio.conf + deploy templates; render-bridge/
gauge_arena_rio_sound.conf (standalone -egg trim); pod-launch --rio
(mutually exclusive with --pipe).
Additive: real pods keep directserial realport:COM1; vRIO-over-pipe keeps
namedpipe pipe:vrio. Validated live 2026-07-22 (pad + keyboard field +
console networking) on the dist install.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
122 lines
6.3 KiB
Markdown
122 lines
6.3 KiB
Markdown
# 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
|
|
```
|
|
|
|
## Console argument reference
|
|
|
|
`pod-launch [mode] [options]` — the single installed entry-point. The product is
|
|
installed once; the console activates features by the args it passes. The per-rig
|
|
layout is fixed at `postinstall` time, so a typical call is just `pod-launch bt`.
|
|
|
|
### Mode — the primary feature selector (positional, or `--mode <name>`)
|
|
|
|
| Arg | Activates | Status |
|
|
|---|---|---|
|
|
| `bt` | BattleTech, networked cockpit (`net_loop.conf`, looped) | wired |
|
|
| `rp` | Red Planet, networked cockpit (`net_rp.conf`, looped) | wired |
|
|
| `test` | VGL_LABS factory cockpit test suite (`vwetest.conf` → `C:\VWETEST` → `TSTALL.EXE`): RIO, plasma, audio, video/Division calibration, Munga-net. DOSBox window defaults to 900,600 (the DOS screen is the suite's UI) | wired |
|
|
| `review` | mission-review PLAYBACK of `last.spl` | recognized, exits 3 (DOS arg TBD) |
|
|
| `test-plasma` | plasma-display diagnostic | recognized, exits 3 |
|
|
| `reset-rio` | RIO reset diagnostic | recognized, exits 3 |
|
|
| `audio-test` | audio test diagnostic | recognized, exits 3 |
|
|
|
|
Camera ship and LIVE mission-review are **not** modes — same `bt`/`rp` boot; the
|
|
console sets the role per-IP via the egg `hostType` (0 pod / 1 camera / 2 review),
|
|
see `../CAMERA-REVIEW-NOTES.md`. Default mode: `bt`.
|
|
|
|
### Feature toggles
|
|
|
|
| Arg | Effect |
|
|
|---|---|
|
|
| `--no-sound` | skip the ~4-min AWE32 SoundFont upload — **freezes bt/rp**: no AWE32 = no SOS ticks, and the default confs use the FAST (SOS) clock, so BTL4 hangs in the RIO-reset busy-wait (`L4RIO.cpp` `SetDTR`/`Now()`; root-caused 2026-07-10). Only safe with a SLOW-clock conf (`setenv` arg2=`s`) |
|
|
| `--mipmap` | mip-filter minified textures (fixes RP floor shimmer; non-authentic) |
|
|
| `--layout cockpit\|explode` | `cockpit` = borderless VDB head windows (default); `explode` = 7-window debug |
|
|
| `--no-bridge` | pod only, no GL render window |
|
|
| `--no-focus` | skip the renderer-topmost / DOSBox-focus pass |
|
|
| `--pipe` | use the `<mode>_pipe` conf: serials as named pipes to vRIO (`pipe:vrio`) + vPLASMA (`pipe:vplasma`), no com0com. **Dev-rig policy (2026-07-17): always `--pipe` on the dev machine** — vRIO dist ≥ `20260716-68e3d1f` speaks the pipe; the plain confs (real COM ports) are for cockpits with the physical RIO/plasma |
|
|
| `--rio` | use the `<mode>_rio` conf: the RIO cockpit board is emulated **in-fork** (`serial1=rio`) and driven by an **SDL game controller + the host keyboard** inside DOSBox-X — no vRIO process, no pipe, no serial round-trip. Self-contained cockpit: pad = stick/throttle/pedals + trigger/hat/torso; keyboard = the 72-button MFD/Secondary/Screen field + internal keypad (vRIO's default layout; **PAUSE toggles** keyboard between panel and DOS; Ctrl/Alt chords always pass through; remap via a vRIO-grammar bindings file, conf `bindings:<path>` or env `VWE_RIO_BINDINGS`). See the fork's `serialrio.cpp`. Dev/standalone only; mutually exclusive with `--pipe`. Real pods still use the plain confs (physical RIO on COM1) |
|
|
|
|
### Window placement (per-rig; normally fixed, overridable per-launch)
|
|
|
|
| Arg | Effect |
|
|
|---|---|
|
|
| `--bridge-pos x,y` | main render window position (default `0,0`) |
|
|
| `--bridge-size w,h` | main render size (default `832,512` — the dPL3 board's native framebuffer res; see `../LAUNCH.md`) |
|
|
| `--dosbox-xy x,y` | DOSBox window position + focus (default `10,10`) |
|
|
|
|
### Path / asset overrides (dev / edge — `postinstall` already wires these)
|
|
|
|
`--root <dir>` · `--conf <path>` · `--dosbox <exe>` · `--renderer <exe>` ·
|
|
`--bridge-script <py>` · `--awe-rom <raw>` · `--work <dir>`
|
|
|
|
### Diagnostics
|
|
|
|
`--dry-run` (resolve + print the launch plan, don't launch) · `-h` / `--help`
|
|
|
|
```
|
|
pod-launch bt --root C:\VWE\TeslaRel410\emulator --dry-run
|
|
```
|
|
|
|
### Exit codes the console reads back
|
|
|
|
- **normal run** → returns **DOSBox's exit code** = the game's **`ExitCodeID`**,
|
|
passed straight through (the same remote-ops code the pod loop dispatched on).
|
|
- **`2`** → bad arguments (usage on stderr).
|
|
- **`3`** → recognized mode not yet wired (reason on stderr).
|
|
|
|
## 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).
|