godot-multiplayer-networking

绝对不要做的事（网络专家规则）

核心架构

• 绝对不要将 Reliable 用于高频数据（位置/移动） — 可靠数据包会阻塞后续所有数据包，直到收到确认（队头阻塞）。请使用 UnreliableOrdered。
• 绝对不要信任客户端提供的共享状态（生命值/金钱/物品栏） — 客户端只能提出操作建议。服务器必须验证并广播结果。
• 绝对不要硬编码服务器 IP — 始终支持发现（net_lan_discovery.gd），或通过 CLI/UI 传入 IP。

性能与带宽

• 绝对不要每帧发送相同的数据 — 使用 net_adaptive_sync_throttle.gd，仅在状态发生显著变化时，或按固定频率间隔（例如 20Hz）发送更新。
• 绝对不要将 JSON 用于高速同步 — 字符串序列化会大幅增加网络传输量。请使用位打包（net_packet_bit_packer.gd），将数据包控制在 100 字节以内。
• 非必要时绝对不要向所有对等端广播 — 在大型世界中，请使用兴趣管理（net_visibility_grid_culling.gd）。身处森林中的玩家不需要知道身处城市中的玩家的位置。

安全

• 绝对不要允许每秒无限次 RPC 调用 — 攻击者可以发送 1,000 个“Attack” RPC 淹没服务器，导致游戏崩溃。请使用 net_packet_rate_limiter.gd。
• 绝对不要向最终用户暴露 PeerID — PeerID 是内部标识。始终通过数据库中的持久化 UserID（net_custom_id_mapper.gd）进行映射。
• 绝对不要在启用 GUI 的情况下运行专用服务器 — 使用 --headless（net_headless_server_auto_start.gd）以节省资源并确保稳定性。

决策树（传输方式 / 权限归属 / 同步频率）

问题	首选方案	脚本
桌面端/主机 LAN 或专用 UDP	ENet	必需 net_enet_expert_config.gd
浏览器 / NAT 不友好的对等端	WebRTC（或 WebSocket 回退方案）	官方文档 + 对等端封装；仍需使用安全 RPC 脚本
谁拥有游戏状态的最终决定权？	服务器权威模式	必需 server_authoritative_controller.gd
无 GUI 的专用主机	--headless	必需 net_headless_server_auto_start.gd / server_dedicated_host.gd
位置每秒同步 10–20 次，而非每帧同步	自适应节流	必需 net_adaptive_sync_throttle.gd

不要从记忆中加载 大厅/RPC 入门范例 — 请使用下方的黄金路径，并且只打开匹配的脚本。

黄金路径

1. 主机 / 专用服务器 → server_dedicated_host.gd + net_headless_server_auto_start.gd；客户端 → client_network_setup.gd。
2. 安全 RPC → secured_rpc_pattern.gd + net_packet_rate_limiter.gd + secure_variable_synchronizer.gd。
3. 预测 / 校正 → client_prediction_synchronizer.gd + net_anti_desync_reconciler.gd；战斗/回滚 → net_rollback_helper.gd。
4. 兴趣剔除 → 广播位置前使用 net_visibility_grid_culling.gd。

可用脚本

传输与主机

• net_enet_expert_config.gd — 通道、压缩、带宽。
• net_headless_server_auto_start.gd — 检测 CLI/--headless。
• server_dedicated_host.gd — 专用主机引导。
• client_network_setup.gd — 客户端对等节点加入。
• net_lan_discovery.gd — UDP 局域网发现。
• network_error_handler.gd — 断开连接/错误路由。
• packet_peer_latency_test.gd — 延迟探测。
• net_heartbeat_monitor.gd — RTT/抖动。

权限、RPC、同步

• server_authoritative_controller.gd — 服务端验证操作。
• secured_rpc_pattern.gd — 安全的 RPC 注解/模式。
• secure_variable_synchronizer.gd — 服务端拥有的变量。
• net_packet_rate_limiter.gd — 洪泛防护。
• net_packet_bit_packer.gd — 精简负载（热路径不使用 JSON）。
• net_adaptive_sync_throttle.gd — 按 Hz / 变化阈值同步。
• game_state_sync_manager.gd — 快照/状态同步。
• multiplayer_spawner_manager.gd — 生成权限。
• network_input_synchronizer.gd — 将输入帧发送到服务端。
• networked_interpolator.gd — 远程实体平滑处理。
• net_custom_id_mapper.gd — UserID ↔ PeerID。

