Falcon Protocol
Minecraft: Bedrock Edition protocol library written in C++17

What is this?

The binary format of the Bedrock protocol, with no game logic attached. It is the lowest layer of Falcon and has no dependency on the server or the transport.

• Packets - one class per Bedrock packet in Protocol/Packets, each with write, read and a typed handle dispatch through NetworkPacketHandler
• Packet ids and factory - MinecraftPacketIds and MinecraftPackets create a packet from its id
• Network types - items, block definitions, inventory sources, commands, camera, attributes and more in Protocol/Types
• Codecs - items (inventory and entity formats), entity metadata, skins, inventory transactions, camera and data store
• Utilities - math types and logging

NBT tags and binary streams come from NBT, fetched automatically.

Usage

The library is a plain CMake target named FalconProtocol. The easiest way to use it is FetchContent:

include(FetchContent)

FetchContent_Declare(
    falcon_protocol
    GIT_REPOSITORY https://github.com/Falcon-MC/Protocol.git
    GIT_TAG main
    GIT_SHALLOW TRUE
)
FetchContent_MakeAvailable(falcon_protocol)

target_link_libraries(your_target PRIVATE FalconProtocol)

Building

Only CMake 3.16+ and a C++17 compiler are required.

cmake -B build -G Ninja
cmake --build build

Checking the packets

tools/check_protocol.py compares every packet's write with the official protocol documentation. It expands both into the encodings that reach the wire, field by field, and reports packet id differences, missing packets and the first field that differs in each packet. Every branch a writer can take (if/else, switch, early return) must match one of the documented variants, and helpers called on members or through function arguments are followed. The Protocol check workflow runs it against the documentation of CURRENT_PROTOCOL and publishes the report in the run summary.

python tools/check_protocol.py --docs /path/to/bedrock-protocol-docs/json
python tools/check_protocol.py --docs /path/to/bedrock-protocol-docs/json --explain PlaySoundPacket

Related repositories

• Falcon - the server
• Network - RakNet and NetherNet transport
• NBT - NBT tags and binary streams
• BedrockData - game data files, versioned by protocol

Licensing information

Falcon Protocol is licensed under the GNU Lesser General Public License v3.0, which supplements the GNU General Public License v3.0. It can be linked from projects under any license, as long as changes to this library itself stay under the same license.

Falcon is not affiliated with Mojang. All brands and trademarks belong to their respective owners.