Game & Join API - Mercury Core

Join Game

GET /game/join Generates a signed Lua script to join a game server. Handles both authenticated game sessions and default local testing.

ticket

string

Client session ticket for authenticated joins (from playing record)

privateServer

string

Optional private server ticket for joining private servers

Response

Returns a signed Lua script that:

Configures the client with server connection details
Sets user information and membership type
Loads character appearance
Establishes presence ping URL

Script Variables

object

Show Variables

_PLACE_ID

number

The place ID to join (0 for local testing)

_SERVER_ADDRESS

string

Server hostname or IP address

_SERVER_PORT

number

Server port number

_USER_ID

number

Random user ID for the session

_USERNAME

string

Player’s username

_MEMBERSHIP_TYPE

string

Player’s membership level based on permission level

_CHAR_APPEARANCE

string

URL to character appearance data

_PING_URL

string

URL for client presence updates

Default Behavior (No Ticket)

When called without a ticket parameter, returns a local testing configuration:

Place ID: 0
Server: localhost:53640
Username: Player1
No character appearance or ping URL

Authenticated Join

With a valid ticket:

Validates private server ticket if provided
Retrieves and invalidates the game session
Determines server address based on hosting configuration (dedicated vs self-hosted)
Generates character appearance URL
Creates presence ping URL

Server Hosting Modes

The endpoint respects the Gameservers.Hosting configuration:

Dedicated: Always uses OrbiterPublicDomain with port based on place ID
Selfhosted: Uses place’s configured serverAddress and serverPort
Both: Respects the place’s dedicated flag

Example Request

# Local testing
curl "http://mercury.local/game/join"

# Authenticated join
curl "http://mercury.local/game/join?ticket=abc123"

# Private server join
curl "http://mercury.local/game/join?ticket=abc123&privateServer=xyz789"

Implementation

Source: (rbxclient)/game/join/+server.ts:38

Host Game Server

GET /game/host Generates a signed Lua script to start a self-hosted game server. Requires a server ticket.

ticket

string

required

Server ticket for the place being hosted

autopilot

string

Base64-encoded map filename (must end in .rbxl)

Response

Returns a signed Lua script configured for server hosting:

Script Variables

object

Show Variables

_BASE_URL

string

Mercury domain for API calls

_MAP_LOCATION

string

