Configuración de MCE Online

MCE Online agrega una capa MMORPG completa al Monster Capture Engine usando Nakama como backend. Esta guía te lleva por la configuración del servidor, la configuración del cliente y la prueba de conectividad.

Disponible en las ediciones Pro, Source y Studio.

¿Qué es Nakama?

Nakama es un servidor de juegos de código abierto que ofrece:

• Autenticación de usuarios (correo, dispositivo, SSO).
• Multijugador en tiempo real (WebSockets).
• Lógica de juego autoritativa en el servidor (RPC).
• Emparejamiento con clasificaciones basadas en ELO.
• Tablas de clasificación, logros y eventos en vivo.
• Guardado en la nube y almacenamiento.
• Chat, amigos, gremios.

MCE Online envuelve Nakama con 25 servicios especializados para el género de captura de monstruos. Son las propiedades de servicio públicas de NakamaManager: cuéntalas ahí si quieres el número de la versión que tienes, en lugar de fiarte de un número en un documento.

Requisitos previos

• MCE Core instalado y funcionando.
• Docker Desktop (para desarrollo local) o una instancia de Nakama alojada.
• MCE Online importado en tu proyecto.

Paso 1: Extraer e iniciar el servidor de Nakama

Desarrollo local (Docker)

Pro, Source y Studio incluyen el servidor de Nakama como Assets/OpenMon/Online/Server/mce-nakama-server.zip. Extráelo desde Unity mediante el OpenMon Hub (Tools > MCE > OpenMon Hub) → pestaña Online → Extract Server Bundle.

Todo lo de esta guía vive en esa única pestaña, aproximadamente en el orden en que lo necesitas: el modo de conexión arriba, la configuración inicial de Nakama debajo, luego la siembra de especies y, después, los controles de Docker que se usan aquí en el Paso 1.

Luego inicia la carpeta del servidor extraída:

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

Esto inicia:

Servicio	Puerto del host	Variable de entorno
API HTTP de Nakama	7350	MCE_NAKAMA_PORT
gRPC de Nakama	7349	MCE_NAKAMA_GRPC_PORT
Consola de administración de Nakama	7351	MCE_NAKAMA_CONSOLE_PORT
PostgreSQL	5432	MCE_PG_PORT

Si esos puertos ya están ocupados

Son los valores por defecto del propio Nakama y de Postgres, que es justo por lo que chocan: cualquiera que ya ejecute un Postgres, o un segundo Nakama, los tiene ocupados.

El fallo es silencioso, y esa es la parte que conviene saber. Docker no se detiene con un mensaje claro: los contenedores se quedan en Created y nada explica por qué.

Todos los puertos se pueden sobrescribir mediante la variable de entorno de la tabla de arriba:

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

O configúralos desde el editor. El Hub de UI Toolkit (Tools → MCE → OpenMon Hub (UI Toolkit), la ventana opcional, no la IMGUI que se abre por defecto) tiene un selector de puertos en su pestaña Online:

Pulsa Comprobar disponibilidad y cada puerto se comprueba enlazándolo de verdad. Esa distinción es el punto clave: un puerto puede parecer libre en un listado y aun así rechazar el enlace, y el enlace es precisamente lo que Docker está a punto de intentar.

nota

El selector de puertos es la única parte de esa pestaña migrada hasta ahora a UI Toolkit. El resto de la pestaña Online sigue viviendo en el Hub heredado, y la ventana lo indica con un botón que lleva hasta él.

El archivo compose también define un servicio opcional nakama-prodsim que arranca los mismos módulos sin MCE_DEV_MODE, usado por las pruebas E2E de la puerta de desarrollo para verificar que las RPC de concesión de la economía se rechazan en producción.

Accede a la consola de administración de Nakama en: http://localhost:7351

Credenciales de administrador por defecto:

• Usuario: admin
• Contraseña: password

Producción

La configuración de Docker por defecto es solo para desarrollo. Para producción, usa una instancia de Nakama alojada (Heroic Cloud o autoalojada con la configuración de seguridad adecuada).

Alojado (Heroic Cloud)

1. Crea una cuenta en heroiclabs.com.
2. Crea un nuevo proyecto de Nakama.
3. Anota la URL del servidor y la clave del servidor desde el panel.

Paso 2: Configurar el cliente de Unity

El asset OnlineConfig

MCE Online usa un ScriptableObject OnlineConfig para los ajustes de conexión:

1. El cliente carga el asset llamado OnlineConfig desde una carpeta Resources (Assets/Resources/OnlineConfig.asset). Pulsa Select OnlineConfig en la pestaña Online del Hub para abrirlo.
2. Si no existe, créalo: Assets > Create > MCE > Online > Configuration, con el nombre OnlineConfig y colocado en una carpeta Resources.

