# 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. 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 ``` ## 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 ``` ## Events Listeners let a script react to the game *after* it has finished running. Register one with `events.on_(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: ```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*.