Godot引擎WebSocket实战：从基础连接到多人游戏网络同步

1. 项目概述

在游戏开发中，实时通信能力往往是决定项目成败的关键一环。无论是构建一个多人在线竞技场，还是一个需要实时数据同步的协作工具，传统的HTTP轮询方式在高频、低延迟的场景下显得力不从心。这时，WebSocket协议就成了一个优雅的解决方案。它允许在单个TCP连接上进行全双工通信，服务器可以主动向客户端推送数据，非常适合聊天、实时游戏状态同步、在线协作编辑等场景。

Godot引擎，作为一个功能全面的开源游戏引擎，从4.0版本开始就内置了对WebSocket的完善支持。它通过WebSocketPeer和WebSocketClient等类，将底层的网络通信细节封装起来，让开发者能够以相对简单的方式，将实时通信能力集成到自己的2D、3D游戏或应用项目中。这意味着你不再需要依赖复杂的外部库或中间件，直接在GDScript或C#中就能处理连接、发送和接收消息。

这篇文章将带你深入Godot的WebSocket世界。我会从一个简单的“回声服务器”示例开始，逐步拆解客户端与服务器的搭建、数据收发、连接状态管理，并探讨如何将其与Godot的高层多人游戏API结合，构建更复杂的实时交互应用。无论你是想做一个简单的在线聊天室，还是一个需要帧同步的多人游戏，这里的内容都将为你打下坚实的基础。

2. WebSocket核心概念与Godot实现解析

2.1 WebSocket协议简述

在深入代码之前，理解WebSocket的基本工作原理至关重要。你可以把它想象成电话线，而HTTP请求更像是寄明信片。打电话（WebSocket）建立连接后，双方可以随时自由交谈；而寄明信片（HTTP）每次都需要完整的地址、邮票和一次独立的投递过程。

WebSocket协议始于一次标准的HTTP“握手”请求。客户端发送一个带有Upgrade: websocket等特殊头部的HTTP请求，服务器如果支持，就会响应“101 Switching Protocols”，从此，这条连接就“升级”为WebSocket连接，后续的所有通信都基于WebSocket帧进行，与HTTP无关了。这种设计使得WebSocket可以穿透大多数防火墙和代理，同时保持了极低的通信开销。

Godot的WebSocketPeer类抽象了这一切。它负责管理底层的TCP套接字、处理WebSocket握手协议、组帧和解析帧。作为开发者，你只需要关心几个核心状态：连接中、已打开、关闭中、已关闭，以及两个核心操作：发送数据和轮询接收。

2.2 Godot中的WebSocket类族

Godot提供了几个关键类来处理WebSocket：

1. WebSocketPeer: 这是最基础的类，代表一个WebSocket对等点（可以是客户端，也可以是服务器端接受的连接）。它提供了连接、发送、接收、轮询和获取状态等所有底层操作。我们上面提到的“电话机”就是这个类。
2. WebSocketClient(在Godot 4.x中通常直接使用WebSocketPeer的客户端模式): 虽然文档中提到了WebSocketClient，但在实际使用中，创建客户端连接更常见的做法是直接实例化一个WebSocketPeer，然后调用其connect_to_url方法。这个类可能封装了一些额外的客户端便利功能。
3. TCPServer: 在创建WebSocket服务器时，我们需要先用TCPServer监听一个端口，接受原始的TCP连接，然后再用WebSocketPeer的accept_stream方法将这个TCP流“升级”为WebSocket连接。

这里有一个重要的设计模式：非阻塞与轮询。网络I/O操作（如接收数据）通常是阻塞的，但游戏主循环必须保持流畅。Godot采用了轮询（Polling）机制。你需要在_process()或_physics_process()函数中定期调用WebSocketPeer.poll()方法。这个方法会处理所有挂起的网络事件：检查是否有新数据到达、连接是否建立或关闭，但它不会阻塞你的游戏线程。如果poll()之后有可用的数据包，你就可以用get_packet()来获取。

2.3 连接生命周期与状态管理

一个WebSocket连接的生命周期清晰地反映在WebSocketPeer.get_ready_state()返回的状态中：

