unity-netcode

调用此模块中的任何技能前： 如果你打算根据技能名称或描述猜测参数后调用技能，请先停下——阅读此文件（或通过 GET /skills/recommend?includeSchema=true 获取其架构）。如果你已从 recommend/schema 获取参数定义，则可直接进行 dryRun。

触发条件

• 搭建多人联机
• 注册网络预制体
• 连接生成逻辑
• 启动 host/server/client
• 搭建多人联机、注册网络预制体、连接生成逻辑、启动 host/server/client

Unity Netcode for GameObjects 技能

用于自动化配置和操作 Netcode for GameObjects (NGO) 多人联机的技能。每项技能都经过 NGO 2.x 源码验证；如果缺少该软件包，每项技能都会返回带有安装说明的 NoNetcode() 错误。部分技能还要求 NGO 2.5.0+（参见 NGO 2.5+ 功能）——在较旧的 2.x 安装版本上，它们会返回结构化的“requires 2.5.0+”错误，而不是编译错误，因为 AttachableBehaviour/AttachableNode/ComponentController 是通过反射检测的，而非通过专用版本符号检测。

要求：com.unity.netcode.gameobjects（2.x）、Unity 6000.0+。 强烈建议：调用任何 netcode_* 技能前，先加载 netcode-design。NGO 的生命周期和权限规则十分严格；仅靠技能无法避免业务代码出错。

Guardrails（防护机制）

Operating Mode（v1.9 三层模式）：

• Approval（默认）：查询／列表／信息类技能（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）直接运行。修改类操作（创建／配置／附加／添加）属于 FullAuto；遇到 MODE_RESTRICTED 时，执行授权流程。

• Auto / Bypass：SemiAuto 和 FullAuto 直接运行。

• 此模块中禁止 Auto 模式执行的操作：

  • SkillOperation.Delete → netcode_remove_manager、netcode_remove_network_object、netcode_remove_from_prefabs_list
  • MayTriggerReload = true → netcode_add_network_behaviour_script（写入新的 .cs 文件，强制脚本编译并触发 Domain Reload）
  • MayEnterPlayMode = true → netcode_start_host、netcode_start_server、netcode_start_client、netcode_shutdown

  这些操作只能在 Bypass 模式下执行，或通过用户管理的 Allowlist 条目执行；授权流程会返回 MODE_FORBIDDEN。此模块设置门槛的实际原因是运行时控制和 Behaviour 脚本生成。

• 缺少 com.unity.netcode.gameobjects 时，每项技能都会返回带有安装说明的 NoNetcode() 错误。

切勿（常见幻觉）：

• netcode_spawn_object / netcode_spawn_player — 不存在。Spawn 必须在运行时代码（NetworkBehaviour）中通过 .Spawn() 或 NetworkManager.SpawnManager.InstantiateAndSpawn 实现。技能不会代理 Spawn，因为 Spawn 需要正在运行的 NetworkManager。
• netcode_register_scene — 不存在。场景注册通过 Build Settings + EnableSceneManagement 完成。此模块只提供 netcode_configure_scene_management 用于读取／写入配置。
• 独立的 netcode_set_tick_rate / netcode_set_protocol 技能 — 不存在。所有 NetworkConfig 编辑都使用 netcode_configure_manager。
• 不要认为 netcode_start_host 在 Edit Mode 下可用。所有运行时控制技能都需要 PlayMode。
• 不要认为 netcode_add_to_prefabs_list 会自动附加 NetworkObject 组件。请先调用 netcode_add_network_object。

路由：

• 创建普通 GameObject 层级 → gameobject
• 附加 NetworkObject / NetworkTransform / 其他网络组件 → 此模块
• 通用玩家预制体组件（Rigidbody / Collider / Animator）→ component
• 运行时场景切换（LoadScene）→ 从生成的 NetworkBehaviour 中调用 NetworkManager.SceneManager.LoadScene；此模块不会执行该调用
• 代码层面的设计决策（RPC 方向、NetworkVariable 权限）→ 参考 netcode-design 提供的建议

对象定位

netcode_add_* / netcode_configure_* 技能使用常见的目标参数：

