Before calling any skill in this module: if you are about to call a skill with parameters guessed from its name or description, STOP — read this file (or fetch its schema via GET /skills/recommend?includeSchema=true) first. If you already have the parameter definitions from recommend/schema, you may proceed straight to dryRun.
Triggers
- Writing or reviewing multiplayer code
- Designing server/distributed authority
- Wiring RPCs or NetworkVariables
- Debugging netcode
- 编写或审查多人联机代码、设计服务器/分布式权威、连接 RPC 或网络变量、排查 netcode 问题
Netcode for GameObjects - Design Rules
Advisory module. Every rule is distilled from com.unity.netcode.gameobjects 2.x source. Each rule cites a concrete file/line so the reasoning is auditable.
Mode: Documentation only — no REST skills to gate; load freely under any operating mode (Approval / Auto / Bypass).
When to Load This Module
Load before writing or reviewing any of:
- NetworkBehaviour scripts (OnNetworkSpawn / OnNetworkDespawn / RPCs / NetworkVariables)
- NetworkManager startup / shutdown / scene switching
- NetworkObject Spawn / Despawn / ChangeOwnership / TrySetParent
- UnityTransport configuration (direct connect / Relay)
- Any code that branches on IsHost / IsServer / IsClient / IsOwner
Critical Rule Summary (memorize even if you skip the sub-docs)
| # |
Rule |
Source anchor |
| 1 |
Spawn() / Despawn() must be called on Server/Host only; client-side calls fail. |
Runtime/Core/NetworkObject.cs:1884, 1921 |
| 2 |
OnNetworkSpawn() runs before Unity Start() and after Awake/OnEnable. |
Runtime/Core/NetworkBehaviour.cs:704 + InvokeBehaviourNetworkSpawn callers |
| 3 |
Legacy [ServerRpc] method names must end with ServerRpc; [ClientRpc] must end with ClientRpc (ILPP enforced at compile time). |
Editor/CodeGen/ ILPP validators |
| 4 |
New [Rpc(SendTo.X)] has no naming constraint; SendTo has 11 values. |
Runtime/Messaging/RpcTargets/RpcTarget.cs:9-80 |
| 5 |
PlayerPrefab must exist in NetworkPrefabsList or NetworkConfig.Prefabs or 2.x runtime rejects it. |
Runtime/Configuration/NetworkConfig.cs:40 + NetworkPrefabsList.cs:14 |
| 6 |
Nested NetworkObjects are forbidden (NetworkObject inside another NetworkObject prefab). Re-parent at runtime via TrySetParent. |
Runtime/Core/NetworkObject.cs:2135-2215 |
| 7 |
NetworkVariable<T> requires T to be unmanaged or implement INetworkSerializable. string, List<>, class are rejected. |
Runtime/NetworkVariable/NetworkVariable.cs:12 + ILPP |
| 8 |
NetworkList<T> requires T: unmanaged, IEquatable<T>. It is NOT NetworkVariable<List<T>>. |
Runtime/NetworkVariable/Collections/NetworkList.cs:14 |
| 9 |
NetworkSceneManager.LoadScene/UnloadScene is Server-only. |
Runtime/SceneManagement/NetworkSceneManager.cs:1496, 1252 |
| 10 |
UnityTransport.SetRelayServerData and SetConnectionData are mutually exclusive; use one or the other. |
Runtime/Transports/UTP/UnityTransport.cs:776-897 |
Sub-doc Routing
| Sub-doc |
When to read |
| LIFECYCLE.md |
Lifecycle, callback ordering, Awake/OnNetworkSpawn/Start differences |
| OWNERSHIP.md |
IsOwner/IsServer/IsHost permission matrix, ChangeOwnership, Distributed Authority |
| RPC.md |
Choosing RPC attributes, SendTo semantics, RpcInvokePermission, deprecated paths |
| VARIABLES.md |
NetworkVariable/NetworkList init and serialization constraints |
| SPAWNING.md |
Prefab registration → Spawn → Despawn, GlobalObjectIdHash, SpawnAsPlayerObject |
| SCENE.md |
NetworkSceneManager, EnableSceneManagement, in-scene object sync |
| TRANSPORT.md |
UnityTransport direct / Relay / DebugSimulator configuration |
| PITFALLS.md |
30 concrete hallucination pitfalls |
Routing to Other Modules
- Generating NetworkBehaviour scripts → use the functional
netcode module's netcode_add_network_behaviour_script
- Bulk attaching NetworkObject/NetworkTransform in the scene →
netcode module Components skills
- Architecture-level decisions (Server-authoritative vs Distributed Authority) → also load architecture
Version Scope
This document targets com.unity.netcode.gameobjects 2.x (validated against 2.11.0, Unity 6000.0+). Some APIs (SendTo.Authority, RpcInvokePermission, the universal [Rpc] attribute) do not exist in 1.x.
1---2name: unity-netcode-design3description: Source-anchored design rules for Netcode for GameObjects 2.x4---5
6> **Before calling any skill in this module:** if you are about to call a skill with parameters guessed from its name or description, STOP — read this file (or fetch its schema via `GET /skills/recommend?includeSchema=true`) first. If you already have the parameter definitions from recommend/schema, you may proceed straight to dryRun.
7
8## Triggers
9- Writing or reviewing multiplayer code
10- Designing server/distributed authority
11- Wiring RPCs or NetworkVariables
12- Debugging netcode
13- 编写或审查多人联机代码、设计服务器/分布式权威、连接 RPC 或网络变量、排查 netcode 问题
14
15# Netcode for GameObjects - Design Rules
16
17Advisory module. Every rule is distilled from `com.unity.netcode.gameobjects` 2.x source. Each rule cites a concrete file/line so the reasoning is auditable.
18
19> **Mode**: Documentation only — no REST skills to gate; load freely under any operating mode (Approval / Auto / Bypass).
20
21## When to Load This Module
22
23Load before writing or reviewing any of:
24- NetworkBehaviour scripts (OnNetworkSpawn / OnNetworkDespawn / RPCs / NetworkVariables)
25- NetworkManager startup / shutdown / scene switching
26- NetworkObject Spawn / Despawn / ChangeOwnership / TrySetParent
27- UnityTransport configuration (direct connect / Relay)
28- Any code that branches on IsHost / IsServer / IsClient / IsOwner
29
30## Critical Rule Summary (memorize even if you skip the sub-docs)
31
32| # | Rule | Source anchor |
33|---|------|---------------|
34| 1 | `Spawn()` / `Despawn()` must be called on Server/Host only; client-side calls fail. | `Runtime/Core/NetworkObject.cs:1884, 1921` |
35| 2 | `OnNetworkSpawn()` runs **before** Unity `Start()` and **after** `Awake`/`OnEnable`. | `Runtime/Core/NetworkBehaviour.cs:704` + `InvokeBehaviourNetworkSpawn` callers |
36| 3 | Legacy `[ServerRpc]` method names **must** end with `ServerRpc`; `[ClientRpc]` must end with `ClientRpc` (ILPP enforced at compile time). | `Editor/CodeGen/` ILPP validators |
37| 4 | New `[Rpc(SendTo.X)]` has no naming constraint; `SendTo` has 11 values. | `Runtime/Messaging/RpcTargets/RpcTarget.cs:9-80` |
38| 5 | `PlayerPrefab` must exist in `NetworkPrefabsList` or `NetworkConfig.Prefabs` or 2.x runtime rejects it. | `Runtime/Configuration/NetworkConfig.cs:40` + `NetworkPrefabsList.cs:14` |
39| 6 | **Nested NetworkObjects are forbidden** (NetworkObject inside another NetworkObject prefab). Re-parent at runtime via `TrySetParent`. | `Runtime/Core/NetworkObject.cs:2135-2215` |
40| 7 | `NetworkVariable<T>` requires `T` to be `unmanaged` or implement `INetworkSerializable`. `string`, `List<>`, `class` are rejected. | `Runtime/NetworkVariable/NetworkVariable.cs:12` + ILPP |
41| 8 | `NetworkList<T>` requires `T: unmanaged, IEquatable<T>`. It is NOT `NetworkVariable<List<T>>`. | `Runtime/NetworkVariable/Collections/NetworkList.cs:14` |
42| 9 | `NetworkSceneManager.LoadScene/UnloadScene` is Server-only. | `Runtime/SceneManagement/NetworkSceneManager.cs:1496, 1252` |
43| 10 | `UnityTransport.SetRelayServerData` and `SetConnectionData` are **mutually exclusive**; use one or the other. | `Runtime/Transports/UTP/UnityTransport.cs:776-897` |
44
45## Sub-doc Routing
46
47| Sub-doc | When to read |
48|---------|--------------|
49| [LIFECYCLE.md](./LIFECYCLE.md) | Lifecycle, callback ordering, `Awake/OnNetworkSpawn/Start` differences |
50| [OWNERSHIP.md](./OWNERSHIP.md) | IsOwner/IsServer/IsHost permission matrix, ChangeOwnership, Distributed Authority |
51| [RPC.md](./RPC.md) | Choosing RPC attributes, `SendTo` semantics, `RpcInvokePermission`, deprecated paths |
52| [VARIABLES.md](./VARIABLES.md) | NetworkVariable/NetworkList init and serialization constraints |
53| [SPAWNING.md](./SPAWNING.md) | Prefab registration → Spawn → Despawn, GlobalObjectIdHash, SpawnAsPlayerObject |
54| [SCENE.md](./SCENE.md) | NetworkSceneManager, EnableSceneManagement, in-scene object sync |
55| [TRANSPORT.md](./TRANSPORT.md) | UnityTransport direct / Relay / DebugSimulator configuration |
56| [PITFALLS.md](./PITFALLS.md) | 30 concrete hallucination pitfalls |
57
58## Routing to Other Modules
59
60- Generating NetworkBehaviour scripts → use the functional `netcode` module's `netcode_add_network_behaviour_script`
61- Bulk attaching NetworkObject/NetworkTransform in the scene → `netcode` module Components skills
62- Architecture-level decisions (Server-authoritative vs Distributed Authority) → also load [architecture](../architecture/SKILL.md)
63
64## Version Scope
65
66This document targets `com.unity.netcode.gameobjects` **2.x** (validated against 2.11.0, Unity 6000.0+). Some APIs (`SendTo.Authority`, `RpcInvokePermission`, the universal `[Rpc]` attribute) do not exist in 1.x.
gabrielmoreira