API Reference — Generated Code

There are no per-field keys on the wire — RelayWriter/RelayReader are purely positional. See Scripts/Relay/RelayWriter.cs and RelayReader.cs.

Generated from ClientToHost (and ClientToHostBroadcast) messages.

Filename: {MessageName}Request.cs Class name: {MessageName}Request

Members

Example

Schema message PlayerMove with fields playerId: PlayerId, position: Vector3, speed: float generates:

// Usage
var req = new PlayerMoveRequest
{
    playerId = RelayConnectionManager.Instance.LocalUserId,
    position = transform.position,
    speed    = currentSpeed
};
req.Send(RelayConnectionManager.Instance);

The generated class:

public class PlayerMoveRequest
{
    public int     playerId;
    public Vector3 position;
    public float   speed;

    public byte[] Serialize()
    {
        var writer = new PivecLabs.NetCrafterRelay.RelayWriter();
        writer.WriteInt32(playerId);
        writer.WriteVector3(position);
        writer.WriteFloat(speed);
        return writer.ToArray();
    }

    public void Send(PivecLabs.NetCrafterRelay.INetCrafterConnection connection, bool reliable = true)
    {
        connection.Send("PlayerMove", Serialize(), reliable);
    }

    public static PlayerMoveRequest Deserialize(byte[] data)
    {
        var reader = new PivecLabs.NetCrafterRelay.RelayReader(data);
        var req = new PlayerMoveRequest();
        req.playerId = reader.ReadInt32();
        req.position = reader.ReadVector3();
        req.speed    = reader.ReadFloat();
        return req;
    }
}

Generated from HostToClient messages.

Filename: {EventName}Event.cs Class name: {EventName}Event

Members

Example

Schema event PlayerStateUpdate with a nested model field state: PlayerState generates:

// Usage — called automatically by RelayConnectionManager
private void OnPlayerStateUpdate(PlayerStateUpdateEvent ev)
{
    Debug.Log($"Health: {ev.state.health}, Position: {ev.state.position}");
}

The generated class:

public class PlayerStateUpdateEvent
{
    public PlayerState state;

    public byte[] Serialize()
    {
        var writer = new PivecLabs.NetCrafterRelay.RelayWriter();
        state?.WriteTo(writer);
        return writer.ToArray();
    }

    public static PlayerStateUpdateEvent Deserialize(byte[] data)
    {
        var reader = new PivecLabs.NetCrafterRelay.RelayReader(data);
        var ev = new PlayerStateUpdateEvent();
        ev.state = PlayerState.ReadFrom(reader);
        return ev;
    }
}

Generated from Data Definitions.

Filename: {ModelName}.cs Class name: {ModelName}

Members

Example

Data Definition PlayerState with fields position: Vector3, health: int, username: string, isAlive: bool generates:

// Embed in a request/event field
var state = new PlayerState
{
    position = transform.position,
    health   = currentHealth,
    username = playerName,
    isAlive  = true
};
ev.state = state;  // event field of type PlayerState

// Reading happens automatically inside the parent Request/Event's Deserialize() —
// you don't call ReadFrom directly unless you're hand-rolling custom (de)serialization.

Generated once per schema and placed in Generated/Client/RelayConnectionManager.cs.

Class: RelayConnectionManager : MonoBehaviour, INetCrafterConnection

Lifecycle

Public API (INetCrafterConnection)

Host-only API

Available only when IsHost is true — used by the generated HostActionRouter, not typically called directly from game code:

Events

Inspector fields

The generated manager has a single Inspector field, connectionSettings — a live reference to this schema's own RelaySettings asset (Definitions/{Name}/RelaySettings.asset), the same asset the Relay Settings tab edits. It is auto-wired whenever the prefab is (re)created via Prefab Generator — there is nothing to fill in by hand unless you built the GameObject yourself instead of using the tool.

Read the live values via the referenced asset directly, e.g. connectionSettings.relayHost, connectionSettings.rendezvousUrl, connectionSettings.credentialMode, connectionSettings.debugLogging — see RelaySettings.cs for the full field list.

Event handling

The generated manager routes every incoming relay message by command name. Each switch case deserialises the payload, forwards it to NetCrafterEventDispatcher (if present in the scene), then calls the private stub method:

