NetCrafter Relay Tutorial: Chat Quick Start

Every peer — host and joiners alike — opens one TURN allocation on your coturn relay and exchanges messages through it. The host does all the fan-out: when a joiner sends a chat message, it goes to the host first, and the host rebroadcasts it to everyone (including back to other joiners) via BroadcastToAll.

This is why the chat demo below has a SendChat message (joiner → host) and a separate ChatBroadcast event (host → everyone) instead of a single two-way message — that split is the host-relay model.

1.1 Open the NetCrafter Relay window

Tools → Pivec Labs → NetCrafter Relay.

1.2 Create a new schema

Click + Create Definition, enter ChatDemo, click Create. This creates Assets/PivecLabs/NetCrafterRelay/Definitions/ChatDemo/ with all the standard subfolders (Messages, DataDefinitions, HostActions, SyncRules, Generated) and a fresh RelaySettings.asset — with no working defaults, by design (see Part 4).

Open the Gameplay Messages tab. Click Create Gameplay Message three times and fill each in as follows.

2.1 Login — client tells the host its display name

Add one field: displayName (type string).

2.2 SendChat — client sends a chat message

Add one field: text (type string).

2.3 ChatBroadcast — host fans a chat message out to everyone

Add two fields: senderName (type string), text (type string).

Open the Host Actions tab. Create two.

3.1 HandleLogin

Custom Host Code:

ChatPlayerRegistry.Names[senderId] = trigger.displayName;
if (connection.debugLogging) Debug.Log($"[ChatDemo] Player {senderId} logged in as '{trigger.displayName}'");

3.2 HandleSendChat

Custom Host Code:

string senderName = ChatPlayerRegistry.Names.TryGetValue(senderId, out var pname) ? pname : ("Player" + senderId);
var fixedEvent = new ChatBroadcastEvent { senderName = senderName, text = trigger.text };
connection.BroadcastToAll("ChatBroadcast", fixedEvent.Serialize(), true);
// BroadcastToAll reaches every registered joiner over the relay, but never loops back to
// this machine -- dispatch locally too, so the host's own Scene Event Router binding (and
// therefore its own chat log) sees other players' messages, not just its own.
PivecLabs.NetCrafterRelay.NetCrafterEventDispatcher.Instance?.Dispatch("ChatBroadcast", fixedEvent);

3.3 Add the player-name registry

Both handlers above reference ChatPlayerRegistry — a tiny static helper you add yourself, since it needs to persist across message handlers for the lifetime of a session. Create Assets/PivecLabs/Examples/ChatDemo/Scripts/ChatPlayerRegistry.cs:

using System.Collections.Generic;

public static class ChatPlayerRegistry
{
    public static readonly Dictionary<int, string> Names = new();
}

Open Settings → Relay Settings. Every field below is blank by default and shows a warning until filled in — that's intentional, not a bug: NetCrafter Relay ships fully self-hosted, with no Pivec Labs-run relay or rendezvous service to fall back to.

If you haven't stood up coturn and the rendezvous service yet, do that first — see the Server Deployment Guide, which covers both on the same box.

Click Save Settings.

Open Build Code, click Validate Definition (optional sanity check), then click Generate All Files.

This writes to Definitions/ChatDemo/Generated/:

• Client/LoginRequest.cs, Client/SendChatRequest.cs, Client/ChatBroadcastEvent.cs, Client/RelayConnectionManager.cs
• Host/HostActionRouter.cs
• Config/RelayConfig.json (or similar, per NC_GenerateConfig)

Let Unity finish recompiling, then check the Console — zero errors expected. If you see CS0103: The name 'ChatPlayerRegistry' does not exist in the current context, double-check the file from Part 3.3 exists and has no namespace wrapped around the class.

Before building the scene, it's worth knowing about two components you'll be adding, since neither is generated and neither is obvious from its name alone.

NetCrafterEventDispatcher

This ships with the base NetCrafter Relay package (Scripts/NetCrafterEventDispatcher.cs) — it is not generated per-schema, and it's the same one class regardless of what your schema looks like. It's a small runtime pub/sub bus: every incoming message, both the two built-in connection-lifecycle notifications (RelayHosting, ConnectionLost) and every HostToClient event your schema defines, gets funneled through it via Dispatch(cmd, payload). You need exactly one NetCrafterEventDispatcher component in your scene, on any GameObject, for any of this to work — without it, nothing fails loudly, but no event handler anywhere will ever fire. You'll add this GameObject in Part 6.1.