• name — 场景对象名称
• instanceId — Unity InstanceID（精确）
• path — 层级路径 Parent/Child

可能存在重名时，优先使用 instanceId。

技能

设置与验证

技能	用途	关键参数
netcode_check_setup	验证程序包、NetworkManager、Transport、PlayerPrefab 和 PrefabsList 的一致性	verbose?
netcode_create_manager	创建 NetworkManager + UnityTransport	name?
netcode_configure_manager	批量编辑 NetworkConfig（TickRate、ConnectionApproval、EnableSceneManagement、NetworkTopology 等）	name?，15 个以上可选字段
netcode_get_manager_info	读取 NetworkConfig + 运行时状态	name?
netcode_remove_manager	删除 NetworkManager（必须已 Shutdown）	name?

传输

技能	用途	关键参数
netcode_set_transport_address	直接连接：设置 Address / Port / ServerListenAddress	address、port、serverListenAddress?
netcode_set_relay_server_data	中继模式（与直接连接互斥）	address、port、allocationIdBase64、keyBase64、connectionDataBase64、hostConnectionDataBase64?、isSecure?
netcode_set_debug_simulator	模拟延迟 / 抖动 / 丢包（仅用于开发）	packetDelay、packetJitter、dropRate
netcode_get_transport_info	读取当前传输信息	name?

NetworkObject

技能	用途	关键参数
netcode_add_network_object	将 NetworkObject 附加到 GameObject	name/instanceId/path + NetworkObject 字段
netcode_configure_network_object	修改现有 NetworkObject 的字段	同上
netcode_remove_network_object	移除 NetworkObject（当前不得处于生成状态）	同上
netcode_list_network_objects	列出场景中的所有 NetworkObject（包括运行时状态）	includeInactive?
netcode_get_network_object_info	查询单个 NetworkObject 的详细信息	同上

NetworkPrefabsList

技能	用途	关键参数
netcode_create_prefabs_list	创建 NetworkPrefabsList 资源	path、assignToManager?
netcode_add_to_prefabs_list	添加预制体（可选覆盖：None/Prefab/Hash）	listPath、prefabPath、overrideMode?、...
netcode_remove_from_prefabs_list	移除预制体条目	listPath、prefabPath
netcode_list_network_prefabs	列出每个条目及其哈希值	listPath
netcode_set_player_prefab	设置 NetworkConfig.PlayerPrefab	prefabPath、name?

组件

技能	用途	关键参数
netcode_add_network_transform	附加 NetworkTransform，并设置轴同步开关	目标 + 15 个可选字段
netcode_configure_network_transform	编辑现有 NT 的字段 / 阈值	包括 PositionThreshold 等
netcode_add_network_rigidbody	附加 NetworkRigidbody / NetworkRigidbody2D	useRigidbody2D?、useRigidBodyForMotion?
netcode_add_network_animator	附加 NetworkAnimator（需要 Animator）	目标
netcode_add_network_behaviour_script	生成 NetworkBehaviour 脚本模板（OnNetworkSpawn/Despawn + 可选 RPC/NetworkVariable/Ownership/NGO 2.5+ OnNetworkPreDespawn）	className、path、includeRpc?、includeNetworkVariable?、includeOwnershipCallbacks?、includePreDespawn?
netcode_list_network_behaviours	列出场景中的 NetworkBehaviour 子类实例	includeInactive?

场景与生成查询

技能	用途
netcode_configure_scene_management	设置 EnableSceneManagement / LoadSceneTimeOut / ClientSynchronizationMode
netcode_get_spawn_manager_info	运行时：列出 SpawnedObjects
netcode_get_scene_manager_info	运行时：读取场景加载状态

运行时控制（需要 PlayMode）

技能	用途
netcode_start_host	启动 Host
netcode_start_server	启动 Server
netcode_start_client	启动 Client
netcode_shutdown	关闭（可选 discardMessageQueue）
netcode_get_status	读取 IsHost / IsServer / IsClient、LocalClientId、ConnectedClients、NetworkTime