• STATE_CONNECTING (0): 正在尝试建立连接。此时不应进行数据发送。
• STATE_OPEN (1): 连接已成功建立，握手完成。此时可以安全地发送和接收数据。这是我们主要进行业务逻辑的状态。
• STATE_CLOSING (2): 连接正在关闭中（一方发起了关闭握手）。你仍然可以接收最后的数据，但不应再发送新数据。必须继续调用poll()，以确保关闭流程顺利完成。
• STATE_CLOSED (3): 连接已完全关闭。此时应停止对该连接的轮询，并释放相关资源。

注意：很多新手会忽略STATE_CLOSING状态。如果在收到关闭帧后不继续调用poll()，连接可能无法干净地终止，导致资源泄漏或端口占用。正确的做法是，在检测到STATE_CLOSING后，依然保持轮询，直到状态变为STATE_CLOSED。

3. 构建一个完整的WebSocket回声服务器

理论说再多，不如动手写一遍。我们来构建一个功能更健全的服务器，它不仅能回显消息，还能处理多个客户端的连接与断开，并记录日志。

3.1 服务器节点结构与初始化

首先，在Godot中创建一个新场景，添加一个名为WebSocketServer的Node节点，并为其附加脚本。

extends Node # 监听的端口号 @export var server_port: int = 9080 # 允许的最大并发连接数（简单实现，实际需更复杂的管理） @export var max_connections: int = 100 # TCP服务器实例 var _tcp_server: TCPServer # 存储所有活跃的WebSocket对等点，键为自定义的客户端ID，值为WebSocketPeer实例 var _connected_peers: Dictionary = {} # 用于生成唯一客户端ID的计数器 var _next_peer_id: int = 1 # 服务器是否正在运行 var _is_running: bool = false func _ready(): start_server() func start_server(): _tcp_server = TCPServer.new() var err = _tcp_server.listen(server_port) if err != OK: push_error("Failed to start server on port %d: Error %d" % [server_port, err]) return _is_running = true print("WebSocket Echo Server started on port %d" % server_port) func stop_server(): _is_running = false # 优雅关闭所有客户端连接 for peer_id in _connected_peers.keys(): var peer: WebSocketPeer = _connected_peers[peer_id] # 发送关闭帧，code 1000 表示正常关闭 peer.close(1000, "Server shutting down") # 清空列表，实际项目中可能需要等待所有连接真正关闭 _connected_peers.clear() if _tcp_server: _tcp_server.stop() print("Server stopped.")

这段代码定义了服务器的基本骨架。@export关键字使得端口和最大连接数可以在编辑器的检查器中直接调整，非常方便。_tcp_server.listen()是启动服务的关键，如果返回OK，说明套接字绑定成功。

3.2 处理客户端连接与轮询

服务器的核心工作是在_process循环中完成的：接受新连接，并轮询所有已连接客户端的消息。

func _process(delta): if not _is_running: return # 1. 接受新的TCP连接并升级为WebSocket _accept_new_connections() # 2. 轮询和处理所有已连接客户端 _poll_existing_connections() func _accept_new_connections(): # 检查是否有等待接受的连接 while _tcp_server.is_connection_available(): if _connected_peers.size() >= max_connections: print("Server is full, rejecting new connection.") # 可以在这里获取连接并立即关闭，这里简单跳过 var temp_conn = _tcp_server.take_connection() temp_conn.close() # 简单处理，实际应发送HTTP 503等响应 continue var new_tcp_connection: StreamPeerTCP = _tcp_server.take_connection() var ws_peer = WebSocketPeer.new() # 关键步骤：将TCP流“升级”为WebSocket连接 var accept_result = ws_peer.accept_stream(new_tcp_connection) if accept_result != OK: push_error("Failed to accept WebSocket connection: Error %d" % accept_result) new_tcp_connection.close() continue var peer_id = _next_peer_id _next_peer_id += 1 _connected_peers[peer_id] = ws_peer print("Client [ID: %d] connected. Total clients: %d" % [peer_id, _connected_peers.size()]) # 可选：向新客户端发送欢迎消息 ws_peer.send_text("Welcome to the Echo Server! Your ID is %d." % peer_id) func _poll_existing_connections(): # 遍历所有客户端ID的副本，因为可能在循环中删除元素 for peer_id in _connected_peers.keys().duplicate(): var peer: WebSocketPeer = _connected_peers[peer_id] # 必须调用poll()来处理网络事件 peer.poll() var state = peer.get_ready_state() match state: WebSocketPeer.STATE_OPEN: _handle_open_peer(peer_id, peer) WebSocketPeer.STATE_CLOSING: # 连接正在关闭，继续轮询直到关闭完成 pass WebSocketPeer.STATE_CLOSED: _handle_closed_peer(peer_id, peer) # STATE_CONNECTING 在服务端accept后通常瞬间进入OPEN，这里一般不会遇到

