LuauAPI is a Geode mod that ships a shared Luau runtime. It can power a script-first mod or add Luau to an existing C++ mod. Scripts call into Geometry Dash through generated bindings. This page is the entry point for mod authors who want to build a Geode mod using Luau.
- For a new mod, start from the LuauAPI example mod template. It includes the dependency, resources, editor config, and first script. See Installation for the Geode CLI and Download ZIP setup paths.
- For an existing C++ mod, add LuauAPI manually and expose your C++ code when needed. See Installation, Editor setup, and Your first script.
- Build LuauAPI from source for unreleased features or runtime work. See Building from source.
- One runtime, one main thread. The runtime is created once and reused. Sync entry points must run on the main thread, and the runtime rejects off-thread calls. Async variants hop to the main thread for you.
- Resources root and flat paths. Scripts load from a resources directory the host passes.
Names are flat
.luaufile names. See modules for path rules. - Deadlines and memory. Each run has a time budget and a memory cap. See Limits and errors.
- Errors are logged, not fatal. LuauAPI runs scripts in a protected call when you call
runFileorrunScript. An error is caught and written to the log instead of crashing the game. - C++ and Luau can live in the same mod. Register C++ functions and values before running scripts that need them.
Registered functions and values live in the shared
_Gtable under the calling mod's id, so other mods can call them too.
Working examples live in the demo scripts under mod/demo/ in this repo.
mod.jsonsrc/main.cppsrc/api.cppsrc/core/Runtime.cppsrc/core/Config.hpp