OpenParable
Skip to content
← Back to skills

Unity Netcode Design

Development
unity-netcode-design

Unity Netcode Design is an Agent Skill for development published in the Besty0728/Unity-Skills repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

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 问题时使用。

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/Besty0728/Unity-Skills/blob/HEAD/SkillsForUnity/unity-skills~/skills/netcode-design/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/unity-netcode-design, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

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)

#RuleSource anchor
1Spawn() / Despawn() must be called on Server/Host only; client-side calls fail.Runtime/Core/NetworkObject.cs:1884, 1921
2OnNetworkSpawn() runs before Unity Start() and after Awake/OnEnable.Runtime/Core/NetworkBehaviour.cs:704 + InvokeBehaviourNetworkSpawn callers
3Legacy [ServerRpc] method names must end with ServerRpc; [ClientRpc] must end with ClientRpc (ILPP enforced at compile time).Editor/CodeGen/ ILPP validators
4New [Rpc(SendTo.X)] has no naming constraint; SendTo has 11 values.Runtime/Messaging/RpcTargets/RpcTarget.cs:9-80
5PlayerPrefab must exist in NetworkPrefabsList or NetworkConfig.Prefabs or 2.x runtime rejects it.Runtime/Configuration/NetworkConfig.cs:40 + NetworkPrefabsList.cs:14
6Nested NetworkObjects are forbidden (NetworkObject inside another NetworkObject prefab). Re-parent at runtime via TrySetParent.Runtime/Core/NetworkObject.cs:2135-2215
7NetworkVariable<T> requires T to be unmanaged or implement INetworkSerializable. string, List<>, class are rejected.Runtime/NetworkVariable/NetworkVariable.cs:12 + ILPP
8NetworkList<T> requires T: unmanaged, IEquatable<T>. It is NOT NetworkVariable<List<T>>.Runtime/NetworkVariable/Collections/NetworkList.cs:14
9NetworkSceneManager.LoadScene/UnloadScene is Server-only.Runtime/SceneManagement/NetworkSceneManager.cs:1496, 1252
10UnityTransport.SetRelayServerData and SetConnectionData are mutually exclusive; use one or the other.Runtime/Transports/UTP/UnityTransport.cs:776-897

Sub-doc Routing

Sub-docWhen to read
LIFECYCLE.mdLifecycle, callback ordering, Awake/OnNetworkSpawn/Start differences
OWNERSHIP.mdIsOwner/IsServer/IsHost permission matrix, ChangeOwnership, Distributed Authority
RPC.mdChoosing RPC attributes, SendTo semantics, RpcInvokePermission, deprecated paths
VARIABLES.mdNetworkVariable/NetworkList init and serialization constraints
SPAWNING.mdPrefab registration → Spawn → Despawn, GlobalObjectIdHash, SpawnAsPlayerObject
SCENE.mdNetworkSceneManager, EnableSceneManagement, in-scene object sync
TRANSPORT.mdUnityTransport direct / Relay / DebugSimulator configuration
PITFALLS.md30 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.