Documentation

World
in package
implements ChunkManager

Interfaces, Classes, Traits and Enums

ChunkManager

Table of Contents

DEFAULT_TICKED_BLOCKS_PER_SUBCHUNK_PER_TICK  = 3
DIFFICULTY_EASY  = 1
DIFFICULTY_HARD  = 3
DIFFICULTY_NORMAL  = 2
DIFFICULTY_PEACEFUL  = 0
TIME_DAY  = 1000
TIME_FULL  = 24000
TIME_MIDNIGHT  = 18000
TIME_NIGHT  = 13000
TIME_NOON  = 6000
TIME_SUNRISE  = 23000
TIME_SUNSET  = 12000
Y_MAX  = 256
Y_MIN  = 0
BLOCKHASH_X_SHIFT  = self::BLOCKHASH_Y_BITS
BLOCKHASH_XZ_EXTRA_BITS  = self::MORTON3D_BIT_SIZE - self::BLOCKHASH_Y_BITS >> 1
BLOCKHASH_XZ_EXTRA_MASK  = (1 << self::BLOCKHASH_XZ_EXTRA_BITS) - 1
BLOCKHASH_XZ_MASK  = (1 << self::MORTON3D_BIT_SIZE) - 1
BLOCKHASH_XZ_SIGN_SHIFT  = 64 - self::MORTON3D_BIT_SIZE - self::BLOCKHASH_XZ_EXTRA_BITS
BLOCKHASH_Y_BITS  = 9
BLOCKHASH_Y_MASK  = (1 << self::BLOCKHASH_Y_BITS) - 1
BLOCKHASH_Y_OFFSET  = self::BLOCKHASH_Y_PADDING - self::Y_MIN
BLOCKHASH_Y_PADDING  = 128
BLOCKHASH_Z_SHIFT  = self::BLOCKHASH_X_SHIFT + self::BLOCKHASH_XZ_EXTRA_BITS
MORTON3D_BIT_SIZE  = 21
$stopTime  : bool
$tickRateTime  : float
$timings  : WorldTimings
$updateEntities  : array<string|int, Entity>
$activeChunkPopulationTasks  : array<string|int, bool>
$autoSave  : bool
$blockCache  : array<string|int, array<string|int, Block>>
$blockLightUpdate  : BlockLightUpdate|null
$changedBlocks  : array<string|int, array<string|int, Vector3>>
$chunkListeners  : array<string|int, array<string|int, ChunkListener>>
$chunkLoaders  : array<string|int, array<string|int, ChunkLoader>>
$chunkLock  : array<string|int, ChunkLockId>
$chunkPopulationRequestMap  : array<string|int, mixed>
$chunkPopulationRequestQueue  : SplQueue
$chunkPopulationRequestQueueIndex  : array<string|int, mixed>
$chunks  : array<string|int, Chunk>
$chunksPerTick  : int
$chunkTickRadius  : int
$displayName  : string
$doingTick  : bool
$entities  : array<string|int, Entity>
$entitiesByChunk  : array<string|int, mixed>
$entityLastKnownPositions  : array<string|int, Vector3>
$folderName  : string
$generator  : string
$generatorRegisteredWorkers  : array<string|int, bool>
$logger  : Logger
$maxConcurrentChunkPopulationTasks  : int
$maxY  : int
$minY  : int
$neighbourBlockUpdateQueue  : SplQueue
$neighbourBlockUpdateQueueIndex  : array<string|int, bool>
$packetBuffersByChunk  : array<string|int, array<string|int, ClientboundPacket>>
$playerChunkListeners  : array<string|int, array<string|int, Player>>
$players  : array<string|int, Player>
$provider  : WritableWorldProvider
$providerGarbageCollectionTicker  : int
$randomTickBlocks  : array<string|int, bool>
$scheduledBlockUpdateQueue  : ReversePriorityQueue
$scheduledBlockUpdateQueueIndex  : array<string|int, int>
$sendTimeTicker  : int
$server  : Server
$skyLightReduction  : int
$skyLightUpdate  : SkyLightUpdate|null
$sleepTicks  : int
$sunAnglePercentage  : float
$tickedBlocksPerSubchunkPerTick  : int
$tickingLoaderCounter  : array<string|int, int>
$tickingLoaders  : array<string|int, TickingChunkLoader>
$time  : int
$unloadCallbacks  : array<string|int, Closure>
$unloaded  : bool
$unloadQueue  : array<string|int, float>
$workerPool  : AsyncPool
$worldId  : int
$worldIdCounter  : int
__construct()  : mixed
Init the default world data
__debugInfo()  : array<string|int, mixed>
addEntity()  : void
addOnUnloadCallback()  : void
addParticle()  : void
addRandomTickedBlock()  : void
addSound()  : void
blockHash()  : int
broadcastPacketToViewers()  : void
Broadcasts a packet to every player who has the target position within their view distance.
cancelUnloadChunkRequest()  : void
checkSleep()  : void
chunkBlockHash()  : int
Computes a small index relative to chunk base from the given coordinates.
chunkHash()  : int
clearCache()  : void
computeSkyLightReduction()  : int
Computes how many points of sky light is subtracted based on the current time. Used to offset raw chunk sky light to get a real light value.
computeSunAnglePercentage()  : float
Computes the percentage of a circle away from noon the sun is currently at. This can be multiplied by 2 * M_PI to get an angle in radians, or by 360 to get an angle in degrees.
createBlockUpdatePackets()  : array<string|int, ClientboundPacket>
doChunkGarbageCollection()  : void
dropExperience()  : array<string|int, ExperienceOrb>
Drops XP orbs into the world for the specified amount, splitting the amount into several orbs if necessary.
dropItem()  : ItemEntity|null
getAdjacentChunks()  : array<string|int, Chunk>|array<string|int, null>
Returns the chunks adjacent to the specified chunk.
getAutoSave()  : bool
getBiome()  : Biome
getBiomeId()  : int
getBlock()  : Block
Gets the Block object at the Vector3 location. This method wraps around {@link getBlockAt}, converting the vector components to integers.
getBlockAt()  : Block
Gets the Block object at the specified coordinates.
getBlockLightAt()  : int
Gets the raw block light level
getBlockXYZ()  : void
getChunk()  : Chunk|null
getChunkEntities()  : array<string|int, Entity>
getChunkListeners()  : array<string|int, ChunkListener>
Returns all the listeners attached to this chunk.
getChunkLoaders()  : array<string|int, ChunkLoader>
Gets the chunk loaders being used in a specific chunk
getChunkPlayers()  : array<string|int, Player>
getCollidingEntities()  : array<string|int, Entity>
Returns the entities colliding the current one inside the AxisAlignedBB
getCollisionBlocks()  : array<string|int, Block>
getCollisionBoxes()  : array<string|int, AxisAlignedBB>
getDifficulty()  : int
getDifficultyFromString()  : int
getDisplayName()  : string
Returns the World display name.
getEntities()  : array<string|int, Entity>
Gets the list of all the entities in this world
getEntity()  : Entity|null
getFolderName()  : string
Returns the World folder name. This will not change at runtime and will be unique to a world per runtime.
getFullLight()  : int
Returns the highest available level of any type of light at the given coordinates, adjusted for the current weather and time of day.
getFullLightAt()  : int
Returns the highest available level of any type of light at the given coordinates, adjusted for the current weather and time of day.
getHighestAdjacentBlockLight()  : int
Returns the highest block light level available in the positions adjacent to the specified block coordinates.
getHighestAdjacentFullLightAt()  : int
Returns the highest available level of any type of light at, or adjacent to, the given coordinates, adjusted for the current weather and time of day.
getHighestAdjacentPotentialBlockSkyLight()  : int
Returns the highest potential level of sky light in the positions adjacent to the specified block coordinates.
getHighestAdjacentRealBlockSkyLight()  : int
Returns the highest block sky light available in the positions adjacent to the given coordinates, adjusted for the world's current time of day and weather conditions.
getHighestBlockAt()  : int|null
Gets the highest block Y value at a specific $x and $z
getId()  : int
Returns the unique world identifier
getLoadedChunks()  : array<string|int, Chunk>
getLogger()  : Logger
getMaxY()  : int
Returns the highest buildable Y coordinate of the world
getMinY()  : int
Returns the lowest buildable Y coordinate of the world
getNearbyEntities()  : array<string|int, Entity>
Returns the entities near the current one inside the AxisAlignedBB
getNearestEntity()  : Entity|null
Returns the closest Entity to the specified position, within the given radius.
getOrLoadChunkAtPosition()  : Chunk|null
Returns the chunk containing the given Vector3 position.
getPlayers()  : array<string|int, Player>
Returns a list of the players in this world
getPotentialBlockSkyLightAt()  : int
Returns the highest potential level of sky light at the target coordinates, regardless of the time of day or weather conditions.
getProvider()  : WritableWorldProvider
getRandomTickedBlocks()  : array<string|int, bool>
getRealBlockSkyLightAt()  : int
Returns the sky light level at the specified coordinates, offset by the current time and weather.
getSafeSpawn()  : Position
getSeed()  : int
Gets the world seed
getServer()  : Server
getSkyLightReduction()  : int
Returns how many points of sky light is subtracted based on the current time.
getSpawnLocation()  : Position
Returns a Position pointing to the spawn
getSunAngleDegrees()  : float
Returns the current sun angle in degrees.
getSunAnglePercentage()  : float
Returns the percentage of a circle away from noon the sun is currently at.
getSunAngleRadians()  : float
Returns the current sun angle in radians.
getTickRateTime()  : float
getTile()  : Tile|null
Returns the Tile in a position, or null if not found.
getTileAt()  : Tile|null
Returns the tile at the specified x,y,z coordinates, or null if it does not exist.
getTime()  : int
Gets the current time
getTimeOfDay()  : int
Returns the current time of day
getViewersForPosition()  : array<string|int, Player>
Returns an array of players who have the target position within their view distance.
getXZ()  : void
isChunkGenerated()  : bool
isChunkInUse()  : bool
isChunkLoaded()  : bool
isChunkLocked()  : bool
Returns whether anyone currently has a lock on the chunk at the given coordinates.
isChunkPopulated()  : bool
isDoingTick()  : bool
isInLoadedTerrain()  : bool
Returns whether the given position is in a loaded area of terrain.
isInWorld()  : bool
Returns whether the specified coordinates are within the valid world boundaries, taking world format limitations into account.
isLoaded()  : bool
isSpawnChunk()  : bool
Returns whether the chunk at the specified coordinates is a spawn chunk
loadChunk()  : Chunk|null
Attempts to load a chunk from the world provider (if not already loaded). If the chunk is already loaded, it is returned directly.
lockChunk()  : void
Flags a chunk as locked, usually for async modification.
notifyNeighbourBlockUpdate()  : void
Notify the blocks at and around the position that the block at the position may have changed.
orderChunkPopulation()  : Promise
Initiates asynchronous generation/population of the target chunk, if it's not already generated/populated.
registerChunkListener()  : void
Registers a listener to receive events on a chunk.
registerChunkLoader()  : void
registerGeneratorToWorker()  : void
removeEntity()  : void
Removes the entity from the world index
removeOnUnloadCallback()  : void
removeRandomTickedBlock()  : void
requestChunkPopulation()  : Promise
Attempts to initiate asynchronous generation/population of the target chunk, if it's currently reasonable to do so (and if it isn't already generated/populated).
save()  : bool
saveChunks()  : void
scheduleDelayedBlockUpdate()  : void
Schedules a block update to be executed after the specified number of ticks.
setAutoSave()  : void
setBiomeId()  : void
setBlock()  : void
Sets the block at the given Vector3 coordinates.
setBlockAt()  : void
Sets the block at the given coordinates.
setChunk()  : void
setDifficulty()  : void
setSleepTicks()  : void
setSpawnLocation()  : void
Sets the world spawn location
setTime()  : void
Sets the current time on the world
startTime()  : void
Start the time again, if it was stopped
stopTime()  : void
Stops the time for the world, will not save the lock state to disk
unloadChunk()  : bool
unloadChunkRequest()  : bool
unloadChunks()  : void
unlockChunk()  : bool
Unlocks a chunk previously locked by lockChunk().
unregisterChunkListener()  : void
Unregisters a chunk listener previously registered.
unregisterChunkListenerFromAll()  : void
Unregisters a chunk listener from all chunks it is listening on in this World.
unregisterChunkLoader()  : void
unregisterGenerator()  : void
updateAllLight()  : void
useBreakOn()  : bool
Tries to break a block using a item, including Player time checks if available It'll try to lower the durability if Item is a tool, and set it to Air if broken.
useItemOn()  : bool
Uses a item on a position and face, placing it or activating the block
actuallyDoTick()  : void
addChunkHashToPopulationRequestQueue()  : void
broadcastPacketToPlayersUsingChunk()  : void
checkChunkPopulationPreconditions()  : array<string|int, bool>|array<string|int, PromiseResolver>|array<string|int, null>
Checks if a chunk needs to be populated, and whether it's ready to do so.
destroyBlockInternal()  : void
drainPopulationRequestQueue()  : void
enqueuePopulationRequest()  : Promise
executeQueuedLightUpdates()  : void
generateChunkCallback()  : void
getHighestAdjacentLight()  : int
initChunk()  : void
internalOrderChunkPopulation()  : Promise
isChunkTickable()  : bool
orderLightPopulation()  : void
queueUnloadChunk()  : void
tickChunk()  : void
tickChunks()  : void
tryAddToNeighbourUpdateQueue()  : void

