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.

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.

  1. Put the disc image in rom/: the .cue and both track .bin files (Redump layout: Alien Gate (USA) (Rev 1).cue, (Track 1).bin, (Track 2).bin).
  2. Run build.bat. It extracts the program modules from the disc, recompiles them into gen/, builds with MSVC and copies aliengate.exe to the project root.
  3. Run aliengate.exe. It finds the image in rom/ next to it (or pass the path of the .cue as 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.

ActionKeyboardGamepad (XInput)
MoveArrow keys (hold Shift for faster)Left stick / D-pad
Button 1 (fire / select)Z, Space, AA
Button 2X, Ctrl, SB, Y
Both buttonsC, EnterX, Start
Fast-forwardTab (hold)
Quicksave / next slot / quickloadF2 / F3 / F4
Invincibility on/offF5
Run-ahead (off, 1-4 fields)F6
Sprite interpolation on/offF7
Aspect ratio / filterF9 / F10
FullscreenF11 or Alt+Enter
QuitEsc

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 .cue sheets 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.l stubs 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 to saves/missed_entries.txt for game.json.
  • Several modules per file: CMDS/cdi_bp holds three modules (cdi_bpsys, cdi_vsync, cdi_vsync_trap); game.json entries take an offset. All five modules the game runs are recompiled.
  • Concurrent processes: the game forks a cdi_vsync helper that runs alongside it. Processes are pure 68000 state: a process blocked in a system call is parked at PC_BLOCKED with 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, and trap #n enters 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

PathContents
game.jsonModules to recompile, their load addresses and extra entry points
tools/cdi_extract.pyGreen Book filesystem reader (.cue, multi-track, scrambled sectors). Writes program files and _app.txt (--all also dumps the real-time streams).
tools/m68k.pyMC68000 decoder
tools/os9mod.pyOS-9 module header, idata and irefs (program, subroutine and trap modules)
tools/analyze.pyCode discovery: recursive descent, switch tables, A5/A6 stub tables, function pointers, speculative decoding
tools/gen.py68000→C generator, flag liveness, dispatch tables, gen/game_config.h
tools/config.pygame.json loader
tools/gen_tests.pyPer-instruction differential tests
tools/bmp2png.pyConverts frame dumps to PNG
runtime/cpu.cDispatcher and run loop (falls back to the interpreter for undiscovered code)
runtime/interp.c68000 interpreter, for RAM code and the --interp reference mode
runtime/alu.cShifts, division and BCD with exact flags
runtime/os9.cOS-9 kernel: memory, processes, signals, alarms, events, trap handlers, paths, NVRAM, CSD (all state in one snapshot-able structure)
runtime/ext.cDriver extension modules (system-state code), native hooks, sandboxed calls into 68k routines
runtime/frame.cFrame loop: one field at a time, snapshots, quicksave slots, run-ahead, on-screen messages
runtime/snapshot.hSnapshot interface: each module serializes its state with snap_bytes()
runtime/cheats.cInvincibility (Alien Gate specific)
runtime/interp_frames.cSprite interpolation (Alien Gate specific, uses the hooks in game.json)
runtime/cdfm.cCD file manager: reads, real-time SS_Play with PCB/PCL/CIL, SS_CDDA
runtime/disc.cDisc image access: .cue tracks, descrambling, directory paths
runtime/video.cUCM display control (FCT/LCT), MCD212-style renderer, cursor, pointer
runtime/audio.cADPCM levels A/B/C, sound maps with gapless SM_Out, CD-DA mixing, attenuation
runtime/render_d3d11.cGPU presenter: aspect modes and sharp/smooth/CRT filters
runtime/host_win32.cWindow, input (keyboard and XInput), hotkeys, waveOut, pacing, scripted and fuzz input
test/Instruction differential tester and ALU reference vectors
docs/CDI_NOTES.mdCD-i facts and API codes worked out during the ports

Using this as a template for another game

  1. Copy the folder, put the disc image (.cue + .bin files) in rom/.
  2. Edit game.json: title, exe_name and the modules.
  3. 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 base address, and the runtime places the file there. Ranges must not overlap and must stay below 0x140000, where the heap starts. Modules that are not listed still run, more slowly, in the interpreter.
  • offset selects a module inside a file that holds several. base is then the module's own address: the file's base plus the offset.
  • extra_entries are code addresses the analyzer can't discover, as absolute hex values. Copy them from saves/missed_entries.txt after playing.
  • a5_table: "auto" detects programs built with Apple MPW-style toolchains (jsr N(a5)). Microware C's jsr d16(a6) stubs are always handled.
  • hooks (optional): instruction addresses before which the runtime's game_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 --interp comparison 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 / --trace3 log syscalls with callers, process switches, signals, display calls and disc activity.
    • --headless --frames N --dump K runs fast without a window and writes every Kth frame as a BMP.
    • --vdump N logs the display programs, CLUT and decoder state at field N.
    • --dump-from N starts --dump at field N; --ramdump f1,f2,... writes the live RAM to saves/ram_<field>.bin after those fields (diff dumps to find game variables); --watch ADDR with --interp logs every write to ADDR with the pc; --shot N file.bmp saves the GPU output of field N (windowed).
    • Script keys S, O, N, I, P press quicksave, quickload, next slot, invincibility and sprite interpolation once at that field.
    • --script "field:key:dur,..." scripts input (keys 1 2 L R U D).
    • --fuzz SEED drives the game with random input, from field --fuzz-from N on (use a script to get past the menus first).
    • --wav out.wav records the audio (give a path outside saves/).
  • 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.py and python test/gen_alu_vectors.py generate 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() in frame.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.