NetCrafter Relay — Racing Tutorial

Racing reuses everything Chat/Co-op/Character already established — Login → Lobby (real join code, Host/Join) → Gameplay, RelayConnectionManager, sync rules for continuous transform replication, NetCrafterEventDispatcher for framework events, Scene Events for schema events — without changing any of it. Two things are genuinely new:

1. A lap system that's host-authoritative for a reason that isn't obvious upfront. A player's own client detects when their own car crosses the finish line (a trigger collider, purely local), but it doesn't just display "Lap 2" — it requests the host record the lap. The host is the only place a lap actually gets counted (RacingGameState.TryRecordLap), the same "one authority decides, everyone reacts to the broadcast" shape as Co-op's pickups, just guarding against an implausibly-fast repeat instead of an exact duplicate — see Part 4.
2. Two sync rules on one car, not six driving one character (compare Character's tutorial): Transform_Position and Transform_Rotation move the car — that's all. There's no Rigidbody_Velocity/CarVelocity sync rule; the remote wheel-spin visual is approximated entirely from position delta between frames instead (Part 1.5), which sidesteps a kinematic remote Rigidbody's own velocity never reflecting transform-driven movement in the first place. Covered in full in Part 7.

This part has nothing to do with networking yet — it gets a drivable car on a track, entirely locally. Skip ahead to Part 2 if you already have one.

1.1 Import the track

The track is a ready-made environment package, not something you build by hand in this tutorial.

1. Get Cartoon Race Track - Oval by RCC Design from the Unity Asset Store. Confirmed at time of writing: this is a free asset (Standard Unity Asset Store EULA, Extension Asset license) — add it to your account from the web store page, then in Unity's Package Manager, switch the source dropdown to My Assets, find it in the list, and click Import.
2. Drag the track prefab into your scene from wherever the package places it in the Project window (the exact folder name depends on the package version — look for an RCC or Cartoon Race Track folder). Position it at world origin (0, 0, 0).

3. Look at the track's own hierarchy before continuing to Part 1.4 — you'll need to know where its start/finish line actually is to place the local car and (in Part 7.3) the lap checkpoint trigger. Package contents vary by version; if the track ships its own spawn markers or a finish-line object, use those positions directly. If it doesn't, use the track's own visible start/finish line marker (every oval track package has one) as your reference point instead of a hardcoded coordinate — this tutorial can't give you an exact number for a package it doesn't ship.

1.2 Import the car

This tutorial's CarController.cs (Part 1.5) and CarCamera.cs (Part 1.6) — and CarColorManager.cs, attached later in Part 7 — are all built against one specific free car package. Nothing else in this doc tells you where to get it, so do this now, before Part 1.4 expects it to already be in the project.

1. Get ARCADE: FREE Racing Car by Mena from the Unity Asset Store. Confirmed at time of writing: this is a free asset (Standard Unity Asset Store EULA, Extension Asset license) — add it to your account from the web store page, then in Unity's Package Manager, switch the source dropdown to My Assets, find it in the list, and click Import.
2. In the Project window, find the package's main car prefab (exact folder name/prefab name may vary by version — look for a folder from the "ARCADE" or "Racing Car" package; there's normally just one obvious car prefab, not several to choose between). You'll drag this into your scene in Part 1.4 — nothing to do with it yet.

1.3 Import NetCrafter Relay

If you haven't already, import the NetCrafter Relay package into this project (Assets → Import Package → Custom Package…, or however you obtained it from the Asset Store). Confirm Assets/PivecLabs/NetCrafterRelay/ exists in the Project window afterward.

1.4 Place the car

1. Drag the ARCADE: FREE Racing Car prefab (Part 1.2) into the scene, at your track's start line. Right-click it → Prefab → Unpack Completely — see the warning in Part 7.2 for exactly why this matters before this tutorial is done with it; doing it now, before you've touched a single component, costs nothing and avoids the trap entirely.
2. Rename the root GameObject LocalCar.
3. Confirm the car's hierarchy has separate WheelCollider components (not just visual wheel meshes) — CarController (Part 1.5) expects to find WheelColliders to drive. If the imported prefab only has visual wheel meshes with no colliders, add four WheelCollider components as children of the car root, roughly at each wheel's position, matching the visual mesh radius.

1.5 Car Controller

Assets/PivecLabs/Examples/RacingDemo/Scripts/CarController.cs ships with the package — nothing to create here, this is what it contains:

