How nicholass003/axiom works
Purpose and Entry Point
Axiom is a PHP library for decoding/encoding and translating Minecraft Bedrock Edition packets across protocol versions. Consumers enter through src/Axiom.php, calling Axiom::for($protocol) to obtain a version-aware codec builder. It is a Composer-installed library, not a standalone server or application.
Protocol Selection and Inheritance
Protocol definitions select the available codecs and preserve compatibility through version layering. src/Version/Protocol/ProtocolInterface.php defines the protocol contract; concrete protocol maps live in files such as src/Version/Protocol/Protocol844.php, src/Version/Protocol/Protocol898.php, and src/Version/Protocol/Protocol1001.php. src/Version/ProtocolVersion.php represents supported protocol identifiers. New versions primarily add or override changed codecs rather than duplicating all packet handling.
Codec Dispatch Layer
src/Codec/CodecBuilder.php is the central lookup boundary between a packet ID and its version-specific codec. src/Codec/Codec.php defines the codec abstraction, while src/Codec/CodecType.php carries encode/decode context. The caller resolves a codec by packet ID, then invokes it with a binary reader/writer supplied by the host runtime.
Packet Model Boundary
Packet classes are version-neutral semantic models: each represents a Bedrock protocol message and its fields, independent of its wire layout. Core examples are src/Packet/Packet.php, src/Packet/PacketIds.php, and concrete packets such as src/Packet/StartGamePacket.php. This separates application-facing packet objects from protocol-specific binary serialization.
Version-Specific Wire Codecs
Per-version codecs implement each packet’s exact binary layout. The broad baseline is src/Codec/v844/; later versions contain only additions and layout overrides, e.g. src/Codec/v898/StartGameCodec.php, src/Codec/v944/UpdateBlockCodec.php, and src/Codec/v1001/StartGameCodec.php. Control flow is packet ID → builder lookup → selected version codec → packet object or encoded bytes.
Shared Serialization System
Reusable serializers handle compound protocol structures used by many packet codecs. src/Codec/Common/Serializer/NetworkNbtSerializer.php, src/Codec/Common/Serializer/InventorySerializer.php, and src/Codec/Common/Serializer/LevelSettingsSerializer.php encapsulate shared binary subformats. Version-specific serializer overrides, such as src/Codec/v944/Serializer/LevelSettingsSerializer.php, isolate wire-format changes without rewriting packet codecs.
Typed Domain Data and Compatibility Support
Nested packet payloads are strongly typed data objects and enums, rather than raw arrays: src/Data/Type/ItemStack.php, src/Data/Type/PlayerAuthInputData.php, and src/Enum/ItemStackRequestActionType.php. Codec cloning/forking support enables derived versions to override mutable codec/serializer dependencies safely: src/Codec/Support/Forkable.php and src/Codec/Support/Forker.php.
Runtime and External Boundaries
The runtime is modern PHP distributed through Composer (composer.json) and intended to be virion-compatible with PocketMine-MP. Axiom does not own sockets, sessions, persistence, or external cloud services; the integrating Minecraft server/proxy supplies transport buffers, routes packets, and applies decoded models. Its external interoperability boundary is the Minecraft Bedrock binary protocol.
Main entry points: Codec.php Codec Contract · Protocol844.php Layered Protocol Maps · CodecBuilder.php Codec Builder · Axiom.php Axiom
Components 18
Public API
- Axiom · Creates a codec builder for a requested protocol.
src/Axiom.php
Protocol Versions
Version maps layer overrides over baseline codecs.
- Protocol Version · Supported protocol identifiers.
src/Version/ProtocolVersion.php - Protocol Contract · Defines a version's codec map contract.
src/Version/Protocol/ProtocolInterface.php - Layered Protocol Maps · Baseline maps are inherited and changed codecs overridden by later versions.
src/Version/Protocol/Protocol844.php
Codec System
- Codec Builder · Resolves packet IDs to version-specific codecs.
src/Codec/CodecBuilder.php - Codec Contract · Defines packet binary encode and decode operations.
src/Codec/Codec.php - Codec Context · Carries encode/decode context.
src/Codec/CodecType.php - v844 Codec Baseline · Broad base implementation of Bedrock packet layouts.
- Version Codec Overrides · Later protocols add or replace changed layouts.
src/Codec/v898/StartGameCodec.php
Packet Model
- Packet Models · Version-neutral application-facing Bedrock messages.
src/Packet/Packet.php - Packet IDs · Maps Bedrock message identities for codec dispatch.
src/Packet/PacketIds.php - Start Game Packet
src/Packet/StartGamePacket.php - Typed Payload Data · Nested packet payloads and enums.
src/Data/Type/ItemStack.php
Shared Serialization
- Shared Serializers · Reusable serializers for NBT, inventory, and level settings.
src/Codec/Common/Serializer/NetworkNbtSerializer.php - Serializer Overrides · Isolates subformat changes for derived versions.
src/Codec/v944/Serializer/LevelSettingsSerializer.php - Codec Forking · Safely clones mutable codec and serializer dependencies.
src/Codec/Support/Forker.php
Other components
- Server / Proxy Host · Supplies transport buffers and consumes packet models.
- Bedrock Binary Protocol · Binary interoperability boundary.
Connections 21
- Server / Proxy Host → Axiom: selects protocol
- Axiom → Protocol Version: accepts
- Axiom → Codec Builder: returns
- Protocol Version → Layered Protocol Maps: selects
- Protocol Contract → Layered Protocol Maps: implemented by
- Layered Protocol Maps → v844 Codec Baseline: maps IDs to
- Layered Protocol Maps → Version Codec Overrides: overrides with
- Layered Protocol Maps → Codec Forking: forks dependencies
- Codec Builder → Packet IDs: looks up by
- Codec Builder → Codec Contract: resolves
- v844 Codec Baseline → Codec Contract: implements
- Version Codec Overrides → Codec Contract: implements
- v844 Codec Baseline → Shared Serializers: uses
- Version Codec Overrides → Serializer Overrides: uses
- Serializer Overrides → Shared Serializers: replaces parts of
- Codec Contract → Codec Context: uses
- Codec Contract → Packet Models: decodes / encodes
- Packet Models → Start Game Packet: includes
- Packet Models → Typed Payload Data: contains
- Server / Proxy Host → Codec Builder: invokes with buffers
- Codec Contract → Bedrock Binary Protocol: reads / writes