Recipes

This page has longer, worked examples. They combine the install, the transport swap, lane selection, and the lifecycle callbacks into programs that you can run. For the per-method reference, see SDK methods. For short snippets, see the Cookbook.

Recipe 1 — Port the ECS racing sample onto FirstByte

Unity’s ECS-Network-Racing-Sample is a DOTS / Netcode for Entities project. The transport swap is the fastest way to check that an end-to-end match runs over the FirstByte relay mesh.

Add the package

Open the sample in Unity. Add the transport via Package Manager → Add package from git URL:

https://github.com/clutchcall/core-sdk.git?path=unity/com.clutchcall.transport

Swap the transport on the NetworkManager

Find the prefab that holds the NetworkManager. Remove UnityTransport. Add ClutchCallTransport. Then point Netcode at it:

var nm = manager.GetComponent<NetworkManager>();
nm.NetworkConfig.NetworkTransport = nm.GetComponent<ClutchCallTransport>();

Configure relay + token

Drive the inspector fields from a small bootstrap. Then the host and the clients agree on the room:

var t = nm.GetComponent<ClutchCallTransport>();
t.RelayHost = "relay.firstbyte.fast";
t.RoomId    = "race-01";
t.Token     = await FetchRoomTokenAsync("race-01", localPlayerId);

Assign host vs client roles

Keep the sample’s own “Go in game” flow. The host opens the room’s authority namespace. Each client announces a discovery namespace and joins the room:

if (isHost) nm.StartHost();
else        nm.StartClient();

Build players (not the editor)

Editor batch mode does not drive Netcode for Entities. Build a player for each role. Start the players. The [Server] / [Client] connection lifecycle completes. Netcode assigns NetworkId. The cars sync.

What flows where:

Car transforms / physics ticks use the unreliable lane (QUIC datagrams). This traffic is high frequency and latest-wins, with no head-of-line blocking.
Spawns, despawns, and race-start / finish RPCs use the reliable lane (MoQT subgroup streams). Delivery is ordered and guaranteed.

Over a full match, tens of thousands of datagrams flow through the relay. You can check link health from the transport:

foreach (var id in nm.ConnectedClientsIds)
    Debug.Log($"peer {id}: rtt={nm.GetComponent<ClutchCallTransport>().GetCurrentRtt(id):F0}ms");

If a client does not appear in the host roster, check that both built players share the same RoomId and a valid token. The discovery namespace announcement drives roster membership. If the rooms do not match, the host never sees the announce.

Recipe 2 — Headless dedicated server with matchmaking

This is a common production shape. A dedicated server player runs the authority for a room. Clients get a room-scoped token from your control-plane API before they connect. The server has no display and starts on launch.

Server bootstrap

using Unity.Netcode;
using FirstByte.Transport;
using UnityEngine;

public class DedicatedServer : MonoBehaviour {
    [SerializeField] NetworkManager nm;

    async void Start() {
        if (!Application.isBatchMode) return; // server build only

        var roomId = Args.Get("room", "lobby-1");
        var t = nm.GetComponent<ClutchCallTransport>();
        t.RelayHost = "relay.firstbyte.fast";
        t.RoomId    = roomId;
        t.Token     = await MintServerTokenAsync(roomId);

        nm.OnClientConnectedCallback  += id => Debug.Log($"join  {id} ({nm.ConnectedClientsIds.Count} in room)");
        nm.OnClientDisconnectCallback += id => Debug.Log($"leave {id}");
        nm.OnTransportFailure         += () => { Debug.LogError("relay session failed"); Application.Quit(1); };

        nm.StartServer();
        Debug.Log($"authority up for room {roomId}");
    }
}

Client matchmaking + join

The client asks the control-plane API for a room and a token. It configures the transport. Then it connects:

public class Matchmaker : MonoBehaviour {
    [SerializeField] NetworkManager nm;

    public async Task JoinAsync(string playerId) {
        // 1. control-plane API hands back a room + short-lived token
        var match = await Api.PostAsync<MatchResp>(
            "https://api.firstbyte.fast/matchmake",
            new { player = playerId });

        // 2. point the transport at the assigned room
        var t = nm.GetComponent<ClutchCallTransport>();
        t.RelayHost = match.RelayHost;     // nearest POP
        t.RoomId    = match.RoomId;
        t.Token     = match.Token;         // room-scoped, short-lived

        // 3. join — datagram lane carries inputs, reliable carries spawns
        nm.OnTransportFailure += () => SceneManager.LoadScene("Lobby");
        nm.StartClient();
    }
}

Why this shape works

No self-hosted relay

Both the dedicated server and the clients connect outbound to the nearest relay POP. There is no inbound port to open and no relay infrastructure to run. The mesh fans state and input between regions.

One QUIC connection per process

The server holds a single QUIC connection for the authority. Each client holds one connection for its session. Reliable and unreliable lanes multiplex over it. There is no second socket and no separate reliability layer to tune.

Tokens are room-scoped and short-lived

The control-plane API mints a token bound to a room and a short TTL. Thus a leaked client token cannot join arbitrary matches. The server mints its own authority token the same way.

Recipe 3 — Lane discipline for a fast-paced shooter

When you control the gameplay code, route traffic onto the correct lane explicitly. The rule: send latest-wins, high-frequency traffic on the unreliable lane. Send anything that you cannot drop on the reliable lane.

public class PlayerSync : NetworkBehaviour {
    // 60 Hz transform updates — drop-safe, latest-wins → unreliable datagram
    [Rpc(SendTo.Server, Delivery = RpcDelivery.Unreliable)]
    void MoveRpc(Vector3 pos, Quaternion rot, ulong tick) =>
        server.IntegrateMove(OwnerClientId, pos, rot, tick);

    // hit registration — must arrive, must be ordered → reliable subgroup stream
    [Rpc(SendTo.Server, Delivery = RpcDelivery.Reliable)]
    void FireRpc(ulong targetTick, Vector3 origin, Vector3 dir) =>
        server.ResolveShot(OwnerClientId, targetTick, origin, dir);

    void Update() {
        if (!IsOwner) return;
        // guard the datagram budget for the move payload
        if (transform.HasMovedSince(lastTick))
            MoveRpc(transform.position, transform.rotation, NetworkTickSystem.Tick);
    }
}

Keep unreliable payloads under MaxPayloadSize(). The transport rejects a QUIC datagram larger than the negotiated max. It does not fragment it. Thus an oversized snapshot silently fails to send. It does not split across packets. For large authoritative state, send a reliable baseline and unreliable deltas.

Details

This page covers the wire model, the lanes, and the architecture.

Games modality

This is the pure-MoQT face of the same wire model, for non-Unity engines.

Start here

Console

Guides

Reference

Recipe 1 — Port the ECS racing sample onto FirstByte

Recipe 2 — Headless dedicated server with matchmaking

Server bootstrap

Client matchmaking + join

Why this shape works

Recipe 3 — Lane discipline for a fast-paced shooter

Details

Games modality

​Recipe 1 — Port the ECS racing sample onto FirstByte

​Recipe 2 — Headless dedicated server with matchmaking

​Server bootstrap

​Client matchmaking + join

​Why this shape works

​Recipe 3 — Lane discipline for a fast-paced shooter

​Related

Details

Games modality

Recipe 1 — Port the ECS racing sample onto FirstByte

Recipe 2 — Headless dedicated server with matchmaking

Server bootstrap

Client matchmaking + join

Why this shape works

Recipe 3 — Lane discipline for a fast-paced shooter

Related