Merge develop-2.0.0 into fix/null-reference-exceptions

Author: netcode-ci-service

com.unity.netcode.gameobjects/Documentation~/TableOfContents.md

@@ -70,15 +70,17 @@
     * [Network update loop reference](advanced-topics/network-update-loop-system/network-update-loop-reference.md)
   * [Network time and ticks](advanced-topics/networktime-ticks.md)
 * [Serialization](serialization.md)
+  * [Serialization overview](advanced-topics/serialization/serialization-overview.md)
   * [C# primitives](advanced-topics/serialization/cprimitives.md)
   * [Unity primitives](advanced-topics/serialization/unity-primitives.md)
   * [Enum types](advanced-topics/serialization/enum-types.md)
   * [Arrays](advanced-topics/serialization/serialization-arrays.md)
-  * [INetworkSerializable](advanced-topics/serialization/inetworkserializable.md)
-  * [INetworkSerializeByMemcpy](advanced-topics/serialization/inetworkserializebymemcpy.md)
-  * [Custom serialization](advanced-topics/custom-serialization.md)
-  * [NetworkObject serialization](advanced-topics/serialization/networkobject-serialization.md)
+  * [Customize serializable types with INetworkSerializable](advanced-topics/serialization/inetworkserializable.md)
+  * [Serialize unmanaged structs with INetworkSerializeByMemcpy](advanced-topics/serialization/inetworkserializebymemcpy.md)
+  * [NetworkObject and NetworkBehaviour serialization](advanced-topics/serialization/networkobject-serialization.md)
   * [FastBufferWriter and FastBufferReader](advanced-topics/fastbufferwriter-fastbufferreader.md)
+  * [BufferSerializer](advanced-topics/bufferserializer.md)
+  * [Custom serialization](advanced-topics/custom-serialization.md)
 * [Scene management](scene-management.md)
   * [Scene management overview](basics/scenemanagement/scene-management-overview.md)
   * [Integrated management](integrated-management.md)

com.unity.netcode.gameobjects/Documentation~/advanced-topics/bufferserializer.md

@@ -1,5 +1,8 @@
 # BufferSerializer
 
+> [!NOTE]
+> Read the [Serialization overview](./serialization/serialization-overview.md) page to understand the basics of serialization before learning how to use `BufferSerializer`.
+
 `BufferSerializer<TReaderWriter>` is the bi-directional serializer primarily used for serializing within [`INetworkSerializable`](serialization/inetworkserializable.md) types. It wraps [`FastBufferWriter` and `FastBufferReader`](fastbufferwriter-fastbufferreader.md) to provide high performance serialization, but has a couple of differences to make it more user-friendly:
 
 - Rather than writing separate methods for serializing and deserializing, `BufferSerializer<TReaderWriter>` allows writing a single method that can handle both operations, which reduces the possibility of a mismatch between the two
@@ -15,3 +18,7 @@ However, when those downsides are unreasonable, `BufferSerializer<TReaderWriter>
 
 - For performance, you can use `PreCheck(int amount)` followed by `SerializeValuePreChecked()` to perform bounds checking for multiple fields at once.
 - For both performance and bandwidth usage, you can obtain the wrapped underlying reader/writer via `serializer.GetFastBufferReader()` when `serializer.IsReader` is `true`, and `serializer.GetFastBufferWriter()` when `serializer.IsWriter` is `true`. These provide micro-performance improvements by removing a level of indirection, and also give you a type you can use with `BytePacker` and `ByteUnpacker`.
+
+## Serializing custom types
+
+`BufferSerializer<TReaderWriter>` can be extended via extension methods to handle serializing custom types. Refer to [customizing `BufferSerializer`](./custom-serialization.md#bufferserializer) for instructions on how to do this.

com.unity.netcode.gameobjects/Documentation~/advanced-topics/custom-serialization.md

@@ -1,93 +1,71 @@
 # Custom serialization
 
-Netcode uses a default serialization pipeline when using `RPC`s, `NetworkVariable`s, or any other Netcode-related tasks that require serialization. The serialization pipeline looks like this:
+> [!NOTE]
+> Read the [Serialization overview](./serialization/serialization-overview.md) page to understand the basics of serialization before learning how to customize serialization.
 
-``
-Custom Types => Built In Types => INetworkSerializable
-``
+Netcode for GameObjects provide support for serializing any unsupported types, and with the API provided, it can even be done with types that you haven't defined yourself, those who are behind a 3rd party wall, such as .NET types. However, the way custom serialization is implemented for RPCs and NetworkVariables is slightly different.
 
-That is, when Netcode first gets hold of a type, it will check for any custom types that the user have registered for serialization, after that it will check if it's a built in type, such as a Vector3, float etc. These are handled by default. If not, it will check if the type inherits `INetworkSerializable`, if it does, it will call it's write methods.
+Netcode for GameObjects supports custom serialization of unsupported types, including those you haven't defined yourself, such as third-party .NET types. You can also use custom serialization to override how an existing supported type is serialized.
 
-By default, any type that satisfies the `unmanaged` generic constraint can be automatically serialized as RPC parameters. This includes all basic types (bool, byte, int, float, enum, etc) as well as any structs that has only these basic types.
+Custom serialization is implemented slightly differently for RPCs and NetworkVariables. The examples on this page provide different ways to serialization a custom health struct.
 
-With this flow, you can provide support for serializing any unsupported types, and with the API provided, it can even be done with types that you haven't defined yourself, those who are behind a 3rd party wall, such as .NET types. However, the way custom serialization is implemented for RPCs and NetworkVariables is slightly different.
+[!code-cs[](../../Tests/Editor/DocumentationCodeSamples/Serialization/SerializationCustomization.cs#HealthStruct)]
 
-### Serialize a type in a Remote Procedure Call (RPC)
+## FastBufferReader and FastBufferWriter
 
-> [!NOTE]
-> From versioln 1.7.0 Remote Procedure Calls (RPCs) can also use the Network Variable flow, but NetworkVariables can't use the RPC flow. The RPC flow is more efficient when RPCs serialize the type. Unity selects the RPC flow if you implement both the RPC and Network variable flows. When a type is used by both NetworkVariables and RPCs you can use the NetworkVariable flow to lower maintenance requirements.
+[`FastBufferReader` and `FastBufferWriter`](./fastbufferwriter-fastbufferreader.md) are the main serialization tools in Netcode for GameObjects. To register serialization for a custom type, or override an already handled type, you need to create extension methods for `FastBufferReader.ReadValueSafe()` and `FastBufferWriter.WriteValueSafe()`. `FastBufferReader` and `FastBufferWriter` can read and write primitive types, and you can extend this functionality to serialize your custom type.
 
-To register a custom type, or override an already handled type, you need to create extension methods for `FastBufferReader.ReadValueSafe()` and `FastBufferWriter.WriteValueSafe()`:
+[!code-cs[](../../Tests/Editor/DocumentationCodeSamples/Serialization/SerializationCustomization.cs#FastBuffer)]
 
-```csharp
-// Tells the Netcode how to serialize and deserialize Url in the future.
-// The class name doesn't matter here.
-public static class SerializationExtensions
-{
-    public static void ReadValueSafe(this FastBufferReader reader, out Url url)
-    {
-        reader.ReadValueSafe(out string val);
-        url = new Url(val);
-    }
-
-    public static void WriteValueSafe(this FastBufferWriter writer, in Url url)
-    {
-        writer.WriteValueSafe(url.Value);
-    }
-}
-```
+You may also need to add extensions for `FastBufferReader.ReadValue()`, `FastBufferWriter.WriteValue()` if you want to serialize without [bounds checking](./fastbufferwriter-fastbufferreader.md#bounds-checking)
 
-The code generation for RPCs will automatically pick up and use these functions, and they'll become available via `FastBufferWriter` and `FastBufferReader` directly.
+## BufferSerializer
 
-You can also optionally use the same method to add support for `BufferSerializer<TReaderWriter>.SerializeValue()`, if you wish, which will make this type readily available within [`INetworkSerializable`](serialization/inetworkserializable.md) types:
+You can also add custom serialization support to the bi-directional [`BufferSerializer`](./bufferserializer.md). This makes your custom type readily available within [`INetworkSerializable`](serialization/inetworkserializable.md) types and in the [`NetworkBehaviour.OnSynchronize()` method](../components/core/networkbehaviour-synchronize.md#prespawn-synchronization-with-onsynchronize):
 
-```csharp
-// The class name doesn't matter here.
-public static class SerializationExtensions
-{
-    public static void SerializeValue<TReaderWriter>(this BufferSerializer<TReaderWriter> serializer, ref Url url) where TReaderWriter: IReaderWriter
-    {
-        if (serializer.IsReader)
-        {
-            url = new Url();
-        }
-        serializer.SerializeValue(ref url.Value);
-    }
-}
-```
+[!code-cs[](../../Tests/Editor/DocumentationCodeSamples/Serialization/SerializationCustomization.cs#BufferSerializer)]
 
-Additionally, you can also add extensions for `FastBufferReader.ReadValue()`, `FastBufferWriter.WriteValue()`, and `BufferSerializer<TReaderWriter>.SerializeValuePreChecked()` to provide more optimal implementations for manual serialization using `FastBufferReader.TryBeginRead()`, `FastBufferWriter.TryBeginWrite()`, and `BufferSerializer<TReaderWriter>.PreCheck()`, respectively. However, none of these will be used for serializing RPCs - only `ReadValueSafe` and `WriteValueSafe` are used.
+## Remote procedure call (RPCs)
 
-### For NetworkVariable
+> [!NOTE]
+> RPCs can use the Network Variable flow, but NetworkVariables can't use the RPC flow. The RPC flow is more efficient when only RPCs need to serialize the type. When a type is used by both NetworkVariables and RPCs, you can implement just the NetworkVariable flow to lower maintenance requirements. Unity will select the RPC flow for RPCs if you have implemented both flows.
 
-`NetworkVariable` goes through a slightly different pipeline than `RPC`s and relies on a different process for determining how to serialize its types. As a result, making a custom type available to the `RPC` pipeline doesn't automatically make it available to the `NetworkVariable` pipeline, and vice-versa. The same method can be used for both, but currently, `NetworkVariable` requires an additional runtime step to make it aware of the methods.
+To serialize a custom type, or override an already handled type, you need to create extension methods for `FastBufferReader.ReadValueSafe()` and `FastBufferWriter.WriteValueSafe()` as [outlined above](#fastbufferreader-and-fastbufferwriter).
 
-To add custom serialization support in `NetworkVariable`, follow the steps from the "For RPCs" section to write extension methods for `FastBufferReader` and `FastBufferWriter`; then, somewhere in your application startup (before any `NetworkVariable`s using the affected types will be serialized) add the following:
+The code generation for RPCs will automatically pick up and use these functions, as they'll become available via `FastBufferWriter` and `FastBufferReader` directly.
 
-```csharp
-UserNetworkVariableSerialization<Url>.WriteValue = SerializationExtensions.WriteValueSafe;
-UserNetworkVariableSerialization<Url>.ReadValue = SerializationExtensions.ReadValueSafe;
-```
+## NetworkVariable
+
+Implementing [`INetworkSerializable`](./serialization/inetworkserializable.md) is the cleanest and most straightforward way to customize the serialization of a type within a [`NetworkVariable`](../basics/networkvariable.md). `UserNetworkVariableSerialization` provides runtime configuration to further override serialization of a type.
 
-You can also use lambda expressions here:
+First you will need to create extension methods for `FastBufferReader.ReadValueSafe()` and `FastBufferWriter.WriteValueSafe()` as [outlined above](#fastbufferreader-and-fastbufferwriter).
+
+Secondly, somewhere in your application startup (before any `NetworkVariable`s using the affected types will be serialized), add the following:
 
 ```csharp
-UserNetworkVariableSerialization<Url>.WriteValue = (FastBufferWriter writer, in Url url) =>
-{
-    writer.WriteValueSafe(url.Value);
-};
-
-UserNetworkVariableSerialization<Url>.ReadValue = (FastBufferReader reader, out Url url)
-{
-    reader.ReadValueSafe(out string val);
-    url = new Url(val);
-};
+UserNetworkVariableSerialization<Health>.WriteValue = SerializationExtensions.WriteValueSafe;
+UserNetworkVariableSerialization<Health>.ReadValue = SerializationExtensions.ReadValueSafe;
+UserNetworkVariableSerialization<Health>.DuplicateValue = (in Health value, ref Health duplicatedValue) => duplicatedValue = value;
 ```
 
-When you create an extension method in `NetworkVariable<T>` you need to implement the following values:
+`DuplicateValue` should return a complete deep copy of the value that `NetworkVariable<T>` compares to a previous value, which is used to check whether the value has changed. `DuplicateValue` avoids re-serializing it over the network every frame when it hasn't changed.
+
+> [!NOTE]
+> `WriteValue`, `ReadValue` and `DuplicateValue` all need to be defined to customize your serialization.
+
+> [!NOTE]
+> `WriteValue` and `ReadValue` will not be used if a type implements `INetworkSerializable` or [`INetworkSerializeByMemcpy`](./serialization/inetworkserializebymemcpy.md).
+
+### Serializing delta updates
+
+Reading and writing a value provides the minimal amount of `NetworkVariable` functionality. This will synchronize your whole type whenever any value within the type value changes. To support sending delta updates rather than a full update whenever your type has changed, implement the following functions:
+
+- `WriteDelta`
+- `ReadDelta`
+
+> [!NOTE]
+> Both `WriteDelta` and `ReadDelta` need to be defined for either to be used.
 
-- `WriteValue`
-- `ReadValue`
-- `DuplicateValue`
+Here is a full implementation of a custom type with the methods needed for `UserNetworkVariableSerialization`
 
-`DuplicateValue` returns a complete deep copy of the value that `NetworkVariable<T>` compares to a previous value to check whether or not that values has changed. This avoids reserializing it over the network every frame when it hasn't changed.
+[!code-cs[](../../Tests/Runtime/DocumentationCodeSamples/NetworkVariable/NetworkVariableSerialization.cs#HealthExample)]

com.unity.netcode.gameobjects/Documentation~/advanced-topics/fastbufferwriter-fastbufferreader.md

@@ -1,5 +1,8 @@
 # FastBufferWriter and FastBufferReader
 
+> [!NOTE]
+> Read the [Serialization overview](./serialization/serialization-overview.md) page to understand the basics of serialization before learning about `FastBufferWriter` and `FastBufferReader`.
+
 The serialization and deserialization is done via `FastBufferWriter` and `FastBufferReader`. These have methods for serializing individual types and methods for serializing packed numbers, but in particular provide a high-performance method called `WriteValue()/ReadValue()` (for Writers and Readers, respectively) that can extremely quickly write an entire unmanaged struct to a buffer.
 
 There's a trade-off of CPU usage vs bandwidth in using this: Writing individual fields is slower (especially when it includes operations on unaligned memory), but allows the buffer to be filled more efficiently, both because it avoids padding for alignment in structs, and because it allows you to use `BytePacker.WriteValuePacked()`/`ByteUnpacker.ReadValuePacked()` and `BytePacker.WriteValueBitPacked()`/`ByteUnpacker.ReadValueBitPacked()`. The difference between these two is that the BitPacked variants pack more efficiently, but they reduce the valid range of values. See the section below for details on packing.
@@ -156,3 +159,7 @@ Packing values is done using the utility classes `BytePacker` and `ByteUnpacker`
   | uint   | 30 bits (0 to 1,073,741,824)                                 |
   | long   | 60 bits + sign bit (-1,152,921,504,606,846,976 to 1,152,921,504,606,846,975) |
   | ulong  | 61 bits (0 to 2,305,843,009,213,693,952)                     |
+
+## Serializing custom types
+
+`FastBufferReader` and `FastBufferWriter` can be extended via extension methods to handle serializing custom types. Refer to [customizing `FastBufferReader` and `FastBufferWriter`](./custom-serialization.md#fastbufferreader-and-fastbufferwriter) for instructions on how to do this.

com.unity.netcode.gameobjects/Documentation~/advanced-topics/message-system/rpc.md

@@ -328,3 +328,4 @@ void Update()
 ## Additional resources
 
 * [RPC parameters](rpc-params.md)
+* [Customizing serialization](../custom-serialization.md#remote-procedure-call-rpc)

com.unity.netcode.gameobjects/Documentation~/advanced-topics/serialization/inetworkserializable.md

@@ -1,9 +1,14 @@
-# INetworkSerializable
+# Customize serializable types with INetworkSerializable
 
-You can use the `INetworkSerializable` interface to define custom serializable types.
+> [!NOTE]
+> Read the [Serialization overview](./serialization/serialization-overview.md) page to understand the basics of serialization before customizing serializable types with `INetworkSerializable`.
+
+You can use the `INetworkSerializable` interface to define custom serializable types. This interface has one function: `NetworkSerialize<T>(BufferSerializer<T> serializer)`, which ingests a bi-directional [`BufferSerializer`](../bufferserializer.md) that you can use to implement bi-directional custom serialization.
+
+`INetworkSerializable` can be implemented on both managed and unmanaged types, although serializing managed types isn't recommended because it can reduce your game's performance.
 
 ```csharp
-struct MyComplexStruct : INetworkSerializable
+struct SpawnPoint : INetworkSerializable
 {
     public Vector3 Position;
     public Quaternion Rotation;
@@ -18,24 +23,20 @@ struct MyComplexStruct : INetworkSerializable
 }
 ```
 
-Types implementing `INetworkSerializable` are supported by `NetworkSerializer`, `RPC` s and `NetworkVariable` s.
+Types implementing `INetworkSerializable` are supported by [`FastBufferReader` and `FastBufferWriter`](./fastbufferwriter-fastbufferreader.md), [`RPC`s'](../message-system/rpc.md), and [`NetworkVariable`s](../../basics/networkvariable.md).
 
 ```csharp
-
 [Rpc(SendTo.Server)]
-void MyServerRpc(MyComplexStruct myStruct) { /* ... */ }
+void SpawnAtPointRpc(SpawnPoint spawnPoint) { /* ... */ }
 
-void Update()
+void DoSpawnHere()
 {
-    if (Input.GetKeyDown(KeyCode.P))
+    var spawnPoint = new SpawnPoint
     {
-        MyServerRpc(
-            new MyComplexStruct
-            {
-                Position = transform.position,
-                Rotation = transform.rotation
-            }); // Client -> Server
-    }
+        Position = transform.position,
+        Rotation = transform.rotation
+    };
+    SpawnAtPointRpc(spawnPoint); // Client -> Server
 }
 ```
 
@@ -59,7 +60,7 @@ The following example explores a more advanced use case.
 
 ```csharp
 
