feat: AttachableBehaviour and ComponentController

[NoelStephensUnity]

Depends on

This PR depends upon the fix for the SendTo.NotMe fix in #3551.

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.

Documentation Update

New Documentation

AttachableBehaviour

Network Components Section Update

New Foundational Components Section

New Helper Components Section

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.

Documentation

• Includes documentation updates:
  • Added new documentation section.
  • Refactored network components section.
  • Fixed some image links.

Testing & QA

Functional Testing

Manual testing :

• Manual testing done
  • Asteroids AttachableBehaviour manual test PR-42

Automated tests:

• Covered by existing automated tests
• Covered by new automated tests

Does the change require QA team to:

• Review automated tests?
• Execute manual tests?

If any boxes above are checked, please add QA as a PR reviewer.

Backport

This is a v2.x only feature.

[jabbacakes]

Okay I just pushed a large docs commit, hear me out:

• The only changes that need in-depth review are those to the three new helper components, it's mostly just tweaking wording, removing 'we' and other colloquialisms that are no bueno in the docs.
• I also did a bunch of mass changes to convert all component names into regular, non-monospace. We've been inconsistent about that for a while, and I checked the style guide and it said do it that way. So FYI but you can ignore those changes throughout the wider docs, I just kept bumping into the inconsistency and it was driving me barmy.
  • For future reference, it's regular CamelCase for component names, and monospace for methods e.g. component.method.
• Changed from foundational components -> core components, as discussed with Noel.

All in all, I think this is a really good body of doc to launch this feature with, and we can finesse it if/when we get user feedback about it.

[NoelStephensUnity]

@jabbacakes
I am still seeing some of the tail end portions of each section getting clipped by the Unity copyright footer.

Is this just the doc tool when building local or is this an issue we need to resolve?

[EmandM]

🥇

[jabbacakes]

Alrighty that's my review of your latest changes done @NoelStephensUnity

Couple of mass changes again, because apparently I can't help myself:

• Changing all instances of de-spawn to despawn for consistency
• Same with pre-spawn to prespawn

Also re: the footer overlap issue, that's an oddity of the local docs build and doesn't recur on the live package sites, so wouldn't worry about it.

[Mechitary]

thanks Noel, it looks like these components will alleviate a lot of unneeded complexity.

With the AttachableBehaviour component, can I parent a network animator that has no network object (i.e. a prefab with its own network animator) to an already spawned network object? Current it does not work without a network object and network animator within the same hierarchy (i.e. prefab), due to how network animator is initialized in its Awake.

mech

[NoelStephensUnity]

thanks Noel, it looks like these components will alleviate a lot of unneeded complexity.

With the AttachableBehaviour component, can I parent a network animator that has no network object (i.e. a prefab with its own network animator) to an already spawned network object? Current it does not work without a network object and network animator within the same hierarchy (i.e. prefab), due to how network animator is initialized in its Awake.

mech

For the attachable, you still need to have another network prefab that would have a nested child with the AttachableBehaviour component and on that child or on a child nested under it the NetworkAnimator.

For now, you can look at the updated documentation to see more about this.

But both AttachableBehaviour and ComponentController should help simplify things a bit.

In regards to NetworkAnimator, take a look at #3586 and then (if you don't mind) posting in that PR what you are trying to do with NetworkAnimator and I will see if that is something we can work into that PR as well.