godot-server-architecture

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Server Architecture

服务器架构

RID-based server API, direct rendering/physics access, and object pooling define maximum-performance patterns.

基于RID的服务器API、直接渲染/物理访问以及对象池是实现极致性能的核心模式。

Available Scripts

可用脚本

headless_init_manager.gd

Automatically detecting and initializing dedicated server logic when launched with

--headless

dedicated_server

features.

在使用

--headless

或

dedicated_server

特性启动时，自动检测并初始化专用服务器逻辑。

enet_optimized_host.gd

Expert initialization of high-performance ENet UDP hosts with precise bandwidth and client limits.

通过精确的带宽和客户端限制，实现高性能ENet UDP主机的专家级初始化。

dtls_secure_server.gd

Securing ENet UDP traffic using DTLS and X509 certificates to prevent man-in-the-middle attacks.

使用DTLS和X509证书加密ENet UDP流量，防止中间人攻击。

physics_server_direct.gd

Massive scale simulation pattern that bypasses the SceneTree by creating bodies directly on the

PhysicsServer3D

通过直接在

PhysicsServer3D

上创建物理体，实现大规模物理模拟的模式，绕过SceneTree的开销。

safe_packet_decoder.gd

Crucial network security pattern that explicitly forbids object decoding to prevent Remote Code Execution (RCE) vulnerabilities.

关键的网络安全模式：明确禁止对象解码，以防止远程代码执行（RCE）漏洞。

manual_network_poll.gd

Moving networking off the main thread by disabling automatic polling and managing manual

multiplayer.poll()

loops.

通过禁用自动轮询并管理手动

multiplayer.poll()

循环，将网络操作移出主线程。

isolated_multiplayer_api.gd

Pattern for running Client and Server branches independently within a single Godot instance via isolated API instances.

通过隔离的API实例，在单个Godot实例内独立运行客户端和服务器分支的实现模式。

server_authority_validator.gd

Authoritative entry point validation using

get_remote_sender_id()

to strictly verify client requests.

使用

get_remote_sender_id()

进行权威入口点验证，严格校验客户端请求。

websocket_server_compat.gd

Ensuring compatibility with HTML5/Web browser clients using

WebSocketMultiplayerPeer

architecture.

使用

WebSocketMultiplayerPeer

架构确保与HTML5/网页浏览器客户端的兼容性。

peer_kick_manager.gd

Graceful termination and cleanup of peer connections with custom reason propagation.

实现带自定义原因通知的优雅对等连接终止与清理。

NEVER Do in Server Architecture

服务器架构中的绝对禁忌

NEVER trust the client — Validate all state changes, purchases, and damage exclusively on the authoritative server to prevent cheating [28].
NEVER use
TRANSFER_MODE_RELIABLE
for continuous data streams — Synchronizing coordinates every frame using reliable mode causes extreme network congestion; always use
```
UNRELIABLE
```
[29].
NEVER use
get_var(true)
on untrusted network packets — Passing
```
true
```
allows the engine to deserialize arbitrary objects, creating a critical Remote Code Execution vulnerability [30].
NEVER use TCP for fast-paced action games — TCP's Nagle's algorithm and congestion control cause unacceptable latency; use Godot's built-in ENet (UDP) [31].
NEVER run a dedicated server without stripping visuals — Always export using "Dedicated Server" mode or use the
```
Dummy
```
audio/physics drivers to prevent GPU/CPU waste [32].
NEVER expect RPCs to work before connection — Calling an RPC on a client before the
```
connected_to_server
```
signal has fired will fail [34].
NEVER assume
UNRELIABLE
packets arrive in order — UDP packets can arrive out of order or be dropped; design state interpolation to handle missing ticks [31].
NEVER leave
SceneTree.multiplayer_poll
set to false without manually calling
poll()
— Disabling auto-polling without manual polling freezes all network traffic [35].
NEVER attempt to connect Godot clients and servers running different engine versions — The high-level multiplayer API protocol is version-specific and breaking [36].
NEVER forget to unbind or free RIDs —
```
PhysicsServer3D.body_create()
```
without
```
free_rid()
```
causes massive server-side memory leaks over time.

Direct access to rendering without nodes.

gdscript

undefined