-public struct MyMoveStruct : INetworkSerializable
+public struct SpawnWithMovement : INetworkSerializable
 {
     public Vector3 Position;
     public Quaternion Rotation;
@@ -125,7 +126,7 @@ Review the following example:
 
 ```csharp
 
-public struct MyStructA : INetworkSerializable
+public struct SpawnPoint : INetworkSerializable
 {
     public Vector3 Position;
     public Quaternion Rotation;
@@ -137,17 +138,17 @@ public struct MyStructA : INetworkSerializable
     }
 }
 
-public struct MyStructB : INetworkSerializable
+public struct SpawnInfo : INetworkSerializable
 {
     public int SomeNumber;
     public string SomeText;
-    public MyStructA StructA;
+    public SpawnPoint SpawnPoint;
 
     void NetworkSerialize<T>(BufferSerializer<T> serializer) where T : IReaderWriter
     {
         serializer.SerializeValue(ref SomeNumber);
         serializer.SerializeValue(ref SomeText);
-        StructA.NetworkSerialize(serializer);
+        SpawnPoint.NetworkSerialize(serializer);
     }
 }
 ```
@@ -167,7 +168,7 @@ While you can have nested `INetworkSerializable` implementations (an `INetworkSe
 
 ```csharp
 /// This isn't supported.
-public struct MyStructB : MyStructA
+public struct SpawnInfo : SpawnPoint
 {
     public int SomeNumber;
     public string SomeText;
@@ -232,4 +233,4 @@ Then declare this network variable like so:
 
 ```csharp
 NetworkVariable<GameDataWithLong> myVar = new NetworkVariable<GameDataWithLong>();
-```
+```