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
Full day-night cycle duration
Peaceful difficulty level
Core Methods
getId
public function getId() : int
getFolderName
public function getFolderName() : string
getDisplayName
public function getDisplayName() : string
getServer
public function getServer() : Server
getProvider
public function getProvider() : WritableWorldProvider
Block Manipulation
getBlock
public function getBlock(Vector3 $pos, bool $cached = true, bool $addToCache = true) : Block
Whether to use cached block data
Whether to add the block to cache
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
Position to place the block
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
Entity Management
getEntity
public function getEntity(int $entityId) : ?Entity
The entity, or null if not found
getEntities
public function getEntities() : array
getNearbyEntities
public function getNearbyEntities(AxisAlignedBB $bb, ?Entity $entity = null) : array
The bounding box to search within
Entity to exclude from results
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
// Example: Broadcast message to all players in world
foreach($world->getPlayers() as $player){
$player->sendMessage("World event!");
}
Time & Weather
getTime
public function getTime() : int
setTime
public function setTime(int $time) : void
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
The loaded chunk, or null if unavailable
isChunkLoaded
public function isChunkLoaded(int $chunkX, int $chunkZ) : bool
Effects & Sounds
addSound
public function addSound(Vector3 $pos, Sound $sound, ?array $players = null) : void
Position to play the sound
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
Position to spawn the particle
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
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
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
The default world, or null if not set
setDefaultWorld
public function setDefaultWorld(?World $world) : void
World to set as default, or null to unset
getWorldByName
public function getWorldByName(string $name) : ?World
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
loadWorld
public function loadWorld(string $name, bool $autoUpgrade = false) : bool
Folder name of the world to load
Whether to automatically upgrade old world formats
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
Whether to force unload (even if it’s the default world)
True if the world was unloaded successfully
generateWorld
public function generateWorld(string $name, WorldCreationOptions $options, bool $backgroundGeneration = true) : bool
options
WorldCreationOptions
required
World generation options
Whether to generate spawn area in background
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
findEntity
public function findEntity(int $entityId) : ?Entity
The entity, or null if not found in any world
Auto-Save Configuration
getAutoSave
public function getAutoSave() : bool
setAutoSave
public function setAutoSave(bool $value) : void
Whether to enable auto-save
getAutoSaveInterval
public function getAutoSaveInterval() : int
setAutoSaveInterval
public function setAutoSaveInterval(int $autoSaveTicks) : void
Interval in ticks between auto-saves
Static Utility Methods
World::chunkHash
public static function chunkHash(int $x, int $z) : int
Hash value for the chunk coordinates
World::blockHash
public static function blockHash(int $x, int $y, int $z) : 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();
}