MCE Online 设置

MCE Online 以 Nakama 作为后端，为 Monster Capture Engine 增加了一个完整的 MMORPG 层。本指南带你完成服务器设置、客户端配置和连接测试。

适用于 Pro、Source 和 Studio 版本。

什么是 Nakama？

Nakama 是一个开源游戏服务器，提供：

用户认证（邮箱、设备、SSO）。
实时多人游戏（WebSocket）。
服务器权威的游戏逻辑（RPC）。
基于 ELO 评分的匹配。
排行榜、成就和实时活动。
云存档与存储。
聊天、好友、公会。

MCE Online 用 25 个面向怪物捕捉类型的专用服务包装了 Nakama。它们是 NakamaManager 的公共服务属性 —— 如果你想要所用版本的数量，请在那里自己数，而不要相信文档中的某个数字。

前提条件

已安装并正常运行的 MCE Core。
Docker Desktop（用于本地开发）或托管的 Nakama 实例。
已导入你项目的 MCE Online。

步骤 1：解压并启动 Nakama 服务器

本地开发（Docker）

Pro、Source 和 Studio 以 Assets/OpenMon/Online/Server/mce-nakama-server.zip 的形式包含 Nakama 服务器。通过 OpenMon Hub（Tools > MCE > OpenMon Hub）→ Online 选项卡 → Extract Server Bundle 从 Unity 中解压它。

OpenMon Hub 的 Online 选项卡�：连接模式、Nakama 设置向导、物种种子状态和 Docker 服务器控制

本指南中的所有内容都位于这一个选项卡上，大致按你需要它们的顺序排列：最上面是连接模式，其下是首次 Nakama 设置，然后是物种播种，最后是步骤 1 中使用的 Docker 控制。

然后启动解压出来的服务器文件夹：

cd path/to/OpenMon-Nakama-Server
docker compose up -d postgres nakama

这会启动：

服务	主机端口	环境变量
Nakama HTTP API	`7350`	`MCE_NAKAMA_PORT`
Nakama gRPC	`7349`	`MCE_NAKAMA_GRPC_PORT`
Nakama 管理控制台	`7351`	`MCE_NAKAMA_CONSOLE_PORT`
PostgreSQL	`5432`	`MCE_PG_PORT`

如果这些端口已被占用

它们是 Nakama 和 Postgres 自己的默认端口，这正是它们会冲突的原因：任何已经运行着 Postgres 或第二个 Nakama 的人都占用了它们。

这个故障是悄无声息的，而这正是值得了解的部分。Docker 不会带着清晰的消息停止 —— 容器停留在 Created 状态，没有任何东西解释原因。

每个端口都可以通过上表中的环境变量覆盖：

MCE_PG_PORT=5433 MCE_NAKAMA_PORT=7360 docker compose up -d postgres nakama

或者从编辑器中设置。UI Toolkit Hub —— Tools → MCE → OpenMon Hub (UI Toolkit)，是可选窗口，而不是默认打开的 IMGUI 窗口 —— 的 Online 选项卡中有一个端口选择器：

UI Toolkit Hub 的 Online 选项卡中的端口选择器

按下 Comprobar disponibilidad，每个端口都会通过实际绑定来检查。这个区别正是关键：端口在列表中可能看起来是空闲的，却仍然拒绝绑定，而绑定恰恰是 Docker 即将尝试的操作。

备注

端口选择器是该选项卡中迄今为止唯一迁移到 UI Toolkit 的部分。Online 选项卡的其余部分仍在旧版 Hub 中，窗口通过一个跳转到它的按钮来说明这一点。

compose 文件还定义了一个可选的 nakama-prodsim 服务，它不带 MCE_DEV_MODE 启动相同的模块，供开发门的 E2E 测试用来验证经济发放 RPC 在生产环境中会被拒绝。

在以下地址访问 Nakama 管理控制台：http://localhost:7351

默认管理员凭据：

用户名：admin
密码：password

生产环境

默认的 Docker 配置仅用于开发。对于生产环境，请使用托管的 Nakama 实例（Heroic Cloud，或配置了适当安全措施的自托管）。

托管（Heroic Cloud）

