Multiplayer Character Movement 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 Character schema is completely independent of the ChatRoom and Racing schemas. All generated code goes into the Character namespace and a separate CharacterZone.

Step 1Create the project

1. Open Unity Hub → New Project → 3D (URP) template
2. Name: NetCrafter_Character
3. Click Create

Step 2Install required packages

1. Go to Window → Package Manager
2. Click the dropdown top-left → Unity Registry

Install these two packages in order:

Cinemachine (required by Starter Assets):

• Search Cinemachine
• Select Cinemachine
• Click Install and wait

Starter Assets — Third Person Character Controller:

• Search Starter Assets
• Select Starter Assets — Third Person Character Controller
• Click Install and wait

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.

Step 3Import NetCrafter

1. In Unity: Assets → Import Package → Custom Package…
2. Select the NetCrafter.unitypackage file
3. Click Import All

After importing, confirm these assembly definition files exist in the Project window:

• Assets/PivecLabs/NetCrafter/Scripts/PivecLabs.NetCrafter.Runtime.asmdef
• Assets/PivecLabs/NetCrafter/Editor/PivecLabs.NetCrafter.Editor.asmdef

If either is missing, the package was not fully imported — repeat the import step.

Step 4Add the scripting define symbol

1. Go to Edit → Project Settings → Player
2. Find Scripting Define Symbols (under Other Settings)
3. Add: NETCRAFTER_CHARACTER_EXAMPLE
4. Click Apply

Zero compile errors should appear after this step. If you see errors about StarterAssets types not found, the Starter Assets package from Step 2 is not fully installed — reimport it before proceeding.

Note: SmartFoxConnectionManager references in the scripts are gated behind a second define (NETCRAFTER_CHARACTER_GENERATED) which you will add in Part B2 after generating the schema code. You do not need it yet — all scripts compile cleanly with only NETCRAFTER_CHARACTER_EXAMPLE defined.

A2.1Import the Starter Assets sample scene

After installing the Starter Assets package, the sample scene is available in the package folder:

1. In the Project window, navigate to Assets/StarterAssets/ThirdPersonController/Scenes/
2. You should see Playground.unity
3. Double-click to open it

A2.2Save a working copy