Constants

DEFAULT_TICKED_BLOCKS_PER_SUBCHUNK_PER_TICK

public mixed DEFAULT_TICKED_BLOCKS_PER_SUBCHUNK_PER_TICK = 3

DIFFICULTY_EASY

public mixed DIFFICULTY_EASY = 1

DIFFICULTY_HARD

public mixed DIFFICULTY_HARD = 3

DIFFICULTY_NORMAL

public mixed DIFFICULTY_NORMAL = 2

DIFFICULTY_PEACEFUL

public mixed DIFFICULTY_PEACEFUL = 0

TIME_DAY

public mixed TIME_DAY = 1000

TIME_FULL

public mixed TIME_FULL = 24000

TIME_MIDNIGHT

public mixed TIME_MIDNIGHT = 18000

TIME_NIGHT

public mixed TIME_NIGHT = 13000

TIME_NOON

public mixed TIME_NOON = 6000

TIME_SUNRISE

public mixed TIME_SUNRISE = 23000

TIME_SUNSET

public mixed TIME_SUNSET = 12000

Y_MAX

public mixed Y_MAX = 256

Y_MIN

public mixed Y_MIN = 0

BLOCKHASH_X_SHIFT

private mixed BLOCKHASH_X_SHIFT = self::BLOCKHASH_Y_BITS

