NetCrafter Pro — 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/NetCrafter/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> and uses SFSArray on the wire.

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 (ToSFSObject() and FromSFSObject()).

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

Server Actions Tab

Displays all ServerActionDefinition assets in Definitions/{Name}/ServerActions/.

Server Actions serve two purposes: satisfying the validation check (every message's Server Handler Name must match at least one Server Action's Handler Name) and driving server-side Java code generation.

Sync Rules Tab

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

Click Create Sync Rule to add a new rule. 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.

Build Code Tab

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

Generated client files land in Definitions/{Name}/Generated/Client/.

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 Server 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, Server, Config.

Selecting a file displays it in the right panel with syntax highlighting.

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.

Server Code Tab

Generates a complete Java SFS3 extension project from your schema and provides one-click build and deploy.

Prerequisites

• Maven installed and on PATH
• JDK 21 required (not 17): SFS3 JARs are compiled with Java 21. JDK 17 will fail with "bad class file" errors even if the classpath appears correct. Recommended: Eclipse Adoptium JDK 21 — winget install EclipseAdoptium.Temurin.21.JDK
• SmartFoxServer 3 installed locally or accessible

Workflow

1. Set Extension Class and Extension Name in Settings → SmartFox Settings. Extension Class must be fully qualified (e.g. com.company.game.MyExtension).
2. Set SFS3 Lib Path and SFS3 Extensions Path in Settings → Project Settings (Server Build Settings section).
3. Click Generate Server Code — creates the Java project in Definitions/{Name}/Generated/Server/.
4. Click Build JAR (mvn package) — compiles the project and produces target/{ExtensionName}.jar.
5. Click Deploy to SFS3 — runs Maven and copies the JAR to your SFS3 extensions folder directly (no script file involved).
6. Start (or restart) your SFS3 server and check the server log for {ExtensionName}: {ExtensionClass} initialized.

Generated Files

Zone Configuration

To activate the extension in SFS3, update your zone XML (e.g. zones/Playground.zone.xml):

<extension>
  <name>MyGame</name>
  <type>JAVA</type>
  <file>com.mygame.MyGameExtension</file>
  <reloadMode>AUTO</reloadMode>
</extension>

Coming Soon — Server Code

Config Generator Tab

Generates a complete zone config XML ({zoneName}.zone.xml) for SmartFoxServer 3 from the current schema's SmartFox Settings asset.

The generated file includes TCP and WebSocket socket config, a Zone block, an MMORoom or plain Room element, and an Extension element (only when Extension Name and Extension Class are set).

SmartFox Settings Tab

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

Connection

Login

Extension

MMO

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 and the Template Files grid appears. See the Template Guide for full details.

Naming Conventions

Generation Behaviour

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 the generated SmartFoxConnectionManager.cs into a reusable prefab saved to Definitions/{Name}/Generated/Prefabs/ConnectionManager.prefab.

Requirements: client code must have been generated first (Build Code tab). The panel shows the expected output path and whether the prefab already exists.

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 — created automatically when you open the tab.

ConnectionManager Prefab Status

A banner at the top shows whether a ConnectionManager.prefab exists. 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 Toggle

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

Player Spawning

• Spawn point list controls — one row per point with a Remove button. Remove deletes that entry and 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 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.

Additive Scenes

Each entry in the list has a SceneAsset picker (path stored as a string in the asset), an Async toggle, and a Remove button.

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

MMO Map Bounds

The MMO fields displayed here are read from and written to SmartFoxSettings.asset — the same asset the Config Generator tab uses. Editing here is equivalent to editing in Settings → SmartFox Settings.

Visualise Bounds in Scene — creates or updates an MMOBounds GameObject with a NetCrafterMMOBoundsGizmo component. The gizmo holds a live reference to SmartFoxSettings, so the viewport rectangles update automatically when you change a bound value.

Scene Events Tab

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

Setup

1. The tab discovers all ServerToClient 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. 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 (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 SmartFoxConnectionManager routes all SFS3 extension responses through a private OnExtensionResponse 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 server 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
private void OnChatBroadcastReceived(object payload)
{
    var ev = (ChatBroadcastEvent)payload;
    chatWindow.AddMessage(ev.senderName, ev.message);
}

How the Dispatcher Integrates with Generated Code

Every switch case in the generated SmartFoxConnectionManager.OnExtensionResponse 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.FromSFSObject(data);
    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 clients 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. It auto-detects the SmartFoxConnectionManager at Start.
2. Add NetCrafterSyncBinding to each networked GameObject.
3. In the Inspector, assign: Rule (drag a SyncRuleDefinition asset), Object Id (a unique integer for this object in the session), and Has Authority (check for the local player, leave unchecked for remote players).

Authority and Object ID

• hasAuthority = true (local player): The binding sends data to the server on every tick according to the sync mode. The server is expected to relay this to other clients.
• 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 does not assign or manage IDs. The SFS3 User.Id is a natural choice for player objects.

Data Flow

Outbound (local player → server):

NetCrafterSyncBinding.FixedUpdate  →  BuildPayload (SFSObject)
  →  NetCrafterSyncManager.TrySendSync
    →  INetCrafterConnection.SendExtensionRequest
      →  sfs.Send(ExtensionRequest("__nc_sync_{RuleName}", payload))

Inbound (server → remote player binding):

SFS3 EXTENSION_RESPONSE "__nc_sync_{RuleName}"
  →  SmartFoxConnectionManager default case
    →  NetCrafterEventDispatcher.Dispatch(cmd, (object)data)
      →  NetCrafterSyncManager callback (ISFSObject payload)
        →  bindings[data.GetInt("id")].ApplyIncoming(data)
          →  transform.position = new Vector3(x, y, z)

Wire Format

All sync commands use the prefix __nc_sync_ followed by the rule name. The payload is an SFSObject with:

What Is NOT Handled

• Interpolation / smoothing: values are applied directly. Use Vector3.Lerp or similar 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.
• Server relay logic: NetCrafter does not generate or manage the server-side handler that relays sync packets to other players.

Features visible in the UI and their current implementation status.