Getting Started

Import the NetCrafter Relay .unitypackage into your project via Assets → Import Package → Custom Package. After import the following structure will appear under Assets/PivecLabs/NetCrafterRelay/:

Documentation/      — these docs
Editor/             — editor window and code-generation tools
Examples/           — example schemas
Plugins/x86_64/     — NetCrafterRelayNative.dll (Windows only)
Scripts/            — ScriptableObject definitions + the pure C# relay client
Templates/          — built-in code templates

Unity menu → Tools → Pivec Labs → NetCrafter Relay

The window opens with four top-level sections in the toolbar: Definition, Code, Scenes, and Settings. Resize it to at least 1100 × 650 if controls appear clipped.

A Definition is a named collection of messages, events, models, and host actions. Each definition generates its own isolated set of C# files.

1. In the schema bar at the very top of the window, click Create Definition.
2. Name it (e.g. MyGame). A folder is created at Assets/PivecLabs/NetCrafterRelay/Definitions/MyGame/.

You can switch between definitions using the dropdown in the schema bar.

Click Settings in the top toolbar, then Relay Settings in the sidebar.

Leave all other fields at their defaults for now. Click Save Settings.

Models are plain data classes that can be nested inside messages and events. Create a PlayerState model:

1. Click Definition in the top toolbar, then Data Definitions in the sidebar.
2. Click Create Data Definition. Name it PlayerState.
3. Add fields:

Messages sent from a client to the host generate a {Name}Request class with a Send() method.

1. Click Definition → Messages in the sidebar.
2. Click Create Gameplay Message. Name it PlayerMove.
3. Set Direction to ClientToHost.
4. Set Host Handler Name to HandlePlayerMove (this must match a Host Action you add next).
5. Add fields:

Add a matching Host Action

1. Click Host Actions in the sidebar.
2. Click Create Host Action. Set Handler Name to HandlePlayerMove.

This logic runs only on whichever peer is currently hosting — there's no separate server process to deploy.

Events sent from the host to a client generate a {Name}Event class with Serialize()/Deserialize() methods.

1. Click Messages in the sidebar. Click Create Gameplay Message.
2. Name it PlayerStateUpdate. Set Direction to HostToClient.
3. Set Host Handler Name to HandlePlayerStateUpdate.
4. Add a field: name state, type string.

Add a matching Host Action with handler name HandlePlayerStateUpdate.

1. Click Code in the top toolbar, then Build Code in the sidebar.
2. Click Validate Definition first to confirm there are no errors.
3. Click Generate All Files.

Generated files appear in:

Assets/PivecLabs/NetCrafterRelay/Definitions/MyGame/Generated/Client/
Assets/PivecLabs/NetCrafterRelay/Definitions/MyGame/Generated/Host/

For the schema above, the generator produces:

The Scene Assistant automates the boilerplate of wiring a multiplayer scene.

Create the ConnectionManager prefab

1. Click Scenes in the top toolbar, then Prefab Generator in the sidebar.
2. Click Create ConnectionManager Prefab.

The generator finds the INetCrafterConnection-implementing type in your Generated/Client/ folder, wraps it in a prefab, and saves it to Prefabs/RelayConnectionManager.prefab — a sibling of Generated/, not inside it, since this prefab holds your actual relay host/rendezvous URL/TURN credentials once you configure it and is never touched by code regeneration. If the script is not found, generate client code first (step 8).

Create the scene

1. Click Scene Assistant in the sidebar.
2. Confirm the green banner shows that the prefab was found.
3. Optionally enable Add Event Dispatcher — this adds a NetCrafterEventDispatcher GameObject that lets any script subscribe to host events without touching the generated file (see step 13).
4. Click Create Multiplayer Scene.

The assistant creates a new scene containing:

• A Main Camera
• A ConnectionManager GameObject (instantiated from the prefab)
• An EventDispatcher GameObject (if the toggle was enabled)
• A NetworkManager empty GameObject (reserved for future use)

The scene is saved to Definitions/{Name}/GameScene.unity and opened in the editor. You can rename it using the Scene Name field before clicking Create.

Add to an existing scene

If you already have a scene open, click Add to Existing Scene instead. This adds only the ConnectionManager (and EventDispatcher) — it does not add a camera or NetworkManager. If a ConnectionManager is already present, a confirmation dialog appears before a second one is added.

If you prefer not to use the Scene Assistant:

1. Create an empty GameObject in your scene. Name it ConnectionManager.
2. Attach the generated RelayConnectionManager component to it.
3. Drag this schema's RelaySettings.asset (Definitions/{Name}/RelaySettings.asset) onto its Connection Settings field — the same asset the Relay Settings tab edits. (Prefab Generator does this automatically; it's only a manual step here because you're skipping the prefab.)

The ConnectionManager is a singleton with DontDestroyOnLoad. Call Connect() from a script when the game starts — with no join code set, it hosts a new session; call UpdateHost(joinCode) first to join an existing one:

void Start()
{
    // Hosting a new session:
    RelayConnectionManager.Instance.Connect();

    // Or, to join an existing session:
    // RelayConnectionManager.Instance.UpdateHost("GAME-4892");
    // RelayConnectionManager.Instance.Connect();
}

Populate the generated request class and call Send():

using PivecLabs.MyGame.Generated;

public class PlayerController : MonoBehaviour
{
    void Update()
    {
        if (Input.GetKeyDown(KeyCode.Space))
        {
            var request = new PlayerMoveRequest
            {
                playerId = RelayConnectionManager.Instance.LocalUserId,
                position = transform.position,
                speed    = 5.0f
            };
            request.Send(RelayConnectionManager.Instance, reliable: true);
        }
    }
}

Option A — Fill in the generated stub. Open RelayConnectionManager.cs and complete the stub method:

private void OnPlayerStateUpdate(PlayerStateUpdateEvent ev)
{
    // ev.state is a deserialized PlayerState object
    Debug.Log($"Player at {ev.state.position}, health {ev.state.health}");
}

Option B — Subscribe via EventDispatcher. From any MonoBehaviour in the scene, subscribe to the event by command name. This approach does not require editing the generated file:

private void OnEnable()
{
    NetCrafterEventDispatcher.Instance.Subscribe("PlayerStateUpdate", OnPlayerState);
}

private void OnDisable()
{
    NetCrafterEventDispatcher.Instance.Unsubscribe("PlayerStateUpdate", OnPlayerState);
}

private void OnPlayerState(object payload)
{
    var ev = (PlayerStateUpdateEvent)payload;
    Debug.Log($"Player at {ev.state.position}, health {ev.state.health}");
}

Both options can be used simultaneously — the dispatcher fires first, then the stub. See the API Reference for full EventDispatcher details.

• See the Manual for a complete reference of every tab and setting.
• See the API Reference for the full generated class API.
• See the Player Hosting Guide for how join codes work for players.