BLOCKHASH_XZ_EXTRA_BITS

private mixed BLOCKHASH_XZ_EXTRA_BITS = self::MORTON3D_BIT_SIZE - self::BLOCKHASH_Y_BITS >> 1

BLOCKHASH_XZ_EXTRA_MASK

private mixed BLOCKHASH_XZ_EXTRA_MASK = (1 << self::BLOCKHASH_XZ_EXTRA_BITS) - 1

BLOCKHASH_XZ_MASK

private mixed BLOCKHASH_XZ_MASK = (1 << self::MORTON3D_BIT_SIZE) - 1

BLOCKHASH_XZ_SIGN_SHIFT

private mixed BLOCKHASH_XZ_SIGN_SHIFT = 64 - self::MORTON3D_BIT_SIZE - self::BLOCKHASH_XZ_EXTRA_BITS

BLOCKHASH_Y_BITS

private mixed BLOCKHASH_Y_BITS = 9

BLOCKHASH_Y_MASK

private mixed BLOCKHASH_Y_MASK = (1 << self::BLOCKHASH_Y_BITS) - 1

BLOCKHASH_Y_OFFSET

private mixed BLOCKHASH_Y_OFFSET = self::BLOCKHASH_Y_PADDING - self::Y_MIN

BLOCKHASH_Y_PADDING

private mixed BLOCKHASH_Y_PADDING = 128

BLOCKHASH_Z_SHIFT

private mixed BLOCKHASH_Z_SHIFT = self::BLOCKHASH_X_SHIFT + self::BLOCKHASH_XZ_EXTRA_BITS

MORTON3D_BIT_SIZE

private mixed MORTON3D_BIT_SIZE = 21

Properties

$stopTime

public bool $stopTime = false

$tickRateTime

public float $tickRateTime = 0

$updateEntities

public array<string|int, Entity> $updateEntities = []

$activeChunkPopulationTasks

private array<string|int, bool> $activeChunkPopulationTasks = []

$autoSave

private bool $autoSave = true

$blockCache

private array<string|int, array<string|int, Block>> $blockCache = []

$changedBlocks

private array<string|int, array<string|int, Vector3>> $changedBlocks = []

$chunkListeners

private array<string|int, array<string|int, ChunkListener>> $chunkListeners = []

$chunkLoaders

private array<string|int, array<string|int, ChunkLoader>> $chunkLoaders = []

$chunkPopulationRequestMap

private array<string|int, mixed> $chunkPopulationRequestMap = []

chunkHash => promise

Tags
phpstan-var

array<int, PromiseResolver<Chunk>>

$chunkPopulationRequestQueue

private SplQueue $chunkPopulationRequestQueue

(queue of chunkHashes)

Tags
phpstan-var

\SplQueue

$chunkPopulationRequestQueueIndex

private array<string|int, mixed> $chunkPopulationRequestQueueIndex = []

chunkHash => dummy

Tags
phpstan-var

array<int, true>

$chunks

private array<string|int, Chunk> $chunks = []

$chunksPerTick

private int $chunksPerTick

$chunkTickRadius

private int $chunkTickRadius

$displayName

private string $displayName

$doingTick

private bool $doingTick = false

$entities

private array<string|int, Entity> $entities = []

$entitiesByChunk

private array<string|int, mixed> $entitiesByChunk = []
Tags
phpstan-var

array<int, array<int, Entity>>

$entityLastKnownPositions

private array<string|int, Vector3> $entityLastKnownPositions = []
Tags
phpstan-var

array<int, Vector3>

$folderName

