godot-adapt-single-to-multiplayer

绝对不要做的事（多人游戏专家规则）

安全与权限

• 绝不要信任客户端上报的状态 — 客户端只拥有“输入”的所有权，而不拥有“位置”或“生命值”的所有权。服务器必须验证每一次坐标和生命值变更。
• 绝不要使用 get_tree() 分组进行权限检查 — 使用 is_multiplayer_authority()。高延迟玩家加入时，分组注册具有非确定性。
• 绝不要允许不受限制的 RPC 调用频率 — 恶意客户端可以每秒调用 10,000 次“FireWeapon” RPC。务必实现速率限制（net_rpc_rate_limiter.gd）。

移动与延迟

• 绝不要跳过客户端预测 — 不使用预测的移动会让人感觉“迟钝”且响应不灵敏。在本地预测移动，然后仅在与服务器状态不一致时进行校正。
• 绝不要以 60Hz 同步对等端 — 每帧发送完整状态会耗尽客户端带宽。使用较低的 tick 频率（20-30Hz），并在数据包之间进行插值。
• 绝不要瞬间跳变对等端的位置 — 突然的位置更新会导致“抖动”。存储过去状态的缓冲区，并在 100ms 的延迟下对状态进行线性插值。

带宽与同步

• 只要可能，绝不要同步“完整浮点数” — 对 Vector3 数据进行量化（截断小数），以节省 50% 以上的带宽。使用启用了增量同步的 MultiplayerSynchronizer。
• 绝不要忽略“迟加入者” — 在游戏进行中加入的玩家看不到已有的环境变化。对等端连接时，广播完整的世界状态“快照”。
• 绝不要在 0ms ping 下测试 — 在 localhost 上一切都能正常工作。使用模拟器（net_latency_simulator.gd）设置 150ms ping，以发现同步错误。

---

可用脚本

必需：先查看架构决策树，再查看黄金路径脚本。深入的延迟工作流 → references/latency-testing.md。

权限 / 传输桥接

multiplayer_sync.gd

为远程对等端添加 MultiplayerSynchronizer 插值时必需。触发条件：权限方拥有变换信息；非权限方进行插值。

rpc_bridge.gd

必需的信号→RPC 桥接。触发条件：游戏逻辑发出本地信号；桥接验证权限并向所有端分发 RPC。

预测 / 延迟 / 大厅

net_prediction_reconciliation.gd

CharacterBody 预测 + 用于服务器协调的输入缓冲区重放。

net_snapshot_interpolation.gd

远程对等端的快照插值 / 抖动缓冲区。

net_auth_server_validator.gd

权威验证（位置、速度、动作）。

net_rpc_rate_limiter.gd

RPC 洪泛 / 宏脚本防护。

net_interest_management.gd

基于距离的可见性控制，以减少带宽占用。

net_delta_compression_sync.gd

用于增量同步的量化 + 重要性检查。

net_lag_compensation.gd

服务器端回溯，用于命中判定。

net_lobby_late_join_sync.gd

迟加入者的世界快照初始化。

诊断

net_latency_simulator.gd

发布前必需 — 参见 references/latency-testing.md。

net_debug_overlay_monitor.gd

RTT / 丢包 / 抖动叠加层。

net_upnp_discovery_logic.gd

用于监听服务器 / P2P 主机的 UPNP 端口映射。

---

架构模式

模式	使用场景	脚本黄金路径
权威服务器	PvP、经济系统、作弊风险	rpc_bridge.gd → net_auth_server_validator.gd → 预测/协调
P2P lockstep	2–4 人合作、作弊风险低	确定性输入 + net_upnp_discovery_logic.gd
混合 / 主机权限	4–8 人派对游戏	主机权限 + 迟加入快照

---

迁移黄金路径（不含内联主机/加入教程）

1. 将输入（客户端）与模拟（权威方）分离。
2. 为每个玩家节点设置 multiplayer_authority；客户端只发送意图。
3. 必须使用 multiplayer_sync.gd 进行属性复制／远程插值。
4. 必须使用 rpc_bridge.gd 传递需要通过网络传输的游戏事件。
5. 仅为需要的游戏类型添加预测／延迟补偿脚本。
6. 使用 latency-testing 参考资料和 net_latency_simulator.gd 在约 150 ms RTT 下进行验证。

专家见解（原因——保留在正文中）

• 客户端预测——原因：没有本地模拟时，感知到的输入延迟会因 RTT 加倍。服务器校正后，重放缓冲的输入（net_prediction_reconciliation.gd）。
• 插值缓冲区——原因：原始同步数据包会产生抖动；在快照之间以约 100 ms 的延迟进行线性插值（net_snapshot_interpolation.gd）。
• 命中回溯——原因：客户端根据过去的世界状态开火；服务器在射线检测前，通过 PhysicsServer3D 回溯 RIDs（net_lag_compensation.gd）。
• 输入发送频率——原因：60 Hz 的输入 RPC 会占满上行带宽；通过重要性检查，以 20–30 Hz 批量发送（net_delta_compression_sync.gd）。