1. File → Save As
2. Navigate to Assets/Scenes/ (create this folder if it doesn't exist)
3. Save as: CharacterScene.unity
4. Work in CharacterScene from now on — do not modify the original Playground scene

A2.3Test single player

1. Press Play
2. Use WASD to move the character
3. Use the mouse to control the camera
4. Confirm walk, run, and jump animations play
5. Press Stop when done

Add CharacterColorManager to the PlayerArmature GameObject.

To verify it works: right-click the component → Apply Test Color (index 2 = green). The character should show a green tint.

In multiplayer (Part B), CharacterNetworkManager assigns colours automatically based on player ID — you do not need to call SetColor() manually.

Remove the component after testing — CharacterNetworkManager adds it at runtime.

Before adding multiplayer, verify the character moves and the colour system works.

1. Press Play
2. Use WASD to walk and Space to jump — the character should animate correctly
3. To test the colour system:
   1. Add CharacterColorManager to the PlayerArmature GameObject
   2. In the Inspector, set Test Color Index to 2 (green)
   3. Right-click the CharacterColorManager component → Apply Test Color
   4. Confirm the character turns green
   5. Right-click → Reset Color (White) to restore
   6. Remove the component when done testing — it will be added automatically by CharacterNetworkManager in Part B

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

SmartFox Settings tab

Project Settings tab

Messages to define

Define the following four messages in the Messages panel:

PlayerUpdate — ClientToServer

This message has 9 fields. Add them one by one:

PlayerJoined — ServerToClient

Fields:

PlayerLeft — ServerToClient

Fields:

PlayerStateUpdate — ServerToClient

Fields — relay of the PlayerUpdate fields, plus the sender's ID:

Server Actions

Create one server action:

No other server actions are needed. PlayerJoined and PlayerLeft are handled automatically by SFS3’s room lifecycle events in the generated extension.

B2.1Generate client code

Click Code → Build Code → Validate Definition. Once validation passes, click Generate All Files. NetCrafter writes to Assets/PivecLabs/NetCrafter/Definitions/Character/Generated/Client/.

Key generated files:

• PlayerUpdateMessage.cs — serialises position/rotation/animation state for sending
• PlayerJoinedEvent.cs — deserialises the join notification
• PlayerLeftEvent.cs — deserialises the leave notification
• PlayerStateUpdateEvent.cs — deserialises the 20 Hz state stream
• SmartFoxConnectionManager.cs — handles login, room join, extension responses

B2.2Enable the generated type guard

After generating, add the second scripting define so the #if NETCRAFTER_CHARACTER_GENERATED blocks in your scripts activate:

1. Go to Edit → Project Settings → Player → Other Settings
2. In Scripting Define Symbols, add: NETCRAFTER_CHARACTER_GENERATED
3. Click Apply

B2.3Generate and build server code

1. Click Code → Server Code → Generate Server Code
2. Click Build JAR (mvn package) — wait for BUILD SUCCESS
3. Click Deploy to SFS3

See the Server Extension Code appendix for the full CharacterExtension.java listing, including the userRooms disconnect fix.

Step 1 — Duplicate and rename

In the Hierarchy, right-click PlayerArmature → Duplicate. Name the duplicate RemoteCharacterPrefab.

Step 2 — Remove local-player components

With RemoteCharacterPrefab selected, right-click each component below and choose Remove Component:

• Third Person Controller (Script)
• Basic Rigid Body Push (Script)
• Starter Assets Inputs (Script)
• Player Input

Step 3 — Add network components

On RemoteCharacterPrefab, use Add Component to attach:

• RemoteCharacterController
• CharacterColorManager
• RemoteAnimationEventReceiver

Step 4 — Set up the name display

4.1 Create the Canvas

1. Right-click RemoteCharacterPrefab in the Hierarchy → UI → Canvas.
2. Name it NameCanvas.
3. On the Canvas component: set Render Mode to World Space.
4. On the NameCanvas Transform:
   • Position: X=0, Y=2.2, Z=0
   • Rotation: X=0, Y=0, Z=0
   • Scale: X=0.01, Y=0.01, Z=0.01
   ⚠

   The default Canvas scale is 100× too large for world space. Setting scale to 0.01 makes it the right size relative to the character.
5. On the Rect Transform: Width = 200, Height = 50.

4.2 Add the Text

1. Right-click NameCanvas → UI → Text - TextMeshPro.
2. Name it NameText.
3. If prompted to import TMP Essentials, click Import TMP Essentials.
4. On the Rect Transform: set Anchor to stretch/stretch (fill the canvas); set Left, Right, Top, Bottom offsets to 0.
5. On the TMP_Text component:
   • Text: (leave empty)
   • Alignment: Center Middle
   • Font Size: 36
   • Color: White
   • Enable Auto Size if text gets clipped

4.3 Add and wire up PlayerNameDisplay

1. Select the NameCanvas child of RemoteCharacterPrefab.
2. Click Add Component and add PlayerNameDisplay.
   ⚠

   PlayerNameDisplay must be on NameCanvas, not on the root RemoteCharacterPrefab. The component calls transform.LookAt() in LateUpdate to billboard the label toward the camera. When placed on the root, this rotates the entire character. On NameCanvas it only rotates the name label.
3. On the PlayerNameDisplay component on NameCanvas:
   • Name Text: drag the NameText GameObject (the TMP_Text child of NameCanvas) from the Hierarchy into this field.
   • Camera Transform: leave empty — CharacterNetworkManager assigns this at runtime from the main camera.

Step 5 — Save as a prefab

Drag RemoteCharacterPrefab from the Hierarchy into:
Assets/PivecLabs/Examples/Character/Prefabs/RemoteCharacterPrefab.prefab

Step 6 — Remove from the Hierarchy

Delete RemoteCharacterPrefab from the Hierarchy — it is now a prefab asset and no longer needs to live in the scene.

Step 7 — Assign the prefab to CharacterNetworkManager

This step is completed in Part B4 after CharacterNetworkManager is added to the scene. For now, save the prefab and continue.

Components on the final RemoteCharacterPrefab

RemoteCharacterController.cs drives every remote player's character. It disables the local-player components on Awake so physics and input do not interfere with the replicated state, then lerps position and rotation and drives the Animator each frame.

RemoteCharacterPrefab has a CharacterController component — leave it on the prefab. RemoteCharacterController automatically disables it at runtime when the remote character spawns. This allows direct transform lerping to work correctly. You do not need to manually disable anything on the prefab.

private void Awake()
{
    _animator = GetComponent<Animator>();
    _cc       = GetComponent<CharacterController>();

    var tpc = GetComponent<ThirdPersonController>();
    if (tpc != null) tpc.enabled = false;

    var inputs = GetComponent<StarterAssetsInputs>();
    if (inputs != null) inputs.enabled = false;

    var playerInput = GetComponent<UnityEngine.InputSystem.PlayerInput>();
    if (playerInput != null) playerInput.enabled = false;

    if (_cc != null)
    {
        var capsule = gameObject.AddComponent<CapsuleCollider>();
        capsule.center = _cc.center;
        capsule.radius = _cc.radius;
        capsule.height = _cc.height;
        _cc.enabled = false;
    }
}

private void Update()
{
    Vector3 currentPos = transform.position;
    float newX    = Mathf.Lerp(currentPos.x, networkTargetPosition.x, Time.deltaTime * positionLerpSpeed);
    float newZ    = Mathf.Lerp(currentPos.z, networkTargetPosition.z, Time.deltaTime * positionLerpSpeed);
    float newPosY = Mathf.MoveTowards(currentPos.y, networkTargetPosition.y, 15f * Time.deltaTime);
    transform.position = new Vector3(newX, newPosY, newZ);

    float newY = Mathf.LerpAngle(
        transform.eulerAngles.y, networkTargetRotY,
        Time.deltaTime * rotationLerpSpeed);
    transform.rotation = Quaternion.Euler(0f, newY, 0f);

    if (_animator != null)
    {
        _animator.SetFloat("Speed",       networkSpeed);
        _animator.SetFloat("MotionSpeed", networkMotionSpeed);

        if (networkStateHash != 0)
        {
            var current = _animator.GetCurrentAnimatorStateInfo(0);
            if (current.shortNameHash != networkStateHash)
                _animator.Play(networkStateHash, 0, networkStateTime);
        }
    }
}

RemoteCharacterPrefab already has RemoteCharacterController attached (added in Part B3). CharacterNetworkManager enables it at spawn time — you do not need to add it dynamically.

B4.1 — Create the NetworkManager

1. In the Hierarchy, right-click the scene name → Create Empty.
2. Name it NetworkManager.
3. Confirm its Transform Position is 0, 0, 0 (click ⋮ → Reset if not).
4. With NetworkManager selected, click Add Component, search for CharacterNetworkManager, and add it.
5. In the Remote Players section of the CharacterNetworkManager component, drag RemoteCharacterPrefab.prefab from:
   Assets/PivecLabs/Examples/Character/Prefabs/RemoteCharacterPrefab.prefab
   into the Remote Character Prefab field. Confirm the field shows RemoteCharacterPrefab (not None).

CharacterNetworkManager.cs is the top-level coordinator. It handles the connection lifecycle, spawns and removes remote characters, runs the 20 Hz send loop, and forwards typed events from the NetCrafter event router.

Key responsibilities

• Connect() — called by the login button; passes the player name to SmartFoxConnectionManager
• OnRoomJoined() — finds the local ThirdPersonController in the scene, starts the send loop
• SendPlayerUpdate() — runs at 20 Hz; reads position, rotation, and Animator params; sends via PlayerUpdateMessage
• OnPlayerJoined() / OnPlayerLeft() — spawn/destroy remote character GameObjects
• OnPlayerStateUpdate() — forwards state to the matching RemoteCharacterController

public void OnRoomJoined()
{
#if NETCRAFTER_CHARACTER_GENERATED
    int uid = SmartFoxConnectionManager.Instance?.LocalUserId ?? 0;
    _localPlayerId = uid >= 0 ? uid : 0;
#else
    _localPlayerId = 0;
#endif
    _localColorIndex = _localPlayerId % CharacterColorManager.PlayerColors.Length;

    _localCharacter = FindAnyObjectByType<ThirdPersonController>();
    if (_localCharacter == null)
    {
        Debug.LogError("[Character] No ThirdPersonController found. " +
                       "Place PlayerArmature in the scene before pressing Play.");
        return;
    }

    _localAnimator = _localCharacter.GetComponent<Animator>();

    var colorMgr = _localCharacter.GetComponent<CharacterColorManager>();
    if (colorMgr != null) colorMgr.SetColor(_localColorIndex);

    var nameBadge = _localCharacter.GetComponentInChildren<PlayerNameDisplay>(true);
    if (nameBadge != null) nameBadge.Hide(); // local player never sees own name tag

    _isConnected = true;
    uiManager?.ShowGamePanel();

    string localName = SmartFoxConnectionManager.Instance?.LocalUserName ?? "Player";
    uiManager?.AddPlayerToList(localName);

    StartCoroutine(SendUpdateLoop());
}

public void OnPlayerStateUpdate()
{
#if NETCRAFTER_CHARACTER_GENERATED
    var payload = NetCrafterSceneEventRouter.Instance?.GetLastPayload("PlayerStateUpdate");
    if (!(payload is PlayerStateUpdateEvent ev)) return;
    if (!_remoteChars.TryGetValue(ev.playerId, out var ctrl)) return;

    ctrl.SetNetworkState(
        new Vector3(ev.posX, ev.posY, ev.posZ),
        ev.rotY,
        ev.speed,
        ev.motionSpeed,
        ev.stateHash,
        ev.stateTime);
#endif
}

CharacterUIManager.cs manages two panels: a login screen before the player connects, and a game panel showing the connected-players list. It has no waiting room — players enter the game immediately on connect.

B6.1Create the Canvas

1. Right-click the Hierarchy → UI → Canvas — Render Mode: Screen Space - Overlay
2. Name it UICanvas

B6.2Create the Login Panel

1. Right-click UICanvas → UI → Panel — name it LoginPanel
2. Add a TMP Text child — title: Character Demo, font size 36, centre-aligned
3. Add a TMP InputField — name it PlayerNameInput, placeholder: Enter your name...
4. Add a TMP Button — name it ConnectButton, label: Connect
5. Add a TMP Text — name it StatusText, small font, for connection messages

B6.3Create the Game Panel

1. Right-click UICanvas → UI → Panel — name it GamePanel, set inactive in the Inspector
2. Resize to a small corner panel (e.g. top-right, 200×200 px)
3. Add a TMP Text child — name it PlayerListText, set alignment to top-left

B6.4Attach and wire CharacterUIManager

1. Create an empty GameObject named UIManager; attach CharacterUIManager
2. In the Inspector, wire all fields:
   • Login Panel → LoginPanel
   • Player Name Input → PlayerNameInput
   • Connect Button → ConnectButton
   • Status Text → StatusText
   • Game Panel → GamePanel
   • Player List Text → PlayerListText
3. Wire ConnectButton's On Click event → CharacterNetworkManager.Connect()

B7.1Add the ConnectionManager prefab

1. In the NetCrafter window, go to Scenes → Prefab Generator → Create ConnectionManager Prefab

The ConnectionManager is added to the scene automatically when you click Add to Existing Scene in the Scene Assistant tab (completed in B4.3). You do not need to drag it manually — if it is already in your Hierarchy, skip this step.

B7.2How connection events work

CharacterNetworkManager automatically subscribes to the RoomJoined event in Start() via NetCrafterEventDispatcher. No manual wiring is needed in the Inspector.

When the player logs in and joins the room:

1. SmartFoxConnectionManager fires OnRoomJoin
2. NetCrafterEventDispatcher dispatches the RoomJoined event
3. CharacterNetworkManager.OnRoomJoined() is called automatically
4. The local character is found and multiplayer begins

The only manual wiring needed is in the Scene Events tab (B7.1) for the three network events: PlayerJoined, PlayerLeft, PlayerStateUpdate.

B7.3Assign the remote character prefab

1. Select the NetworkManager GameObject (with CharacterNetworkManager attached)
2. Drag RemoteCharacterPrefab into the Remote Character Prefab slot
3. Drag UIManager into the Ui Manager slot (or leave empty — it auto-finds)

The NetCrafter event router dispatches server-to-client events as Unity Events. Wire the three character events:

1. In the NetCrafter window, go to Scenes → Scene Events → Add Router to Scene
2. The NetCrafterSceneEventRouter GameObject appears in the Hierarchy
3. For each event listed below, click + under On Received and wire it:

These events fire whenever the server pushes a matching extension response. The CharacterNetworkManager then calls NetCrafterSceneEventRouter.Instance.GetLastPayload() to retrieve the typed payload.

Click Code → Config Generator → Refresh Preview to see the generated zone XML. Click Generate CharacterZone.zone.xml, then click Deploy Config to SFS3.

Alternatively, deploy manually:

C:\Users\YourName\SmartFoxServer3\server\zones\CharacterZone.zone.xml

After deploying the config and JAR, restart SFS3. You should see in the server log:

{Character}: CharacterExtension initialized

B10.1Start SmartFoxServer 3

Run SmartFoxServer3.exe. Confirm CharacterExtension initialized appears in the server log before proceeding.

B10.2First player — Press Play in Unity

1. Enter a name in the Login Panel and click Connect
2. The Game Panel replaces the Login Panel; your name appears in the player list
3. Walk around with WASD, jump with Space — confirm animations play

B10.3Second player — open a second build or editor instance

1. Build a standalone (File → Build and Run) or open a second editor instance
2. Connect with a different name
3. Both players should now see each other's animated characters
4. The player list on the Game Panel updates in both instances
5. Close one instance — the other instance removes the character and updates the list

NetCrafter already generates a complete, working CharacterExtension.java and HandlePlayerUpdate.java — join/leave/disconnect tracking and the PlayerUpdate → PlayerStateUpdate broadcast are all produced automatically from the Response Event and Logic Type: BroadcastAll you set on the HandlePlayerUpdate server action in Part B1. There is nothing to hand-write or replace. The real generated files look like this:

public class CharacterExtension extends SFSExtension {

    private final Map<Integer, Room> userRooms = new ConcurrentHashMap<>();

    @Override
    public void init() {
        addRequestHandler("PlayerUpdate", com.piveclabs.character.handlers.HandlePlayerUpdate.class);
        addEventHandler(SFSEventType.USER_JOIN_ROOM,  this::onUserJoinRoom);
        addEventHandler(SFSEventType.USER_LEAVE_ROOM, this::onUserLeaveRoom);
        addEventHandler(SFSEventType.USER_DISCONNECT, this::onUserDisconnect);
        trace("CharacterExtension initialized");
    }

    public Room getRoomForUser(int userId) {
        return userRooms.get(userId);
    }

    // ── Join: track room, announce to existing players ──────────────────

    private void onUserJoinRoom(ISFSEvent event) {
        User user = (User) event.getParameter(SFSEventParam.USER);
        Room room = (Room) event.getParameter(SFSEventParam.ROOM);
        if (room == null || user == null) return;
        userRooms.put(user.getId(), room);

        ISFSObject response = SFSObject.newInstance();
        response.putInt("playerId",      user.getId());
        response.putString("playerName", user.getName());
        response.putInt("colorIndex",    user.getId() % 8);
        response.putInt("spawnIndex",    user.getId() % 4);

        List<User> others = new ArrayList<>(room.getUserManager().getAllUsers());
        others.remove(user);
        if (!others.isEmpty())
            send("PlayerJoined", response, others);

        // Tell the new joiner about everyone already in the room
        for (User existing : room.getUserManager().getAllUsers()) {
            if (existing.getId() == user.getId()) continue;
            ISFSObject existingData = SFSObject.newInstance();
            existingData.putInt("playerId",      existing.getId());
            existingData.putString("playerName", existing.getName());
            existingData.putInt("colorIndex",    existing.getId() % 8);
            existingData.putInt("spawnIndex",    existing.getId() % 4);
            send("PlayerJoined", existingData, user);
        }
    }

    // ── Leave / Disconnect: send PlayerLeft to the remaining players ────

    private void onUserLeaveRoom(ISFSEvent event) {
        User user = (User) event.getParameter(SFSEventParam.USER);
        Room room = (Room) event.getParameter(SFSEventParam.ROOM);
        if (room == null || user == null) return;
        userRooms.remove(user.getId());

        ISFSObject response = SFSObject.newInstance();
        response.putInt("playerId", user.getId());
        List<User> remaining = new ArrayList<>(room.getUserManager().getAllUsers());
        remaining.remove(user);
        if (!remaining.isEmpty())
            send("PlayerLeft", response, remaining);
    }

    private void onUserDisconnect(ISFSEvent event) {
        User user = (User) event.getParameter(SFSEventParam.USER);
        if (user == null) return;
        Room room = userRooms.remove(user.getId()); // see "Why userRooms?" above
        if (room == null) return;

        ISFSObject response = SFSObject.newInstance();
        response.putInt("playerId", user.getId());
        List<User> remaining = new ArrayList<>(room.getUserManager().getAllUsers());
        remaining.remove(user);
        if (!remaining.isEmpty())
            send("PlayerLeft", response, remaining);
    }

    // ── Custom game logic ─────────────────────────────────────────────────

    public void broadcastPlayerState(User sender, Room room, ISFSObject fields) {
        ISFSObject response = SFSObject.newInstance();
        response.putInt("playerId", sender.getId());
        response.putFloat("posX",        fields.getFloat("posX"));
        response.putFloat("posY",        fields.getFloat("posY"));
        response.putFloat("posZ",        fields.getFloat("posZ"));
        response.putFloat("rotY",        fields.getFloat("rotY"));
        response.putFloat("speed",       fields.getFloat("speed"));
        response.putFloat("motionSpeed", fields.getFloat("motionSpeed"));
        response.putInt("stateHash",     fields.getInt("stateHash"));
        response.putFloat("stateTime",   fields.getFloat("stateTime"));

        List<User> others = new ArrayList<>(room.getUserManager().getAllUsers());
        others.remove(sender);
        if (!others.isEmpty())
            send("PlayerStateUpdate", response, others);
    }
}

public class HandlePlayerUpdate extends BaseClientRequestHandler {

    @Override
    public void handleClientRequest(User sender, ISFSObject params, TransportType transport) {
        CharacterExtension ext = (CharacterExtension) getParentExtension();
        Room room = ext.getRoomForUser(sender.getId());
        if (room == null) return;

        ext.broadcastPlayerState(sender, room, params);
    }
}

Note colorIndex and spawnIndex are assigned server-side in onUserJoinRoom and sent only on PlayerJoined — they aren't part of PlayerStateUpdate, so broadcastPlayerState doesn't forward them.

You have a working multiplayer third-person game. Here are natural next features: