feat: add Unity CLI commands for Netcode for GameObjects (MTT-16534)

com.unity.netcode.gameobjects/CHANGELOG.md

@@ -10,6 +10,7 @@ Additional documentation and release notes are available at [Multiplayer Documen
 
 ### Added
 
+- Added Unity CLI commands (`netcode.gameobjects` groups) to set up NetworkManagers and network prefabs, start and stop sessions, inspect clients and spawned objects, spawn, despawn and change ownership, simulate network conditions and sample network traffic. They are available when the project has `com.unity.pipeline` 0.9.0-exp.1 or later. (#4210)
 - Added alignment of the Netcode for Entities tick rates with `NetworkConfig.TickRate` when a session carrying `GhostObject` prefabs is started, so `GhostObject` updates land on the same interval as the rest of Netcode for GameObjects. (#4144)
 - Added `NetworkConfig.AutoConfigureSnapshotSize`, enabled by default, which sets the Netcode for Entities snapshot packet size to 4096 bytes when a session carrying `GhostObject` prefabs is started. Netcode for Entities defaults to a single MTU, which updates `GhostObject`s well below the tick rate at the instance counts Netcode for GameObjects projects typically run. Disable it to manage the value yourself. (#4144)
 

com.unity.netcode.gameobjects/Documentation~/TableOfContents.md

@@ -103,6 +103,7 @@
   * [Logging](basics/logging.md)
   * [Techniques and tricks for debugging multiplayer games](tutorials/testing/techniques_and_tricks_for_debugging_multiplayer_games.md)
   * [Command-line helper](tutorials/command-line-helper.md)
+  * [Unity CLI commands](unity-cli-commands.md)
   * [Troubleshooting](troubleshooting/troubleshooting.md)
   * [Error messages](troubleshooting/error-messages.md)
 * [FAQ](learn/faq.md)

com.unity.netcode.gameobjects/Documentation~/testing-debugging.md

@@ -10,5 +10,6 @@ Understand how to set up session management in Netcode for GameObjects.
 | **[Logging](basics/logging.md)** | In a multiplayer game, clients might get disconnected from the server for a variety of reasons (such as network issues or application/device crashes). For those reasons, you might want to allow your players to reconnect to the game. |
 | **[Techniques and tricks for debugging multiplayer games](tutorials/testing/techniques_and_tricks_for_debugging_multiplayer_games.md)** | In a multiplayer game, clients might get disconnected from the server for a variety of reasons (such as network issues or application/device crashes). For those reasons, you might want to allow your players to reconnect to the game. |
 | **[Command-line helper](tutorials/command-line-helper.md)** | In a multiplayer game, clients might get disconnected from the server for a variety of reasons (such as network issues or application/device crashes). For those reasons, you might want to allow your players to reconnect to the game. |
+| **[Unity CLI commands](unity-cli-commands.md)** | Drive Netcode for GameObjects from the command line, CI, or an AI agent: set up NetworkManagers and prefabs, run sessions, inspect clients and objects, and simulate network conditions. |
 | **[Troubleshooting](troubleshooting/troubleshooting.md)** | In a multiplayer game, clients might get disconnected from the server for a variety of reasons (such as network issues or application/device crashes). For those reasons, you might want to allow your players to reconnect to the game. |
 | **[Error messages](troubleshooting/error-messages.md)** | In a multiplayer game, clients might get disconnected from the server for a variety of reasons (such as network issues or application/device crashes). For those reasons, you might want to allow your players to reconnect to the game. |

com.unity.netcode.gameobjects/Documentation~/unity-cli-commands.md

@@ -0,0 +1,87 @@
+# Unity CLI commands
+
+Drive Netcode for GameObjects from the command line, a CI job, or an AI agent with the [Unity CLI](https://docs.unity.com/en-us/unity-cli/unity-cli). You can use commands to set up a NetworkManager and network prefabs, start and stop sessions, inspect connected clients and spawned objects, simulate poor network conditions, and sample network traffic.
+
+To use Unity CLI commands with Netcode for GameObjects, you must install the [Unity Pipeline package](https://docs.unity.com/en-us/unity-cli/unity-pipeline/unity-pipeline-package) (version 0.9.0-exp.1 or later). Without it, the commands aren't compiled. Run them against an open Unity Editor as `unity command <group> <name> [arguments]`. `unity command --list` shows every command with its arguments.
+
+## Typical workflow
+
+```
+unity command netcode.gameobjects create_network_manager
+unity command netcode.gameobjects make_prefab --prefab Assets/Prefabs/Player.prefab
+unity command netcode.gameobjects.config set --field player_prefab --value Assets/Prefabs/Player.prefab
+unity command editor.playmode start
+unity command netcode.gameobjects.session start --mode Host
+unity command netcode.gameobjects.session wait_ready
+unity command netcode.gameobjects list_objects
+```
+
+To test with several players, use [Multiplayer Play Mode](https://docs.unity3d.com/Packages/com.unity.multiplayer.playmode@latest) scenarios (`editor.playmode start_scenario`) and run the commands against each player's Editor with `unity command --project-path <player project path>`.
+
+## Commands
+
+### netcode.gameobjects
+
+| **Command** | **Description** |
+| :--- | :--- |
+| `status` | Each NetworkManager: role (host, server, client), connection state, local client id, topology, session owner, client and object counts, ticks, transport address, and whether the session runs hybrid prefabs. |
+| `list_clients` | Connected clients with their player object, owned object count and round trip time. |
+| `list_objects` | Spawned NetworkObjects as this peer sees them, filtered by name or owner. |
+| `get_object` | One NetworkObject: owner, authority, ownership flags and who can change them, observers and NetworkBehaviours. |
+| `spawn` | Instantiate and spawn a registered network prefab at a position, optionally for an owner or as a player object. |
+| `despawn` | Despawn a NetworkObject, optionally keeping the GameObject. |
+| `change_owner` | Give a NetworkObject to another client, following the topology's ownership rules. |
+| `create_network_manager` | Add a NetworkManager with a UnityTransport to the active scene. |
+| `list_prefabs` | Network prefabs lists with their prefabs, and the lists and player prefab each NetworkManager uses. |
+| `register_prefab` | Add a network prefab to a network prefabs list and save the list. |
+| `make_prefab` | Add a NetworkObject to a prefab's root and report its prefab id hash. |
+| `audit` | Find setup problems that otherwise show when a session starts: in NetworkManagers (transport, topology, prefab lists, player prefab, hybrid prefab requirements) and in network prefabs (NetworkBehaviours without a NetworkObject, nested NetworkObjects, duplicate prefab ids, unregistered prefabs). `--scope config` or `--scope prefabs` runs one half. |
+
+### netcode.gameobjects.profiler
+
+| **Command** | **Description** |
+| :--- | :--- |
+| `get_stats` | Sample network traffic over a number of frames: bytes and messages sent and received, per message type. |
+
+The total bytes sent and received are exact. Per message type, the bytes received can be overstated by up to 6 bytes per message, because Netcode for GameObjects reports received messages with their header's unpacked size.
+
+### netcode.gameobjects.session
+
+| **Command** | **Description** |
+| :--- | :--- |
+| `start` | Start the NetworkManager as host, server or client, optionally with another address and port. |
+| `stop` | Shut the NetworkManager down. |
+| `kick` | Disconnect a client from the server or host. |
+| `reconnect` | Disconnect a client and connect it again, then wait for it to be connected. A client that was already disconnected, for example kicked or timed out, just connects again. |
+| `wait_ready` | Wait until a client is connected, or a server has a number of clients. |
+
+### netcode.gameobjects.simulator
+
+The simulator applies packet delay, jitter and loss to UnityTransport through its simulator pipeline stage, which is available in the Editor and development builds. Settings last for the Editor session and also apply to sessions started later. Once the simulator, `timeout` and `lag_spike` are all off, the transport gets its own simulator settings back. While the simulator is on, the Console shows a warning in each play session it affects, and again when its settings change.
+
+| **Command** | **Description** |
+| :--- | :--- |
+| `get` | The current simulated conditions. |
+| `set` | Set a preset and/or packet delay, jitter and loss. |
+| `list_presets` | Network condition presets. They come from the Multiplayer Tools package (2.0 or later). |
+| `lag_spike` | Drop every packet for a short time. |
+| `timeout` | Drop every packet until turned off, so connections time out. |
+
+### netcode.gameobjects.config
+
+| **Command** | **Description** |
+| :--- | :--- |
+| `get` | The NetworkManager's configuration and the names `set` accepts. |
+| `set` | Set a NetworkConfig field (for example `tick_rate`), the transport `address`, `port` or `listen_address`, the `player_prefab`, or the `log_level`. The log level also changes a running session. |
+
+Commands that change scenes or assets are undoable where Unity supports it and don't save the scene; save it with `unity command scene save`. Commands that change a running session apply to the Editor they run in.
+
+## Hybrid sessions
+
+A session whose network prefabs include `GhostObject` prefabs runs on a Netcode for Entities world. Its traffic goes through Netcode for Entities on port 7979, not through the NetworkManager's UnityTransport. In a hybrid session:
+
+- The `netcode.gameobjects.simulator` commands don't affect the session's traffic. `timeout` and `lag_spike` refuse to run.
+- The transport `address` and `port` set with `netcode.gameobjects.config set` or `netcode.gameobjects.session start` don't apply.
+- `get_stats` counts Netcode for GameObjects messages only, not `GhostObject` replication.
+
+The commands say so in their notes when this applies. For the Netcode for Entities side of the session, use the Netcode for Entities commands, for example `netcode.simulator` and `netcode.profiler get_snapshot_stats`.

com.unity.netcode.gameobjects/Editor/AssemblyInfo.cs

@@ -1,8 +1,12 @@
 using System.Runtime.CompilerServices;
 
+// The Unity CLI commands (com.unity.pipeline) wrap the internal query layer in Editor/CliQueries.
+[assembly: InternalsVisibleTo("Unity.Netcode.GameObjects.CLI.Editor")]
+
 #if UNITY_INCLUDE_TESTS
 #if UNITY_EDITOR
 [assembly: InternalsVisibleTo("Unity.Netcode.GameObjects.Editor.Tests")]
+[assembly: InternalsVisibleTo("Unity.Netcode.GameObjects.CLI.Editor.Tests")]
 [assembly: InternalsVisibleTo("TestProject.Runtime.Tests")]
 #endif // UNITY_EDITOR
 #endif // UNITY_INCLUDE_TESTS

com.unity.netcode.gameobjects/Editor/CLI/AssemblyInfo.cs

@@ -0,0 +1,5 @@
+using System.Runtime.CompilerServices;
+
+#if UNITY_INCLUDE_TESTS
+[assembly: InternalsVisibleTo("Unity.Netcode.GameObjects.CLI.Editor.Tests")]
+#endif // UNITY_INCLUDE_TESTS