This commit is contained in:
@@ -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:
|
||||
|
||||
Reference in New Issue
Block a user