Multiplayer Racing with NetCrafter

This tutorial assumes you have completed the NetCrafter Chat Tutorial. You should be familiar with:

• Creating a schema and adding messages in the NetCrafter window
• Running Generate Client Code and Generate Server Code
• Building and deploying a JAR to SmartFoxServer 3
• Deploying a zone config and restarting SFS3

The Racing schema is completely independent of the ChatRoom schema. All generated code goes into the Racing namespace and a separate RacingZone.

Create the script folder structure. All six Racing scripts live in Assets/PivecLabs/Examples/Racing/Scripts/ — inside the NetCrafter package for export, but outside the NetCrafter/ subfolder so they compile into Assembly-CSharp alongside the generated code.

Assets/PivecLabs/Examples/Racing/Scripts/
  TrackBuilder.cs         ← procedural track builder
  CarController.cs        ← physics car + remote lerp
  CarCamera.cs            ← smooth follow camera
  CarColorManager.cs      ← 8-colour player system
  RacingNetworkManager.cs ← all multiplayer logic
  RacingUIManager.cs      ← login / HUD panels

All six scripts are provided in this tutorial. Copy them into the folder and Unity will compile them automatically.

TextMeshPro: TextMeshPro is built into Unity 6. Before using any TMP components, import TMP Essentials once: Window → TextMeshPro → Import TMP Essentials. Click Import when prompted.

TrackBuilder.cs generates a rectangular oval track from Unity primitives — no external assets needed. Adjust parameters in the Inspector, then click ⋮ → Rebuild Track to regenerate.

Track layout

The track is a closed rectangular loop made from overlapping cube primitives:

Adding the track to your scene

1. In the Hierarchy, right-click the scene name (at the very top of the Hierarchy panel, e.g. RacingScene) → Create Empty. Name it Track.
   Important: right-click the scene name, not an existing GameObject. This ensures Track is created at world position 0,0,0.
2. With Track selected, check the Transform component — confirm Position is 0, 0, 0. If not, click ⋮ on the Transform component → Reset.
3. Add Component → search for TrackBuilder → add it.
4. Click ⋮ at the top right of the TrackBuilder component → Rebuild Track. The track appears immediately.

TrackBuilder only rebuilds when you explicitly click ⋮ → Rebuild Track. Changing parameter values in the Inspector does not auto-rebuild, so your scene references (including spawn point assignments) are preserved.

TrackBuilder parameters

// Assets/PivecLabs/Examples/Racing/Scripts/TrackBuilder.cs
// Full source — add to your project as-is.
// After attaching, click gear icon → "Rebuild Track" in the Inspector.

[ExecuteInEditMode]
public class TrackBuilder : MonoBehaviour
{
    public float trackWidth    = 20f;
    public float trackLength   = 150f;
    public float cornerRadius  = 30f;
    public float barrierHeight = 2f;
    public int   numSpawnPoints = 4;

    [ContextMenu("Rebuild Track")]
    public void Build() { /* ... builds track from primitives ... */ }
}

The SpawnPoints child contains SpawnPoint_0 through SpawnPoint_N transforms you'll assign to RacingNetworkManager in Part B.

CarController.cs drives the ARCADE car using WheelCollider physics for the local player, and lerp-smoothing for remote players (see Part B5 for the remote mode detail).

ARCADE car hierarchy

ArcadeRacingCar (root)       ← add CarController here
  Body
  Wheels
    FrontLeft                ← visual mesh only
    FrontRight
    RearLeft
    RearRight
  WC_FrontLeft               ← WheelCollider (you create these)
  WC_FrontRight
  WC_RearLeft
  WC_RearRight

The visual wheel transforms under Wheels/ are pure meshes. The WC_* objects are empty GameObjects with WheelCollider components. CarController syncs visual wheel world-pose to the colliders each frame.

Setup steps

1. Drag the ARCADE car prefab into the scene. Right-click → Prefab → Unpack Completely.
2. Select the car root GameObject.
3. Click Add Component and search for CarController.
4. That’s it — CarController automatically detects the existing WheelColliders and Rigidbody. No manual assignment needed.

CarController fields

using UnityEngine.InputSystem;

