Skip to content

World

Represents the in-game world, exposing time, dimension, spawn location, and chunk state information.

Example: Waiting for the morning

local world = spell.world
print("It's " .. world.timeOfDay .. " in " .. world.dimension)
while world.night do
  sleep(20)
end
spell:execute("/say Good morning!")

Fields

day: boolean — Read-Only

Indicates whether it is currently daytime in the world.

dimension: string — Read-Only

The identifier of the world’s dimension (e.g., "minecraft:overworld", "minecraft:the_nether").

night: boolean — Read-Only

Indicates whether it is currently nighttime in the world.

realtime: number — Read-Only

The current real-world time in milliseconds since 1970-01-01 (UTC), as the server's clock tells it.

spawnPos: Vec3 — Read/Write

The world spawn point where players appear when respawning.

time: number — Read-Only

The number of ticks this world has run. It always advances, even while the daylight cycle is stopped, and it is not affected by /time set.

timeOfDay: number — Read-Only

The time of day in ticks, from 0 to 23999: 0 is sunrise, 6000 noon, 12000 sunset and 18000 midnight. /time set changes it, and it stands still while the daylight cycle is stopped.

Methods

getBiome(pos: Vec3) → biome: string

Returns the biome at the given position, like Spell.biome does for the spell's own position.

It works for any position and never loads a chunk: where none is loaded, it tells the biome the world generator puts there.

Example

local ahead = spell.pos + spell.lookVec * 500
print("500 blocks ahead: " .. spell.world:getBiome(ahead))

Parameters

  • pos: Vec3 — The position.

Returns

  • biome: string — The biome ID (e.g., "plains", "forest", "ocean").

getHeight(pos: Vec3, kind?: Heightmap) → y: number?

Returns the height of the column at the given position: the Y of its topmost block. Only the position's x and z matter. The kind decides which blocks count, so that grass, leaves or water can be looked through.

This reads the heightmaps Minecraft keeps up to date for every loaded chunk, which is much faster than looking at the blocks one by one. It returns nil for a chunk that isn't loaded, and never loads one. Note that Minecraft's own heightmaps give the first free Y above the topmost block, one more than this.

Example: Standing on the ground

local y = spell.world:getHeight(spell.pos, "solid")
if y then
  spell.pos = Vec3(spell.pos.x, y + 1, spell.pos.z)
end

Example: How deep the water is

local surface = spell.world:getHeight(spell.pos, "solid")
local floor = spell.world:getHeight(spell.pos, "floor")
if surface and floor then
  print("The water is " .. (surface - floor) .. " blocks deep")
end

Parameters

  • pos: Vec3 — The position of the column.
  • kind?: Heightmap — Which blocks count. Defaults to "any".

Returns

  • y: number? — The Y of the topmost block that counts, or nil if the chunk isn't loaded or no block of the column counts.

isLoaded(pos: Vec3) → loaded: boolean

Checks whether the chunk containing the specified position is currently loaded in memory.

Example

local position = Vec3(100, 64, 100)
if world:isLoaded(position) then
    print("The chunk at the specified position is loaded.")
else
    print("The chunk at the specified position is not loaded.")
end

Parameters

  • pos: Vec3 — The position to check.

Returns

  • loaded: boolean — true if the chunk is loaded, false otherwise.

predictHeight(pos: Vec3) → y: number?, fluid: string?

Predicts the height of the column at the given position as the world generator will make it: the Y of its topmost block, and the fluid if that block is water or lava. Only the position's x and z matter.

Nothing gets generated or loaded for this, so it is fast enough to look at thousands of places far away, for example to find land before going there. It only knows the bare terrain: the stone, the water and the lava of the world's shape. What comes later in the generation is not part of it: grass, sand and snow on top, trees, lava pools, villages and other structures, and whatever players have built or dug. For a loaded chunk use getHeight instead, which tells the height as it is. In the Nether the topmost block is the bedrock of its ceiling.

Example: Land or sea?

local pos = spell.pos + Vec3(5000, 0, 0)
local y, fluid = spell.world:predictHeight(pos)
if fluid == "water" then
  print("Water at " .. y)
elseif y then
  print("Land at " .. y)
end

Parameters

  • pos: Vec3 — The position of the column.

Returns

  • y: number? — The Y of the topmost block, or nil if the column has no block at all, like the void of the End.
  • fluid: string? — "water" or "lava" if the topmost block is one, otherwise nil.