feat: AttachableBehaviour and ComponentController

[NoelStephensUnity]

AttachableBehaviour and Support Components

The purpose of this PR (feat) is to address the complexity of "picking up" or "dropping" an item in the world which can become complex when using the traditional NetworkObject parenting pattern. In this PR there are three primary components added to help reduce this complexity:

• 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.
• AttachableNode: This component is required by the AttachableBehaviour component in order to be able to attach (i.e. parent) to another GameObject without having to parent the entire NetworkObject component the AttachableBehaviour component is associated with.
• ComponentController: This component provides users the ability to synchronize the enabling or disabling of any Object derived component that has an enabled property.

This PR also incorporates a new "Helpers" subfolder under the NGO components folder where additional helper components will live.

Attaching vs NetworkObject parenting

Fundamentally, attaching is another form of synchronized (i.e. netcode) parenting that does not require one to use the traditional NetworkObject parenting. Attaching a child GameObject nested under a NeworkObject (really the GameObject the NetworkObject component belongs to) will only take the child GameObject and parent it under another child GameObject nested under or on the same GameObject with a different NeworkObject.

NetworkObject parenting

The traditional approach has been to spawn two network prefab instances:

Then parent one instance under the other:

This is simple enough for many scenarios, but can become cumbersome under more specific scenarios where a user might want to have a "world" version of the item and a "picked up" version of the item.

Attaching

With attaching, a user would create nested GameObject children that represent the item when it is picked up and when it is dropped/placed somewhere in the scene (i.e. world).

• The WorldItemRoot is where the NetworkObject component is placed.
• The NestedChild-World contains the components needed for the item when it is placed in the world.
• The NestedChild-PickedUp contains the components needed for the item when it is picked up by a player.

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.

ComponentController

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. As an example:

• 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.
• 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.
• It would also make sense to synchronize the enabling or disabling of components with all instances.

The ComponentController provides this type of functionality.

Example of synchronized RPC driven properties

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 NetworkVariables which can update out of order (regarding the order in which certain states were updated) depending upon several edge case scenarios.

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.

NetworkBehaviour.OnNetworkPreDespawn

Added another virtual method to NetworkBehaviour, OnNetworkPreDespawn, that is invoked before running through the despawn sequence for the NetworkObject and all NetworkBehaviour children of the NetworkObject being despawned. This provides an opportunity to do any kind of cleanup up or last micro-second state updates prior to despawning.

Changelog

• Added: AttachableBehaviour helper component to provide an alternate approach to parenting items without using the NetworkObject parenting.
• Added : AttachableNode helper component that is used by AttachableBehaviour as the target node for parenting.
• Added: ComponentController helper component that can be used to synchronize the enabling and disabling of components and can be used in conjunction with AttachableBehaviour.
• Added: NetworkBehaviour.OnNetworkPreDespawn that is invoked before running through the despawn sequence for the NetworkObject and all NetworkBehaviour children of the NetworkObject being despawned.

Testing and Documentation

• Includes two new integration tests:
  • AttachableBehaviourTests
  • ComponentControllerTests
• No internal API documentation changes or additions were necessary.
• Requires public documentation that provides usage and examples (wip).

Backport

These new helper components are currently only targeting v2.x.