在 heroiclabs.com 创建账户。
创建一个新的 Nakama 项目。
从控制面板记下服务器 URL 和服务器密钥。

步骤 2：配置 Unity 客户端

OnlineConfig 资产

MCE Online 使用 OnlineConfig ScriptableObject 作为连接设置：

客户端从 Resources 文件夹（Assets/Resources/OnlineConfig.asset）加载名为 OnlineConfig 的资产。在 Hub 的 Online 选项卡中按 Select OnlineConfig 即可打开它。
如果它不存在，请创建：Assets > Create > MCE > Online > Configuration，命名为 OnlineConfig 并放在 Resources 文件夹中。

配置以下字段：

字段	说明	本地默认值
Server Host	Nakama 服务器主机名	`127.0.0.1`
Server Port	HTTP API 端口	`7350`（或你选择的 `MCE_NAKAMA_PORT`）
Server Key	API 密钥（来自 Nakama 控制台）	`defaultkey`
Use SSL	启用 HTTPS/WSS	`false`（本地）、`true`（生产）

OnlineConfig 还包含以下设置：

Enable Online 和 Allow Offline Fallback：游戏是否上线，以及无法连接服务器时是否可以回退到离线游戏。
Auto Reconnect 和 Max Reconnect Attempts：连接断开时的重连。
Connection Timeout：一次连接尝试可以花多长时间（秒）。
世界同步：传输模式、兴趣区域半径（AOIRadius）、最大可见玩家数、位置同步速率和频道。
功能开关：Housing、Spectator、Mod 支持、服务器权威、突袭战斗；单点登录提供商（Discord、Google、Apple）；以及好友、公会成员、GTL 挂单和聊天历史等上限。

为在线界面提供 emoji 字体

在线界面使用 emoji 作为图标语言 —— 各界面上大约有八十种不同的字形。 TextMesh Pro 的默认字体里一个都没有，会把每一个都渲染成 ▯。

打开 Hub → Build 选项卡 → Setup Emoji Fallback (Online UI)。 它会把随附的 Noto Emoji 字体（SIL OFL 1.1，位于 Assets/OpenMon/Online/UI/Fonts/）接入 TMP 的回退列表。

为什么这是一个步骤，而不是已经替你做好的事

字体及其 TMP 资产随附在 Assets/OpenMon/Online 中，因此会随包一起到达。接线则不会：它位于 Assets/TextMesh Pro 下的 TMP Settings 中，而它不属于任何版本的载荷。所以资产到了，而指向它的列表没有到 —— 一个按钮就能填补这个缺口。

同一个字体资产是动态的：它按需从 .ttf 光栅化字形，所以没有任何预烘焙内容，添加它也不需要构建图集。这也是默认字体不能直接扩展的原因 —— 它的图集是静态的，无法增长。

启用 MCE_ONLINE 宏定义

MCE Online 需要 MCE_ONLINE 脚本宏定义符号：

前往 Edit > Project Settings > Player > Other Settings > Scripting Define Symbols。
把 MCE_ONLINE 添加到列表中。
点击 Apply。

这会启用引擎中所有与在线相关的代码路径。

步骤 3：部署服务器端代码

MCE Online 在解压出的服务器包中附带两种运行时：用于 RPC、战斗、经济和社交的 TypeScript 模块，以及运行世界对局的 Go 插件。

包的布局（有所删节，文件夹里的文件比所列更多）：