这里有几个关键点：

1. take_connection(): 这个方法从TCP服务器的等待队列中取出一个已建立的TCP连接，返回一个StreamPeerTCP对象。每个循环中要用while来处理可能同时到达的多个连接。
2. accept_stream(): 这是将普通TCP连接升级为WebSocket连接的魔法。它内部完成了WebSocket的握手协议。
3. 使用keys().duplicate()遍历: 在遍历字典时，如果直接在循环体内修改字典（如删除断开连接的客户端），会导致运行时错误。先复制键列表再遍历是安全的做法。
4. match语句: Godot 4.x 的match语句比一堆if-elif更清晰，非常适合处理这种状态机。

3.3 实现消息处理与回声逻辑

现在，我们来填充_handle_open_peer函数，处理客户端发来的消息。

func _handle_open_peer(peer_id: int, peer: WebSocketPeer): # 检查并处理所有已到达的数据包 while peer.get_available_packet_count() > 0: var packet: PackedByteArray = peer.get_packet() if peer.was_string_packet(): # 收到文本消息 var message = packet.get_string_from_utf8() print("Received TEXT from Client [%d]: %s" % [peer_id, message]) # 回声逻辑：将消息原样发回 var echo_message = "Echo (ID:%d): %s" % [peer_id, message] peer.send_text(echo_message) # 可选：广播给其他所有客户端（简易聊天室功能） # _broadcast_message(peer_id, message) else: # 收到二进制消息 print("Received BINARY from Client [%d], size: %d bytes" % [peer_id, packet.size()]) # 回声二进制数据 peer.send(packet) # 注意：发送二进制数据用 `send()`，不是 `send_text()`

• get_available_packet_count(): 检查当前有多少个完整的数据包在缓冲区中等待处理。WebSocket协议是基于消息的，一个send操作对应一个完整的消息包。
• get_packet(): 取出一个完整的消息包，返回PackedByteArray（字节数组）。
• was_string_packet(): 判断刚取出的包是否是按文本帧发送的。WebSocket协议区分文本帧和二进制帧。文本帧的内容应该是有效的UTF-8字符串。
• get_string_from_utf8(): 将PackedByteArray按UTF-8编码解码成字符串。
• send_text()vssend(): 这是最重要的区别之一。send_text()用于发送字符串，引擎会自动将其编码为UTF-8并使用文本帧发送。send()用于发送原始的PackedByteArray，会使用二进制帧发送。如果你发送的是JSON字符串，用send_text()；如果你发送的是序列化的游戏状态（例如使用var2bytes），用send()。

3.4 处理连接关闭与资源清理

最后，我们需要妥善处理客户端断开连接的情况。

func _handle_closed_peer(peer_id: int, peer: WebSocketPeer): var close_code = peer.get_close_code() var close_reason = peer.get_close_reason() var was_clean = close_code != -1 # -1 通常表示连接非正常中断（如网络错误） print("Client [ID: %d] disconnected. Code: %d, Reason: '%s', Clean: %s" % [peer_id, close_code, close_reason, was_clean]) # 从活跃连接字典中移除 _connected_peers.erase(peer_id) # 注意：WebSocketPeer对象本身会被Godot的引用计数自动管理，这里移除引用即可。

