libsm64: Integrating Mario 64 into External Game Engines

The primary objective of this project is to create a streamlined interface for the rendering and movement logic—originally reverse-engineered via the SM64 decompilation project—allowing developers to integrate Mario into various game engines or custom systems with minimal friction.

⚙️ Technical Architecture

The project functions as a shared library. Rather than bundling assets, it extracts textures and animation data from an official SM64 ROM during runtime. Consequently, any application utilizing this library must hardcode assets must require the end-user to provide a valid ROM.

The logic flow can be visualized as follows:

API and Implementation

The entire public-facing API is encapsulated within a single header file: libsm64.h. To implement the library, a client project simply needs to:

1. Include the libsm64.h header.
2. Load the compiled shared library.

For those seeking a practical implementation guide, a basic example is provided in the /test directory.

---

🔌 Supported Bindings & Plugins

The ecosystem for libsm64 is extensive, offering support for various languages and platforms:

• Languages:
  • Rust bindings
  • Odin bindings
  • C# bindings
• Engines & Tools:
  • Unity: Plugin, MelonLoader mod, and BepInEx plugin.
  • Godot: Dedicated add-on.
  • Blender: Specialized add-on.
  • Game Maker 8: Extension available.

---

🛠️ Build Instructions

🍎 macOS and 🐧 Linux

To compile on Unix-like systems, follow these requirements:

• Install python3.
• Install SDL2 and GLEW (Required for the test suite).
  • Ubuntu users: sudo apt install libsdl2-dev libglew-dev.
• (Optional) To link musl libc instead of glibc, use the following command: LIBSM64_MUSL=1 make

Note: To execute the test program, place a US SM64 ROM in the root folder named baserom.us.z64.

🪟 Windows

1. Setup MSYS2 MinGW 64 (follow steps 1-4 of the standard guide), but use this repository URL: https://github.com/libsm64/libsm64.git.
2. Install dependencies via pacman:

   pacman -S mingw-w64-x86_64-SDL2 mingw-w64-x86_64-glew
   

3. Execute make to compile.
4. Ensure baserom.us.z64 is present in the root directory for testing.

🌐 Web (Emscripten) - Work in Progress

To compile for the web, use:

emmake make CC=emcc

• For a standalone JS call: Run emcc dist/libsm64.so -o libsm64.js to generate libsm64.wasm and libsm64.js.
• For C projects: Use dist/libsm64.so as a compiled WebAssembly object.

---

📋 Summary of Make Targets

---

🧮 Mathematical Logic

The library essentially treats Mario's state as a function of input and current physics: $\text{New State} = f(\text{Current State}, \text{User Input}, \Delta t)$

📦 Repository Metadata

• License: CC0-1.0
• Stats:
  • ⭐ 861 Stars
  • 🍴 50 Forks
  • 👀 18 Watchers