SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillsunity-netcode-design

unity-netcode-design

Design & creation

View repository

Updated 10-15 17:25

About this skill

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
  • Write or review multiplayer networking code, design server/distributed authority, connect RPCs or network variables, troubleshoot netcode issues
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.