• 关闭代码 (Close Code): WebSocket协议定义了一系列标准关闭代码（如1000表示正常关闭，1001表示端点“离开”）。-1通常表示底层TCP连接异常断开，没有收到规范的WebSocket关闭握手帧。
• 关闭原因 (Close Reason): 一个可选的字符串，说明关闭的原因。
• 清理连接: 确保从管理结构中移除断开连接的peer，防止内存泄漏和后续轮询错误。

至此，一个功能完整的、支持多客户端的WebSocket回声服务器就搭建好了。你可以运行这个服务器，然后用任何WebSocket客户端（如浏览器开发者工具中的WebSocket控制台，或websocat命令行工具）连接到ws://localhost:9080进行测试。

4. 开发健壮的WebSocket客户端

有了服务器，自然需要一个与之匹配的客户端。在Godot中，客户端逻辑通常放在一个独立的场景或节点中。

4.1 客户端场景与自动重连机制

我们创建一个WebSocketClient场景，根节点是一个Node，并附上脚本。

extends Node @export var server_url: String = "ws://localhost:9080" @export var auto_reconnect: bool = true @export var reconnect_delay_sec: float = 3.0 var _websocket_peer: WebSocketPeer var _connection_in_progress: bool = false var _reconnect_timer: Timer func _ready(): _reconnect_timer = Timer.new() _reconnect_timer.one_shot = true _reconnect_timer.timeout.connect(_attempt_reconnect) add_child(_reconnect_timer) connect_to_server() func connect_to_server(): if _connection_in_progress: return print("Attempting to connect to %s" % server_url) _connection_in_progress = true _websocket_peer = WebSocketPeer.new() var err = _websocket_peer.connect_to_url(server_url) if err != OK: push_error("Failed to initiate connection: Error %d" % err) _connection_in_progress = false _schedule_reconnect() return # 连接已发起，等待poll()更新状态 func _attempt_reconnect(): if auto_reconnect and not _connection_in_progress: print("Attempting to reconnect...") connect_to_server()

这段代码引入了几个重要概念：

1. 可配置参数: 服务器地址、是否自动重连、重连延迟都通过@export暴露，便于调试。
2. 连接状态标志 (_connection_in_progress): 防止在连接过程中重复发起连接请求。
3. 自动重连: 网络不稳定是常态。通过一个Timer节点，在连接失败或断开后，延迟一段时间自动尝试重连，能极大提升用户体验和系统健壮性。

4.2 核心轮询与消息处理循环

客户端的核心同样在_process函数中，其结构与服务器端类似，但更简单，因为通常只管理一个连接。

func _process(delta): if not _websocket_peer: return # 关键：必须定期轮询 _websocket_peer.poll() var state = _websocket_peer.get_ready_state() match state: WebSocketPeer.STATE_CONNECTING: # 连接中，可以显示加载动画 pass WebSocketPeer.STATE_OPEN: _connection_in_progress = false # 连接成功，重置标志 _handle_received_messages() WebSocketPeer.STATE_CLOSING: # 正在关闭，继续轮询 pass WebSocketPeer.STATE_CLOSED: _handle_connection_closed() func _handle_received_messages(): while _websocket_peer.get_available_packet_count() > 0: var packet = _websocket_peer.get_packet() if _websocket_peer.was_string_packet(): var message = packet.get_string_from_utf8() print("Received from server: %s" % message) # 这里可以触发自定义信号，将消息传递给游戏逻辑 # emit_signal("message_received", message) else: print("Received binary data from server: %d bytes" % packet.size()) # 处理二进制数据，例如反序列化游戏状态 # var game_state = bytes2var(packet) func _handle_connection_closed(): _connection_in_progress = false var code = _websocket_peer.get_close_code() var reason = _websocket_peer.get_close_reason() print("Connection closed. Code: %d, Reason: %s" % [code, reason]) _websocket_peer = null # 释放引用 if auto_reconnect: _schedule_reconnect() func _schedule_reconnect(): if _reconnect_timer and not _reconnect_timer.is_stopped(): _reconnect_timer.stop() _reconnect_timer.start(reconnect_delay_sec)

