unity-netcode

name	unity-netcode
description	Set up Netcode for GameObjects (NGO 2.x) multiplayer

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

• Scaffolding multiplayer
• Registering network prefabs
• Wiring spawn logic
• Starting host/server/client
• 搭建多人联机、注册网络预制体、连接生成逻辑、启动 host/server/client

Unity Netcode for GameObjects Skills

Automation for Netcode for GameObjects (NGO) multiplayer setup and operations. Every skill is source-verified against NGO 2.x; when the package is absent, each skill returns a NoNetcode() error with install instructions. A subset of skills additionally require NGO 2.5.0+ (see NGO 2.5+ features) — on an older 2.x install they return a structured "requires 2.5.0+" error instead of a compile error, since AttachableBehaviour/AttachableNode/ComponentController are detected by reflection, not by a dedicated version symbol.

Requires: com.unity.netcode.gameobjects (2.x), Unity 6000.0+. Strongly recommended: before calling any netcode_* skill, load netcode-design. NGO lifecycle and permission rules are strict; skills alone cannot prevent incorrect business code.

Guardrails

Operating Mode (v1.9 three-tier):

• Approval (default): query/list/info skills (netcode_check_setup, netcode_get_manager_info, netcode_get_transport_info, netcode_list_network_objects, netcode_get_network_object_info, netcode_list_network_prefabs, netcode_list_network_behaviours, netcode_get_spawn_manager_info, netcode_get_scene_manager_info, netcode_get_status, netcode_version, netcode_attachable_info) run directly. Mutators (create/configure/attach/add) are FullAuto — on MODE_RESTRICTED, run the grant protocol.

• Auto / Bypass: SemiAuto and FullAuto run directly.

• Auto-forbidden in this module:

  • SkillOperation.Delete → netcode_remove_manager, netcode_remove_network_object, netcode_remove_from_prefabs_list
  • MayTriggerReload = true → netcode_add_network_behaviour_script (writes a new .cs, forces script compile + Domain Reload)
  • MayEnterPlayMode = true → netcode_start_host, netcode_start_server, netcode_start_client, netcode_shutdown

  These are reachable only under Bypass mode or via a user-managed Allowlist entry; the grant flow returns MODE_FORBIDDEN. Runtime control + Behaviour-script generation are the practical reason this module is gated.

• When com.unity.netcode.gameobjects is missing, every skill returns a NoNetcode() error with install instructions.

DO NOT (common hallucinations):

• netcode_spawn_object / netcode_spawn_player — do not exist. Spawn must happen in runtime code (NetworkBehaviour) via .Spawn() or NetworkManager.SpawnManager.InstantiateAndSpawn. Skills do not proxy Spawn because Spawn requires a running NetworkManager.
• netcode_register_scene — does not exist. Scene registration goes through Build Settings + EnableSceneManagement. This module only exposes netcode_configure_scene_management for reading/writing the config.
• netcode_set_tick_rate / netcode_set_protocol as standalone skills — do not exist. Use netcode_configure_manager for all NetworkConfig edits.
• Do not assume netcode_start_host works in Edit Mode. All Runtime control skills require PlayMode.
• Do not assume netcode_add_to_prefabs_list automatically attaches a NetworkObject component. Call netcode_add_network_object first.

Routing:

• Plain GameObject hierarchy creation → gameobject
• Attach NetworkObject / NetworkTransform / other networking components → this module
• Generic player-prefab components (Rigidbody / Collider / Animator) → component
• Runtime scene switching (LoadScene) → call NetworkManager.SceneManager.LoadScene from the generated NetworkBehaviour; this module does not execute it
• Code-level design decisions (RPC direction, NetworkVariable permission) → netcode-design advisory

Object Targeting

netcode_add_* / netcode_configure_* skills use the usual target parameters:

• name — scene object name
• instanceId — Unity InstanceID (exact)
• path — hierarchy path Parent/Child

Prefer instanceId when there is a chance of duplicate names.

Skills

Setup & Validation

Skill	Purpose	Key Parameters
netcode_check_setup	Verify package, NetworkManager, Transport, PlayerPrefab, and PrefabsList consistency	verbose?
netcode_create_manager	Create NetworkManager + UnityTransport	name?
netcode_configure_manager	Bulk-edit NetworkConfig (TickRate, ConnectionApproval, EnableSceneManagement, NetworkTopology, ...)	name?, 15+ optional fields
netcode_get_manager_info	Read NetworkConfig + runtime state	name?
netcode_remove_manager	Delete the NetworkManager (must already be Shutdown)	name?

