How the two Rust projects differ

There are two related Rust efforts in this workspace. Both aim to run MKDS on a PC, but they take different routes and their Rust source has a different meaning.

The earlier hand-written port

The earlier PC port lives mainly in 3_hand_port/vm_model/ and 3_hand_port/game/. 3_hand_port/vm_model/ contains Rust implementations of selected game systems such as kart movement, race flow, items, drivers, objects, and asset loading. 3_hand_port/game/ connects that model to a desktop window, controls, camera, and course rendering with Bevy. The code is organized around named game concepts and Rust data types, so a developer can read and change a system such as steering or item behavior directly.

This is a semantic port: developers study the original behavior and implement corresponding Rust logic. It can be easier to understand and customize, but it only contains systems that have been implemented. Matching the original game depends on how much behavior has been recreated and verified. The project also contains research-only scans and notes; those are not all part of the playable program.

The ROM-generated Rust build

The newer route starts with a user-supplied .nds file. 1_build_tool/ validates the ROM and drives generation and compilation. 2_native_game/ contains the ARM/Thumb lifting and DS runtime, while 2_native_game/native/ supplies the native window, input, and audio host. The generator translates discovered machine-code routines into Rust code, groups that generated code into crates, and builds a Windows executable that runs against the supplied ROM.

This generated Rust is closer to a machine-code translation than a conventional hand-written game port. Function and segment boundaries come from the selected ROM metadata; generated functions preserve instruction-level behavior and call through a runtime that models the DS CPU, memory, graphics, input, and sound services. Generated files can be large and mechanical. They are useful build inputs and inspectable output, but they are not a clean, named rewrite of the game’s source code. The generated source is retained in the bundle only when the build is asked to keep it; otherwise the bundle carries the executable and build reports.

At a glance

The two routes can inform each other: the hand-written model and emulator research help explain behavior, while the generated build provides a separate way to execute code from the user’s ROM. They are not the same source tree, and changes to one do not automatically update the other.

What “generated source” means

The build can produce both a Windows executable and generated Rust source. The source is the Rust representation of lifted ROM routines and generated wiring; it is not a complete high-level source listing equivalent to Nintendo’s original development code. The native runtime and builder are hand-written project code. If the bundle was built without the keep-generated option, the Rust workspace is not included even though it was used during compilation.

The executable and generated source are tied to the ROM identity, revision, and metadata used for that build. A source bundle is therefore best read alongside its manifest and coverage report. Runtime acceptance is tracked separately from successful code generation and compilation: a build can compile while graphics, timing, audio, or game-flow behavior still needs testing.

See the user-supplied ROM build workflow and native build baseline and contract for the current build details and verification limits.