Skip to content

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.

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.

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
package.json
{
"name": "launcher-example",
"private": true,
"version": "1.0.0",
"type": "module",
"main": "main.mjs",
"scripts": { "start": "electron ." },
"devDependencies": { "electron": "45.2.3" }
}

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
main.mjs
// @ts-check
import { 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
helper.mjs
// @ts-check
import { 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
preload.cjs
// @ts-check
const { 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);

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
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
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:

Terminal window
npm install
npm start

Keep 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.

Once the player selects a server, show Checking installation… and run:

Terminal window
.\client-helper.exe inspect --join-code YOUR_CODE

For 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:

Terminal window
.\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.

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.

When the player chooses Install, Update or Prepare, run:

Terminal window
.\client-helper.exe prepare --join-code YOUR_CODE

Map 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) / elapsedSeconds

Reset 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.

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.

When the player presses Play, run:

Terminal window
.\client-helper.exe launch --join-code YOUR_CODE

launch 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.

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.