DOCSEARCHbyAlgolia
Submit Docs

Minecraft: Bedrock Edition Network Protocol Documentation

repository·main·Indexed 20 days ago

https://github.com/mojang/bedrock-protocol-docs

Official technical specifications for the Minecraft: Bedrock Edition Network Protocol, designed for developers building custom servers. Includes packet structures, classes, and enums via tree diagrams. Covers current release r/21_u13 (Network Version 893), with detailed documentation on anti-cheat implementation, player movement validation, block breaking authority modes, and server-authoritative inventory systems.

Tokens
33.6K
Snippets
51
Records
185
Agent score
67%

What's inside mojang-bedrock-protocol-docs

  1. Overview of the Minecraft: Bedrock Edition Network Protocol Documentation

    main

    This documentation provides the technical specifications required for server partners to develop custom Minecraft servers. It consists of tree diagrams defining the structure of network packets, along with related classes and enums used in the protocol.

    Important Note: The protocol is subject to change with every new release. Always verify that your implementation matches the specific release version you are targeting.

  2. Access Anti-Cheat implementation documentation

    main
    The additional_docs/ directory contains technical documentation regarding anti-cheat implementation details that are not immediately apparent from the source code classes. This documentation is maintained alongside the code to ensure accuracy. For the best reading experience, use GitHub's file view to render the Markdown content.

  3. What is the Player UI Container?

    main

    The Player UI Container is a specialized item stack container with 51 slots designed to hold player-specific UI elements (e.g., cursor items, crafting inputs, anvil inputs).

    It is a key component of the transition toward a Server Authoritative system for containers. This allows servers to track all containers that clients are interacting with (like crafting tables or anvils), enabling the server to become fully authoritative over all item stacks in all containers.

  4. How server-authoritative movement and client prediction work

    main

    The movement mode is client-predicted with full server authority.

    The Workflow:

    1. Client Prediction: After simulating movement for a frame, the client sends an input packet containing their input and their predicted position, along with a tick ID.
    2. Server Simulation: The server waits for the input packet, simulates the movement for that player, and compares the server's result with the client's predicted position.
    3. Correction: If the server detects a discrepancy, it sends a correction packet containing the tick ID from the frame being corrected.
    4. Client Rewind: Because the client has already predicted several ticks past the correction point, it performs a 'rewind': it reverts its state to the specified tick ID, applies the correction, and then re-simulates all subsequent ticks up to the present. This minimizes disruption compared to applying corrections directly to the current frame.

    Note: When riding a client-predicted vehicle (e.g., a horse or boat), predicted position values and corrections refer to the vehicle, not the player.

  5. Manage OpenContainerPacket for Server-Authoritative UI

    main

    Clients no longer open container screens (including the player's inventory) immediately on the client side. Instead, they wait for an OpenContainerPacket from the server. This allows the server to be authoritative and deny requests (e.g., if a chest is occupied).

    Implementation Details:

    • Responsiveness: Servers must respond with OpenContainerPacket promptly to avoid perceived latency in UI opening.
    • Follow-up Packets: After sending an OpenContainerPacket, servers typically follow up with an InventoryContentPacket for the primary container (e.g., chest contents, furnace items, or horse/llama equipment).
    • Exceptions:
      • Servers do not send InventoryContentPacket for the player's own inventory screen (including 2x2 crafting or enchanting tables).
      • Servers do not send Hotbar, Inventory, Offhand, or Armor contents when opening those specific screens.

    Alternative Packets for Specific Containers:

    Some containers use different packets instead of OpenContainerPacket:

    • Horse/Donkey/Mule equipment: Use UpdateEquipPacket.
    • Villager trading (Legacy Trade1 and newer Trade2): Use UpdateTradePacket.

  7. Use ItemStackNetId for inventory packets

    main

    When the ItemStackNetManager is disabled, the server is still responsible for providing ItemStackNetId values in inventory-related packets. These values are serialized as VarInt (packed 32-bit signed integer) or IntTag in NBT.

    Required values for disabled mode:

    • 0: For empty slots (no item stack).
    • 1: For non-empty slots (contains an item stack).

  8. How movement anti-cheat works with client rewind

    main

    When anti-cheat with client rewind is enabled, both the client and server simulate inputs. If the server detects that the client is out of sync (by comparing the server's authoritative position against the client's prediction in PlayerAuthInputPacket), it issues a correction.

    To handle this, the client:

    1. Rewinds to the specific point in time the server was referring to.
    2. Performs the correction.
    3. Replays all inputs that occurred since that point in time.

  9. How fast block destruction works in Survival

    main

    In Survival mode, block destruction is governed by a delay between actions. The standard delay is defined by GameMode::creativeDestructionTickDelay, which is 250ms.

    Exceptions:

    • If a tool is efficient enough to damage a block's durability completely in a single tick (e.g., an Efficiency 5 diamond shovel on dirt), the delay is bypassed.
    • The delay can be cancelled by targeting a different block while mining.

    For implementation details, refer to GameMode::continueDestroyBlock.

  10. Recipe Unlocking Requirements in r21 (Version 685)

    main

    In Network Protocol Version 685 (r21), ShapedRecipe and ShapelessRecipe now include recipe.getUnlockingRequirement() which returns a RecipeUnlockingRequirement object.

    RecipeUnlockingRequirement contains:

    • getUnlockingContext() (enum RecipeUnlockingRequirement::UnlockingContext)
    • If getUnlockingContext() returns RecipeUnlockingRequirement::UnlockingContext::None, a vector list of getUnlockingIngredients() (containing RecipeIngredient objects) is provided.

  11. Understand the NetherNet Architecture

    main

    NetherNet is a peer-to-peer networking transport layer for Minecraft built on WebRTC. It uses an HTTP signaling server to bridge the gap between the Minecraft client and the game host.

    The connection lifecycle follows these steps:

    1. SDP Gathering: The Minecraft client gathers a complete SDP offer (including all ICE candidates).
    2. Signaling: The client sends this offer to a partner's signaling server via a single HTTP POST.
    3. Negotiation: The signaling server relays the offer to the host and returns the host's SDP answer to the client.
    4. P2P Connection: Once the client receives the answer, WebRTC ICE connectivity checks run directly between the client and host.
    5. Data Flow: Once connectivity is established, SCTP data channels open, and game traffic flows peer-to-peer (DTLS + SCTP).

    Note: The signaling server is only involved during the initial SDP exchange. All subsequent game traffic flows directly between the client and host.

    ┌──────────────┐         HTTPS          ┌──────────────────────┐
│              │ ─────────────────────► │                      │
│   Minecraft  │   POST /v1/join/{id}   │   Partner Signaling  │
│    Client    │   Body: SDP offer      │       Server         │
│              │ ◄───────────────────── │                      │
│              │   200 OK               │                      │
│              │   Body: SDP answer     │                      │
└──────┬───────┘                        └──────────────────────┘
       │
       │  WebRTC P2P (DTLS + SCTP)
       │
       ▼
┌──────────────┐
│   Partner    │
│    Host      │
│  (WebRTC)    │
└──────────────┘

  12. Configure WebRTC for NetherNet (Full ICE)

    main

    When building a compatible WebRTC peer for NetherNet, you must adhere to the following configuration requirements:

    • ICE Strategy: Use Full ICE. Do not use Trickle ICE. The signaling protocol expects the entire SDP (with all candidates) to be transmitted in a single round-trip.
    • Data Channels: Use WebRTC data channels exclusively. NetherNet does not use audio or video tracks.
    • STUN/TURN Recommendation: It is not recommended to configure STUN or TURN servers when using HTTP signaling. Because trickle ICE is disabled, the client must wait for all STUN/TURN interactions to complete before sending the SDP, which increases connection latency.
    • Transport: The peer-to-peer connection uses DTLS and SCTP for data channels.