using UnityEngine;
using UnityEngine.InputSystem;

public class CarController : MonoBehaviour
{
    [Header("Wheel Colliders")]
    public WheelCollider frontLeft;
    public WheelCollider frontRight;
    public WheelCollider rearLeft;
    public WheelCollider rearRight;

    [Header("Wheel Visuals (optional -- spin/steer animation only, no physics)")]
    public Transform frontLeftVisual;
    public Transform frontRightVisual;
    public Transform rearLeftVisual;
    public Transform rearRightVisual;

    [Header("Handling")]
    public float motorTorque = 1500f;
    public float maxSteerAngle = 30f;
    public float brakeTorque = 3000f;

    public bool HasAuthority { get; private set; }
    public int PlayerId { get; private set; }

    // ...full source in the shipped file -- Configure(), DriveLocal(), the remote-car
    // wheel-spin approximation, and ResetToSpawn() are covered below and in Part 7.
}

Setup steps:

1. Select LocalCar's root GameObject.
2. Add Component → search for Car Controller → add it.
3. Drag the four WheelCollider components into Front Left / Front Right / Rear Left / Rear Right.
4. If the car has separate visual wheel mesh Transforms (distinct from the WheelColliders themselves), drag those into the matching Wheel Visual fields — optional, only used to spin/steer the wheels visually; leave blank and the car still drives correctly, it just won't show wheel rotation.

CarController.Configure(playerId, hasAuthority) isn't called yet — that happens once login is wired up in Part 7.6. For now, in Play mode with no RacingDemoController in the scene at all, HasAuthority defaults to false and the car won't respond to input; that's expected at this stage, not a bug. If you want to test raw driving feel right now before wiring up anything else, temporarily call GetComponent<CarController>().Configure(0, true) from any script's Start(), test, then remove it — Part 7 replaces this properly.

1.6 Follow Camera

Assets/PivecLabs/Examples/RacingDemo/Scripts/CarCamera.cs ships with the package — nothing to create here, this is what it contains:

using UnityEngine;

public class CarCamera : MonoBehaviour
{
    public Transform target;
    public Vector3 offset = new(0f, 4f, -9f);
    public float smoothTime = 0.18f;

    // ...full source in the shipped file. SmoothDamp for position, Slerp for
    // rotation, so it feels weighty without being jittery.
}

1. Select your Main Camera.
2. Add Component → search for Car Camera → add it.
3. Target: assign LocalCar's Transform (for now — Part 7.6 reassigns this automatically once a real local car is spawned after login).
4. Leave Offset and Smooth Time at their defaults, or adjust to taste.

1.7 Test single-player driving

Temporarily call Configure(0, true) as described in 1.5, press Play, and confirm:

• W / Up arrow: accelerate
• S / Down arrow: brake/reverse
• A/D or Left/Right arrows: steer
• Space: handbrake

Adjust motorTorque (default 1500) and maxSteerAngle (default 30) on CarController if the handling feels too aggressive or too sluggish. Remove the temporary Configure() call before continuing — Part 7 wires this up for real.

Tools → Pivec Labs → NetCrafter Relay. Click + Create Definition, enter Racing, click Create.

Open the Gameplay Messages tab. Create the following.

3.1 Login — client tells the host its display name

Add one field: displayName (type string).

3.2 PlayerJoined — host announces a player (new or already-known) to someone

Add four fields: playerId (int), displayName (string), colorIndex (int), spawnIndex (int). colorIndex picks this player's car colour (Part 3's CarColorManager, 8 colours); spawnIndex picks which spawn point their car starts at — both computed host-side in Part 4, not sent by the joining client.

3.3 PlayerLeft — host announces a player disconnected

Add one field: playerId (int).

Only covers a joiner disconnecting — the host detects it and broadcasts this message to everyone else (Part 7.6). If the host itself disconnects, there's no one left to broadcast anything: each remaining joiner detects that independently, locally, without a PlayerLeft message at all — see the warning in Part 7.6.

3.4 RequestLapCompleted — a client's own car crossed the finish line

No fields — the host already knows who sent it (see Part 4).

3.5 LapCompleted — host's authoritative lap result, broadcast to everyone

Add four fields: playerId (int), lapNumber (int), lapTimeSeconds (float), totalTimeSeconds (float).

Open the Host Actions tab. Create two.

4.1 HandleLogin

