DKC2Recomp

DKC2Recomp

This recompilation is a byproduct of developing snesrecomp: the games are the proving ground, while the reusable framework is the larger goal. This is a community recompilation, not an official port. Please report any reproducible gameplay, video, or audio regressions.

Static recompilation of Donkey Kong Country 2: Diddy's Kong Quest for SNES into native desktop applications, using the snesrecomp framework. Windows and Apple-silicon macOS builds are available. The native Mac application includes an AppKit menu, Dock icon, platform user-data directory, and Mac-specific exact-rate frame pacing. It is ad-hoc signed; notarization remains open.

The 65816 game program is translated to native C where analysis can prove an exact entry state. The current profile emits 3,475 exact AOT variants and keeps two deliberate original-game fault variants on the shared 65816 interpreter. That interpreter remains available as a correctness and exceptional-path fallback. SNES hardware outside the main CPU—the PPU, SPC700/S-DSP, DMA/HDMA, controllers, and cartridge mapping—is modeled by the shared runtime.

Optional Donkey and Kiddy characters

Open the in-game pause menu with Escape, then choose Characters. Each original character slot can use Donkey Kong or Kiddy Kong; Donkey + Kiddy selects both, and Original pair restores Diddy and Dixie. The game remembers your choices between runs. Animal riders use mount-specific seated/hanging poses and attachment points. Hold Down + Y on the ground for Donkey's hand slap or Kiddy's body slam. Barrel carrying and throwing use each character's original style and timing. Neither replacement inherits Dixie's helicopter flight. Select plays a paired tag handoff when swapping Kongs. Donkey/Kiddy team pickup and throws use synchronized poses and shoulder/hand placement (private pack v5). Kiddy uses a seated recovery after a missed throw; regenerate earlier packs if he repeatedly snaps between hurt poses while waiting for the leader. Other movement/collision still uses DKC2's engine; this is not a complete DKC1/DKC3 mechanics transplant. Replacement animations freeze during Start or Escape pause. Re-import older packs for these changes.

Create the private character pack from your own Project Kongs checkout using the import instructions, then select Load character pack.... Game art is never included in this source tree or the app bundle.

Quick start

Windows release

1. Download DKC2Recomp-v0.0.8-Windows-x64.zip from Releases and extract the complete archive.
2. Run DKC2Recomp.exe.
3. In the Dear ImGui launcher, select your own legally obtained North American v1.0 ROM and choose Play.

DKC2RecompSDL.exe is the alternate SDL host. Keep the bundled DLLs and assets directory beside both executables. The archive also includes the character importer and MSU-1 setup guides; supply those packs separately.

The selected external path is remembered in rom.cfg beside the executable. The ROM is never copied into the release. Saves are written to saves/save.srm, with the previous clean save retained as save.srm.bak.

Windows menus and controls

Both Windows hosts include a dark Game / View / Input dropdown bar. Use Game for pause/resume and Quick Save/Load, View for aspect, scaling, level edges, screen filters and fullscreen, and Input to choose each player's Keyboard/Gamepad source or TEAM co-op policy. Changes apply while playing and persist in launcher.cfg. Alt+Enter toggles fullscreen; Escape leaves fullscreen when the overlay is closed, otherwise pauses/resumes. The bar returns on leaving fullscreen.

Default keyboard: arrows move; Z jumps (SNES B), A runs/rolls (Y), X is A, S is X, Q/W are L/R, Enter is Start and right Shift is Select. Player 1 defaults to keyboard, Player 2 to the first connected gamepad; select Gamepad for both players to assign two connected pads in order. Start+Back opens/closes the pause overlay without sending the chord to the game. Bindings and deadzones are editable in the launcher or in-game overlay. GDI supports both the native menus and the full ImGui pause/settings overlay; Reconstruct is available in SDL and native Windows OpenGL. GDI exposes its supported Nearest/Bilinear samplers. The menus reflect compiled shader capability.

CRT television, characters and MSU-1 music

Open Escape > Settings > Display > CRT television. Choose Living room, Studio monitor, Soft or Custom; adjust Scanlines, Sharpness, Phosphor mask, Mask strength, Glow, Halation and Curvature. Phosphor colors are separate. Native Windows OpenGL and SDL use identical CRT passes. Tube mode supplies its own scaling; Flat panel retains Reconstruct. GDI uses flat display.

