Files
codecraft/docs/lua-api.md
Aran Roig fe084e1843
Some checks failed
build / build (push) Failing after 50s
More things editor is now more stable
2026-10-08 14:00:22 +02:00

380 lines
16 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Lua scripting
Scripts are written in the in-game editor (`J` by default, rebindable under
*Options → Controls* → *Codecraft*) and run **on the server**. The top bar's
**Run Script** executes `main.lua`, which is the entrypoint.
This same documentation is browsable in-game from the editor:
**Help → Lua API Documentation**, or press **F1** on a function while editing.
The browser has a search box above its function list — press **Ctrl+F** and
type to filter functions by name or description.
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. A script can also keep
listening *after* it has finished, with [events](#events).
```lua
print("hello, player!")
```
## print(...)
Writes to the chat of the player who ran the script, tab-separated, like Minecraft
commands do.
```lua
print("blocks placed:", 12)
```
Whole numbers go through the Lua wrapper and are printed as `12.0`. To print them
without the decimal, concatenate them into a string:
```lua
print("blocks placed: " .. 12) -- -> blocks placed: 12
```
## run(command)
Runs a Minecraft command from the server command source, with full server permissions
and no player position or entity. The command may be written with or without a leading
slash. The function returns `true` when the command is submitted, or `false` and a
reason when the argument is invalid. A `true` result means the command was submitted;
it does not guarantee the command succeeded.
```lua
run("time set day")
run("weather clear")
```
For commands that need a player or coordinates, use explicit selectors and coordinates
in the command string. The command source is the server, not the player running Lua.
## Blocks
Coordinates are **absolute world coordinates** — never relative to the player — in the
dimension the running player stands in. Press `F3` to read your own coordinates, then
use them in the script.
| Function | Returns |
| --------------------------------------- | --------------------------------------------------- |
| `world.set_block(x, y, z, block)` | `true`, or `false` and a reason |
| `world.remove_block(x, y, z[, drops])` | `true`, or `false` and a reason |
| `world.get_block(x, y, z)` | block id string, or `nil` and a reason |
| `world.get_dimension()` | dimension id |
| `world.get_time()` / `world.set_time(ticks)` | world clock time in ticks |
| `world.get_weather()` / `world.set_weather(weather[, ticks])` | `clear`, `rain` or `thunder` |
| `world.get_biome(x, y, z)` | biome id, or `nil` and a reason |
| `world.players()` | array of online player names |
### world.set_block(x, y, z, block)
Places a block and updates neighbours and clients, like `/setblock` does. `block` is a
block id, with or without the `minecraft:` namespace, and may carry block states:
```lua
world.set_block(10, 64, -3, "minecraft:stone")
world.set_block(10, 65, -3, "gold_block") -- namespace optional
world.set_block(10, 66, -3, "minecraft:oak_stairs[facing=north]")
world.set_block(11, 66, -3, "minecraft:wall_torch[facing=south]") -- needs a wall behind it
```
The block is placed even if something is in the way. Blocks that cannot survive where
they are put (a torch without a wall, a flower without ground) drop themselves again,
and the call reports it as a failure.
Replacing a block that holds items, such as a chest, drops the contents like
`/setblock` does.
### world.remove_block(x, y, z[, drops])
Removes the block. Without `drops` the block just vanishes, silently and without items.
With `true` it breaks the way a player breaking it would: items, sound and particles.
```lua
world.remove_block(10, 64, -3) -- vanish
world.remove_block(10, 65, -3, true) -- break it, dropping items
```
### world.get_block(x, y, z)
Returns the block id at that position, including its block states, so the result can be
handed straight back to `world.set_block`:
```lua
print(world.get_block(10, 64, -3)) -- -> minecraft:grass_block[snowy=false]
```
Air is `"minecraft:air"`, a string, and every string is *true* in Lua — compare
against the id rather than testing the value:
```lua
local block = world.get_block(10, 64, -3)
if block ~= "minecraft:air" then
print("something is there: " .. block)
end
```
## Entities
Entity ids returned by `entities.nearby` and `entities.spawn` are UUID strings. The
nearby query only checks loaded entities in the executing player's current dimension;
it excludes the script owner, its radius defaults to 16 blocks and is capped at 128.
Entity positions are absolute.
| Function | Purpose |
| -------- | ------- |
| `entities.nearby([radius[, type]])` | UUIDs of nearby entities, optionally filtered by type id |
| `entities.spawn(type, x, y, z)` | Spawn a summonable entity and return its UUID |
| `entities.get(uuid)` | Return type id, x, y, z and custom/display name |
| `entities.teleport(uuid, x, y, z)` | Move an entity in its current dimension |
| `entities.remove(uuid)` | Remove an entity (players are protected) |
| `entities.set_name(uuid, name)` | Set a visible custom name |
| `entities.set_health(uuid, health)` | Set living entity health up to its maximum |
```lua
local ids = entities.nearby(12, "minecraft:zombie")
for _, id in ipairs(ids) do
local type, x, y, z, name = entities.get(id)
print(name .. " is at " .. x .. ", " .. y .. ", " .. z)
end
```
## Scoreboards
Scoreboard helpers operate on the server scoreboard. Objective names follow vanilla's
1–16 character limit. `create_objective` defaults to the `dummy` criterion; built-in
criteria such as `deathCount` and `health` are also accepted. `display` accepts `list`,
`sidebar` or `below_name`.
| Function | Purpose |
| -------- | ------- |
| `scoreboard.create_objective(name[, criterion[, display_name]])` | Create an objective |
| `scoreboard.remove_objective(name)` | Remove an objective |
| `scoreboard.set(player, objective, value)` | Set a score |
| `scoreboard.add(player, objective, value)` | Add to a score |
| `scoreboard.get(player, objective)` | Read a score (`nil` when unset) |
| `scoreboard.reset(player[, objective])` | Clear one score or all of a player's scores |
| `scoreboard.display(objective, slot)` | Show an objective in a display slot |
```lua
scoreboard.create_objective("coins", "dummy", "Coins")
scoreboard.add("Alex", "coins", 5)
scoreboard.display("coins", "sidebar")
```
## HUD and boss bars
Titles, subtitles and action-bar messages go to the player who ran the script by default;
pass an online player name to target someone else. Title timings are measured in ticks
(20 ticks per second). Boss bars are saved server-side, identified by a resource id; ids
without a namespace use `codecraft:`. A new boss bar is shown to the script owner by
default. `bossbar_visible` can add or remove any online player.
| Function | Purpose |
| -------- | ------- |
| `hud.title(text)` / `hud.subtitle(text)` | Show a title or subtitle |
| `hud.action_bar(text)` | Show text above the hotbar |
| `hud.title_times(fade_in, stay, fade_out)` | Set title timings in ticks |
| `hud.clear_titles([reset])` | Clear title and subtitle |
| `hud.bossbar_add(id, name[, max])` | Create a boss bar (max defaults to 100) |
| `hud.bossbar_remove(id)` | Remove a boss bar |
| `hud.bossbar_value(id, value)` / `hud.bossbar_max(id, value)` | Change boss bar progress |
| `hud.bossbar_visible(id, visible)` | Show or hide it for the script owner |
```lua
hud.title_times(10, 60, 20)
hud.title("Welcome!")
hud.action_bar("You have " .. scoreboard.get("Alex", "coins") .. " coins")
hud.bossbar_add("round", "Round progress", 10)
hud.bossbar_value("round", 3)
```
## Items and inventories
Item ids can omit the `minecraft:` namespace. Inventory slots are indexed from 0 to 35
in the player's main inventory. The optional player argument names an online player;
when omitted, the script owner is used. Excess items from `items.give` drop at the
target player's feet. `items.clear` and `items.count` only affect the main inventory.
| Function | Purpose |
| -------- | ------- |
| `items.give(item, count[, player])` | Give items; overflow drops at the player |
| `items.count(item[, player])` | Count matching items in the main inventory |
| `items.clear(item[, player])` | Remove matching items; also returns the removed count |
| `items.get_slot(slot[, player])` | Read an inventory slot (item id and count, or `nil`) |
| `items.set_slot(slot, item, count[, player])` | Replace a slot; count 0 clears it |
```lua
items.give("gold_ingot", 8)
print("You now have " .. items.count("minecraft:gold_ingot"))
items.set_slot(0, "minecraft:diamond_sword", 1)
```
All mutating helpers return `true` on success or `false` and a reason on invalid input
or missing targets. Read helpers return their value, or `nil` and a reason when lookup
fails.
## 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 Minecraft API tables. 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:
```lua
for y = 64, 67 do
world.set_block(10, y, -3, "minecraft:cobblestone")
end
```
A 7×7 platform:
```lua
for x = -3, 3 do
for z = -3, 3 do
world.set_block(10 + x, 64, -3 + z, "minecraft:stone_bricks")
end
end
```
A room with walls, a floor and an empty inside, i.e. hollowing out a box:
```lua
local x, y, z = 10, 64, -3 -- corner of the room
local width, height, depth = 7, 4, 7
for dx = 0, width - 1 do
for dy = 0, height - 1 do
for dz = 0, depth - 1 do
local shell = dx == 0 or dx == width - 1
or dy == 0 or dy == height - 1
or dz == 0 or dz == depth - 1
local px, py, pz = x + dx, y + dy, z + dz
if shell then
world.set_block(px, py, pz, "minecraft:stone_bricks")
else
world.remove_block(px, py, pz)
end
end
end
end
```
Copy the block type of one place to another:
```lua
local block = world.get_block(10, 64, -3)
if block then
world.set_block(20, 70, 5, block)
end
```
Clear an area of everything that is not air (leaves, grass, and so on):
```lua
for x = 0, 15 do
for y = 60, 80 do
for z = 0, 15 do
if world.get_block(x, y, z) ~= "minecraft:air" then
world.remove_block(x, y, z)
end
end
end
end
```
## Checking whether a call worked
Every block function returns a reason as its second value, which is worth printing
while a script misbehaves:
```lua
local ok, reason = world.set_block(10, 64, -3, "minecraft:stone")
if not ok then
print("could not place the block: " .. reason)
end
```
| Reason | What it means |
| ------------------------------------------ | ------------------------------------------------------------------------- |
| `usage: world.set_block(...)` | too few arguments |
| `x, y and z must be numbers` | a coordinate is missing, `nil`, or a string like `"10"` |
| `block must be a string, e.g. "minecraft:stone"` | the block was given as a number or table rather than a string |
| `'X' is not a block` | unknown block id, a misspelled state, or a tag such as `#minecraft:logs` |
| `y must be between -64 and 319, not 400` | outside the world's build height |
| `the chunk at x, z is not loaded` | too far away from any player, and not force-loaded |
| `'X' does not fit at x, y, z` | the block was placed and removed itself again (no support block) |
| `there is nothing to remove at x, y, z` | the target block is already air |
## Limits
- No reach or permission checks: a script can change any block in a **loaded** chunk of
the running player's dimension. Keep an eye on what you run.
- Only loaded chunks can be read or edited — those around players, or force-loaded.
- Block entity data is not exposed: a placed chest is empty, and a sign has no text.
- Only `main.lua` is executed. Code in the other project files is not loaded, so
`require` does not find them yet.
- The Lua runtime is LuaJ (Lua 5.1) with only the base library loaded: `tostring`,
`tonumber`, `type`, `pcall`, `pairs`, `ipairs`, `assert`, `error` are available, but
the `string`, `math`, `table` and `coroutine` libraries are not, so `math.floor(2.7)`
fails with *attempt to index a nil value*.