You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
feat: AttachableBehaviour and ComponentController (#3518)
## 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]>
This example provides you with the fundamental building blocks for smooth synchronized transitions between two non-rigidbody based objects. This includes transitioning from world to local, local to world, and local to local transform spaces.
4
+
This example provides you with the fundamental building blocks for smooth synchronized transitions between two non-rigidbody based objects. This includes transitioning from world to local, local to world, and local to local transform spaces.
The `CharacterController` component is assigned to the `PlayerNoRigidbody` player prefab. It includes a `MoverScriptNoRigidbody` that handles all of the player's motion and includes some additional "non-rigidbody to non-rigidbody" collision handling logic that is applied when a player bumps into a rotation and/or moving body. The player prefab includes a child "PlayerBallPrime" that rotates around the player in local space (nested `NetworkTransform`), and the "PlayerBallPrime" has 3 children ("PlayerBallChild1-3") that each rotates around a different axis of the "PlayerBallPrime". While the end resulting effect is kind of cool looking, they provide a point of reference as to whether there is any deviation of each child's given axial path relative to each parent level. Additionally, it shows how tick synchronized nested `NetworkTransform` components keep synchronized with their parent and how that persists when the parent is parented or has its parent removed.
8
+
The `CharacterController` component is assigned to the `PlayerNoRigidbody` player prefab. It includes a `MoverScriptNoRigidbody` that handles all of the player's motion and includes some additional "non-rigidbody to non-rigidbody" collision handling logic that is applied when a player bumps into a rotation and/or moving body. The player prefab includes a child "PlayerBallPrime" that rotates around the player in local space (nested NetworkTransform), and the "PlayerBallPrime" has 3 children ("PlayerBallChild1-3") that each rotates around a different axis of the "PlayerBallPrime". While the end resulting effect is kind of cool looking, they provide a point of reference as to whether there is any deviation of each child's given axial path relative to each parent level. Additionally, it shows how tick synchronized nested NetworkTransform components keep synchronized with their parent and how that persists when the parent is parented or has its parent removed.
Copy file name to clipboardExpand all lines: Examples/OverridingScenesAndPrefabs/Readme.md
+15-15Lines changed: 15 additions & 15 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -5,10 +5,10 @@ _Supports using the client-server and distributed authority network topologies._
5
5
6
6
This example, based on the [Netcode for GameObjects Smooth Transform Space Transitions](https://github.com/Unity-Technologies/com.unity.netcode.gameobjects/tree/example/server-client-unique-scenes-and-prefabs/Examples/CharacterControllerMovingBodies), provides and overview of how to use:
7
7
-[`NetworkPrefabHandler`](https://docs.unity3d.com/Packages/[email protected]/api/Unity.Netcode.NetworkPrefabHandler.html) as a way to dynamically control overriding network prefabs and how they are instantiated.
8
-
- For this example, the prefab handler is overriding the player prefab.
8
+
- For this example, the prefab handler is overriding the player prefab.
9
9
-*You will only see the end result of this portion of the example by running a server instance (i.e. not host) as that will create instances of the ServerPlayer network prefab instead of the ClientPlayer network prefab.*
10
-
-[`NetworkSceneManager.SetClientSynchronizationMode`](https://docs.unity3d.com/Packages/[email protected]/api/Unity.Netcode.NetworkSceneManager.html#Unity_Netcode_NetworkSceneManager_SetClientSynchronizationMode_UnityEngine_SceneManagement_LoadSceneMode_) to change the default client synchronization mode (SingleMode) to an additive client synchronization mode.
11
-
- Additive client synchronization mode will prevent already existing preloaded scenes from being unloaded and will use them, as opposed to reloading the same scene, during a client's initial synchronization.
10
+
-[`NetworkSceneManager.SetClientSynchronizationMode`](https://docs.unity3d.com/Packages/[email protected]/api/Unity.Netcode.NetworkSceneManager.html#Unity_Netcode_NetworkSceneManager_SetClientSynchronizationMode_UnityEngine_SceneManagement_LoadSceneMode_) to change the default client synchronization mode (SingleMode) to an additive client synchronization mode.
11
+
- Additive client synchronization mode will prevent already existing preloaded scenes from being unloaded and will use them, as opposed to reloading the same scene, during a client's initial synchronization.
12
12
-*This is a server-side only setting that gets sent to the clients during the initial synchronization process.*
13
13
-[`NetworkSceneManager.VerifySceneBeforeLoading`](https://docs.unity3d.com/Packages/[email protected]/api/Unity.Netcode.NetworkSceneManager.html#Unity_Netcode_NetworkSceneManager_VerifySceneBeforeLoading) in order to control what scenes the server will include when sending the synchronization message to newly connecting clients.
14
14
@@ -19,14 +19,14 @@ This example uses unity services. Upon loading the project for the first time, y
19
19
## Terminology
20
20
21
21
### Shared Scenes
22
-
These are scenes that will be synchronized between a server or session owner and used when a client runs through the initial synchronization process.
23
-
- You can populate these scenes with in-scene placed or dynamically spawned NetworkObjects.
22
+
These are scenes that will be synchronized between a server or session owner and used when a client runs through the initial synchronization process.
23
+
- You can populate these scenes with in-scene placed or dynamically spawned NetworkObjects.
24
24
- These scenes **must be** within the scenes in build list.
25
25
26
26
### Local Scenes
27
-
These are scenes that are always only local to the application instances (server or client) and will not be synchronized.
28
-
- You should not populate these scenes with NetworkObjects.
29
-
-However, this example includes one of several ways you can associate a `MonoBehaviour` with a `NetworkBehaviour`.
27
+
These are scenes that are always only local to the application instances (server or client) and will not be synchronized.
28
+
- You should not populate these scenes with NetworkObjects.
29
+
-However, this example includes one of several ways you can associate a `MonoBehaviour` with a NetworkBehaviour.
30
30
- These scenes can be dynamically created, included in the scenes in build list, or be an addressable loaded at some point prior to connecting or while connected to a session.
31
31
32
32
## Client Synchronization and Scene Validation
@@ -54,16 +54,16 @@ The first scene loaded. Contains a `NetworkManagerBootstrapper` in-scene placed
Handles the pre-network session menu interface along with connect and disconnect events. Since it is derived from `NetworkManager`, it also defines the network session configuration (i.e. `NetworkConfig`). The `NetworkManagerBootstrapper` in-scene placed `GameObject` gets loaded into the DDOL scene automatically and will persist throughout the application life time. This derived class requires the `SceneBootstrapLoader` component.
57
+
Handles the pre-network session menu interface along with connect and disconnect events. Since it is derived from NetworkManager, it also defines the network session configuration (i.e. `NetworkConfig`). The `NetworkManagerBootstrapper` in-scene placed `GameObject` gets loaded into the DDOL scene automatically and will persist throughout the application life time. This derived class requires the `SceneBootstrapLoader` component.
58
58
59
59
#### Scene Bootstrap Loader (component)
60
60

61
61
62
-
This component handles preloading scenes for both the client(s) and server. Upon being started, the `NetworkManagerBootstrapper` component will invoke `SceneBootstrapLoader.LoadMainMenu` method that kicks off the scene preloading process.
62
+
This component handles preloading scenes for both the client(s) and server. Upon being started, the `NetworkManagerBootstrapper` component will invoke `SceneBootstrapLoader.LoadMainMenu` method that kicks off the scene preloading process.
63
63
-**Default Active Scene Asset:** There is always an active scene. For this example, the default active scene is the same on both the client and server relative properties. *The active scene is always (and should always) be a "shared scene".*
64
64
- This could represent a lobby or network session main menu (i.e. create or join session).
65
65
- Both the client and the server preload this scene prior to starting a network session.
66
-
-**Local Scene Assets:** There could be times where you want to load scenes specific to the `NetworkManager` instance type (i.e. client, host, or server).
66
+
-**Local Scene Assets:** There could be times where you want to load scenes specific to the NetworkManager instance type (i.e. client, host, or server).
67
67
- These scenes are not synchronized by a server (client-server) or session owner (distributed authority).
68
68
- Having different locally loaded scenes is typically more common in a client-server network topology.
69
69
- In a distributed authority network topology, it is more common to keep all scenes synchronized but you might want to load non-synchronized scenes (i.e. menu interface for settings etc).
@@ -72,11 +72,11 @@ This component handles preloading scenes for both the client(s) and server. Upon
72
72
- If the server synchronizes any scenes from the share scene assets with a client that already has those scene loaded, then those locally loaded scenes on the client side will be used during synchronization.
73
73
- Depending upon how many scenes you want to synchronize and/or how large one or more scenes are, preloading scenes can reduce synchronization time for clients.
74
74
The `NetworkManagerBootstrapper` uses the `SceneBootstrapLoader` component to start the creation or joining of a network session. The logical flow looks like:
75
-
-`NetworkManagerBootstrapper` invokes `SceneBootstrapLoader.StartSession` when you click one of the (very simple) main menu buttons and passes in the mode/type of `NetworkManager` to start.
76
-
- Based on the `NetworkManager` type being started, the `SceneBootstrapLoader` will then:
75
+
-`NetworkManagerBootstrapper` invokes `SceneBootstrapLoader.StartSession` when you click one of the (very simple) main menu buttons and passes in the mode/type of NetworkManager to start.
76
+
- Based on the NetworkManager type being started, the `SceneBootstrapLoader` will then:
77
77
- Load the default active scene using the `UnityEngine.SceneManagement.SceneManager`.
78
78
- Load the local scenes using the `UnityEngine.SceneManagement.SceneManager`.
79
-
- Then it will create or join a network session by either starting the `NetworkManager` or connecting to the sesssion via multiplayer services.
79
+
- Then it will create or join a network session by either starting the NetworkManager or connecting to the sesssion via multiplayer services.
80
80
-_Server or Session Owner only:_
81
81
- If any, load the shared (i.e. synchronized) scene assets using the `NetworkSceneManager`
82
82
@@ -87,7 +87,7 @@ This `MonoBehaviour` component implements the `INetworkPrefabInstanceHandler` in
87
87
- Network Prefab: This is the network prefab that you want to override. In this example, it is what is used to spawn a server-side player prefab and is what is defined within the `NetworkManagerBootstrapper` component.
88
88
- Network Prefab Override: This is what is used to spawn a player prefab on the client-side.
89
89
90
-
At runtime the local `NetworkManager` instance is a client/host or server and will spawn either the ClientPlayer or ServerPlayer prefab. The `NetworkPrefabOverrideHandler` does not need to be a `NetworkBehaviour` and sometimes (especially for overriding the player prefab) it is better to register prefab handlers prior to starting the `NetworkManager`.
90
+
At runtime the local NetworkManager instance is a client/host or server and will spawn either the ClientPlayer or ServerPlayer prefab. The `NetworkPrefabOverrideHandler` does not need to be a NetworkBehaviour and sometimes (especially for overriding the player prefab) it is better to register prefab handlers prior to starting the NetworkManager.
91
91
92
92
## Input Controls
93
93
The following is a list of the input controls used in this project:
0 commit comments