# pmmp/pocketmine-mp architecture

> Architecture diagram of the GitHub repository pmmp/pocketmine-mp, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-18). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/pmmp/pocketmine-mp
- Repository: https://github.com/pmmp/pocketmine-mp

## Overview

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: [`src/plugin/PluginManager.php`](https://github.com/pmmp/pocketmine-mp/blob/stable/src/plugin/PluginManager.php) (Plugin Lifecycle Manager), [`src/network/query/QueryHandler.php`](https://github.com/pmmp/pocketmine-mp/blob/stable/src/network/query/QueryHandler.php) (Server-list Query Responder), [`src/Server.php`](https://github.com/pmmp/pocketmine-mp/blob/stable/src/Server.php) (Server Runtime Coordinator), [`src/entity/ExperienceManager.php`](https://github.com/pmmp/pocketmine-mp/blob/stable/src/entity/ExperienceManager.php) (Player Experience Controller)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime and Control Plane"]
  node_operator(("Server Operator<br/>external actor"))
  node_bootstrap["PocketMine Bootstrap<br/>entry point"]
  node_server["Server Runtime Coordinator<br/>application coordinator"]
  node_plugin_manager["Plugin Lifecycle Manager<br/>extension manager"]
  node_event_dispatcher["Event Dispatcher<br/>event system"]
  node_scheduler["Task Scheduler"]
  node_gc_controller["Cyclic GC Controller<br/>runtime controller"]
  node_thread_registry["Thread Registry<br/>thread manager"]
  node_worker_threads(("Managed Worker Threads<br/>runtime objects"))
  node_php_runtime(("PHP Runtime<br/>external runtime"))
  node_plugin_packages["Plugin Packages and Directories<br/>external plugin files"]
end

subgraph group_network["Network and Assets"]
  node_bedrock_client(("Minecraft Bedrock Client<br/>external client"))
  node_raw_transport["Raw Packet Transport<br/>network transport"]
  node_bedrock_protocol["Bedrock Session Protocol<br/>protocol subsystem"]
  node_session_registry["Network Session Registry<br/>session manager"]
  node_query_client(("Server-list Query Client<br/>external UDP client"))
  node_query_responder["Server-list Query Responder<br/>query handler"]
  node_resource_catalog["Resource-pack Catalog<br/>asset manager"]
  node_resource_files["Resource-pack Files and Configuration<br/>external filesystem"]
end

subgraph group_simulation["Game Simulation and World"]
  node_chunk_contract["World/Chunk Access Contract<br/>world API"]
  node_world_persistence[("World Persistence Formats<br/>world storage")]
  node_world_generation["World Generation and Lighting"]
  node_block_model["Block State and Behaviour Model<br/>block domain"]
  node_block_tile["Block Tile State<br/>persistent block state"]
  node_entity_model["Entity and Player Model<br/>entity domain"]
  node_experience["Player Experience Controller<br/>player service"]
  node_inventory["Inventory and Item Domain"]
  node_crafting["Recipe and Furnace Registry<br/>recipe registry"]
  node_bedrock_data["Bedrock Saved-data Conversion"]
end

subgraph group_admin["Gameplay Administration"]
  node_commands["Command Framework and Built-ins<br/>command system"]
  node_permissions["Permission Registry<br/>permission system"]
end

node_operator -->|"launches"| node_bootstrap
node_bootstrap -->|"initializes"| node_server
node_bedrock_client -->|"exchanges traffic"| node_bedrock_protocol
node_session_registry -->|"ticks and disconnects"| node_bedrock_protocol
node_query_client -->|"sends UDP queries"| node_query_responder
node_query_responder -->|"reads query info"| node_server
node_query_responder -->|"sends replies"| node_raw_transport
node_resource_catalog -->|"reads assets"| node_resource_files
node_plugin_packages -->|"supplies plugins"| node_plugin_manager
node_plugin_manager -->|"uses server APIs"| node_server
node_plugin_manager -->|"registers listeners"| node_event_dispatcher
node_experience -->|"dispatches change event"| node_event_dispatcher
node_experience -->|"updates attributes"| node_entity_model
node_crafting -->|"hashes item outputs"| node_inventory
node_chunk_contract -->|"reads and writes blocks"| node_block_model
node_thread_registry -->|"manages threads"| node_worker_threads
node_gc_controller -->|"collects cycles"| node_php_runtime

click node_bootstrap "https://github.com/pmmp/pocketmine-mp/blob/stable/src/PocketMine.php"
click node_server "https://github.com/pmmp/pocketmine-mp/blob/stable/src/Server.php"
click node_plugin_manager "https://github.com/pmmp/pocketmine-mp/blob/stable/src/plugin/PluginManager.php"
click node_event_dispatcher "https://github.com/pmmp/pocketmine-mp/blob/stable/src/event/HandlerListManager.php"
click node_scheduler "https://github.com/pmmp/pocketmine-mp/tree/stable/src/scheduler"
click node_gc_controller "https://github.com/pmmp/pocketmine-mp/blob/stable/src/GarbageCollectorManager.php"
click node_thread_registry "https://github.com/pmmp/pocketmine-mp/blob/stable/src/thread/ThreadManager.php"
click node_raw_transport "https://github.com/pmmp/pocketmine-mp/tree/stable/src/network"
click node_bedrock_protocol "https://github.com/pmmp/pocketmine-mp/tree/stable/src/network/mcpe"
click node_session_registry "https://github.com/pmmp/pocketmine-mp/blob/stable/src/network/NetworkSessionManager.php"
click node_query_responder "https://github.com/pmmp/pocketmine-mp/blob/stable/src/network/query/QueryHandler.php"
click node_resource_catalog "https://github.com/pmmp/pocketmine-mp/blob/stable/src/resourcepacks/ResourcePackManager.php"
click node_chunk_contract "https://github.com/pmmp/pocketmine-mp/blob/stable/src/world/ChunkManager.php"
click node_world_persistence "https://github.com/pmmp/pocketmine-mp/tree/stable/src/world/format/io"
click node_world_generation "https://github.com/pmmp/pocketmine-mp/tree/stable/src/world/generator"
click node_block_model "https://github.com/pmmp/pocketmine-mp/tree/stable/src/block"
click node_block_tile "https://github.com/pmmp/pocketmine-mp/tree/stable/src/block/tile"
click node_entity_model "https://github.com/pmmp/pocketmine-mp/tree/stable/src/entity"
click node_experience "https://github.com/pmmp/pocketmine-mp/blob/stable/src/entity/ExperienceManager.php"
click node_inventory "https://github.com/pmmp/pocketmine-mp/tree/stable/src/inventory"
click node_crafting "https://github.com/pmmp/pocketmine-mp/blob/stable/src/crafting/CraftingManager.php"
click node_bedrock_data "https://github.com/pmmp/pocketmine-mp/tree/stable/src/data/bedrock"
click node_commands "https://github.com/pmmp/pocketmine-mp/tree/stable/src/command"
click node_permissions "https://github.com/pmmp/pocketmine-mp/blob/stable/src/permission/PermissionManager.php"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_operator,node_bootstrap,node_server,node_plugin_manager,node_event_dispatcher,node_scheduler,node_gc_controller,node_thread_registry,node_worker_threads,node_php_runtime,node_plugin_packages toneBlue
class node_bedrock_client,node_raw_transport,node_bedrock_protocol,node_session_registry,node_query_client,node_query_responder,node_resource_catalog,node_resource_files toneAmber
class node_chunk_contract,node_world_persistence,node_world_generation,node_block_model,node_block_tile,node_entity_model,node_experience,node_inventory,node_crafting,node_bedrock_data toneMint
class node_commands,node_permissions toneRose
```

## Components

### Runtime and Control Plane

- **Server Operator**: external actor
- [PocketMine Bootstrap](https://github.com/pmmp/pocketmine-mp/blob/stable/src/PocketMine.php): entry point · `src/PocketMine.php`
- [Server Runtime Coordinator](https://github.com/pmmp/pocketmine-mp/blob/stable/src/Server.php): application coordinator · `src/Server.php`
- [Plugin Lifecycle Manager](https://github.com/pmmp/pocketmine-mp/blob/stable/src/plugin/PluginManager.php): extension manager · `src/plugin/PluginManager.php`
- [Event Dispatcher](https://github.com/pmmp/pocketmine-mp/blob/stable/src/event/HandlerListManager.php): event system · `src/event/HandlerListManager.php`
- [Task Scheduler](https://github.com/pmmp/pocketmine-mp/tree/stable/src/scheduler): scheduler · `src/scheduler`
- [Cyclic GC Controller](https://github.com/pmmp/pocketmine-mp/blob/stable/src/GarbageCollectorManager.php): runtime controller · `src/GarbageCollectorManager.php`
- [Thread Registry](https://github.com/pmmp/pocketmine-mp/blob/stable/src/thread/ThreadManager.php): thread manager · `src/thread/ThreadManager.php`
- **Managed Worker Threads**: runtime objects
- **PHP Runtime**: external runtime
- **Plugin Packages and Directories**: external plugin files

### Network and Assets

- **Minecraft Bedrock Client**: external client
- [Raw Packet Transport](https://github.com/pmmp/pocketmine-mp/tree/stable/src/network): network transport · `src/network`
- [Bedrock Session Protocol](https://github.com/pmmp/pocketmine-mp/tree/stable/src/network/mcpe): protocol subsystem · `src/network/mcpe`
- [Network Session Registry](https://github.com/pmmp/pocketmine-mp/blob/stable/src/network/NetworkSessionManager.php): session manager · `src/network/NetworkSessionManager.php`
- **Server-list Query Client**: external UDP client
- [Server-list Query Responder](https://github.com/pmmp/pocketmine-mp/blob/stable/src/network/query/QueryHandler.php): query handler · `src/network/query/QueryHandler.php`
- [Resource-pack Catalog](https://github.com/pmmp/pocketmine-mp/blob/stable/src/resourcepacks/ResourcePackManager.php): asset manager · `src/resourcepacks/ResourcePackManager.php`
- **Resource-pack Files and Configuration**: external filesystem

### Game Simulation and World

- [World/Chunk Access Contract](https://github.com/pmmp/pocketmine-mp/blob/stable/src/world/ChunkManager.php): world API · `src/world/ChunkManager.php`
- [World Persistence Formats](https://github.com/pmmp/pocketmine-mp/tree/stable/src/world/format/io): world storage · `src/world/format/io`
- [World Generation and Lighting](https://github.com/pmmp/pocketmine-mp/tree/stable/src/world/generator): world generation · `src/world/generator`
- [Block State and Behaviour Model](https://github.com/pmmp/pocketmine-mp/tree/stable/src/block): block domain · `src/block`
- [Block Tile State](https://github.com/pmmp/pocketmine-mp/tree/stable/src/block/tile): persistent block state · `src/block/tile`
- [Entity and Player Model](https://github.com/pmmp/pocketmine-mp/tree/stable/src/entity): entity domain · `src/entity`
- [Player Experience Controller](https://github.com/pmmp/pocketmine-mp/blob/stable/src/entity/ExperienceManager.php): player service · `src/entity/ExperienceManager.php`
- [Inventory and Item Domain](https://github.com/pmmp/pocketmine-mp/tree/stable/src/inventory): item domain · `src/inventory`
- [Recipe and Furnace Registry](https://github.com/pmmp/pocketmine-mp/blob/stable/src/crafting/CraftingManager.php): recipe registry · `src/crafting/CraftingManager.php`
- [Bedrock Saved-data Conversion](https://github.com/pmmp/pocketmine-mp/tree/stable/src/data/bedrock): data conversion · `src/data/bedrock`

### Gameplay Administration

- [Command Framework and Built-ins](https://github.com/pmmp/pocketmine-mp/tree/stable/src/command): command system · `src/command`
- [Permission Registry](https://github.com/pmmp/pocketmine-mp/blob/stable/src/permission/PermissionManager.php): permission system · `src/permission/PermissionManager.php`

## Connections

- 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.
