update: distributed authority parenting rules (#1423)

Co-authored-by: Amy Reeve <[email protected]>

Author: NoelStephensUnity

docs/advanced-topics/networkobject-parenting.md

@@ -25,6 +25,37 @@ If you aren't completely familiar with transform parenting in Unity, then it's h
   - When `OnNetworkObjectParentChanged` is invoked, on the server side, adjust the child's transform values within the overridden method.
   - Netcode for GameObjects will then synchronize all clients with the child's parenting and transform changes.
 
+### Parenting, distributed authority, and NetworkObject redistribution
+
+Parenting within a [distributed authority](../terms-concepts/distributed-authority.md) network topology follows the same rules as outlined above, with the exception that you can change any references to the server with references to authority.
+ 
+#### Rule adjustments
+
+  - Whichever client has authority over a NetworkObject can control its parenting. 
+  - You can parent under mixed authority. This means that Client-B can parent a NetworkObject it has authority over under another NetworkObject that Client-A has authority over.
+
+#### Distributable permissions and child hierarchies
+
+- **When a client disconnects:**
+  - Any root parent with [distributable permission](../basics/ownership.md#ownership-permission-settings) set that was owned by the disconnected client is redistributed.
+    - If the root parent was locked when the client disconnected, then it's unlocked prior to redistributing.
+    - Children of the root parent change ownership with the root parent only if:
+      - The child was owned by the client that disconnected.
+      - The child has either the distributable or transferable permission set.
+    - If a child's ownership permission is locked, it's unlocked prior to redistributing.
+    - Any child of the root parent that's owned by a different client won't get redistributed.
+- **When a client connects:**
+  - Any root parent with [distributable permission](../basics/ownership.md#ownership-permission-settings) set that doesn't have ownership locked is considered for redistribution.
+    - If a root parent is redistributed to a newly connecting client then:
+      - Any child under the root parent that has the same owner as the root parent changes ownership with the root parent.
+        - Unless the child has ownership locked.
+    - Any child under the root parent that has the distributable or transferrable permission set can be redistributed as well.
+      - Unless the child has ownership locked.
+
+#### Distributable permissions and in-scene placed `NetworkObject` instances:
+By default, any root in-scnee placed `NetworkObject` instance will have the `Distributable` permissions flag unless it already has the `SessionOwner` permission flag set. This assures in-scene placed `NetworkObject` instances will always distributed amongst clients or a newly promoted session owner.
+
+
 :::tip
 When a NetworkObject is parented, Netcode for GameObjects synchronizes both the parenting information along with the child's transform values. Netcode for GameObjects uses the `WorldPositionStays` setting to decide whether to synchronize the local or world space transform values of the child NetworkObject component. This means that a NetworkObject component doesn't require you to include a NetworkTransform component if it never moves around, rotates, or changes its scale when it isn't parented. This can be beneficial for world items a player might pickup (parent the item under the player) and the item in question needs to adjustment relative to the player when it's parented or the parent is removed (dropped). This helps to reduce the item's over-all bandwidth and processing resources consumption.
 :::