unity-netcode-design

name

unity-netcode-design

description

Source-anchored design rules for Netcode for GameObjects 2.x. Load this before writing any NetworkBehaviour / RPC / NetworkVariable / Spawn code to avoid hallucinated APIs and lifecycle-ordering bugs. Triggers: netcode, NGO, NetworkManager, NetworkObject, NetworkBehaviour, NetworkVariable, NetworkList, NetworkSceneManager, NetworkPrefabsList, NetworkConfig, ServerRpc, ClientRpc, Rpc, SendTo, RpcTarget, RpcInvokePermission, INetworkSerializable, OnNetworkSpawn, OnNetworkDespawn, OnNetworkObjectParentChanged, Spawn, Despawn, SpawnAsPlayerObject, SpawnWithOwnership, ChangeOwnership, RemoveOwnership, TrySetParent, IsOwner, IsServer, IsHost, IsClient, IsLocalPlayer, GlobalObjectIdHash, UnityTransport, SetRelayServerData, SetConnectionData, DebugSimulator, DistributedAuthority, multiplayer, host, client, server, transport, relay, 网络同步, 多人游戏, 联机, 服务器权威, 分布式权威, 主机, 客户端, 服务端, 网络对象, 网络变量, 网络列表, 网络场景管理, 远程过程调用, RPC 调用, 所有权, 生成对象, 销毁对象, 网络游戏, netcode 设计, 网络架构, NGO 2.x.

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.