OpenMon-Nakama-Server/
  README.md                  # Local setup + test commands
  docker-compose.yml         # Local Nakama + Postgres (+ optional prod-sim node)
  nakama/
    src/
      main.ts                # Entry point, RPC registration
      battle/
        pvp-engine.ts        # Server-authoritative PvP
        raid-engine.ts       # Battle Tower / Raids
      economy/
        gtl.ts               # Global Trade Link (GTL)
        gtl-engine.ts        # GTL matching engine
        gts.ts               # Global Trade Station (GTS)
      data/
        species.ts           # Species/stats lookup tables
        roster.ts            # Roster helpers
        shop.ts              # Dev-gated shop catalog
      social/
        trade.ts             # Direct player trading
      world/
        secretbase.ts        # Secret Base multiplayer (F3-A snapshot RPCs)
        playergym.ts         # Player Gym challenge snapshot (F2b RPCs)
        housing.ts           # Legacy furniture placement validation
        presence.ts          # Presence + AOI + anti-teleport movement guard
    go/                      # The overworld match, in Go
      main.go                # Nakama match adapter
      mundo.go               # Tick loop: presences, AOI, batch assembly
      aoi.go                 # Area of interest: grid + partial selection
      formato.go             # Compact batch format
      construir.mjs          # Rebuilds the plugin for another Nakama version
    tools/                   # Seed scripts: seed-species.js, seed-shop.js, ...
    data/
      modules/
        mundo.so             # The plugin, PREBUILT for Nakama 3.22.0 / linux-amd64
    tsconfig.json
    package.json
    jest.config.js           # Unit tests
    jest.e2e.config.js       # E2E tests (needs a running Nakama)
    CONTRACT.md              # RPC contract reference

世界需要 Go 插件

world_map 不是 TypeScript。它以预编译的 nakama/data/modules/mundo.so 形式随附，Nakama 会在启动时加载它，因此在此包所针对的 Nakama 3.22.0 / linux-amd64 上无需额外操作。

Go 插件必须针对加载它的 Nakama 的确切版本编译。在任何其他版本上，预编译的插件都不会加载，world_join 会失败。没有 TypeScript 回退，这是有意为之：TypeScript 版的世界每个 tick 要 450 ms，而 Go 版仅 12 ms，前者有 253,606 个位置因队列已满而被丢弃，后者为零。一个慢 37 倍的静默回退比一次响亮的失败更糟糕 —— 你会看到一个运行不佳的游戏，却看不到明显的原因。

用 node go/construir.mjs（需要 Docker）为你的版本重新构建它。Go 源码正是为此随包一起提供的。

备注

源码仓库把这些文件存放在 Assets/OpenMon/Online/Server~/ 下，以便 Unity 忽略它们。商业包将其作为 mce-nakama-server.zip 发布；在运行 Docker 或 npm 命令之前，请先解压该 zip。

部署到 Nakama

构建服务器模块：

cd path/to/OpenMon-Nakama-Server/nakama
npm install
npm run build

构建会编译为 nakama/build/index.js（参见 tsconfig.json 中的 outFile）。
重启 Nakama 以加载模块。

随附的 docker-compose.yml 已经挂载了构建输出 —— 无需手动复制：

volumes:
  - ./nakama/data:/nakama/data
  - ./nakama/build:/nakama/data/modules/build

步骤 4：NakamaManager

NakamaManager 是管理连接的单例：

通过 [RuntimeInitializeOnLoadMethod] 在运行时自动创建。
拥有 25 个服务类（Auth、World、Battle、Social、Economy、Housing、Persistence、LiveOps、Modding）。
以指数退避处理重连。
通过主线程队列路由所有 Nakama 通信（线程安全）。

你不需要手动创建或配置 NakamaManager。它会读取 OnlineConfig 并自行初始化。

连接状态

Disconnected → Connecting → Connected
                    ↓              ↓
                 Offline     Disconnected
                    ↑              ↑
              (reconnect)   (connection lost)

状态	说明
Disconnected	没有连接，也没有在尝试
Connecting	正在尝试连接或重连
Connected	连接有效，所有服务均可用
Offline	连接失败，以离线模式运行

步骤 5：测试连接

快速测试

启动 Nakama（Docker 或托管）。
打开你的 Unity 项目。
进入 Play Mode。
在控制台中查看连接消息：

[MCE Online] Connected as <DisplayName> (<UserId>)

连接测试脚本

using UnityEngine;

public class OnlineConnectionTest : MonoBehaviour
{
    private void Start()
    {
        // NakamaManager auto-creates itself
        // Check connection state after a short delay
        Invoke(nameof(CheckConnection), 3f);
    }

    private void CheckConnection()
    {
        var nakama = NakamaManager.Instance;
        Debug.Log($"Connection State: {nakama.State}");
        Debug.Log($"Connected: {nakama.IsConnected}");
    }
}

管理控制台

在线会话中的世界：延迟和服务器徽章位于右下角