The Characters tab offers Original, Donkey Kong and Kiddy Kong for each slot, Donkey + Kiddy, and Original pair. Load an external character pack as described in Project Kongs. Choices and pack paths persist in kongs.cfg. Original slot collision sizes and some movement rules remain; this is not a full DKC1/DKC3 move-set transplant.

Under Settings > Audio, choose an extracted MSU-1 music folder, enable Replacement music (MSU-1) and adjust Music volume. Standard dkc2_msu1-N.pcm tracks replace music while original sound effects remain. Missing tracks fall back to SNES music. The external folder preference is saved in msu1.cfg. No patched ROM or .msu marker is needed. See MSU-1 audio for state/rewind behavior and validation.

Unlocking every level in a save

scripts/dkc2_unlock_levels.py marks every real level of a save file as cleared, which opens every path on the world maps and every world whose boss it clears, and can open the Lost World and grant coins:

python3 scripts/dkc2_unlock_levels.py --save "$HOME/Library/Application Support/Flat2VR/DKC2Recomp/saves/save.srm" --rom /private/path/dkc2.sfc --file all --lost-world --kremkoins 75 --banana-coins 99 --snapshot "$HOME/Library/Application Support/Flat2VR/DKC2Recomp/saves/dkc2s0.sav"

It backs each file up beside itself first (.before-unlock, numbered when one exists). Quit the app before running it, since the app writes its own copy of the SRAM back on exit, and start from the file select afterwards. --lost-world marks every Klubba kiosk as paid, so Klubba lets the Kongs through without a toll, and records the five Lost World levels as beaten, which opens Krocodile Kore. --kremkoins sets the Kremkoin count the kiosks charge (15 each; the game holds 75). Banana Coins are not stored in the save file, the game zeroes them whenever it loads a file, so --banana-coins sets them only in the quick save named by --snapshot. The percentage is recounted by the game at its next save. --no-levels leaves the cleared flags alone, and --repair recomputes the header of a file the game shows as empty because its sums disagree while its data is intact.

Native macOS release

1. Download DKC2Recomp-v0.0.6-macOS-arm64.zip from Releases and extract it.
2. Open DKC2Recomp.app and select your own legally obtained North American v1.0 ROM. The ROM remains outside the application bundle.

The v0.0.6 Mac archive is an ad-hoc-signed Apple-silicon build and is not notarized. It adds the CRT television display, the Retina pause-menu fix, and the optional Donkey/Kiddy character slots. The v0.0.8 release carries this Mac archive unchanged alongside the new Windows build; the Mac binary does not contain the new simultaneous co-op or MSU-1 support. If Gatekeeper quarantines the downloaded archive, open the app from Finder with Control-click > Open and confirm once.

Native macOS source build

Install Xcode Command Line Tools, CMake, Ninja, Python 3, Rust/Cargo, and SDL2, then run:

./build_macos.sh "/private/path/to/DKC2-USA-v1.0.sfc"
open build/macos/DKC2Recomp.app

The resulting application is build/macos/DKC2Recomp.app. It bundles its SDL2 dynamic library, carries the project icon, is ad-hoc signed, and stores ROM selection, launcher settings, SRAM, save states, and diagnostics under ~/Library/Application Support/Flat2VR/DKC2Recomp. The private ROM remains at its original path and is never copied into the application bundle.

Supported ROM

The launcher and runtime verify the ROM after removing an optional 512-byte copier header.

Property	Expected value
Size	4,194,304 bytes (headerless body)
CRC32	006364DB
SHA-256	35421a9af9dd011b40b91f792192af9f99c93201d8d394026bdfb42cbf2d8633
Internal name	DIDDY'S KONG QUEST
Region/version	North America v1.0

You must supply your own lawfully obtained dump. ROMs, extracted in-game graphics, music, level data, save files, and generated ROM-derived C are not distributed in this repository or its release archives. The launcher includes North American retail cover art solely to identify the supported game and region; its source and copyright notice are documented in recomp/launcher/README.md.

Semantic symbols for development

Reverse-engineering knowledge is kept outside the generated C. recomp/symbols.toml assigns reviewed names, aliases, confidence, provenance, tags, and notes to stable USA v1.0 CFG addresses. recomp/layouts.toml records confirmed WRAM objects and fields. docs/SYMBOL_DATABASE.md is the generated readable index.

After editing either TOML file, validate and regenerate with Python 3.11+ (or Python 3.9/3.10 with tomli):

