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 is the idea. The next one puts a working script in your world in about half an hour.
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 only reaches the world through the object it is sitting in.
That has a consequence worth knowing on day one: copy the object and the script comes with it. Sell a lamp, give it away, drop it in somebody else's world, and 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 cannot see each other's variables. Splitting behaviour in two is a normal thing to do: one script 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 it as a sentence: when someone touches me, print their name. The script sets that up once and then waits, and waiting is free. A world with a thousand silent scripts is a world doing nothing at all.
The things a script can wait for are called events. These are the ones you will meet first:
| Event | Happens when |
|---|---|
on_touch | someone clicks the object |
on_contact | someone's body physically bumps into it |
on_region | someone walks into a sphere around it, or leaves one |
on_action | someone presses a key the world set up |
on_hold and on_drop | someone picks the object up, or lets go of it |
on_timer | a set number of seconds went by |
on_hud | someone clicked a button on a menu you showed them |
There are a few more, and they all have the same shape. You hand the event a function, and the world calls that function back when the moment arrives.
The four things a script can do#
Everything in these docs 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 a number of seconds.
self:rotate_by(0, 90, 0)self:tween({ to = { x = 0, y = 5, z = 0 }, seconds = 2 })3. Talk to a player. Show a menu, a crosshair or a message, move their camera, hand them an object, teleport them somewhere.
4. Remember something. A number of coins, whether the door is open, when a crop was planted. Memory that survives the world restarting.
What a script is not allowed to do#
Knowing the fences early saves a lot of confusion later.
A script cannot read another object's position. It can tell an object to move, but it cannot ask where that object is. There is a reason and a way around it, both on the objects page.
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 agreed when they walked into the world.
Nothing a script creates is permanent. Objects made with world:spawn vanish when the world restarts. Permanence is what the build tools are for.
None of these are errors you will trip over by accident. They are the shape of the system, and every reference page says which permission its verbs need.
Where a script runs#
Almost everything runs on the server, the machine hosting the world. That is what makes it fair: everyone 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 a round trip to the server would make them feel broken:
- Menus and HUDs. Changing pages, dragging a slider, ticking a box. All instant. Only a button that explicitly reports back reaches your script.
- The crosshair.
- A weapon's kick and the spread of its shot.
- The optional preview of a click, so a door starts opening on the frame you click it rather than a fifth of a second later.
You never have to pick. Each verb already runs where it should, and its reference page says which side that is.
Three kinds of script#
Almost everything you write is the first kind. The other two exist because a menu and a hat are not objects standing in a world.
| Kind | Lives on | Typical use |
|---|---|---|
| object script | a thing in the world | doors, shops, traps, weapons on the ground |
| worn script | an item somebody is wearing | a hat that glows, a sword that swings |
| personal HUD | a player's screen | a scoreboard, a health bar, a shop window |
The same self is there in all three, with the verbs that make sense in each. A verb that means nothing where you put the script does not crash: it says so in the console, in one sentence, and the rest of the script keeps running.
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 piece at a time.
Next
Your first script takes an empty box and turns it into a door you can click, in about half an hour.
Updated 04 September 2026