右下角的徽章是连接指示器 —— 往返延迟以及你所在的服务器。这是一眼区分在线会话和离线会话的最快方式。

连接期间，在 Nakama 管理控制台（http://localhost:7351）中验证：

前往 Users —— 你应该能看到自动创建的设备账户。
前往 Runtime Modules —— 你应该能看到已加载的 MCE 服务器模块。
前往 API Explorer —— 直接测试 RPC。

在线服务概览

MCE Online 把它的 25 个服务类分组到以下模块中。每一个都是 NakamaManager 的公共属性（括号内所示）：

模块	服务
Auth	`AuthService`（`Auth`）-- 邮箱、设备和 SSO 登录；`SessionManager`（`SessionMgr`）-- 令牌持久化和刷新
World	`WorldSyncService`（`WorldSync`）-- 实时移动和兴趣区域过滤；`ChannelManager`（`Channels`）-- 世界频道
Battle	`BattleMatchmaker`（`Matchmaker`）、`PvpBattleService`（`PvpBattle`）、`SpectatorService`（`Spectator`）、`RaidBattleService`（`Raids`）
Social	`ChatService`（`Chat`）、`GuildService`（`Guilds`）、`FriendService`（`Friends`）、`TradeService`（`Trade`）
Economy	`GTLService`（`GTL`）、`GtsService`（`Gts`）、`WalletService`（`Wallet`）、`ShopService`（`Shop`）、`InventorySyncService`（`Inventory`）
Housing	`HousingService`（`Housing`）-- 秘密基地的保存/访问/邀请；`BaseSyncService`（`BaseSync`）-- 基地内的实时同在；`GymOnlineService`（`Gym`）-- 玩家道馆挑战快照
Persistence	`CloudSaveService`（`CloudSave`）
LiveOps	`EventService`（`Events`）、`LeaderboardService`（`Leaderboards`）、`AchievementService`（`Achievements`）
Modding	`ModLoader`（`Mods`）

在它们周围：NetworkedBattleManager（在线战斗编排）、PlayerNetworkEntity 和 PlayerSpawnManager（远程玩家）、AntiCheatManager、OnlineCommandBridge（把在线操作桥接到诸如怪物赠礼之类的 CommandGraph 节点）以及 OnlineSceneBootstrapper（在线场景生命周期）。

每个服务都在本节自己的指南中有说明。

故障排除

问题	解决方案
"Connection refused"	确保 Nakama 正在运行（用 `docker ps` 检查）
"Invalid server key"	检查 `OnlineConfig.ServerKey` 是否与 Nakama 的配置一致
`MCE_ONLINE` 错误	确保已设置脚本宏定义符号
连接超时	检查防火墙设置，验证服务器主机/端口
"Module not found" RPC 错误	部署服务器端 TypeScript 模块并重启 Nakama
生产环境中的 SSL 错误	确保 `UseSSL = true` 并且证书有效

下一步

在相信战斗结果之前先播种你的物种

刚部署的服务器并不认识你的物种。它用占位能力值结算战斗，并且从不告诉你 —— 没有错误，也没有警告。在判断服务器计算出的任何内容之前，请先做**物种播种**。

物种播种 -- 把你真实的物种数据交给服务器。
认证 -- 设置用户账户和登录流程。
世界同步 -- 启用实时多人世界。
PvP 战斗 -- 服务器权威的在线战斗。
经济 -- 交易、商店和货币。
世界选项 -- 设定你的世界所遵循的规则。
GM 模式 -- 运营并测试你的线上服务器。

什么是 Nakama？​

前提条件​

步骤 1：解压并启动 Nakama 服务器​

本地开发（Docker）​

如果这些端口已被占用​

托管（Heroic Cloud）​

步骤 2：配置 Unity 客户端​

OnlineConfig 资产​

为在线界面提供 emoji 字体​

启用 MCE_ONLINE 宏定义​

步骤 3：部署服务器端代码​

部署到 Nakama​

步骤 4：NakamaManager​

连接状态​

步骤 5：测试连接​

快速测试​

连接测试脚本​

管理控制台​

在线服务概览​

故障排除​

下一步​