khdays-port

A native PC port of Kingdom Hearts 358/2 Days, built on khdays-decomp.

The game is the decompilation's C, compiled for the PC; the port supplies what the Nintendo DS hardware did underneath it -- graphics, sound, input, the card, interrupts and the system calls of its SDK -- and, around it, what a PC version wants: modern controls, rendering, resolutions, a single-screen mode and replaceable content. This is how other decompilation-based ports work: the game code is the original's, readable and moddable; the platform layer is new.

[!IMPORTANT] This repository contains no ROM, game assets, audio, video, text, SDK files or game binaries. You need your own legally obtained copy of the game.

[!WARNING] The port is a work in progress and may have bugs. Reports are very welcome, in the issues or on Discord: what happened and what you were doing when it did.

AI-assisted coding tools were used to help make this possible.

Status

The whole game runs natively from the decompilation: the title and its menus, Story Mode (opening movie, days, cutscenes, the field), Mission Mode (character select, camp, missions, results), combat and magic, the shop, and a player's save loaded, played and saved again. Crashes found while playing are fixed as classes in the build's source preparation, and what they show about the C goes back to the decompilation (docs/DECOMP_FINDINGS.md).

Today it builds for Windows x64 (64-bit). It plays with the keyboard, the mouse or a gamepad, with remappable controls and optional enhancements (an analog camera among them). The picture is the port's own: the 2D composed by the port on the graphics card from what the game asks for, and the 3D's geometry answered by the port and drawn there too -- at up to eight times the DS's resolution, in widescreen, and with HD textures, models and 2D graphics from mods; the DS's own engines remain only as the reference the port is checked against. The sound is the port's own: the ARM7's sound driver in C, mixed at the PC's rate, with its own volumes and every sound replaceable from mods. So are the movies: decoded by the port, shown at full colour, their sound at its own volume, each replaceable by a video from a mod. No machine code of the DS runs: the port has no ARM interpreter, and what the decompilation keeps as assembly and the game calls is C the port wrote from it. The game's files reach it from the port as well: each read copied at once from a mod's file or the extracted data, with no card in between (the emulated card stays as the reference). The game's time is the port's too: its frames, its tick and alarms on the PC's clock, its interrupts taken where the game waits or unmasks them, nothing simulating the DS's timers or its display; and the 3D is drawn at the monitor's refresh rate, between the game's frames, which still come 30 a second as on the DS. The game's memory is the port's: a range Windows places, with each DS region at its DS address from its start, the game's pointers kept as references into it -- the DS's own addresses hold nothing. The HUD, the menus and the game's text are drawn anew by the port, each element placeable. Underneath, the game still sees a DS -- two screens one above the other, and the ARM7's services, which the port answers on the PC: the clock from the PC's, the save from its files.

On top of the game, a new edition from content the user provides: HD textures, models and 2D graphics, new rooms, sounds and videos, a single-screen mode, and Mission Mode's multiplayer.

Restored from what the game left unfinished: Stop, its sixth magic (Stop, Stopra and Stopga; in Spanish Paro, Paro+ and Paro++). Days kept its effect, its animations and its names in two languages, but no panels, no words and no code that casts it; the port casts it with the game's own pieces and makes the rest: enemies in its reach stand still for a time that grows with its level, and the damage they take meanwhile lands at once as it ends. Its panels show in the deck and the camp with an unused clock picture of the game's, take Magic LV and Doublecast like the other magics, are made at the moogle's shop (dearer than any other magic) and work in multiplayer, where with friendly fire on Stop also holds the other players. Its numbers, prices, recipes and words are in an open file, port/runtime/battle/stop_magic.txt. It is on unless turned off in Settings → General → Stop magic ([gameplay] stop_magic = off, read as the game starts): the game is then the DS's, and a save's Stop panels stay in it, unseen, until it is on again. In a room every player must have it the same.

Planned: the port on other systems -- Linux first, then, from one ARM64 build, macOS, Windows on ARM and the Nintendo Switch.

Installing