实操心得：错误处理与状态分离在实际项目中，我强烈建议将网络状态（连接中、已连接、已断开）与UI或游戏逻辑状态分离。例如，可以定义一个枚举enum ConnectionState { DISCONNECTED, CONNECTING, CONNECTED, ERROR }，并在状态变化时发出不同的信号（如connection_established,connection_lost,message_received）。这样，你的游戏界面（显示“连接中...”提示）和逻辑层（处理收到的游戏指令）只需要监听这些信号，而不需要直接访问WebSocketPeer对象，代码耦合度更低，更易于测试和维护。

4.3 发送数据与用户交互

最后，我们需要提供向服务器发送数据的方法。这可以由UI按钮触发，或由游戏逻辑调用。

# 在客户端脚本中添加发送函数 func send_text_message(text: String): if _websocket_peer and _websocket_peer.get_ready_state() == WebSocketPeer.STATE_OPEN: var err = _websocket_peer.send_text(text) if err != OK: push_error("Failed to send text message: %s" % text) # 发送失败可能意味着底层连接已出现问题，可以尝试触发重连检查 else: print("Cannot send message, WebSocket is not open.") func send_binary_data(data: PackedByteArray): if _websocket_peer and _websocket_peer.get_ready_state() == WebSocketPeer.STATE_OPEN: var err = _websocket_peer.send(data) if err != OK: push_error("Failed to send binary data.") else: print("Cannot send binary data, WebSocket is not open.") # 示例：在UI中连接一个按钮来发送消息 func _on_send_button_pressed(): var input_text = $LineEdit.text if input_text.strip_edges() != "": send_text_message(input_text) $LineEdit.text = "" # 清空输入框

现在，运行你的客户端场景，确保服务器也在运行。在客户端的UI中输入文字并点击发送，你应该能在客户端控制台看到服务器返回的“Echo”消息，同时在服务器控制台看到相应的接收日志。

5. 进阶应用：与Godot高阶多人游戏网络集成

Godot的高层多人游戏API（MultiplayerAPI、MultiplayerSpawner、MultiplayerSynchronizer）为状态同步和远程过程调用（RPC）提供了强大的抽象。WebSocket可以作为这些高层API的底层传输层。

5.1 配置WebSocket为MultiplayerPeer

Godot的MultiplayerAPI需要一个实现了MultiplayerPeer接口的对象作为网络传输层。WebSocketPeer可以通过WebSocketMultiplayerPeer这个适配器来满足这个要求。

服务器端配置示例：

# 在服务器脚本中 var multiplayer_peer = WebSocketMultiplayerPeer.new() func start_multiplayer_server(port: int): # 创建TCP服务器并监听 var tcp_server = TCPServer.new() tcp_server.listen(port) # 将TCP服务器传递给WebSocketMultiplayerPeer，它会处理连接的升级和Peer管理 multiplayer_peer.create_server(port) # 内部其实做了类似我们之前手写的工作 # 或者，如果你已经有一个TCPServer，可以这样： # multiplayer_peer.accept_stream(tcp_server.take_connection()) # 但通常直接使用create_server更简单。 get_tree().get_multiplayer().multiplayer_peer = multiplayer_peer print("Multiplayer server started on port %d" % port)

客户端配置示例：

# 在客户端脚本中 var multiplayer_peer = WebSocketMultiplayerPeer.new() func connect_to_multiplayer_server(url: String): var err = multiplayer_peer.create_client(url) if err == OK: get_tree().get_multiplayer().multiplayer_peer = multiplayer_peer print("Connected to multiplayer server.") else: push_error("Failed to connect to server: %d" % err)

一旦将multiplayer_peer设置给SceneTree的multiplayer对象，Godot的高层网络系统就开始工作了。你可以使用@rpc注解来标记需要远程调用的函数，使用MultiplayerSpawner来自动同步节点的生成与销毁。

5.2 使用RPC进行通信

假设我们有一个简单的玩家节点，我们想同步其位置。

