Kinoko

A reimplementation of Mario Kart Wii's physics engine in C++.

Kinoko is a reimplementation of Mario Kart Wii's physics engine in C++. This project is a spiritual continuation of stblr/Hanachan. Like Hanachan, the goal of this reimplementation is to reach perfectly accurate ghost replay.

To see the current list of test cases and progress, visit STATUS.md.

Building

Dependencies

g++ 13.1 (C++23)
ninja 1.3
Python 3.6
Mario Kart Wii disc

Extracting Files

Kinoko relies on files from the base game to run, with the same paths relative to the executable. Dolphin is the preferred method of extracting these files.

Make sure Mario Kart Wii is in the Dolphin game list. If it's not, click on Config, navigate to the Paths tab, and click "Add...". Find the folder Mario Kart Wii is in, and if needed, close out of the Config menu and click "Refresh".
Right click Mario Kart Wii in the game tab, and click "Properties".
Navigate to the "Filesystem" tab using the arrow keys in the top right of the properties window.
If "Data Partition (0)" is not already open, click the arrow next to the name to open it.
Right click on the "Race" folder, and click "Extract Files...".
Select the folder the Kinoko executable is placed in. For developers, this is most commonly in the "out" folder after building the project.

Process

Generate the ninja file and test case binary:

./configure.py

Execute it:

ninja

Run Kinoko:

cd out

./kinoko test -s testCases.bin

Replaying a Ghost

The simplest use of Kinoko is to just determine whether or not a ghost finishes the race with the timer matching what is present in the ghost .rkg file header. To replay a ghost, you can run:

./kinoko replay -g pathTo.rkg

Creating New Test Cases

When a ghost doesn't play back correctly, we want to be able to capture the exact frame that a desynchronization occurs, as well as gain insight as to what variables desynced. There are two ways to evaluate test cases in Kinoko. Both approaches require generating a .krkg file.

Create KRKG

Test cases use a custom .krkg file format, which stores relevant in-game memory values to validate accuracy on every frame of a race. This file is generated using a custom version of MKW-SP.

Navigate to the workflows page for the KRKG branch of vabold/mkw-sp.
Download the mkw-sp-test artifact at the bottom of the page.
Extract boot.dol to a folder of your choosing.
In Dolphin, navigate to Config > Paths and set Default ISO to the path of your Mario Kart Wii PAL ISO.
In Dolphin, click Open and select the extracted boot.dol.
You should see some debug information printed on-screen and Mario Kart Wii should boot soon after.
Watch a ghost replay of your choosing. After the ghost finishes and the screen fades to black, navigate to [DolphinDir]\User\Wii\title\00010004\524d4345\data. You should see a new file called test.krkg.

Approach 1: Creating a Test Suite

Kinoko will iterate the array of test cases defined in testCases.json, each with the following format:

"testCaseName": {
    "rkgPath": "pathTo.rkg",
    "krkgPath": "pathTo.krkg",
    "targetFrame": 0
}

rkgPath is the path to the game's native ghost file for the time trial you want to simulate.

krkgPath points to the krkg file generated in the previous section for this time trial ghost.

targetFrame is the number of frames to attempt sync for this ghost. Kinoko will throw an error if it is larger than the framecount stored in the krkg. If Kinoko reaches targetFrame while maintaing sync, then the test case will pass.

To update the test binary after making changes to testCases.json, be sure to re-run:

./configure.py

Approach 2: Testing a Single Ghost

If you just want to test a single ghost, you can run:

./kinoko test -g pathTo.rkg -k pathTo.krkg

In this scenario, Kinoko will validate the entire ghost, only passing the test if the entire ghost syncs.

Interfacing

While a GUI is not planned for the project at this time, contributors are welcome to add a graphics frontend under three conditions: the license must not change, it does not interfere with the CLI, and most importantly, it must not distribute any in-game assets.

Integrate Kinoko to your project

You can link Kinoko to your own project using CMake by linking with the libkinoko target. For example:

# add_subdirectory(kinoko)
 
add_executable(example main.cpp)
target_link_libraries(example libkinoko)

Note that any project using Kinoko's include directories will also require C++23.

Contributing

The codebase uses C++ for the engine and Python for any external scripts.

Pull requests resolving an issue or element of a tracking issue should reference the issue or item in the description.

Any commits should be formatted using the project's clang-format file.

Resources

Kinoko Discord - Discuss development, offer suggestions, and more!
MKW-SP Discord - Request Ghidra server access and chat with contributors.
Matching Decompilation - A repository that compiles back into the game's original assembly.
Tockdom - A wiki maintained by multiple community members, most notably used for file formats.