1. 项目概述与核心价值如果你正在用Godot开发一款需要在线功能的游戏比如多人对战、排行榜、好友系统或者实时聊天那么“自己搭服务器”这个念头大概率会让你头疼不已。从零构建一套稳定、可扩展的后端服务涉及网络通信、数据存储、用户认证、实时同步等一大堆复杂问题这远非游戏开发的核心。这时一个专为游戏设计的后端服务BaaS就显得至关重要。Nakama正是这样一个强大的开源游戏服务器后端而Nakama Godot SDK则是连接你的Godot游戏与这个强大后端的桥梁。简单来说这个“Nakama Godot 开源项目教程”的核心就是教你如何将Godot游戏引擎与Nakama服务器无缝集成快速为你的游戏注入“灵魂”——在线社交与实时互动能力。它解决的不仅仅是“联网”这个技术问题更是帮你绕开了后端开发中无数的“坑”让你能专注于游戏玩法本身。无论是想做一款像《Among Us》那样的社交推理游戏还是带有公会、排行榜的MMO Lite或是简单的多人竞技游戏Nakama提供了一套开箱即用的解决方案。本教程将基于官方文档和最佳实践带你从零开始深入理解如何在实际的Godot项目中运用Nakama。我们会从一个简单的“Sagi-shi”一个受《Among Us》启发的概念项目示例出发但重点在于剖析每个功能模块的实现原理、代码细节以及我踩过的那些坑确保你能真正掌握并将其应用到自己的项目中。2. 环境准备与SDK集成在开始写代码之前我们需要把“舞台”搭好。这包括运行起Nakama服务器以及在Godot项目中正确引入SDK。2.1 启动Nakama服务器Nakama服务器是后端核心它负责处理所有逻辑。最快速的启动方式是使用Docker。确保你的系统已经安装了Docker和Docker Compose。首先创建一个docker-compose.yml文件内容如下version: 3 services: postgres: image: postgres:15-alpine environment: POSTGRES_DB: nakama POSTGRES_PASSWORD: localhost volumes: - postgres_data:/var/lib/postgresql/data healthcheck: test: [CMD-SHELL, pg_isready -U postgres] interval: 10s timeout: 5s retries: 5 nakama: image: heroiclabs/nakama:3.20.0 depends_on: postgres: condition: service_healthy command: - --name - nakama-node-1 - --database.address - postgres:localhost - --logger.level - DEBUG links: - postgres:db ports: - 7350:7350 # 客户端通信端口 - 7351:7351 # 服务器管理/GRPC端口 - 9100:9100 # 指标监控端口可选 volumes: - ./data:/data - ./modules:/modules # 用于存放自定义服务器逻辑如RPC restart: unless-stopped volumes: postgres_data:这个配置定义了两个服务PostgreSQL数据库和Nakama服务器。Nakama默认使用127.0.0.1:7350进行客户端通信。在项目根目录下运行docker-compose up看到日志输出没有报错就说明服务器启动成功了。注意生产环境部署需要考虑更多因素如配置TLS证书、设置防火墙规则、使用更复杂的数据库集群等。但对于开发和测试这个配置足够了。2.2 在Godot中集成Nakama SDKNakama为Godot提供了官方的GDScript SDK。集成方式主要有两种方法一通过AssetLib安装推荐给Godot 4在Godot编辑器中打开“AssetLib”面板。搜索“Nakama”。找到“Nakama Godot Client”插件点击“Download”然后“Install”。安装完成后在“项目” - “项目设置” - “插件”中启用它。方法二手动下载集成适用于Godot 3.x或自定义需求从Heroic Labs的GitHub仓库heroiclabs/nakama-godot下载最新版本的SDK。将下载的addons/com.heroiclabs.nakama文件夹复制到你的Godot项目根目录下。同样在项目设置的“插件”中启用它。启用插件后你会在编辑器的“节点”选项卡中看到新增的“Nakama”节点类型。不过我们更倾向于在代码中动态创建和管理客户端这样控制更灵活。关键一步配置自动加载Autoload为了让Nakama客户端在整个游戏生命周期内都能方便地访问我们通常将其设置为自动加载的单例。这避免了在不同场景间传递客户端实例的麻烦。创建一个名为NakamaClient.gd的脚本。在“项目” - “项目设置” - “自动加载”中添加这个脚本并将其路径设置为NakamaClient这是它在全局作用域中的名字。在NakamaClient.gd中我们进行初始化extends Node var client: NakamaClient var socket: NakamaSocket var session: NakamaSession func _ready(): # 创建客户端实例连接到本地运行的Nakama服务器 # 参数依次为服务器密钥默认defaultkey、服务器地址、端口、是否使用SSLhttp/https client Nakama.create_client(defaultkey, 127.0.0.1, 7350, http) # 可选设置请求超时时间秒 client.timeout 10 print(Nakama 客户端初始化完成。)现在你可以在任何脚本中通过NakamaClient.client来访问这个客户端实例了。3. 用户系统从认证到个人资料任何在线服务的第一步都是识别用户。Nakama提供了多种灵活的认证方式。3.1 设备认证最简捷的入门方式对于快速原型或不需要复杂登录流程的游戏设备认证是最简单的。它使用设备的唯一标识符来创建或恢复用户会话。# 在某个场景的脚本中比如 LoginScene.gd func _on_DeviceLoginButton_pressed(): # 获取设备的唯一ID注意不同平台实现不同此方法在导出后可能更可靠 var device_id OS.get_unique_id() if device_id.empty(): # 如果获取失败可以生成一个UUID或使用其他标识 device_id device_ str(randi() % 100000) # 异步调用设备认证 var result yield(NakamaClient.client.authenticate_device_async(device_id), completed) if result.is_exception(): print(设备认证失败: , result.get_exception().message) # 这里可以显示错误提示给玩家 return # 认证成功保存会话 NakamaClient.session result print(登录成功用户ID: , NakamaClient.session.user_id) # 跳转到主菜单或游戏大厅场景 get_tree().change_scene(res://MainMenu.tscn)实操心得OS.get_unique_id()在编辑器内运行和某些平台上可能返回空字符串。为了更好的兼容性我通常会结合设备ID和本地存储首次启动时如果设备ID为空则生成一个随机UUID并保存到本地后续启动都使用这个保存的ID。这样能保证同一设备上的用户会话是连续的。3.2 会话管理与恢复用户认证后获得的NakamaSession对象至关重要它包含了访问令牌auth_token和刷新令牌refresh_token。我们需要妥善保存它们以实现“记住登录”功能。# 在NakamaClient.gd中扩展功能 func save_session(): if session and not session.expired: # 使用Godot的ConfigFile或自定义文件保存token var config ConfigFile.new() config.set_value(nakama, auth_token, session.auth_token) config.set_value(nakama, refresh_token, session.refresh_token) config.save(user://nakama_session.cfg) func load_session(): var config ConfigFile.new() var err config.load(user://nakama_session.cfg) if err OK: var auth_token config.get_value(nakama, auth_token) var refresh_token config.get_value(nakama, refresh_token) if auth_token: # 尝试恢复会话 var restored_session NakamaClient.restore_session(auth_token, refresh_token) if not restored_session.expired: NakamaClient.session restored_session print(会话恢复成功。) return true return false # 在游戏启动时调用 func attempt_session_restore(): if load_session(): # 检查会话是否即将过期尝试刷新 if session.is_expired() or session.expire_time - OS.get_unix_time() 3600: # 1小时内过期 var new_session yield(client.session_refresh_async(session), completed) if not new_session.is_exception(): session new_session save_session() else: # 刷新失败需要重新认证 print(会话刷新失败需要重新登录。) session null return true return false3.3 获取与更新用户账户成功认证后你可以获取和更新玩家的公开信息。# 获取当前登录用户的完整账户信息 func fetch_my_account(): if not NakamaClient.session: return var account_result yield(NakamaClient.client.get_account_async(NakamaClient.session), completed) if account_result.is_exception(): print(获取账户信息失败: , account_result.get_exception().message) return null var account account_result print(用户名: , account.user.username) print(头像URL: , account.user.avatar_url) print(创建时间: , account.user.create_time) # 用户元数据自定义信息存储在 account.user.metadata 中是JSON字符串 return account # 更新用户资料如用户名、头像等 func update_my_profile(new_username: String, new_avatar_url: String ): if not NakamaClient.session: return false # 注意username更新后旧的将无法再使用。 var update_result yield(NakamaClient.client.update_account_async( NakamaClient.session, new_username, , # display_name 可选项 new_avatar_url, , # lang_tag , # location # timezone ), completed) if update_result.is_exception(): print(更新资料失败: , update_result.get_exception().message) return false print(资料更新成功) return true注意事项update_account_async会更新所有传入的参数。如果你只想更新头像而保持用户名不变必须从get_account_async获取当前的用户名并作为参数传入否则用户名会被置空。4. 实时功能核心Socket连接与匹配Nakama的实时功能如聊天、实时匹配、状态同步都依赖于Socket连接。这是游戏“活”起来的关键。4.1 建立Socket连接在用户认证后我们需要建立Socket连接来接收和发送实时数据。# 在NakamaClient.gd中 func connect_socket(): if not session: print(无法连接Socket无有效会话。) return false # 从已有的client创建socket socket Nakama.create_socket_from(client) # 连接Socket var connect_result yield(socket.connect_async(session), completed) if connect_result.is_exception(): print(Socket连接失败: , connect_result.get_exception().message) socket null return false print(Socket连接成功) # 开始监听Socket事件 _setup_socket_listeners() return true func _setup_socket_listeners(): # 监听匹配相关事件 socket.connect(received_matchmaker_matched, self, _on_matchmaker_matched) socket.connect(received_match_state, self, _on_match_state) socket.connect(received_match_presence, self, _on_match_presence) # 监听状态更新好友在线状态 socket.connect(received_status_presence, self, _on_status_presence) # 监听聊天消息 socket.connect(received_channel_message, self, _on_channel_message) # 监听通知 socket.connect(received_notification, self, _on_notification) print(Socket事件监听器已设置。)4.2 创建与加入实时匹配匹配Match是Nakama实时多人游戏的核心。你可以创建房间或者通过匹配器Matchmaker加入他人的房间。创建匹配创建房间func create_match(): if not socket: print(请先连接Socket。) return null var match_result yield(socket.create_match_async(), completed) if match_result.is_exception(): print(创建匹配失败: , match_result.get_exception().message) return null var match_obj match_result print(匹配创建成功ID: , match_obj.match_id) # 这里可以通知好友或通过其他方式分享 match_obj.match_id return match_obj使用匹配器寻找对手匹配器允许你根据条件如技能值、自定义标签自动寻找对手而不是直接输入房间ID。func find_match_with_matchmaker(): if not socket: return null var min_players 2 var max_players 10 # 查询字符串可以用于筛选。例如“skill:100 mode:deathmatch” var query # 字符串属性用于精确匹配标签 var string_properties {} # 数值属性用于范围匹配 var numeric_properties {} print(正在寻找匹配...) var ticket_result yield(socket.add_matchmaker_async(query, min_players, max_players, string_properties, numeric_properties), completed) if ticket_result.is_exception(): print(加入匹配队列失败: , ticket_result.get_exception().message) return null print(已加入匹配队列等待对手...) # 等待 _on_matchmaker_matched 信号被触发处理匹配成功事件当匹配器找到足够玩家时会触发信号我们需要在这个回调中加入匹配。func _on_matchmaker_matched(p_matched): print(匹配成功找到 %d 名玩家。 % p_matched.users.size()) # p_matched 包含匹配到的玩家信息和生成的 match_id var join_result yield(socket.join_match_async(p_matched.match_id), completed) if join_result.is_exception(): print(加入匹配失败: , join_result.get_exception().message) return var match_obj join_result print(已加入匹配: , match_obj.match_id) # 在这里你可以初始化游戏场景并为 match_obj.presences 中的每个玩家生成游戏对象 # 例如GameManager.start_online_match(match_obj)4.3 实时状态同步加入匹配后游戏的核心就变成了状态同步。Nakama通过send_match_state_async和received_match_state信号来处理。发送游戏状态假设我们有一个简单的玩家位置状态。# 定义操作码用于区分不同类型的消息 enum OpCode { PLAYER_POSITION 1, PLAYER_ACTION 2, GAME_EVENT 3 } func send_player_position(match_id: String, position: Vector3): if not socket: return # 将状态数据序列化为JSON或二进制 var state_data { x: position.x, y: position.y, z: position.z, t: OS.get_ticks_msec() # 可选添加时间戳用于插值 } var op_code OpCode.PLAYER_POSITION # 发送状态到服务器服务器会广播给匹配内的其他玩家 var send_result yield(socket.send_match_state_async(match_id, op_code, JSON.print(state_data)), completed) if send_result.is_exception(): print(发送状态失败: , send_result.get_exception().message)接收并处理游戏状态func _on_match_state(p_state): # p_state 包含op_code, data, presence (发送者信息) var sender_id p_state.user_presence.session_id var op_code p_state.op_code var raw_data p_state.data # 这是一个 PoolByteArray match op_code: OpCode.PLAYER_POSITION: # 反序列化数据 var json JSON.parse(raw_data.get_string_from_utf8()) if json.error OK: var pos_data json.result var new_position Vector3(pos_data.x, pos_data.y, pos_data.z) # 更新对应玩家的位置 # 例如GameManager.update_player_position(sender_id, new_position, pos_data.t) OpCode.PLAYER_ACTION: # 处理玩家动作如攻击、使用技能 pass OpCode.GAME_EVENT: # 处理游戏事件如游戏开始、结束、物品生成 pass _: print(收到未知操作码: , op_code)核心技巧状态同步优化频率与冗余不要每帧发送所有数据。对于位置同步可以设定一个固定频率如每秒10-20次或者只在位置变化超过阈值时发送。数据压缩发送前考虑对数据进行压缩。对于简单的Vector3直接发三个float可能比JSON字符串更高效。Nakama的data字段是PoolByteArray你可以使用var2bytes和bytes2var来序列化Godot的Variant类型如数组、字典这通常比JSON更紧凑。客户端预测与服务器调和对于快节奏动作游戏纯权威服务器模式可能会有延迟感。常见的做法是客户端预测本地输入服务器定期发送权威状态进行校正。这需要更复杂的逻辑但Nakama的实时通道为这种通信提供了基础。操作码设计清晰的操作码枚举能让你的网络代码更易维护。将不同游戏系统移动、战斗、聊天的消息用不同操作码区分。5. 社交与数据持久化一个完整的在线游戏离不开社交功能和玩家数据的持久化。5.1 好友系统Nakama的好友系统支持添加、列出、接受/拒绝请求。# 通过用户名添加好友 func add_friend_by_username(username: String): if not session: return false var result yield(client.add_friends_async(session, [], [username]), completed) if result.is_exception(): print(添加好友请求发送失败: , result.get_exception().message) return false print(好友请求已发送给: , username) return true # 列出所有好友状态0已是好友 func list_friends(): if not session: return [] var result yield(client.list_friends_async(session, 0, 100), completed) # 状态0限制100个 if result.is_exception(): print(获取好友列表失败: , result.get_exception().message) return [] var friends [] for f in result.friends: var friend f as NakamaAPI.ApiFriend friends.append({ id: friend.user.id, username: friend.user.username, online: friend.user.online }) return friends # 接受所有待处理的好友请求 func accept_all_friend_requests(): if not session: return # 先列出状态为2收到的请求的好友 var requests_result yield(client.list_friends_async(session, 2, 100), completed) if requests_result.is_exception(): return for f in requests_result.friends: var friend f as NakamaAPI.ApiFriend # 接受请求通过再次添加对方为好友来实现 yield(client.add_friends_async(session, [friend.user.id], []), completed)5.2 存储玩家数据Nakama的存储对象Storage Objects功能强大可以安全地存储每个玩家的游戏数据如装备、进度、设置。写入玩家数据假设我们要存储玩家解锁的帽子。func save_unlocked_hats(hat_list: Array): if not session: return false # 定义存储对象ID集合(collection)“player_items” 键(key)“unlocked_hats” 所有者(owner)用户自己 var object_id NakamaStorageObjectId.new() object_id.collection player_items object_id.key unlocked_hats object_id.user_id session.user_id # 准备要写入的数据 var value { hats: hat_list, # 例如[cowboy, wizard, baseball] last_updated: OS.get_unix_time() } # 权限1仅自己可读2公开可读。写权限通常只留给自己和服务器。 var permission_read 1 var permission_write 1 var write_object NakamaWriteStorageObject.new() write_object.collection object_id.collection write_object.key object_id.key write_object.value JSON.print(value) # 必须序列化为字符串 write_object.permission_read permission_read write_object.permission_write permission_write # 如果需要条件写入防止覆盖可以设置 version从读取操作中获得 var write_result yield(client.write_storage_objects_async(session, [write_object]), completed) if write_result.is_exception(): print(保存数据失败: , write_result.get_exception().message) return false print(玩家数据保存成功) return true读取玩家数据func load_unlocked_hats(): if not session: return [] var object_id NakamaStorageObjectId.new() object_id.collection player_items object_id.key unlocked_hats object_id.user_id session.user_id var read_result yield(client.read_storage_objects_async(session, [object_id]), completed) if read_result.is_exception(): print(读取数据失败: , read_result.get_exception().message) return [] var objects read_result.objects if objects.size() 0: var data_str objects[0].value var json JSON.parse(data_str) if json.error OK: var data json.result return data.get(hats, []) return [] # 默认返回空列表重要提醒数据安全永远不要相信客户端传来的数据上述存储操作是从客户端发起的这意味着恶意玩家可能修改代码直接给自己写入顶级装备。为了解决这个问题服务器权威写入关键数据如任务进度、购买记录的写入应该在服务器端的RPC函数中完成。客户端只发起请求由服务器验证逻辑后写入。使用条件写入版本控制读取数据时会返回一个版本号version。写入时带上这个版本号只有版本匹配时才允许写入可以防止数据覆盖冲突。数据校验在服务器RPC中对客户端传来的数据进行严格校验确保其符合游戏规则。5.3 排行榜与锦标赛排行榜Leaderboards和锦标赛Tournaments是驱动玩家竞争的核心功能。向排行榜提交分数func submit_score_to_leaderboard(leaderboard_id: String, score: int, subscore: int 0): if not session: return false # 可选的元数据用于记录额外信息如通关关卡、使用角色等 var metadata { level: space_station_3, character: blue } var submit_result yield(client.write_leaderboard_record_async( session, leaderboard_id, score, subscore, JSON.print(metadata) ), completed) if submit_result.is_exception(): print(提交分数失败: , submit_result.get_exception().message) return false print(分数提交成功) return true获取排行榜列表func get_leaderboard_top(leaderboard_id: String, limit: int 20): if not session: return [] var result yield(client.list_leaderboard_records_async( session, leaderboard_id, null, # owner_ids null, # expiry limit, null # cursor ), completed) if result.is_exception(): return [] var records [] for record in result.records: records.append({ rank: record.rank, username: record.username, score: record.score, metadata: JSON.parse(record.metadata).result if record.metadata else {} }) return records # 获取玩家自己在排行榜周围的情况前10后10 func get_leaderboard_around_me(leaderboard_id: String, limit: int 20): if not session: return [] # 这里使用一个特殊的API传入自己的user_id来获取周围记录 var result yield(client.list_leaderboard_records_async( session, leaderboard_id, [session.user_id], # 围绕这个用户 null, limit, null ), completed) # ... 处理结果同上6. 常见问题与实战调试技巧在实际集成Nakama的过程中你一定会遇到各种问题。下面是我总结的一些常见坑点和解决方法。6.1 连接与认证问题问题连接服务器失败错误提示“无法解析主机”或“连接超时”。检查点1服务器地址和端口。确保Godot客户端中配置的IP和端口与运行的Nakama服务器一致。Docker运行在本地时通常是127.0.0.1:7350。检查点2防火墙/安全组。如果服务器在远程确保云服务商的安全组和服务器自身的防火墙如ufw开放了7350和7351端口。检查点3Docker网络。如果你在Docker容器内运行Nakama并从主机上的Godot连接确保使用宿主机的IP而不是localhost。问题设备认证失败OS.get_unique_id()返回空。解决方案实现一个后备方案。首次启动时生成一个随机UUID例如使用str(randi() % 1000000000)并加上时间戳将其保存到user://目录下的配置文件中。后续启动都读取这个文件中的ID。这保证了同一设备用户的稳定性。6.2 实时同步与性能问题问题游戏卡顿网络延迟感明显。优化1降低同步频率。不要每帧发送位置更新。对于非竞技类游戏每秒10-15次66-100ms间隔通常足够平滑。可以使用Timer节点来控制发送节奏。优化2状态压缩与差分。只发送变化的数据。例如如果玩家没有移动就不发送位置包。对于状态复杂的对象可以只发送变化的属性。优化3客户端插值。在_on_match_state中收到其他玩家的新位置时不要直接position new_position而是记录目标位置和时间在_process中平滑地插值过去。这能极大缓解网络抖动带来的卡顿。Godot特定技巧对于需要网络同步的节点可以考虑使用RemoteTransform节点来处理其他玩家的位置和旋转同步它能自动进行平滑插值。问题匹配成功后玩家加入游戏场景时出现对象重复或缺失。根本原因_on_match_presence信号处理不当。这个信号会在玩家加入或离开匹配时触发。你需要维护一个本地字典将presence.session_id映射到场景中的玩家节点。标准处理流程var players_in_match {} # key: session_id, value: PlayerNode func _on_match_presence(p_presence): # 处理新加入的玩家 for joined_presence in p_presence.joins: if not players_in_match.has(joined_presence.session_id): var new_player preload(res://Player.tscn).instance() new_player.name str(joined_presence.session_id) # 重要给节点唯一命名 new_player.set_network_master(1) # 如果是权威服务器其他玩家设为远程 $Players.add_child(new_player) players_in_match[joined_presence.session_id] new_player print(玩家加入: , joined_presence.username) # 处理离开的玩家 for left_presence in p_presence.leaves: if players_in_match.has(left_presence.session_id): var player_node players_in_match[left_presence.session_id] player_node.queue_free() players_in_match.erase(left_presence.session_id) print(玩家离开: , left_presence.username)6.3 数据存储与安全问题玩家通过修改客户端给自己添加了非法道具或无限金币。解决方案如前所述关键逻辑必须放在服务器端。使用Nakama的RPC远程过程调用功能。在Nakama服务器的Lua/Go/TypeScript模块中编写一个函数例如purchase_item。该函数验证玩家金币是否足够扣除金币然后在服务器端向存储对象写入新道具。Godot客户端调用这个RPC而不是直接写存储。# Godot客户端调用RPC var payload {item_id: sword_of_legend, cost: 100} var rpc_result yield(client.rpc_async(session, purchase_item, JSON.print(payload)), completed) if not rpc_result.is_exception(): print(购买成功)启用服务器验证在Nakama服务器的data/modules目录下放置你的自定义模块并在配置中启用它。这是保证游戏经济系统公平性的基石。问题读取存储数据时JSON解析出错。检查确保写入和读取时使用相同的序列化/反序列化方法。写入时用JSON.print(data)读取时用JSON.parse(json_string).result。始终检查JSON.parse的error属性。使用结构化的类为你的存储数据定义GDScript类并编写专门的序列化/反序列化方法这比直接操作原始字典更安全、更易维护。6.4 调试与日志启用Nakama服务器详细日志在docker-compose.yml的Nakama服务命令中添加--logger.level DEBUG可以在控制台看到所有进出的请求和内部处理信息对于排查问题非常有用。在Godot中打印详细的网络信息在关键的网络调用前后添加打印语句并打印出错误对象的完整信息。var result yield(socket.some_async_function(), completed) if result.is_exception(): var exception result.get_exception() print(错误详情 - 消息: %s, 代码: %s % [exception.message, exception.code]) # 有时exception.status_code和exception.grpc_status_code也很有用使用Wireshark或Godot的网络分析器对于复杂的协议问题使用网络抓包工具可以查看原始的网络包判断问题是出在客户端、网络还是服务器。将Nakama集成到Godot项目中一开始可能会觉得步骤繁多但一旦你理解了客户端-服务器-存储这个基本模型并成功运行起第一个多人匹配 demo后面的扩展就会变得顺理成章。记住从一个小功能开始比如简单的设备认证和“Hello World”聊天逐步添加排行榜、好友、匹配等模块每次只专注于一个功能的实现和测试。Nakama的官方文档和社区是宝贵的资源遇到问题时多去查阅和搜索。最重要的是动手去试代码跑起来的过程就是最好的学习。
)
