What scripts are

A script is a set of instructions you put inside an object. The object then does something on its own: a door opens when you click it, a lamp turns itself on at night, a crate hurts you when it lands on your head.

You do not need to have programmed before. This page explains the idea. The next one has you writing a working script in about ten minutes.

Every script lives in an object

There is no central place where "the code of the world" lives. Each object carries its own scripts, and a script can only act on the world through the object it is in.

That has a consequence worth knowing early: if you copy the object, the script comes with it. Sell a lamp, give it away, drop it in another world — it still works, because the behaviour was never stored anywhere else.

An object can hold up to 8 scripts at once. They run side by side and do not see each other's variables. Splitting behaviour across two scripts is a normal thing to do: one for the door, one for the sign above it.

Scripts wait for things to happen

A script is not a recipe that runs top to bottom and finishes. It is a set of answers to things that might happen.

local self = require("self")

self:on_touch(function(player)
    print(player.name .. " clicked me")
end)

Read that as a sentence: when someone touches me, print their name. The script sets that up once and then waits. It costs nothing while it waits — a world with a thousand silent scripts is a world doing nothing.

The things a script can wait for are called events. The main ones:

Event	Happens when
on_touch	someone clicks the object
on_contact	someone's body physically bumps into it
on_region	someone walks into (or out of) a sphere around it
on_action	someone presses a key the world declared
on_hold / on_drop	someone picks the object up or lets go
on_timer	a set number of seconds passed
on_hud	someone clicked a button on a menu you showed them

There are more, and they all have the same shape: you hand the event a function, and the engine calls it back when the moment arrives.

The four things scripts can do

Everything in this documentation is one of these four.

1. Change a property. Colour, transparency, whether it glows, whether you can walk through it, whether it falls.

self:set({ color = "#ff3355", light = true })

2. Move something. Instantly, or smoothly over time.

self:rotate_by(0, 90, 0)                        -- turn a quarter turn now
self:tween({ to = { x = 0, y = 5, z = 0 }, seconds = 2 })  -- rise over 2s

3. Talk to a player. Show them a menu, a crosshair, a message; move their camera; hand them an object; teleport them.

4. Remember something. A number of coins, whether the door is open, when a crop was planted. Memory that survives the world being restarted.

What a script is not allowed to do

Knowing the fences early saves you a lot of confusion later.

• A script cannot read another object's position. It can tell an object to move, but not ask where it is. (There is a reason, and a workaround — see objects.)
• A script cannot take something out of somebody's inventory. It can hand things over; it cannot reach in.
• A script cannot move a player's camera or body unless that player allowed it when they entered the world.
• Nothing a script creates is permanent. Objects made with world:spawn disappear when the world restarts. Permanence is what the build tools are for.

None of these are error messages you will hit by accident. They are shapes of the system, and the documentation says which permission each verb needs.

Where a script runs

Almost everything runs on the server — the machine hosting the world. That is what makes it fair: every player sees the same result, and nobody can edit their own copy to cheat.

A few things run on each player's own machine instead, because waiting for the server would feel broken:

• Menus and HUDs. Changing pages, moving a slider, ticking a box — instant, no round trip. Only a button that explicitly reports back reaches your script.
• The crosshair.
• A weapon's kick and its shot cone.
• The optional preview of a click (predict), so a door starts opening on the frame you click it instead of a fifth of a second later.

You never have to choose. Each verb already runs where it should, and the reference page for it says so.

What you can build

Doors, lifts, buttons, traps, checkpoints, shops with a working menu, weapons with recoil and ammunition, campfires that burn out, crops that grow while nobody is watching, day and night, storms, vehicles, a scoreboard, a whole round-based game with a lobby.

The rest of this guide is that list, one recipe at a time.

Next: Your first script — a door you can click, from an empty object to a working thing, in ten minutes.