Skip to content

world_api.md

Latest commit

 

History

History
351 lines (247 loc) · 6.43 KB

world_api.md

File metadata and controls

351 lines (247 loc) · 6.43 KB
Raw

World API Documentation

The World API provides Lua scripts with access to manipulate the world in Minecraft, including getting/setting blocks, spawning particles, controlling time and weather, creating explosions, striking lightning, and managing spawn locations.

Global Access

The API is accessed via the global WorldApi table in Lua scripts.

Methods

getBlock

Gets the block at a specific location.

Syntax:

local block = WorldApi:getBlock(location)

Parameters:

  • location (userdata): The Location to query

Returns:

  • block (userdata): The Block object at the location

Example:

local blockLoc = location:clone()
blockLoc:setY(blockLoc:getY() - 1)
local block = WorldApi:getBlock(blockLoc)

setBlock

Sets the block type at a specific location.

Syntax:

WorldApi:setBlock(location, blockType)

Parameters:

  • location (userdata): The Location to modify
  • blockType (string): The block type name (e.g., "STONE", "DIRT", "GRASS_BLOCK")

Example:

WorldApi:setBlock(blockLoc, "STONE")

getBlockData

Gets the block data at a specific location.

Syntax:

local blockData = WorldApi:getBlockData(location)

Parameters:

  • location (userdata): The Location to query

Returns:

  • blockData (userdata): The BlockData object

Example:

local data = WorldApi:getBlockData(blockLoc)

setBlockData

Sets the block data at a specific location.

Syntax:

WorldApi:setBlockData(location, blockData)

Parameters:

  • location (userdata): The Location to modify
  • blockData (userdata): The BlockData object to set

Example:

local data = WorldApi:getBlockData(blockLoc)
WorldApi:setBlockData(blockLoc, data)

spawnParticle

Spawns particles at a location.

Syntax:

WorldApi:spawnParticle(location, particleType, count, offset, [data])

Parameters:

  • location (userdata): The Location to spawn particles at
  • particleType (string): The particle type name (e.g., "FLAME", "SMOKE", "BUBBLE")
  • count (number): Number of particles to spawn
  • offset (number): The offset spread for particles
  • data (userdata, optional): Particle-specific data (e.g., dust color, block state)

Example:

WorldApi:spawnParticle(location, "FLAME", 10, 0.5)

getTime

Gets the world time.

Syntax:

local time = WorldApi:getTime(world)

Parameters:

  • world (userdata): The World to query

Returns:

  • time (number): The world time in ticks

Example:

local time = WorldApi:getTime(world)
print("Time: " .. time)

setTime

Sets the world time.

Syntax:

WorldApi:setTime(world, time)

Parameters:

  • world (userdata): The World to modify
  • time (number): The time to set in ticks

Example:

WorldApi:setTime(world, 1000) -- Morning

isDaytime

Checks if it is currently daytime in the world.

Syntax:

local isDay = WorldApi:isDaytime(world)

Parameters:

  • world (userdata): The World to query

Returns:

  • isDay (boolean): true if it is daytime, false otherwise

Example:

if WorldApi:isDaytime(world) then
    print("It is daytime")
end

getWeather

Gets the current weather in the world.

Syntax:

local weather = WorldApi:getWeather(world)

Parameters:

  • world (userdata): The World to query

Returns:

  • weather (string): The weather type ("clear", "rain", "thunder")

Example:

local weather = WorldApi:getWeather(world)
print("Weather: " .. weather)

setWeather

Sets the weather in the world.

Syntax:

WorldApi:setWeather(world, weatherType, duration)

Parameters:

  • world (userdata): The World to modify
  • weatherType (string): The weather type ("clear", "rain", "thunder")
  • duration (number): Duration in ticks

Example:

WorldApi:setWeather(world, "clear", 6000) -- Clear for 5 minutes

createExplosion

Creates an explosion at a location.

Syntax:

WorldApi:createExplosion(location, power, setFire, breakBlocks)

Parameters:

  • location (userdata): The Location to create the explosion at
  • power (number): The explosion power (typically 1-10)
  • setFire (boolean): Whether the explosion should set blocks on fire
  • breakBlocks (boolean): Whether the explosion should break blocks

Example:

WorldApi:createExplosion(location, 2, false, false)

strikeLightning

Strikes lightning at a location.

Syntax:

local lightning = WorldApi:strikeLightning(location, isEffect)

Parameters:

  • location (userdata): The Location to strike lightning at
  • isEffect (boolean): If true, only the visual effect is shown (no damage)

Returns:

  • lightning (userdata): The LightningStrike object

Example:

local lightning = WorldApi:strikeLightning(location, true) -- Visual only
local lightning = WorldApi:strikeLightning(location, false) -- Real damage

getWorld

Gets a world by name.

Syntax:

local world = WorldApi:getWorld(worldName)

Parameters:

  • worldName (string): The name of the world (e.g., "world", "world_nether", "world_the_end")

Returns:

  • world (userdata): The World object, or nil if not found

Example:

local world = WorldApi:getWorld("world")

getSpawnLocation

Gets the spawn location of a world.

Syntax:

local spawnLocation = WorldApi:getSpawnLocation(world)

Parameters:

  • world (userdata): The World to query

Returns:

  • spawnLocation (userdata): The spawn Location

Example:

local spawn = WorldApi:getSpawnLocation(world)

setSpawnLocation

Sets the spawn location of a world.

Syntax:

WorldApi:setSpawnLocation(world, location)

Parameters:

  • world (userdata): The World to modify
  • location (userdata): The new spawn Location

Example:

local newSpawn = location:clone()
WorldApi:setSpawnLocation(world, newSpawn)

Notes

  • Block type names must be valid Bukkit material names
  • Time is measured in ticks (20 ticks = 1 second)
  • Weather duration is measured in ticks
  • Explosion power of 4 is equivalent to TNT
  • Lightning with isEffect=true will not damage entities or ignite blocks
  • The spawn location must belong to the target world, or the operation will fail
  • Particle data is optional and only required for certain particle types (e.g., DUST_COLOR, BLOCK)