Script folders and manifests
A script is either one .lua file or a folder with a manifest.json and any number of files. Both end up in the same place: Documents\Base\scripts\<id>\.
Single file#
The simplest form. The header lines at the top become the manifest:
--@name My script
--@version 1.2.0
--@author you
--@api 1.0
--@description What it does.
--@permissions data,media
--@net_hosts api.example.com| Header | Meaning |
|---|---|
--@name | The name shown on the Scripts page. |
--@version | The script's own version, major.minor.patch. Default 1.0.0. |
--@author, --@description, --@license | Shown on the script's card. |
--@api | The API version the script was written for. Defaults to the version of the overlay you install on. |
--@permissions | Comma-separated permissions the script asks for. See permissions. |
--@net_hosts | Comma-separated hosts, required together with the net permission. |
Only the first 40 lines are read for headers, and the file may be at most 512 KB. Installing a file creates the folder scripts\<id>\ containing your file as main.lua and a generated manifest.json.
Folder#
A folder is the form for scripts with several files, assets, or settings you want to control:
Documents\Base\scripts\my-script\
manifest.json required
main.lua the entry file (the manifest's "entry" can name another)
util.lua loaded with require("util")
assets\logo.png pictures, fonts, anything the script loadsInstall a folder from the Scripts page the same way as a file: paste the folder's path and press Install.
manifest.json#
{
"id": "my-script",
"name": "My script",
"version": "1.2.0",
"api": "1.1",
"author": "you",
"description": "What it does.",
"permissions": ["data", "net"],
"net_hosts": ["api.example.com"],
"requires": { "vec2": ">=1.0 <2" },
"kind": "script",
"memory_mb": 32
}| Field | Required | Meaning |
|---|---|---|
id | yes | The folder name. 2 to 48 characters from a-z 0-9 - _. |
name, version, api | yes | Display name; the script's own version; the API version it targets. |
author, description | no | Shown on the card. |
permissions | no | What the script asks for: data, media, theme, input, net, memory, memory_write, memory_patch. The user still has to grant the ones that need granting. |
net_hosts | with net | The only hosts net may contact. |
requires | no | Other installed scripts or libraries this one needs, with version ranges. |
kind | no | "script" (default) or "library", which has no code of its own that runs: other scripts require it. |
memory_mb | no | The Lua heap limit for the script, 8 to 96. Default 32. |
entry | no | The file that runs at load. Default main.lua. It must stay inside the folder. |
Versions and ranges#
The api number is major.minor. The major must match the overlay's exactly; the minor must not be newer than the overlay's. See API-version compatibility.
Script versions are major.minor.patch; a -pre suffix (1.0.0-beta.1) makes a version older than the release. Ranges in requires: >=1.2.0 <2.0.0, ^1.2 (same major, at least 1.2), ~1.2.3 (same minor), 1.x, * or an exact version.
Libraries and require#
require(name) loads a .lua file from your own folder (require("util") loads util.lua) or the library a requires entry names. A module that requires itself, or two that require each other, is an error. Paths cannot leave the folder.
local util = require("util") -- util.lua next to main.lua
log.info(util.double(21))local M = {}
function M.double(x) return x * 2 end
return MAssets and data#
- Assets (pictures, fonts, anything you ship) live in the installed folder, which the script can only read:
assets.texture("assets/logo.png"),assets.read("data.json"). - Data the script writes goes to its own folder,
Documents\Base\script-data\<id>\, through the file and store functions. The folder is limited to 16 MB and 256 files and is kept when you remove a script (unless you also delete its data).
Removing and updating#
Remove on a script's card deletes its folder under scripts\; its saved settings remain. To update a script, edit the installed files and press Reload, or remove it and install the new version. Reinstalling over an existing id is refused on purpose.
When a script's files change, any net, input and memory permissions you granted are switched off again until you grant them again: a grant belongs to the code you saw.