private string $folderName

$generator

private string $generator
Tags
phpstan-var

class-string<\pocketmine\world\generator\Generator>

$generatorRegisteredWorkers

private array<string|int, bool> $generatorRegisteredWorkers = []

$maxConcurrentChunkPopulationTasks

private int $maxConcurrentChunkPopulationTasks = 2

$neighbourBlockUpdateQueue

private SplQueue $neighbourBlockUpdateQueue
Tags
phpstan-var

\SplQueue

$neighbourBlockUpdateQueueIndex

private array<string|int, bool> $neighbourBlockUpdateQueueIndex = []

blockhash => dummy

$packetBuffersByChunk

private array<string|int, array<string|int, ClientboundPacket>> $packetBuffersByChunk = []

$playerChunkListeners

private array<string|int, array<string|int, Player>> $playerChunkListeners = []

$providerGarbageCollectionTicker

private int $providerGarbageCollectionTicker = 0

$randomTickBlocks

private array<string|int, bool> $randomTickBlocks = []

$scheduledBlockUpdateQueue

private ReversePriorityQueue $scheduledBlockUpdateQueue
Tags
phpstan-var

ReversePriorityQueue<int, Vector3>

$scheduledBlockUpdateQueueIndex

private array<string|int, int> $scheduledBlockUpdateQueueIndex = []

$sendTimeTicker

private int $sendTimeTicker = 0

$skyLightReduction

private int $skyLightReduction = 0

$sleepTicks

private int $sleepTicks = 0

$sunAnglePercentage

private float $sunAnglePercentage = 0.0

$tickedBlocksPerSubchunkPerTick

private int $tickedBlocksPerSubchunkPerTick = self::DEFAULT_TICKED_BLOCKS_PER_SUBCHUNK_PER_TICK

$tickingLoaderCounter

private array<string|int, int> $tickingLoaderCounter = []

$unloadCallbacks

private array<string|int, Closure> $unloadCallbacks = []
Tags
phpstan-var

array<int, \Closure() : void>

$unloaded

private bool $unloaded = false

$unloadQueue

private array<string|int, float> $unloadQueue = []

$worldId

private int $worldId

$worldIdCounter

private static int $worldIdCounter = 1

Methods

__debugInfo()

public __debugInfo() : array<string|int, mixed>
Return values
array<string|int, mixed>

addEntity()

public addEntity(Entity $entity) : void
Parameters
$entity : Entity
Tags
throws
InvalidArgumentException
Return values
void

addOnUnloadCallback()

public addOnUnloadCallback(Closure $callback) : void
Parameters
$callback : Closure
Tags
phpstan-param

\Closure() : void $callback

Return values
void

addParticle()

public addParticle(Vector3 $pos, Particle $particle[, array<string|int, Player>|null $players = null ]) : void
Parameters
$pos : Vector3
$particle : Particle
$players : array<string|int, Player>|null = null
Return values
void

addRandomTickedBlock()

public addRandomTickedBlock(Block $block) : void
Parameters
$block : Block
Return values
void

addSound()

public addSound(Vector3 $pos, Sound $sound[, array<string|int, Player>|null $players = null ]) : void
Parameters
$pos : Vector3
$sound : Sound
$players : array<string|int, Player>|null = null
Return values
void

blockHash()

public static blockHash(int $x, int $y, int $z) : int
Parameters
$x : int
$y : int
$z : int
Return values
int

broadcastPacketToViewers()

Broadcasts a packet to every player who has the target position within their view distance.

public broadcastPacketToViewers(Vector3 $pos, ClientboundPacket $packet) : void
Parameters
$pos : Vector3
$packet : ClientboundPacket
Return values
void

cancelUnloadChunkRequest()

public cancelUnloadChunkRequest(int $x, int $z) : void
Parameters
$x : int
$z : int
Return values
void

checkSleep()

public checkSleep() : void
Return values
void

chunkBlockHash()

Computes a small index relative to chunk base from the given coordinates.

public static chunkBlockHash(int $x, int $y, int $z) : int
Parameters
$x : int
$y : int
$z : int
Return values
int

chunkHash()

public static chunkHash(int $x, int $z) : int
Parameters
$x : int
$z : int
Return values
int

clearCache()

public clearCache([bool $force = false ]) : void
Parameters
$force : bool = false
Return values
void

computeSkyLightReduction()

Computes how many points of sky light is subtracted based on the current time. Used to offset raw chunk sky light to get a real light value.

public computeSkyLightReduction() : int
Return values
int

computeSunAnglePercentage()

Computes the percentage of a circle away from noon the sun is currently at. This can be multiplied by 2 * M_PI to get an angle in radians, or by 360 to get an angle in degrees.

public computeSunAnglePercentage() : float
Return values
float

doChunkGarbageCollection()

public doChunkGarbageCollection() : void
Return values
void

dropExperience()

Drops XP orbs into the world for the specified amount, splitting the amount into several orbs if necessary.

public dropExperience(Vector3 $pos, int $amount) : array<string|int, ExperienceOrb>
Parameters
$pos : Vector3
$amount : int
Return values
array<string|int, ExperienceOrb>

getAdjacentChunks()

Returns the chunks adjacent to the specified chunk.

public getAdjacentChunks(int $x, int $z) : array<string|int, Chunk>|array<string|int, null>
Parameters
$x : int
$z : int
Return values
array<string|int, Chunk>|array<string|int, null>

getAutoSave()

public getAutoSave() : bool
Return values
bool

getBiome()

public getBiome(int $x, int $z) : Biome
Parameters
$x : int
$z : int
Return values
Biome

getBiomeId()

public getBiomeId(int $x, int $z) : int
Parameters
$x : int
$z : int
Return values
int

getBlock()

Gets the Block object at the Vector3 location. This method wraps around {@link getBlockAt}, converting the vector components to integers.

public getBlock(Vector3 $pos[, bool $cached = true ][, bool $addToCache = true ]) : Block

Note: If you're using this for performance-sensitive code, and you're guaranteed to be supplying ints in the specified vector, consider using instead for better performance.

Parameters
$pos : Vector3
$cached : bool = true

Whether to use the block cache for getting the block (faster, but may be inaccurate)

