wolfhacklua API 1.1 Forum

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:

my-script.lualua
--@name My script
--@version 1.2.0
--@author you
--@api 1.0
--@description What it does.
--@permissions data,media
--@net_hosts api.example.com
HeaderMeaning
--@nameThe name shown on the Scripts page.
--@versionThe script's own version, major.minor.patch. Default 1.0.0.
--@author, --@description, --@licenseShown on the script's card.
--@apiThe API version the script was written for. Defaults to the version of the overlay you install on.
--@permissionsComma-separated permissions the script asks for. See permissions.
--@net_hostsComma-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:

text
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 loads

Install a folder from the Scripts page the same way as a file: paste the folder's path and press Install.

manifest.json#

manifest.jsonjson
{
  "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
}
FieldRequiredMeaning
idyesThe folder name. 2 to 48 characters from a-z 0-9 - _.
name, version, apiyesDisplay name; the script's own version; the API version it targets.
author, descriptionnoShown on the card.
permissionsnoWhat 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_hostswith netThe only hosts net may contact.
requiresnoOther installed scripts or libraries this one needs, with version ranges.
kindno"script" (default) or "library", which has no code of its own that runs: other scripts require it.
memory_mbnoThe Lua heap limit for the script, 8 to 96. Default 32.
entrynoThe 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.

main.lualua
local util = require("util")      -- util.lua next to main.lua
log.info(util.double(21))
util.lualua
local M = {}
function M.double(x) return x * 2 end
return M

Assets 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.

API 1.1 · source docs-src/pages/start/script-folders.md