# player.gd extends CharacterBody2D @export var player_name: String = "Player" var _last_sync_pos: Vector2 func _ready(): # 只有当前控制的玩家才处理本地输入 if is_multiplayer_authority(): # 设置该玩家节点为网络主控权（通常由服务器分配或客户端对自己的角色） pass func _physics_process(delta): if is_multiplayer_authority(): # 本地玩家：处理输入并移动 var input_vector = Input.get_vector("move_left", "move_right", "move_up", "move_down") velocity = input_vector * 200 move_and_slide() # 定期（或当位置变化较大时）向网络同步位置 if position.distance_to(_last_sync_pos) > 5.0: rpc("update_position", position) _last_sync_pos = position @rpc("any_peer", "call_local", "unreliable") func update_position(new_pos: Vector2): position = new_pos # 这里可以添加插值平滑移动，避免卡顿

• @rpc注解: 定义了函数的调用规则。
  • "any_peer": 任何网络对等点（客户端或服务器）都可以调用这个函数。
  • "call_local": 调用也会在本地执行。如果不加，只有远程端会执行。
  • "unreliable": 使用不可靠传输（UDP-like），速度快，但可能丢包。对于频繁更新的位置信息，这通常是可接受的。对于关键指令（如“玩家死亡”），应使用"reliable"。
• is_multiplayer_authority(): 检查当前实例是否对该节点拥有网络权威。通常，服务器对所有节点拥有权威，而客户端只对自己的玩家角色拥有权威。这用于确定谁有资格执行某些逻辑（如移动计算）和发起RPC调用。

5.3 处理玩家加入与离开

使用MultiplayerSpawner可以大大简化玩家角色实例的同步生成。

1. 在服务器上，创建一个“玩家预制体”场景（如player_scene.tscn）。
2. 在服务器场景中，添加一个MultiplayerSpawner节点。
3. 将player_scene.tscn赋值给MultiplayerSpawner的Spawn Path。
4. 当新客户端连接时，服务器端调用multiplayer_spawner.spawn()，并传入一个可选的配置字典（如玩家名称、初始位置）。这个调用会自动在所有客户端（包括服务器）上实例化该预制体。
5. 当客户端断开时，对应的玩家节点会自动通过MultiplayerSpawner被反实例化（销毁）。

这种方式比手动通过RPC发送创建/销毁指令并管理节点ID要可靠和简洁得多。

6. 实战问题排查与性能优化

即使代码逻辑正确，在网络环境中也会遇到各种问题。下面是一些常见陷阱和解决方案。

6.1 常见连接与通信问题

6.2 心跳机制与连接健康检查

在长连接中，网络中间设备（如NAT路由器、防火墙）可能会因为连接长时间空闲而将其断开。为了保持连接活跃，并快速检测断线，需要实现心跳机制。

服务器端心跳示例：

# 在服务器脚本中为每个peer添加一个计时器 var _peer_heartbeat_timers: Dictionary = {} # peer_id -> last_heartbeat_time func _accept_new_connections(): # ... 接受连接后 ... _connected_peers[peer_id] = ws_peer _peer_heartbeat_timers[peer_id] = Time.get_ticks_msec() # 记录连接时间 # 发送欢迎消息，其中可包含服务器时间戳，用于计算延迟 ws_peer.send_text(JSON.stringify({"type": "welcome", "time": Time.get_ticks_msec()})) func _process(delta): # ... 原有逻辑 ... _check_heartbeats() # 检查心跳 func _check_heartbeats(): var current_time = Time.get_ticks_msec() var timeout_ms = 30000 # 30秒无通信视为超时 for peer_id in _peer_heartbeat_timers.keys(): if current_time - _peer_heartbeat_timers[peer_id] > timeout_ms: print("Peer %d heartbeat timeout, closing connection." % peer_id) var peer = _connected_peers.get(peer_id) if peer: peer.close(1000, "Heartbeat timeout") # 会在下次_poll_existing_connections中清理 func _handle_open_peer(peer_id: int, peer: WebSocketPeer): while peer.get_available_packet_count() > 0: var packet = peer.get_packet() if peer.was_string_packet(): var msg_text = packet.get_string_from_utf8() var msg = JSON.parse_string(msg_text) if msg and msg.get("type") == "heartbeat": # 收到客户端心跳，更新时间戳 _peer_heartbeat_timers[peer_id] = Time.get_ticks_msec() # 可选：回复一个pong，带服务器时间用于计算延迟 var pong = JSON.stringify({"type": "pong", "server_time": Time.get_ticks_msec()}) peer.send_text(pong) else: # ... 处理其他业务消息 ... pass