$addToCache : bool = true

Whether to cache the block object created by this method call.

Return values
Block

getBlockAt()

Gets the Block object at the specified coordinates.

public getBlockAt(int $x, int $y, int $z[, bool $cached = true ][, bool $addToCache = true ]) : Block

Note for plugin developers: If you are using this method a lot (thousands of times for many positions for example), you may want to set addToCache to false to avoid using excessive amounts of memory.

Parameters
$x : int
$y : int
$z : int
$cached : bool = true

Whether to use the block cache for getting the block (faster, but may be inaccurate)

$addToCache : bool = true

Whether to cache the block object created by this method call.

Return values
Block

getBlockLightAt()

Gets the raw block light level

public getBlockLightAt(int $x, int $y, int $z) : int
Parameters
$x : int
$y : int
$z : int
Return values
int

0-15

getBlockXYZ()

public static getBlockXYZ(int $hash, int|null &$x, int|null &$y, int|null &$z) : void
Parameters
$hash : int
$x : int|null
$y : int|null
$z : int|null
Return values
void

getChunk()

public getChunk(int $chunkX, int $chunkZ) : Chunk|null
Parameters
$chunkX : int
$chunkZ : int
Return values
Chunk|null

getChunkEntities()

public getChunkEntities(int $chunkX, int $chunkZ) : array<string|int, Entity>
Parameters
$chunkX : int
$chunkZ : int
Return values
array<string|int, Entity>

getChunkListeners()

Returns all the listeners attached to this chunk.

public getChunkListeners(int $chunkX, int $chunkZ) : array<string|int, ChunkListener>
Parameters
$chunkX : int
$chunkZ : int
Return values
array<string|int, ChunkListener>

getChunkLoaders()

Gets the chunk loaders being used in a specific chunk

public getChunkLoaders(int $chunkX, int $chunkZ) : array<string|int, ChunkLoader>
Parameters
$chunkX : int
$chunkZ : int
Return values
array<string|int, ChunkLoader>

getChunkPlayers()

public getChunkPlayers(int $chunkX, int $chunkZ) : array<string|int, Player>
Parameters
$chunkX : int
$chunkZ : int
Tags
deprecated

WARNING: This function has a misleading name. Contrary to what the name might imply, this function DOES NOT return players who are IN a chunk, rather, it returns players who can SEE the chunk.

Returns a list of players who have the target chunk within their view distance.

Return values
array<string|int, Player>

getCollidingEntities()

Returns the entities colliding the current one inside the AxisAlignedBB

public getCollidingEntities(AxisAlignedBB $bb[, Entity|null $entity = null ]) : array<string|int, Entity>
Parameters
$bb : AxisAlignedBB
$entity : Entity|null = null
Return values
array<string|int, Entity>

getCollisionBlocks()

public getCollisionBlocks(AxisAlignedBB $bb[, bool $targetFirst = false ]) : array<string|int, Block>
Parameters
$bb : AxisAlignedBB
$targetFirst : bool = false
Return values
array<string|int, Block>

getDifficulty()

public getDifficulty() : int
Return values
int

getDifficultyFromString()

public static getDifficultyFromString(string $str) : int
Parameters
$str : string
Return values
int

getDisplayName()

Returns the World display name.

public getDisplayName() : string

WARNING: This is NOT guaranteed to be unique. Multiple worlds at runtime may share the same display name.

Return values
string

getEntities()

Gets the list of all the entities in this world

public getEntities() : array<string|int, Entity>
Return values
array<string|int, Entity>

getEntity()

public getEntity(int $entityId) : Entity|null
Parameters
$entityId : int
Return values
Entity|null

getFolderName()

Returns the World folder name. This will not change at runtime and will be unique to a world per runtime.

public getFolderName() : string
Return values
string

getFullLight()

Returns the highest available level of any type of light at the given coordinates, adjusted for the current weather and time of day.

public getFullLight(Vector3 $pos) : int
Parameters
$pos : Vector3
Return values
int

getFullLightAt()

Returns the highest available level of any type of light at the given coordinates, adjusted for the current weather and time of day.

public getFullLightAt(int $x, int $y, int $z) : int
Parameters
$x : int
$y : int
$z : int
Return values
int

getHighestAdjacentBlockLight()

Returns the highest block light level available in the positions adjacent to the specified block coordinates.

public getHighestAdjacentBlockLight(int $x, int $y, int $z) : int
Parameters
$x : int
$y : int
$z : int
Return values
int

getHighestAdjacentFullLightAt()

Returns the highest available level of any type of light at, or adjacent to, the given coordinates, adjusted for the current weather and time of day.

public getHighestAdjacentFullLightAt(int $x, int $y, int $z) : int
Parameters
$x : int
$y : int
$z : int
Return values
int

getHighestAdjacentPotentialBlockSkyLight()

Returns the highest potential level of sky light in the positions adjacent to the specified block coordinates.

public getHighestAdjacentPotentialBlockSkyLight(int $x, int $y, int $z) : int
Parameters
$x : int
$y : int
$z : int
Return values
int

getHighestAdjacentRealBlockSkyLight()

Returns the highest block sky light available in the positions adjacent to the given coordinates, adjusted for the world's current time of day and weather conditions.

public getHighestAdjacentRealBlockSkyLight(int $x, int $y, int $z) : int
Parameters
$x : int
$y : int
$z : int
Return values
int

getHighestBlockAt()

Gets the highest block Y value at a specific $x and $z

public getHighestBlockAt(int $x, int $z) : int|null
Parameters
$x : int
$z : int
Tags
throws
WorldException

if the terrain is not generated

Return values
int|null

0-255, or null if the column is empty

getId()

Returns the unique world identifier

public final getId() : int
Return values
int

getLoadedChunks()

public getLoadedChunks() : array<string|int, Chunk>
Return values
array<string|int, Chunk>

getMaxY()

Returns the highest buildable Y coordinate of the world

public getMaxY() : int
Return values
int

getMinY()

Returns the lowest buildable Y coordinate of the world

public getMinY() : int
Return values
int

getNearbyEntities()

Returns the entities near the current one inside the AxisAlignedBB