Code can subscribe to it directly (NetCrafterEventDispatcher.Instance.Subscribe("SomeEvent", callback)) — this tutorial does that for the two built-in lifecycle notifications, since those aren't schema events and have no other wiring path. But for schema-defined events like ChatBroadcast, there's a friendlier option:

NetCrafterSceneEventRouter

This is a higher-level, no-code wrapper around the dispatcher, built specifically for schema events. Open Settings → Scene Events and click Add Router to Scene — it adds a NetCrafterSceneEventRouter GameObject and auto-lists every HostToClient event in your schema (here, just ChatBroadcast), each with its own UnityEvent called On Received that you wire up in the Inspector exactly like a Button's On Click () — no Subscribe() call to write yourself. Internally, the router subscribes to NetCrafterEventDispatcher on your behalf, one binding per schema event, and invokes your wired method when that event arrives. You'll use this in Part 6.4 for ChatBroadcast.

Put simply: the dispatcher is the low-level bus every event goes through; the router is an Inspector-friendly shortcut for schema events specifically. You still need both GameObjects in the scene — the router doesn't replace the dispatcher, it sits on top of it.

Keep this simple — the point of this tutorial is proving the pipeline, not polishing UI. Every step below assumes an empty scene with nothing in it yet.

7.1 Create the Canvas

1. In the Hierarchy, right-click → UI → Canvas. This also creates an EventSystem GameObject automatically if one doesn't already exist.
2. On the Canvas component, confirm Render Mode is Screen Space - Overlay.

7.2 Create the Login panel

1. Right-click Canvas → UI → Panel — name it LoginPanel. Leave it stretched to fill the parent (the default anchor).
2. Right-click LoginPanel → UI → Text - TextMeshPro — name it Title. Set its text to Chat Room Login, center-align it, and move it toward the top of the panel.
3. Right-click LoginPanel → UI → Input Field - TextMeshPro — name it DisplayNameInput. Set its Placeholder child's text to Enter your name.... Position it below Title.
4. Right-click LoginPanel → UI → Button - TextMeshPro — name it ContinueButton. Set its label's text to Continue. Position it below DisplayNameInput.

7.3 Create the Lobby panel

1. Right-click Canvas → UI → Panel — name it LobbyPanel.
2. Right-click LobbyPanel → UI → Button - TextMeshPro — name it HostButton. Label: Host Game. Position it near the top.
3. Right-click LobbyPanel → UI → Input Field - TextMeshPro — name it JoinCodeInput. Placeholder text: Join code.... Position it below HostButton.
4. Right-click LobbyPanel → UI → Button - TextMeshPro — name it JoinButton. Label: Join Game. Position it below JoinCodeInput.
5. Right-click LobbyPanel → UI → Text - TextMeshPro — name it JoinCodeDisplay. Leave the text blank for now — the script fills it in once you're hosting. Position it near the bottom.
6. Right-click LobbyPanel → UI → Text - TextMeshPro — name it StatusText. Leave the text blank. Position it just below JoinCodeDisplay. This is where connection errors ("Couldn't reach the relay server — check your connection") and transient retry messages ("Retrying connection… (attempt 2 of 3)") show up — kept as its own field, separate from JoinCodeDisplay, so a success message and an error/retry message never have to share one field.
7. Select LobbyPanel in the Hierarchy and uncheck the checkbox next to its name in the Inspector to disable it — you start on the Login panel, not this one.

7.4 Create the Chat panel

1. Right-click Canvas → UI → Panel — name it ChatPanel.
2. Right-click ChatPanel → UI → Scroll View — name it ChatScrollView. Uncheck Horizontal scrolling (keep Vertical checked). Resize it to fill roughly the top three-quarters of ChatPanel.
3. Expand ChatScrollView in the Hierarchy: Viewport → Content.
4. Right-click Content → UI → Text - TextMeshPro — name it ChatLog. Set its anchors to stretch horizontally (left = 0, right = 1) with left/right offsets of 0. Set its alignment to Top Left.
5. Select Content itself (not ChatLog) and add two components: a Vertical Layout Group (Padding all 0, Spacing 0, Child Alignment Upper Left, Child Controls Size checked for both Width and Height, Child Force Expand checked for Width only) and a Content Size Fitter (Horizontal Fit Unconstrained, Vertical Fit Preferred Size).

6. Right-click ChatPanel → UI → Input Field - TextMeshPro — name it MessageInput. Placeholder text: Type a message.... Position it at the bottom-left of ChatPanel.
7. Right-click ChatPanel → UI → Button - TextMeshPro — name it SendButton. Label: Send. Position it to the right of MessageInput.
8. Select ChatPanel in the Hierarchy and uncheck it to disable it, same as you did for LobbyPanel.

