require and pinned dependencies

A bundle can depend on libraries. A library is a marketplace item of kind script whose version is marked as a library; its entry file returns a table.

Declare the dependency

Pin each library to one exact version in manifest.json:

"deps": { "sam/vectors": "2.0.1" }

Require it

local vectors = require("sam/vectors@2.0.1")

client.set_event_callback("paint", function()
  local v = vectors.unit({ x = 3, y = 4 })
end)

The string is author/name@version and must match a deps entry exactly. A different version, a library not in deps, a bare name, a file path or a standard module name all raise an error. There is no search path.

require returns the table the library’s entry file returned. Calling it twice returns the same table.

What the loader does

At load the runtime reads deps, fetches each pinned bundle from the installed set, verifies its signature, and installs it as a module in the script’s _ENV. Dependencies of a dependency are resolved the same way from that library’s own manifest. A missing or unverifiable library refuses the whole load.

Capabilities of a library

A library declares its own capabilities in its manifest. Those must be a subset of the script’s capabilities. A script granted only http cannot load a library that declares websocket; the load is refused with the library and the missing group named.

A library sees the same globals as the script that loaded it: the script’s grants, the script’s log name, the script’s budgets.

Writing a library

The entry file returns a table:

local vectors = {}

function vectors.unit(v)
  return vector.normalize(v)
end

return vectors

Do not register event callbacks in a library; the runtime runs only the loading script’s. A library exposes functions the script calls from its own callbacks.