public getNearbyEntities(AxisAlignedBB $bb[, Entity|null $entity = null ]) : array<string|int, Entity>
Parameters
$bb : AxisAlignedBB
$entity : Entity|null = null
Return values
array<string|int, Entity>

getNearestEntity()

Returns the closest Entity to the specified position, within the given radius.

public getNearestEntity(Vector3 $pos, float $maxDistance[, string $entityType = Entity::class ][, bool $includeDead = false ]) : Entity|null
Parameters
$pos : Vector3
$maxDistance : float
$entityType : string = Entity::class

Class of entity to use for instanceof

$includeDead : bool = false

Whether to include entitites which are dead

Tags
phpstan-template

TEntity of Entity

phpstan-param

class-string<TEntity> $entityType

phpstan-return

TEntity

Return values
Entity|null

an entity of type $entityType, or null if not found

getOrLoadChunkAtPosition()

Returns the chunk containing the given Vector3 position.

public getOrLoadChunkAtPosition(Vector3 $pos) : Chunk|null
Parameters
$pos : Vector3
Return values
Chunk|null

getPlayers()

Returns a list of the players in this world

public getPlayers() : array<string|int, Player>
Return values
array<string|int, Player>

getPotentialBlockSkyLightAt()

Returns the highest potential level of sky light at the target coordinates, regardless of the time of day or weather conditions.

public getPotentialBlockSkyLightAt(int $x, int $y, int $z) : int

You usually don't want to use this for vanilla gameplay logic; prefer the real sky light instead.

Parameters
$x : int
$y : int
$z : int
Tags
see
World::getRealBlockSkyLightAt()
Return values
int

0-15

getRandomTickedBlocks()

public getRandomTickedBlocks() : array<string|int, bool>
Return values
array<string|int, bool>

fullID => bool

getRealBlockSkyLightAt()

Returns the sky light level at the specified coordinates, offset by the current time and weather.

public getRealBlockSkyLightAt(int $x, int $y, int $z) : int
Parameters
$x : int
$y : int
$z : int
Return values
int

0-15

getSeed()

Gets the world seed

public getSeed() : int
Return values
int

getSkyLightReduction()

Returns how many points of sky light is subtracted based on the current time.

public getSkyLightReduction() : int
Return values
int

getSpawnLocation()

Returns a Position pointing to the spawn

public getSpawnLocation() : Position
Return values
Position

getSunAngleDegrees()

Returns the current sun angle in degrees.

public getSunAngleDegrees() : float
Return values
float

getSunAnglePercentage()

Returns the percentage of a circle away from noon the sun is currently at.

public getSunAnglePercentage() : float
Return values
float

getSunAngleRadians()

Returns the current sun angle in radians.

public getSunAngleRadians() : float
Return values
float

getTickRateTime()

public getTickRateTime() : float
Return values
float

getTile()

Returns the Tile in a position, or null if not found.

public getTile(Vector3 $pos) : Tile|null

Note: This method wraps getTileAt(). If you're guaranteed to be passing integers, and you're using this method in performance-sensitive code, consider using getTileAt() instead of this method for better performance.

Parameters
$pos : Vector3
Return values
Tile|null

getTileAt()

Returns the tile at the specified x,y,z coordinates, or null if it does not exist.

public getTileAt(int $x, int $y, int $z) : Tile|null
Parameters
$x : int
$y : int
$z : int
Return values
Tile|null

getTime()

Gets the current time

public getTime() : int
Return values
int

getTimeOfDay()

Returns the current time of day

public getTimeOfDay() : int
Return values
int

getViewersForPosition()

Returns an array of players who have the target position within their view distance.

public getViewersForPosition(Vector3 $pos) : array<string|int, Player>
Parameters
$pos : Vector3
Return values
array<string|int, Player>

getXZ()

public static getXZ(int $hash, int|null &$x, int|null &$z) : void
Parameters
$hash : int
$x : int|null
$z : int|null
Return values
void

isChunkGenerated()

public isChunkGenerated(int $x, int $z) : bool
Parameters
$x : int
$z : int
Return values
bool

isChunkInUse()

public isChunkInUse(int $x, int $z) : bool
Parameters
$x : int
$z : int
Return values
bool

isChunkLoaded()

public isChunkLoaded(int $x, int $z) : bool
Parameters
$x : int
$z : int
Return values
bool

isChunkLocked()

Returns whether anyone currently has a lock on the chunk at the given coordinates.

public isChunkLocked(int $chunkX, int $chunkZ) : bool

You should check this to make sure that population tasks aren't currently modifying chunks that you want to use in async tasks.

Parameters
$chunkX : int
$chunkZ : int
Return values
bool

isChunkPopulated()

public isChunkPopulated(int $x, int $z) : bool
Parameters
$x : int
$z : int
Return values
bool

isDoingTick()

public isDoingTick() : bool
Return values
bool

isInLoadedTerrain()

Returns whether the given position is in a loaded area of terrain.

public isInLoadedTerrain(Vector3 $pos) : bool
Parameters
$pos : Vector3
Return values
bool

isInWorld()

Returns whether the specified coordinates are within the valid world boundaries, taking world format limitations into account.

public isInWorld(int $x, int $y, int $z) : bool
Parameters
$x : int
$y : int
$z : int
Return values
bool

isLoaded()

public isLoaded() : bool
Return values
bool

isSpawnChunk()

Returns whether the chunk at the specified coordinates is a spawn chunk

public isSpawnChunk(int $X, int $Z) : bool
Parameters
$X : int
$Z : int
Return values
bool

loadChunk()

Attempts to load a chunk from the world provider (if not already loaded). If the chunk is already loaded, it is returned directly.

public loadChunk(int $x, int $z) : Chunk|null
Parameters
$x : int
$z : int
Return values
Chunk|null

the requested chunk, or null on failure.

lockChunk()

Flags a chunk as locked, usually for async modification.

public lockChunk(int $chunkX, int $chunkZ, ChunkLockId $lockId) : void

This is an advisory lock. This means that the lock does not prevent the chunk from being modified on the main thread, such as by setBlock() or setBiomeId(). However, you can use it to detect when such modifications have taken place - unlockChunk() with the same lockID will fail and return false if this happens.