Custom Host Code (roster-replay pattern shared with Co-op/Character's HandleLogin — see either tutorial for the full explanation of why the replay loop exists — plus Racing-specific colour/spawn assignment):

string displayName = trigger.displayName;
int colorIndex = senderId % 8;
int spawnIndex = senderId % 4;

foreach (var kv in RacingGameState.Players)
{
    var existing = new PlayerJoinedEvent {
        playerId = kv.Key, displayName = kv.Value.displayName,
        colorIndex = kv.Value.colorIndex, spawnIndex = kv.Value.spawnIndex
    };
    connection.SendToPeer(senderId, "PlayerJoined", existing.Serialize(), true);
}

RacingGameState.Players[senderId] = new RacingGameState.PlayerInfo {
    displayName = displayName, colorIndex = colorIndex, spawnIndex = spawnIndex
};
var joined = new PlayerJoinedEvent {
    playerId = senderId, displayName = displayName, colorIndex = colorIndex, spawnIndex = spawnIndex
};
connection.BroadcastToAll("PlayerJoined", joined.Serialize(), true);

// BroadcastToAll never loops back to the host's own incoming-message pipeline, so without
// this direct call the HOST never spawns a remote instance for a newly-joined player.
RacingDemoController.Instance?.HostRegisterPlayerLocally(senderId, displayName, colorIndex, spawnIndex);

colorIndex/spawnIndex are computed here, host-side, from senderId — deterministic and never trusted from the client. This mirrors the same "always use the authoritative sender id, never trust a client-sent one" rule this package has followed since its very first (SFS3-era) handler generation — the reasoning hasn't changed even though nothing about how it's enforced is SFS3-specific anymore.

4.2 HandleLapCompleted

Custom Host Code:

if (RacingGameState.TryRecordLap(senderId, out int lapNumber, out float lapTimeSeconds, out float totalTimeSeconds))
{
    var ev = new LapCompletedEvent {
        playerId = senderId, lapNumber = lapNumber,
        lapTimeSeconds = lapTimeSeconds, totalTimeSeconds = totalTimeSeconds
    };
    connection.BroadcastToAll("LapCompleted", ev.Serialize(), true);

    // Same reasoning as HandleLogin above -- the host never receives its own broadcast.
    RacingDemoController.Instance?.HostRegisterLapLocally(senderId, lapNumber, lapTimeSeconds, totalTimeSeconds);
}

Open Settings → Relay Settings and fill in your own coturn/rendezvous details (identical fields to every other tutorial — Relay Host, Relay Port 3478, Rendezvous URL, Credential Mode StaticSecret, TURN Username, Shared Secret). Click Save Settings.

Open Build Code, click Validate Definition, then Generate All Files. This writes to Definitions/Racing/Generated/:

• Client/LoginRequest.cs, Client/PlayerJoinedEvent.cs, Client/PlayerLeftEvent.cs, Client/RequestLapCompletedRequest.cs, Client/LapCompletedEvent.cs, Client/RelayConnectionManager.cs
• Host/HostActionRouter.cs
• Config/RelayConfig.json

Let Unity recompile and check the Console for CS0103: The name 'RacingGameState' does not exist or CS0103: The name 'RacingDemoController' does not exist — if you see either, double-check Part 6.1's file exists (below).

6.1 The shared game-state helper

Assets/PivecLabs/Examples/RacingDemo/Scripts/RacingGameState.cs ships with the package — nothing to create here, this is what it contains:

using System.Collections.Generic;
using UnityEngine;

public static class RacingGameState
{
    public class PlayerInfo
    {
        public string displayName;
        public int colorIndex;
        public int spawnIndex;
    }

    public static readonly Dictionary<int, PlayerInfo> Players = new();

    private const float MinLapSeconds = 5f;

    public static void Reset() { /* ...clears all tracked state, called from Awake() */ }

    public static bool TryRecordLap(int playerId, out int lapNumber, out float lapTimeSeconds, out float totalTimeSeconds)
    {
        // ...full source in the shipped file -- see Part 4.2's warning for what this
        // actually validates and why.
    }
}

Every rule below is a SyncRuleDefinition asset, created in Assets/PivecLabs/Examples/RacingDemo/ via right-click → Create → PivecLabs → NetCrafterRelay → Sync Rule.

These two rules directly move a remote car — Transform_Position/Transform_Rotation are applied immediately, with no interpolation (see the note on NetCrafterSyncBinding applying incoming values immediately in the Common Mistakes section of the Character tutorial — the same behavior applies here). Nothing else needs to be synced: the remote wheel-spin visual (Part 1.5) is entirely a local approximation from position delta between frames, not driven by any additional sync rule.

You'll assign these two rules to two NetCrafterSyncBinding components in Part 7 — one set on the local car, another matching set on the remote car prefab.

7.1 Add sync bindings to the local car

Select LocalCar's root GameObject (from Part 1.4) in your scene. Twice: Add Component → NetCrafter → Sync Binding, then immediately drag one of Part 6's two rule assets onto that specific binding's Rule field before adding the next one.

Leave every added Sync Binding component's checkbox unchecked — RacingDemoController (Part 7.6) enables all of them together, with the correct objectId/authority, right after login.

7.2 Build the remote car prefab

Step 1 — Duplicate, unpack, and check. Right-click LocalCar in the Hierarchy → Duplicate. Rename the duplicate RemoteCarPrefab. If you didn't already unpack the original car prefab back in Part 1.4, right-click RemoteCarPrefab → Prefab → Unpack Completely now, before touching any components.

Both NetCrafterSyncBinding components already exist on RemoteCarPrefab — they were duplicated along with everything else in Step 1, rules and all. Leave both of them unchecked, same as the local car — RacingDemoController configures and enables both the moment this prefab is spawned for an actual remote player (Part 7.6).

Step 2 — Disable local-only components. CarController stays on RemoteCarPrefab (it drives BOTH local and remote behavior internally, gated on HasAuthority — see Part 1.5's source), but nothing else needs to change here: Configure(playerId, false) (called at spawn time, Part 7.6) is what actually disables the Rigidbody's physics and the WheelColliders for a remote instance, not a manual component removal step. There's nothing else on the car that reads local input.

Step 3 — Save and remove from the Hierarchy. Drag RemoteCarPrefab from the Hierarchy into Assets/PivecLabs/Examples/RacingDemo/Prefabs/RemoteCarPrefab.prefab, then delete it from the Hierarchy — it's now a prefab asset, spawned at runtime instead of pre-placed.

7.3 Place the lap checkpoint

Assets/PivecLabs/Examples/RacingDemo/Scripts/LapCheckpoint.cs ships with the package — nothing to create here, this is what it contains:

using UnityEngine;

[RequireComponent(typeof(Collider))]
public class LapCheckpoint : MonoBehaviour
{
    private void OnTriggerEnter(Collider other)
    {
        var car = other.GetComponentInParent<CarController>();
        if (car == null || !car.HasAuthority) return;

        RacingDemoController.Instance?.RequestLapCompleted();
    }
}

1. At your track's start/finish line (the exact spot you noted in Part 1.1), Create Empty — name it LapCheckpoint.
2. Add Component → Box Collider. Size and position it to span the full width of the track at the finish line, thin along the direction of travel (a car should pass through it in one frame at racing speed, not sit inside it). Check Is Trigger.
3. Add Component → search for Lap Checkpoint → add it.

7.4 Build the UI

1. Canvas (Screen Space - Overlay) — name it UICanvas.
2. LoginPanel: TMP Text (Title, "Racing"), TMP Input Field (DisplayNameInput, placeholder "Enter your name..."), TMP Button (ContinueButton, "Continue").
3. LobbyPanel (unchecked by default): TMP Button (HostButton, "Host Game"), TMP Input Field (JoinCodeInput, placeholder "Join code..."), TMP Button (JoinButton, "Join Game"), TMP Text (JoinCodeDisplay, blank), TMP Text (StatusText, blank — shows connection errors/retry status; kept separate from JoinCodeDisplay so success and error text never share one field).
4. GameplayPanel (unchecked by default, Image alpha 0 — gameplay is the 3D track behind it): TMP Text (LeaderboardText, blank, anchored top-left) — sorted lap count / time, refreshed on every LapCompleted and player join/leave.

7.5 Create the RelayConnectionManager prefab and add the relay/event GameObjects

Open Scenes → Prefab Generator in the NetCrafter Relay window, confirm Racing is the selected schema, click Create RelayConnectionManager Prefab. This writes RelayConnectionManager.prefab to Definitions/Racing/Prefabs/ (a sibling of Generated/, not inside it — this prefab holds your actual relay settings once configured, so it's never touched by code regeneration) — do this before the Scene Assistant step below, so the connection-manager GameObject it adds to the scene comes from this prefab rather than a raw, disconnected GameObject. (Scene Assistant falls back to creating one either way if you skip this — nothing breaks — but building from the prefab is the intended path and keeps the scene object linked to a reusable asset.)

Open Scenes → Scene Assistant, confirm Racing is still the selected schema, confirm Add Event Dispatcher is checked, click Add to Existing Scene. This adds:

• RelayConnectionManager — an instance of the prefab you just created (Racing's generated connection type), added already disabled.
• HostActionRouter — Racing's generated host-side logic dispatcher.
• NetCrafterEventDispatcher.
• NetCrafterSyncManager — added automatically because Racing has SyncRuleDefinition assets (Part 6).

Then: Settings → Scene Events → Add Router to Scene — creates a SceneEventRouter GameObject listing PlayerJoined, PlayerLeft, and LapCompleted, each with an empty On Received slot (wired in 7.6).

7.6 Attach and wire RacingDemoController

Assets/PivecLabs/Examples/RacingDemo/Scripts/RacingDemoController.cs ships with the package — nothing to create here, this is what it contains:

using System.Collections;
using System.Collections.Generic;
using System.Text;
using UnityEngine;
using TMPro;
using PivecLabs.Generated.Racing;
using PivecLabs.NetCrafterRelay;

public class RacingDemoController : MonoBehaviour
{
    public static RacingDemoController Instance { get; private set; }

    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;

    public GameObject gameplayPanel;
    public TMP_Text leaderboardText;

    public GameObject localCar;
    public GameObject remoteCarPrefab;
    public Transform[] spawnPoints;
    public CarCamera carCamera;

    // ...full source in the shipped file. See Part 4 for HostRegisterPlayerLocally /
    // HostRegisterLapLocally (called directly from Custom Host Code, same "host never
    // receives its own broadcast" reasoning used throughout this package), and Part 7.3
    // for RequestLapCompleted (called by LapCheckpoint for the local player's own car).
}

Wire it up:

1. Create an empty GameObject named RacingDemoController, drag the script onto it.
2. Wire:

3. Wire the buttons and events:
   • ContinueButton → On Click () → RacingDemoController.OnLoginClicked()
   • HostButton → On Click () → RacingDemoController.OnHostClicked()
   • JoinButton → On Click () → RacingDemoController.OnJoinClicked()
   • SceneEventRouter's PlayerJoined binding → On Received → RacingDemoController.OnPlayerJoinedReceived()
   • SceneEventRouter's PlayerLeft binding → On Received → RacingDemoController.OnPlayerLeftBroadcastReceived()
   • SceneEventRouter's LapCompleted binding → On Received → RacingDemoController.OnLapCompletedReceived()

1. Run one copy — the host. Enter a name, Continue, Host Game. The Lobby panel stays up with your join code for a few seconds before moving on to the track automatically. Drive a lap — confirm your own car handles exactly as in Part 1.7, and the leaderboard shows your name at "Lap 0" until you cross LapCheckpoint, then "Lap 1" with a time.
2. Run 1–3 more copies — joiners. Enter a name, Continue, type in the join code, Join Game.
3. On every client, confirm:
   • Every other connected player's car appears, correctly coloured (colorIndex), at its own spawn point.
   • Driving on any one client's own car shows smooth movement — not just a moved position, actual wheel spin — on every other client's screen.
   • Crossing LapCheckpoint updates the leaderboard identically on every client, including the one that crossed it, at the same lap number and time.
   • The leaderboard re-sorts as lap counts/times change.
4. Quit one joiner. After a short delay (host-side peer-timeout detection), that car disappears from every remaining client and the leaderboard drops them.
5. With at least one joiner still connected, quit the host instead. After the same short delay, each remaining joiner's StatusText shows a "Host disconnected" message and the host's own now-frozen car disappears from their scene — independently on each joiner's client, since joiners never talk to each other directly (Part 7.6). There's no way to keep playing after this — no host migration — so this is as far as that session goes; host or join a fresh session to continue testing.

If hosting or joining fails outright — relay unreachable, join code not found — StatusText on the Lobby panel shows a plain-language message instead of a silent, unexplained Lobby screen (full detail still goes to the Console, unchanged). A join that's still retrying briefly shows "Retrying connection… (attempt N of 3)" first.

If cars move but the leaderboard never updates, check the Console for HandleLapCompleted logs on the host's copy — same troubleshooting instinct as every other tutorial's host-action debugging. If cars don't appear at all for a joiner, see Common Mistakes below before assuming the network itself is broken.

Tutorial by Pivec Labs — NetCrafter Relay