Agent Skills
› Besty0728/Unity-Skills
› unity-netcode-design
unity-netcode-design
GitHub为 Unity Netcode for GameObjects 2.x 提供源码级设计规则，涵盖生命周期、所有权、RPC、网络变量及场景管理等。用于编写、审查多人联机代码或排查同步问题时加载，确保权威性与合规性。
Trigger Scenarios
编写或审查多人联机代码
设计服务器/分布式权威架构
配置 RPC 或 NetworkVariables
排查 Netcode 同步问题
用户提及'联机'或'多人同步'
Install
npx skills add Besty0728/Unity-Skills --skill unity-netcode-design -g -y
SKILL.md
Frontmatter
{
"name": "unity-netcode-design",
"description": "Source-anchored design rules for Netcode for GameObjects 2.x — lifecycle, ownership, RPCs, NetworkVariables, spawning, scene management, transport, and pitfalls. Use when writing or reviewing multiplayer code, designing server\/distributed authority, wiring RPCs or NetworkVariables, or debugging netcode, even if the user just says \"联机\" or \"多人同步\". 为 Netcode for GameObjects 2.x 提供源码锚定的设计规则(生命周期、所有权、RPC、NetworkVariable、生成、场景管理、传输、陷阱);当用户要编写或审查多人联机代码、设计服务器\/分布式权威、连接 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
netcodemodule'snetcode_add_network_behaviour_script - Bulk attaching NetworkObject/NetworkTransform in the scene →
netcodemodule 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.
Version History
- ec9f870 Current 2026-07-05 14:40
