Настройка MCE Online

MCE Online добавляет в Monster Capture Engine полноценный слой MMORPG, используя Nakama в качестве бэкенда. Это руководство проведёт вас через настройку сервера, настройку клиента и проверку подключения.

Доступно в редакциях Pro, Source и Studio.

Что такое Nakama?

Nakama — игровой сервер с открытым исходным кодом, который предоставляет:

• Аутентификацию пользователей (почта, устройство, SSO).
• Многопользовательскую игру в реальном времени (WebSocket).
• Серверно-авторитетную игровую логику (RPC).
• Подбор соперников с рейтингами на основе ELO.
• Таблицы лидеров, достижения и живые события.
• Облачные сохранения и хранилище.
• Чат, друзей, гильдии.

MCE Online оборачивает Nakama в 25 специализированных сервисов для жанра ловли монстров. Это публичные свойства-сервисы NakamaManager — пересчитайте их там, если вам нужно число для вашей версии, вместо того чтобы доверять числу в документе.

Предварительные требования

• Установленный и работающий MCE Core.
• Docker Desktop (для локальной разработки) или размещённый экземпляр Nakama.
• MCE Online, импортированный в ваш проект.

Шаг 1: Распакуйте и запустите сервер Nakama

Локальная разработка (Docker)

Pro, Source и Studio включают сервер Nakama как Assets/OpenMon/Online/Server/mce-nakama-server.zip. Распакуйте его из Unity через OpenMon Hub (Tools > MCE > OpenMon Hub) → вкладка Online → Extract Server Bundle.

Всё в этом руководстве находится на этой единственной вкладке, примерно в том порядке, в котором оно вам нужно: режим подключения вверху, первичная настройка Nakama под ним, затем засев видов, затем элементы управления Docker, используемые здесь на шаге 1.

Затем запустите распакованную папку сервера:

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

Это запускает:

Сервис	Порт хоста	Переменная окружения
HTTP API Nakama	7350	MCE_NAKAMA_PORT
gRPC Nakama	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 есть выбор портов:

Нажмите Comprobar disponibilidad, и каждый порт проверяется реальной попыткой его занять. В этом различии вся суть: порт может выглядеть свободным в списке и всё же отказать в привязке, а привязка — это именно то, что вот-вот попытается сделать Docker.

примечание

Выбор портов — единственная часть этой вкладки, перенесённая на UI Toolkit на данный момент. Остальная часть вкладки Online по-прежнему находится в прежнем Hub, и окно сообщает об этом кнопкой перехода в него.

Файл compose также определяет необязательный сервис nakama-prodsim, который запускает те же модули без MCE_DEV_MODE; он используется E2E-тестами dev-шлюза, чтобы убедиться, что RPC выдачи в экономике отклоняются в продакшене.

Консоль администратора Nakama доступна по адресу: http://localhost:7351

Учётные данные администратора по умолчанию:

• Имя пользователя: admin
• Пароль: password

Продакшен

Конфигурация Docker по умолчанию предназначена только для разработки. Для продакшена используйте размещённый экземпляр Nakama (Heroic Cloud или собственный хостинг с правильной настройкой безопасности).

Размещённый (Heroic Cloud)

1. Создайте аккаунт на heroiclabs.com.
2. Создайте новый проект Nakama.
3. Запишите URL сервера и ключ сервера с панели управления.

Шаг 2: Настройте клиент Unity

Ассет OnlineConfig

MCE Online использует ScriptableObject OnlineConfig для параметров подключения:

1. Клиент загружает ассет с именем OnlineConfig из папки Resources (Assets/Resources/OnlineConfig.asset). Нажмите Select OnlineConfig на вкладке Online в Hub, чтобы открыть его.
2. Если его нет, создайте: 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, поддержка модов, серверный авторитет, рейдовые сражения; провайдеры единого входа (Discord, Google, Apple); а также лимиты, такие как друзья, члены гильдии, лоты GTL и история чата.

Дайте онлайн-интерфейсу шрифт эмодзи

Онлайн-интерфейс использует эмодзи как язык значков — около восьмидесяти различных глифов на экранах. В шрифте 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, поэтому приходят вместе с пакетом. А вот подключение — нет: оно находится в TMP Settings под Assets/TextMesh Pro, который не входит ни в один пакет редакций. Ассет приходит, а список, который на него указывает, — нет: одна кнопка закрывает этот разрыв.

Тот же ассет шрифта динамический: он растеризует глифы из .ttf по требованию, поэтому ничего не запекается заранее, а его добавление не требует построения атласа. Поэтому же шрифт по умолчанию нельзя просто расширить: его атлас статичен и не может расти.

Включите define MCE_ONLINE

MCE Online требует символ define скриптинга MCE_ONLINE:

1. Перейдите в Edit > Project Settings > Player > Other Settings > Scripting Define Symbols.
2. Добавьте MCE_ONLINE в список.
3. Нажмите Apply.

Это включает все связанные с онлайном пути кода в движке.

Шаг 3: Разверните серверный код

MCE Online поставляет две среды выполнения внутри распакованного пакета сервера: модули TypeScript для RPC, сражений, экономики и социальных функций и плагин на 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 занимал 450 мс на тик против 12 мс у мира на Go, при этом было потеряно 253 606 позиций из-за переполненных очередей против нуля. Молчаливая запасная версия, работающая в 37 раз медленнее, хуже громкого сбоя: вы бы увидели игру, которая плохо работает без видимой причины.

Пересоберите его под вашу версию командой node go/construir.mjs (нужен Docker). Исходники на Go поставляются вместе с пакетом именно для этого.

примечание

Репозиторий с исходным кодом хранит эти файлы в Assets/OpenMon/Online/Server~/, чтобы Unity их игнорировал. Коммерческий пакет поставляет их как mce-nakama-server.zip; распакуйте этот zip, прежде чем запускать команды Docker или npm.

Развёртывание в Nakama

1. Соберите серверные модули:

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

2. Сборка компилируется в nakama/build/index.js (см. outFile в tsconfig.json).
3. Перезапустите 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: Проверка подключения

Быстрая проверка

1. Запустите Nakama (Docker или размещённый).
2. Откройте проект Unity.
3. Войдите в Play Mode.
4. Проверьте сообщения о подключении в консоли:

[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):

1. Откройте Users — вы должны увидеть автоматически созданный аккаунт устройства.
2. Откройте Runtime Modules — вы должны увидеть загруженные серверные модули MCE.
3. Откройте 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	Убедитесь, что символ define скриптинга задан
Тайм-аут при подключении	Проверьте настройки брандмауэра, проверьте хост и порт сервера
Ошибки RPC «Module not found»	Разверните серверные модули TypeScript и перезапустите Nakama
Ошибки SSL в продакшене	Убедитесь, что UseSSL = true и сертификаты действительны

Следующие шаги

Засейте виды, прежде чем доверять результату сражения

Только что развёрнутый сервер не знает ваших видов. Он разрешает сражения с подставными характеристиками и никогда об этом не сообщает — ни ошибки, ни предупреждения. Выполните Засев видов следующим шагом, прежде чем оценивать что-либо, что вычисляет сервер.

• Засев видов -- Передайте серверу реальные данные ваших видов.
• Аутентификация -- Настройте учётные записи пользователей и сценарии входа.
• Синхронизация мира -- Включите многопользовательский мир в реальном времени.
• PvP-сражения -- Серверно-авторитетные онлайн-сражения.
• Экономика -- Обмен, магазины и валюта.
• Опции мира -- Задайте правила, по которым играет ваш мир.
• Режим GM -- Управляйте работающим сервером и тестируйте его.