不同步 / 回滚 / 兴趣管理

• client_prediction_synchronizer.gd — 预测与校正。
• net_anti_desync_reconciler.gd — 强制校正。
• net_rollback_helper.gd — 快照重新模拟辅助工具。
• net_visibility_grid_culling.gd — 兴趣管理。

专家提示

• 位置/移动：使用 UnreliableOrdered + 节流——切勿每帧都可靠发送。
• 客户端提出建议；服务端验证并广播结果。
• 大型世界：先用可见性网格剔除，再增加同步 Hz。

深入了解（按需）

• RPC 模式、大厅握手、傀儡插值 → rpc-lobby-and-sync.md
• 差量压缩和网络模拟器概念见该参考文档（LLM 未知：不可靠与可靠传输的队头阻塞并非通用知识）。

参考

渐进式披露：仅在研究特定 API 时打开官方文档链接；在路由到相关领域时加载相关技能——不要预加载整个技能网格。

官方文档

• 高级多人游戏 — RPC 模式、权限以及对等端生命周期，用于主机/加入大厅和由服务器验证的操作。
• 网络 — 传输方式概览（ENet / WebSocket / WebRTC / HTTP），帮助根据平台和 NAT 限制选择合适的对等端。
• MultiplayerAPI — multiplayer 单例：对等端 ID、连接信号以及 rpc / rpc_id 入口。
• MultiplayerPeer — 各后端通用的传输模式（可靠 / 不可靠 / 无序）和连接状态。
• ENetMultiplayerPeer — 用于局域网、专用服务器和大多数动作游戏的 UDP 主机/客户端对等端。
• SceneMultiplayer — 默认的 MultiplayerAPI：根路径、身份验证回调以及场景树 RPC 路由。
• MultiplayerSpawner — 生成/销毁复制，使晚加入的玩家也能共享相同的联网场景图。
• MultiplayerSynchronizer — 属性复制、变更时增量更新和可见性过滤器，可替代临时的位置 RPC。
• Node — set_multiplayer_authority / is_multiplayer_authority 所定义的所有权规则，用于区分输入与共享状态。
• PacketPeerUDP — 通过原始 UDP 发送/接收数据包，在高级多人游戏对等端之外实现局域网发现广播。
• WebRTC — 当 ENet UDP 无法单独穿透防火墙时，适用于浏览器的 P2P 方案。
• 命令行教程 — 用于启动专用服务器和多实例测试的 --headless 及 CLI 标志。

相关技能

前置条件

• godot-project-foundations — 项目布局、Autoload，以及主机/加入和专用服务器构建所依赖的导出/功能标志。
• godot-gdscript-mastery — 安全 RPC 和位打包器所用的类型化 @rpc 注解、Callable 和 PackedByteArray 模式。
• godot-input-handling — 将 InputMap 读取与模拟分开，使客户端发送意图，并由权限方决定结果。

补充

• godot-adapt-single-to-multiplayer — 在应用此技能的大厅/RPC/ENet 工具包前，先确定迁移方案（权限拆分、预测框架）。
• godot-autoload-architecture — 在主机/加入和重新连接流程中，负责跨场景变更持续存在的会话/大厅 Autoload。
• godot-signal-architecture — 与传输 RPC 解耦的本地对等连接/大厅事件。
• godot-server-architecture — 权威模拟所用的无头主机脚手架和 PhysicsServer/RID 模式。
• godot-export-builds — 用于真实多实例测试的专用服务器导出预设和 CLI 打包。
• godot-debugging-profiling — RTT/抖动叠加层和远程调试习惯，可捕获本地主机测试无法发现的同步错误。
• godot-save-load-systems — 持久化 UserID、大厅偏好和重新连接令牌，不要将 PeerID 视为持久身份。

下游 / 使用方

• godot-performance-optimization — 当带宽/CPU 预算在对等端负载下超限时，限制复制频率并进行兴趣裁剪。
• godot-monte-carlo-balancer — 当网络代码变更改变有效武器时序或技能窗口后，重新调整经济系统/TTK。
• godot-genre-battle-royale — BR 规模下的大量对等端兴趣管理和迟到加入者快照。
• godot-genre-moba — 多人竞技场的固定 tick 权限、技能 RPC 和适用于观战者的状态同步。

主索引

• godot-master — 技能库路由器和镜像模块入口；探索哪个领域技能负责跨领域网络问题时请打开此项。