nicholass003/littlebrother

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.