## 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](https://github.com/Unity-Technologies/com.unity.netcode.gameobjects/blob/feat/attachable-networkbehaviour-and-object-controller/com.unity.netcode.gameobjects/Documentation~/components/Helpers/attachablebehaviour.md)

### Network Components Section Update
<img width="957" height="589" alt="image"
src="https://github.com/user-attachments/assets/48e9edaf-cf8d-4a61-b0b9-c0369bb8f26f"
/>

### New Foundational Components Section
<img width="1145" height="831" alt="image"
src="https://github.com/user-attachments/assets/f3dc71b4-cd07-4884-a5a6-fc7c78e9e24c"
/>

### New Helper Components Section
<img width="1015" height="537" alt="image"
src="https://github.com/user-attachments/assets/407636b8-9085-4b80-8bb4-d55b18512ce1"
/>

## 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.

<!-- Add short version of the JIRA ticket to the PR title (e.g. "feat:
new shiny feature [MTT-123]") -->

## 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.


<!-- Uncomment and mark items off with a * if this PR deprecates any
API:
### Deprecated API
- [ ] An `[Obsolete]` attribute was added along with a `(RemovedAfter
yyyy-mm-dd)` entry.
- [ ] An [api updater] was added.
- [ ] Deprecation of the API is explained in the CHANGELOG.
- [ ] The users can understand why this API was removed and what they
should use instead.
-->

## Documentation
[//]: # (
This section is REQUIRED and should mention what documentation changes
were following the changes in this PR.
We should always evaluate if the changes in this PR require any
documentation changes.
)

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


## Testing & QA
[//]: #  (
This section is REQUIRED and should describe how the changes were tested
and how should they be tested when Playtesting for the release.
It can range from "edge case covered by unit tests" to "manual testing
required and new sample was added".
Expectation is that PR creator does some manual testing and provides a
summary of it here.)

### Functional Testing
[//]: # (If checked, List manual tests that have been performed.)
_Manual testing :_
- [X] `Manual testing done`
- Asteroids `AttachableBehaviour` manual test
[PR-42](https://github.cds.internal.unity3d.com/unity/Asteroids-CMB-NGO-Sample/pull/42)

_Automated tests:_
- [ ] `Covered by existing automated tests`
- [X] `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.

<!-- If this is a backport:
 - Add the following to the PR title: "\[Backport\] ..." .
 - Link to the original PR.
If this needs a backport - state this here
If a backport is not needed please provide the reason why.
If the "Backports" section is not present it will lead to a CI test
failure.
-->

---------

Co-authored-by: Emma <[email protected]>
Co-authored-by: Amy Reeve <[email protected]>
Co-authored-by: Unity Netcode CI <[email protected]>

## Purpose of this PR

The regex we used to validate hostnames did not accept single words as
valid hostnames. But single words _can_ be valid hostnames. The most
common is of course "localhost" but one can edit one's hosts file to
define any word as something the local resolver will resolve to an IP
address.

This PR addresses this by removing any validation of the provided
hostname. We could modify the validity check to accept single words too,
but the regex is pretty indigestible already and it's simpler to just
let the resolver fail if the user provided garbage. UTP will signal this
through a disconnection event with an appropriate reason (which we'll be
able to map to a nice error message once [this
PR](#3551)
lands).

While I was at it, I also made a few cleanups and improvements:

- Removed the `UTP_TRANSPORT_2_4_ABOVE` define. NGO depends on UTP 2.4.0
so it can be safely assumed that users will have it installed. No need
to conditionally compile the code that depends on it.
- Added a test that establishes a connection using hostname resolution.
- Simplified the logic around connections and avoid bypassing the
`Connect` method when connecting to a hostname.
- Deprecated `ConnectionAddressData.ServerEndPoint`. We don't use it
anymore, it doesn't work with hostnames, and it's not providing any
value over just calling `NetworkEndpoint.Parse`. And worst of all: its
capitalization of "endpoint" doesn't match what we use elsewhere.
- Modified the listen address logic so that if a domain name is used, by
default if remote connections are allowed we will listen on :: (the IPv6
"any" address) instead of 0.0.0.0. This can still be overridden using
`SetConnectionData`. The reason for this change is that the resolver in
UTP prioritizes IPv6 addresses over IPv4. So if we listen on IPv4 by
default, we're likely to get issues if the resolver then ends up with an
IPv6 address. In current versions of UTP for instance, this causes
errors on Windows (a fix is on the way). I'm looking into changing the
behavior of the resolver to prefer IPv4, but that's an engine change so
might take a while to land. In the meantime defaulting to IPv6 seems
like the best approach.

### Changelog

- Fixed: Fixed an issue where `UnityTransport` would not accept single
words as valid hostnames (notably "localhost").
- Changed: Marked `UnityTransport.ConnectionAddressData.ServerEndPoint`
as obsolete. It can't work when using hostnames as the server address,
and its functionality can easily be replicated using
`NetworkEndpoint.Parse`.

## Documentation

No documentation changes or additions were necessary.

## Testing & QA

Tested with manual and automated tests.

## Backport

Hostname resolution is only supported in UTP 2.4+ and Unity 6.1+, so no
backport necessary.

---------

Co-authored-by: Michał Chrobot <[email protected]>
Co-authored-by: Noel Stephens <[email protected]>