feat: AttachableBehaviour and ComponentController

com.unity.netcode.gameobjects/CHANGELOG.md

@@ -11,6 +11,10 @@ Additional documentation and release notes are available at [Multiplayer Documen
 ### Added
 
 - Added serializer for `Pose` (#3546)
+- Added `AttachableBehaviour` helper component to provide an alternate approach to parenting items without using the `NetworkObject` parenting. (#3518)
+- Added `AttachableNode` helper component that is used by `AttachableBehaviour` as the target node for parenting. (#3518)
+- Added `ComponentController` helper component that can be used to synchronize the enabling and disabling of components and can be used in conjunction with `AttachableBehaviour`. (#3518)
+- Added `NetworkBehaviour.OnNetworkPreDespawn` that is invoked before running through the despawn sequence for the `NetworkObject` and all `NetworkBehaviour` children of the `NetworkObject` being despawned. (#3518)
 - Added methods `GetDefaultNetworkSettings` and `GetDefaultPipelineConfigurations` to `UnityTransport`. These can be used to retrieve the default settings and pipeline stages that are used by `UnityTransport`. This is useful when providing a custom driver constructor through `UnityTransport.s_DriverConstructor`, since it allows reusing or tuning the existing configuration instead of trying to recreate it. This means a transport with a custom driver can now easily benefit from most of the features of `UnityTransport`, like integration with the Network Simulator and Network Profiler from the multiplayer tools package. (#3501)
 - Added mappings between `ClientId` and `TransportId`. (#3516)
 - Added `NetworkPrefabInstanceHandlerWithData<T>`, a variant of `INetworkPrefabInstanceHandler` that provides access to custom instantiation data directly within the `Instantiate()` method. (#3430)

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

@@ -19,16 +19,20 @@
   * [Transports](advanced-topics/transports.md)
   * [Relay](relay/relay.md)
 * [Network components](network-components.md)
-  * [NetworkObject](basics/networkobject.md)
-  * [PlayerObjects and player prefabs](basics/playerobjects.md)
-  * [NetworkObject parenting](advanced-topics/networkobject-parenting.md)
-  * [NetworkBehaviour](networkbehaviour-landing.md)
-    * [NetworkBehaviour](basics/networkbehaviour.md)
-    * [Synchronize](basics/networkbehaviour-synchronize.md)
-  * [Physics](advanced-topics/physics.md)
-  * [NetworkManager](components/networkmanager.md)
-  * [NetworkTransform](components/networktransform.md)
-  * [NetworkAnimator](components/networkanimator.md)
+  * [Foundational Components](components/foundational/foundationalcomponents.md)
+    * [NetworkObject](components/foundational/networkobject.md)
+      * [NetworkObject parenting](advanced-topics/networkobject-parenting.md)
+    * [NetworkBehaviour](components/foundational/networkbehaviour.md)
+      * [Synchronizing & Order of Operations](components/foundational/networkbehaviour-synchronize.md)
+    * [NetworkManager](components/foundational/networkmanager.md)
+      * [PlayerObjects and player prefabs](components/foundational/playerobjects.md)
+  * [Helper Components](components/Helpers/helpercomponents.md)
+    * [AttachableBehaviour](components/Helpers/attachablebehaviour.md)
+    * [AttachableNode](components/Helpers/attachablenode.md)
+    * [ComponentController](components/Helpers/componentcontroller.md)
+    * [NetworkAnimator](components/helpers/networkanimator.md)
+    * [NetworkTransform](components/helpers/networktransform.md)
+      * [Physics](advanced-topics/physics.md)
 * [Ownership and authority](ownership-authority.md)
   * [Understanding ownership and authority](basics/ownership.md)
   * [Ownership race conditions](basics/race-conditions.md)
@@ -39,11 +43,11 @@
   * [Spawning synchronization](basics/spawning-synchronization.md)
   * [Deferred despawning](basics/deferred-despawning.md)
 * [Latency and performance](latency-performance.md)
-  * [Understanding latency](learn/lagandpacketloss.md)
-  * [Ticks and update rates](learn/ticks-and-update-rates.md)
-  * [Improving performance with client-side interpolation](learn/clientside-interpolation.md)
-  * [Client anticipation](advanced-topics/client-anticipation.md)
-  * [Dealing with latency](learn/dealing-with-latency.md)
+    * [Understanding latency](learn/lagandpacketloss.md)
+    * [Ticks and update rates](learn/ticks-and-update-rates.md)
+    * [Improving performance with client-side interpolation](learn/clientside-interpolation.md)
+    * [Client anticipation](advanced-topics/client-anticipation.md)
+    * [Dealing with latency](learn/dealing-with-latency.md)
 * [Network synchronization](network-synchronization.md)
   * [Synchronizing states and events](advanced-topics/ways-to-synchronize.md)
   * [NetworkVariables](networkvariables-landing.md)

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

@@ -21,7 +21,7 @@ Some collision events aren't fired when using `NetworkRigidbody`.
 
 ## NetworkRigidbody and ClientNetworkTransform
 
-You can use NetworkRigidbody with the [`ClientNetworkTransform`](../components/networktransform.md) package sample to allow the owner client of a NetworkObject to move it authoritatively. In this mode, collisions only result in realistic dynamic collisions if the object is colliding with other NetworkObjects (owned by the same client).
+You can use NetworkRigidbody with the [`ClientNetworkTransform`](../components/helpers/networktransform.md) package sample to allow the owner client of a NetworkObject to move it authoritatively. In this mode, collisions only result in realistic dynamic collisions if the object is colliding with other NetworkObjects (owned by the same client).
 
 > [!NOTE]
 > Add the ClientNetworkTransform component to your GameObject first. Otherwise the NetworkRigidbody automatically adds a regular NetworkTransform.

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

@@ -19,7 +19,7 @@ You can also decide to clear all data when a session completes or add a timeout
 
 # Reconnection
 
-The best way to reconnect players depends on your game. For example, if you use a [Player Object](../basics/networkobject.md#player-objects), a new `Default Player Prefab` automatically spawns when a player connects to the game (including when they reconnect). You can use the player's earlier saved session data to update that object so that it returns to the same state before disconnecting. In those cases, you would need to keep all the important data that you want to restore and map it to the player using your identification system. You can save this data when a player disconnects or update it periodically. You can then use the `OnNetworkSpawn` event on the Player Object's `NetworkBehavior`(s) to get this data and apply it where needed.
+The best way to reconnect players depends on your game. For example, if you use a [Player Object](../components/foundational/networkobject.md#player-objects), a new `Default Player Prefab` automatically spawns when a player connects to the game (including when they reconnect). You can use the player's earlier saved session data to update that object so that it returns to the same state before disconnecting. In those cases, you would need to keep all the important data that you want to restore and map it to the player using your identification system. You can save this data when a player disconnects or update it periodically. You can then use the `OnNetworkSpawn` event on the Player Object's `NetworkBehavior`(s) to get this data and apply it where needed.
 
 In cases where we don't use the Player Object approach and instead manually attribute client ownership to `NetworkObject`(s), we can keep the objects that a player owns when they disconnect, and set the reconnected player as their new owner. To accomplish this, the only data we would need to keep would be the mapping between those objects and their owning player's identifier, then when a player reconnects we can use this mapping to set them as the new owner. This mapping can be as simple as a dictionary mapping the player identifier with the `NetworkObjectId`(s) of the `NetworkObject`(s) they own. Then, in the `OnClientConnectedCallback` from the `NetworkManager`, the server can set the ownership of these objects.
 

com.unity.netcode.gameobjects/Documentation~/basics/object-spawning.md

@@ -31,7 +31,7 @@ _In most cases, you will want to keep the `NetworkObject` component attached to
 
 By default a newly spawned network Prefab instance is owned by the server unless otherwise specified.
 
-See [Ownership](networkobject.md#ownership) for more information.
+See [Ownership](../components/foundational/networkobject.md#ownership) for more information.
 
 The following is a basic example of how to spawn a network Prefab instance (with the default server ownership):
 

com.unity.netcode.gameobjects/Documentation~/basics/object-visibility.md

@@ -111,4 +111,4 @@ NetworkObject.SpawnWithObservers = false;
 NetworkObject.Spawn();
 ```
 
-See [Spawning With (or Without) Observers](networkobject.md#spawning-with-or-without-observers) for more information.
+See [Spawning With (or Without) Observers](../components/foundational/networkobject.md#spawning-with-or-without-observers) for more information.

com.unity.netcode.gameobjects/Documentation~/basics/ownership.md

@@ -1,6 +1,6 @@
 # Understanding ownership and authority
 
-By default, Netcode for GameObjects assumes a [client-server topology](../terms-concepts/client-server.md), in which the server owns all NetworkObjects (with [some exceptions](networkobject.md#ownership)) and has ultimate authority over [spawning and despawning](object-spawning.md).
+By default, Netcode for GameObjects assumes a [client-server topology](../terms-concepts/client-server.md), in which the server owns all NetworkObjects (with [some exceptions](../components/foundational/networkobject.md#ownership)) and has ultimate authority over [spawning and despawning](object-spawning.md).
 
 Netcode for GameObjects also supports building games with a [distributed authority topology](../terms-concepts/distributed-authority.md), which provides more options for ownership and authority over NetworkObjects.
 

com.unity.netcode.gameobjects/Documentation~/basics/scenemanagement/custom-management.md

@@ -39,7 +39,7 @@ Once you've registered your in-scene placed Network Prefabs with your `NetworkPr
 > When a client first connects, it deletes any in-scene placed `NetworkObjects` in any of the scenes it has currently loaded.  When using a custom scene management solution, in-scene placed `NetworkObject`s are actually dynamically spawned. This means any changes you make to your in-scene placed Network Prefabs will *not* be synchronized with clients automatically.
 
 ### Synchronizing In-Scene Placed Network Prefab Instances
-If you want to change an in-scene placed network prefab instance, you need to handle the serialization of these settings yourself. You can do this by overriding `NetworkBehaviour.OnSynchronize` and serializing any property updates you want to have synchronized with clients when they join. [Read More About OnSynchronize Here](../../basics/networkbehaviour.md#pre-spawn-synchronization).
+If you want to change an in-scene placed network prefab instance, you need to handle the serialization of these settings yourself. You can do this by overriding `NetworkBehaviour.OnSynchronize` and serializing any property updates you want to have synchronized with clients when they join. [Read More About OnSynchronize Here](../../components/foundational/networkbehaviour.md#pre-spawn-synchronization).
 
 ## Starting a Netcode Enabled Game Session
 The recommended way of starting session using your own scene management solution is to assure that when a client attempts to join a netcode game session it should already have (as best as possible) any scenes that the server might have loaded.  While this does not assure that your newly connecting client will load any additional scenes that might have been loaded, using this approach initially will get you started so you can then come up with a strategy to handling:

com.unity.netcode.gameobjects/Documentation~/basics/scenemanagement/inscene-placed-networkobjects.md

@@ -13,7 +13,7 @@ In-scene placed `NetworkObject`s are GameObjects with a `NetworkObject` componen
    - For example, a heads up display (HUD) that includes information about other items or players.
    - Or some form of platform or teleporter that moves a player from one location to the next when a player enters a trigger or uses an object.
 
-Another benefit of in-scene placed `NetworkObject`s is that they don't require you to register them with the [`NetworkManager`](../../components/networkmanager.md). In-scene placed `NetworkObjects` are registered internally, when scene management is enabled, for tracking and identification purposes.
+Another benefit of in-scene placed `NetworkObject`s is that they don't require you to register them with the [`NetworkManager`](../../components/foundational/networkmanager.md). In-scene placed `NetworkObjects` are registered internally, when scene management is enabled, for tracking and identification purposes.
 
 > [!NOTE]
 > Items that can be picked up are typically better implemented using a [hybrid approach](#hybrid-approach) with both an in-scene placed and a dynamically spawned `NetworkObject`. The in-scene placed `NetworkObject` can be used to configure additional information about the item (what kind, does another one respawn after one is picked up, and if so how much time should it wait before spawning a new item), while the dynamically spawned object is the item itself.

com.unity.netcode.gameobjects/Documentation~/basics/scenemanagement/scene-events.md

@@ -57,7 +57,7 @@ While client synchronization does fall partially outside of the scene management
 <br/>
 Below is a diagram of the client connection approval and synchronization process:
 
-![image](../images/scenemanagement_synchronization_overview.png)
+![image](../../images/scenemanagement_synchronization_overview.png)
 
 Starting with the "Player" in the top right part of the above diagram, the client (Player) runs through the connection and approval process first which occurs within the `NetworkManager`.  Once approved, the server-side `NetworkSceneManager` begins the client synchronization process by sending the `SceneEventType.Synchronize` Scene Event message to the approved client.  The client then processes through the synchronization message.  Once the client is finished processing the synchronize message, it responds to the server with a `SceneEventType.SynchronizeComplete` message. At this point the client is considered "synchronized".  If the server determines any `NetworkObject` was despawned during the client-side synchronization message processing period, it will send a list of `NetworkObject` identifiers to the client via the `SceneEventType.ReSynchronize` message and the client will locally despawn the `NetworkObject`s.
 
@@ -228,10 +228,10 @@ You can stop the coroutine checking the progress upon receiving any of the follo
 The SceneEvent class has values that may or may not be set depending upon the `SceneEventType`.  Below are two quick lookup tables to determine which property is set for each `SceneEventType`.
 
 **Part-1**<br/>
-![image](../images/SceneEventProperties-1.png)<br/>
+![image](../../images/SceneEventProperties-1.png)<br/>
 
 **Part-2** <br/>
-![image](../images/SceneEventProperties-2.png)<br/>
+![image](../../images/SceneEventProperties-2.png)<br/>
 
 So, the big "take-away" from the above table is that you need to understand the `SceneEventType` context of the `SceneEvent` you are processing to know which properties are valid and you can use.  As an example, it wouldn't make sense to provide the AsyncOperation for the following `SceneEventType`s:
 - LoadComplete or LoadEventCompleted