MultiConnectMultiConnectDocs Website home
MultiConnectSDK › Developer Guide

7. Binary Serialization Setup

Every message your game sends is an ordinary C# class or struct. MultiConnectSDK turns it into compact binary with McBinarySerializer and rebuilds it on the other side. Any class or struct with public fields or properties can be sent, and needs no setup.

Each message also carries a short description of its type, so the two sides match members by name. The order in which you declare members does not matter. A client and a server built from different versions of a class still read each other's messages, so you can update your server before your players update their game (see Changing a Message Class).

Add [McSerializationObject] to each message class, as in Script 7.1. It is optional: marked classes are registered when MultiConnectSDK starts, so the first message of each type costs nothing extra. Classes and structs used inside a message, such as a list element, need no attribute.

Script 7.1: PlayerMoveData.cs

using System.Collections.Generic;
using MultiConnect.Serialization;

[McSerializationObject]
public class PlayerMoveData
{
    public string playerId;
    public float x;
    public float y;
    public float z;
    public float rotation;
}

[McSerializationObject]
public class GameStateUpdate
{
    public int score;
    public int health;
    public bool isAlive;
    public List<string> activeBuffs;
    public Dictionary<string, int> inventory;
}

What is sent: public fields, and properties that have both a getter and a setter. Private members, read-only fields and get-only properties are never sent. Unity's own structs (Vector3, Quaternion, Color and the rest) send their fields only.

Ignoring Fields

Use [McSerializationIgnore] on a public member that should not be sent, as in Script 7.2.

Script 7.2: PlayerData

[McSerializationObject]
public class PlayerData
{
    public string playerId;
    public string displayName;

    [McSerializationIgnore]
    public GameObject localReference; // Not sent
}

Choosing Members Explicitly (Advanced)

Use [McSerializationMember] when you want to list the members that are sent, as in Script 7.3. Once any member of a class has this attribute, only the members that have it are sent. Order sets where each member goes in the message.

Script 7.3: OrderedData

[McSerializationObject]
public class OrderedData
{
    [McSerializationMember(Order = 1)]
    public int id;

    [McSerializationMember(Order = 2)]
    public string name;

    [McSerializationMember(Order = 3)]
    public string optionalField;

    public int localOnly; // Not sent: other members have [McSerializationMember]
}

Same Class on Both Sides

A message is identified by its class's full name, namespace included. Declare each message class in the client and the server with the same name in the same namespace, as in Script 7.4. The simplest way is a shared folder or package that both projects use.

Script 7.4: Namespaces

// ✅ CORRECT - Same namespace on both projects
// Client Project:
namespace Game.Network.Messages { public class PlayerData { ... } }
// Server Project:
namespace Game.Network.Messages { public class PlayerData { ... } }

// ❌ WRONG - Different namespaces: the server cannot find the client's class
// Client Project:
namespace NetworkMessages { public class PlayerData { ... } }
// Server Project:
namespace Server.NetworkMessages { public class PlayerData { ... } }

Changing a Message Class

Players do not all update at once, so for a while a new server talks to clients that still have the old class, or the reverse. The two sides read each other's messages member by member, by name:

Change on one side What the other side gets
Member added Its value is ignored by the side that does not have it. The side that has it keeps the member's initial value when the message comes from the other build.
Member removed The side that still has it keeps the member's initial value.
Members reordered No effect.
Member renamed Add [McFormerName("oldName")] to the renamed member, as in Script 7.5, and its value keeps arriving in both directions. Without it, a rename is a removal plus an addition.
Number type widened (int → long, float → double, int → float) The value converts. A value that does not fit the narrower type (a large long read as int) keeps the initial value instead.
Enum value added The older build receives the number.
Member type changed to something unrelated (string → int) The member keeps its initial value, and MultiConnectSDK logs a warning once.

The first message of a changed class costs one extra round trip on each connection while the two sides exchange descriptions. Every later message of that class arrives at full speed.

Script 7.5: Renaming a member

[McSerializationObject]
public class ShotData
{
    [McFormerName("player")]   // was: public string player;
    public string shooter;
    public float power;
}

Supported Types

Type Notes
bool, byte, sbyte, short, ushort, int, uint, long, ulong, char, float, double, decimal Integers are variable-length: small values take one byte
string null arrives as null
DateTime, TimeSpan, Guid DateTime keeps its kind (UTC, local or unspecified)
Enums Any underlying type
Nullable<T> (int?, bool?, …)
T[], T[,], List<T>, HashSet<T> null stays null, including null elements. byte[], float[] and double[] are copied as one block
Dictionary<K,V>, ConcurrentDictionary<K,V> Any key type
Your own classes and structs, nested to any depth No attribute needed
Unity structs: Vector2, Vector3, Vector4, Quaternion, Color, … Fields only

Not supported:

Case What happens
A member declared as object, an interface or an abstract class The member is not sent, and a warning is logged once
A derived object in a member declared as its base class Only the base class's members are sent, and it arrives as the base class (a warning is logged once)
An object that refers back to itself, or nesting deeper than 64 levels Sending it throws McWireException

Faster Serialization on Android and iOS (IL2CPP)

Builds that use the IL2CPP scripting backend (Android, iOS, consoles, WebGL) cannot generate code while the game runs. The MultiConnectSDK package therefore includes Assets/Plugins/MultiConnectPlugin/DLL/MultiConnect.SourceGen.dll, a source generator that writes the code which reads and writes your message classes while Unity compiles your project. It needs no setup: it arrives with the label RoslynAnalyzer and with no platform ticked, so Unity runs it while compiling and never adds it to a build. Keep those settings if you move it. Without it every message still works, but on IL2CPP it is serialized with reflection, which is several times slower.

The generator covers every class marked [McSerializationObject] and every class, struct and enum those classes use.

Message Type Enum

Define all your network message types in a single location to avoid conflicts:

Script 7.6: Message types

// NetworkMessages.cs - Keep in a shared location accessible by both client and server
public enum GameMessage
{
    // Player actions
    PlayerMove = 1,
    PlayerShoot = 2,
    PlayerJump = 3,
    
    // Game state
    GameStart = 100,
    GameEnd = 101,
    ScoreUpdate = 102,
    
    // Room events
    PlayerJoined = 200,
    PlayerLeft = 201,
    
    // Chat
    ChatMessage = 300
}