Files
codecraft/docs/lua-api.md
2026-10-06 17:59:26 +02:00

6.9 KiB
Raw Blame History

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.

print("hello, player!")

print(...)

Writes to the chat of the player who ran the script, tab-separated, like Minecraft commands do.

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:

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:

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.

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:

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:

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:

for y = 64, 67 do
    world.set_block(10, y, -3, "minecraft:cobblestone")
end

A 7×7 platform:

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:

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:

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):

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:

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.