World & WorldManager API

Complete API reference for world management and world manipulation in PocketMine-MP

Overview

The World API provides comprehensive control over game worlds, including block manipulation, entity management, chunk loading, time control, and world events.

World Class

The World class represents a loaded world in PocketMine-MP.

Namespace: pocketmine\world\World

Constants

Y_MAX · int · default: "320"

Maximum world height

Y_MIN · int · default: "-64"

Minimum world height

TIME_DAY · int · default: "1000"

Time value for day

TIME_NOON · int · default: "6000"

Time value for noon

TIME_SUNSET · int · default: "12000"

Time value for sunset

TIME_NIGHT · int · default: "13000"

Time value for night

TIME_MIDNIGHT · int · default: "18000"

Time value for midnight

TIME_SUNRISE · int · default: "23000"

Time value for sunrise

TIME_FULL · int · default: "24000"

Full day-night cycle duration

DIFFICULTY_PEACEFUL · int · default: "0"

Peaceful difficulty level

DIFFICULTY_EASY · int · default: "1"

Easy difficulty level

DIFFICULTY_NORMAL · int · default: "2"

Normal difficulty level

DIFFICULTY_HARD · int · default: "3"

Hard difficulty level

Core Methods

getId

public function getId() : int

Returns the unique world identifier.

return · int

The unique world ID

---

getFolderName

public function getFolderName() : string

Returns the folder name of the world.

---

getDisplayName

public function getDisplayName() : string

Returns the display name of the world.

---

getServer

public function getServer() : Server

Returns the Server instance.

---

getProvider

public function getProvider() : WritableWorldProvider

Returns the world provider handling world data storage.

---

Block Manipulation

getBlock

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

Gets a block at the specified position.

pos · Vector3 · required

Position of the block

cached · bool · default: "true"

Whether to use cached block data

addToCache · bool · default: "true"

Whether to add the block to cache

return · Block

The block at the specified position

// Example: Get block at position
$block = $world->getBlock(new Vector3(100, 64, 100));
$player->sendMessage("Block: " . $block->getName());

---

setBlock

public function setBlock(Vector3 $pos, Block $block, bool $update = true) : void

Sets a block at the specified position.

pos · Vector3 · required

Position to place the block

block · Block · required

Block to place

update · bool · default: "true"

Whether to send updates to clients

// Example: Place a block
use pocketmine\block\VanillaBlocks;

$world->setBlock(new Vector3(100, 64, 100), VanillaBlocks::STONE());

---

isInWorld

public function isInWorld(int $x, int $y, int $z) : bool

Checks if coordinates are within valid world bounds.

x · int · required

X coordinate

y · int · required

Y coordinate

z · int · required

Z coordinate

---

Entity Management

getEntity

public function getEntity(int $entityId) : ?Entity

Gets an entity by its runtime ID.

entityId · int · required

The entity’s runtime ID

return · Entity|null

The entity, or null if not found

---

getEntities

public function getEntities() : array

Returns all entities in the world.

return · Entity[]

Array of all entities

---

getNearbyEntities

public function getNearbyEntities(AxisAlignedBB $bb, ?Entity $entity = null) : array

Gets entities within a bounding box.

bb · AxisAlignedBB · required

The bounding box to search within

entity · Entity|null

Entity to exclude from results

return · Entity[]

Entities within the bounding box

// Example: Find nearby entities
use pocketmine\math\AxisAlignedBB;

$bb = new AxisAlignedBB(
    $pos->x - 5, $pos->y - 5, $pos->z - 5,
    $pos->x + 5, $pos->y + 5, $pos->z + 5
);
$nearby = $world->getNearbyEntities($bb);
foreach($nearby as $entity){
    // Process nearby entities
}

---

Player Management

getPlayers

public function getPlayers() : array

Returns all players currently in the world.

return · Player[]

Array of all players

// Example: Broadcast message to all players in world
foreach($world->getPlayers() as $player){
    $player->sendMessage("World event!");
}

---

Time & Weather

getTime

public function getTime() : int

Returns the current world time.

return · int

Current time (0-23999)

---

setTime

public function setTime(int $time) : void

Sets the world time.

time · int · required

Time value to set (0-23999)

// Example: Set time to day
$world->setTime(World::TIME_DAY);

// Example: Set time to night
$world->setTime(World::TIME_NIGHT);

---

Chunk Operations

loadChunk

public function loadChunk(int $chunkX, int $chunkZ) : ?Chunk

Loads a chunk at the specified coordinates.

chunkX · int · required

Chunk X coordinate

chunkZ · int · required

Chunk Z coordinate

return · Chunk|null

The loaded chunk, or null if unavailable

---

isChunkLoaded

public function isChunkLoaded(int $chunkX, int $chunkZ) : bool

Checks if a chunk is loaded.

---

Effects & Sounds

addSound

public function addSound(Vector3 $pos, Sound $sound, ?array $players = null) : void

Plays a sound at the specified position.

pos · Vector3 · required

Position to play the sound

sound · Sound · required

Sound to play

players · Player[]|null

Specific players to play sound for (null = all viewers)

// Example: Play a sound
use pocketmine\world\sound\ClickSound;

$world->addSound($player->getPosition(), new ClickSound());

---

addParticle

public function addParticle(Vector3 $pos, Particle $particle, ?array $players = null) : void

Spawns a particle at the specified position.

pos · Vector3 · required

Position to spawn the particle

particle · Particle · required

Particle to spawn

players · Player[]|null

Specific players to show particle to (null = all viewers)

// Example: Spawn particles
use pocketmine\world\particle\FlameParticle;

$world->addParticle($pos, new FlameParticle());

---

World Data

save

public function save(bool $force = false) : void

Saves the world data to disk.

force · bool · default: "false"

