Serialization

Search…
Serialization
This page goes into depth about Serialization, for the basics see DataTypes.
Mirror creates Serialize and Deserialize functions for types using Weaver. Weaver edits dll after unity compiles them using Mono.Cecil. This allows mirror to have a lot of complex features like SyncVar, ClientRpc and Message Serialization without the user needed to manually set everything up.
Rules and tips
There are some rules and limits for what Weaver can do. Some features add complexity and are hard to maintain so have not been implemented. These features are not impossible to implement and could be added if there is a high demand for them.
You should be able to write Custom Read/Write functions for any type, and Weaver will use.
This means if there is a unsupported type like int[][] creating a custom Read/Write function will allow you to sync int[][] in SyncVar/ClientRpc/etc
If you have a type that has a field that is not able to be Serialize, you can mark that field with [System.NonSerialized] and weaver will ignore it
Unsupported Types
Some of these types are unsupported due to the complexity they would add, as mentioned above.
NOTE: Types in this list can have custom writers.
Jagged and Multidimensional array
Types that Inherit from UnityEngine.Component
UnityEngine.Object
UnityEngine.ScriptableObject
Generic Types, eg MyData
Custom Read/Write must declare T, eg MyData
Interfaces
Types that references themselves
Built-in Read Write Functions
Mirror provides some built-in Read/Write Functions. They can be found in NetworkReaderExtensions and NetworkWriterExtensions.
This is a Non-compete list of types that have built-in functions, check the classes above to see the full list.
Most C# primitive types​
Common Unity structs
Vector3
Quaternion
Rect
Ray
Guid
NetworkIdentity, GameObject, Transform
NetworkIdentity, GameObject, Transform
The netId of the Object is sent over the network, and the Object with the same netId is returned on the other side. If the netId is zero or an object is not found then null will be returned.
Generated Read Write Functions
Weaver will Generate Read Write functions for
Classes or Structs
Enums
Arrays
eg int[]
ArraySegments
eg ArraySegment
Lists
eg List
Classes and Structs
Weaver will Read/Write every public field in the type, unless the field is marked with [System.NonSerialized]. If there is an unsupported type in the class or struct Weaver will fail to make Read/Write functions for it.
NOTE: Weaver does not check properties
Enums
Weaver will use the underlying Type of an enum to Read and Write them. By default this is int.
For example Switch will use the byte Read/Write functions to be Serialized
1
public enum Switch : byte
2
{
3
    Left,
4
    Middle,
5
    Right,
6
}
Copied!
Collections
Weaver will Generate writes for the collections listed above. Weaver will use the elements Read/Write function. The element must have a Read/Write function so must be a supported type, or have a custom Read/Write function.
For example:
float[] is a supported type because Mirror has a built-in Read/Write function for float.
MyData[] is a supported type as Weaver is able to generate a Read/Write function for MyData
1
public struct MyData
2
{
3
    public int someValue;
4
    public float anotherValue;
5
}
Copied!
Adding Custom Read Write functions
Read Write functions are static methods in the form of:
1
public static void WriteMyType(this NetworkWriter writer, MyType value)
2
{
3
    // write MyType data here
4
}
5
​
6
public static MyType ReadMyType(this NetworkReader reader)
7
{
8
    // read MyType data here
9
}
Copied!
It is best practice to make Read/Write functions extension methods so they can be called like writer.WriteMyType(value).
It is a good idea to call them ReadMyType and WriteMyType so it is obvious what type they are for. However the name of the function doesn't matter, weaver should be able to find it no matter what it is called.
Properties Example
Weaver wont write properties, but a custom writer can be used to send them over the network.
This can be useful if you want to have private set for your properties
1
public struct MyData
2
{
3
    public int someValue { get; private set; }
4
    public float anotherValue { get; private set; }
5
​
6
    public MyData(int someValue, float anotherValue)
7
    {
8
        this.someValue = someValue;
9
        this.anotherValue = anotherValue;
10
    }
11
}
12
​
13
public static class CustomReadWriteFunctions 
14
{
15
    public static void WriteMyType(this NetworkWriter writer, MyData value)
16
    {
17
        writer.WriteInt32(value.someValue);
18
        writer.WriteSingle(value.anotherValue);
19
    }
20
​
21
    public static MyData ReadMyType(this NetworkReader reader)
22
    {
23
        return new MyData(reader.ReadInt32(), reader.ReadSingle());
24
    }
25
}
Copied!
Unsupported type Example
Rigidbody is an unsupported type because it inherits from Component. But a custom writer can be added so that it is synced using a NetworkIdentity if one is attached.
1
public struct MyCollision
2
{
3
    public Vector3 force;
4
    public Rigidbody rigidbody;
5
}
6
​
7
public static class CustomReadWriteFunctions
8
{
9
    public static void WriteMyCollision(this NetworkWriter writer, MyCollision value)
10
    {
11
        writer.WriteVector3(value.force);
12
​
13
        NetworkIdentity networkIdentity = value.rigidbody.GetComponent<NetworkIdentity>();
14
        writer.WriteNetworkIdentity(networkIdentity);
15
    }
16
​
17
    public static MyCollision ReadMyCollision(this NetworkReader reader)
18
    {
19
        Vector3 force = reader.ReadVector3();
20
​
21
        NetworkIdentity networkIdentity = reader.ReadNetworkIdentity<NetworkIdentity>();
22
        Rigidbody rigidBody = networkIdentity != null
23
            ? networkIdentity.GetComponent()
24
            : null;
25
​
26
        return new MyCollision
27
        {
28
            force = force,
29
            rigidbody = rigidBody,
30
        };
31
    }
32
}
Copied!
Above are functions for MyCollision, but instead you could add functions for Rigidbody and let weaver would generate a writer for MyCollision.
1
public static class CustomReadWriteFunctions
2
{
3
    public static void WriteRigidbody(this NetworkWriter writer, Rigidbody rigidbody)
4
    {
5
        NetworkIdentity networkIdentity = rigidbody.GetComponent<NetworkIdentity>();
6
        writer.WriteNetworkIdentity(networkIdentity);
7
    }
8
​
9
    public static Rigidbody ReadRigidbody(this NetworkReader reader)
10
    {
11
        NetworkIdentity networkIdentity = reader.ReadNetworkIdentity();
12
        Rigidbody rigidBody = networkIdentity != null
13
            ? networkIdentity.GetComponent<Rigidbody>()
14
            : null;
15
​
16
        return rigidBody;
17
    }
18
}
Copied!
Debugging
You can use tools like ILSpy and dnSpy to view the complied code after Weaver has altered it. This can help to understand and debug what Mirror and Weaver does.
Data types
Synchronization
Last modified 10mo ago
Copy link
Contents
Rules and tips
Unsupported Types
Built-in Read Write Functions
NetworkIdentity, GameObject, Transform
Generated Read Write Functions
Adding Custom Read Write functions
Debugging