python scripts\build_dkc2_symbol_database.py --apply-cfg
python scripts\build_dkc2_symbol_database.py --check
python scripts\lookup_dkc2_symbol.py banana

The build tool imports all 3,314 structural CFG entries into an ignored JSON index at .cache/dkc2-symbols.json, updates only exact-address CFG names, and generates the constants consumed by widescreen diagnostics. Generated game C remains ignored and must still be rebuilt from the user's verified ROM.

Widescreen route auditing

The experimental 16:9 path includes an automatic deterministic route auditor, not only single-frame screenshots. scripts/audit_widescreen_route.py replays composite/BG/OBJ layers and correlates them with camera state, exact world-keyed terrain entries, margin-source provenance, and placed-object lifetimes. Its HTML/JSON report flags raw rolling-VRAM fallback, missing terrain replaced by transparent tiles, terrain identity changes, old-edge seams, object spawn/despawn near the former 4:3 boundary, and active margin objects with no OBJ pixels.

The trace also proves, for each sampled frame, how many expanded-margin cells were requested, present, and equal to the static level source. A newer cartridge tilemap write is treated as authoritative rather than compared with a later animation phase. Verified transparent fallback is retained in a separate safe-observation section; it is not counted as an actionable defect. Object lifetime conclusions require --step 1.

Start with a coarse --step 4 route, then rerun a short suspicious interval at --step 1. All generated evidence belongs under ignored .cache/ or an external private test directory. See docs/WIDESCREEN_DIAGNOSTICS.md for commands, confidence meanings, storage costs, and limitations.

Default controls

Action	Keyboard	Controller
D-Pad	Arrow keys	D-Pad
A / B	X / Z	B / A
X / Y	S / A	Y / X
L / R	Q / W	Left / right shoulder
Start / Select	Enter / Right Shift	Start / Back
Rewind	Hold 1	Left trigger
Fast-forward	Hold 2	Right trigger
Save state (selected slot)	F5	Unbound
Load state (selected slot)	F9	Unbound
Toggle performance log	F	—
Open/close overlay	Escape	Guide or Start+Back

Each player's Configure page in the pre-boot launcher and the in-game Controls tab edit the real keyboard and standard-controller mapping consumed by both playable hosts. Rewind and Fast-forward also appear there as global Assist shortcuts. The top-level Assist Tools page edits Rewind, Fast-forward, Save State, and Load State keyboard/controller bindings. Press a binding chip and then the desired key, controller button, or controller axis. All mappings persist in launcher.cfg; per-player and Assist reset buttons restore the defaults above.

The launcher exposes independent Player 1 and Player 2 source selectors. By default the keyboard controls Player 1 and the first connected gamepad controls Player 2. The accepted Windows host uses XInput; the portable host uses SDL GameController. Players set to Gamepad receive connected devices in player order, so two gamepads drive the two SNES controller ports independently. Source, deadzone, and binding choices persist in launcher.cfg.

Two-player co-op

Selecting "2 PLAYER TEAM" in the game's own menu used to alternate control: one Kong was player-controlled while the other followed by AI, and control passed only when a Kong was hit or swapped. The port now makes TEAM mode simultaneous by default: controller 1 always drives the first Kong slot and controller 2 always drives the second, so both players play at the same time, each with their own Kong. The second Kong stands by (and auto-catches-up when separated) until player 2 first touches their controller, then stays fully playable, including after landing. Both players use normal bright colors and can attack enemies; Player 2's roll, stomp and bounce are covered by a private first-level replay, along with contact damage and a Player 1 attack regression. Roll/stomp recovery restores walking and jumping. Held barrels follow and launch from their owner, including throws across different platform heights. Either player can walk up to their partner and press SNES A (keyboard X by default) to carry them. Pickup requires both Kongs on foot and within 24 game pixels horizontally and 16 vertically. Press A again to put them down, or Y to throw them. The carrier keeps their own controls; both players regain independent movement after release. Diddy/Dixie and Donkey/Kiddy checks cover near/far pickup, carrying, drop/throw and save/load. Each player can grab and climb ropes independently, with climbing animations in both directions. Single/double-rope junctions complete normally, including when loading a save already stuck at the end of a transition. The Topsail Trouble regression covers Player 2 attaching, both players climbing in opposite directions, save/load and jumping to the neighboring rope. To repeat it with the private reported snapshot, configure DKC2_COOP_ROPE_STATE with its external path and run the supplied_rom_coop_ropes CTest check. Adding DKC2_COOP_ROPE_JUNCTION_STATE enables the second reported checkpoint's double-rope animations, side exits and transition save/load checks. It also checks crossing the entire net and reversing direction to reach both outer ropes without repeating the turning animation in place. A hurt Kong completes its departure and waits for a DK barrel; pressing its controls or loading a save cannot revive it. The survivor continues without the original TEAM turn-taking prompt. A DK barrel restores independent control. Private checks cover both Kong roles after a leader swap and save/load across loss, revival and a second loss. Either player can mount Rambi; the rider becomes the camera leader and keeps their own controller. The other Kong retains on-foot movement. Private checks cover riding, jumping, dismount/remount, passing Rambi from P1 to P2 and loading while mounted. Death handoff keeps the survivor in place and resumes enemies. Both players can collect banana trails while the other rides Rambi; overlapping hitboxes and revisiting collected bananas after save/load award each only once. Both Kongs can move into the visible side areas in 16:10 and 16:9, with the level walls retained. The camera still follows the active Kong; this is shared-camera local co-op. Full-game death/respawn, other animal types and special throwables remain unverified. The "2P Team mode" choice in the overlay's Settings page (or CoopMode in launcher.cfg, or DKC2_COOP=simultaneous|classic) restores the classic alternating behavior; 1 PLAYER and "2 PLAYER CONTEST" are never affected.