7.5 Add the relay and event GameObjects

1. Create Empty (right-click in the Hierarchy) — name it RelayConnectionManager. In Part 7.7 you'll attach the generated RelayConnectionManager component to it.
2. Create Empty — name it HostActionRouter. You'll attach the generated HostActionRouter component here.
3. Create Empty — name it NetCrafterEventDispatcher. Attach the NetCrafterEventDispatcher component to it (Add Component in the Inspector, search for it by name) — see Part 6 for what this does.
4. Select the RelayConnectionManager GameObject and uncheck it to disable it.

7.6 Add the Scene Event Router

1. Go to Settings → Scene Events in the NetCrafter Relay window.
2. Click Add Router to Scene. This creates a SceneEventRouter GameObject with a NetCrafterSceneEventRouter component, and lists ChatBroadcast (the only HostToClient event in this schema) with an empty On Received slot. Leave it empty for now — you'll wire it in Part 7.9, after ChatDemoController exists to wire it to.

7.7 Attach the generated RelayConnectionManager and HostActionRouter

1. Select the RelayConnectionManager GameObject. Add Component → search for RelayConnectionManager (the generated component from Part 5) → add it.
2. Select the HostActionRouter GameObject. Add Component → search for HostActionRouter → add it.

7.8 Attach the ChatDemoController script

ChatDemoController.cs already ships with the package — you don't write it from scratch. It's at:

Assets/PivecLabs/Examples/ChatDemo/Scripts/ChatDemoController.cs

1. Create Empty in the Hierarchy — name it ChatDemoController.
2. Drag ChatDemoController.cs onto it (or Add Component → search for Chat Demo Controller).
3. With ChatDemoController selected, wire up its Inspector fields:

7.9 Wire the buttons and the ChatBroadcast event

1. Select ContinueButton. In the Inspector, find Button → On Click (), click +, drag the ChatDemoController GameObject into the object slot, and pick ChatDemoController → OnLoginClicked () from the function dropdown.
2. Select HostButton. Same steps, picking OnHostClicked ().
3. Select JoinButton. Same steps, picking OnJoinClicked ().
4. Select SendButton. Same steps, picking OnSendClicked ().
5. Select the SceneEventRouter GameObject you created in Part 7.6. Find ChatBroadcast's On Received UnityEvent, click +, drag ChatDemoController into the object slot, and pick ChatDemoController → OnChatBroadcastReceived ().

That's every wiring step — no code left to write. Here's what ChatDemoController.cs actually does, for reference:

using System.Collections;
using UnityEngine;
using UnityEngine.UI;
using TMPro;
using PivecLabs.Generated;
using PivecLabs.NetCrafterRelay;

public class ChatDemoController : MonoBehaviour
{
    public GameObject relayConnectionManagerObject;

    public GameObject loginPanel;
    public TMP_InputField displayNameInput;

    public GameObject lobbyPanel;
    public TMP_InputField joinCodeInput;
    public TMP_Text joinCodeDisplay;
    public TMP_Text statusText; // optional -- errors/retry status on the Lobby panel

    public GameObject chatPanel;
    public TMP_InputField messageInput;
    public TMP_Text chatLog;
    public ScrollRect chatScrollRect;

    private RelayConnectionManager relay;
    private string displayName = "Player";

    private void Awake()
    {
        // ChatPlayerRegistry.Names is a static dictionary -- it survives across repeated Unity
        // Editor Play-mode sessions when Domain Reload is disabled (Project Settings -> Editor
        // -> Enter Play Mode Settings), a common performance setting. Without clearing it here,
        // a second Play session can inherit a stale display name from a previous one under the
        // same user id (the host is always id 0). Standalone builds always start a fresh
        // process, so this only matters for repeated in-Editor testing.
        ChatPlayerRegistry.Names.Clear();

        relay = relayConnectionManagerObject.GetComponent<RelayConnectionManager>();

        // Confirmed live: RelayConnectionManager.Start() unconditionally calls Connect(), which
        // defaults to hosting a new session when no join code is pending. If Part 7.5's checkbox
        // is left active by mistake, the app auto-hosts the instant the scene loads -- zero
        // clicks, entirely bypassing Login/Lobby. Force it inactive here defensively, the same
        // pattern already used below for the panel states, so correct behavior doesn't depend on
        // a reader noticing and manually unchecking a box.
        relayConnectionManagerObject.SetActive(false);

        ShowLogin();
    }

