API reference

Every verb, every option, every refusal.

If you are looking for how do I build X, start with the recipes instead — they link back here for the details.

The six modules

local self    = require("self")
local world   = require("world")
local players = require("players")
local events  = require("events")
local objects = require("objects")
local vec     = require("vec")
local json    = require("json")
local http    = require("http")

Module	What it is
self	the object your script is inside
world	the region around it
players	who is here, and what they are doing
events	messages between scripts
objects	acting on other objects
vec	points, directions and the maths on them
json	turning a table into text a store can hold, and back
http	calling a service outside the world

self and objects also work without the require, as ready-made globals. The rest do not — a snippet using world: without requiring it will fail on the first line that touches it.

Writing all six is still worth it: the require is what gives you autocomplete and type checking in VS Code.

Sub-tables

world.terrain	sculpting the ground
world.blocks	the cubic volume
world.build	pieces players raise, and what holds them up

Tables and rules

Player and screen	HUDs, cursor, crosshair, camera, weapons
HUD reference	every node, style key and theme value
Object properties	every key set accepts
Particles	every emitter field
Sockets	the eighteen places an object can hang on a body
Permissions	why a verb answers "permission"
Limits and refusals	every ceiling and every reason

---

Conventions

These hold everywhere, so they are worth reading once.

Two answer shapes

A reading hands you the value and never fails:

local here = self:position()
local n = players:count()

An action hands you true (or a useful value), or nil plus a reason:

local ok, why = self:move_to(0, 5, 0)

Three meanings of nil

Answer	Meaning
a value	it worked
nil	a real answer meaning nothing — no hit, no such item, nobody here
nil, reason	the call could not be carried out

world:raycast returning plain nil is a clear line of sight, not an error.

Angles are degrees

Everywhere, without exception. rot is the word for an orientation on every verb that takes one.

ease names a curve, smooth counts seconds

ease is always one of "linear", "in", "out", "in_out". smooth is always a number of seconds. Never the other way round.

Points are interchangeable

Anything that takes a point accepts a plain { x =, y =, z = } table or a vec, and every reading hands you a vec. Nothing needs repacking by hand.

Coordinates follow the parent

World coordinates when the object stands alone; local to the parent when it is inside a group.

Names, not hashes

A script refers to what an object holds by name — a sound, a model, a content item. No content hash ever enters a script.

The slash decides which shelf: a bare name lives inside the object and travels with it; world/… lives in the world you are standing in.

Ids, not usernames

player.id is permanent. player.name is a display name the person can change. Use id as a key, always.

See also

• How scripts run — slices, saving, budgets
• Recipes — the same verbs, applied