godot-server-architecture

技能边界（请勿加载）

使用此技能的场景	使用 godot-multiplayer-networking 的场景
--headless / 专用服务器导出启动	大厅 UI、匹配体验、好友邀请
ENet/DTLS 主机对等端 + 安全解码	RPC 签名、@rpc 游戏玩法处理程序
特权操作的权限验证	MultiplayerSynchronizer / 场景复制
踢出、健康遥测、匹配器移交	客户端预测、延迟补偿

仅在启动主机时，请勿加载 multiplayer-networking 中有关大厅/RPC 的教程脚本——请先遵循此处的主机黄金路径。

主机黄金路径（强制）

1. 无头检测/初始化 — 强制使用 headless_init_manager.gd（--headless / dedicated_server 特性）。
2. 安全解码 — 在任何不可信的 get_var 调用之前，强制使用 safe_packet_decoder.gd。
3. 主机对等端 — 使用 enet_optimized_host.gd；加密 UDP 时添加 dtls_secure_server.gd。
4. 权限验证 — 对每个特权 RPC 使用 server_authority_validator.gd。
5. 运维 — 使用 peer_kick_manager.gd、server_health_exporter.gd；通过 server_matchmaker_client.gd 移交给匹配器。

可用脚本

headless_init_manager.gd

为 --headless / dedicated_server 检测并初始化专用服务器逻辑。

headless_manager.gd

无头运行时管理器的配套模式。

enet_optimized_host.gd

高性能 ENet UDP 主机，支持带宽/客户端数量限制。

dtls_secure_server.gd

为 ENet UDP 提供 DTLS + X509 加固。

safe_packet_decoder.gd

禁止解码不可信数据包中的对象（防止远程代码执行）。

manual_network_poll.gd

禁用自动轮询时手动调用 multiplayer.poll()。

isolated_multiplayer_api.gd

隔离的 MultiplayerAPI 实例（在同一进程中运行客户端和服务器）。

server_authority_validator.gd

对权威请求使用 get_remote_sender_id() 进行门控。

websocket_server_compat.gd

兼容 HTML5 的 WebSocketMultiplayerPeer 主机。

peer_kick_manager.gd

优雅地终止对等端并传递原因。

server_matchmaker_client.gd

将负载均衡器/匹配器移交给游戏主机。

server_health_exporter.gd

用于监控技术栈的无头遥测。

physics_server_direct.gd / rid_performance_server.gd

可选的主机端 RID 模拟——仅当节点物理无法满足每帧预算时使用：每帧有 > ~200 个活动物体，或使用节点时，无头主机在物理步骤中的 CPU 占用 > 70%。判断标准：先进行性能分析；如果 SceneTree 中的物体占用主要资源，优先使用 godot-performance-optimization。对于 ≤64 个实体的大厅，请勿加载 RID 脚本。

服务端架构（主机）中绝对不要做的事

• 绝不信任客户端——在权威主机上验证状态、购买记录和伤害。
• 绝不对连续流使用 TRANSFER_MODE_RELIABLE——高频变换数据应优先使用不可靠传输。
• 绝不对不可信数据包使用 get_var(true)——对象解码会导致远程代码执行（RCE）。必须使用 safe_packet_decoder。
• 绝不在快节奏动作游戏中使用 TCP——优先使用 ENet UDP（或在 HTML5 限制下使用 WebSocket）。
• 绝不在未剥离视觉效果的情况下运行专用服务器——使用 Dedicated Server 导出 / 虚拟驱动程序。
• 绝不在 connected_to_server / 对等端就绪前期待 RPC 到达。
• 绝不假设 UNRELIABLE 数据包会按顺序到达。
• 绝不在未手动调用 poll() 的情况下将 SceneTree.multiplayer_poll 设为 false。
• 绝不在对等端之间混用不兼容的引擎 / 多人游戏协议版本。
• 如果主机使用 Physics/RenderingServer 池，绝不忘记释放服务器创建的 RID，使用 free_rid。

主机模式

兴趣管理

大型世界：使用 MultiplayerSynchronizer.public_visibility = false + 可见性筛选器（AABB / 网格），避免主机向每个对等端同步整个世界。