    private void Start()
    {
        // Start() runs after every Awake() in the scene, so the dispatcher is guaranteed to
        // exist here even though Awake ordering between separate GameObjects isn't guaranteed.
        NetCrafterEventDispatcher.Instance.Subscribe("RelayHosting", OnRelayHosting);
        NetCrafterEventDispatcher.Instance.Subscribe("ConnectionLost", OnConnectionLost);
        NetCrafterEventDispatcher.Instance.Subscribe("RelayStatus", OnRelayStatus);
    }

    private void ShowLogin() { loginPanel.SetActive(true); lobbyPanel.SetActive(false); chatPanel.SetActive(false); }
    private void ShowLobby() { loginPanel.SetActive(false); lobbyPanel.SetActive(true); chatPanel.SetActive(false); }
    private void ShowChat()  { loginPanel.SetActive(false); lobbyPanel.SetActive(false); chatPanel.SetActive(true); }

    public void OnLoginClicked()
    {
        displayName = string.IsNullOrEmpty(displayNameInput.text) ? "Player" : displayNameInput.text;
        ShowLobby();
    }

    public void OnHostClicked()
    {
        if (statusText != null) statusText.text = ""; // clear any error/retry text from a previous attempt
        relayConnectionManagerObject.SetActive(true);
    }

    public void OnJoinClicked()
    {
        string code = joinCodeInput.text.Trim();
        if (string.IsNullOrEmpty(code)) return;
        if (statusText != null) statusText.text = "";
        relay.UpdateHost(code);
        relayConnectionManagerObject.SetActive(true);
        StartCoroutine(SendLoginWhenConnected());
    }

    private void OnRelayHosting(object joinCodeObj)
    {
        // Just update the join code text and stay on the Lobby panel here -- it's already
        // showing (OnHostClicked doesn't change panels). SendLoginWhenConnected() below is the
        // only place that transitions to Chat. An earlier version of this called ShowChat()
        // right here too, which deactivated the Lobby panel in the very same frame the join
        // code was set on it -- confirmed live, the host never actually saw JoinCodeDisplay,
        // only the join code in the Debug log.
        joinCodeDisplay.text = "Join code: " + (string)joinCodeObj;
        StartCoroutine(SendLoginWhenConnected());
    }

    private void OnConnectionLost(object reason)
    {
        // Additive -- AppendLog (and its own Debug.Log) is unchanged. This is for the Lobby
        // panel, which is where a failed host/join attempt actually leaves the player -- Chat's
        // own log is never shown yet at that point.
        AppendLog("[system] Connection lost: " + reason);
        if (statusText != null) statusText.text = NetCrafterConnectionStatus.ToPlayerMessage((string)reason);
    }

    // "RelayStatus" carries transient, already-friendly text (e.g. a retry-in-progress message)
    // rather than a raw reason string, so it's shown as-is instead of going through the mapper.
    private void OnRelayStatus(object message)
    {
        if (statusText != null) statusText.text = (string)message;
    }

    private const float HostLobbyDisplaySeconds = 4f;

    // Confirmed live: the rendezvous lookup alone can retry up to 3 times at 15s each on a slow
    // or flaky connection (RelayConnectionManager's RendezvousRequestTimeoutSeconds/
    // maxJoinAttempts) before TURN permissions and the hello/ack handshake even start -- a
    // real-network join can take well over 10 seconds without anything actually being wrong.
    private const float ConnectTimeoutSeconds = 60f;

    private IEnumerator SendLoginWhenConnected()
    {
        float deadline = Time.realtimeSinceStartup + ConnectTimeoutSeconds;
        while (!relay.IsConnected && Time.realtimeSinceStartup < deadline) yield return null;
        if (!relay.IsConnected) { AppendLog($"[system] Failed to connect within {ConnectTimeoutSeconds}s."); yield break; }

        // RelayConnectionManager.Send() only has an implicit destination for joiners -- on
        // the host it's a documented no-op with a warning, since the host has no single "the"
        // peer to send to (see API Reference). The host registers its own name directly
        // instead of routing a Login message to itself.
        if (relay.IsHost)
        {
            ChatPlayerRegistry.Names[relay.LocalUserId] = displayName;

            // Confirmed live: RelayConnectionManager marks the host "connected" the instant its
            // own rendezvous registration succeeds -- the same moment the join code becomes
            // available -- so the wait-for-connected loop above never actually waits for a
            // host. Without a deliberate pause, Lobby (with the join code the host needs to
            // read and share) would show and hide again within the same frame. This gives the
            // host a real window to see and share it before Chat appears.
            yield return new WaitForSeconds(HostLobbyDisplaySeconds);
        }
        else
        {
            new LoginRequest { displayName = displayName }.Send(relay);
        }

        ShowChat();
    }

