#How mods work

#Scripts and data

A mod has two kinds of material:

• Data: mod.json, content definitions (blocks, maps) as JSON, models, pictures, sounds, video, interfaces (.uxml) and styles (.uss). The game reads and checks these itself.
• Scripts: Lua files that use the API to react to the game and change it.

Many mods are only data. A new block needs one JSON file and a model. Scripts add behaviour.

#Two sides

Project Avion is multiplayer at heart. Even single player runs a server and a client in the same process. A mod therefore has up to two copies running:

You choose which scripts run where in mod.json:

"entry": { "server": "scripts/server.lua", "client": "scripts/client.lua" }

"shared" runs the same script on both sides, and mod.server and mod.client tell it which copy it is. Modules only exist where they make sense: ui, world, effects, input and camera are nil in a server script, net and players exist only in a session, a client-only function such as audio.play raises an error in a server script, and building.raiseLimit refuses to run in a client script. The reference marks every function that is client only or server only, and mod.whyUnavailable("ui") tells a script why a module is missing.

The two copies do not share variables. They talk through messages and replicated state.

#The sandbox

Scripts run in a sandboxed Lua 5.2 (MoonSharp). A mod cannot:

• read or write files, except its own files (read-only) and its own storage;
• reach the internet, except sites the player allowed by name (http:example.com);
• run native code: packages containing programs, libraries or scripts for other languages are refused;
• see the game's internals: only the functions in the reference exist, and using a name the API does not have is an error that suggests the right one;
• freeze the game, because every call has a time budget and a runaway loop is stopped (see Scripting).

Anything that affects other players, the world or the player's screen needs a permission. Risky permissions are shown to the player first.

#Life of a mod

1. Discovered: the game finds the folder or .zip, reads mod.json, and checks every file against the content rules. A mod with errors here is Invalid and never loads.
2. Waiting for consent (Needs consent in Mods), if it asks for medium or high risk permissions the player has not allowed.
3. Loading: dependencies start first; a mod whose dependency is missing or failed is Blocked. Content declared in mod.json is registered, then the entry script runs from top to bottom. A script that fails here stops the mod (Faulted) and the error is shown in Mods.
4. Running: events, timers, tasks and messages call back into the script.
5. Stopped: the player turns it off, the mod is reloaded (saving in the script editor does that), the session ends, or the mod keeps failing. The game then removes everything the mod created: panels, changes to game screens, objects, effects, sounds, timers, console commands, raised limits and registered blocks. Put your own bookkeeping in mod.onUnload.

Client mods start at the main menu. When you host or join, mods restart for the session so they see the network, the players and the map. Players switch mods on and off in Mods, and the change takes effect with Apply changes; see Installing mods.

#Multiplayer and downloads

When you join a server, the server lists the mods its session runs with an exact content hash. Mods you already have with the same hash are used as they are. Anything else is offered as a download, with sizes and permissions shown, and nothing is fetched or run until you agree. Downloaded files are checked against the hash before they are used. Mods marked "network": "local" (personal UI tweaks, sound packs) are never sent and never required. See Joining a modded server for what players see, and Publishing for what it means for your mod.

#Next

• mod.json
• Scripting
• Script editor
• Security and permissions