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.

AttachableBehaviour

The basic functionality of the AttachableBehaviour component provides:

• The ability to assign (make aware) ComponetController components from any part of the parent-child hierarchy.
  • 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.
• The ability to control when an AttachableBehaviour component will automatically detach from an AttachableNode via the Auto Detach property.
  • The Auto Detach property can have any combination of the below flags or none (no flags):
    • On Ownership Changed: Upon ownership changing, the AttachableBehaviour will detach from any AttachableNode it is attached to.
    • On Despawn: Upon the AttachableBehaviour being despawned, it will detach from any AttachableNode it is attached to.
    • On Attach Node Destroy: Just prior to the AttachableNode being destroyed, any attached AttachableBehaviour with this flag will automatically detach from the AttachableNode.

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.

AttachableNode

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.

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 when something is attached or detached.

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:

• Can be used with AttachableBehaviour or independently for another purpose.
• Each assigned component entry can be configured to directly or inversely follow the ComponentController's current state.
• Each assigned component entry can have an enable and/or disable delay.
  • When invoked internally by AttachableBehaviour, delays are ignored when an AttachableNode is being destroyed and the changes are immediate.

The ComponentController could be daisy chained with minimal user script:

/// <summary>
/// Use as a component in the ComponentController that will
/// trigger the Controller (ComponentController).
/// This pattern can repeat.
/// </summary>
public class DaisyChainedController : MonoBehaviour
{
    public ComponentController Controller;

    private void OnEnable()
    {
        if (!Controller || !Controller.HasAuthority)
        {
            return;
        }
        Controller.SetEnabled(true);
    }

    private void OnDisable()
    {
        if (!Controller || !Controller.HasAuthority)
        {
            return;
        }
        Controller.SetEnabled(false);
    }
}

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

This is a v2.x only feature.