Shell and folders
Some checks failed
build / build (push) Failing after 1m37s

This commit is contained in:
2026-10-07 19:13:25 +02:00
parent 7a115445ab
commit 5897870725
53 changed files with 6626 additions and 450 deletions

View File

@@ -9,7 +9,8 @@ This same documentation is browsable in-game from the editor:
Because a script runs on the server thread from start to finish, everything it does
happens at once and the game waits for it to finish. Loops that place millions of
blocks will freeze the server, so keep them reasonable.
blocks will freeze the server, so keep them reasonable. A script can also keep
listening *after* it has finished, with [events](#events).
```lua
print("hello, player!")
@@ -91,6 +92,67 @@ if block ~= "minecraft:air" then
end
```
## Events
Listeners let a script react to the game *after* it has finished running. Register one
with `events.on_<event>(callback)`; from then on the callback runs whenever the event
happens.
| Registration | Callback signature |
| ----------------------------------- | ----------------------------------------------------------- |
| `events.on_use_item(cb)` | `cb(player, item, count, hand)` |
| `events.on_break_block(cb)` | `cb(player, x, y, z, block)` |
| `events.on_chat(cb)` | `cb(player, message)` |
| `events.on_player_join(cb)` | `cb(player)` |
| `events.on_player_leave(cb)` | `cb(player)` |
| `events.on_tick(cb)` | `cb(tick)` |
`player` is always the name of the player who caused the event. Other values depend on
the event:
- **on_use_item** — fires when a player right-clicks to use the item in their hand:
`item` is the item id (`"minecraft:stick"`), `count` the stack size, and `hand`
`"main"` or `"off"`. An empty hand does not fire. The click still does whatever it
would normally do — the listener only observes it.
- **on_break_block** — fires *after* the block is broken (`x, y, z` now hold air),
with the id of the block that was there.
- **on_chat** — fires with the plain text of the message. The message is sent to chat
as usual.
- **on_player_join / on_player_leave** — fire when a player joins or leaves, including
the running player themselves.
- **on_tick** — fires at the end of every server tick with the tick counter, a whole
number that grows by one every tick (20 ticks per second). Keep tick callbacks
cheap: they run twenty times a second, and a slow one lags the whole server.
Callbacks run on the server thread and have the same powers as the script that
registered them — they can call `print` and the `world` functions. An error inside a
callback is printed to the owner's chat; it never stops the game or the other
listeners.
```lua
events.on_use_item(function(player, item, count, hand)
if item == "minecraft:stick" then
print(player .. " waved a stick (" .. hand .. " hand)")
end
end)
events.on_break_block(function(player, x, y, z, block)
if block == "minecraft:diamond_ore" then
print(player .. " struck diamond at " .. x .. ", " .. y .. ", " .. z)
end
end)
```
### Listening resets
Pressing **Run Script** replaces the previous run completely: all listeners from the
previous run are dropped, and only the ones the new run registers are active. If a run
registers none, the old listeners go quiet. Likewise, when the running player
disconnects their script stops with them — a script cannot outlive its owner.
If you run the same script twice, its listeners are *not* doubled — each run starts
from a clean slate.
## Examples
A pillar four blocks tall: