Alien Gate static recomp
Alien Gate static recomp is a Windows port of Alien Gate for the Philips CD-i with quicksave and invincibility features.
- Type: PC port
- Game: Alien Gate
- Runs on Windows
- By tools81
- Latest release v1.0.0, 2026-11-17
- Source: https://github.com/tools81/alien-gate-static-recomp
README
Alien Gate — CD-i static recompilation
A native Windows port of Alien Gate (Philips CD-i, 1993). The game's 68000 code is translated ahead of time into C and linked with a runtime that provides the parts of the CD-i the code expects: the CD-RTOS (OS-9) kernel, the CD file manager, the UCM video driver (with a Direct3D 11 presenter), the ADPCM audio processor and CD-DA playback.
The game data is not included. You need your own disc image.
Building
Requirements: Windows 10+, Visual Studio 2022 (C compiler), CMake 3.19+ and Python 3.8+. No third-party libraries are needed.
- Put the disc image in
rom/: the.cueand both track.binfiles (Redump layout:Alien Gate (USA) (Rev 1).cue,(Track 1).bin,(Track 2).bin). - Run
build.bat. It extracts the program modules from the disc, recompiles them intogen/, builds with MSVC and copiesaliengate.exeto the project root. - Run
aliengate.exe. It finds the image inrom/next to it (or pass the path of the.cueas an argument).
Saves (the high-score table in NVRAM), settings and the log go to saves/
next to the executable.
Controls
The CD-i thumbpad drives an on-screen pointer, which also steers the ship.
| Action | Keyboard | Gamepad (XInput) |
|---|---|---|
| Move | Arrow keys (hold Shift for faster) | Left stick / D-pad |
| Button 1 (fire / select) | Z, Space, A | A |
| Button 2 | X, Ctrl, S | B, Y |
| Both buttons | C, Enter | X, Start |
| Fast-forward | Tab (hold) | |
| Quicksave / next slot / quickload | F2 / F3 / F4 | |
| Invincibility on/off | F5 | |
| Run-ahead (off, 1-4 fields) | F6 | |
| Sprite interpolation on/off | F7 | |
| Aspect ratio / filter | F9 / F10 | |
| Fullscreen | F11 or Alt+Enter | |
| Quit | Esc |
Video options can also be given on the command line: --aspect N,
--filter N (0 sharp, 1 smooth, 2 CRT, 3 nearest, 4 Cartoon HD,
5 Cartoon HD+), --fullscreen, --windowed, --size WxH, --gdi,
--runahead N. Messages for these keys appear in the top-left corner.
Settings are remembered in saves/settings.ini.
Enhancements
- Quicksave (F2 save, F4 load, F3 next slot): 10 slots holding the
complete machine state, kept in memory and in
saves/state_<n>.sav(about 2 MB each). Slot files only load into the same build of the program they were saved with. - Invincibility (F5): hits on the player's ship are ignored, so it is never destroyed. The game itself is otherwise unchanged (the spawn shield still runs out as usual) and enemies are unaffected.
- Run-ahead (F6, default 2 fields): each displayed frame is computed a few fields ahead with the current input and then rolled back, which removes that much of the game's built-in input lag. Sound always comes from the real timeline. It costs about 1 ms per extra field.
- Sprite interpolation (F7, on by default): the game updates its picture at 20 frames per second. On the fields in between, every sprite is redrawn with the game's own drawing routines at a position between the last two frames, so motion is smooth at 60 fps. This shows sprites up to two fields late, which run-ahead compensates for. Objects that jump far (teleports, respawns) are not interpolated. The background scrolls one line per game frame, the finest step the display has, so it is left as is.
- Cartoon HD / Cartoon HD+ filters (F10): Cartoon HD smooths the game's pixel edges into clean curves with an edge-directed upscaler while keeping flat colour areas crisp. Cartoon HD+ adds a cel-shaded look: ink outlines on strong edges, light colour banding and more saturation.
None of these features changes the game when it is off. Sprite interpolation and the filters only affect what is shown: test runs with them on produce exactly the same game state and audio as runs without.
What this disc needed (beyond the template)
The project started from the CD-i template extracted from the Link: The Faces of Evil port. Alien Gate differs from Link in almost every system-level respect, so the template gained these capabilities:
- Disc image: the CD-i track is in the pregap of an audio track, so the
dump stores its data sectors scrambled. The disc readers (Python and C)
read
.cuesheets with several track files as one run of sectors and descramble sectors on the fly. All files carry file number 1, so real-time streams are recognised from their subheaders instead. - Microware C code: calls go through
jmp abs.lstubs in static storage (jsr d16(a6)). The analyzer reads them from the idata/irefs, as well as function-pointer tables, and speculatively decodes code reached only through computed pointers. Code that is still undiscovered runs in the interpreter instead of aborting, and is logged tosaves/missed_entries.txtforgame.json. - Several modules per file:
CMDS/cdi_bpholds three modules (cdi_bpsys,cdi_vsync,cdi_vsync_trap);game.jsonentries take anoffset. All five modules the game runs are recompiled. - Concurrent processes: the game forks a
cdi_vsynchelper that runs alongside it. Processes are pure 68000 state: a process blocked in a system call is parked atPC_BLOCKEDwith a resume address (translated code always unwinds to the dispatcher), and the scheduler switches processes at blocking calls and yield points. F$Fork, F$Wait, F$Exit, F$Sleep and F$Event (events, used for the display handshake) are implemented accordingly. Because no process ever holds a host stack, the whole machine can be snapshotted between fields. - Trap handler modules: F$TLink links
cdi_vsync_trap, andtrap #nenters it with the OS-9 calling convention. - Driver extension: the game installs
cdi_bpsys(the Balboa pointer system) into the video and pointer drivers. Its real code runs in a synthetic driver context with native callbacks into the HLE drivers, and its system-state alarm runs every field. - CD-DA music (SS_CDDA), DC_NOP, I$ChgDir, SM_Close as function 4,
the video driver's
line_event.
Validation: headless runs of the recompiled build and of the pure
interpreter (--interp) produce bit-identical frames and audio, over menu,
gameplay, game over and high-score sequences.
Layout
| Path | Contents |
|---|---|
game.json | Modules to recompile, their load addresses and extra entry points |
tools/cdi_extract.py | Green Book filesystem reader (.cue, multi-track, scrambled sectors). Writes program files and _app.txt (--all also dumps the real-time streams). |
tools/m68k.py | MC68000 decoder |
tools/os9mod.py | OS-9 module header, idata and irefs (program, subroutine and trap modules) |
tools/analyze.py | Code discovery: recursive descent, switch tables, A5/A6 stub tables, function pointers, speculative decoding |
tools/gen.py | 68000→C generator, flag liveness, dispatch tables, gen/game_config.h |
tools/config.py | game.json loader |
tools/gen_tests.py | Per-instruction differential tests |
tools/bmp2png.py | Converts frame dumps to PNG |
runtime/cpu.c | Dispatcher and run loop (falls back to the interpreter for undiscovered code) |
runtime/interp.c | 68000 interpreter, for RAM code and the --interp reference mode |
runtime/alu.c | Shifts, division and BCD with exact flags |
runtime/os9.c | OS-9 kernel: memory, processes, signals, alarms, events, trap handlers, paths, NVRAM, CSD (all state in one snapshot-able structure) |
runtime/ext.c | Driver extension modules (system-state code), native hooks, sandboxed calls into 68k routines |
runtime/frame.c | Frame loop: one field at a time, snapshots, quicksave slots, run-ahead, on-screen messages |
runtime/snapshot.h | Snapshot interface: each module serializes its state with snap_bytes() |
runtime/cheats.c | Invincibility (Alien Gate specific) |
runtime/interp_frames.c | Sprite interpolation (Alien Gate specific, uses the hooks in game.json) |
runtime/cdfm.c | CD file manager: reads, real-time SS_Play with PCB/PCL/CIL, SS_CDDA |
runtime/disc.c | Disc image access: .cue tracks, descrambling, directory paths |
runtime/video.c | UCM display control (FCT/LCT), MCD212-style renderer, cursor, pointer |
runtime/audio.c | ADPCM levels A/B/C, sound maps with gapless SM_Out, CD-DA mixing, attenuation |
runtime/render_d3d11.c | GPU presenter: aspect modes and sharp/smooth/CRT filters |
runtime/host_win32.c | Window, input (keyboard and XInput), hotkeys, waveOut, pacing, scripted and fuzz input |
test/ | Instruction differential tester and ALU reference vectors |
docs/CDI_NOTES.md | CD-i facts and API codes worked out during the ports |
Using this as a template for another game
- Copy the folder, put the disc image (
.cue+.binfiles) inrom/. - Edit
game.json:title,exe_nameand the modules. - Run
build.bat, then run the game and follow the debugging workflow.
game.json
{
"title": "Alien Gate",
"exe_name": "aliengate",
"modules": [
{"file": "auto", "base": "0x100000", "extra_entries": [], "a5_table": "auto"},
{"file": "CMDS/cdi_bp", "base": "0xF0000", "extra_entries": [], "a5_table": false},
{"file": "CMDS/cdi_bp", "offset": "0x1086", "base": "0xF1086", "extra_entries": []}
]
}
- The first module is the program the player boots.
"auto"reads its path from the disc label's application identifier (extracted/_app.txt). - Other modules are programs, subroutine modules or trap handlers the
game loads at run time (F$Load, F$Link, F$Fork, F$TLink). Each one is
recompiled for its
baseaddress, and the runtime places the file there. Ranges must not overlap and must stay below0x140000, where the heap starts. Modules that are not listed still run, more slowly, in the interpreter. offsetselects a module inside a file that holds several.baseis then the module's own address: the file's base plus the offset.extra_entriesare code addresses the analyzer can't discover, as absolute hex values. Copy them fromsaves/missed_entries.txtafter playing.a5_table:"auto"detects programs built with Apple MPW-style toolchains (jsr N(a5)). Microware C'sjsr d16(a6)stubs are always handled.hooks(optional): instruction addresses before which the runtime'sgame_hook(addr)is called, in translated and interpreted code alike. Alien Gate hooks its 18 sprite-draw dispatch sites for sprite interpolation, and the player's hit test for invincibility. A hook runs the same way in translated and interpreted code, so the--interpcomparison still holds.
To see what the analyzer found, run python tools/analyze.py [module index].
It writes a disassembly to build/listing_<module>.asm.
Debugging workflow
-
Find what fails. Unimplemented OS calls, SetStat/GetStat codes and DC functions are logged to
saves/recomp.log. Fatal errors also show a 68k register dump and a stack backtrace with function names. -
Debug options:
--trace/--trace3log syscalls with callers, process switches, signals, display calls and disc activity.--headless --frames N --dump Kruns fast without a window and writes every Kth frame as a BMP.--vdump Nlogs the display programs, CLUT and decoder state at field N.--dump-from Nstarts--dumpat field N;--ramdump f1,f2,...writes the live RAM tosaves/ram_<field>.binafter those fields (diff dumps to find game variables);--watch ADDRwith--interplogs every write to ADDR with the pc;--shot N file.bmpsaves the GPU output of field N (windowed).- Script keys
S,O,N,I,Ppress quicksave, quickload, next slot, invincibility and sprite interpolation once at that field. --script "field:key:dur,..."scripts input (keys1 2 L R U D).--fuzz SEEDdrives the game with random input, from field--fuzz-from Non (use a script to get past the menus first).--wav out.wavrecords the audio (give a path outsidesaves/).
-
Check the translation. Run the same headless session twice, once with
--interp, and compare the frame dumps and WAVs. Headless runs are deterministic: emulated time is counted in instructions and the clock uses a fixed epoch. -
Unit-level checks.
python tools/gen_tests.pyandpython test/gen_alu_vectors.pygenerate test sources. Then:cmake --build build\cmake --config Release --target insn_test alu_test build\cmake\Release\insn_test.exe "rom\<image>.cue" 200 build\cmake\Release\alu_test.exe
Known limitations
- UCM drawing functions (DM_/DP_/DR_/RG_ and text) are not implemented; Alien Gate draws everything itself.
- PAL titles and Full Motion Video (MPEG cartridge) are not supported.
- Run-ahead and quicksave need every piece of runtime state to be in a
snapshot. A new module must add its state to
snapshot_all()inframe.c; test with--runahead N --dump N, whose frames must equal the frames N fields later of a run without run-ahead (while input does not change), with identical audio. - Process scheduling is cooperative with preemption at yield points, not priority-based time slicing.