Template Guide

NetCrafter generates code by substituting placeholders in .tpl text files. Override any of the six built-in templates per-schema to fully customise your generated output.

6 templates Per-schema overrides

Never edit the built-in templates directly. The global templates live at Assets/PivecLabs/NetCrafter/Templates/ and are owned by the package. Use the Override System described below to customise output for a specific schema.

How the Override System Works#

When Use Custom Templates is enabled in Settings → Project Settings, the generator checks the schema's override folder before loading each template:

Path

Definitions/{SchemaName}/Templates/{TemplateName}.tpl

If the override file exists, it is used instead of the global template. If it does not exist, the global template is used as a fallback. You can override any subset of the six templates — you do not need to provide all six.

Tip

You can override any subset of the six templates. Schemas with different overrides can coexist in the same Unity project — each uses its own Definitions/{SchemaName}/Templates/ folder.

Setting Up Overrides#

Open Settings → Project Settings for your schema.
Enable Use Custom Templates.
Click Create Override Folder.

This creates Definitions/{SchemaName}/Templates/ and copies all six global templates into it. Each copied file receives a header comment:

Template header comment

// NetCrafter Template Override
// Schema: MyGame
// Template: RequestClass.tpl
// Modified: 2026-06-06
// This file overrides the global template for this schema only.
// Delete this file to revert to the global template.

The Template Files grid shows a green [✓] next to each template that exists in the override folder. Templates marked [ ] use the global fallback.

Reverting an Override#

Click Reset next to any template in the grid. This deletes the override file; the next generation will use the global template for that file. Alternatively, delete the file manually from Definitions/{SchemaName}/Templates/.

Template Reference

The six built-in templates and the placeholders each one recognises. Placeholder tokens are shown as {{TOKEN}} — each is replaced by the generator when files are produced.

RequestClass.tpl 1 file per ClientToServer message

Generates {MessageName}Request.cs — the class a game script instantiates and calls Send() on to send data to the server.

Placeholder	Replaced with
{{NAMESPACE}}	The C# namespace from Project Settings
{{REQUEST_NAME}}	The message name (e.g. `SendChat`)
{{FIELDS}}	Public field declarations, one per message field
{{WRITE_FIELDS}}	`obj.Put*(key, value)` statements for each field

EventClass.tpl 1 file per ServerToClient event

Generates {EventName}Event.cs — the class that the generated SmartFoxConnectionManager deserialises from SFS3 payloads and passes to your handlers.

Placeholder	Replaced with
{{NAMESPACE}}	The C# namespace
{{EVENT_NAME}}	The event name (e.g. `ChatBroadcast`)
{{FIELDS}}	Public field declarations
{{READ_FIELDS}}	`ev.field = obj.Get*(key)` statements

ModelClass.tpl 1 file per Data Definition

Generates {ModelName}.cs — a reusable data class with ToSFSObject() and FromSFSObject() helpers for embedding in requests and events.

Placeholder	Replaced with
{{NAMESPACE}}	The C# namespace
{{MODEL_NAME}}	The model name (e.g. `PlayerState`)
{{FIELDS}}	Public field declarations
{{WRITE_FIELDS}}	Serialisation statements for `ToSFSObject()`
{{READ_FIELDS}}	Deserialisation statements for `FromSFSObject()`

SFS3ConnectionManager.tpl 1 file per schema

Generates SmartFoxConnectionManager.cs — the MonoBehaviour that manages the SFS3 connection lifecycle, routes incoming events, and exposes SendExtensionRequest().

Placeholder	Replaced with
{{NAMESPACE}}	The C# namespace
{{HOST}}	Host value from SmartFox Settings
{{PORT}}	TCP port
{{HTTP_PORT}}	BlueBox HTTP port
{{HTTPS_PORT}}	BlueBox HTTPS port
{{USE_HTTP_TUNNEL}}	`true` or `false`
{{ENCRYPT}}	`true` or `false`
{{ZONE}}	Zone name
{{USE_WEBSOCKET}}	`true` or `false`
{{EVENT_SWITCH}}	One `case` block per ServerToClient event
{{EVENT_HANDLERS}}	One handler stub method per ServerToClient event

HandlerSwitch.tpl Injected into EVENT_SWITCH — 1 per ServerToClient event

Generates the case block injected into {{EVENT_SWITCH}}. Each case deserialises the payload, dispatches to NetCrafterEventDispatcher, and calls the private stub method.

Placeholder	Replaced with
{{EVENT_NAME}}	The event name

EventHandler.tpl Injected into EVENT_HANDLERS — 1 per ServerToClient event

Generates the private handler stub method injected into {{EVENT_HANDLERS}}. Override this stub in a subclass — or subscribe to NetCrafterEventDispatcher instead.

Placeholder	Replaced with
{{EVENT_NAME}}	The event name

Example: Add a Log Line to Every Request#

This example adds a Debug.Log call at the top of every request's Send() method — a useful pattern for debugging network traffic during development.

Enable Use Custom Templates and click Create Override Folder.
Open Definitions/{SchemaName}/Templates/RequestClass.tpl.
Find the Send method body and add one line before the SFSObject is created:

RequestClass.tpl · modified Send() method

        public void Send(SmartFox Sfs)
        {
            Debug.Log("[Net] Sending {{REQUEST_NAME}}");
            var obj = new SFSObject();
{{WRITE_FIELDS}}
            Sfs.Send(new ExtensionRequest("{{REQUEST_NAME}}", obj));
        }

Click Generate All Files. Every request class in the schema will now include the log line with the correct message name substituted in.

The placeholder {{REQUEST_NAME}} is substituted at generation time — so a schema with three messages (SendChat, PlayerMove, UseItem) produces three log lines: [Net] Sending SendChat, [Net] Sending PlayerMove, and [Net] Sending UseItem.

Placeholder Validation#

Each time you generate with Use Custom Templates on, NetCrafter checks every override template for required placeholders and logs a [NetCrafter] Warning in the Unity console for any that are missing.

Generation still proceeds, but the output will be malformed if a required placeholder is absent. The same check runs when you click Create Override Folder.

Best Practice

After editing an override template, run Validate Definition first to catch any schema errors, then Generate All Files to see the result. Check the Unity console for [NetCrafter] Warning messages about missing placeholders before committing the override.