# nicholass003/littlebrother architecture

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

- Interactive diagram: https://gitdiagram.com/nicholass003/littlebrother
- Repository: https://github.com/nicholass003/littlebrother

## Overview

#### Purpose and Runtime

LittleBrother is a PHP PocketMine-MP plugin that lets older Minecraft Bedrock clients connect to a server using the current PocketMine protocol. It is a bidirectional, in-process packet compatibility layer rather than a proxy or web service. The plugin targets PocketMine-MP API 5.43.0 and is packaged/loaded through `plugin.yml`.

#### Entry Points and Lifecycle

- `src/plugin.php` is the plugin bootstrap and likely owns service initialization.
- `src/listener.php` is the PocketMine event/network integration boundary.
- `src/command/protocol.php` exposes protocol-related operational functionality.
- `resources/config.yml` supplies deployment-time behavior.

The plugin must attach translation behavior to client connections early enough to alter protocol handling, then preserve normal PocketMine server semantics after inbound conversion.

#### Protocol Session Boundary

`src/protocol/storage.php` and `src/protocol/version.php` model connection-specific protocol/version state. `src/protocol/sender.php` is the outbound emission boundary, while `src/protocol/encryption/inter.php` isolates encryption-related interoperability.

Control flow is version-aware: determine a connecting client’s legacy Bedrock protocol, retain that context per session, decode/translate its packets toward PocketMine’s current protocol, and translate server responses back before serialization to that client.

#### Translation Engine

The central translation layer is organized around:

- `src/protocol/translator/translator.php`
- `src/protocol/translator/runtime.php`
- `src/protocol/translator/batch.php`

Runtime translation provides dynamic protocol-aware serialization/deserialization for compatible packet shapes. Batch handling is architecturally important because Bedrock transports packets in grouped payloads. This layer is the boundary between wire-format/version differences and PocketMine’s native packet model.

#### Manual Runtime Packet Adaptation

Packets with semantic or structural differences use targeted runtime translators in `src/protocol/translator/runtime/`. Core examples include:

- World/chunk and block updates: `level_chunk.php`, `update_block.php`, `update_sub_chunk_blocks.php`
- Entity spawning and equipment: `add_actor.php`, `add_player.php`, `mob_equipment.php`
- Inventory and player actions: `inventory_content.php`, `inventory_transaction.php`, `item_stack_wrapper.php`

These handlers supplement generic runtime codecs and are the primary extension points when a newly supported version causes desync or unsupported gameplay behavior.

#### Block, Item, and Runtime-ID Conversion

Protocol packet translation depends on data-model conversion:

- `src/convert/manager.php` coordinates conversion services.
- `src/convert/block/mapper.php` and `src/convert/block/chunk.php` remap block states, including chunk payloads.
- `src/convert/item/mapper.php`, `src/convert/item/dictionary.php`, and `src/convert/item/translator.php` map item identities and representations.

Runtime ID conversion is also explicitly handled by `src/protocol/translator/runtime/runtime_id.php`. This is a critical correctness boundary: old-client numeric IDs and state encodings must be converted without changing the server’s canonical world/item model.

#### Versioned Data and External Dependencies

Version-specific Bedrock schemas are packaged under `resources/data/bedrock/`, for example `resources/data/bedrock/844/canonical_block_states.nbt`, `resources/data/bedrock/844/required_item_list.json`, and `resources/data/bedrock/1001/block_state_meta_map.json`. Shared sound mapping is in `resources/data/bedrock/level_sound_id_map.json`.

Development-time generation scripts, especially `tools/generate-protocol-data.php`, retrieve protocol data from `pmmp/BedrockData` on GitHub. At runtime, the material external platform dependency is PocketMine-MP; clients are Minecraft Bedrock clients across supported legacy protocol versions.