Transport

Skill	Purpose	Key Parameters
netcode_set_transport_address	Direct connection: set Address / Port / ServerListenAddress	address, port, serverListenAddress?
netcode_set_relay_server_data	Relay mode (mutually exclusive with direct connection)	address, port, allocationIdBase64, keyBase64, connectionDataBase64, hostConnectionDataBase64?, isSecure?
netcode_set_debug_simulator	Simulate latency / jitter / packet loss (development only)	packetDelay, packetJitter, dropRate
netcode_get_transport_info	Read current transport info	name?

NetworkObject

Skill	Purpose	Key Parameters
netcode_add_network_object	Attach NetworkObject to a GameObject	name/instanceId/path + NetworkObject fields
netcode_configure_network_object	Modify fields on an existing NetworkObject	same as above
netcode_remove_network_object	Remove a NetworkObject (must not be currently spawned)	same as above
netcode_list_network_objects	List all NetworkObjects in scene (including runtime state)	includeInactive?
netcode_get_network_object_info	Query a single NetworkObject in detail	same as above

NetworkPrefabsList

Skill	Purpose	Key Parameters
netcode_create_prefabs_list	Create a NetworkPrefabsList asset	path, assignToManager?
netcode_add_to_prefabs_list	Add a prefab (optional override: None/Prefab/Hash)	listPath, prefabPath, overrideMode?, ...
netcode_remove_from_prefabs_list	Remove a prefab entry	listPath, prefabPath
netcode_list_network_prefabs	List every entry with its hash	listPath
netcode_set_player_prefab	Set NetworkConfig.PlayerPrefab	prefabPath, name?

Components

Skill	Purpose	Key Parameters
netcode_add_network_transform	Attach NetworkTransform with axis sync toggles	target + 15 optional fields
netcode_configure_network_transform	Edit fields / thresholds on an existing NT	includes PositionThreshold etc.
netcode_add_network_rigidbody	Attach NetworkRigidbody / NetworkRigidbody2D	useRigidbody2D?, useRigidBodyForMotion?
netcode_add_network_animator	Attach NetworkAnimator (Animator required)	target
netcode_add_network_behaviour_script	Generate a NetworkBehaviour script template (OnNetworkSpawn/Despawn + optional RPC/NetworkVariable/Ownership/NGO 2.5+ OnNetworkPreDespawn)	className, path, includeRpc?, includeNetworkVariable?, includeOwnershipCallbacks?, includePreDespawn?
netcode_list_network_behaviours	List NetworkBehaviour subclass instances in the scene	includeInactive?

Scene & Spawning Query

Skill	Purpose
netcode_configure_scene_management	Set EnableSceneManagement / LoadSceneTimeOut / ClientSynchronizationMode
netcode_get_spawn_manager_info	Runtime: list SpawnedObjects
netcode_get_scene_manager_info	Runtime: read scene load state

Runtime Control (PlayMode required)

Skill	Purpose
netcode_start_host	Start Host
netcode_start_server	Start Server
netcode_start_client	Start Client
netcode_shutdown	Shut down (optional discardMessageQueue)
netcode_get_status	Read IsHost / IsServer / IsClient, LocalClientId, ConnectedClients, NetworkTime

