Skip to main content

world — World API

Phase: Server

The world global targets the overworld by default. Use world.inDimension(id) to get an equivalent table for any loaded dimension.

Block Operations​

world.setBlock(x, y, z, blockId)​

Places a block at the given coordinates using its default block state.

world.setBlock(100, 64, 100, "minecraft:diamond_block")

world.getBlock(x, y, z) → string​

Returns the block identifier at the given coordinates.

local block = world.getBlock(0, 64, 0)
print(block)  -- "minecraft:grass_block"

world.fill(x1, y1, z1, x2, y2, z2, blockId)​

Fills a rectangular region with the given block. Limited to 64,000 blocks per call.

-- Clear a 10×10×10 area
world.fill(0, 60, 0, 9, 69, 9, "minecraft:air")

Entity & Particles​

world.spawnEntity(typeId, x, y, z)​

Spawns an entity of the given type at the specified position.

world.spawnEntity("minecraft:creeper", 100, 64, 100)
world.spawnEntity("minecraft:villager", 0, 65, 0)

world.spawnParticle(particleId, x, y, z [, count])​

Spawns particles at the given position. count defaults to 1.

world.spawnParticle("minecraft:flame", 0, 70, 0, 20)
world.spawnParticle("minecraft:heart", player.pos.x, player.pos.y + 1, player.pos.z)

Sound & Effects​

world.playSound(soundId, x, y, z [, volume [, pitch]])​

Plays a sound at the given position. volume defaults to 1.0, pitch defaults to 1.0.

world.playSound("minecraft:entity.lightning_bolt.thunder", 0, 64, 0, 1.0, 1.0)

world.explode(x, y, z, power [, createFire])​

Creates an explosion at the given coordinates. createFire defaults to false.

world.explode(0, 64, 0, 4.0)         -- TNT-strength explosion
world.explode(0, 64, 0, 8.0, true)   -- large explosion with fire

Time​

world.getTime() → int​

Returns the total world age in ticks (always increasing).

world.getTimeOfDay() → int​

Returns the time of day in ticks, in the range 0–23999. (6000 = noon, 18000 = midnight.)

local tod = world.getTimeOfDay()
if tod > 13000 and tod < 23000 then
  logger.info("It is night-time")
end

world.setTimeOfDay(ticks)​

Sets the time of day for the dimension.

world.setTimeOfDay(6000)   -- set to noon
world.setTimeOfDay(18000)  -- set to midnight

Weather & Dimension​

world.isRaining() → boolean​

Returns true if it is currently raining in this dimension.

world.getDimension() → string​

Returns this world's registry key, e.g. "minecraft:overworld".

world.getDimensions() → table​

Returns a sequential table of dimension identifiers for every loaded world.

for _, dim in ipairs(world.getDimensions()) do
  print(dim)
end

world.inDimension(dimId) → world table​

Returns a world API table targeting the given dimension. All methods above are available on the returned table.

local nether = world.inDimension("minecraft:the_nether")
nether.setBlock(0, 60, 0, "minecraft:netherrack")
nether.spawnEntity("minecraft:blaze", 0, 61, 0)