Main entry points: [`src/protocol/translator/translator.php`](https://github.com/nicholass003/littlebrother/blob/stable/src/protocol/translator/translator.php) (Protocol Translator), [`src/listener.php`](https://github.com/nicholass003/littlebrother/blob/stable/src/listener.php) (Network Listener), [`src/protocol/translator/runtime.php`](https://github.com/nicholass003/littlebrother/blob/stable/src/protocol/translator/runtime.php) (Runtime Codec), [`src/convert/manager.php`](https://github.com/nicholass003/littlebrother/blob/stable/src/convert/manager.php) (Conversion Manager)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_integration["Plugin Integration"]
  node_plugin["Plugin Bootstrap<br/>plugin lifecycle<br/>[plugin.php]"]
  node_listener["Network Listener<br/>PocketMine boundary<br/>[listener.php]"]
  node_command["Protocol Command<br/>operations command<br/>[protocol.php]"]
  node_config["Plugin Config<br/>deployment config<br/>[config.yml]"]
end

subgraph group_session["Session Protocol"]
  node_version["Protocol Version<br/>version model<br/>[version.php]"]
  node_storage[("Session Storage<br/>connection state<br/>[storage.php]")]
  node_sender["Outbound Sender<br/>packet emission<br/>[sender.php]"]
  node_encryption["Encryption Interop<br/>encryption adapter<br/>[inter.php]"]
end

subgraph group_translation["Translation Engine"]
  node_translator["Protocol Translator<br/>translation coordinator<br/>[translator.php]"]
  node_runtime["Runtime Codec<br/>dynamic packet codec<br/>[runtime.php]"]
  node_batch["Batch Translator<br/>transport batch codec<br/>[batch.php]"]
  node_packet_adapters["Runtime Packet Adapters<br/>semantic packet translators"]
  node_runtime_ids["Runtime ID Conversion<br/>numeric ID translator<br/>[runtime_id.php]"]
end

subgraph group_conversion["Data Conversion"]
  node_convert_manager["Conversion Manager<br/>conversion coordinator<br/>[manager.php]"]
  node_block_conversion["Block and Chunk Mapping<br/>block-state converter<br/>[mapper.php]"]
  node_item_conversion["Item Mapping<br/>item converter<br/>[translator.php]"]
end

subgraph group_data["Versioned Data"]
  node_bedrock_data["Bedrock Schema Data<br/>versioned protocol data"]
  node_generator["Protocol Data Generator<br/>development generator"]
end

node_clients(("Legacy Bedrock Clients<br/>external clients"))
node_pocketmine{{"PocketMine-MP<br/>server platform"}}

node_clients -->|"connects and sends legacy packets"| node_listener
node_pocketmine -->|"loads"| node_plugin
node_plugin -->|"initializes"| node_listener
node_config -.->|"configures"| node_plugin
node_command -->|"operates"| node_plugin
node_listener -->|"detects client protocol"| node_version
node_version -->|"stores per session"| node_storage
node_listener -->|"routes inbound and outbound packets"| node_translator
node_storage -->|"supplies session context"| node_translator
node_translator -->|"decodes and encodes batches"| node_batch
node_batch -->|"translates packet payloads"| node_runtime
node_runtime -->|"delegates structural differences"| node_packet_adapters
node_translator -->|"converts runtime IDs"| node_runtime_ids
node_translator -->|"converts game data"| node_convert_manager
node_convert_manager -->|"coordinates"| node_block_conversion
node_convert_manager -->|"coordinates"| node_item_conversion
node_bedrock_data -.->|"provides version mappings"| node_convert_manager
node_bedrock_data -.->|"provides protocol schemas"| node_runtime
node_runtime -->|"emits native packet model"| node_pocketmine
node_pocketmine -->|"provides server responses"| node_translator
node_translator -->|"produces legacy outbound packets"| node_sender
node_sender -->|"applies interoperability handling"| node_encryption
node_encryption -->|"serializes legacy responses"| node_clients
node_generator -.->|"generates packaged data"| node_bedrock_data

click node_plugin "https://github.com/nicholass003/littlebrother/blob/stable/src/plugin.php"
click node_listener "https://github.com/nicholass003/littlebrother/blob/stable/src/listener.php"
click node_command "https://github.com/nicholass003/littlebrother/blob/stable/src/command/protocol.php"
click node_config "https://github.com/nicholass003/littlebrother/blob/stable/resources/config.yml"
click node_version "https://github.com/nicholass003/littlebrother/blob/stable/src/protocol/version.php"
click node_storage "https://github.com/nicholass003/littlebrother/blob/stable/src/protocol/storage.php"
click node_sender "https://github.com/nicholass003/littlebrother/blob/stable/src/protocol/sender.php"
click node_encryption "https://github.com/nicholass003/littlebrother/blob/stable/src/protocol/encryption/inter.php"
click node_translator "https://github.com/nicholass003/littlebrother/blob/stable/src/protocol/translator/translator.php"
click node_runtime "https://github.com/nicholass003/littlebrother/blob/stable/src/protocol/translator/runtime.php"
click node_batch "https://github.com/nicholass003/littlebrother/blob/stable/src/protocol/translator/batch.php"
click node_runtime_ids "https://github.com/nicholass003/littlebrother/blob/stable/src/protocol/translator/runtime/runtime_id.php"
click node_convert_manager "https://github.com/nicholass003/littlebrother/blob/stable/src/convert/manager.php"
click node_block_conversion "https://github.com/nicholass003/littlebrother/blob/stable/src/convert/block/mapper.php"
click node_item_conversion "https://github.com/nicholass003/littlebrother/blob/stable/src/convert/item/translator.php"
click node_generator "https://github.com/nicholass003/littlebrother/blob/stable/tools/generate-protocol-data.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_plugin,node_listener,node_command,node_config toneBlue
class node_version,node_storage,node_sender,node_encryption toneAmber
class node_translator,node_runtime,node_batch,node_packet_adapters,node_runtime_ids toneMint
class node_convert_manager,node_block_conversion,node_item_conversion toneRose
class node_bedrock_data,node_generator toneIndigo
class node_clients,node_pocketmine toneNeutral
```

## Components

### Plugin Integration

- [Plugin Bootstrap](https://github.com/nicholass003/littlebrother/blob/stable/src/plugin.php): plugin lifecycle · `src/plugin.php`
- [Network Listener](https://github.com/nicholass003/littlebrother/blob/stable/src/listener.php): PocketMine boundary · Attaches compatibility behavior to connections. · `src/listener.php`
- [Protocol Command](https://github.com/nicholass003/littlebrother/blob/stable/src/command/protocol.php): operations command · `src/command/protocol.php`
- [Plugin Config](https://github.com/nicholass003/littlebrother/blob/stable/resources/config.yml): deployment config · `resources/config.yml`

### Session Protocol

- [Protocol Version](https://github.com/nicholass003/littlebrother/blob/stable/src/protocol/version.php): version model · `src/protocol/version.php`
- [Session Storage](https://github.com/nicholass003/littlebrother/blob/stable/src/protocol/storage.php): connection state · Retains legacy protocol context per connection. · `src/protocol/storage.php`
- [Outbound Sender](https://github.com/nicholass003/littlebrother/blob/stable/src/protocol/sender.php): packet emission · `src/protocol/sender.php`
- [Encryption Interop](https://github.com/nicholass003/littlebrother/blob/stable/src/protocol/encryption/inter.php): encryption adapter · `src/protocol/encryption/inter.php`

### Translation Engine

- [Protocol Translator](https://github.com/nicholass003/littlebrother/blob/stable/src/protocol/translator/translator.php): translation coordinator · Converts between legacy wire packets and PocketMine packet models. · `src/protocol/translator/translator.php`
- [Runtime Codec](https://github.com/nicholass003/littlebrother/blob/stable/src/protocol/translator/runtime.php): dynamic packet codec · `src/protocol/translator/runtime.php`
- [Batch Translator](https://github.com/nicholass003/littlebrother/blob/stable/src/protocol/translator/batch.php): transport batch codec · Handles grouped Bedrock packet payloads. · `src/protocol/translator/batch.php`
- **Runtime Packet Adapters**: semantic packet translators · Adapts chunks, entities, inventory, and player actions with structural differences.
- [Runtime ID Conversion](https://github.com/nicholass003/littlebrother/blob/stable/src/protocol/translator/runtime/runtime_id.php): numeric ID translator · `src/protocol/translator/runtime/runtime_id.php`

### Data Conversion

- [Conversion Manager](https://github.com/nicholass003/littlebrother/blob/stable/src/convert/manager.php): conversion coordinator · `src/convert/manager.php`
- [Block and Chunk Mapping](https://github.com/nicholass003/littlebrother/blob/stable/src/convert/block/mapper.php): block-state converter · `src/convert/block/mapper.php`
- [Item Mapping](https://github.com/nicholass003/littlebrother/blob/stable/src/convert/item/translator.php): item converter · `src/convert/item/translator.php`

### Versioned Data

- **Bedrock Schema Data**: versioned protocol data · Canonical block states, item lists, metadata, and sound mappings.
- [Protocol Data Generator](https://github.com/nicholass003/littlebrother/blob/stable/tools/generate-protocol-data.php): development generator · Retrieves protocol data from pmmp/BedrockData. · `tools/generate-protocol-data.php`

### Other components

- **Legacy Bedrock Clients**: external clients
- **PocketMine-MP**: server platform · Provides the current native protocol and server semantics.

## Connections

- Legacy Bedrock Clients → Network Listener: connects and sends legacy packets
- PocketMine-MP → Plugin Bootstrap: loads
- Plugin Bootstrap → Network Listener: initializes
- Plugin Config → Plugin Bootstrap: configures
- Protocol Command → Plugin Bootstrap: operates
- Network Listener → Protocol Version: detects client protocol
- Protocol Version → Session Storage: stores per session
- Network Listener → Protocol Translator: routes inbound and outbound packets
- Session Storage → Protocol Translator: supplies session context
- Protocol Translator → Batch Translator: decodes and encodes batches
- Batch Translator → Runtime Codec: translates packet payloads
- Runtime Codec → Runtime Packet Adapters: delegates structural differences
- Protocol Translator → Runtime ID Conversion: converts runtime IDs
- Protocol Translator → Conversion Manager: converts game data
- Conversion Manager → Block and Chunk Mapping: coordinates
- Conversion Manager → Item Mapping: coordinates
- Bedrock Schema Data → Conversion Manager: provides version mappings
- Bedrock Schema Data → Runtime Codec: provides protocol schemas
- Runtime Codec → PocketMine-MP: emits native packet model
- PocketMine-MP → Protocol Translator: provides server responses
- Protocol Translator → Outbound Sender: produces legacy outbound packets
- Outbound Sender → Encryption Interop: applies interoperability handling
- Encryption Interop → Legacy Bedrock Clients: serializes legacy responses
- Protocol Data Generator → Bedrock Schema Data: generates packaged data