NetherNet Protocol and Add-On Networking

Historically, Minecraft Bedrock Edition relied entirely on RakNet over UDP for all multiplayer communication, from local LAN games to dedicated servers. NetherNet introduces a modern networking stack built around WebRTC data channels, ICE (Interactive Connectivity Establishment), STUN, and TURN relays. When two players connect over Xbox Live or Nintendo Switch Online—or when a client discovers a local host—the engine negotiates a NetherNet session identified by a 64-bit network ID rather than binding strictly to raw IPv4 sockets.

At the game layer, Bedrock serializes gameplay packets (such as entity movement, block updates, and resource pack chunks) using the same internal format regardless of the underlying transport. However, the transport characteristics of NetherNet differ from raw RakNet. Because traffic often routes through TURN relay servers when symmetric NATs block direct UDP hole-punching, latency variance (jitter) and maximum transmission unit (MTU) overhead behave differently. Add-on developers feel these differences most acutely during initial world join, when the host transfers behavior and resource packs, and during high-frequency Script API updates.

When a client joins a host over NetherNet, the signaling service exchanges Session Description Protocol (SDP) offers and ICE candidates. Once the DTLS handshake completes and the WebRTC data channel opens, the standard Bedrock login sequence begins. Immediately after authentication, the server sends the resource pack stack info to the client.

If the host requires the client to download an add-on they do not have cached, the host slices the zipped pack into chunks and streams them across the NetherNet data channel. Over a relayed TURN connection, available bandwidth is throttled compared to a direct UDP connection, and congestion control algorithms in the WebRTC stack will aggressively back off if the game thread floods the socket. If your add-on consists of a single monolithic resource pack containing tens of megabytes of uncompressed `.tga` textures and `.wav` audio files, the NetherNet SCTP/DTLS queue can stall, leading to a connection timeout before the client ever spawns into the world.

To ensure reliable transfers over NetherNet relays, keep individual pack archives modular, use `.ogg` for audio, prefer `.png` over `.tga` where possible, and declare strict dependencies in your manifest so the client caches base assets separately from frequent script updates.

{
  "format_version": 2,
  "header": {
    "name": "NetherNet Optimized Behavior Pack",
    "description": "Separates heavy assets into the RP to keep BP chunk transfers fast.",
    "uuid": "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d",
    "version": [1, 0, 0],
    "min_engine_version": [1, 20, 80]
  },
  "modules": [
    {
      "type": "data",
      "uuid": "b2c3d4e5-f6a7-4b5c-9d0e-1f2a3b4c5d6e",
      "version": [1, 0, 0]
    },
    {
      "type": "script",
      "language": "javascript",
      "uuid": "c3d4e5f6-a7b8-4c5d-0e1f-2a3b4c5d6e7f",
      "entry": "scripts/main.js",
      "version": [1, 0, 0]
    }
  ],
  "dependencies": [
    {
      "uuid": "d4e5f6a7-b8c9-4d5e-1f2a-3b4c5d6e7f80",
      "version": [1, 0, 0]
    },
    {
      "module_name": "@minecraft/server",
      "version": "1.11.0"
    }
  ]
}

A common pitfall when testing add-ons exclusively in singleplayer or on local dedicated servers is assuming that a player entity is immediately ready to receive UI forms or camera instructions the moment they join. Over NetherNet—especially on consoles or mobile devices routing through a relay—there is a measurable delay between the server allocating the player actor (`playerJoin`) and the client completing chunk generation and closing the loading screen (`playerSpawn`).

If your script attempts to send a `ActionFormData` payload or play a client-side sound during `playerJoin`, the packet is queued in the NetherNet transport buffer while the client is still processing terrain chunks. In high-latency sessions, the client may silently drop UI packets that arrive before the local HUD is initialized. Always defer initial client-bound payloads until the `playerSpawn` after-event fires with `initialSpawn` set to `true`, and consider adding a short tick delay to allow the WebRTC channel to flush initial entity state synchronization.

import { world, system } from "@minecraft/server";

// Track connection timing to diagnose slow NetherNet relay handshakes
const joinTimestamps = new Map();

world.afterEvents.playerJoin.subscribe((event) => {
  // At this stage, the NetherNet session is open and pack transfer is complete,
  // but the client is still on the loading screen awaiting level chunks.
  joinTimestamps.set(event.playerId, Date.now());
});

world.afterEvents.playerSpawn.subscribe((event) => {
  const { player, initialSpawn } = event;
  if (!initialSpawn) return;

  const joinTime = joinTimestamps.get(player.id);
  joinTimestamps.delete(player.id);

  const handshakeDuration = joinTime ? Date.now() - joinTime : 0;

  // Defer heavy client-bound packets by 20 ticks (1 second) so the WebRTC
  // data channel finishes flushing initial entity and property payloads.
  system.runTimeout(() => {
    if (!player.isValid()) return;

    player.sendMessage(
      `[NetDiag] Sync complete in ${handshakeDuration}ms. Initializing add-on state.`
    );
    player.setDynamicProperty("addon:net_ready", true);
  }, 20);
});

Every time a behavior pack modifies a synced actor property (defined under `properties` in the entity description with `client_sync: true`) or triggers a client-visible state change (such as `minecraft:skin_id` or `minecraft:variant`), the server queues a delta packet for all clients within simulation distance. Over NetherNet, packets are encapsulated inside DTLS records and SCTP chunks, which adds header overhead to every transmission.

When designing custom entities that communicate state to resource pack render controllers or animations, batch your state changes rather than toggling properties every tick. For example, if an entity needs to sync a custom mana bar or charge meter to a client-side Molang query (`query.property`), updating a float property 20 times a second across 50 entities will saturate a peer-to-peer host's upload bandwidth. Instead, quantize the value into discrete integer steps or rely on client-side Molang interpolation (`math.lerp`) between infrequent server updates.

{
  "format_version": "1.20.80",
  "minecraft:entity": {
    "description": {
      "identifier": "custom:synced_turret",
      "is_spawnable": true,
      "is_summonable": true,
      "properties": {
        "custom:charge_stage": {
          "type": "int",
          "range": [0, 4],
          "default": 0,
          "client_sync": true
        }
      }
    },
    "components": {
      "minecraft:physics": {},
      "minecraft:Health": {
        "value": 20,
        "max": 20
      }
    }
  }
}

Applies to Minecraft Bedrock Edition 1.19.50 and newer, where NetherNet was rolled out for Xbox Live, PlayStation, Switch, and LAN peer-to-peer transport. No experimental toggle is required, as transport selection is handled automatically by the engine.

Read out of the game itself, so the ids match the version you are building for.