195 lines
6.9 KiB
Markdown
195 lines
6.9 KiB
Markdown
# 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*.
|