NetCrafter Relay — Manual

Schema bar

The schema bar runs across the top of every section. It shows a dropdown of all discovered definitions (schemas found anywhere under Assets/PivecLabs/NetCrafterRelay/Definitions/). Selecting a definition switches the entire window to that definition's assets.

Click Create Definition when no definition exists or to add a new one.

Messages tab

Displays all GameplayMessageDefinition assets found in Definitions/{Name}/Messages/.

To create a message: click Create Gameplay Message.

Message fields

Field types

Arrays: any field type can be made an array. Edit the asset YAML directly and set isArray: 1. The generated C# field becomes List<T>, written as a count prefix followed by each element in order.

There are no per-field keys on the wire — fields are written in schema declaration order, since client and host logic are generated together from one schema in one pass.

Data Definitions tab

Displays all DataDefinition assets in Definitions/{Name}/DataDefinitions/.

A Data Definition defines a reusable data model. The generator produces a {Name}.cs class with serialisation helpers (WriteTo(RelayWriter) and ReadFrom(RelayReader)).

To create a model: click Create Data Definition. Set a Model Name and add fields exactly as you would for a message.

Host Actions tab

Displays all HostActionDefinition assets in Definitions/{Name}/HostActions/.

Host Actions serve two purposes:

1. They satisfy the validation check — every message's Host Handler Name must match at least one Host Action's Handler Name.
2. They drive HostActionRouter.cs generation — the logic that runs only on whichever peer is currently hosting.

There is no server to deploy: HostActionRouter.cs compiles straight into the same client build as everyone else.

Sync Rules tab

Displays all SyncRuleDefinition assets in Definitions/{Name}/SyncRules/.

Click Create Sync Rule to add a new rule to the list. Select a rule in the left panel to edit its details on the right.

Sync Targets

Sync Modes

Sync rules are stored in the schema and exported for validation. The runtime system is implemented via NetCrafterSyncManager and NetCrafterSyncBinding — see the Sync Rule Runtime section below.

Build Code tab

All generation paths run schema validation first. If validation fails the error window opens and generation is aborted.

Generated files land in:

Definitions/{Name}/Generated/Client/
Definitions/{Name}/Generated/Host/
Definitions/{Name}/Generated/Config/

Schema validation

The validator (NC_ValidateSchema) performs four checks in order:

1. Duplicate names — no two messages, events, or models may share a name; no message and model may share a name.
2. Invalid field types — all field types must be a supported primitive or a declared model name.
3. Missing handler references — every message and event must name a handler that exists in the Host Actions list.
4. Circular model references — model fields must not form a cycle (e.g. A references B which references A).

Errors are shown in a scrollable Validation Error Window. Fix all errors before generating.

Code Preview tab

Displays the generated files for the selected definition, split into three groups: Client, Host, Config.

Selecting a file displays it in the right panel with syntax highlighting (VS Code–style dark theme or a darker light theme, adapting to your editor skin).

Normal / Diff toggle: after you generate at least once, the toggle becomes active. Diff view compares the on-disk file against a snapshot captured immediately before the last generation run. Added lines have a green background; removed lines have a red background. The toggle is greyed out with a tooltip if no snapshot exists yet.

Action buttons (top of the file panel):

Config Generator tab

Generates RelayConfig.json from the current schema's Relay Settings asset — relay host/port, rendezvous URL, and credential mode. There is no zone/room/AOI concept here; every peer talks to the same fixed relay endpoint.

Relay Settings tab

Settings are stored in Definitions/{Name}/RelaySettings.asset — one asset per definition.

Relay

Login

Transport

Click Save Settings to persist changes. Click Reset to Defaults to restore the values shown above.

Project Settings tab

Settings are stored in Definitions/{Name}/ProjectSettings.asset.

Output Folders

Read-only display of the three output paths, all derived from the schema's definition folder. Cannot be changed manually.

Template Settings

When Use Custom Templates is on:

