MCE Online Setup

MCE Online adds a complete MMORPG layer to the Monster Capture Engine using Nakama as the backend. This guide walks you through setting up the server, configuring the client, and testing connectivity.

Available in Online tier and above.

What is Nakama?

Nakama is an open-source game server that provides:

• User authentication (email, device, SSO).
• Real-time multiplayer (WebSockets).
• Server-authoritative game logic (RPCs).
• Matchmaking with ELO-based ratings.
• Leaderboards, achievements, and live events.
• Cloud save and storage.
• Chat, friends, guilds.

MCE Online wraps Nakama with 18 specialized services for the monster capture genre.

Prerequisites

• MCE Core installed and working.
• Docker Desktop (for local development) or a hosted Nakama instance.
• MCE Online addon imported into your project.

Step 1: Start the Nakama Server

Local Development (Docker)

MCE includes a docker-compose.yml for local Nakama:

# From your project root or the MCE_Online server directory
docker-compose up -d

This starts:

• Nakama server on port 7350 (gRPC) and 7351 (HTTP/console).
• CockroachDB as the database on port 26257.

Access the Nakama admin console at: http://localhost:7351

Default admin credentials:

• Username: admin
• Password: password

Production

The default Docker configuration is for development only. For production, use a hosted Nakama instance (Heroic Cloud or self-hosted with proper security configuration).

Hosted (Heroic Cloud)

1. Create an account at heroiclabs.com.
2. Create a new Nakama project.
3. Note the server URL and server key from the dashboard.

Step 2: Configure the Unity Client

OnlineConfig Asset

MCE Online uses an OnlineConfig ScriptableObject for connection settings:

1. Navigate to Assets/MCE_Online/Resources/OnlineConfig.asset.
2. If it does not exist, create it: Assets > Create > MCE Online > Online Config.

Configure the following fields:

Field	Description	Local Default
Server Host	Nakama server hostname	localhost
Server Port	HTTP port	7350
Server Key	API key (from Nakama console)	defaultkey
Use SSL	Enable HTTPS/WSS	false (local), true (production)

The OnlineConfig also contains settings for:

• Auto-Connect: Whether to connect automatically on game start.
• Reconnection: Exponential backoff settings for dropped connections.
• Timeout: Request timeout duration.
• Feature Toggles: Enable/disable specific online features.

Enable the MCE_ONLINE Define

MCE Online requires the MCE_ONLINE scripting define symbol:

1. Go to Edit > Project Settings > Player > Other Settings > Scripting Define Symbols.
2. Add MCE_ONLINE to the list.
3. Click Apply.

This enables all online-related code paths in the engine.

Step 3: Deploy Server-Side Code

MCE Online includes TypeScript server modules for Nakama:

MCE_Online/
  Server/
    src/
      main.ts          # Entry point, RPC registration
      battle.ts        # Server-authoritative battle RPCs
      gtl.ts           # Global Trade Link RPCs
      housing.ts       # Housing system RPCs
    tsconfig.json
    package.json

Deploy to Nakama

1. Build the server modules:

cd MCE_Online/Server
npm install
npm run build

2. Copy the built JS output to your Nakama data/modules/ directory.
3. Restart Nakama to load the modules.

For Docker, the docker-compose.yml typically mounts the modules directory:

volumes:
  - ./MCE_Online/Server/dist:/nakama/data/modules

Step 4: NakamaManager

The NakamaManager is the singleton that manages the connection:

• Created automatically at runtime via [RuntimeInitializeOnLoadMethod].
• Manages 18 services (Auth, Battle, Economy, Social, etc.).
• Handles reconnection with exponential backoff.
• Routes all Nakama communication through a main thread queue (thread-safe).

You do not need to create or configure the NakamaManager manually. It reads from OnlineConfig and initializes itself.

Connection States

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

State	Description
Disconnected	No connection, not attempting
Connecting	Attempting to connect or reconnect
Connected	Active connection, all services available
Offline	Failed to connect, operating in offline mode

Step 5: Test Connectivity

Quick Test

1. Start Nakama (Docker or hosted).
2. Open your Unity project.
3. Enter Play Mode.
4. Check the Console for connection messages:

[NakamaManager] Connecting to localhost:7350...
[NakamaManager] Connected successfully. Session ID: xxxx

Connection Test Script

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.ConnectionState}");
        Debug.Log($"Session Valid: {nakama.IsSessionValid}");
    }
}

Admin Console

While connected, verify on the Nakama admin console (http://localhost:7351):

1. Go to Users -- you should see the auto-created device account.
2. Go to Runtime Modules -- you should see the loaded MCE server modules.
3. Go to API Explorer -- test RPCs directly.

Online Services Overview

MCE Online provides 18 services:

Service	Description
AuthService	Email, Device, SSO authentication
SessionManager	Token persistence and refresh
WorldSyncService	Real-time player movement, AOI filtering
PlayerNetworkEntity	Networked player representation
BattleServices	Server-authoritative PvP, matchmaking
NetworkedBattleManager	Online battle orchestration
EconomyServices	Global Trade Link, wallet, shop
SocialServices	Chat, guilds, friends, trading
HousingService	Player housing CRUD
PersistenceAndSystems	Cloud saves, backups
AntiCheatManager	Speed validation, inventory auditing
EventService	Live events
LeaderboardService	Rankings and scores
AchievementService	Achievement tracking
ModLoader	Server-side mod management
OnlineCommandBridge	Bridges online actions to CommandGraph
OnlineSceneBootstrapper	Online scene lifecycle

Each service is documented in its own guide in this section.

Troubleshooting

Issue	Solution
"Connection refused"	Ensure Nakama is running (docker ps to check)
"Invalid server key"	Check OnlineConfig.ServerKey matches Nakama's config
MCE_ONLINE errors	Ensure the scripting define symbol is set
Timeout on connect	Check firewall settings, verify server host/port
"Module not found" RPC errors	Deploy server-side TypeScript modules and restart Nakama
SSL errors in production	Ensure UseSSL = true and valid certificates

Next Steps

• Authentication -- Set up user accounts and login flows.
• World Sync -- Enable real-time multiplayer world.
• PvP Battles -- Server-authoritative online battles.
• Economy -- Trading, shops, and currency.