决策树：选择哪种架构？

因素	权威服务器	P2P 锁步
玩家人数	8-100+	2-4
防作弊需求	关键	不重要
服务器托管	可用	不可用
游戏类型	PvP、竞技	合作、休闲
延迟容忍度	中（预测有帮助）	低（会出现不同步）
开发复杂度	高	中

高级网络主题

点对点 NAT 穿透（打洞）

在 P2P 架构中，客户端通常位于防火墙之后。UPNP（通用即插即用）是第一道防线，它允许游戏使用 net_upnp_discovery_logic.gd 自动向路由器请求端口转发。

UPNP 失效时：

• STUN/TURN：使用 STUN 服务发现公网 IP／端口组合。
• 中继服务：如果无法直接连接，则回退到中继服务（TURN），连接两个对等节点。

网络性能分析与可视化

可视化数据包时间线对于调试抖动至关重要。建议添加一个叠加层，用图表显示：

• 数据包到达：滚动时间线，显示数据包相对于物理帧的到达时间。
• 缓冲区状态：显示插值抖动缓冲区大小的可视化图表。
• RTT（往返时间）：实时显示延迟峰值的图表。

深度配方（按需查阅）

主题	参考资料／脚本
预测／协调／插值	prediction-and-reconciliation.md
权威性／反作弊／带宽	authority-and-security.md

参考资料

渐进式披露：仅在研究特定 API 时打开官方文档链接； 将工作分配给相邻领域时再加载相关技能——不要预先加载整个技能网络。

官方文档

• 高阶多人游戏 — RPC 模式、权限和对等端生命周期；在任何游戏状态离开单人游戏流程之前，都必须先改造这些机制。
• 网络 — 传输方式概览（ENet / WebSocket / WebRTC），确保主机/加入选项符合平台和 NAT 限制。
• MultiplayerSynchronizer — 属性复制、增量同步和可见性筛选器，可取代临时的位置 RPC。
• MultiplayerSpawner — 当后加入的玩家需要与主机拥有相同场景树时，用于复制生成/销毁操作。
• SceneMultiplayer — 默认的 MultiplayerAPI 实现：SceneTree 下的根路径、身份验证回调和 RPC 路由。
• ENetMultiplayerPeer — UDP 主机/客户端对等端，适用于大多数将单人游戏移植到局域网和专用服务器的场景。
• MultiplayerAPI — multiplayer 单例接口：对等端 ID、信号以及 rpc / rpc_id 入口。
• MultiplayerPeer — 所有具体对等端后端共用的传输模式和连接状态。
• UPNP — 为位于家用路由器后的监听服务器 / P2P 主机自动映射端口。
• WebRTC — 当 ENet UDP 无法单独穿透防火墙时，适用于浏览器的 P2P 方案。
• Node — set_multiplayer_authority / is_multiplayer_authority 的所有权规则，适用于输入与状态。
• PhysicsServer3D — 直接操作 RID 变换，在不产生 SceneTree 副作用的情况下实现服务器端命中回溯。

相关技能

前置条件

• godot-input-handling — 将 InputMap 读取与模拟拆分开来，使客户端发送意图，由权威端决定结果。
• godot-signal-architecture — 本地信号图可由 rpc_bridge.gd 封装，避免游戏逻辑与传输方式耦合。
• godot-autoload-architecture — 在主机/加入流程中，跨场景切换持续存在的会话/大厅 Autoload。

补充内容

• godot-multiplayer-networking — 在确定从单人模式迁移到在线模式的方案后，深入了解 RPC、大厅和 ENet 调优。
• godot-characterbody-2d — 可复用于客户端预测和协调缓冲区的确定性 move_and_slide 步骤。
• godot-physics-3d — 延迟补偿回滚和命中验证查询所依据的刚体／形状设置。
• godot-raycasting-queries — 状态回滚后用于权威射击判定的服务端射线／形状查询。
• godot-debugging-profiling — RTT／抖动叠加层和远程调试习惯，可捕获本地主机上无法复现的同步错误。
• godot-export-builds — 用于真实多实例测试的无头／专用服务端导出预设和 CLI 标志。
• godot-server-architecture — 回滚和专用对等端使用的 PhysicsServer／RID 模式及无头主机脚手架。

下游／使用方

• godot-genre-shooter-fps — 依赖此技能提供的预测和延迟补偿的即时命中／投射物手感。
• godot-genre-battle-royale — BR 规模下的大型对等端兴趣管理和迟到加入时的快照。
• godot-monte-carlo-balancer — 在网络代码变更影响实际武器时序后，重新调整经济系统／TTK。
• godot-performance-optimization — 当带宽／CPU 预算在对等端负载下超限时，限制复制速率并裁剪兴趣范围。

主模块

• godot-master — 此领域技能的库路由器和镜像模块入口。