chore: Add NetworkObject ownership docs and update related docs

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

@@ -7,12 +7,12 @@
     * [Distributed authority WebGL quickstart](learn/distributed-authority-webgl.md)
 * [Networking concepts](networking-concepts.md)
   * [Authority](terms-concepts/authority.md)
-  * [Ownership](terms-concepts/ownership.md)
   * [Network topologies](network-topologies.md)
     * [Network topologies](terms-concepts/network-topologies.md)
     * [Client-server](terms-concepts/client-server.md)
     * [Listen server host architecture](learn/listenserverhostarchitecture.md)
     * [Distributed authority topologies](terms-concepts/distributed-authority.md)
+  * [Ownership](terms-concepts/ownership.md)
 * [Configuration](configuration.md)
   * [Configuring connections](configure-connections.md)
     * [Connection approval](basics/connection-approval.md)
@@ -23,9 +23,11 @@
 * [Network components](network-components.md)
   * [Core components](components/core/corecomponents.md)
     * [NetworkObject](components/core/networkobject.md)
+      * [NetworkObject ownership](components/core/networkobject-ownership.md)
       * [NetworkObject parenting](advanced-topics/networkobject-parenting.md)
     * [NetworkBehaviour](components/core/networkbehaviour.md)
       * [Synchronizing & Order of Operations](components/core/networkbehaviour-synchronize.md)
+      * [NetworkBehaviour ownership](components/core/networkbehaviour-ownership.md)
     * [NetworkManager](components/core/networkmanager.md)
       * [PlayerObjects and player prefabs](components/core/playerobjects.md)
   * [Helper Components](components/helper/helpercomponents.md)

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

@@ -36,11 +36,11 @@ However, the RPC signature hash doesn't change when the names of the parameters
 
 When the RPC signature changes, it directs to a different invocation code path that has different serialization code. This means that the RPC method with the new signature doesn't invoke previous versions of that RPC method (for example, an RPC method from an older build).
 
-| Compatibility | <i class="fp-check"></i> | Description |
-| -- | :--: | -- |
-| Cross-Build Compatibility | <i class="fp-check"></i> | As long as the RPC method signature is kept the same, it will be compatible between different builds. |
-| Cross-Version Compatibility | <i class="fp-check"></i> | As long as the RPC method signature is kept the same, it will be compatible between different versions. |
-| Cross-Project Compatibility | <i class="fp-x"></i> | The exact same RPC method signature can be defined in different projects. This is because the project name or project-specific token isn't part of RPC signature. Cross-project RPC methods aren't compatible with each other. |
+| Compatibility | | Description |
+| -- | -- | -- |
+| Cross-Build Compatibility | **Yes** | As long as the RPC method signature is kept the same, it will be compatible between different builds. |
+| Cross-Version Compatibility | **Yes** | As long as the RPC method signature is kept the same, it will be compatible between different versions. |
+| Cross-Project Compatibility | No | The exact same RPC method signature can be defined in different projects. This is because the project name or project-specific token isn't part of RPC signature. Cross-project RPC methods aren't compatible with each other. |
 
 ## Deprecation of return values
 

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

@@ -1,15 +1,15 @@
 # NetworkObject parenting
 
-### Overview
+## Overview
 
