Create a custom launcher
Use client-helper.exe to inspect the installation, download updates and start
GTA. Your launcher controls the interface and reads the helper’s JSON events to
update it.
For command arguments and response fields, see the Client helper reference.
Include the helper
Section titled “Include the helper”Get client-helper-<version>-release.zip through your developer access and
include its extracted contents with your launcher. Keep the lib folder beside
client-helper.exe. For the installer layout and updates, see
Package and distribute your launcher.
Start the helper as a child process with a hidden console and redirected stdin, stdout and stderr. Pass the executable path and arguments separately. Keep stdin open while the operation runs.
Stdout contains UTF-8 JSON, one event per line, with protocolVersion: 1.
Buffer incomplete lines before parsing them. Read stderr separately for
diagnostics. This works with any launcher technology that supports child
processes and pipes.
The helper checks for its own updates during inspection, preparation and launch. You can keep starting the copy bundled with your launcher. Update progress and the final result arrive through the same process.
Example with Electron
Section titled “Example with Electron”Let’s assume your launcher uses Electron. Run the helper in the main process
and expose launcher actions through a preload script. The page calls
window.launcher.inspect(), prepare(), pause(), resume() and play(), and
receives progress through onProgress().
This follows Electron’s IPC and context isolation patterns. The example keeps Node access in the main process, validates the calling frame and exposes specific actions through the preload.
Create a folder of your choice with these files. Extract the released helper
package into its helper folder:
launcher/├── package.json├── main.mjs├── helper.mjs├── preload.cjs├── renderer.js├── index.html└── helper/ ├── client-helper.exe └── lib/package.json
{ "name": "launcher-example", "private": true, "version": "1.0.0", "type": "module", "main": "main.mjs", "scripts": { "start": "electron ." }, "devDependencies": { "electron": "45.2.3" }}Connect the buttons to the main process
Section titled “Connect the buttons to the main process”main.mjs handles the folder pickers and helper operations. Inspection checks
the GTA folder first. Resume checks the installation again and prepares any
remaining files. Operations run one at a time.
The join code is dev for a server on the same PC. Change joinCode to use your
server’s code.
main.mjs
// @ts-checkimport { app, BrowserWindow, dialog, ipcMain } from 'electron';import { join } from 'node:path';import { fileURLToPath, pathToFileURL } from 'node:url';import { runHelper } from './helper.mjs';
const directory = fileURLToPath(new URL('.', import.meta.url));const helper = join(app.isPackaged ? process.resourcesPath : directory, 'helper', 'client-helper.exe');const page = join(directory, 'index.html');const joinCode = 'dev'; // Replace with your server's join code.const selection = ['--join-code', joinCode];
app.whenReady().then(async () => { const window = new BrowserWindow({ width: 720, height: 460, webPreferences: { preload: join(directory, 'preload.cjs'), contextIsolation: true, nodeIntegration: false, sandbox: true, }, }); window.webContents.setWindowOpenHandler(() => ({ action: 'deny' })); window.webContents.on('will-navigate', event => event.preventDefault());
let busy = false; let closing = false; /** @type {ReturnType<typeof runHelper> | undefined} */ let task;
/** @param {import('electron').IpcMainInvokeEvent} event */ function checkSender(event) { if (event.sender !== window.webContents || event.senderFrame !== window.webContents.mainFrame || event.senderFrame.url !== pathToFileURL(page).href) { throw new Error('Unknown launcher page'); } }
/** @param {import('./helper.mjs').HelperEvent} event */ function notify(event) { if (!window.isDestroyed()) window.webContents.send('launcher:progress', event); }
/** @param {string[]} args @param {string} successEvent */ async function execute(args, successEvent) { if (closing) throw new Error('Launcher is closing'); notify({ event: 'operation', cancellable: args[0] === 'prepare' || args[0] === 'launch' }); task = runHelper(helper, args, successEvent, notify); try { return await task.result; } finally { task = undefined; } }
async function inspect() { const game = await execute(['game'], 'game'); if (game.event !== 'game') return game; if (game.valid !== true) return { event: 'game_required', path: game.path }; return execute(['inspect', ...selection], 'state'); }
ipcMain.handle('launcher:action', async (event, action) => { checkSender(event); if (busy || closing) throw new Error('An operation is already running'); busy = true; try { switch (action) { case 'inspect': return await inspect(); case 'prepare': return await execute(['prepare', ...selection], 'ready'); case 'resume': { const state = await inspect(); if (state.event !== 'state' || !['download_required', 'preparation_required'].includes(String(state.status))) return state; return await execute(['prepare', ...selection], 'ready'); } case 'launch': return await execute(['launch', ...selection], 'launched'); case 'game': case 'storage': { const choice = await dialog.showOpenDialog(window, { title: action === 'game' ? 'Choose GTA V Legacy' : 'Choose resource storage', properties: ['openDirectory'], }); if (choice.canceled) return { event: 'dismissed' }; const selected = choice.filePaths[0]; const result = action === 'game' ? await execute(['game', '--path', selected], 'game') : await execute(['configure', '--storage-dir', selected], 'configured'); if (result.event === 'error' || result.event === 'cancelled') return result; return await inspect(); } default: throw new Error('Unknown launcher action'); } } finally { busy = false; if (closing) window.destroy(); } });
ipcMain.handle('launcher:pause', event => { checkSender(event); return task?.cancel() ?? false; });
// Keep the helper alive until cancellation or committed startup finishes. window.on('close', event => { if (!busy) return; event.preventDefault(); closing = true; task?.cancel(); }); app.on('window-all-closed', () => app.quit()); await window.loadFile(page);}).catch(error => { console.error(error); app.quit();});helper.mjs starts the process, reads complete JSON lines and checks the final
event against the exit code. Its cancel() method sends the cancellation line
while the operation allows it.
helper.mjs
// @ts-checkimport { spawn } from 'node:child_process';import { dirname } from 'node:path';import { createInterface } from 'node:readline';
/** @typedef {Record<string, unknown> & { event: string }} HelperEvent */
/** * @param {string} executable * @param {string[]} args * @param {string} successEvent * @param {(event: HelperEvent) => void} onEvent * @param {NodeJS.ProcessEnv} [env] */export function runHelper(executable, args, successEvent, onEvent, env = process.env) { const child = spawn(executable, args, { cwd: dirname(executable), env, windowsHide: true, shell: false, stdio: ['pipe', 'pipe', 'pipe'], });
let cancellable = true; let requested = false; let finished = false; /** @type {Error | undefined} */ let failure; /** @type {HelperEvent | undefined} */ let terminal;
child.on('error', error => { failure = error; }); child.stdin.on('error', () => {}); // The process may finish before a cancel write arrives. child.stderr.resume(); child.stdout.setEncoding('utf8'); const lines = createInterface({ input: child.stdout, crlfDelay: Infinity }); const exited = new Promise(resolve => child.once('close', resolve));
const result = (async () => { try { for await (const line of lines) { if (!line.trim()) continue; const event = JSON.parse(line); if (!event || event.protocolVersion !== 1 || typeof event.event !== 'string') { throw new Error('Unsupported helper response'); } if (terminal) throw new Error('Output after the helper result');
if ([successEvent, 'error', 'cancelled'].includes(event.event)) { terminal = event; } else { if (typeof event.cancellable === 'boolean') cancellable = event.cancellable; onEvent(event); } } } catch (error) { failure = error instanceof Error ? error : new Error(String(error)); child.stdin.end(); child.stdout.resume(); }
const code = await exited; finished = true; child.stdin.end(); if (failure) throw failure; if (!terminal) throw new Error('Helper exited without a result');
const expectedCode = terminal.event === 'error' ? 1 : terminal.event === 'cancelled' ? 2 : 0; if (code !== expectedCode) throw new Error('Helper result and exit code disagree'); return terminal; })();
return { result, cancel() { if (!cancellable || requested || terminal || finished || child.stdin.destroyed || child.stdin.writableEnded) return false; requested = true; child.stdin.write('{"command":"cancel"}\n'); return true; }, };}The preload exposes the actions and a progress subscription. The callback receives only the event data. The returned function removes the subscription.
preload.cjs
// @ts-checkconst { contextBridge, ipcRenderer } = require('electron');
/** @param {'inspect'|'prepare'|'resume'|'launch'|'game'|'storage'} action */const invoke = action => ipcRenderer.invoke('launcher:action', action);
const launcher = { inspect: () => invoke('inspect'), prepare: () => invoke('prepare'), resume: () => invoke('resume'), play: () => invoke('launch'), chooseGame: () => invoke('game'), chooseStorage: () => invoke('storage'), pause: () => ipcRenderer.invoke('launcher:pause'), /** @param {(event: import('./helper.mjs').HelperEvent) => void} callback */ onProgress(callback) { /** @param {import('electron').IpcRendererEvent} _event @param {import('./helper.mjs').HelperEvent} data */ const listener = (_event, data) => callback(data); ipcRenderer.on('launcher:progress', listener); return () => { ipcRenderer.removeListener('launcher:progress', listener); }; },};/** @typedef {typeof launcher} LauncherApi */contextBridge.exposeInMainWorld('launcher', launcher);Display installation state and progress
Section titled “Display installation state and progress”The page has a primary action, Pause, Check again and a GTA folder picker. The primary action changes from folder selection to Install / Update, Resume or Play as results arrive. It becomes unavailable while an operation runs.
index.html
<!doctype html><html lang="en"><head> <meta charset="utf-8"> <meta http-equiv="Content-Security-Policy" content="default-src 'self'; script-src 'self'; object-src 'none'; base-uri 'none'"> <title>Launcher example</title> <script src="renderer.js" defer></script></head><body> <h1>Launcher</h1> <p id="status" role="status">Checking installation…</p> <progress id="progress" max="100" hidden></progress> <p id="details"></p> <button id="primary" disabled>Checking…</button> <button id="pause" disabled>Pause</button> <button id="check" disabled>Check again</button> <button id="game" disabled>GTA folder</button></body></html>The renderer updates the progress bar and size label from progress events.
It samples downloadedBytes for the speed display and waits for confirmed
cancellation before offering Resume.
renderer.js
// @ts-check/** @type {import('./preload.cjs').LauncherApi} */const api = Reflect.get(window, 'launcher');const status = /** @type {HTMLParagraphElement} */ (document.getElementById('status'));const details = /** @type {HTMLParagraphElement} */ (document.getElementById('details'));const progress = /** @type {HTMLProgressElement} */ (document.getElementById('progress'));const primary = /** @type {HTMLButtonElement} */ (document.getElementById('primary'));const pause = /** @type {HTMLButtonElement} */ (document.getElementById('pause'));const check = /** @type {HTMLButtonElement} */ (document.getElementById('check'));const game = /** @type {HTMLButtonElement} */ (document.getElementById('game'));
const actions = { inspect: api.inspect, prepare: api.prepare, resume: api.resume, launch: api.play, game: api.chooseGame, storage: api.chooseStorage,};/** @typedef {keyof typeof actions} Action *//** @type {Action} */let nextAction = 'inspect';let busy = false;let cancellable = false;let pausing = false;let running = false;let operation = 0;/** @type {{ content: unknown, at: number, bytes: number } | undefined} */let sample;let speed = '';
/** @param {unknown} value */const mib = value => typeof value === 'number' ? `${(value / 1048576).toFixed(1)} MiB` : 'unknown';
/** @param {string} label @param {Action} action */function button(label, action) { primary.textContent = label; nextAction = action;}
function controls() { primary.disabled = check.disabled = game.disabled = busy || running; pause.disabled = !busy || !cancellable || pausing;}
/** @type {Record<string, string>} */const stages = { client: 'Checking client...', resolving: 'Finding server...', manifest: 'Checking updates...', checking: 'Checking files...', downloading: 'Downloading...', preparing: 'Preparing files...', cleaning: 'Cleaning up...', checking_update: 'Checking helper...', updating_helper: 'Updating helper...', launching: 'Starting GTA...', starting_launcher: 'Starting Rockstar Games Launcher...', waiting_for_game: 'Waiting for GTA...', bootstrapping: 'Initializing client...', authenticating: 'Authenticating...',};
const unsubscribe = api.onProgress(event => { if (event.event === 'operation') { cancellable = event.cancellable === true; sample = undefined; speed = ''; progress.hidden = true; } else if (event.event === 'status') { if (typeof event.cancellable === 'boolean') cancellable = event.cancellable; if (!pausing) status.textContent = stages[String(event.stage)] ?? 'Working...'; progress.hidden = false; progress.removeAttribute('value'); details.textContent = ''; } else if (event.event === 'progress') { if (typeof event.percent === 'number' && Number.isFinite(event.percent)) { progress.hidden = false; progress.value = Math.min(100, Math.max(0, event.percent)); } const now = performance.now(); if (typeof event.downloadedBytes === 'number') { if (!sample || sample.content !== event.content || event.downloadedBytes < sample.bytes) { sample = { content: event.content, at: now, bytes: event.downloadedBytes }; speed = ''; } else if (now - sample.at >= 1000) { speed = `${mib((event.downloadedBytes - sample.bytes) * 1000 / (now - sample.at))}/s`; sample = { content: event.content, at: now, bytes: event.downloadedBytes }; } } else { sample = undefined; speed = ''; } details.textContent = `${event.content}: ${mib(event.completedBytes)} / ${mib(event.totalBytes)} ${speed}`; } controls();});
/** @param {import('./helper.mjs').HelperEvent} result @param {Action} action */function showResult(result, action) { progress.hidden = true; details.textContent = ''; button('Check again', 'inspect'); switch (result.event) { case 'game_required': status.textContent = 'Select your GTA V Legacy folder.'; button('Choose GTA folder', 'game'); break; case 'state': details.textContent = `Download: ${mib(result.downloadBytes)}. Additional disk space: ${mib(result.requiredBytes)}.`; switch (result.status) { case 'storage_required': status.textContent = 'Choose where to store resources.'; details.textContent = ''; button('Choose storage', 'storage'); break; case 'ready': status.textContent = 'Ready to play.'; button('Play', 'launch'); break; case 'download_required': case 'preparation_required': status.textContent = 'Installation needs preparation.'; button(result.status === 'download_required' ? 'Install / Update' : 'Prepare', 'prepare'); break; case 'insufficient_space': status.textContent = 'Free disk space, then check again.'; details.textContent = `Additional space needed: ${mib(result.shortfallBytes)}.`; break; default: status.textContent = `Unknown installation state: ${result.status}`; } break; case 'ready': status.textContent = 'Ready to play.'; button('Play', 'launch'); break; case 'cancelled': status.textContent = 'Paused.'; button('Resume', 'resume'); break; case 'launched': status.textContent = `Client initialized. GTA PID: ${result.gamePid}`; running = true; button('Running', 'inspect'); break; case 'error': status.textContent = `${result.code}: ${result.message}`; if (result.retryable === true) button('Retry', action); break; default: status.textContent = 'Unexpected helper result.'; }}
/** @param {Action} action */async function run(action) { if (busy || running) return; const previous = { status: status.textContent, details: details.textContent }; busy = true; pausing = cancellable = false; ++operation; status.textContent = 'Checking...'; details.textContent = ''; controls(); try { const result = await actions[action](); if (result.event === 'dismissed') { status.textContent = previous.status; details.textContent = previous.details; } else showResult(result, action); } catch (error) { progress.hidden = true; status.textContent = error instanceof Error ? error.message : String(error); button('Check again', 'inspect'); } finally { busy = false; controls(); }}
primary.onclick = () => { void run(nextAction); };check.onclick = () => { void run('inspect'); };game.onclick = () => { void run('game'); };pause.onclick = async () => { const current = operation; pause.disabled = true; try { if (await api.pause() && busy && operation === current) { pausing = true; status.textContent = 'Pausing...'; } } catch (error) { console.error(error); } finally { controls(); }};window.addEventListener('beforeunload', unsubscribe, { once: true });void run('inspect');Run these commands in the example folder:
npm installnpm startKeep the development server running
for dev. Select GTA and resource storage when prompted, then try Install,
Pause, Resume and Play. After startup succeeds, the example displays the GTA
PID and enters its Running state.
Closing the window during preparation requests cancellation and waits for it to finish. After startup becomes non-cancellable, the window waits for the startup result before closing.
For a packaged launcher, include the helper folder as an external resource
beside the packaged application data. The main process uses
process.resourcesPath/helper when app.isPackaged is true. The helper files
must remain accessible as ordinary files outside the ASAR archive.
Inspect before showing the main action
Section titled “Inspect before showing the main action”Once the player selects a server, show Checking installation… and run:
.\client-helper.exe inspect --join-code YOUR_CODEFor a server on the same PC, use dev, as shown in
Run locally.
The final state event contains a status. Use it to choose the next action:
| Status | Launcher action |
|---|---|
storage_required |
Show a folder picker for resource storage. Save the choice with configure, then inspect again. |
download_required |
Show Install or Update, with the estimated download size. |
preparation_required |
Show Prepare. Cached files still need to be assembled or verified. |
insufficient_space |
Show which drive needs space and the reported shortfall. Check again after the player resolves it. |
ready |
Show Play. |
Save the player’s resource folder with:
.\client-helper.exe configure --storage-dir "C:\Revo\client-data"The player can choose another location. Client binaries use
%LOCALAPPDATA%\revo\client separately from resource storage. For moving
existing files and cleaning unused downloads, see
Resource storage and disk management.
Also run client-helper.exe game to display the detected GTA V Legacy path.
If valid is false, ask the player to select the game folder and validate it with
game --path "D:\Games\Grand Theft Auto V". Use game --path auto to restore
registry detection. See GTA folder selection for
unavailable saved paths and validation behavior.
Inspect when opening the launcher, changing servers or retrying a failed check. Keep the main action unavailable until the check finishes. Run one installation operation at a time, including when the player changes servers.
Download size and disk space
Section titled “Download size and disk space”Configured installations report these fields:
| Field | Use in the launcher |
|---|---|
downloadBytes |
Estimated bytes still to download. Compression and cached files are included in the estimate. Resuming partial files can reduce the actual transfer. |
requiredBytes |
Additional disk space needed for cached downloads and prepared files. |
freeBytes |
Available space when the installation uses one volume. |
shortfallBytes |
Additional space needed to proceed, when known. |
clientSpace, resourceSpace |
Separate disk-space details when client files and resources use different volumes. |
With separate volumes, top-level freeBytes is null. Show the per-volume
values. An unknown value should appear as unavailable. Moving resources to
another drive only addresses the resource storage requirement.
Inspection checks manifests, local paths and file sizes. Verify files or
Repair should run prepare, which fully verifies file contents.
Install and show progress
Section titled “Install and show progress”When the player chooses Install, Update or Prepare, run:
.\client-helper.exe prepare --join-code YOUR_CODEMap status.stage to your own localized labels. For example:
| Stage | Display text |
|---|---|
resolving, manifest |
Checking for updates… |
checking |
Checking files… |
downloading |
Downloading… |
preparing |
Preparing files… |
cleaning |
Cleaning up… |
While downloading, a progress event supplies the values for the progress bar.
For example:
{"protocolVersion":1,"event":"progress","content":"resources","path":"maps/city.rpf","completedBytes":52428800,"downloadedBytes":20971520,"totalBytes":104857600,"completedFiles":3,"totalFiles":8,"percent":50}Use percent for the bar and completedBytes / totalBytes for the size label.
content identifies the current download group: helper, client or
resources. Label the group and reset the displayed progress when it changes.
Cached groups can finish without download progress events.
completedBytes includes cached files and resumed data. To display download
speed, use the change in downloadedBytes over elapsed time:
bytesPerSecond = (downloadedBytes - previousDownloadedBytes) / elapsedSecondsReset the speed sample for each operation and download group. Smooth the value
over a few seconds for display. If the helper omits downloadedBytes, hide the
speed indicator. During verification and preparation, show the current stage
with an indeterminate indicator.
A download group reaching 100% can still be followed by verification, preparation
or another group. Keep Play disabled until preparation returns ready and
the helper exits successfully. A partial file that needs to restart can make
progress move backwards.
Pause and resume
Section titled “Pause and resume”Implement Pause by sending this JSON line to the running helper’s stdin, including the final newline:
{"command":"cancel"}Show Pausing… while waiting for the cancelled event and exit code 2.
Then show Paused and enable Resume. Let the helper finish cancelling
before starting another operation.
Downloaded files and partial downloads remain in the cache. On Resume,
inspect again and run prepare if files still need downloading or preparation.
The helper checks the current release and reuses available data automatically.
A host that supports HTTP byte ranges allows partial files to continue from
their saved offsets. If the host ignores the range request, the affected file
starts again from the beginning.
The helper process exits on pause. A resume starts a new operation and repeats its checks. Keep the same storage location and leave the download cache intact. Closing the launcher’s stdin pipe also cancels preparation, so interrupted sessions can use the same recovery flow.
If preparation finishes before cancellation takes effect, handle its successful result normally. If it returns an error, show that error. Only display Paused after confirmed cancellation.
Start the game
Section titled “Start the game”When the player presses Play, run:
.\client-helper.exe launch --join-code YOUR_CODElaunch checks for updates and prepares missing files before starting GTA.
Continue handling progress events during this operation. A separate prepare
is useful for an install or repair action, but is optional when launching.
When a status event contains cancellable: false, disable Pause and
Cancel. Startup has reached the handoff to GTA and continues even if the
launcher’s stdin pipe closes. Show a starting state while waiting for the final
result.
A launched event with exit code 0 confirms that the client has initialized.
It includes gamePid. GTA continues loading and connecting after the helper
exits. Use gamePid to track the game process if the launcher displays a
Running state. See Game launch and process lifecycle
for process tracking and startup failures.
Finish operations and handle failures
Section titled “Finish operations and handle failures”Wait for both the terminal event and process exit before changing the launcher to a completed state:
| Operation | Successful terminal event |
|---|---|
game |
game |
configure |
configured |
inspect |
state |
prepare |
ready |
launch |
launched |
Success uses exit code 0. An error event uses exit code 1 and contains
code, message and retryable. Cancellation uses cancelled and exit code
2. Missing terminal output or a conflicting exit code should produce a
launcher error.
Use error codes for localized messages and retain diagnostic details in the
launcher’s logs. Offer Retry when retryable is true. Errors such as an
invalid game path or insufficient space need the player to resolve the cause
first. If another operation holds the installation lock, cache_busy means
the launcher should wait until that operation finishes before retrying.
Keep these states separate in the interface: checking, downloading, preparing, paused, ready, starting and failed. This gives each button a clear action and prevents a failed check or a completed download from being shown as a successful launch.