Configura los siguientes campos:

Campo	Descripción	Valor local por defecto
Server Host	Nombre de host del servidor de Nakama	127.0.0.1
Server Port	Puerto de la API HTTP	7350 (o el MCE_NAKAMA_PORT que hayas elegido)
Server Key	Clave de API (de la consola de Nakama)	defaultkey
Use SSL	Habilitar HTTPS/WSS	false (local), true (producción)

El OnlineConfig también contiene ajustes para:

• Enable Online y Allow Offline Fallback: si el juego se conecta y si puede recurrir al juego sin conexión cuando no se alcanza el servidor.
• Auto Reconnect y Max Reconnect Attempts: la reconexión cuando se cae la conexión.
• Connection Timeout: cuánto puede tardar un intento de conexión (segundos).
• World sync: modo de transporte, radio del área de interés (AOIRadius), máximo de jugadores visibles, frecuencia de sincronización de posición y canales.
• Interruptores de funciones: Housing, Spectator, soporte de mods, autoridad del servidor, batallas de incursión; los proveedores de inicio de sesión único (Discord, Google, Apple); y límites como amigos, miembros del gremio, anuncios de GTL e historial de chat.

Dale a la interfaz en línea su fuente de emoji

La interfaz en línea usa emoji como lenguaje de iconos: unos ochenta glifos distintos repartidos por las pantallas. La fuente por defecto de TextMesh Pro no tiene ninguno y muestra cada uno como ▯.

Abre el Hub → pestaña Build → Setup Emoji Fallback (Online UI). Conecta la fuente Noto Emoji incluida (SIL OFL 1.1, en Assets/OpenMon/Online/UI/Fonts/) a la lista de fallback de TMP.

Por qué esto es un paso y no algo que ya viene hecho

La fuente y su asset de TMP vienen dentro de Assets/OpenMon/Online, así que llegan con el paquete. La conexión no: vive en TMP Settings, bajo Assets/TextMesh Pro, que no forma parte de la carga útil de ninguna edición. Así que el asset llega y la lista que apunta a él no: un botón cierra la brecha.

El mismo asset de fuente es dinámico: rasteriza los glifos a partir del .ttf bajo demanda, así que no hay nada precalculado y agregarlo no cuesta construir un atlas. Por eso tampoco se puede simplemente ampliar la fuente por defecto: su atlas es estático y no puede crecer.

Habilitar el define MCE_ONLINE

MCE Online requiere el símbolo de scripting define MCE_ONLINE:

1. Ve a Edit > Project Settings > Player > Other Settings > Scripting Define Symbols.
2. Agrega MCE_ONLINE a la lista.
3. Haz clic en Apply.

Esto habilita todos los caminos de código relacionados con el modo en línea en el motor.

Paso 3: Desplegar el código del servidor

MCE Online incluye dos entornos de ejecución dentro del paquete del servidor extraído: módulos TypeScript para RPC, batallas, economía y social, y un plugin de Go que ejecuta la partida del mundo.

La estructura del paquete, abreviada (las carpetas contienen más archivos de los listados):

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

El mundo necesita el plugin de Go

world_map no es TypeScript. Viene precompilado como nakama/data/modules/mundo.so y Nakama lo carga al arrancar, así que no hay nada más que hacer en Nakama 3.22.0 / linux-amd64, la versión a la que apunta este paquete.

Un plugin de Go debe compilarse contra la versión exacta de Nakama que lo carga. En cualquier otra versión el plugin precompilado no se cargará y world_join fallará. No hay alternativa en TypeScript, y es deliberado: el mundo en TypeScript tardaba 450 ms por tick frente a 12 ms del de Go, con 253 606 posiciones descartadas por colas llenas frente a cero. Una alternativa silenciosa 37 veces más lenta es peor que un fallo ruidoso: verías un juego que funciona mal sin causa visible.

Reconstrúyelo para tu versión con node go/construir.mjs (necesita Docker). Los fuentes de Go vienen con el paquete precisamente para esto.

nota

El repositorio de código fuente guarda estos archivos bajo Assets/OpenMon/Online/Server~/ para que Unity los ignore. El paquete comercial los distribuye como mce-nakama-server.zip; extrae ese zip antes de ejecutar comandos de Docker o npm.

Desplegar en Nakama

1. Compila los módulos del servidor:

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

2. La compilación genera nakama/build/index.js (consulta outFile en tsconfig.json).
3. Reinicia Nakama para cargar los módulos.

