# Commander Keen port (Commander Genius)

Working port package for bringing the **Commander Keen** episodes to the
Ultimatum platform through the [Commander Genius](https://gitlab.com/Dringgstein/Commander-Genius)
interpreter. The first target is **Keen 4: Secret of the Oracle** (Galaxy
engine).

**Status:** Phase 0 complete (engine pinned, data-free WASM build reproduced and
runtime-verified, platform seams recorded). No adapter, catalog entry, or
public route exists yet.

- Plan and platform analysis: [`../../docs/engineering/COMMANDER_KEEN_PORT_FEASIBILITY.md`](../../docs/engineering/COMMANDER_KEEN_PORT_FEASIBILITY.md)
- Phase 0 evidence: [`../../docs/engineering/COMMANDER_KEEN_PHASE0_AUDIT.md`](../../docs/engineering/COMMANDER_KEEN_PHASE0_AUDIT.md)
- Roadmap: [`ROADMAP.md`](ROADMAP.md)
- Engine pin: [`upstream.lock.json`](upstream.lock.json)
- Attribution: [`THIRD_PARTY_NOTICES.md`](THIRD_PARTY_NOTICES.md)

## Layout

```text
ports/commanderkeen/
  upstream.lock.json        # pinned commit, tarball and file hashes, patch stack
  THIRD_PARTY_NOTICES.md
  engine/
    README.md               # build description and patch-stack rationale
    patches/                # minimal Emscripten delta (CMake, threads, main loop)
  platform-host/            # QA-only browser host that mounts local data at runtime
  scripts/
    resolve-upstream.mjs    # clone/verify the pin
    build-wasm.ps1          # reproduce the data-free WASM build
    serve-qa.mjs            # loopback QA server (host + wasm + local game data)
```

No original game data is committed. The QA host reads it from the ignored cache
at `.cache/ports/commanderkeen/keen4-v14-ega/`.

## Build (Windows, repository toolchain)

The pinned toolchain lives under `clients/web/.cache/` (Emscripten 6.0.9, CMake
4.4.3, Ninja 1.13.2). Reproduce the data-free build with:

```powershell
node ports/commanderkeen/scripts/resolve-upstream.mjs
powershell -File ports/commanderkeen/scripts/build-wasm.ps1
```

Output lands in `.cache/ports/commanderkeen/build-wasm/src/` (ignored).

## Run the QA spike

1. Put a complete Keen 4 v1.4 EGA set (the four required files
   `KEEN4E.EXE`, `EGAGRAPH.CK4`, `GAMEMAPS.CK4`, `AUDIO.CK4`) in
   `.cache/ports/commanderkeen/keen4-v14-ega/`.
2. `node ports/commanderkeen/scripts/serve-qa.mjs`
3. Open `http://127.0.0.1:8177/`.

The page fetches the game data and the engine's own `vfsroot` UI assets, mounts
them into the Emscripten virtual FS, and launches the engine with
`dir=games/keen4`, bypassing CG's launcher.

> The header/dictionary files (`EGAHEAD`, `EGADICT`, `MAPHEAD`, `AUDIOHED`,
> `AUDIODCT`) are embedded in the original `KEEN4E.EXE`; they are not separate
> files in a standard install. See the feasibility document §6.1.

## Data policy

Bring your own data. Nothing under `.cache/` is committed. Shareware
distribution and the GPL/App Store question both still need a license review.