客户端心跳示例：

# 在客户端脚本中 var _heartbeat_timer: Timer var _last_heartbeat_sent_time: int = 0 var _latency: float = 0.0 func _ready(): # ... 其他初始化 ... _heartbeat_timer = Timer.new() _heartbeat_timer.wait_time = 5.0 # 每5秒发送一次心跳 _heartbeat_timer.timeout.connect(_send_heartbeat) add_child(_heartbeat_timer) func _on_connection_opened(): # 连接成功时启动心跳计时器 _heartbeat_timer.start() _last_heartbeat_sent_time = Time.get_ticks_msec() func _send_heartbeat(): if _websocket_peer and _websocket_peer.get_ready_state() == WebSocketPeer.STATE_OPEN: var heartbeat_msg = JSON.stringify({"type": "heartbeat", "client_time": Time.get_ticks_msec()}) _websocket_peer.send_text(heartbeat_msg) _last_heartbeat_sent_time = Time.get_ticks_msec() func _handle_received_messages(): while _websocket_peer.get_available_packet_count() > 0: var packet = _websocket_peer.get_packet() if _websocket_peer.was_string_packet(): var msg_text = packet.get_string_from_utf8() var msg = JSON.parse_string(msg_text) if msg and msg.get("type") == "pong": var now = Time.get_ticks_msec() var server_time = msg.get("server_time", 0) # 简单计算单向延迟 (RTT/2) _latency = (now - _last_heartbeat_sent_time) / 2.0 # 也可以计算时钟偏移等更复杂的信息 print("Heartbeat acknowledged. Latency: %.2f ms" % _latency)

心跳机制不仅保活，还能用于测量网络延迟，这对于需要延迟补偿的实时游戏非常有用。

6.3 数据序列化与协议设计

对于复杂的游戏状态，直接发送字符串可能效率低下。Godot提供了var2bytes和bytes2var函数，可以将大多数Godot数据类型（Variant）序列化为二进制PackedByteArray，反之亦然。

# 发送复杂游戏状态 var game_state = { "players": { 1: {"pos": Vector2(100, 200), "health": 85}, 2: {"pos": Vector2(300, 150), "health": 100} }, "game_time": 125.67 } var binary_data = var2bytes(game_state, true) # 第二个参数`full_objects`设为true以包含对象 _websocket_peer.send(binary_data) # 接收并解析 var packet = peer.get_packet() if not peer.was_string_packet(): var received_state = bytes2var(packet, true) # 处理 received_state["players"] 等...

协议设计建议：

1. 定义消息类型: 每条消息应该有一个类型字段，方便路由和处理。例如：{"t": "move", "x": 100, "y": 200}或{"t": "chat", "user": "Alice", "msg": "Hello"}。
2. 使用JSON还是二进制?: 对于调试和小型消息，JSON非常方便。对于高频、大型的状态同步，二进制序列化（var2bytes）或自定义的紧凑二进制协议（如FlatBuffers, Protocol Buffers的GDExtension）性能更好。
3. 数据压缩: 对于文本协议（如JSON），在发送前使用GZIP压缩（Compression.compress()）可以显著减少带宽。但要注意压缩/解压的CPU开销。
4. 差分更新: 不要每次都发送完整的游戏状态。只发送自上次更新以来发生变化的部分。例如，只发送位置发生变化的玩家ID和新位置。

将WebSocket集成到Godot项目中，就像是给你的游戏装上了“实时神经”。从简单的回声测试到复杂的多人游戏同步，这套技术栈提供了坚实的基础。关键在于理解连接的生命周期、坚持非阻塞的轮询模式、妥善处理错误和重连，并设计清晰的应用层通信协议。