绝对不要信任客户端 — 所有状态变更、购买操作和伤害计算必须仅在权威服务器上进行验证，以防止作弊 [28]。
绝对不要对连续数据流使用
TRANSFER_MODE_RELIABLE
— 每帧使用可靠模式同步坐标会导致严重的网络拥塞；请始终使用
```
UNRELIABLE
```
[29]。
绝对不要在不可信的网络数据包上使用
get_var(true)
— 传入
```
true
```
会允许引擎反序列化任意对象，从而引发严重的远程代码执行（RCE）漏洞 [30]。
绝对不要在快节奏动作游戏中使用TCP — TCP的Nagle算法和拥塞控制会导致无法接受的延迟；请使用Godot内置的ENet（UDP） [31]。
绝对不要在不剥离视觉资源的情况下运行专用服务器 — 请始终使用“专用服务器”模式导出，或使用
```
Dummy
```
音频/物理驱动，以避免GPU/CPU资源浪费 [32]。
绝对不要在连接建立前调用RPC — 在
```
connected_to_server
```
信号触发前调用客户端RPC会执行失败 [34]。
绝对不要假设
UNRELIABLE
数据包会按顺序到达 — UDP数据包可能乱序或丢失；请设计状态插值逻辑以处理丢失的帧 [31]。
绝对不要在禁用
SceneTree.multiplayer_poll
后不手动调用
poll()
— 禁用自动轮询但不进行手动轮询会导致所有网络通信冻结 [35]。
绝对不要尝试连接运行不同引擎版本的Godot客户端和服务器 — 高层多人游戏API协议与版本强绑定，跨版本会出现兼容性问题 [36]。
绝对不要忘记解绑或释放RID — 调用
```
PhysicsServer3D.body_create()
```
后不调用
```
free_rid()
```
会导致服务器端长期内存泄漏。

无需节点的直接渲染访问。

gdscript

undefined

Create canvas item (2D sprite equivalent)

创建画布项（相当于2D精灵）

var canvas_item := RenderingServer.canvas_item_create() RenderingServer.canvas_item_set_parent(canvas_item, get_canvas_item())

Draw texture

绘制纹理

var texture_rid := load("res://icon.png").get_rid() RenderingServer.canvas_item_add_texture_rect( canvas_item, Rect2(0, 0, 64, 64), texture_rid )

undefined

var texture_rid := load("res://icon.png").get_rid() RenderingServer.canvas_item_add_texture_rect( canvas_item, Rect2(0, 0, 64, 64), texture_rid )

undefined

PhysicsServer2D

Create physics bodies without nodes.

gdscript

undefined

无需节点创建物理体。

gdscript

undefined

Create body

创建物理体

var body_rid := PhysicsServer2D.body_create() PhysicsServer2D.body_set_mode(body_rid, PhysicsServer2D.BODY_MODE_RIGID)

Create shape

创建形状

var shape_rid := PhysicsServer2D.circle_shape_create() PhysicsServer2D.shape_set_data(shape_rid, 16.0) # radius

var shape_rid := PhysicsServer2D.circle_shape_create() PhysicsServer2D.shape_set_data(shape_rid, 16.0) # 半径

Assign shape to body

为物理体分配形状

PhysicsServer2D.body_add_shape(body_rid, shape_rid)

undefined

PhysicsServer2D.body_add_shape(body_rid, shape_rid)

undefined

When to Use Servers

何时使用服务器

Use servers for:

Procedural generation (thousands of objects)
Particle systems
Voxel engines
Custom rendering

Use nodes for:

Regular game objects
UI
Prototyping

使用服务器的场景：

程序化生成（数千个对象）
粒子系统
体素引擎
自定义渲染

使用节点的场景：

常规游戏对象
UI界面
原型开发

Reference

参考资料

Godot Docs: Using Servers

Godot官方文档：使用服务器

godot-server-architecture

Original

Translation

Server Architecture

服务器架构

Available Scripts

可用脚本

headless_init_manager.gd

headless_init_manager.gd

enet_optimized_host.gd

enet_optimized_host.gd

dtls_secure_server.gd

dtls_secure_server.gd

physics_server_direct.gd

physics_server_direct.gd

safe_packet_decoder.gd

safe_packet_decoder.gd

manual_network_poll.gd

manual_network_poll.gd

isolated_multiplayer_api.gd

isolated_multiplayer_api.gd

server_authority_validator.gd

server_authority_validator.gd

websocket_server_compat.gd

websocket_server_compat.gd

peer_kick_manager.gd

peer_kick_manager.gd

NEVER Do in Server Architecture

服务器架构中的绝对禁忌

Create canvas item (2D sprite equivalent)

创建画布项（相当于2D精灵）

Draw texture

绘制纹理

PhysicsServer2D

PhysicsServer2D

Create body

创建物理体

Create shape

创建形状

Assign shape to body

为物理体分配形状

When to Use Servers

何时使用服务器

Reference

参考资料

Related

相关技能