dkc1-tools

DKC1Recomp

Static recompilation of Donkey Kong Country (SNES, USA v1.0) into a native desktop application, using the project's pinned snesrecomp fork framework — following the working DKC2Recomp project (same Rare engine family) as the template.

Status: playable bring-up. The project has 100% statically generated game code, a headless validation host, playable Windows and native macOS hosts, continuous audio, and an opt-in 342x224 widescreen presentation path. See docs/BRINGUP.md for the chronological bring-up record and docs/WIDESCREEN.md for the widescreen architecture, ported SuperZSNES findings, validation, and limitations.

Windows releases now include the Mac host's graphics, CRT/reconstruction, 16:10/16:9, remapping, Assist, music and mod controls in a dark native menu and settings panel. See Windows build, features and validation.

Windows v0.0.13 adds the optional Mods > Dixie Kong Country variant, including the map sprite fix. Keep both executables and SDL2.dll together; the same verified clean DKC1 ROM supplies either variant. See Dixie setup and tested scope. The accompanying Mac download is the unchanged v0.0.9 build and does not include Dixie or the v0.0.12 save fix.

Starting with v0.0.12 on Windows, Candy's in-game saves persist across launches. See save locations, recovery and validation.

A native iPhone/iPad frontend is available in v0.0.14, with full-screen landscape, transparent touch controls, Y/B thumb rolling and Y hold, Metal upscaling, stereo audio, controller support, ROM import and saves. The signed sideload IPA requires re-signing for the recipient's device. The release also retains the Windows v0.0.13 and Mac v0.0.9 downloads. See iOS build instructions and validated scope.

Why this game is a strong recomp candidate

Unlike most bring-ups, DKC1 does not need blind code discovery: the Yoshifanatic1 DKC1 disassembly (GPL-3) rebuilds the ROM byte-identically, and an IDA-based pipeline over it (in the disassembly repo under Tools/IDA/) provides:

• the exact start and size of every instruction (53,230 instructions / 126,790 bytes) derived from the asar symbol map — no heuristics;
• 1,276 function entries with proven entry M/X flag states;
• complete target lists for the indirect-dispatch sites, extracted from the disassembly's own dw jump tables (25 sites, 293 targets — including the 460-entry game-mode dispatcher and the animation-command table);
• ~90 semantically identified engine routines and RAM addresses.

tools/ingest_dkc1_disasm.py distills that into the per-bank CFG files in recomp/. DKC1 executes all code from banks 80-BF (low-RAM-mirror halves of HiROM); the cfg banks follow that layout.

Supported ROM

Headerless Donkey Kong Country USA v1.0:

The ROM must remain outside Git. No ROM bytes, extracted assets, or generated game code are committed.

For controlled testing of a data-only ROM produced by a level editor, the runtime can opt into one exact modified 4 MB payload. Set DKC1_ALLOW_ROM_SHA256 to that file's complete SHA-256 digest and pass the same file on the command line. This does not disable verification: a missing, malformed, or non-matching value is rejected, and the clean retail digest remains the only accepted default. Because the native game code was generated from the supported retail ROM, use this development override only for a patch whose changed ranges have been audited as data.

The macOS host also accepts DKC1_STARTUP_SCRIPT=/path/to/route.dks for editor playtests. It runs an input/wait-only deterministic route from clean power-on before showing the first interactive frame; save-state and checkpoint commands are rejected. RainbowZ combines this with an exact modified-ROM hash pin to open its generated Jungle Hijinxs level directly without a reusable save state.

Debugging and validation

The widescreen port is developed from byte-exact, deterministic evidence—not screenshots alone. docs/WIDESCREEN_DEBUG_TOOLS.md defines the native debug-tool roadmap, ordered from per-frame decision traces and replayable snapshots through object-lifecycle analysis and whole-game level sweeps. docs/WIDESCREEN_HANDOFF.md records the current evidence, hashes, open issues, and release gates. docs/HOST_PACING.md documents the Windows compositor clock, audio/save-state recovery, JSONL profiler, measured baselines, and the deterministic stall-recovery test.

Licensing and third-party code

Project-authored host and tooling code is MIT licensed. The pinned snesrecomp framework has its own PolyForm Noncommercial license and third-party notices. DKC structural metadata retains its documented GPL-3 disassembly provenance. See THIRD_PARTY_NOTICES.md.

Generate the recompiled sources

git submodule update --init --recursive
python scripts\generate_snesrecomp.py --rom "C:\private\dkc1.sfc"

Output lands in ignored generated/snesrecomp/. Regenerate recomp/*.cfg from the disassembly pipeline with:

python tools\ingest_dkc1_disasm.py --work "<disassembly>\Tools\IDA\work" --out recomp

Generation automatically runs the fail-closed widescreen override pass. It adapts only source-visible culling, object activation, and direct-OAM packing; logical camera, collision, exits, boss arenas, and tile streaming remain the cartridge program.

Build and run

With a Visual Studio developer environment available:

.\build_host.bat
.\build\dkc1_desktop.exe "C:\private\dkc1.sfc"

The desktop host enables widescreen by default. Set DKC1_WIDESCREEN=0 for the exact 256x224 presentation path. At a level's authored walls the 4:3 edge stays pinned at the wall and the inward view is released gradually over eight margins of travel, so nothing past the level is shown; View > Level Edge on macOS (or DKC1_WIDESCREEN_EDGE=reflect|bars|shift|glide) switches to a view locked to the camera with the terrain mirrored past the wall, black past the wall, or the earlier inward clamp. The headless validator accepts a frame count and supports deterministic input playback and private frame/state captures; its environment variables are documented in docs/BRINGUP.md.

macOS

Install CMake, Ninja, and SDL2, then provide the same verified ROM the first time private generated sources are needed:

brew install cmake ninja sdl2
./build_macos.sh "/path/to/Donkey Kong Country (USA).sfc"
open build/macos/DKC1Recomp.app

The arm64 app targets macOS 26 or newer, includes its SDL2 runtime, and opens a native ROM picker when launched without arguments; the ROM is never copied into the app. Keyboard controls match Windows (arrows, Z/X/S/A, Q/W, Return, Right Shift), and SDL game controllers are supported. F7 pauses, F8 steps, F9 exports an armed flight-recorder bundle, F11/F12 quick-save/load, and Option-Return toggles fullscreen. Native Game and View menus expose those commands plus checked 4:3, 16:10 (308x224), and 16:9 (342x224) aspect-ratio options, layer isolation, and provenance controls. DKC1_ASPECT=16:10 selects the Mac-oriented mode at startup. The Mac host presents SNES pixels at their 7:6 pixel aspect. Fullscreen uses the maximum undistorted fractional fit and offers three persistent host-only samplers: the default Sharp Bilinear keeps flat source-pixel interiors with an approximately one-output-pixel transition, Smooth (Linear) applies conventional bilinear filtering, and `Pixel Sharp (Ne