The world from Lua

worlds.default(), worlds.by_name(name) and p.pos.world give you a world object. Single blocks use the calls below; edits of many blocks have a bulk form that is orders of magnitude cheaper.

local world = worlds.default()
world:set_block(0, 64, 0, "minecraft:oak_stairs[facing=east]")
print(world:block_state(0, 64, 0))

A position can be given as three integers or as a pos.

Sections#

A section is 16 by 16 by 16 blocks. It travels as a list of 4096 block state ids, ordered x first, then z, then y (index y * 256 + z * 16 + x + 1 for local coordinates from 0). A state id is an integer; worlds.state_id and worlds.state_text convert to and from the text form.

local stone = worlds.state_id("minecraft:stone")
local states = world:section(0, 4, 0)            -- chunk_x, section_y, chunk_z
for i = 1, 4096 do states[i] = stone end
world:set_section(0, 4, 0, states)

In apply_chunk and apply_chunks, sections maps a section y to its 4096 ids, and a negative id keeps the block that is there. options.resend (default true) shows the result to the players; options.previous = true returns a second value with what each section held before, which is what an undo needs. They return the number of blocks that changed, or nil when something was out of range (everything else is still applied).

local changed, before = world:apply_chunk(0, 0, { [4] = states }, { previous = true })

A copy of a section stays good while world.block_version has not moved.

world:resend_chunks({ {0, 0}, {1, 0} }) sends chunks again to the players near them, and world:loaded_chunks() lists the loaded ones as { cx, cz } pairs.

Many positions at once#

world:read_states(positions, load?) returns the state id at each { x, y, z } (-1 where the chunk is not loaded and load is false), and world:write_states(positions, states, notify?) writes them, returning how many changed.

A change of blocks can set off more than the blocks. world:apply_changes(positions, states, effects?) writes the states and then runs effects for the blocks that changed, the way Level.setBlock does in the official server; world:update_neighbors(positions, effects?, previous?) runs them for blocks that are already written, and previous (a state id per position) says what each held before, which the departure of a block needs. effects is a list of names, or their bits added up; without it the effects are neighbors, shapes and clients:

local at = { {10, 64, 10}, {10, 65, 10} }
local changed = world:apply_changes(at, { stone, stone }, { "neighbors", "shapes", "clients" })
-- sand put down this way falls, water flows, a redstone block lights the lamp next to it
world:apply_changes({ {0, 70, 0} }, { worlds.state_id("minecraft:sand") }, { "place", "ticks", "neighbors" })

The pieces of that aftermath can also be asked for on their own, for blocks already written:

Chunks#

world:chunk_sections(cx, cz, load?) returns every section of a chunk at once, a table from section y to the 4096 ids, which is one call instead of one per section. world:chunk_status(cx, cz) says where a chunk stands: unloaded, queued (asked for and on its way), loaded or ticking (loaded near a player).

request_chunk(world, cx, cz, options?) waits until a chunk is loaded, see Scheduler and coroutines. Look at chunk_status afterwards.

request_chunk("world", 40, -12, { urgent = true })
if world:chunk_status(40, -12) ~= "unloaded" then
    local sections = world:chunk_sections(40, -12, false)
end

A chunk another plugin needs can be kept loaded with world:hold_chunks(token, { {40, -12} }). The chunks stay until world:release_chunks(token) is called with the same token, whether or not a player is near.

Block entities#

Chests, signs, banners and the like carry data besides their state. It is read and written as SNBT text, the same notation /data uses.

local chest = world:block_entity(10, 64, 10)       -- nil when the block holds none
world:set_block_entity(10, 64, 10, chest)          -- id, x, y and z in the text are ignored
for _, at in ipairs(world:block_entities(0, 0)) do -- { x, y, z } for every one in a loaded chunk
    print(at[1], at[2], at[3])
end

set_block_entity returns false when the block there owns no block entity, and shows the change to the players who see it. create_block_entity(x, y, z, snbt?) gives the block a block entity (the block's defaults when the text is left out) in place of the one there, and remove_block_entity(x, y, z) takes it away and leaves the block; both return false when they have nothing to do.

Entities as NBT#

local snbt = world:entity_nbt(entity)    -- an entity or its id
local copy = world:spawn_nbt(snbt)       -- edit Pos in the text first to place it elsewhere
world:remove_entity(copy.uuid)           -- takes an entity out by its uuid

spawn_nbt(snbt, cause?) asks the entity.spawn event first, with cause as its reason (plugin unless given), and returns nil when a handler cancels it.

Entities also expose uuid, yaw, pitch, velocity, on_ground, age, width, height and custom_name. world:entity(id_or_uuid) finds one and world:entities_in(cx, cz) lists the entities a chunk would save.

Biomes and light#

Biomes are stored per 4 by 4 by 4 cell. A chunk column has world.height / 4 * 16 of them, ordered (cell_y * 4 + cell_z) * 4 + cell_x from the lowest block up.

local biomes = world:biomes(0, 0)                 -- one name per cell, nil when not loaded
biomes[1] = "minecraft:desert"
world:set_biomes(0, 0, biomes)                    -- shows the chunk again

A cell in set_biomes that is not a string keeps its biome. worlds.biomes() lists every biome name.

The server works the light out itself when blocks change, off the tick thread. These calls are for tools that edit many blocks and want to read the result or take control of it.

world:relight_chunks({ {0, 0} })
print(world:light_at(0, 64, 0, "sky"))

What blocks are#

The tables the server uses for blocks are readable, so a plugin does not need its own copy.

local info = worlds.block_info(worlds.state_id("minecraft:ice"))
print(info.friction, info.push_reaction)   -- 0.98   normal

Old saved data#

Data written by an older version can be brought up to date with the same fixes the server applies to its own worlds. Block states and biome ids are only fixed from data version 2832 (1.18) on; older text comes back unchanged.

print(worlds.fix_name("block_state", "minecraft:grass", 3000))   -- minecraft:short_grass

Threads#

These calls follow the rules of the rest of the API: a plugin runs in its own lane, and the world hands the work to the thread that owns it. Reading a loaded section is cheap from any lane; a write is applied before the call returns.