Skip to content
OpenAgentSkill
Browsing is open · Catalog captured 2026-11-21 · Automatic updates and account services are paused.
Other skills

port-and-verify

Use when a byte-matched, exactly linked DOS decompilation with a working modding build is to become a native program for macOS, Linux or Windows that behaves exactly as the original - the portability layer, link stubs, the platform layer, assembly through a static recompiler and then readable C, and verification against DOS by record and replay, golden references and routine fuzzing; with the sound library for Miles AIL 2 games, the null-pointer plan, the host hazard audits (literals written through, null reads, reads past tables and frames) and the black box that records players' sessions.

abedegno · Static checks on file

Installation

Read the source and dependencies before running a command. Copying does not install or execute anything.

npx skills add abedegno/Exhume --skill port-and-verify

About this skill


name: port-and-verify description: Use when a byte-matched, exactly linked DOS decompilation with a working modding build is to become a native program for macOS, Linux or Windows that behaves exactly as the original - the portability layer, link stubs, the platform layer, assembly through a static recompiler and then readable C, and verification against DOS by record and replay, golden references and routine fuzzing; with the sound library for Miles AIL 2 games, the null-pointer plan, the host hazard audits (literals written through, null reads, reads past tables and frames) and the black box that records players' sessions.

Port and verify

Paths are relative to the Exhume checkout. docs/port.md is the method and the reasons; runtime/ is the porting harness every port builds against in place, never copied (runtime/README.md); examples/uw2/ has UW2's configuration, and Underworld Exhumed's uw2/src/port and uw2/src/include have UW2's bindings, the worked example. UW2's port (then UW2Decomp) went from Milestone 1 to Milestone 6a in about 21 hours this way (docs/case-study-uw2.md, "The port").

Before you start

  • The modding build works and its layout audit is done (skills/modding-build), and the readability pass has given you the gate (skills/readability-pass): every change to a shared source must pass tools/gate.py check, so the DOS bytes never change.
  • One tree, two builds. Port-only C goes in the port's directory, never in a game source; a shared-source change is a macro or type that is the original tokens under Turbo C. Add the port's directory to [project] exclude.
  • The runtime is a library. Never copy a runtime file into the project: the tools compile runtime/ where it is ([port] runtime; docs/port.md, "The runtime"), and the project writes only its bindings and its game's own C. A project with build scripts of its own finds the checkout as Underworld Exhumed's uw2/tools/exhume.py does and pins the Exhume commit it was proved with: best as a git submodule, as Underworld Exhumed does (exhume/), whose recorded commit CI checks out. A fix you find in the runtime goes into Exhume, proved on UW2 (examples/uw2/prove-port.sh) before the project moves its pin.

Steps

  1. Measure. Write the port's directory's portgame.h with at least your PORT_NAME and PORT_GAME_MAIN (runtime/README.md, "The project's side"), and a hookgame.h in the shared headers (empty until step 4); include portable.h from a shared header every source includes (the DOS build stages the runtime's beside yours). Fill in [port] (docs/config.md) and run tools/portcheck.py: per category, per file, and the names a link still needs.
  2. Compile and link. Fix the errors, then the warnings that matter, each change proved by the gate: near pointers in integers become NEARPTR; calls get prototypes (OLDSTYLE where callers push an int for a char); tools/widths.py rewrites declarations to explicit widths; tools/layoutcheck.py must show every file record identical ([port.layout]); tools/intaudit.py lists the promotion sites, and the ones that can leave 16 bits get casts; FAR_COPY and FP_OFF for the far pointer idioms. tools/portstubs.py writes link stubs and tools/portbuild.py links: the port now runs until the first stub.
  3. Platform and machine. The runtime's platform layer, paragraph map and far heap, EMS memory, VGA, Borland's library, records, crash handler, black box and game finder link as they are; give them what portgame.h names (DGROUP, _ctype, the exit chain, the black box: PORT_BLACKBOX and the calls in your main, runtime/README.md; the window's title and icon; what marks the game's folder), and write the C they call: port_load_exe and port_check_exe, port_game_nulls, the port's main and its diagnostics. If the game uses EMS, keep its own EMS entry points over emm_open, emm_map and emm_close. Load the far data no source defines from the user's own EXE at start-up, by the link's offsets; never ship it. Replace the system assembly (start-up, keyboard, mouse, timer) with C on the platform API. If the game draws its own cursor from relative motion, make the mouse driver steer it to the host's pointer (docs/port.md, "The platform layer": on each host move with absolute set, report the motion that puts the game's cursor at the pointer; none while it is still), and offer PlatConfig.mouse_lock for players who want DOSBox's captured mouse. First exit test: an opening screen whose scan-out equals a DOS screenshot of the same frame, pixel for pixel (hold both builds on it with a for (;;) in a modding build).
  4. Replay. Put a hook on every read of the outside world (GAME_TIME, KEY, MOUSE, MBUTTONS, JOY_*, WALL_TIME, SRAND, CHECKPOINT), with their original tokens in hookgame.h, write rpgame.h in the shared headers for runtime/replay/replay.c (which the replay DOS build and the port compile where it is), give [replay] link the modding link with --add, and fill in [replay]. tools/replay.py record a session in js-dos, replay it twice in DOS (replay.py dos, then compare --same-build): two DOS runs must agree before the port means anything. If they part, it is stack junk or an unhooked read: UWRPTRACE (or your trace variable) shows the call where they part; give the local STACK_JUNK(v), with v read from tools/match.py --dis on your own build, and record again. Then replay in the port and compare; mask only what is machinery ([[replay.mask]], with why), and compare far segments as blocks ([replay.segments]).
  5. Assembly. Modules that pass state in registers, patch themselves, discard return addresses or use divide faults as control flow go through tools/asm2c.py ([asm2c] spec and overrides, runtime/port/x86/asmrt with your asmgame.h in the port's directory and your asm_divfault; the overrides and asm_divfault are the game's code, so they live in the project, never in Exhume); commit the output and
Read the complete source ↗