Write Lua, nothing else
No engine, no compiler. A text editor and the game are all you need, with a documented API and autocompletion for VS Code.
Safe for players
Scripts run in a sandbox with no file or internet access unless the player allows a named site. Risky permissions are always asked for.
Multiplayer by default
The server copy of a mod decides and clients ask. Players who join a modded server download its mods after agreeing.
Quick start
Your first mod in ten minutes
- Try an exampleDownload Glow Sphere Block and put the .zip in your mods folder (Mods → Open folder in the game).
- Allow itStart the game, open Mods, and allow the permissions it asks for.
- Make your ownFollow Getting started, or run
theonaris-mod new block my-block --id yourname.my-block --name "My Block". - IteratePress F1 in game and open Mods → Script editor: saving a file reloads its mod and shows any error on its line.
The guide
Everything, in order
Start here
- Getting started
Install a mod, make your first one, and see it run. - Installing mods
For players - where mods go, the Mods screen, permissions, modded servers, turning mods off, and what to do when one breaks. - How mods work
Sides, the sandbox, content, and the life of a mod, explained once.
Making mods
- mod.json
Every field of the mod manifest, the files a mod may contain, and their size limits. - Scripting
The Lua you can use, modules and require, values, handles, events, timers and tasks, errors and time budgets. - Settings and storage
Options declared in mod.json that the game keeps valid, saved and in sync, and data a mod keeps between sessions. - Multiplayer
Messages between server and client scripts, replicated state, players, limits, and how to keep a mod cheat-proof. - Interface
Panels and windows from layout (.uxml) and style (.uss) files, reacting to clicks, changing the game's own screens, the cursor and keys. - Security and permissions
What mods can and cannot do, how players decide, and what the game does to keep downloaded mods safe.
Content
- Blocks and building
New blocks from models, reading and changing creations, part limits, overlapping moves and toolbar tools. - Gears and turning parts
Gear blocks from JSON, mechanisms declared in data, placement guides and the kinetics module. - Maps
Custom maps built on the game's scenes, with terrain, props, lighting, sounds, effects and spawn points. - Models, pictures and objects
Model formats and how they convert, textures and materials, and putting objects in the world. - Planets
A map's own star system - planets with heightmaps, painted ground, air, seas and clouds, the sun and the weather. - Sound, music and video
Sound effects in the world, music with fades, the player's volume, and video on panels and objects. - Effects and camera
Particle effects from presets, effects that follow objects, camera shake and zoom.
Tools
- Script editor
The code editor built into the game - edit a mod's files while it runs, reload on save, run Lua inside it, and read its errors and log. - Command line tool
theonaris-mod creates, validates, packs and installs mods from a terminal. - Developer console
Console commands for mod makers, running Lua inside a mod, and adding your own commands. - Troubleshooting
Why a mod doesn't load or behave, what every validator message means, and how to fix it.
Sharing
- Publishing and updates
Packing a mod, versioning, dependencies, updates, and how servers send mods to players.
API reference
- All modules
Every function a script can call - Handles
Blocks, objects, players and sounds - Events
Everything a mod can react to - Permissions
What each allows and how risky it is