Network Object State IL Weaving

Overview

To maintain simplicity when writing networked code, Photon Fusion manages all the underlying interactions between Network Object properties and the internal buffer that is synchronized among peers. This is achieved by rewriting and including extra code directly in the IL code generated during the compilation process, a step referred to as IL Weaving.

The IL (Intermediate Language) weaving process involves modifying the compiled IL code of a program to inject additional functionality or behavior. In this context, the Fusion IL Weaver is responsible for enhancing Networked Properties within a Network Behaviour by adding networking handling code during compilation. This includes value compression/decompression, validation, and, more importantly, reading from/writing to the networked buffers.

The weaving process ensures that the networking logic is seamlessly integrated into the compiled code, enabling proper functionality of Networked Properties, which behave like normal properties but have their values synchronized.

Another role of Fusion IL Weaving is to parse/process all the RPC methods described in the project, making them function as intended by hooking into the invoke process to send/receive data between the calling end and the execution end.

Setup and Execution

Within the NetworkProjectConfig asset (which describes most settings for Photon Fusion), there is a section named Weaver Settings, containing the following settings:

• Assemblies to Weave: This is a list of all compilation assemblies that Fusion will look over for NetworkBehavior implementations to process all their Network Properties. This is useful to increase the post-compilation time by removing any assemblies that do not contain any NetworkBehavior.
• UseSerializableDictionary: Use Fusion.SerializableDictionary to store [Networked] dictionary properties' initial value. If unchecked, the weaver will emit System.Generic.Dictionary instead—a type that's not Unity-serializable, but custom serializers (e.g., Odin) may support it.
• NullChecksForNetworkedProperties: If set, the weaver will add a check to all [Networked] properties on each NetworkBehaviour to verify if the owning NetworkObject has been attached.
• CheckRpcAttributeUsage: If set, the weaver will check if the RpcAttribute is used in types that do not support it. This requires all types to be scanned and can increase weaving duration.
• CheckNetworkedPropertiesBeingEmpty: If set, the weaver will check if [Networked] properties' getters and setters are empty.

The IL Weaving process occurs under two main circumstances:

1. Automatic: After any changes in the project code are detected by Unity, it will trigger the weaving process.
2. Manual: In some rare circumstances, it might be necessary to run the Fusion Weaver manually. For such cases, there is a Tools/Fusion/Run Weaver menu item to trigger it.