Libsm64 Godot

Addon that binds libsm64 to Godot via GDExtension, allowing to integrate Mario from the Super Mario 64 engine into any Godot 4 project.

Try out the online demo at itch.io.

You can get the addon from the Godot Asset Library or from the GitHub releases page.

Projects using libsm64-godot

Infinite Mario 64 (by TwilightPB)

Current Godot compatibility

Currently compatible with Godot 4.3.x, with binaries compiled for Windows (x86_64), macOS (universal) and Linux (x86_64).

How to compile the GDExtension

If you just clone the project throught Git and attempt to run it, you'll get errors complaining about the lack of the GDExtension library (the package in the GitHub releases page already includes the compiled GDExtension).

First, build libsm64 and then copy (don't move) the genereated dynamic library from the extension/libsm64/dist/ folder into addons/libsm64_godot/extension/bin.

Setup the requirements for building Godot for your platform of choice (If compiling for Windows, use the MinGW 64 enviroment you used to compile libsm64). Then, run the following command from inside of the extension folder to compile the GDExtension. It will automatically copy the generated binary into addons/libsm64_godot/extension/bin.

• For debug build: scons target=template_debug use_mingw=yes
• For release build: scons target=template_release use_mingw=yes

Note: if you are using MSYS2 to compile, you must run this command from the MSYS2 MINGW64 terminal window.

How to use

This addon requires a Super Mario 64 (USA) ROM file (for legal reasons, steps to get a ROM will not be disclosed). Make sure the ROM file has the following SHA256 hash:

17ce077343c6133f8c9f2d6d6d9a4ab62c8cd2aa57c40aea1f490b4c8bb21d91

This addon has 2 interfaces: A lower level interface that exposes the libsm64 API directly, and a higher level interface that provides a more Godot-like API built on top of the lower level interface. If the higher level interface does not provide the functionality or the flexibility that you need, you can use the lower level interface to access the libsm64 API directly.

Lower level interface

The LibSM64 singleton exposes the same constants and functions as the libsm64 C API. All of the inputs and outputs of LibSM64 are internally converted back and forth between Godot's and libsm64's types, acconting for the differences in the coordinate systems, using [member scale_factor] to convert between Godot's metric system and libsm64's internal units, and converting time between Godot's seconds and libsm64's frames (assuming libsm64 is ticked at a frame rate of 30 frames per second, see LibSM64.tick_delta_time). The functions and constants exposed in LibSM64 are meant to be as one-to-one as possible with libsm64's C API.

Higher level interface

The project in this repository acts as a demo and example of how to use the higher level interface. Play around with the demo project to see how the higher level interface works.

This add-on consists of two main components:

• LibSM64Global: Static class that exposes the init() and terminate() functions of the libsm64 library. Also implements a load_rom_file() to load the ROM file with SHA-256 checksum verification.
• LibSM64Mario: Extends Node3D; can have multiple the scene.

It also adds two helper nodes:

• LibSM64StaticSurfaceHandler: Extends Node; provides helper functions to load all the meshes under the libsm64_static_surfaces group into the libsm64 world.
• LibSM64SurfaceObjectsHandler: Extends Node; provides helper functions to load and update all the meshes under the libsm64_surface_objects group into the libsm64 world.

And a node for audio:

• LibSM64AudioStreamPlayer: Extends AudioStreamPlayer; plays the audio generated by libsm64; add this node to the scene and call the play() method after calling LibSM64Global.init().

Simple steps for basic use

On the Project Settings:

1. Set the libsm64/scale_factor setting to the desired value (at default value of 100.0, the spawned Mario hitbox will be 1.61 meters tall and 1 meter wide).

When creating the scene:

1. Add a LibSM64StaticSurfaceHandler node to the scene.
2. Add the meshes that compose the world to the libsm64_static_surfaces group (NOTICE: use simple, low-polycount meshes for best results).
3. Add a LibSM64Mario node and set its camera property with an Camera3D node.
4. Create the action names that are in the LibSM64Mario node's Mario Inputs Actions export group in the project's Input Map and bind them to the appropriate axes/buttons/keys. Alternatively, change the action names in the LibSM64Mario node's Mario Inputs Actions export group to match already existing action names in the project's Input Map.

Then do the following on the scene's main script:

1. Call the LibSM64Global.load_rom_file() function with the file path to the Super Mario 64 ROM file (the SHA-256 of the file will be checked against the known good ROM).
2. Call the LibSM64Global.init() function.
3. Call LibStaticSurfaceHandler.load_static_surfaces() on your instanced LibSM64StaticSurfaceHandler node.
4. Call LibSM64Mario.create() on your instanced SM64Mario node(s).

For more detailed instructions refer to the manual.