This commit is contained in:
2026-10-06 17:59:26 +02:00
parent f2d09b8a9c
commit 7a115445ab
12 changed files with 1288 additions and 0 deletions

194
docs/lua-api.md Normal file
View File

@@ -0,0 +1,194 @@
# 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.
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.
```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
```
## 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.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
```
## 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*.