NGO 2.5+ 功能 {#ngo-25-features}

Netcode for GameObjects 2.5.0 中新增（已根据包的 CHANGELOG 和 PR #3518 验证）：AttachableBehaviour / AttachableNode 是一种替代性的“附加”父级系统，可避开经典 NetworkObject 父级关系的陷阱；ComponentController 可通过网络同步组件列表的启用/禁用状态。在 NGO 2.0–2.4.x 中（NETCODE_GAMEOBJECTS 仍处于启用状态，但这些类型尚不存在），以下每项技能都会返回结构化的 requires 2.5.0+ 错误，而不是执行失败——请先调用 netcode_version 确认版本。

技能	用途	关键参数
netcode_version	报告已安装的 NGO 版本及 2.5+ 功能是否可用	—
netcode_attachable_info	检查场景中 AttachableBehaviour / AttachableNode / ComponentController 的分布情况	includeInactive?
netcode_attachable_add	将 AttachableBehaviour 附加到嵌套在 NetworkObject 下的 GameObject	目标 + autoDetach?（None/OnAttachNodeDestroy/OnDespawn/OnOwnershipChange，以逗号分隔）
netcode_attachable_node_add	附加 AttachableNode（供 AttachableBehaviour 附加到的插槽）	目标 + detachOnDespawn?
netcode_component_controller_add	将 ComponentController 附加到 GameObject	目标 + startEnabled?
netcode_component_controller_configure	设置 StartEnabled，和/或从目标 GameObject 填充同步组件列表（相当于在 Inspector 中将 GameObject 拖到 Components 字段）	目标、targetPaths?、clearExisting?、startEnabled?

说明：

• AttachableBehaviour 必须位于嵌套在 NetworkObject 层级中的子 GameObject 上，不能直接位于 NetworkObject 自身的 GameObject 上。
• AttachableNode 必须属于与附加到它的 AttachableBehaviour 实例不同的 NetworkObject。
• Attach() / Detach() 是仅限运行时的调用（要求两个实例都已生成），因此有意不作为技能提供——理由与不存在 netcode_spawn_object 相同（参见上文的 DO NOT）：调用方必须已有正在运行的 NetworkManager，并从 NetworkBehaviour 代码中执行这些调用。
• netcode_component_controller_configure 的 targetPaths 接受完整的 GameObject；NGO 自带的 OnValidate()（由此技能调用）会将每个 GameObject 展开为其所有符合条件的子组件，这些组件必须具有公开的 bool enabled 属性；会跳过 NetworkBehaviour/NetworkObject/NetworkManager——与在 Inspector 中将 GameObject 拖到 Components 字段时的行为完全相同。如果缺少或抛出异常，响应中会包含 warning，且条目不会展开。

快速入门

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("editor_play")   # enter PlayMode
u.call_skill("netcode_start_host")
u.call_skill("netcode_get_status")
u.call_skill("netcode_shutdown")
u.call_skill("editor_stop")

关键规则（必读）

1. 不提供 Spawn/Despawn 技能。 必须从 NetworkBehaviour 运行时代码中调用（由服务器掌握权限）。技能仅处理预制件注册和 NetworkManager 生命周期。
2. PlayerPrefab 必须位于 NetworkPrefabsList 中（在运行时针对 2.x 强制执行）。使用 netcode_add_to_prefabs_list 注册。
3. 运行时控制技能（start_*/shutdown）要求处于 PlayMode。 从 Edit Mode 调用会返回错误。
4. Address 和 ServerListenAddress 含义不同。 在客户端上，Address 是目标服务器 IP。在服务器上，ServerListenAddress 是绑定地址（通常为 0.0.0.0）。
5. useRigidbody2D 用于在 NetworkRigidbody 和 NetworkRigidbody2D 之间切换。无关的物理设置（例如 Physics2D.AutoSyncTransforms）位于其他位置。

版本范围

目标版本为 NGO 2.x（已根据 2.13.1 验证）。旧版 1.x（旧的预制件列表布局、不同的 RPC 模型）不在此模块范围内。NGO 2.5+ 功能中的技能还要求此范围内的版本为 2.5.0+；使用前请调用 netcode_version 检查。

精确签名

如需查询准确的参数名称、默认值和返回字段，请调用 GET /skills/schema 或 unity_skills.get_skill_schema()。本文档是路由和最佳实践指南，并非权威的签名来源。