This is used internally by the generation system to ensure that two PopulationTasks don't try to modify the same chunk at the same time. Generation will respect these locks and won't try to do generation of chunks over which a lock is held.

WARNING: Be sure to release all locks once you're done with them, or you WILL have problems with terrain not being generated.

Parameters
$chunkX : int
$chunkZ : int
$lockId : ChunkLockId
Return values
void

notifyNeighbourBlockUpdate()

Notify the blocks at and around the position that the block at the position may have changed.

public notifyNeighbourBlockUpdate(Vector3 $pos) : void

This will cause onNeighbourBlockUpdate() to be called for these blocks.

Parameters
$pos : Vector3
Return values
void

orderChunkPopulation()

Initiates asynchronous generation/population of the target chunk, if it's not already generated/populated.

public orderChunkPopulation(int $chunkX, int $chunkZ, ChunkLoader|null $associatedChunkLoader) : Promise

If generation has already been requested for the target chunk, the promise for the already active request will be returned directly.

If the chunk is currently locked (for example due to another chunk using it for async generation), the request will be queued and executed at the earliest opportunity.

Parameters
$chunkX : int
$chunkZ : int
$associatedChunkLoader : ChunkLoader|null
Tags
phpstan-return

Promise<Chunk>

Return values
Promise

registerChunkListener()

Registers a listener to receive events on a chunk.

public registerChunkListener(ChunkListener $listener, int $chunkX, int $chunkZ) : void
Parameters
$listener : ChunkListener
$chunkX : int
$chunkZ : int
Return values
void

registerChunkLoader()

public registerChunkLoader(ChunkLoader $loader, int $chunkX, int $chunkZ[, bool $autoLoad = true ]) : void
Parameters
$loader : ChunkLoader
$chunkX : int
$chunkZ : int
$autoLoad : bool = true
Return values
void

registerGeneratorToWorker()

public registerGeneratorToWorker(int $worker) : void
Parameters
$worker : int
Return values
void

removeEntity()

Removes the entity from the world index

public removeEntity(Entity $entity) : void
Parameters
$entity : Entity
Tags
throws
InvalidArgumentException
Return values
void

removeOnUnloadCallback()

public removeOnUnloadCallback(Closure $callback) : void
Parameters
$callback : Closure
Tags
phpstan-param

\Closure() : void $callback

Return values
void

removeRandomTickedBlock()

public removeRandomTickedBlock(Block $block) : void
Parameters
$block : Block
Return values
void

requestChunkPopulation()

Attempts to initiate asynchronous generation/population of the target chunk, if it's currently reasonable to do so (and if it isn't already generated/populated).

public requestChunkPopulation(int $chunkX, int $chunkZ, ChunkLoader|null $associatedChunkLoader) : Promise

If the generator is busy, the request will be put into a queue and delayed until a better time.

A ChunkLoader can be associated with the generation request to ensure that the generation request is cancelled if no loaders are attached to the target chunk. If no loader is provided, one will be assigned (and automatically removed when the generation request completes).

Parameters
$chunkX : int
$chunkZ : int
$associatedChunkLoader : ChunkLoader|null
Tags
phpstan-return

Promise<Chunk>

Return values
Promise

save()

public save([bool $force = false ]) : bool
Parameters
$force : bool = false
Return values
bool

saveChunks()

public saveChunks() : void
Return values
void

scheduleDelayedBlockUpdate()

Schedules a block update to be executed after the specified number of ticks.

public scheduleDelayedBlockUpdate(Vector3 $pos, int $delay) : void

Blocks will be updated with the scheduled update type.

Parameters
$pos : Vector3
$delay : int
Return values
void

setAutoSave()

public setAutoSave(bool $value) : void
Parameters
$value : bool
Return values
void

setBiomeId()

public setBiomeId(int $x, int $z, int $biomeId) : void
Parameters
$x : int
$z : int
$biomeId : int
Return values
void

setBlock()

Sets the block at the given Vector3 coordinates.

public setBlock(Vector3 $pos, Block $block[, bool $update = true ]) : void
Parameters
$pos : Vector3
$block : Block
$update : bool = true
Tags
throws
InvalidArgumentException

if the position is out of the world bounds

Return values
void

setBlockAt()

Sets the block at the given coordinates.

public setBlockAt(int $x, int $y, int $z, Block $block[, bool $update = true ]) : void

If $update is true, it'll get the neighbour blocks (6 sides) and update them, and also update local lighting. If you are doing big changes, you might want to set this to false, then update manually.

Parameters
$x : int
$y : int
$z : int
$block : Block
$update : bool = true
Tags
throws
InvalidArgumentException

if the position is out of the world bounds

Return values
void

setChunk()

public setChunk(int $chunkX, int $chunkZ, Chunk $chunk) : void
Parameters
$chunkX : int
$chunkZ : int
$chunk : Chunk
Return values
void

setDifficulty()

public setDifficulty(int $difficulty) : void
Parameters
$difficulty : int
Return values
void

setSleepTicks()

public setSleepTicks(int $ticks) : void
Parameters
$ticks : int
Return values
void

setSpawnLocation()

Sets the world spawn location

public setSpawnLocation(Vector3 $pos) : void
Parameters
$pos : Vector3
Return values
void

setTime()

Sets the current time on the world

public setTime(int $time) : void
Parameters
$time : int
Return values
void

startTime()

Start the time again, if it was stopped

public startTime() : void
Return values
void

stopTime()

Stops the time for the world, will not save the lock state to disk

public stopTime() : void
Return values
void

unloadChunk()

public unloadChunk(int $x, int $z[, bool $safe = true ][, bool $trySave = true ]) : bool
Parameters
$x : int
$z : int
$safe : bool = true
$trySave : bool = true
Return values
bool

unloadChunkRequest()

public unloadChunkRequest(int $x, int $z[, bool $safe = true ]) : bool
Parameters
$x : int
$z : int
$safe : bool = true
Return values
bool

unloadChunks()

public unloadChunks([bool $force = false ]) : void
Parameters
$force : bool = false
Return values
void

unlockChunk()

Unlocks a chunk previously locked by lockChunk().

public unlockChunk(int $chunkX, int $chunkZ, ChunkLockId|null $lockId) : bool

