MKW Logger

MKW Logger is a lightweight, low-overhead logging module for Mario Kart Wii game built on the Pulsar engine. It is designed to extract gameplay/engine data points in real time while keeping runtime impact small.

The Logger operates as a Single Producer, Single Consumer (SPSC) lock-free n-buffer ring. It is designed to extract game state data (position, inputs, variables etc.) frame-by-frame with minimal performance overhead, for all 1-12 players, to ensure single point of reference and data synchronization. Data is serialized in binary format and written to the Wii's internal NAND (/shared2) to ensure low-latency IO. The file can be read with our Python parser and visualized via our Dash-based web app.

This makes it easy to extend the logger with new signals without turning logging into a performance bottleneck.

Project Status

Currently, this project functions as an extension for the CTTP (Custom Track Testing Pack).

• Why is this not a fork? This logger is designed as a modular component for the Pulsar engine. While it currently relies on CTTP, the roadmap includes decoupling it into a standalone module compatible with any Pulsar-based distribution.

---

Getting Started (For Users)

If you simply want to use the logger to extract data (using the default set of fields defined in CSVLogger.csv in the fieldnames variable), you do not need to compile the code.

Prerequisites

1. Dolphin Emulator: Ensure you have a recent version installed.
2. Mario Kart Wii ISO/WBFS: You must own a copy of the game.
3. CTTP Distribution: Download CTTP v2.1.3 (Pre-built) from Cotni's Release Page.

Installation

1. Install CTTP:
   • Navigate to your Dolphin User directory (Usually %appdata%/Dolphin Emulator/ on Windows).
   • Paste the CTTP and riivolution folders from the download into the Load folder.
2. Install the Logger:
   • Download the Code.pul file from the or the build folder of this repo.
   • Navigate to Load/CTTP/Binaries/ in your Dolphin directory.
   • Place the new Code.pul here next to the Loader.pul.

Usage

1. Open Dolphin Emulator.
2. Right-click Mario Kart Wii in your game list.
3. Select "Start with Riivolution Patches".
4. Select Open a Riivolution XML.
5. Select riivolution/CTTP.xml, enable the pack and launch the game.
6. Play the game (any kind of races); logs are automatically recorded in the background.

Accessing Log Data

Dolphin stores the emulated Wii filesystem under its User Folder:

Data is saved to the emulated Wii filesystem, which Dolphin stores under its User Folder. To retrieve your logs:

1. File -> Open User Folder
2. Then look under: Wii/shared2/
3. You will find the binary log files here.

---

Development (For Contributors)

If you wish to modify the source code or add new data points to the logger.

Prerequisites

• Pulsar Source Code: You must use Pulsar commit 0e899e9 (This is the specific commit prior to Update 2.0).

• Project Structure: Place this repository's files into the root level of the Pulsar source folder.

• This project requires Nintendo’s original Wii compiler family, the Embedded PowerPC EABI compiler (Metrowerks/Freescale).

  My local setup uses: Freescale C/C++ Compiler for Embedded PowerPC Version 4.3 build 213

  Any 4.3‑series EABI mwcceppc from a Wii‑compatible CodeWarrior install (e.g. the one that comes with CodeWarrior for MPC55xx/MPC56xx v2.10) should work; the exact build number is not important as long as it's the same tool family. Other compilers (devkitPPC/GCC, etc.) are not supported for this project's code.

  For licensing reasons, the compiler binaries are not included here; you must supply your own mwcceppc.exe and point CC at it.

Building

1. Open buildCode.bat.
2. Modify the file paths.
3. Run buildCode.bat.
4. If successful, a new Code.pul will be generated in the output directory.

---

On real Wii hardware

This has not been fully validated by the author on real hardware.

If you test it on console, feedback (installation process, what worked, what path the files ended up in) is very welcome.

---

Version History

• 0.1
  • Initial Release
  • SPSC ring buffer implementation (logger)
  • Data file format defined by logger implementation

Roadmap (planned)

• Better data shape
  • Delta encoding (compressors love small values)
  • Event based
  • Structure of Array (SoA) instead of Array of Structure (AoS)
  • Bitpacking, Quaternion, Quantization...
• Data compression
• System as a modular component, independent of CTTP

Acknowledgments

• Pulsar
• Cotni's CTTP fork and Melg CTTP base work

---

License

This project is licensed under the MIT License - see the LICENSE.md file for details.