private void UpdateLocal()
{
    if (Keyboard.current == null) return;

    // Steering — A/D or Left/Right arrows
    float steerInput = 0f;
    if (Keyboard.current.aKey.isPressed || Keyboard.current.leftArrowKey.isPressed)
        steerInput = -1f;
    else if (Keyboard.current.dKey.isPressed || Keyboard.current.rightArrowKey.isPressed)
        steerInput = 1f;

    // Throttle — W/Up arrow; Brake/Reverse — S/Down arrow
    float throttleInput = 0f;
    if (Keyboard.current.wKey.isPressed || Keyboard.current.upArrowKey.isPressed)
        throttleInput = 1f;
    float brakeInput = 0f;
    if (Keyboard.current.sKey.isPressed || Keyboard.current.downArrowKey.isPressed)
        brakeInput = 1f;

    // Handbrake — Space
    bool handbrake = Keyboard.current.spaceKey.isPressed;

    // W = forward (+1), S = reverse (−1)
    float combinedThrottle = throttleInput - brakeInput;

    float speed = _rb != null ? _rb.linearVelocity.magnitude : 0f;
    float appliedTorque = speed < maxSpeed ? motorTorque * combinedThrottle : 0f;

    foreach (var w in driveWheels)
    {
        w.motorTorque = appliedTorque;
        w.brakeTorque = handbrake ? brakeTorque : 0f;
    }
    foreach (var w in steerWheels)
    {
        w.steerAngle  = maxSteerAngle * steerInput;
        w.brakeTorque = handbrake ? brakeTorque : 0f;
    }
}

CarCamera.cs provides a smooth third-person follow camera using SmoothDamp for position and Slerp for rotation. It feels weighty without being jittery.

1. Select the Main Camera.
2. Add Component → CarCamera.
3. Target: assign the car root's Transform.
4. Offset: (0, 4, -9) — 4 m above, 9 m behind.
5. Smooth Time: 0.18

private void LateUpdate()
{
    if (target == null) return;

    Vector3 desiredPos = target.position + target.rotation * offset;
    transform.position = Vector3.SmoothDamp(
        transform.position, desiredPos, ref _velocity, smoothTime);

    Quaternion desiredRot = Quaternion.LookRotation(
        target.position - transform.position);
    _currentRot = Quaternion.Slerp(
        _currentRot, desiredRot, Time.deltaTime / rotationSmoothTime);
    transform.rotation = _currentRot;
}

Set up a minimal test scene before adding multiplayer.

1. File → New Scene, save as Assets/Scenes/RacingScene.unity.
2. Add a Directional Light if not present.
3. Create a Track GameObject with TrackBuilder — click Rebuild Track.
4. Drag the unpacked ARCADE car to the scene. Position at SpawnPoint_0.
5. Set Main Camera → CarCamera.target = the car root's Transform.

Test controls

Press Play and drive around the track. If the car flips easily, lower motorTorque to 800 or increase Rigidbody mass. If steering is sluggish, increase maxSteerAngle to 35.

Open the NetCrafter window: Tools → Pivec Labs → NetCrafter Pro. Click New Schema and name it Racing.

SmartFox Settings tab

Extension Name and Extension Class are only required for server code generation (Part B2) and config generation (Part B3). The connection will work without them, but the server JAR and zone config won't be generated correctly.

Project Settings tab

Gameplay Messages tab — ClientToServer

Create one ClientToServer message named CarUpdate with these exact settings:

• Direction: ClientToServer
• Transport: ExtensionRequest
• Server Handler Name: HandleCarUpdate

This message has 9 fields. Add them one by one using the + Add Field button:

Gameplay Messages tab — ServerToClient

Create three ServerToClient events:

CarStateUpdate — Direction: ServerToClient, Transport: ExtensionEvent, Server Handler Name: (leave blank)

This event has 9 fields:

PlayerJoined — Direction: ServerToClient, Transport: ExtensionEvent, Server Handler Name: (leave blank)

This event has 4 fields:

PlayerLeft — Direction: ServerToClient, Transport: ExtensionEvent, Server Handler Name: (leave blank)

This event has 1 field:

Server Actions tab

Only one Server Action is needed — HandleCarUpdate:

This handles the incoming CarUpdate message from each client and broadcasts it as CarStateUpdate to all other players. PlayerJoined and PlayerLeft are handled automatically by SFS3's room lifecycle events — the generated Java extension will handle these in Part B2.

Sync Rules tab

Create two sync rules:

These rules document the intended sync cadence. The actual network sending is handled by RacingNetworkManager, which bundles position and rotation together in a single CarUpdate message every 0.05 seconds — more efficient than sending them as separate messages.

Generate client code

In the Code Generation tab, click Generate Client Code. Generated files:

Definitions/Racing/Generated/Client/
  SmartFoxConnectionManager.cs   ← connection + event dispatch
  CarUpdateRequest.cs         ← typed request sender
  CarStateUpdateEvent.cs      ← typed event receiver
  PlayerJoinedEvent.cs
  PlayerLeftEvent.cs

LocalUserId and LocalUserName

LocalUserId and LocalUserName are automatically included in the generated SmartFoxConnectionManager — no manual editing needed. RacingNetworkManager uses LocalUserId to identify the local player and assign colour/spawn index.

Generate server code

Click Generate Server Code. Generated files:

Definitions/Racing/Generated/Server/src/main/java/com/piveclabs/racing/
  RacingExtension.java
  handlers/
    HandleCarUpdate.java   ← reads position, broadcasts CarStateUpdate

Join/leave handling — auto-generated

The generated RacingExtension.java automatically handles all room lifecycle events — no manual editing needed:

• Player join: sends PlayerJoined to all existing players, and sends a PlayerJoined for each existing player to the joining user
• Player leave: sends PlayerLeft to all remaining players
• Player disconnect: sends PlayerLeft to all remaining players in the disconnected user's last room

Build and deploy the JAR

Click Deploy to SFS3 in the NetCrafter window → Code → Server Code tab.

This builds RacingExtension.jar and copies it to SmartFoxServer3/server/extensions/Racing/.

CarColorManager.cs applies a player colour to all body renderers on a car. Renderers whose gameObject.name contains "wheel" are skipped.

public class CarColorManager : MonoBehaviour
{
    public static readonly Color[] PlayerColors = new Color[]
    {
        Color.red,
        Color.blue,
        Color.green,
        Color.yellow,
        new Color(1f, 0.5f, 0f),  // orange
        Color.magenta,
        Color.cyan,
        Color.white,
    };

    public void SetColor(int colorIndex)
    {
        Color c = PlayerColors[colorIndex % PlayerColors.Length];
        foreach (var r in GetComponentsInChildren<Renderer>())
        {
            if (r.gameObject.name.ToLower().Contains("wheel")) continue;
            r.material.color = c;
        }
    }
}

colorIndex is assigned by the server as playerId % 8. Add CarColorManager to the car prefab so both local and remote cars can be coloured at spawn time.

B4.1 — Create ConnectionManager Prefab

1. Open the NetCrafter window → Scenes tab → Prefab Generator.
2. Click Create ConnectionManager Prefab.
3. Confirm the prefab was created at:
   Definitions/Racing/Generated/Prefabs/ConnectionManager.prefab

B4.2 — Create Multiplayer Scene

1. Open the NetCrafter window → Scenes tab → Scene Assistant.
2. Confirm that the ConnectionManager prefab is detected.
3. Ensure the EventDispatcher toggle is checked.
4. Click Create Multiplayer Scene and name it RacingScene.
   If your scene is already set up, click Add to Existing Scene instead.

The Scene Assistant adds the following GameObjects:

• ConnectionManager (from generated prefab)
• NetCrafterEventDispatcher
• NetworkManager (empty GameObject — configured in B4.5)
• Main Camera
• SpawnPoints

B4.3 — Verify Scene Hierarchy

After Scene Assistant completes, your Hierarchy should contain:

• ConnectionManager
• NetCrafterEventDispatcher
• NetworkManager (empty — RacingNetworkManager component added in B4.5)
• SpawnPoints with children SpawnPoint_0 through SpawnPoint_3
• Track (from Part A)
• Car (car prefab — assigned in B4.5)
• Main Camera

B4.4 — Wire Scene Events

Open the NetCrafter window → Scene Events tab for the Racing schema. Wire these three events:

The generated SmartFoxConnectionManager routes each incoming SFS3 extension event to the wired Unity method. Inside each method, the event payload is read via NetCrafterSceneEventRouter.Instance.GetLastPayload(eventName).