On Windows, the installer from the releases page is all you need besides your own copy of the game: it asks for your ROM (the European release of KINGDOM HEARTS 358/2 Days; it finds it by itself where KH Melon Mix keeps one in your KINGDOM HEARTS HD 1.5+2.5 ReMIX folder), prepares the game's data from it, and can also make the HD pack from your HD collections, add the port to Steam (PC and Steam Deck), and install the mod studio. Nothing of the game comes with it. The port tells you when a newer release is out, and its Download updates your copy by itself: it fetches the new installer, checks it, closes the game, updates it with your choices (Windows asks for the administrator's permission) and opens it again. More: installer/README.md.

Getting started

To build the port from source instead:

1. Check and extract your copy of the game (Python 3.11+):

powershell py .\tools\verify_rom.py "E:\path\game.nds" py .\tools\extract_data.py "E:\path\game.nds"

The data goes to data/extracted/<hash>/, which is never committed.

2. Build (Windows, Visual Studio 2026 with the C++ workload, CMake, Ninja, and for the preparation Python's pycparser):

powershell py -m pip install pycparser py .\port\build.py --config Release

port/tools/prepare.py generates the build's sources from the decompilation -- the game's C rewritten with every pointer a reference (build/port/gen-x64); the executable is build/port/obj-release-x64/khdays-native.exe (--config Debug: build/port/obj-x64/).

3. Run it from the repository root, so it finds data/ and keeps the save in saves/khdays.sav:

powershell .\build\port\obj-release-x64\khdays-native.exe 2> khdays.log

The runtime reports to stderr; 2> keeps it for a bug report. Started without the data (or with it incomplete), it says so in a message box in the system's language, with the folder it looked in.

The save is the DS's backup memory as a file, in the same format as a DS save (a 64 KB raw backup), so a save from the DS loads. It is written whole each time the game saves -- a new file beside it, then put in its place -- so a crash of the game or the PC while saving leaves the save as it was before, or as it is after, never half of one.

4. When something seems wrong -- music late, the game stopping for a moment -- the session log says what the game was doing: the Debug build writes one for every session in saves/logs/ (Release: turn on Session log in the settings, or KHDAYS_LOG=1): its scenes, the files it read and how long they took, when each music was asked for and when it was heard, and every stretch over 50 ms without a frame. Press F12 when you see it happen: the log gets a mark there, and what the DS's two screens show then is saved in saves/marks/ (mark_<n>_frame_<frame>.bmp, with the upper screen's layer registers and the pause's pieces in the log). Send the log and the pictures with the bug report.

Controls

By default the game is played as on the DS.

• Keyboard and mouse: W A S D = D-pad, left button = A, Space = B, C = X, right button = Y, left Shift or Left = L, middle button or Right = R, M or Enter = START, N = SELECT; in a field, with the command menu on the D-pad, the wheel moves the command menu up and down and Q and E left and right. Any key or mouse button (left, middle, right, the side buttons X1 and X2, the wheel) can be bound to any action in Settings -> Controls; a notch of the wheel is a short press. The pointer hides over the game while its window has the focus (the touch screen is not used).
• Gamepad (Xbox, PlayStation, Switch Pro, Steam Deck, or any controller your system recognises as a gamepad): connect it whenever you like, even in the middle of a battle. The buttons follow the DS's layout by position, whatever is printed on them: the right-hand face button is A, the bottom one B, the left one Y and the top one X; the shoulders are L and R; Start or Options is START; Select, Share or View is SELECT. The left stick moves like the D-pad (the DS's eight directions). With several gamepads connected, the first one plays.

Settings. Press Esc, the gamepad's Guide / Home button or L3 (click the left stick in; Steam and the Steam Deck keep Guide for themselves), or click the title's settings key where the title is the theater's. The menu covers the window, the game dimmed and paused behind it (in a multiplayer session the game goes on). Every section is on one screen -- Controls, Enhancements, Sticks and camera, Video, Sound, Multiplayer, Language, General -- and works with the mouse alone, the keyboard alone or a gamepad alone (its shoulders move between the sections). A change takes effect when you make it: the picture behind the menu follows the video settings, each volume plays a sample of its kind (the game is heard at it when it resumes), and a new binding works from the first press after the menu closes. The Controls section shows every action with its two keys and two gamepad buttons side by side: choose a cell and press the new input; the Kingdom Hearts II layout and the defaults of each section are there too. A setting that waits for something says so beside it (the movies' choice from the next movie; the nickname, online play and the server from the next multiplayer session while one is open).

Language. The game and the settings menu follow your system's language when the game has it (English, Fren