• The Override Folder path is shown (read-only, auto-computed).
• Create Override Folder copies all nine built-in templates into the override folder and prepends a header comment identifying them as overrides. The button is disabled once the folder exists.
• The Template Files grid shows each template with a green [✓] if an override exists or grey [ ] if the global fallback will be used.
• Reset next to each template deletes the override file, reverting that template to the global fallback.

See the Template Guide for full details.

Naming Conventions

Generation Behavior

Logging

Experimental Features

Prefab Generator tab

The Prefab Generator creates Unity prefabs for use in your multiplayer scene.

ConnectionManager Prefab

The Create ConnectionManager Prefab button packages whichever generated type implements INetCrafterConnection (normally RelayConnectionManager.cs) into a reusable prefab saved to:

Definitions/{Name}/Prefabs/ConnectionManager.prefab

Deliberately a sibling of Generated/, not inside it — this is a hand-configured runtime asset (your actual relay host, rendezvous URL, and TURN credentials once you set them in the Inspector), not codegen output, so it's never touched by Build Code's regeneration.

Requirements: client code must have been generated first (Build Code tab). If no INetCrafterConnection type is found in Generated/Client/, an error dialog explains what to do.

The panel shows the expected output path and whether the prefab already exists. The Scene Assistant tab reads this same path and prefers the prefab when setting up scenes. If the prefab is absent, the scene buttons fall back to creating a raw GameObject via reflection.

Coming Soon — Prefab Generator

The following sections are visible in the UI but greyed out.

Scene Assistant tab

The Scene Assistant scaffolds a Unity scene with all required multiplayer GameObjects.

Settings are stored in Definitions/{Name}/SceneAssistantSettings.asset — one asset per definition, created automatically when you open the tab.

ConnectionManager Prefab Status

A banner at the top of the tab shows whether a ConnectionManager.prefab exists. If it is missing, a warning prompts you to create it in the Prefab Generator tab first. Scene buttons work either way — the prefab is preferred, but a raw GameObject is added via reflection if the prefab does not yet exist.

Scene Setup

Event Dispatcher

The Add Event Dispatcher toggle controls whether a NetCrafterEventDispatcher GameObject is included when a scene is created or patched. See the Event Dispatcher section below for full details on the API.

Player Spawning

Spawn point list controls:

• [i] (x, y, z) Remove — one row per point. Remove deletes that entry and immediately renames any SpawnPoint_N children in the active scene to stay in sequence.
• + Add Spawn Point — appends a new point at (0, 0, 0).

Place Spawn Points in Scene — creates or updates a SpawnPoints parent GameObject in the active scene. Each child is named SpawnPoint_0, SpawnPoint_1, … and carries a NetCrafterSpawnPointGizmo that draws a green wire sphere with a Scene view label. Button is disabled with a tooltip when no spawn points are defined.

Place Player Prefab — instantiates the assigned player prefab at spawnPoints[0] (or Vector3.zero if no points are defined), registers the action with undo, and selects the new GameObject. Disabled when no prefab is assigned. A HelpBox below the button notes that spawn point 0 is always used and suggests using multiple points for team starts or respawn logic.

Additive Scenes

Each entry in the list has:

• A SceneAsset picker — the chosen scene's path is stored as a string in SceneAssistantSettings.asset so it survives builds.
• An Async toggle — when on, the scene is loaded with SceneManager.LoadSceneAsync; when off, with SceneManager.LoadScene (synchronous, blocking).
• A Remove button.

Generate Scene Loader — writes NetCrafterSceneLoader.cs to Generated/Client/ alongside the RelayConnectionManager. The file contains an IEnumerator Start() that loads each scene in list order. Re-generate any time the list changes; the file is overwritten.

Scene Events tab

Binds HostToClient network events to scene-level UnityEvent hooks without writing code.

Setup

1. The tab discovers all HostToClient GameplayMessageDefinition assets in the current schema and displays one binding entry per event.
2. Click Add Router to Scene to create a SceneEventRouter GameObject in the active scene. The tab header immediately changes to a green [✓] SceneEventRouter status with a Select button. A second click is disabled — only one router per scene.
3. Wire each event's On Received UnityEvent in the Inspector-style UI. Bindings are serialized into the scene and survive save/reopen.
4. The enabled toggle on each entry silences that binding at runtime without removing it.