B4.5 — Add RacingNetworkManager

RacingNetworkManager.cs is the hub for all multiplayer logic. It:

• Finds the existing scene car (placed in Part A) and uses it as the local player car
• Spawns remote cars from Car Prefab on PlayerJoined
• Destroys remote cars on PlayerLeft
• Updates remote car target transforms on CarStateUpdate
• Sends CarUpdate at 20 Hz via SendExtensionRequest

Create a Car Prefab from your scene car

1. In the Hierarchy, select your Car GameObject.
2. Drag it into the Project window under Assets/PivecLabs/Examples/Racing/Prefabs/ (create the folder if needed).
3. Name the prefab CarPrefab.
4. The original car remains in the scene — Unity creates the prefab as a copy. Do not remove the scene car.

Add RacingNetworkManager to the scene

1. Select the NetworkManager GameObject created in B4.2.
2. Add Component → RacingNetworkManager.
3. Car Prefab: assign the CarPrefab you just created. This is used for remote players only — the scene car is used for the local player.
4. Spawn Points: drag in the SpawnPoint_0 through SpawnPoint_3 transforms from the TrackBuilder's SpawnPoints child.

After adding RacingNetworkManager to the scene, drag the SpawnPoint_0 through SpawnPoint_3 GameObjects from the Hierarchy into the Spawn Points array in the Inspector. These references are saved with the scene — you only need to assign them once.

Car prefab checklist

• ✅ CarController — all wheel references assigned, isLocalPlayer starts as true (set to false at runtime for remote cars)
• ✅ CarColorManager — no config needed
• ✅ Rigidbody — Mass: 1200
• ✅ Four WheelCollider children configured

Save as Assets/PivecLabs/Examples/Racing/Prefabs/CarPrefab.prefab.

// Scene Event callbacks — wired in the NetCrafter Scene Events tab
// Typed events are available after Generate Client Code + NETCRAFTER_RACING_GENERATED.
public void OnPlayerJoined()
{
#if NETCRAFTER_RACING_GENERATED
    var payload = NetCrafterSceneEventRouter.Instance?
        .GetLastPayload("PlayerJoined");
    if (!(payload is PlayerJoinedEvent ev)) return;

    int localId = SmartFoxConnectionManager.Instance?.LocalUserId ?? -1;
    if (ev.playerId == localId) return;           // ignore echo of own join
    if (_remoteCars.ContainsKey(ev.playerId)) return;  // duplicate guard

    SpawnRemoteCar(ev.playerId, ev.playerName, ev.colorIndex, ev.spawnIndex);
    FindAnyObjectByType<RacingUIManager>()?.AddPlayerToList(ev.playerName);
#endif
}

public void OnPlayerLeft()
{
#if NETCRAFTER_RACING_GENERATED
    var payload = NetCrafterSceneEventRouter.Instance?
        .GetLastPayload("PlayerLeft");
    if (!(payload is PlayerLeftEvent ev)) return;

    string name = _remotePlayerNames.TryGetValue(ev.playerId, out var n) ? n : "";
    RemoveRemoteCar(ev.playerId);
    if (!string.IsNullOrEmpty(name))
        FindAnyObjectByType<RacingUIManager>()?.RemovePlayerFromList(name);
#endif
}

public void OnCarStateUpdate()
{
#if NETCRAFTER_RACING_GENERATED
    var payload = NetCrafterSceneEventRouter.Instance?
        .GetLastPayload("CarStateUpdate");
    if (!(payload is CarStateUpdateEvent ev)) return;

    if (ev.playerId == _localPlayerId) return;

    UpdateRemoteCar(
        ev.playerId,
        new Vector3(ev.posX, ev.posY, ev.posZ),
        new Quaternion(ev.rotX, ev.rotY, ev.rotZ, ev.rotW),
        ev.speed);
#endif
}

When CarController.isLocalPlayer = false:

• The Rigidbody is set to kinematic — no local physics simulation
• All WheelCollider components are disabled
• Each Update() lerps position and rotation toward the latest network values
• Visual wheels are animated from networkSpeed (spin only — steering angle isn't part of CarStateUpdate, so remote front wheels don't visually turn)