private void DispatchLocal(string cmd, byte[] payload)
{
    switch (cmd)
    {
        case "PlayerStateUpdate":
        {
            var ev = PlayerStateUpdateEvent.Deserialize(payload);
            NetCrafterEventDispatcher.Instance?.Dispatch("PlayerStateUpdate", ev);
            OnPlayerStateUpdate(ev);
            break;
        }
        // ... one case per event in your schema
    }
}

Both the dispatcher call and the stub method always fire. This means you can handle events either by subscribing to NetCrafterEventDispatcher from any script, or by overriding the stub in a subclass — or both.

Each handler stub is generated as a private method. Fill them in to respond to host pushes:

private void OnPlayerStateUpdate(PlayerStateUpdateEvent ev)
{
    // Your game logic here
}

Editing generated code

The generated file is yours to edit — Generate All Files with Overwrite Existing Files enabled will replace it, so keep custom code in a subclass or copy the file out of the Generated/ folder.

Generated once per schema and placed in Generated/Host/HostActionRouter.cs. Executed only on the peer where connection.IsHost is true — every other peer's copy of this class simply never has Handle() invoked by its own RelayConnectionManager.

Class: HostActionRouter : MonoBehaviour

Members

Generated handler methods

One Handle_{HandlerName} method per Host Action:

private void Handle_HandlePlayerMove(int senderId, byte[] payload, RelayConnectionManager connection)
{
    var trigger = PlayerMoveRequest.Deserialize(payload);

    var response = new PlayerStateUpdateEvent();
    response.playerId = senderId; // auto-mapped if the response event has a matching "playerId" int field
    byte[] responseBytes = response.Serialize();

    connection.BroadcastToAll("PlayerStateUpdate", responseBytes, reliable: true);
}

Response fields are auto-populated when a same-named field exists on the trigger message, or when the field is named playerId (auto-mapped from senderId). Anything else is left at its C# default with a // TODO comment — fill it in, or set Custom Host Code on the Host Action for full control over the method body.

A runtime MonoBehaviour that ships with NetCrafter Relay in Scripts/NetCrafterEventDispatcher.cs. Not generated — it is a permanent part of the package.

Namespace: PivecLabs.NetCrafterRelay Class: NetCrafterEventDispatcher : MonoBehaviour

Summary

Provides a publish–subscribe bus for host events. Any script in your project can subscribe to a command name and receive the already-deserialised typed event object whenever that event arrives, without subclassing or modifying the generated RelayConnectionManager.

Members

Usage example

using PivecLabs.NetCrafterRelay;

public class ChatController : MonoBehaviour
{
    private void OnEnable()
    {
        NetCrafterEventDispatcher.Instance.Subscribe("ChatBroadcast", OnChat);
        NetCrafterEventDispatcher.Instance.Subscribe("PlayerStateUpdate", OnPlayerState);
    }

    private void OnDisable()
    {
        // Always unsubscribe — failing to do so leaves a dangling reference
        NetCrafterEventDispatcher.Instance.Unsubscribe("ChatBroadcast", OnChat);
        NetCrafterEventDispatcher.Instance.Unsubscribe("PlayerStateUpdate", OnPlayerState);
    }

