Steam
Coming soon toSteam
Modding docsAPI 1

Getting started

This page takes you from nothing to a running mod of your own in about ten minutes. All you need is the game: it has a script editor built in, and any other text editor works too.

Install a mod

  1. Download an example from the examples page, such as the Glow Sphere Block.
  2. In the game's main menu, open Mods and press Open folder. This is your mods folder:
    • Windows: %USERPROFILE%\AppData\LocalLow\Ivyture\Project Avion\Mods
  3. Put the downloaded .zip there. An unpacked folder works too.
  4. Back in Mods, press Refresh. The mod appears, switched on. If it asks for permissions, press Review permissions, read them, press Allow, then Apply changes.

A mod that asks only for low risk permissions starts immediately. One that asks for more waits until you allow it, and asks again if a later version wants more. Installing mods explains the whole Mods screen, and Security and permissions what the risks mean.

Make your first mod

A mod is a folder with a mod.json and whatever scripts and files it needs.

my-first-mod/
  mod.json
  scripts/main.lua
mod.json
{
  "format": 1,
  "id": "yourname.my-first-mod",
  "name": "My First Mod",
  "version": "0.1.0",
  "api": 1,
  "entry": { "client": "scripts/main.lua" },
  "permissions": ["ui"]
}
scripts/main.lua
log.info("Hello from", mod.name)

local panel = ui.panel{ anchor = "top-right", padding = 12 }
panel:style{ ["background-color"] = "#1b1d22e0", ["border-radius"] = "6px" }
panel:addNew("Label", { text = "My first mod is running!", style = { color = "#f59e0b" } })

Put the folder in your mods folder and press Refresh in Mods. The label appears in the corner of the screen.

Faster ways to start:

Change it and reload

Open the script editor (F1, then Mods → Script editor). Your mod is in the explorer on the left: open scripts/main.lua, change the label's text and press Ctrl+S. The mod reloads at once. It stops, everything it made (panels, objects, sounds, timers) is removed, and it starts again with your change. If something is wrong, the error appears under Problems with its file and line, and the line is marked in the editor.

You can edit in any other editor as well. While the script editor is open, saving there reloads the mod too. Otherwise press Console on the developer tools bar and type:

/mods.reload yourname.my-first-mod

/mods.log yourname.my-first-mod shows what the mod wrote with log.info and any errors, with file and line. The script editor's Log tab shows the same as it happens. See Script editor and Developer console.

Get autocompletion

The script editor completes the API as you type: write a module name and a dot (ui.), or press Ctrl+Space.

For VS Code and other editors, the API reference ships as theonaris.d.lua, a type definition file for the Lua language server. Install the Lua extension in VS Code, then run theonaris-mod setup-editor my-first-mod. Every function, parameter and handle is completed and documented as you type.

Where next