#Publishing and updates

#Packing

theonaris-mod pack my-mod --out releases

You get <id>-<version>.zip, validated and within the download limits. Players install it by dropping the zip into their mods folder, with no need to unpack (see Installing mods). Hidden files (like .luarc.json) and unknown file types are left out. The command line tool page says where to get theonaris-mod.

Include a README.md and a LICENSE in your mod: they are packed and help people who take it apart.

#Versions

Use semantic versions:

• Patch (1.2.3 → 1.2.4): fixes, with nothing else changing.
• Minor (1.2.4 → 1.3.0): new things; everything that worked still works.
• Major (1.3.0 → 2.0.0): something others rely on changed: an export, a content id, a setting key.

Never change the mod id or a content id: saves and servers refer to them. Renaming a block's id makes every creation using it lose that block.

Set game to the versions you tested: ">=0.1.0", or "^0.4.0" if a later game version might break you.

#Dependencies

Libraries are ordinary mods that mod.export functions:

"dependencies": { "someone.ui-kit": "^1.2.0" },
"optionalDependencies": { "someone.sounds": "*" }

A mod whose dependency is missing, disabled, out of range or failed does not start, and Mods says which one. Players need the dependency installed. Servers send dependencies along with the mod.

#Updates and permissions

Players replace the old zip or folder with the new one and press Refresh in Mods. If the new version asks for different permissions than the player allowed, it shows as Needs consent and waits for them to review the change. Keep permission changes rare, and explain them in your changelog.

Settings keep their values across updates if the key and type stay the same. Storage is kept by mod id.

#Multiplayer downloads

When a player joins a server, the server tells them which mods its session runs, each with an id, version, size, permissions and content hash. Only mods with "network": "required" or "optional" are listed. For each mod the player:

• already has it, when an installed mod has the identical hash, and uses it;
• has it cached, from an earlier download with the identical hash;
• needs it, and it is offered for download.

Before anything downloads, the player sees the list with sizes and permissions and chooses Download and join (Join when nothing needs downloading) or Leave. Optional mods can be skipped: they are only fetched with Join with optional mods. A list with a high-risk mod needs an extra tick before the player can join, so ask for as little as you need. The server streams the files with a bandwidth cap so the game doesn't stutter, and each file is checked against the hash. Downloaded mods are stored apart from the player's own mods and used only for sessions announcing that exact hash.

Things that follow from this:

• Any change to any file makes a different mod. A player with 1.2.0 joining a server with a locally edited 1.2.0 downloads the server's copy for that session. Their own copy is untouched.
• Size matters: downloaded mods are limited to 256 MB, with 64 MB per model or sound and 128 MB per video. Players on slow connections see the total before agreeing.
• Local mods ("network": "local") are never sent or required, so they work on any server, modded or not.

#Sharing the source

The examples in this documentation are MIT licensed so you can start from them. Whatever license you choose, say so in mod.json ("license") and in a LICENSE file.