Server selection and join codes
The launcher gets the server list using your project ID, displays it, then
passes the selected server’s join code to client-helper.exe.
| Value | Use |
|---|---|
| Project ID | Request the servers registered to your project. |
| Server ID | Identify a server in the list and remember the player’s selection. |
| Join code | Select the connection target for inspect, prepare and launch. |
To register an instance and get its join code, see Register a production server.
Get servers by project ID
Section titled “Get servers by project ID”Send this request to the discovery API:
GET /api/v1/project/{projectId}/serversAccept: application/jsonThe endpoint is public and requires no authorization header. Keep the API base
URL and public project ID in your launcher configuration. Keep project_secret
on the server and out of the launcher package.
A response contains the project and its registered servers:
{ "project": { "id": "e04dc4c2-f622-4e41-9b12-2390c09b80c3", "name": "Example" }, "servers": [ { "id": "0e79a9cc-3bb9-4d15-a99d-30fa0755b162", "name": "Example #1", "joinCode": "example_01", "language": "en", "dev": false, "hasPassword": false, "currentPlayers": 42, "maxPlayers": 300, "online": true, "lastSeenAt": "2026-11-16T12:00:00.000Z" } ]}servers can be empty. A missing project returns HTTP 404.
In Electron, fetch the list in the main process. This example accepts the API base URL and project ID from your launcher configuration and returns the fields used by the interface. Extra response fields are ignored.
// @ts-check
/** * @typedef {object} Server * @property {string} id * @property {string} name * @property {string} joinCode * @property {boolean} online * @property {boolean} hasPassword * @property {number | null} currentPlayers * @property {number | null} maxPlayers */
/** @param {unknown} value */const isCount = value => value === null || (typeof value === 'number' && Number.isSafeInteger(value) && value >= 0);
/** * Run in Electron's main process. * @param {string} apiUrl Discovery API base URL from your launcher configuration. * @param {string} projectId Your public project UUID. * @returns {Promise<Server[]>} */export async function fetchServers(apiUrl, projectId) { const id = projectId.toLowerCase(); const url = new URL(`/api/v1/project/${encodeURIComponent(id)}/servers`, apiUrl); const response = await fetch(url, { headers: { Accept: 'application/json' }, redirect: 'error', signal: AbortSignal.timeout(15_000), }); if (!response.ok) throw new Error(`Could not load servers (${response.status})`);
const directory = await response.json(); const servers = directory?.servers; if (directory?.project?.id !== id || !Array.isArray(servers)) { throw new Error('Invalid server directory response'); }
return servers.map(server => { if (!server || typeof server.id !== 'string' || typeof server.name !== 'string' || typeof server.joinCode !== 'string' || !/^[A-Za-z0-9_-]{1,32}$/.test(server.joinCode) || typeof server.online !== 'boolean' || typeof server.hasPassword !== 'boolean' || !isCount(server.currentPlayers) || !isCount(server.maxPlayers)) { throw new Error('Invalid server entry'); }
return { id: server.id, name: server.name, joinCode: server.joinCode, online: server.online, hasPassword: server.hasPassword, currentPlayers: server.currentPlayers, maxPlayers: server.maxPlayers, }; });}
/** * Look up the renderer's selection in the main process's latest server list. * @param {Server[]} servers * @param {string} selectedId */export function selectServer(servers, selectedId) { const server = servers.find(entry => entry.id === selectedId); if (!server?.online) throw new Error('The selected server is unavailable'); return server;}Display the list
Section titled “Display the list”Show the server name, player count and password requirement. Keep offline
servers visible with connection disabled. online is based on the server’s
last heartbeat. An offline server has currentPlayers: null, so display
“Offline” rather than a zero player count. maxPlayers, language and
lastSeenAt can also be null.
For example, the renderer can build a button for each server. Pass the selected server ID to your preload’s selection action:
// @ts-check
/** * Run in the renderer. onSelect calls your preload's server-selection action. * @param {HTMLElement} container * @param {import('./server-directory.mjs').Server[]} servers * @param {(id: string) => Promise<void>} onSelect * @param {(message: string) => void} showError */export function renderServers(container, servers, onSelect, showError) { container.replaceChildren(); if (servers.length === 0) { container.textContent = 'No servers are registered yet.'; return; }
for (const server of servers) { const button = document.createElement('button'); const players = `${server.currentPlayers ?? '?'} / ${server.maxPlayers ?? '?'}`; const status = server.online ? players : 'Offline'; button.type = 'button'; button.textContent = `${server.name} · ${status}${server.hasPassword ? ' · Password required' : ''}`; button.disabled = !server.online; button.addEventListener('click', () => { void onSelect(server.id).catch(error => showError(String(error))); }); container.append(button); }}Expose actions for fetching and selecting servers through the preload, using
the same IPC pattern as the launcher example.
Keep the latest list in the main process. Its selection handler calls
selectServer(servers, selectedId) to find the chosen entry, then starts
inspection with ['inspect', '--join-code', server.joinCode].
Refresh the list when the launcher opens and provide a Refresh action. If a refresh fails, keep the last list visible and show the failure separately. Clear the selection if that server disappears or goes offline. Render names as text, as the example does.
Use the selected join code
Section titled “Use the selected join code”After selection, pass that entry’s joinCode to inspection. For the example
response above:
.\client-helper.exe inspect --join-code example_01.\client-helper.exe prepare --join-code example_01.\client-helper.exe launch --join-code example_01Run preparation when inspection reports missing files. Enable Play when the installation is ready, following the launcher flow. The helper resolves the join code into connection details, client compatibility and resource metadata.
When selection changes, clear the previous inspection result and inspect the new server. Keep selection disabled while a helper operation is running, so its progress and result stay associated with the server that started it.
A server can become unavailable after the list loads. Display the helper’s error and let the player refresh or choose another server. For a launcher with one fixed server, you can store its join code and use the same helper commands without displaying a list.
Password-protected servers
Section titled “Password-protected servers”When hasPassword is true, ask for the password on Play. Inspection and
preparation work without it. launch checks the password with the game server
before downloading client/resource payloads or starting GTA.
Pass the password in the helper process’s environment and supply the variable
name through --password-env. The following main-process example uses
runHelper from the launcher example,
which accepts a child environment as its optional fifth argument:
// @ts-checkimport { runHelper } from './helper.mjs';
/** * Called in the main process after selecting and preparing the server. * @param {string} executable * @param {import('./server-directory.mjs').Server} server * @param {(event: import('./helper.mjs').HelperEvent) => void} onEvent * @param {string} [password] Omit for a server without a password. */export function launchServer(executable, server, onEvent, password) { const args = ['launch', '--join-code', server.joinCode]; const env = { ...process.env }; delete env.REVO_SERVER_PASSWORD;
if (server.hasPassword || password !== undefined) { if (!password || password.includes('\0') || Buffer.byteLength(password, 'utf8') > 256) { throw new Error('Enter a password of at most 256 UTF-8 bytes'); } env.REVO_SERVER_PASSWORD = password; args.push('--password-env', 'REVO_SERVER_PASSWORD'); }
return runHelper(executable, args, 'launched', onEvent, env);}Read the password from the input without trimming spaces. The limit is 256
UTF-8 bytes. The example creates a separate child environment without changing
process.env. Clear the password field after submitting it and keep its value
out of logs and saved launcher settings.
Handle password_required and invalid_password by reopening the prompt.
For authentication_unavailable, show a retry action. For
server_identity_mismatch, stop the attempt and report the error. The helper
handles authentication, and the password is never sent to the directory API.
Local development
Section titled “Local development”For a server on the same PC, use dev instead of fetching a directory entry:
.\client-helper.exe inspect --join-code dev.\client-helper.exe launch --join-code devThe server must have API registration disabled:
[api]enabled = falselocal_port = 27019dev uses local discovery at 127.0.0.1:27019. If api.local_port is 27119,
use dev:27119. This is the discovery port. The game connection port is read
from the discovery response.
Local servers do not appear in the public directory. A development launcher can provide a separate local-server action that uses this join code. See Set up a development server for the complete configuration.