# Hook on synchronizer — filter peers by grid cell / AABB (no full tutorial)
func _visibility_filter(for_peer: int, node: Node) -> bool:
	return _interest_grid.is_visible_to_peer(for_peer, node.global_position)
# Assign: synchronizer.set_visibility_filter(_visibility_filter)

健康指标

通过 server_health_exporter.gd 监控主机 FPS、静态内存（RID 泄漏）和孤立对象数量。

深入方案（按需查阅）

LLM 无知规则：如果通用 Agent 在阅读前不会了解某项内容，它就应放在这里或 scripts/ 中——绝不删除，只能移动。

主题	参考资料
RID 画布 / 物理烹饪指南	rendering-physics-server-cookbook.md

参考资料

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

官方文档

• 使用服务器 — 当 SceneTree 节点速度太慢时，采用基于 RID 的 RenderingServer/PhysicsServer/NavigationServer 工作流。
• RenderingServer — 使用 canvas_item_* / instance_* / free_rid，无需 MeshInstance 节点即可实现程序化绘制和网格群集。
• PhysicsServer3D — body_create、空间绑定和直接状态查询，可用于无头权威模拟。
• PhysicsServer2D — 2D 刚体/形状 RID 遵循相同的绕过 SceneTree 模式。
• RID — 不透明的服务器句柄；每个 *_create() 都需要对应的 free_rid，以避免泄漏。
• 高级多人游戏 — 专用主机和隔离的 MultiplayerAPI 分支所需的权限、RPC 和对等端生命周期。
• ENetMultiplayerPeer — UDP 主机创建、通道/带宽限制，以及在 peer.host 上设置 DTLS 主机。
• WebSocket 多人游戏 — ENet UDP 不可用时的浏览器兼容对等端方案（HTML5 客户端）。
• 导出专用服务器 — 专用服务器导出预设，以及为生产环境主机剥离视觉效果/音频。
• 命令行教程 — 无头初始化/管理器使用的 --headless 和 CLI 标志。
• 二进制序列化 API — get_var(false) / 对象解码规则，可阻止不可信数据包触发 RCE。
• DTLSServer — 与 ENet dtls_server_setup 配套的 DTLS 接受流程，支持 X509/TLSOptions。

相关技能

前置要求

• godot-project-foundations — 项目布局、Autoload 和功能标签；专用服务器和无头启动依赖这些内容。
• godot-gdscript-mastery — 类型化 RID 数组、@rpc 注解，以及服务器脚本中使用的安全 Variant 解码模式。
• godot-physics-3d — 在使用 PhysicsServer3D RID 绕过节点之前，先了解节点级 PhysicsBody3D/空间概念。

补充

• godot-multiplayer-networking — 大厅/RPC/同步器工具包，可与此技能搭建的无头 ENet/WebSocket 主机配合使用。
• godot-adapt-single-to-multiplayer — 在接入专用服务器验证和兴趣过滤器之前，先搭建权限拆分和预测框架。
• godot-export-builds — 用于真实多实例主机测试的专用服务器导出预设和 CLI 打包。
• godot-2d-physics — 用于不依赖 SceneTree 节点的 2D 权威群集的 PhysicsServer2D 主体/形状模式。
• godot-navigation-pathfinding — 当 AI Agent 共用同一底层服务器路径时使用的 NavigationServer RID 和烘焙更新。
• godot-performance-optimization — 用于判断在对等端/对象负载下 RID 服务器何时优于节点的预算和性能分析。
• godot-debugging-profiling — 用于无头 FPS/内存/孤儿对象遥测的性能监视器和远程调试实践。
• godot-platform-web — HTML5 客户端限制使其必须使用 WebSocketMultiplayerPeer，而不能使用 ENet。

下游 / 使用方

• godot-procedural-generation — 使用 RenderingServer/PhysicsServer RID 池的海量对象/体素生成器。
• godot-monte-carlo-balancer — 在权威服务器 tick 频率或验证机制改变有效战斗窗口后，重新调整经济/TTK。
• godot-genre-battle-royale — 需要兴趣网格、踢出/健康状态导出器和 RID 规模模拟的大型对等端专用主机。

主索引

• godot-master — 资源库路由器和镜像模块入口；查找负责跨领域服务器问题的领域技能时打开。