How it works at runtime

NetCrafterSceneEventRouter subscribes to NetCrafterEventDispatcher in Start(). When an event fires, the router stores the payload in an internal dictionary and calls onReceived.Invoke(). To read the event payload in your handler:

var ev = (ChatBroadcastEvent)
    NetCrafterSceneEventRouter.Instance.GetLastPayload("ChatBroadcast");

A HelpBox below each event's UnityEvent shows the exact cast pattern for that event type.

Orphaned bindings

If an event is renamed or removed from the schema, its binding moves to an Orphaned Bindings section at the bottom of the tab with a warning and a Remove button.

NetCrafterEventDispatcher is a runtime MonoBehaviour that ships with NetCrafter Relay (Scripts/NetCrafterEventDispatcher.cs). It is not generated — it is a permanent part of the package available to any script in your project.

Why it exists

The generated RelayConnectionManager routes all incoming relay messages through a private dispatch switch. Traditionally, to intercept events you would either subclass the generated file or edit it directly — both approaches break on the next Generate run. NetCrafterEventDispatcher provides an alternative: a string-keyed publish–subscribe bus that any MonoBehaviour can subscribe to without touching the generated code.

Adding it to a scene

Enable Add Event Dispatcher in Scenes → Scene Assistant, then use Create Multiplayer Scene or Add to Existing Scene. The dispatcher is added as a separate EventDispatcher GameObject with DontDestroyOnLoad.

To add it manually: create a GameObject and attach NetCrafterEventDispatcher to it.

API

// Register a callback for a host event
NetCrafterEventDispatcher.Instance.Subscribe("ChatBroadcast", OnChatBroadcastReceived);

// Deregister — call this in OnDisable or OnDestroy
NetCrafterEventDispatcher.Instance.Unsubscribe("ChatBroadcast", OnChatBroadcastReceived);

The callback receives the already-deserialised typed event object as object. Cast it to the generated event class:

private void OnChatBroadcastReceived(object payload)
{
    var ev = (ChatBroadcastEvent)payload;
    chatWindow.AddMessage(ev.senderName, ev.message);
}

Command names match your schema event names exactly — schema event ChatBroadcast → command string "ChatBroadcast".

How the dispatcher integrates with generated code

Every switch case in the generated RelayConnectionManager.DispatchLocal calls Dispatch before the stub handler. Both always fire — the dispatcher fires first so subscribers receive the event, then the On{Event} stub runs so any direct override in a subclass also executes.

case "ChatBroadcast":
{
    var ev = ChatBroadcastEvent.Deserialize(payload);
    NetCrafterEventDispatcher.Instance?.Dispatch("ChatBroadcast", ev);
    OnChatBroadcast(ev);  // stub — override in a subclass if preferred
    break;
}

Exception isolation

Each subscriber callback is wrapped in an individual try/catch. One failing subscriber cannot block other subscribers from receiving the same event. The error is logged to the Unity console with the command name and full stack trace.

Lifetime and cleanup

NetCrafterEventDispatcher is a singleton with DontDestroyOnLoad. Always call Unsubscribe in OnDisable or OnDestroy — failing to do so leaves a dangling reference and the callback will continue to fire for the lifetime of the dispatcher.

The Sync Rule Runtime automatically synchronises component values between peers according to the rules defined in the Sync Rules tab. It ships as three permanent runtime MonoBehaviours in Scripts/ — nothing is generated per-schema.

Components

Setting up sync in a scene

1. Add NetCrafterSyncManager to a persistent GameObject in the scene (or enable Add Event Dispatcher in Scene Assistant and add it manually). It auto-detects the RelayConnectionManager at Start. If no connection is found, it logs a clear error and gates all send calls.
2. Add NetCrafterSyncBinding to each networked GameObject.
3. In the Inspector, assign:
   • Rule — drag a SyncRuleDefinition asset from Definitions/{Name}/SyncRules/.
   • Object Id — a unique integer identifying this object in the session. Assign from game logic (e.g. RelayConnectionManager.Instance.LocalUserId on connect for the local player).
   • Has Authority — check this for the local player. Leave unchecked for remote players.

