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]

🥇