    public void OnSendClicked()
    {
        if (messageInput == null || string.IsNullOrEmpty(messageInput.text)) return;

        if (relay.IsHost)
        {
            // Same reasoning as above -- broadcast directly instead of routing through
            // Send(), and echo locally since BroadcastToAll doesn't loop the message back to
            // the host's own OnChatBroadcastReceived handler.
            var ev = new ChatBroadcastEvent { senderName = displayName, text = messageInput.text };
            relay.BroadcastToAll("ChatBroadcast", ev.Serialize(), true);
            AppendLog($"{ev.senderName}: {ev.text}");
        }
        else
        {
            new SendChatRequest { text = messageInput.text }.Send(relay);
        }

        messageInput.text = "";
    }

    // Wired to the ChatBroadcast binding's "On Received" UnityEvent (Part 7.9), not a
    // code-based Subscribe call -- it needs to be parameterless, so the actual payload is
    // pulled via GetLastPayload() instead of arriving as an argument.
    public void OnChatBroadcastReceived()
    {
        var ev = (ChatBroadcastEvent)NetCrafterSceneEventRouter.Instance.GetLastPayload("ChatBroadcast");
        AppendLog($"{ev.senderName}: {ev.text}");
    }

    // How close to the bottom (0 = bottom, 1 = top, Unity's own ScrollRect convention) counts
    // as "already reading the latest messages" for auto-scroll purposes.
    private const float AutoScrollThreshold = 0.02f;

    private void AppendLog(string line)
    {
        // Decide BEFORE appending: only auto-scroll if the user was already at (or very near)
        // the bottom. Yanking the view down on every message would make it impossible to
        // scroll up and read history -- confirmed live as the actual "scrolling doesn't work
        // well" complaint, not just a missing nicety.
        bool wasAtBottom = chatScrollRect == null || chatScrollRect.verticalNormalizedPosition <= AutoScrollThreshold;

        chatLog.text += line + "\n";

        if (wasAtBottom && chatScrollRect != null)
            StartCoroutine(ScrollToBottomNextFrame());

        Debug.Log("[ChatDemo] " + line);
    }

    // Confirmed live: setting verticalNormalizedPosition in the same frame the text changes
    // does nothing useful -- Content Size Fitter/Layout Group haven't recalculated Content's
    // height yet, so the ScrollRect is still working off the previous (smaller) bounds. One
    // frame plus a forced canvas update is enough for the rebuilt layout to land first.
    private IEnumerator ScrollToBottomNextFrame()
    {
        yield return null;
        Canvas.ForceUpdateCanvases();
        chatScrollRect.verticalNormalizedPosition = 0f;
    }
}

A finished reference scene with all of the above already wired up lives at Assets/PivecLabs/Examples/ChatDemo/ChatDemoScene.unity, if you'd rather inspect a working example side by side with your own than build entirely from these steps alone.

1. Build the scene (File → Build Settings → Build), or use two Editor instances if you have a license that supports it.
2. Run one copy. Enter a name, click Continue — you land on the Lobby panel. Click Host Game. The Lobby panel stays up with your join code on JoinCodeDisplay for a few seconds (HostLobbyDisplaySeconds in ChatDemoController.cs, shown above) — that's your window to read and share it — before it moves on to the Chat panel automatically.
3. Run a second copy (and a third, a fourth — this works the same at 2, 3, or 4 players). Enter a name, click Continue, type in the join code from step 2, click Join Game.
4. Send a message from any copy. It should appear in every copy's chat log, prefixed with the sender's name — including copies that didn't send it, proving the host's BroadcastToAll fan-out is working, and including on the host's own copy, since the host is also a player.

If something goes wrong instead — the relay is unreachable, or a join code doesn't resolve — StatusText on the Lobby panel now shows a plain-language message (e.g. "Couldn't reach the relay server — check your connection", or "That join code wasn't found — check it and try again") instead of leaving you looking at a Lobby panel with no explanation. A join that's still retrying briefly shows "Retrying connection… (attempt N of 3)" first. Full technical detail always still goes to the Console, unchanged.

If a message doesn't show up everywhere, check the Console on the host's copy first — HandleSendChat logs are the easiest place to see whether the host received it and re-broadcast it.

NetCrafter Relay — Pivec Labs