NGO 2.5+ Features {#ngo-25-features}

Added in Netcode for GameObjects 2.5.0 (verified against the package CHANGELOG, PR #3518): AttachableBehaviour / AttachableNode are an alternate "attach" parenting system that avoids the classic NetworkObject parenting pitfalls; ComponentController network-synchronizes the enabled/disabled state of a list of components. On NGO 2.0–2.4.x (NETCODE_GAMEOBJECTS is still active, but these types don't exist yet) every skill below returns a structured requires 2.5.0+ error instead of failing — call netcode_version first to confirm.

Skill	Purpose	Key Parameters
netcode_version	Report installed NGO version and 2.5+ feature availability	—
netcode_attachable_info	Audit the scene's AttachableBehaviour / AttachableNode / ComponentController distribution	includeInactive?
netcode_attachable_add	Attach an AttachableBehaviour to a GameObject nested under a NetworkObject	target + autoDetach? (None/OnAttachNodeDestroy/OnDespawn/OnOwnershipChange, comma-separated)
netcode_attachable_node_add	Attach an AttachableNode (the socket an AttachableBehaviour attaches to)	target + detachOnDespawn?
netcode_component_controller_add	Attach a ComponentController to a GameObject	target + startEnabled?
netcode_component_controller_configure	Set StartEnabled and/or populate the synchronized component list from target GameObjects (mirrors dragging a GameObject onto the Components field in the Inspector)	target, targetPaths?, clearExisting?, startEnabled?

Notes:

• AttachableBehaviour must live on a child GameObject nested under a NetworkObject's hierarchy, not directly on the NetworkObject's own GameObject.
• AttachableNode must belong to a different NetworkObject than the AttachableBehaviour instances attaching to it.
• Attach() / Detach() are runtime-only calls (require both instances spawned) and are intentionally not exposed as skills — same rationale as netcode_spawn_object not existing (see DO NOT above): the caller must already have a running NetworkManager and do this from NetworkBehaviour code.
• netcode_component_controller_configure's targetPaths accepts whole GameObjects; NGO's own OnValidate() (invoked by this skill) expands each into every eligible child component with a public bool enabled property, skipping NetworkBehaviour/NetworkObject/NetworkManager — identical to what happens when you drag a GameObject onto the Components field in the Inspector.

Quick Start

import unity_skills as u

# 1. Inspect current state
u.call_skill("netcode_check_setup")

# 2. Create NetworkManager + UnityTransport
u.call_skill("netcode_create_manager", name="NetworkManager")

# 3. Configure the NetworkConfig
u.call_skill("netcode_configure_manager",
    tickRate=30,
    connectionApproval=False,
    enableSceneManagement=True,
    networkTopology="ClientServer")

# 4. Transport
u.call_skill("netcode_set_transport_address",
    address="127.0.0.1", port=7777, serverListenAddress="0.0.0.0")

# 5. Player prefab setup
#    NOTE: add_network_object on a prefab path depends on GameObjectFinder support.
#    Safer route: instantiate the prefab in the scene first, then attach.
u.call_skill("netcode_add_network_object", path="Assets/Prefabs/Player.prefab")
u.call_skill("netcode_create_prefabs_list", path="Assets/NetworkPrefabs.asset")
u.call_skill("netcode_add_to_prefabs_list",
    listPath="Assets/NetworkPrefabs.asset",
    prefabPath="Assets/Prefabs/Player.prefab")
u.call_skill("netcode_set_player_prefab", prefabPath="Assets/Prefabs/Player.prefab")

# 6. Generate a NetworkBehaviour template
u.call_skill("netcode_add_network_behaviour_script",
    className="PlayerController",
    path="Assets/Scripts/PlayerController.cs",
    includeRpc=True, includeNetworkVariable=True)

# 7. Drive the session in PlayMode
u.call_skill()   
u.call_skill()
u.call_skill()
u.call_skill()
u.call_skill()

Critical Rules (must read)

1. Spawn/Despawn are not exposed as skills. They must be called from NetworkBehaviour runtime code (Server authority). Skills handle prefab registration and NetworkManager lifecycle only.
2. PlayerPrefab must be in a NetworkPrefabsList (enforced at runtime on 2.x). Register it with netcode_add_to_prefabs_list.
3. Runtime control skills (start_*/shutdown) require PlayMode. Calls from Edit Mode return an error.
4. Address vs ServerListenAddress have different meaning. On a client, Address is the target server IP. On a server, ServerListenAddress is the bind address (usually 0.0.0.0).
5. useRigidbody2D switches between NetworkRigidbody and NetworkRigidbody2D. Unrelated physics settings (e.g. Physics2D.AutoSyncTransforms) live elsewhere.

Version Scope

Targets NGO 2.x (validated against 2.13.1). Legacy 1.x (old prefabs list layout, different RPC model) is out of scope for this module. The NGO 2.5+ features skills additionally require 2.5.0+ within that range; call netcode_version to check before relying on them.

Exact Signatures

For exact parameter names, defaults, and return fields, query GET /skills/schema or unity_skills.get_skill_schema(). This document is a routing and best-practice guide, not the authoritative signature source.