Skip to content

Commit 5f9463a

Browse files
NoelStephensUnityEmandMjabbacakesnetcode-ci-service
authored
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]>
1 parent 42002f9 commit 5f9463a

File tree

101 files changed

+3562
-835
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

101 files changed

+3562
-835
lines changed

Examples/CharacterControllerMovingBodies/Readme.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,11 @@
11
# Netcode for GameObjects Smooth Transform Space Transitions
22
## Non-Rigidbody CharacterController Parenting with Moving Bodies
33
![image](https://github.com/user-attachments/assets/096953ca-5d7d-40d5-916b-72212575d258)
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.
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.
55

66
### The `CharacterController`
77
![image](https://github.com/user-attachments/assets/13c627bd-920d-40c8-8947-69aa37b44ebf)
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.
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.
99

1010
### Rotating Bodies
1111
#### StationaryBodyA&B

Examples/OverridingScenesAndPrefabs/Readme.md

Lines changed: 15 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -5,10 +5,10 @@ _Supports using the client-server and distributed authority network topologies._
55

66
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:
77
- [`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.
99
- *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.
1212
- *This is a server-side only setting that gets sent to the clients during the initial synchronization process.*
1313
- [`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.
1414

@@ -19,14 +19,14 @@ This example uses unity services. Upon loading the project for the first time, y
1919
## Terminology
2020

2121
### 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.
2424
- These scenes **must be** within the scenes in build list.
2525

2626
### 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.
3030
- 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.
3131

3232
## Client Synchronization and Scene Validation
@@ -54,16 +54,16 @@ The first scene loaded. Contains a `NetworkManagerBootstrapper` in-scene placed
5454
#### NetworkManager Bootstrapper (component)
5555
![image](Images/NetworkManagerBootstrapperProperties.png)
5656

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

5959
#### Scene Bootstrap Loader (component)
6060
![image](Images/SceneBootstrapLoader.png)
6161

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.
6363
- **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".*
6464
- This could represent a lobby or network session main menu (i.e. create or join session).
6565
- 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).
6767
- These scenes are not synchronized by a server (client-server) or session owner (distributed authority).
6868
- Having different locally loaded scenes is typically more common in a client-server network topology.
6969
- 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
7272
- 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.
7373
- 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.
7474
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:
7777
- Load the default active scene using the `UnityEngine.SceneManagement.SceneManager`.
7878
- 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.
8080
- _Server or Session Owner only:_
8181
- If any, load the shared (i.e. synchronized) scene assets using the `NetworkSceneManager`
8282

@@ -87,7 +87,7 @@ This `MonoBehaviour` component implements the `INetworkPrefabInstanceHandler` in
8787
- 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.
8888
- Network Prefab Override: This is what is used to spawn a player prefab on the client-side.
8989

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

9292
## Input Controls
9393
The following is a list of the input controls used in this project:

0 commit comments

Comments
 (0)