El docker-compose.yml incluido ya monta la salida de la compilación: no hace falta copiar nada a mano:

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

Paso 4: NakamaManager

NakamaManager es el singleton que gestiona la conexión:

• Se crea automáticamente en tiempo de ejecución mediante [RuntimeInitializeOnLoadMethod].
• Posee las 25 clases de servicio (Auth, World, Battle, Social, Economy, Housing, Persistence, LiveOps, Modding).
• Gestiona la reconexión con retroceso exponencial.
• Encamina toda la comunicación con Nakama por una cola del hilo principal (segura entre hilos).

No necesitas crear ni configurar el NakamaManager manualmente. Lee de OnlineConfig y se inicializa solo.

Estados de conexión

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

Estado	Descripción
Disconnected	Sin conexión y sin intentarla
Connecting	Intentando conectar o reconectar
Connected	Conexión activa, todos los servicios disponibles
Offline	No se pudo conectar, funcionando en modo sin conexión

Paso 5: Probar la conectividad

Prueba rápida

1. Inicia Nakama (Docker o alojado).
2. Abre tu proyecto de Unity.
3. Entra en Play Mode.
4. Revisa en la Consola los mensajes de conexión:

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

Script de prueba de conexión

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}");
    }
}

Consola de administración

La insignia de la esquina inferior derecha es el indicador de conexión: la latencia de ida y vuelta y el servidor en el que estás. Es la forma más rápida de distinguir de un vistazo una sesión en línea de una sin conexión.

Mientras estés conectado, verifica en la consola de administración de Nakama (http://localhost:7351):

1. Ve a Users: deberías ver la cuenta de dispositivo creada automáticamente.
2. Ve a Runtime Modules: deberías ver los módulos de servidor de MCE cargados.
3. Ve a API Explorer: prueba las RPC directamente.

Resumen de los servicios en línea

MCE Online agrupa sus 25 clases de servicio en estos módulos. Cada una es una propiedad pública de NakamaManager (se muestra entre paréntesis):

Módulo	Servicios
Auth	AuthService (Auth): inicio de sesión por correo, dispositivo y SSO; SessionManager (SessionMgr): persistencia y renovación de tokens
World	WorldSyncService (WorldSync): movimiento en tiempo real y filtrado por área de interés; ChannelManager (Channels): canales del mundo
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): guardar/visitar/invitar a una base secreta; BaseSyncService (BaseSync): copresencia en vivo dentro de una base; GymOnlineService (Gym): instantánea del desafío al gimnasio de un jugador
Persistence	CloudSaveService (CloudSave)
LiveOps	EventService (Events), LeaderboardService (Leaderboards), AchievementService (Achievements)
Modding	ModLoader (Mods)

A su alrededor: NetworkedBattleManager (orquestación de las batallas en línea), PlayerNetworkEntity y PlayerSpawnManager (jugadores remotos), AntiCheatManager, OnlineCommandBridge (conecta las acciones en línea con nodos de CommandGraph como los Regalos de monstruos) y OnlineSceneBootstrapper (ciclo de vida de la escena en línea).

Cada servicio está documentado en su propia guía de esta sección.

Solución de problemas

Problema	Solución
"Connection refused"	Asegúrate de que Nakama esté en marcha (docker ps para comprobarlo)
"Invalid server key"	Comprueba que OnlineConfig.ServerKey coincida con la configuración de Nakama
Errores de MCE_ONLINE	Asegúrate de que el símbolo de scripting define esté establecido
Tiempo de espera al conectar	Revisa la configuración del firewall y verifica el host/puerto del servidor
Errores de RPC "Module not found"	Despliega los módulos TypeScript del servidor y reinicia Nakama
Errores de SSL en producción	Asegúrate de que UseSSL = true y de tener certificados válidos

Próximos pasos

Siembra tus especies antes de fiarte del resultado de una batalla

Un servidor recién desplegado no conoce tus especies. Resuelve las batallas con estadísticas de relleno y nunca lo dice: ni error, ni advertencia. Haz Siembra de especies a continuación, antes de juzgar cualquier cosa que calcule el servidor.

• Siembra de especies -- Dale al servidor los datos reales de tus especies.
• Autenticación -- Configura cuentas de usuario y flujos de inicio de sesión.
• Sincronización del mundo -- Habilita el mundo multijugador en tiempo real.
• Batallas PvP -- Batallas en línea autoritativas en el servidor.
• Economía -- Intercambio, tiendas y moneda.
• Opciones del mundo -- Establece las reglas con las que juega tu mundo.
• Modo GM -- Opera y prueba tu servidor en vivo.