$ show Brawmario/libsm64-godot
This repository is a Godot 4 addon that integrates the libsm64 library (a reimplementation of Super Mario 64's game engine) into Godot via GDExtension. It provides both a low-level C++ API exposed as a Godot singleton (`LibSM64`) and high-level GDScript nodes (`LibSM64Mario`, `LibSM64StaticSurfaceHandler`, `LibSM64SurfaceObjectsHandler`, `LibSM64AudioStreamPlayer`) for easily adding Mario characters and surface geometry to Godot scenes. The addon handles coordinate system conversion (SM64 to Godot), fixed-rate physics ticking at 30 FPS with interpolation for smooth rendering, and dynamic material switching based on Mario's power-up state. A demo project with multiple playable scenarios (Bob-omb Battlefield, many Marios, flying range) is included, along with a ROM picker dialog for loading the required Super Mario 64 US ROM. The architecture is a classic Godot plugin: a GDExtension shared library (built from C++ source in `extension/`) registers new engine classes and a singleton, while GDScript files in `addons/libsm64_godot/` provide editor integration and higher-level abstractions. The core C++ code wraps all libsm64 functions (global init, Mario creation/tick, surface loading, audio) and exposes them as Godot methods. The GDScript layer adds node lifecycle management, input mapping, interpolation, and surface handling utilities. The demo project in `libsm64_godot_demo/` showcases the addon with custom scenes, a camera rig, HUD, and input configuration. Key external dependencies are the libsm64 C library (included as a Git submodule) and the godot-cpp bindings (also a submodule). The addon requires a specific Super Mario 64 US ROM (SHA-256 verified) to function, as libsm64 uses original game assets. The build system uses SCons and GitHub Actions to compile the GDExtension for Windows, macOS, Linux, and Web platforms. The code is well-structured with clear separation between C++ engine bindings and GDScript gameplay logic, making it a solid reference for integrating complex C libraries into Godot.
The LLM identified 3 files worth highlighting for reuse:
The `LibSM64Mario` node is a high-level GDScript wrapper that encapsulates the entire Mario lifecycle: creation, input handling, physics ticking, mesh generation, and material switching. It uses a `LibSM64MarioInterpolator` to smoothly interpolate Mario's state and mesh between the fixed 30 FPS physics ticks and Godot's variable frame rate, a pattern reusable for any fixed-rate physics integration. Inputs are abstracted via Godot's InputMap actions, allowing easy rebinding. This component is self-contained and could be extracted as a template for wrapping other libsm64-based characters or similar engine integrations.
This base class provides static methods to extract triangle faces from Godot `MeshInstance3D` and `CollisionShape3D` nodes (including `BoxShape3D`), converting them into the format expected by libsm64's surface loading API. It handles coordinate conversion, vertex winding order, and surface property assignment. The pattern of extracting geometry from Godot nodes and feeding it to an external physics engine is reusable for any project that needs to bridge Godot's scene tree with a custom physics or collision system. The methods are stateless and operate on Godot's built-in types, making them easy to reuse in other contexts.
The `LibSM64MarioInterpolator` C++ class implements a generic interpolation system for smoothing between discrete physics states. It stores a history of Mario states (position, rotation, mesh data) and linearly interpolates between them based on the time since the last tick. This pattern is essential for decoupling a fixed-rate physics engine (30 FPS) from a variable-rate render loop, and the implementation is clean, self-contained, and could be extracted for use in any Godot project that needs to smooth data from a fixed-rate source.