    private void OnChat(object payload)
    {
        var ev = (ChatBroadcastEvent)payload;
        Debug.Log($"{ev.senderName}: {ev.message}");
    }

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

Notes

• Command names are the schema event names verbatim. Schema event ChatBroadcast → subscribe with "ChatBroadcast".
• Both paths always fire. Dispatch runs before the On{Event} stub in the generated ConnectionManager. Whether or not any subscriber is registered has no effect on the stub.
• Thread safety. Incoming relay datagrams arrive on a background thread inside StunTurnClient, but are only ever acted on in RelayConnectionManager.Update() (main thread) — Dispatch is not thread-safe and must only be called from the main thread, which is already guaranteed by this design.
• Scene Assistant. Enable Add Event Dispatcher in the Scene Assistant tab to have the GameObject added automatically when creating or patching a scene.

An interface that decouples the sync runtime (and your join-flow UI) from the generated namespace. Implemented by the generated RelayConnectionManager.

Namespace: PivecLabs.NetCrafterRelay File: Scripts/INetCrafterConnection.cs

Members

Why it exists

NetCrafterSyncManager needs to send data through the generated RelayConnectionManager, which lives in a user-defined namespace unknown to the runtime. INetCrafterConnection provides a namespace-agnostic contract. SyncManager finds the implementor at Start by scanning FindObjectsByType<MonoBehaviour>() — the same pattern PrefabGeneratorTab and SceneAssistantTab use in the editor to locate the connection-manager type by interface rather than a hardcoded class name.

Singleton MonoBehaviour that owns the object registry and routes sync traffic.

Namespace: PivecLabs.NetCrafterRelay File: Scripts/NetCrafterSyncManager.cs Class: NetCrafterSyncManager : MonoBehaviour

Members

Setup

Add NetCrafterSyncManager to a persistent GameObject in the scene (or enable Add Event Dispatcher in Scene Assistant and add it alongside NetCrafterEventDispatcher). Both NetCrafterSyncManager and NetCrafterEventDispatcher must be present in the scene for sync to function.

Graceful degradation

If no INetCrafterConnection is found during Start, a Debug.LogError is emitted and _ready is set to false. All subsequent TrySendSync calls return false immediately — there is no repeated NullReferenceException per FixedUpdate tick.

Per-object MonoBehaviour that drives the sync tick loop, builds outbound payloads, and applies inbound values.

Namespace: PivecLabs.NetCrafterRelay File: Scripts/NetCrafterSyncBinding.cs Class: NetCrafterSyncBinding : MonoBehaviour Menu path: Component > NetCrafter > Sync Binding

Inspector fields

Sync Modes

Sync Targets

Animator_Float and Animator_Bool read SyncRuleDefinition.animatorParameterName (set in the Sync Settings tab) to know which Animator Controller parameter to read/write — it must exactly match a parameter name defined on the character's Animator Controller. Read/written on the GetComponent<Animator>() found on the same GameObject as the binding.

⚠ Multiple bindings, one object. Since each SyncRuleDefinition syncs exactly one property, an object that needs several synced properties at once (e.g. a character's position, rotation, and four Animator parameters) carries several NetCrafterSyncBinding components side by side, one per rule, all sharing the same objectId/hasAuthority. NetCrafterSyncManager's registry is keyed by (ruleName, objectId), not objectId alone, specifically so this works — registering a second binding under the same objectId but a different rule doesn't overwrite the first. See the Character tutorial for a worked example with 6 bindings per character.

Usage example

// After connecting, assign objectId from the relay connection
private void OnConnected()
{
    int myId = RelayConnectionManager.Instance.LocalUserId;

    // Local player — authority binding
    var localPlayer = Instantiate(playerPrefab);
    var binding = localPlayer.GetComponent<NetCrafterSyncBinding>();
    binding.objectId     = myId;
    binding.hasAuthority = true;

    // Remote player — already in scene with hasAuthority = false and matching rule
    // objectId must be set before Start runs (i.e. before the object is active)
}

Notes

• NetCrafterSyncBinding.Start validates that a SyncRuleDefinition and a NetCrafterSyncManager are present. If either is missing, the component self-disables with a Debug.LogWarning.
• Remote bindings (non-authority) subscribe to their rule via NetCrafterSyncManager.SubscribeToSyncRule. This wires the NetCrafterEventDispatcher callback that routes the payload back to ApplyIncoming.
• ApplyIncoming is internal — only NetCrafterSyncManager calls it, and only after it has already consumed the leading id field from the shared RelayReader.

The pure C# STUN (RFC 5389) / TURN (RFC 5766) relay client underlying RelayConnectionManager. Not generated — a permanent part of the package runtime, usable directly if you need lower-level relay access.

Namespace: PivecLabs.NetCrafterRelay File: Scripts/Relay/StunTurnClient.cs

Members

Channel binding (RFC 5766 §11) is not implemented — every relayed packet currently goes through a Send/Data Indication pair, which has more per-packet overhead than a bound channel. This is a known follow-up, not required for the MVP's session sizes (2–4 players typical, up to 8–10).