Authority and object ID

Each networked GameObject has an objectId and an authority flag:

• hasAuthority = true (local player): The binding sends data unreliably every tick according to the sync mode. The host relays this to other peers via BroadcastAll.
• hasAuthority = false (remote players): The binding subscribes to incoming sync events via NetCrafterEventDispatcher and applies received values to its component.

objectId must be unique per session and agreed between sender and receiver. NetCrafter Relay does not assign or manage IDs — this is game-logic responsibility. RelayConnectionManager.Instance.LocalUserId is a natural choice for player objects.

Data flow

Outbound (local player → host):

NetCrafterSyncBinding.FixedUpdate  →  BuildPayload (RelayWriter → byte[])
  →  NetCrafterSyncManager.TrySendSync
    →  INetCrafterConnection.Send(cmd, payload, reliable: false)
      →  relay client sends the raw UDP envelope

Inbound (host → remote peer binding):

Relay envelope "__nc_sync_{RuleName}" arrives
  →  RelayConnectionManager default case
    →  NetCrafterEventDispatcher.Dispatch(cmd, (object)new RelayReader(payload))
      →  NetCrafterSyncManager callback (RelayReader payload)
        →  bindings[data.ReadInt32()].ApplyIncoming(data)
          →  transform.position = data.ReadVector3()

Wire format

All sync commands use the prefix __nc_sync_ followed by the rule name. The payload is a positional binary blob (no per-field keys):

Payload convention note

Sync callbacks receive a RelayReader as the object payload — not a typed event class — with the "id" field already consumed by NetCrafterSyncManager before the binding's ApplyIncoming is called. This is different from normal event callbacks (which receive a deserialised event object). See the comment in NetCrafterSyncManager.SubscribeToSyncRule and the default case in the generated RelayConnectionManager.

What is NOT handled

• Interpolation / smoothing: values are applied directly. Use Vector3.Lerp or a similar approach in game code if smoothing is needed.
• Ownership transfer: hasAuthority is set in the Inspector and does not change at runtime.
• Bandwidth budgeting: tick rate is controlled by Unity's FixedUpdate rate and the interval field.
• Duplicate suppression on sync messages: sync traffic is sent unreliably by design (no retry/dedupe) — only Reliable messages get the ACK+retry treatment.

Message size limits

This isn't a relay bug — it's an inherent limit of sending raw UDP through TURN with no application-level fragmentation. Payloads that push the underlying UDP datagram past the typical ~1500-byte Ethernet MTU get IP-fragmented, and fragmented UDP is unreliable across the public internet (many routers, NAT devices, and firewalls drop fragments). The Max Message Size setting (default 32768 bytes) only limits what's queued for send — it does not mean payloads that large will actually arrive.

If a message needs to carry more data than that (e.g. a large snapshot or asset chunk), split it into multiple smaller messages at the application level and reassemble on the receiving side. NetCrafter Relay does not do this chunking automatically today.

Disconnect detection

RelayConnectionManager sends a tiny liveness heartbeat to the connected peer every 5 seconds (piggybacked on the same timer that refreshes the TURN allocation/permission — see API Reference). If no traffic at all — heartbeat or any real message — has been received from a peer for about 15 seconds (3x the heartbeat interval), OnPeerDisconnected(peerId) fires exactly once for that peer. Confirmed live: after a force-killed peer, the surviving side fired the event in ~15 seconds, versus no signal at all previously.

What it does not do: reconnect automatically, retry the underlying TURN allocation on the disconnected peer's behalf, or fire more than once per peer. Treat it as "this peer is gone, handle it in your own game logic" (show a disconnect screen, end the session, etc.) — not as a building block for resilience against flaky connections.

The following features are visible in the UI but not yet fully implemented.