In-game overlay and Assist Tools

Press Escape during gameplay to pause on a completed frame boundary and open the Dear ImGui overlay. In a fullscreen SDL/Mac game window, the first Escape returns to windowed mode without also opening the overlay; Escape then retains its normal overlay behavior. The SDL host also accepts the controller Guide button; Start+Back is the portable fallback. The overlay provides Resume, Settings, Controls, Assist Tools / Cheats, Credits, and Quit. Gameplay input and audio are paused while it is open. Its first placement is centered from ImGui's logical display size, including on Retina/high-DPI windows, and the title bar can then be dragged to reposition it.

The Settings page exposes the launcher's display, audio, filtering, screen model, widescreen, skip-launcher, and Restore Defaults choices. Volume, widescreen, texture filtering, screen model, Player 1/2 source/deadzone, and the Assist gate apply immediately; window scale, fullscreen mode, renderer, audio enable, and skip-launcher take effect on the next launch. The shared sample-rate choice is mirrored and persisted, but this host currently outputs the SNES-native 32,040 Hz only. The Controls page has Player 1, Player 2, Assist, and Fixed Shortcuts tabs. Player tabs expose source, deadzone, and all 12 SNES keyboard/controller bindings. The Assist tab edits Rewind, Fast-forward, Save State, and Load State bindings. Select a binding and press the replacement key, controller button, or axis; controller capture waits for a neutral release first to avoid recording the button that opened the editor. Changes apply immediately and are written to launcher.cfg on clean exit. Per-player and Assist reset buttons restore only their respective control defaults. Escape cancels an active capture; the menu and performance shortcuts are listed read-only so they cannot be made unreachable.

Rewind, fast-forward, the overlay's five save-state slots, and every configured Assist shortcut are intentionally gated behind Enable Assist Tools / Cheats. This setting defaults off, persists as AssistTools in launcher.cfg, and adds (Assist Tools: On) to the game window title. On the native Mac app, the Game menu's fixed Quick Save State and Quick Load State commands always operate Slot 1, even when Assist Tools are disabled.

The overlay is available in the Windows OpenGL and GDI presenters and the SDL/OpenGL host. GDI draws ImGui through an SDL software renderer into the completed game buffer before presentation, so Escape and Game > Settings / Controls work with the compatibility renderer too.

The pre-boot launcher now also has top-level Assist Tools and Credits sections beside Settings. Credits text is supplied by this project rather than hardcoded in recomp-ui.

The Settings page has a fixed Restore Defaults button. After confirmation, it restores the complete DKC2 launcher configuration: window/display choices, audio, controller sources/deadzones/bindings, Assist bindings, and the skip-launcher preference. The selected ROM, cartridge SRAM, save states, and rewind history are not deleted or replaced. The restored choices are persisted when Play is pressed.

Video settings

The launcher defaults to the OpenGL presenter with nearest-neighbor sampling and the Raw screen model. Raw is a byte-exact presentation bypass. The opt-in CRT, Composite, and Trinitron choices apply the present-time scr