Whether to force save even if auto-save is disabled

---

WorldManager Class

Manages all loaded worlds on the server.

Namespace: pocketmine\world\WorldManager

Core Methods

getWorlds

public function getWorlds() : array

Returns all loaded worlds.

return · World[]

Array of all loaded worlds indexed by world ID

// Example: List all worlds
$worldManager = $server->getWorldManager();
foreach($worldManager->getWorlds() as $world){
    $server->getLogger()->info("World: " . $world->getDisplayName());
}

---

getDefaultWorld

public function getDefaultWorld() : ?World

Returns the default world (spawn world).

return · World|null

The default world, or null if not set

---

setDefaultWorld

public function setDefaultWorld(?World $world) : void

Sets the default world.

world · World|null · required

World to set as default, or null to unset

---

getWorldByName

public function getWorldByName(string $name) : ?World

Finds a world by its folder name.

name · string · required

Folder name of the world

return · World|null

The world, or null if not found

// Example: Get world by name
$world = $server->getWorldManager()->getWorldByName("world");
if($world !== null){
    $player->teleport($world->getSafeSpawn());
}

---

isWorldLoaded

public function isWorldLoaded(string $name) : bool

Checks if a world is loaded.

name · string · required

Folder name of the world

---

loadWorld

public function loadWorld(string $name, bool $autoUpgrade = false) : bool

Loads a world from the worlds folder.

name · string · required

Folder name of the world to load

autoUpgrade · bool · default: "false"

Whether to automatically upgrade old world formats

return · bool

True if the world was loaded successfully

// Example: Load a world
$worldManager = $server->getWorldManager();
if($worldManager->loadWorld("custom_world")){
    $server->getLogger()->info("World loaded successfully!");
}

---

unloadWorld

public function unloadWorld(World $world, bool $forceUnload = false) : bool

Unloads a world from memory.

world · World · required

The world to unload

forceUnload · bool · default: "false"

Whether to force unload (even if it’s the default world)

return · bool

True if the world was unloaded successfully

---

generateWorld

public function generateWorld(string $name, WorldCreationOptions $options, bool $backgroundGeneration = true) : bool

Generates a new world.

name · string · required

Name for the new world

options · WorldCreationOptions · required

World generation options

backgroundGeneration · bool · default: "true"

Whether to generate spawn area in background

return · bool

True if generation started successfully

// Example: Generate a new world
use pocketmine\world\WorldCreationOptions;
use pocketmine\world\generator\GeneratorManager;

$options = WorldCreationOptions::create()
    ->setGeneratorClass(GeneratorManager::getInstance()->getGenerator("flat")?->getGeneratorClass())
    ->setSeed(12345);

if($worldManager->generateWorld("my_flat_world", $options)){
    $server->getLogger()->info("World generation started!");
}

---

isWorldGenerated

public function isWorldGenerated(string $name) : bool

Checks if a world exists on disk.

name · string · required

Folder name of the world

---

findEntity

public function findEntity(int $entityId) : ?Entity

Searches all worlds for an entity with the specified ID.

entityId · int · required

The entity runtime ID

return · Entity|null

The entity, or null if not found in any world

---

Auto-Save Configuration

getAutoSave

public function getAutoSave() : bool

Returns whether auto-save is enabled.

---

setAutoSave

public function setAutoSave(bool $value) : void

Enables or disables auto-save for all worlds.

value · bool · required

Whether to enable auto-save

---

getAutoSaveInterval

public function getAutoSaveInterval() : int

Returns the auto-save interval in ticks.

---

setAutoSaveInterval

public function setAutoSaveInterval(int $autoSaveTicks) : void

Sets the auto-save interval.

autoSaveTicks · int · required

Interval in ticks between auto-saves

---

Static Utility Methods

World::chunkHash

public static function chunkHash(int $x, int $z) : int

Computes a hash for chunk coordinates.

x · int · required

Chunk X coordinate

z · int · required

Chunk Z coordinate

return · int

Hash value for the chunk coordinates

---

World::blockHash

public static function blockHash(int $x, int $y, int $z) : int

Computes a hash for block coordinates.

x · int · required

Block X coordinate

y · int · required

Block Y coordinate

z · int · required

Block Z coordinate

return · int

Hash value for the block coordinates

---

Common Usage Patterns

Teleporting Between Worlds

use pocketmine\event\player\PlayerJoinEvent;

public function onJoin(PlayerJoinEvent $event) : void{
    $player = $event->getPlayer();
    $worldManager = $this->getServer()->getWorldManager();
    
    $lobbyWorld = $worldManager->getWorldByName("lobby");
    if($lobbyWorld !== null){
        $player->teleport($lobbyWorld->getSafeSpawn());
    }
}

Modifying Blocks in a Region

use pocketmine\block\VanillaBlocks;

public function fillRegion(World $world, Vector3 $pos1, Vector3 $pos2, Block $block) : void{
    for($x = min($pos1->x, $pos2->x); $x <= max($pos1->x, $pos2->x); $x++){
        for($y = min($pos1->y, $pos2->y); $y <= max($pos1->y, $pos2->y); $y++){
            for($z = min($pos1->z, $pos2->z); $z <= max($pos1->z, $pos2->z); $z++){
                $world->setBlock(new Vector3($x, $y, $z), $block);
            }
        }
    }
}

// Usage
$this->fillRegion(
    $world, 
    new Vector3(0, 64, 0), 
    new Vector3(10, 74, 10), 
    VanillaBlocks::STONE()
);

Working with Explosions

use pocketmine\world\Explosion;

public function createExplosion(World $world, Vector3 $center, float $size) : void{
    $explosion = new Explosion($center, $size);
    $explosion->explodeA();
    $explosion->explodeB();
}