You must provide the same lockID as provided to lockChunk(). If a null lockID is given, any existing lock will be removed from the chunk, regardless of who owns it.

Returns true if unlocking was successful, false otherwise.

Parameters
$chunkX : int
$chunkZ : int
$lockId : ChunkLockId|null
Return values
bool

unregisterChunkListenerFromAll()

Unregisters a chunk listener from all chunks it is listening on in this World.

public unregisterChunkListenerFromAll(ChunkListener $listener) : void
Parameters
$listener : ChunkListener
Return values
void

unregisterChunkLoader()

public unregisterChunkLoader(ChunkLoader $loader, int $chunkX, int $chunkZ) : void
Parameters
$loader : ChunkLoader
$chunkX : int
$chunkZ : int
Return values
void

unregisterGenerator()

public unregisterGenerator() : void
Return values
void

updateAllLight()

public updateAllLight(int $x, int $y, int $z) : void
Parameters
$x : int
$y : int
$z : int
Return values
void

useBreakOn()

Tries to break a block using a item, including Player time checks if available It'll try to lower the durability if Item is a tool, and set it to Air if broken.

public useBreakOn(Vector3 $vector[, Item &$item = null ][, Player|null $player = null ][, bool $createParticles = false ]) : bool
Parameters
$vector : Vector3
$item : Item = null

reference parameter (if null, can break anything)

$player : Player|null = null
$createParticles : bool = false
Return values
bool

useItemOn()

Uses a item on a position and face, placing it or activating the block

public useItemOn(Vector3 $vector, Item &$item, int $face[, Vector3|null $clickVector = null ][, Player|null $player = null ][, bool $playSound = false ]) : bool
Parameters
$vector : Vector3
$item : Item
$face : int
$clickVector : Vector3|null = null
$player : Player|null = null

default null

$playSound : bool = false

Whether to play a block-place sound if the block was placed successfully.

Return values
bool

actuallyDoTick()

protected actuallyDoTick(int $currentTick) : void
Parameters
$currentTick : int
Return values
void

addChunkHashToPopulationRequestQueue()

private addChunkHashToPopulationRequestQueue(int $chunkHash) : void
Parameters
$chunkHash : int
Return values
void

broadcastPacketToPlayersUsingChunk()

private broadcastPacketToPlayersUsingChunk(int $chunkX, int $chunkZ, ClientboundPacket $packet) : void
Parameters
$chunkX : int
$chunkZ : int
$packet : ClientboundPacket
Return values
void

checkChunkPopulationPreconditions()

Checks if a chunk needs to be populated, and whether it's ready to do so.

private checkChunkPopulationPreconditions(int $chunkX, int $chunkZ) : array<string|int, bool>|array<string|int, PromiseResolver>|array<string|int, null>
Parameters
$chunkX : int
$chunkZ : int
Tags
phpstan-return

array{?PromiseResolver<Chunk>, bool}

Return values
array<string|int, bool>|array<string|int, PromiseResolver>|array<string|int, null>

destroyBlockInternal()

private destroyBlockInternal(Block $target, Item $item[, Player|null $player = null ][, bool $createParticles = false ]) : void
Parameters
$target : Block
$item : Item
$player : Player|null = null
$createParticles : bool = false
Return values
void

drainPopulationRequestQueue()

private drainPopulationRequestQueue() : void
Return values
void

enqueuePopulationRequest()

private enqueuePopulationRequest(int $chunkX, int $chunkZ, ChunkLoader|null $associatedChunkLoader) : Promise
Parameters
$chunkX : int
$chunkZ : int
$associatedChunkLoader : ChunkLoader|null
Tags
phpstan-return

Promise<Chunk>

Return values
Promise

executeQueuedLightUpdates()

private executeQueuedLightUpdates() : void
Return values
void

generateChunkCallback()

private generateChunkCallback(ChunkLockId $chunkLockId, int $x, int $z, Chunk $chunk, array<string|int, Chunk$adjacentChunks, ChunkLoader $temporaryChunkLoader) : void
Parameters
$chunkLockId : ChunkLockId
$x : int
$z : int
$chunk : Chunk
$adjacentChunks : array<string|int, Chunk>

chunkHash => chunk

$temporaryChunkLoader : ChunkLoader
Tags
phpstan-param

array<int, Chunk> $adjacentChunks

Return values
void

getHighestAdjacentLight()

private getHighestAdjacentLight(int $x, int $y, int $z, Closure $lightGetter) : int
Parameters
$x : int
$y : int
$z : int
$lightGetter : Closure
Tags
phpstan-param

\Closure(int $x, int $y, int $z) : int $lightGetter

Return values
int

initChunk()

private initChunk(int $chunkX, int $chunkZ, ChunkData $chunkData) : void
Parameters
$chunkX : int
$chunkZ : int
$chunkData : ChunkData
Return values
void

internalOrderChunkPopulation()

private internalOrderChunkPopulation(int $chunkX, int $chunkZ, ChunkLoader|null $associatedChunkLoader, PromiseResolver|null $resolver) : Promise
Parameters
$chunkX : int
$chunkZ : int
$associatedChunkLoader : ChunkLoader|null
$resolver : PromiseResolver|null
Tags
phpstan-param

PromiseResolver<Chunk>|null $resolver

phpstan-return

Promise<Chunk>

Return values
Promise

isChunkTickable()

private isChunkTickable(int $chunkX, int $chunkZ) : bool
Parameters
$chunkX : int
$chunkZ : int
Return values
bool

orderLightPopulation()

private orderLightPopulation(int $chunkX, int $chunkZ) : void
Parameters
$chunkX : int
$chunkZ : int
Return values
void

queueUnloadChunk()

private queueUnloadChunk(int $x, int $z) : void
Parameters
$x : int
$z : int
Return values
void

tickChunk()

private tickChunk(int $chunkX, int $chunkZ) : void
Parameters
$chunkX : int
$chunkZ : int
Return values
void

tickChunks()

private tickChunks() : void
Return values
void

tryAddToNeighbourUpdateQueue()

private tryAddToNeighbourUpdateQueue(Vector3 $pos) : void
Parameters
$pos : Vector3
Return values
void

Search results