How pmmp/pocketmine-mp works
1. Purpose and principal workflow
PocketMine-MP is a PHP server for Minecraft: Bedrock Edition, designed for customizable multiplayer worlds and plugin-driven gameplay rather than vanilla survival parity. A server operator / PHP process launcher initiates operation through the bootstrap; Minecraft Bedrock clients then connect for session-based play against worlds, entities, blocks, inventories, and plugin extensions. Separately, a server-list query client can issue UT3 Query Protocol UDP requests and receive server status directly from the query handler.
2. Components
Runtime, extension, and control plane
• Server Operator / PHP Process Launcher — null repository path: External actor that starts the server executable.
• PocketMine Bootstrap — src/PocketMine.php: Root application entry-point module, by repository placement and project structure; its detailed startup code was not sampled.
• Server Runtime Coordinator — src/Server.php: Central server application object, including query information consumed by the query responder.
• Plugin Lifecycle Manager — src/plugin/PluginManager.php: Discovers plugin files, resolves load triage/dependencies, constructs plugin instances, enables/disables them, and reflects enabled-plugin listener methods for event registration.
• Event Dispatcher — src/event/HandlerListManager.php: Lazily creates per-event handler lists and inheritance-aware listener caches, and removes registered listeners during cleanup.
• Task Scheduler — src/scheduler: Dedicated subsystem for scheduled server and plugin work; its dispatch wiring was not sampled.
• Cyclic GC Controller — src/GarbageCollectorManager.php: Disables PHP’s automatic cyclic GC and performs threshold-adjusted collections at server-controlled times while recording timing totals.
• Thread Registry — src/thread/ThreadManager.php: Globally tracks worker/thread objects and coordinates their shutdown.
Network ingress and client-facing assets
• Raw Packet Transport — src/network: Network abstraction area containing the advanced/raw interfaces used to send non-MCPE packets.
• Bedrock Session Protocol — src/network/mcpe: Minecraft Bedrock protocol, authentication, compression, encryption, conversion, handler, and serializer subsystem.
• Network Session Registry — src/network/NetworkSessionManager.php: Tracks all sessions and pending-login sessions, ticks connected sessions, removes disconnected ones, and disconnects all sessions at shutdown.
• Server-list Query Responder — src/network/query/QueryHandler.php: Parses UT3 Query handshakes/statistics packets, rotates address-derived challenge tokens, reads short query data, and emits raw replies.
• Server-list Query Client — null repository path: External UDP requester of handshake and statistics responses.
• Resource-pack Catalog — src/resourcepacks/ResourcePackManager.php: Creates/validates the pack directory, loads configured ZIP/MCPACK assets, indexes packs by UUID, applies force-resource policy, and reads optional 32-byte encryption keys.
• Resource-pack Files and Configuration — null repository path: External filesystem state containing resource_packs.yml, pack archives, and optional key files.
Game simulation and persistent world model
• World/Chunk Access Contract — src/world/ChunkManager.php: Defines the world-facing API to read/write blocks, access chunks, expose build-height limits, and validate coordinate bounds.
• World Persistence Formats — src/world/format/io: Multi-file world serialization/storage layer, including LevelDB and region-oriented format support.
• World Generation and Lighting — src/world/generator: Generator, biome, noise, population, and execution facilities; lighting has a distinct sibling subsystem under the world package.
• Block State and Behaviour Model — src/block: Concrete block classes, type/state registries, placement/interaction behaviour, inventories, and common block traits.
• Block Tile State — src/block/tile: Persistent per-block objects for containers, signs, furnaces, spawners, lecterns, and similar stateful blocks.
• Entity and Player Model — src/entity: Base entity hierarchy, player/human state, attributes, effects, animations, projectiles, and factories.
• Player Experience Controller — src/entity/ExperienceManager.php: Maintains total XP plus level/progress attributes, applies cancellable experience changes, limits integer totals, and triggers collection/level-up sounds.
• Inventory and Item Domain — src/inventory: Inventory state, transaction processing, actions, and validators; item types are maintained in the sibling item subsystem.
• Recipe and Furnace Registry — src/crafting/CraftingManager.php: Stores shaped, shapeless, furnace, potion, brewing, and container-change recipes, initializes a manager per furnace type, and hashes item/NBT outputs for recipe lookup.
• Bedrock Saved-data Conversion — src/data/bedrock: Serializes/deserializes and upgrades Bedrock block/item data, including legacy-ID mappings and block-state conversion schemas.
Gameplay administration
• Command Framework and Built-ins — src/command: Command abstractions, maps, senders, aliases, plugin commands, and default moderation/gameplay/server commands.
• Permission Registry — src/permission/PermissionManager.php: Singleton registry of permission definitions and permissible subscriptions, with legacy permission-broadcast subscription support.
3. Relationships
• Server Operator / PHP Process Launcher -> PocketMine Bootstrap: launches the server process; documented server product and designated root entry module, though bootstrap calls were not sampled.
• PocketMine Bootstrap -> Server Runtime Coordinator: initializes/owns server execution; runtime wiring is not present in the supplied excerpts.
• Minecraft Bedrock Client -> Bedrock Session Protocol: exchanges Bedrock multiplayer traffic; supported by the documented product purpose and dedicated MCPE subsystem, while packet ingress call sites were not sampled.
• Network Session Registry -> Bedrock Session Protocol: ticks sessions and invokes session disconnects; tick() and close() directly call methods on NetworkSession objects.
• Server-list Query Client -> Server-list Query Responder: sends UT3 Query handshake/statistics datagrams; the handler matches, parses, and switches on those packet types.
• Server-list Query Responder -> Server Runtime Coordinator: reads short server query information for statistics responses.
• Server-list Query Responder -> Raw Packet Transport: sends handshake tokens and statistics replies through sendRawPacket().
• Resource-pack Catalog -> Resource-pack Files and Configuration: reads YAML configuration, pack archives, and optional encryption-key files.
• Plugin packages/directories -> Plugin Lifecycle Manager: supplies candidate plugin files for loader triage, dependency analysis, and instantiation.
• Plugin Lifecycle Manager -> Server Runtime Coordinator: uses server API-version, logger, and language facilities while loading and managing plugins.
• Plugin Lifecycle Manager -> Event Dispatcher: emits plugin enable/disable events and registers reflected listener methods for enabled plugins.
• Player Experience Controller -> Event Dispatcher: calls a cancellable player-experience-change event before mutating level/progress attributes.
• Player Experience Controller -> Entity and Player Model: updates entity attributes and broadcasts XP collection or level-up sounds through its owning entity.
• Recipe and Furnace Registry -> Inventory and Item Domain: derives stable recipe-output hashes from item state IDs and named NBT.
• World/Chunk Access Contract -> Block State and Behaviour Model: uses Block values as the read result and write input for world coordinates.
• Thread Registry -> Managed worker/thread objects: adds, removes, enumerates, and requests termination of registered runtime threads.
• Cyclic GC Controller -> PHP runtime: invokes gc_collect_cycles() only after its managed root threshold is reached.
4. Coverage limits
No excerpts were supplied for bootstrap/server construction, Bedrock packet dispatch, world ticking, world persistence call sites, scheduler execution, command execution, or plugin-to-world interactions. Directory-level components describe established subsystem boundaries, but their exact runtime ordering and ownership should not be treated as confirmed beyond the relationships above.
Main entry points: PluginManager.php Plugin Lifecycle Manager · QueryHandler.php Server-list Query Responder · Server.php Server Runtime Coordinator · ExperienceManager.php Player Experience Controller
Components 31
Runtime and Control Plane
- Server Operator
- PocketMine Bootstrap
src/PocketMine.php - Server Runtime Coordinator
src/Server.php - Plugin Lifecycle Manager
src/plugin/PluginManager.php - Event Dispatcher
src/event/HandlerListManager.php - Task Scheduler
src/scheduler - Cyclic GC Controller
src/GarbageCollectorManager.php - Thread Registry
src/thread/ThreadManager.php - Managed Worker Threads
- PHP Runtime
- Plugin Packages and Directories
Network and Assets
- Minecraft Bedrock Client
- Raw Packet Transport
src/network - Bedrock Session Protocol
src/network/mcpe - Network Session Registry
src/network/NetworkSessionManager.php - Server-list Query Client
- Server-list Query Responder
src/network/query/QueryHandler.php - Resource-pack Catalog
src/resourcepacks/ResourcePackManager.php - Resource-pack Files and Configuration
Game Simulation and World
- World/Chunk Access Contract
src/world/ChunkManager.php - World Persistence Formats
src/world/format/io - World Generation and Lighting
src/world/generator - Block State and Behaviour Model
src/block - Block Tile State
src/block/tile - Entity and Player Model
src/entity - Player Experience Controller
src/entity/ExperienceManager.php - Inventory and Item Domain
src/inventory - Recipe and Furnace Registry
src/crafting/CraftingManager.php - Bedrock Saved-data Conversion
src/data/bedrock
Gameplay Administration
- Command Framework and Built-ins
src/command - Permission Registry
src/permission/PermissionManager.php
Connections 17
- Server Operator → PocketMine Bootstrap: launches · Starts the server process.
- PocketMine Bootstrap → Server Runtime Coordinator: initializes · Runtime wiring was not sampled.
- Minecraft Bedrock Client → Bedrock Session Protocol: exchanges traffic · Packet ingress call sites were not sampled.
- Network Session Registry → Bedrock Session Protocol: ticks and disconnects
- Server-list Query Client → Server-list Query Responder: sends UDP queries
- Server-list Query Responder → Server Runtime Coordinator: reads query info
- Server-list Query Responder → Raw Packet Transport: sends replies
- Resource-pack Catalog → Resource-pack Files and Configuration: reads assets
- Plugin Packages and Directories → Plugin Lifecycle Manager: supplies plugins
- Plugin Lifecycle Manager → Server Runtime Coordinator: uses server APIs
- Plugin Lifecycle Manager → Event Dispatcher: registers listeners · Also emits plugin enable/disable events.
- Player Experience Controller → Event Dispatcher: dispatches change event
- Player Experience Controller → Entity and Player Model: updates attributes
- Recipe and Furnace Registry → Inventory and Item Domain: hashes item outputs
- World/Chunk Access Contract → Block State and Behaviour Model: reads and writes blocks
- Thread Registry → Managed Worker Threads: manages threads
- Cyclic GC Controller → PHP Runtime: collects cycles · Calls gc_collect_cycles() after its managed threshold is reached.