You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Adding `AttachableNode` and `ComponentController` sections.
Added "Synchronized RPC driven fields" section to networkbehaviour-synchronize.md.
Updated various areas based on the additions.
The `AttachableBehaviour` Provides "out of the box" support for attaching (i.e. parenting) a nested child `GameObject` that includes an `AttachableBehaviour` component to another nested child `GameObject` with an `AttachableNode` component that is associated with a different `NetworkObject`.
The basic functionality of the `AttachableBehaviour` component provides:
6
+
- The ability to assign (make aware) `ComponetController` components from any part of the parent-child hierarchy.
7
+
- Each `ComponentControllerEntry` provides the ability to select when the `ComponentController` should be triggered (via the **Auto Trigger** property) and whether its enabled state should be enabled or disabled upon attaching (via the **Enable On Attach** property). The default setting is to be disabled upon the `AttachableBehaviour` attaching to an `AttachableNode` and enabled upon detaching. When the **Enable On Attach** property is enabled, the `ComponentController` will be set to enabled upon the `AttachableBehaviour` attaching to an `AttachableNode` and disabled upon detaching.
8
+
- The ability to control when an `AttachableBehaviour` component will automatically detach from an `AttachableNode` via the **Auto Detach** property.
9
+
- The **Auto Detach** property can have any combination of the below flags or none (no flags):
10
+
-**On Ownership Changed:** Upon ownership changing, the `AttachableBehaviour` will detach from any `AttachableNode` it is attached to.
11
+
-**On Despawn:** Upon the `AttachableBehaviour` being despawned, it will detach from any `AttachableNode` it is attached to.
12
+
-**On Attach Node Destroy**: Just prior to the `AttachableNode` being destroyed, any attached `AttachableBehaviour` with this flag will automatically detach from the `AttachableNode`.
13
+
14
+
_Any of the `AttachableBehaviour.AutoDetach` settings will be invoked on all instances without the need for the owner to synchronize the end result(i.e. detaching) which provides a level of redundancy for edge case scenarios like a player being disconnected abruptly by the host or by timing out or any scenario where a spawned object is being destroyed with the owner or perhaps being redistributed to another client authority in a distributed authority session. Having the ability to select or deselect any of the auto-detach flags coupled with the ability to derive from `AttachableBehaviour` provides additional levels of modularity/customization._
3
15
4
16
## Attaching vs NetworkObject parenting
5
17
@@ -27,82 +39,15 @@ With attaching, a user would create nested `GameObject` children that represent
27
39
By placing an `AttachableBehaviour` component on the NestedChild-PickedUp `GameObject` and an `AttachableNode` component on the TargetNode, a user can then invoke the `AttachableBehaviour.Attach` method while passing in the `AttachableNode` component and the NestedChild-PickedUp `GameObject` will get parented under the TargetNode while also synchronizing this action with all other clients.<br />
The basic functionality of the `AttachableBehaviour` component provides:
35
-
- The ability to assign (make aware) `ComponetController` components from any part of the parent-child hierarchy.
36
-
- Each `ComponentControllerEntry` provides the ability to select when the `ComponentController` should be triggered (via the **Auto Trigger** property) and whether its enabled state should be enabled or disabled upon attaching (via the **Enable On Attach** property). The default setting is to be disabled upon the `AttachableBehaviour` attaching to an `AttachableNode` and enabled upon detaching. When the **Enable On Attach** property is enabled, the `ComponentController` will be set to enabled upon the `AttachableBehaviour` attaching to an `AttachableNode` and disabled upon detaching.
37
-
- The ability to control when an `AttachableBehaviour` component will automatically detach from an `AttachableNode` via the **Auto Detach** property.
38
-
- The **Auto Detach** property can have any combination of the below flags or none (no flags):
39
-
-**On Ownership Changed:** Upon ownership changing, the `AttachableBehaviour` will detach from any `AttachableNode` it is attached to.
40
-
-**On Despawn:** Upon the `AttachableBehaviour` being despawned, it will detach from any `AttachableNode` it is attached to.
41
-
-**On Attach Node Destroy**: Just prior to the `AttachableNode` being destroyed, any attached `AttachableBehaviour` with this flag will automatically detach from the `AttachableNode`.
42
-
43
-
_Any of the `AttachableBehaviour.AutoDetach` settings will be invoked on all instances without the need for the owner to synchronize the end result(i.e. detaching) which provides a level of redundancy for edge case scenarios like a player being disconnected abruptly by the host or by timing out or any scenario where a spawned object is being destroyed with the owner or perhaps being redistributed to another client authority in a distributed authority session. Having the ability to select or deselect any of the auto-detach flags coupled with the ability to derive from `AttachableBehaviour` provides additional levels of modularity/customization._
The simplest component in the bunch, this provides a valid connection point (_i.e. what an `AttachableBehaviour` can attach to_) with the ability to have it automatically detach from any attached `AttachableBehaviour` instances when it is despawned.
Taking the above example into consideration, it would make sense that a user would want to be able to easily control whether a specific component is enabled or disabled when something is attached or detached.
56
-
57
-
As an example:
58
-
59
-
- When the WorldItemRoot is in the "placed in the world" state, it would make sense to disable any `MeshRenderer`, `Collider`, and other components on the NestedChild-PickedUp `GameObject` while enabling similar types of components on the NestedChild-World.
60
-
- When the WorldItemRoot is in the "picked up" state, it would make sense to enable any `MeshRenderer`, `Collider`, and other components on the NestedChild-PickedUp `GameObject` while disabling similar types of components on the NestedChild-World.
61
-
- It would also make sense to synchronize the enabling or disabling of components with all instances.
62
-
63
-
The `ComponentController` provides this type of functionality:
64
-
- Can be used with `AttachableBehaviour` or independently for another purpose.
65
-
- Each assigned component entry can be configured to directly or inversely follow the `ComponentController`'s current state.
66
-
- Each assigned component entry can have an enable and/or disable delay.
67
-
-_When invoked internally by `AttachableBehaviour`, delays are ignored when an `AttachableNode` is being destroyed and the changes are immediate._
68
-
The `ComponentController` could be daisy chained with minimal user script:
69
-
```csharp
70
-
/// <summary>
71
-
/// Use as a component in the ComponentController that will
72
-
/// trigger the Controller (ComponentController).
73
-
/// This pattern can repeat.
74
-
/// </summary>
75
-
publicclassDaisyChainedController : MonoBehaviour
76
-
{
77
-
publicComponentControllerController;
78
-
79
-
privatevoidOnEnable()
80
-
{
81
-
if (!Controller||!Controller.HasAuthority)
82
-
{
83
-
return;
84
-
}
85
-
Controller.SetEnabled(true);
86
-
}
87
-
88
-
privatevoidOnDisable()
89
-
{
90
-
if (!Controller||!Controller.HasAuthority)
91
-
{
92
-
return;
93
-
}
94
-
Controller.SetEnabled(false);
95
-
}
96
-
}
97
-
```
98
-
99
-
### Example of synchronized RPC driven properties
42
+
:::info
43
+
**Example of synchronized RPC driven properties**
100
44
101
45
Both the `AttachableBehaviour` and the `ComponentController` provide an example of using synchronized RPC driven properties in place of `NetworkVariable`. Under certain conditions it is better to use RPCs when a specific order of operations is needed as opposed to `NetworkVariable`s which can update out of order (regarding the order in which certain states were updated) depending upon several edge case scenarios.
102
46
103
47
Under this condition using reliable RPCs will assure the messages are received in the order they were generated while also reducing the latency time between the change and the non-authority instances being notified of the change. Synchronized RPC driven properties only require overriding the `NetworkBehaviour.OnSynchronize` method and serializing any properties that need to be synchronized with late joining players or handling network object visibility related scenarios.
48
+
:::
104
49
105
-
## Usage Walk Through
50
+
## Usage walk through
106
51
107
52
### Introduction
108
53
@@ -118,7 +63,7 @@ The player prefab in the above diagram is not complete, includes the components
118
63
119
64
This diagram has a bit more detail to it and introduces one possible usage of a `ComponentController` and `AttachableBehaviour`. The `ComponentController` will be used to control the enabling and disabling of components and synchronizing this with non-authority instances. The `AttachableBehaviour` resides on the child `AttachedView`'s `GameObject` and will be the catalyst for attaching to a player.
@@ -160,4 +105,9 @@ Upon a `NetworkObject` component being spawned, all associated `NetworkBehaviour
160
105
- and several other edge case scenarios...
161
106
162
107
`AttachableBehaviour` leverages from this "spawn lifetime" relationship to provide another type of "parenting" (attaching) while also taking into consideration these types of edge case scenarios.
This component provides a valid attach point for `AttachableBehaviour` components. It includes the `AttachableNode.DetachOnDespawn` field that, when enabled (the default), it will automatically detach any attached `AttachableBehaviour` instances when the associated `NetworkObject` of the `AttachableNode` is de-spawned.
6
+
7
+
## AttachableBehaviour Usage
8
+
9
+
[A usage example can be found here.](attachablebehaviour.md#usage-walk-through)
A `ComponentController` provides you with the ability to enable or disable one or more components by the authority instance and have those changes synchronized with non-authority/remote instances. It uses a [synchronized RPC driven field approach](../foundational/networkbehaviour-synchronize.md#synchronized-rpc-driven-fields) to synchronize its enabled state of the components it is controlling to assure optimal performance and that the order of operations of changes is relative to other `ComponentController` and/or other `AttachableBehaviour` component instances.
4
+
5
+
The `ComponentController` can be:
6
+
- Used with `AttachableBehaviour` or independently for another purpose.
7
+
- Configured to directly or inversely follow the `ComponentController`'s current state.
8
+
- Configured to have an enable and/or disable delay.
9
+
-_When invoked internally by `AttachableBehaviour`, delays are ignored when an `AttachableNode` is being destroyed and the changes are immediate._
A `ComponentController` can have one or more `ComponentEntry` entries in its **Components** list. Each `ComponentEntry` has some additional fields that you can adjust based on your desired result:
17
+
-**Invert Enabled:** When enabled, this will make the associated component inversely follow the `ComponentControllers` global enabled state. This is useful if you want a set of components to be enabled when the `ComponentController` component's global enable state is set to `false` and for that same set of components to be disabled when the `ComponentController` component's global enable state is set to `true`.
18
+
-**Enable Delay:** When greater than 0 (the default), the component will delay transitioning from a disabled state to an enabled state by the amount of time (in seconds) specified.
19
+
-**Disable Delay:** When greater than 0 (the default), the component will delay transitioning from an enabled state to a disabled state by the amount of time (in seconds) specified.
20
+
-**Component:** The component to control and synchronize its enabled state.
21
+
22
+
Both delay values (Enable & Disable) has many uses, but an example would be to prevent a `MeshRenderer` from being enabled prior to other specific events like avoiding it from rendering for a few frames while the attachable is positioned.
23
+
24
+
25
+
## Examples
26
+
27
+
### Independent Usage
28
+
29
+
While `ComponentController` can be used with an `AttachableBehaviour` without writing any script, you might find that it can be used for many other purposes. Below is a pseudo example where a `ComponentController` would have its synchronized enabled state updated when the `DaisyChainedController` is either enabled or disabled.
30
+
31
+
```csharp
32
+
/// <summary>
33
+
/// Use as a component in the ComponentController that will
34
+
/// trigger the Controller (ComponentController).
35
+
/// This pattern can repeat/be daisy chained.
36
+
/// </summary>
37
+
publicclassDaisyChainedController : MonoBehaviour
38
+
{
39
+
publicComponentControllerController;
40
+
41
+
privatevoidOnEnable()
42
+
{
43
+
if (!Controller||!Controller.HasAuthority)
44
+
{
45
+
return;
46
+
}
47
+
Controller.SetEnabled(true);
48
+
}
49
+
50
+
privatevoidOnDisable()
51
+
{
52
+
if (!Controller||!Controller.HasAuthority)
53
+
{
54
+
return;
55
+
}
56
+
Controller.SetEnabled(false);
57
+
}
58
+
}
59
+
```
60
+
The above component could be arranged to create a chained sequence of components when the root `DaisyChainedController` component is enabled or disabled. Such a sequence could look like:
61
+
62
+
- DaisyChainedController-A
63
+
- Controller
64
+
- Points to DaisyChainedController-B
65
+
- DaisyChainedController-B
66
+
- Controller
67
+
- Points to DaisyChainedController-C
68
+
- DaisyChainedController-C
69
+
- Controller
70
+
71
+
When DaisyChainedController-A is enabled, then a sequence of events would occur where DaisyChainedController-B and DaisyChainedController-C would be enabled. The same sequence of events would occur when DaisyChainedController-A was then disabled.
72
+
73
+
### AttachableBehaviour Usage
74
+
75
+
The `AttachableBehaviour` can be assigned one or more component controllers that will be invoked, depending upon configuration, when the `AttachableBehaviour` is attached and detached from an `AttachableNode`. You can find the [usage example with an `AttachableBehaviour` here.](attachablebehaviour.md#usage-walk-through)
76
+
77
+
:::info
78
+
**Example of synchronized RPC driven properties**
79
+
80
+
Both the `AttachableBehaviour` and the `ComponentController` provide an example of using synchronized RPC driven properties in place of `NetworkVariable`. Under certain conditions it is better to use RPCs when a specific order of operations is needed as opposed to `NetworkVariable`s which can update out of order (regarding the order in which certain states were updated) depending upon several edge case scenarios.
81
+
82
+
Under this condition using reliable RPCs will assure the messages are received in the order they were generated while also reducing the latency time between the change and the non-authority instances being notified of the change. Synchronized RPC driven properties only require overriding the `NetworkBehaviour.OnSynchronize` method and serializing any properties that need to be synchronized with late joining players or handling network object visibility related scenarios.
|**[AttachableBehaviour](attachablebehaviour.md)**| Provides an alternative to `NetworkObject` parenting. (wip)|
8
-
|**AttachableNode**| Target parent for an `AttachableBehaviour`. (wip)|
9
-
|**ComponentController**| Provides the synchronization of and control over enabling or disabling objects. (wip)|
7
+
|**[AttachableBehaviour](attachablebehaviour.md)**| Provides an alternative to `NetworkObject` parenting. This section includes a usage example with `AttachableBehaviour`, `AttachableNode`, and `ComponentController`.|
8
+
|**[AttachableNode](attachablenode.md)**| Target parent for an `AttachableBehaviour`. |
9
+
|**[ComponentController](componentcontroller.md)**| Provides the synchronization of and control over enabling or disabling objects. |
10
10
|**[NetworkAnimator](networkanimator.md)**| The `NetworkAnimator` component provides you with a fundamental example of how to synchronize animations during a network session. Animation states are synchronized with players joining an existing network session and any client already connected before the animation state changing. |
11
11
|**[NetworkTransform](networktransform.md)**|[NetworkTransform](https://docs.unity3d.com/Packages/com.unity.netcode.gameobjects@latest?subfolder=/api/Unity.Netcode.Components.NetworkTransform.html) is a concrete class that inherits from [NetworkBehaviour](../foundational/networkbehaviour.md) and synchronizes [Transform](https://docs.unity3d.com/Manual/class-Transform.html) properties across the network, ensuring that the position, rotation, and scale of a [GameObject](https://docs.unity3d.com/Manual/working-with-gameobjects.html) are replicated to other clients. |
12
12
|**[Physics](../../advanced-topics/physics.md)**| Netcode for GameObjects has a built in approach which allows for server-authoritative physics where the physics simulation only runs on the server. |
0 commit comments