Map file path (rbxasset://maps/ or empty)

_SERVER_PORT

number

Port number for the server (derived from place ID)

_SERVER_PRESENCE_URL

string

URL for server presence heartbeats

Autopilot Maps

The autopilot parameter allows loading custom maps:

Value must be base64-encoded
Decoded value must end with .rbxl
Map is loaded from rbxasset://maps/{filename}

This endpoint returns an error if Gameservers.Hosting is set to “Dedicated”

Example Request

# Basic server hosting
curl "http://mercury.local/game/host?ticket=server123"

# With custom map
curl "http://mercury.local/game/host?ticket=server123&autopilot=$(echo -n 'custommap.rbxl' | base64)"

Implementation

Source: (rbxclient)/game/host/+server.ts:7

Serve Place File

GET /game/{id} Serves the place file (RBXL) for dedicated game servers.

number

required

The place ID to serve

Response

Returns the binary place file from ../data/places/{id}.

Validation

Verifies the place exists in the database
Checks if the place file exists on disk
Returns 404 if either check fails

Bearer token authentication is temporarily disabled in the current implementation

Example Request

curl "http://mercury.local/game/123"

Implementation

Source: (rbxclient)/game/[id=asset]/+server.ts:5

Serve Place Script (Dedicated)

GET /game/{id}/serve Generates a signed hosting script for dedicated game servers.

number

required

The place ID to host

Response

Returns a signed Lua script with:

Base URL for API calls
Map location pointing to /game/{id}
Server port derived from place ID
Server presence URL with server ticket

Returns 400 error if Gameservers.Hosting is set to “Selfhosted”

Example Request

curl "http://mercury.local/game/123/serve"

Implementation

Source: (rbxclient)/game/[id=asset]/serve/+server.ts:14

Visit (Studio)

GET /game/visit Generates a signed Lua script for Roblox Studio visits.

Response

Returns a signed visit script with place ID set to 0.

Example Request

curl "http://mercury.local/game/visit"

Implementation

Source: (rbxclient)/game/visit/+server.ts:3

Studio Mode

GET /game/studio Generates a signed Lua script for Roblox Studio mode.

Response

Returns a signed studio script for launching Studio.

Example Request

curl "http://mercury.local/game/studio"

Implementation

Source: (rbxclient)/game/studio/+server.ts:3

Client Presence

GET /game/clientpresence Receives heartbeat pings from connected clients to track active sessions.

ticket

string

required

The playing session ticket

Validation

Must be called with User-Agent: Roblox/WinInet
Ticket must exist in the playing records

Response

Returns “OK” with no-cache headers.

Cache-Control

string

Set to no-cache

Example Request

curl -H "User-Agent: Roblox/WinInet" "http://mercury.local/game/clientpresence?ticket=abc123"

Implementation

Source: (rbxclient)/game/clientpresence/+server.ts:5

Server Presence

GET /game/serverpresence Receives heartbeat pings from game servers to track server health and uptime.

ticket

string

required

The server ticket

Validation

Must be called with User-Agent: Roblox/WinInet
Ticket parameter is required

Response

Returns “OK” with no-cache headers.

Cache-Control

string

Set to no-cache

Example Request

curl -H "User-Agent: Roblox/WinInet" "http://mercury.local/game/serverpresence?ticket=server123"

Implementation

Source: (rbxclient)/game/serverpresence/+server.ts:5

Machine Configuration

GET /game/machineconfiguration Returns machine configuration for the client. Currently returns a basic OK response.

Response

Returns “OK” as plain text.

Example Request

curl "http://mercury.local/game/machineconfiguration"

Implementation

Source: (rbxclient)/game/machineconfiguration/+server.ts:1

Insert Asset Tool

GET /game/tools/insertasset Redirects to an external service for asset insertion in Studio.

Response

Returns a 302 redirect to https://sets.pizzaboxer.xyz/Game/Tools/InsertAsset.ashx with query parameters preserved.

Example Request

curl "http://mercury.local/game/tools/insertasset?assetId=123"

Implementation

Source: (rbxclient)/game/tools/insertasset/+server.ts:3

Thumbnail Asset Tool

GET /game/tools/thumbnailasset Provides cached asset thumbnails for use in Studio and games (e.g., stamper tool).

aid

number

required

Asset ID to get thumbnail for

number

required

Thumbnail width in pixels

number

required

Thumbnail height in pixels

Response

Returns a 302 redirect to the thumbnail image URL. Thumbnails are:

Checked in local cache first
Fetched from Roblox thumbnails API if not cached
Cached locally for future requests

Thumbnail API

Uses Roblox’s thumbnail API with parameters:

returnPolicy: Placeholder
format: Png
isCircular: false

Example Request

curl "http://mercury.local/game/tools/thumbnailasset?aid=123&wd=150&ht=150"

Implementation

Source: (rbxclient)/game/tools/thumbnailasset/+server.ts:7

Economy Service

Client API

Web API

​Join Game

​Response

​Default Behavior (No Ticket)

​Authenticated Join

​Server Hosting Modes

​Example Request

​Implementation

​Host Game Server

​Response

​Autopilot Maps

​Example Request

​Implementation

​Serve Place File

​Response

​Validation

​Example Request

​Implementation

​Serve Place Script (Dedicated)

​Response

​Example Request

​Implementation

​Visit (Studio)

​Response

​Example Request

​Implementation

​Studio Mode

​Response

​Example Request

​Implementation

​Client Presence

​Validation

​Response

​Example Request

​Implementation

​Server Presence

​Validation

​Response

​Example Request

​Implementation

​Machine Configuration

​Response

​Example Request

​Implementation

​Insert Asset Tool

​Response

​Example Request

​Implementation

​Thumbnail Asset Tool

​Response

​Thumbnail API

​Example Request

​Implementation

Build docs developers (and LLMs) love

Join Game

Response

Default Behavior (No Ticket)

Authenticated Join

Server Hosting Modes

Example Request

Implementation

Host Game Server

Response

Autopilot Maps

Example Request

Implementation

Serve Place File

Response

Validation

Example Request

Implementation

Serve Place Script (Dedicated)

Response

Example Request

Implementation

Visit (Studio)

Response

Example Request

Implementation

Studio Mode

Response

Example Request

Implementation

Client Presence

Validation

Response

Example Request

Implementation

Server Presence

Validation

Response

Example Request

Implementation

Machine Configuration

Response

Example Request

Implementation

Insert Asset Tool

Response

Example Request

Implementation

Thumbnail Asset Tool

Response

Thumbnail API

Example Request

Implementation