private void UpdateRemote()
{
    transform.position = Vector3.Lerp(
        transform.position,
        networkTargetPosition,
        Time.deltaTime * 10f);

    transform.rotation = Quaternion.Slerp(
        transform.rotation,
        networkTargetRotation,
        Time.deltaTime * 10f);

    // Accumulate wheel spin angle from received speed
    _wheelSpinAngle += networkSpeed * Time.deltaTime * (360f / (2f * Mathf.PI * 0.35f));
}

A lerp factor of 10 means the car visually reaches its target within ~100 ms. At 20 updates per second, remote cars look smooth even on a typical LAN with <50 ms ping.

The UI has three panels on a single Canvas. Only one panel is visible at a time.

Create the Canvas and panels

1. GameObject → UI → Canvas. Set Render Mode to Screen Space — Overlay.
2. Inside the Canvas, create three empty child GameObjects: LoginPanel, WaitingPanel, RacePanel.

LoginPanel layout

WaitingPanel layout

RacePanel layout

Wire up RacingUIManager

1. Create an empty GameObject, name it UIManager.
2. Add Component → RacingUIManager.
3. Assign all panel GameObjects and UI element references in the Inspector.
4. Set LoginButton.onClick → RacingUIManager.OnLoginClicked.
5. Set StartRaceButton.onClick → RacingUIManager.OnStartRaceClicked.

Open the NetCrafter window → Scene Events tab for the Racing schema. Wire these three events:

The generated SmartFoxConnectionManager routes each incoming SFS3 extension event to the wired Unity method. Inside each method, the event payload is read via NetCrafterSceneEventRouter.Instance.GetLastPayload(eventName).

The zone file RacingZone.zone.xml must be in SmartFoxServer3/server/zones/. If you followed this tutorial, it was created automatically. The key values:

<zone>
  <name>RacingZone</name>
  <allowGuestUsers>true</allowGuestUsers>
  <guestUserNamePrefix>Guest#</guestUserNamePrefix>
  <maxUsers>100</maxUsers>
  <wordsFilter active="false"/>
  <floodFilter active="false"/>
  <rooms>
    <room>
      <name>GameRoom</name>
      <maxUsers>16</maxUsers>
      <isGame>false</isGame>
      <!-- ... full room structure with mmoSettings, roomVariables stubs ... -->
    </room>
  </rooms>
  <privilegeManager active="false"/>
  <extension>
    <name>Racing</name>
    <type>JAVA</type>
    <file>com.piveclabs.racing.RacingExtension</file>
    <propertiesFile></propertiesFile>
    <reloadMode>AUTO</reloadMode>
  </extension>
  <buddyList active="false"/>
  <databaseManager active="false"/>
  <udpSettings>
    <keepAlive>true</keepAlive>
    <rdpQualitySetting>BEST_EFFORT</rdpQualitySetting>
    <rdpReliableChannelType>2</rdpReliableChannelType>
  </udpSettings>
</zone>

1. Start SFS3

Launch sfs3-standalone.exe. Wait for the console to show the extension loaded. In AdminTool, Zones → RacingZone → Extensions should show Racing in green.

2. Player 1 (Unity Editor)

1. Press Play.
2. The LoginPanel appears. Enter a name (e.g., Driver1) and click Login.
3. The WaitingPanel appears. "Waiting for players..."

3. Player 2 (Build or second instance)

Option A — File → Build and Run a standalone build, then run the .exe alongside Unity.

Option B — run a second Unity instance from the same project on the same machine.

1. Enter a different name (e.g., Driver2) and click Login.
2. Both WaitingPanels now show Start Race.

4. Expected results

Debugging tips

• Car doesn't appear: Confirm PlayerJoined is wired in Scene Events and NetworkManager is active in the scene hierarchy.
• Remote car teleports: The lerp factor is applied per-frame — ensure Time.deltaTime is being used (it is in the provided code).
• Build failed: Check the Tool Detection panel in the Server Code tab — it shows the Maven and JDK paths that will be used, detected live each time the tab is drawn.
• AdminTool shows extension in red: Check SFS3 console for Java stack trace — usually a missing import or wrong FQN in the zone XML.

The multiplayer foundation is in place. Here are natural next features: