Skip to main content
Mercury Core supports flexible game hosting with both self-hosted and dedicated server options, allowing players to host games from their own computers or use centralized dedicated servers.

​
Hosting Modes

Configure your preferred hosting mode in Assets/schema.ts: 
Gameservers: {
  Hosting: "Selfhosted" | "Dedicated" | "Both"
}

Self-Hosted

Players run game servers on their own machines. Ideal for small communities and testing.

Dedicated

Central servers managed by Orbiter. Best for production deployments and larger player counts.

Both

Support both modes simultaneously. Players can choose their preferred hosting method.

​
Places (Games)

Places are the core game units in Mercury Core. Each place represents a playable game world.

​
Creating a Place

Places are created through the Games section:
  1. Navigate to /games/create
  2. Upload a place file (game world data)
  3. Configure place settings
  4. Place is automatically assigned a unique ID

​
Place Configuration

Place owners can configure their games through the settings page (/place/{id}/{name}/settings).

​
Visual Presentation

Configure how your place appears to players:Name:
  • 3-100 characters
  • Filtered for profanity
  • Used in URLs and listings
Description:
  • Up to 1000 characters
  • Supports formatted text
  • Filtered for profanity
  • Shows last updated timestamp
Icon:
  • Custom place icon upload
  • Maximum 1MB file size
  • Automatically resized to 270x270
  • Converted to AVIF format for optimal delivery
  • Stored in data/icons/{placeId}.avif
Thumbnails:
  • Default thumbnails are assigned based on place ID
  • Configured in Images.DefaultPlaceThumbnails
Source: Site/src/routes/(main)/place/[id=asset]/[name]/settings/+page.server.ts:103-134

​
Joining Games

Players can join games through the place page (/place/{id}/{name}).

​
Join Process

1

Navigate to Place

Click on a game from the Games listing page
2

Join Server

Click the “Join” button to get a play ticket
3

Launch Client

The platform opens the game client using a custom launcher URI scheme
4

Connect

Client connects to the game server using the provided ticket

​
Join Ticket System

When a player joins:
  1. All existing playing sessions for the user are invalidated
  2. A new unique join ticket is generated
  3. The ticket is passed to the game client via the launcher URI
  4. Orbiter validates the ticket when the client connects
  5. Player status is updated to “Playing”
Security:
  • Tickets are single-use and time-limited
  • Moderated users cannot join games
  • Private server access is verified
Source: Site/src/routes/(main)/place/[id=asset]/[name]/+page.server.ts:116-127

​
Dedicated Server Management

When using dedicated hosting mode, servers are managed through Orbiter.

​
Starting a Server

Players can start dedicated servers for places:
  1. Click “Start Server” on the place page
  2. System verifies place file exists
  3. Request is sent to Orbiter to spawn server
  4. Server starts and listens for connections
Requirements:
  • Place file must exist in data/places/{placeId}
  • Rate limited to 20 requests per time window
  • User must have access to the place
Source: Site/src/routes/(main)/place/[id=asset]/[name]/+page.server.ts:129-153

​
Closing a Server

Servers can be closed by:
  • Place Owner: Full control over their servers
  • Administrators: Permission level 4+ can close any server
Process:
  1. Submit close request
  2. Orbiter gracefully shuts down the server
  3. Players are disconnected
  4. Resources are freed
Source: Site/src/routes/(main)/place/[id=asset]/[name]/+page.server.ts:155-169

​
Server Status

Place pages display real-time server information:
  • Server Ping: Latency to the game server
  • Active Players: List of currently connected players with usernames
  • Max Players: Configured player limit
  • Server Status: Online/Offline indicator

​
Orbiter Integration

Orbiter is Mercury Core’s game server orchestrator.

​
Configuration

Configure Orbiter in Assets/schema.ts: 
OrbiterPrivateURL: "http://localhost:8080",  // Private API for Site
OrbiterPublicDomain: "orbiter.example.com",  // Public domain for browsers

​
API Functions

  • List Gameservers: Get all running servers (admin only)
  • Start Gameserver: Spawn a new dedicated server
  • Close Gameserver: Gracefully shut down a server
  • Get Server Status: Query server state and player list
Source: Site/src/lib/server/orbiter.ts

​
Launcher URI

Mercury Core uses a custom URI scheme to launch the game client: 
LauncherURI: "mercurycore://"  // Configure in schema.ts
The launcher URI is called with: 
{LauncherURI}join?ticket={ticket}&server={serverAddress}
The client application handles this URI scheme to:
  1. Parse connection parameters
  2. Authenticate with the ticket
  3. Connect to the game server
  4. Load the place data

​
Admin Tools

Administrators with permission level 5 can access gameserver management at /admin/gameservers.

​
Gameserver Dashboard

  • View all active dedicated servers
  • See player counts and connection info
  • Monitor server health and performance
  • Force close servers if needed
Source: Site/src/routes/(main)/admin/gameservers/+page.server.ts:5-14

Build docs developers (and LLMs) love

Get started for freeTalk to us