-If you aren't completely familiar with transform parenting in Unity, then it's highly recommended to [review over the existing Unity documentation](https://docs.unity3d.com/Manual/class-Transform.html) before reading further to properly synchronize all connected clients with any change in a GameObject component's transform parented status, Netcode for GameObjects requires that the parent and child GameObject components have NetworkObject components attached to them.
+If you aren't completely familiar with transform parenting in Unity, then it's highly recommended to [review over the existing Unity documentation](https://docs.unity3d.com/Manual/class-Transform.html) before reading further. To properly synchronize all connected clients with any change in a GameObject component's transform parented status, Netcode for GameObjects requires that the parent and child GameObject components have NetworkObject components attached to them. Otherwise, you can use the [AttachableBehaviour](../components/helper/attachablebehaviour.md) and [AttachableNode](../components/helper/attachablenode.md) helper components to synchronize other types of parenting.
 
-### Parenting rules
+## Parenting rules
 
 - Setting the parent of a child's `Transform` directly (that is, `transform.parent = childTransform;`) always uses the default `WorldPositionStays` value of `true`.
   - It's recommended to always use the `NetworkObject.TrySetParent` method when parenting if you plan on changing the `WorldPositionStays` default value.
   - Likewise, it's also recommended to use the `NetworkObject.TryRemoveParent` method to remove a parent from a child.
-- When a server parents a spawned NetworkObject component under another spawned NetworkObject component during a Netcode game session this parent child relationship replicates across the network to all connected and future late joining clients.
+- When an [authority](../terms-concepts/authority.md) parents a spawned NetworkObject component under another spawned NetworkObject component during a Netcode game session this parent child relationship replicates across the network to all connected and future late joining clients.
 - If, while editing a scene, you place an in-scene placed NetworkObject component under a GameObject component that doesn't have a NetworkObject component attached to it, Netcode for GameObjects preserves that parenting relationship.
   - During runtime, this parent-child hierarchy remains true unless the user code removes the GameObject parent from the child NetworkObject component.
     - **Note**: Once removed, Netcode for GameObjects won't allow you to re-parent the NetworkObject component back under the same or another GameObject component that with no NetworkObject component attached to it.
@@ -35,15 +35,26 @@ If you aren't completely familiar with transform parenting in Unity, then it's h
 virtual void OnNetworkObjectParentChanged(NetworkObject parentNetworkObject) { }
 ```
 
-> [!NOTE] Multi-generation children and scale
+> [!NOTE]
+> Multi-generation children and scale
 > If you are dealing with more than one generation of nested children where each parent and child have scale values other than `Vector3.one`, then mixing the `WorldPositionStays` value when parenting and removing a parent will impact how the final scale is calculated! If you want to keep the same values before parenting when removing a parent from a child, then you need to use the same `WorldPositionStays` value used when the child was parented.
 
-### Only a server (or a host) can parent NetworkObjects
+### Who can parent NetworkObjects
+
+#### Under a spawned NetworkObject
+
+The [owner](../terms-concepts/ownership.md) of a NetworkObject can always parent that NetworkObject under any other spawned NetworkObject. This works regardless of who owns the other NetworkObject.
+
+#### Under other GameObjects
+
+By default, only the [authority](../terms-concepts/authority.md) of a NetworkObject can parent a NetworkObject under a non-networked object. This means in a client-server game, only the server (or host) can control NetworkObject component parenting. In a distributed authority game the [owner](../terms-concepts/ownership.md) of the object can always parent the object.
+
+To allow the owner to parent their owned object in a client-server game, use the [`NetworkObject.AllowOwnerToParent`](https://docs.unity3d.com/Packages/com.unity.netcode.gameobjects@latest?subfolder=/api/Unity.Netcode.NetworkObject.html#Unity_Netcode_NetworkObject_AllowOwnerToParent) property.
 
-Similar to [Ownership](../basics/networkobject#ownership), only the server (or host) can control NetworkObject component parenting.
+![image](../images/networkobject/allowOwnerToParent.png)
 
 > [!NOTE]
-> If you run into a situation where your client must trigger parenting a NetworkObject component, one solution is for the client to send an RPC to the server. Upon receiving the RPC message, the server then handles parenting the NetworkObject component.
+> If you run into a situation where your client must trigger parenting a NetworkObject component, one solution is for the client to send an RPC to the authority. Upon receiving the RPC message, the authority then handles parenting the NetworkObject component.
 
 ### Only parent under a NetworkObject Or nothing (root or null)
 

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

@@ -30,9 +30,7 @@ When using a [server authoritative networking model](../terms-concepts/authority
 
 To spawn a network prefab, you must first create an instance of the network prefab and then invoke the spawn method on the NetworkObject component of the instance you created. In most cases, you will want to keep the NetworkObject component attached to the root GameObject of the network prefab.
 
-By default, a newly spawned network prefab instance is owned by the authority unless otherwise specified.
-
-See [Ownership](networkobject.md#ownership) for more information.
+See [NetworkObject ownership](../components/core/networkobject-ownership.md) for more information.
 
 The following is a basic example of how to spawn a network prefab instance:
 

com.unity.netcode.gameobjects/Documentation~/components/core/networkbehaviour-ownership.md

@@ -0,0 +1,68 @@
+# NetworkBehaviour ownership
+
+Before reading these docs, ensure you understand the concepts of [ownership](../terms-concepts/ownership.md) and [NetworkObject ownership](./networkobject-ownership.md). It's also important to be familiar with the [NetworkBehaviour](./networkbehaviour.md)
+
+The owner of each NetworkBehaviour in your game is decided by the owner of that NetworkBehaviour's NetworkObject. The NetworkObject is found as a property on the NetworkBehaviour: [`NetworkBehaviour.NetworkObject`](https://docs.unity3d.com/Packages/com.unity.netcode.gameobjects@latest?subfolder=/api/Unity.Netcode.NetworkBehaviour.html#Unity_Netcode_NetworkBehaviour_NetworkObject).
+
+## Helpful properties
+
+> [!NOTE]
+> The following properties are only valid if the NetworkBehaviour has been spawned. Use [`NetworkBehaviour.IsSpawned`](https://docs.unity3d.com/Packages/com.unity.netcode.gameobjects@latest?subfolder=/api/Unity.Netcode.NetworkBehaviour.html#Unity_Netcode_NetworkBehaviour_IsSpawned) to check the spawned status of the NetworkBehaviour
+
+To see if the local client is the owner of a NetworkBehaviour, you can check the[`NetworkBehaviour.IsOwner`](https://docs.unity3d.com/Packages/com.unity.netcode.gameobjects@latest?subfolder=/api/Unity.Netcode.NetworkBehaviour.html#Unity_Netcode_NetworkBehaviour_IsOwner) property.
+
+To see if the server owns a NetworkBehaviour, you can check the [`NetworkBehaviour.IsOwnedByServer`](https://docs.unity3d.com/Packages/com.unity.netcode.gameobjects@latest?subfolder=/api/Unity.Netcode.NetworkBehaviour.html#Unity_Netcode_NetworkBehaviour_IsOwnedByServer) property.
+
+To see if the local client has authority of a NetworkBehaviour, you can check the[`NetworkBehaviour.HasAuthority`](https://docs.unity3d.com/Packages/com.unity.netcode.gameobjects@latest?subfolder=/api/Unity.Netcode.NetworkBehaviour.html#Unity_Netcode_NetworkBehaviour_HasAuthority) property.
+
+## Detecting ownership changes
+
+There are three functions that can be implemented to detect ownership changes on a NetworkBehaviour. These functions are invoked in the order they are listed here.
+
+### [OnLostOwnership](https://docs.unity3d.com/Packages/com.unity.netcode.gameobjects@latest?subfolder=/api/Unity.Netcode.NetworkBehaviour.html#Unity_Netcode_NetworkBehaviour_OnLostOwnership)
+
+When using a [client-server network topology](../../terms-concepts/client-server.md) `OnLostOwnership`  is invoked on both the server any time a connected client loses ownership of this NetworkBehaviour. It is also invoked on the game client who just lost ownership.
+
+In a [distributed authority network topology](../../terms-concepts/distributed-authority.md) `OnLostOwnership` is invoked on all connected game clients.
+
+```csharp
+void OnLostOwnership()
+{
+    var newOwner = OwnerClientId;
+
+    // Take action on lost ownership here
+}
+```
+
+### [OnGainedOwnership](https://docs.unity3d.com/Packages/com.unity.netcode.gameobjects@latest?subfolder=/api/Unity.Netcode.NetworkBehaviour.html#Unity_Netcode_NetworkBehaviour_OnGainedOwnership)
+
+When using a client-server network topology `OnGainedOwnership` is invoked on the server any time ownership is gained. It is also be invoked on the game client who just gained ownership.
+
+In a distributed authority network topology `OnGainedOwnership` is invoked on all connected game clients.
+
+`OnGainedOwnership` is invoked after `OnLostOwnership`.
+
+```csharp
+void OnGainedOwnership()
+{
+    var newOwner = OwnerClientId;
+    var newOwnerIsMe = IsOwner;
+
+    // Take action on ownership gain here
+}
+```
+
+### [OnOwnershipChanged](https://docs.unity3d.com/Packages/com.unity.netcode.gameobjects@latest?subfolder=/api/Unity.Netcode.NetworkBehaviour.html#Unity_Netcode_NetworkBehaviour_OnOwnershipChanged_System_UInt64_System_UInt64_)
+
+Whenever you want notification on any and all ownership changes, implement the `OnOwnershipChanged` method. `OnOwnershipChanged` is invoked on all connected game clients whenever the ownership of the NetworkBehaviour it is implemented on changes.
+
+`OnOwnershipChanged` is invoked after `OnLostOwnership` and `OnGainedOwnership`.
+
+```csharp
+void OnOwnershipChanged(ulong previousOwnerId, ulong currentOwnerId)
+{
+    var newOwnerIsMe = IsOwner;
+
+    // Take action on ownership change here
+}
+```

com.unity.netcode.gameobjects/Documentation~/components/core/networkbehaviour.md

@@ -1,4 +1,4 @@
-# NetworkBehaviour spawning and despawning
+# NetworkBehaviour
 
 [NetworkBehaviour](https://docs.unity3d.com/Packages/com.unity.netcode.gameobjects@latest?subfolder=/api/Unity.Netcode.NetworkBehaviour.html) is an abstract class that derives from [MonoBehaviour](https://docs.unity3d.com/ScriptReference/MonoBehaviour.html) and is primarily used to create unique netcode or game logic. To replicate any netcode-aware properties or send and receive RPCs, a [GameObject](https://docs.unity3d.com/Manual/GameObjects.html) must have a [NetworkObject](networkobject.md) component and at least one NetworkBehaviour component.
 
@@ -38,6 +38,7 @@ The diagram above represents how the spawn process works for two NetworkBehaviou
 NetworkObjects go through three states during the spawn process:
 
 **Spawn states**
+
 - Prespawning: Before any netcode-related properties have been set.
 - Spawning: Netcode-related properties have been set.
 - Spawned: All NetworkBehaviour components have completed their spawn logic.
@@ -98,7 +99,7 @@ private void Update()
 
 Alternatively, you can leverage the [NetworkUpdateLoop](../../advanced-topics/network-update-loop-system/index.md) system by making a NetworkBehaviour implement the `INetworkUpdateSystem` interface and register each instance for a specific `NetworkUpdateStage` during the `OnNetworkSpawn` or `OnNetworkPreSpawn` invocations, and then use your own script logic to determine which instance should be updating.
 
-This can be useful when you want only the owner, authority, or non-authority to be updating and can help to remove checks like the above. It can also reduce the performance cost of all instances that do not register for the update stage (depending upon how many instances are spawned).
+This can be useful when you want only the [owner](../../terms-concepts/ownership.md), [authority](../../terms-concepts/authority.md), or non-authority to be updating and can help to remove checks like the above. It can also reduce the performance cost of all instances that do not register for the update stage (depending upon how many instances are spawned).
 
 ### Dynamically spawned NetworkObjects
 
@@ -189,4 +190,4 @@ Similar to the [spawn process and invocation order section above](#spawn-process
 ## Additional resources
 
 - [NetworkObjects](networkobject.md)
-- [NetworkBehaviour synchronization](networkbehaviour-synchronize.md)
+- [NetworkBehaviour synchronization](networkbehaviour-synchronize.md)