Client helper reference
The current protocol version is 1. For an Electron integration and the
player-facing flow, see Create a custom launcher.
Commands
Section titled “Commands”Start a new client-helper.exe process for each command. Arguments follow the
command as separate name/value pairs. Optional arguments appear in brackets
below. Paths must be absolute.
Installation and launch
Section titled “Installation and launch”| Command | Successful result | Behavior |
|---|---|---|
inspect --join-code CODE |
state |
Check the selected server’s client and resource requirements against the installation. |
prepare --join-code CODE |
ready |
Download, fully verify and prepare files. Also used for repair. |
launch --join-code CODE |
launched |
Check for updates, prepare files and start GTA. |
configure --storage-dir PATH |
configured |
Save a writable resource storage path. Existing files stay in their previous location. |
game [--path PATH] |
game |
Inspect the GTA V Legacy location, or validate and save a selected folder. --path auto restores registry detection. |
diagnostics [--crash-reports true/false] |
diagnostics |
Read or change the crash-reporting preference. Pass either true or false as the value. |
inspect, prepare and launch require a join code. Use dev for the local
development server or dev:PORT for a custom local discovery port.
Additional launch arguments:
| Argument | Value |
|---|---|
--password-env NAME |
Name of a variable in the helper process’s environment containing the server password. |
--cef-debug-port PORT |
Per-launch CEF debugger port, from 1024 to 65535. The server must enable the debugger. See CEF debugging. |
For protected servers, supply the password through the child process’s
environment and pass its variable name in the arguments. inspect and
prepare work without a password. Keep passwords out of arguments and logs.
Storage maintenance and helper updates
Section titled “Storage maintenance and helper updates”| Command | Successful result | Behavior |
|---|---|---|
cleanup |
cleaned |
Remove eligible unused bundles and cached files. |
move --path PATH |
moved |
Move resource storage and its associated data to an empty destination, then save the new path. |
remove-project --project-id UUID |
project_removed |
Remove the specified project’s known resource bundles and unneeded cached files. Settings, logs and crash dumps remain. |
info |
info |
Read helper information offline. |
update |
updated |
Check for a helper update and fully verify its files. |
Storage maintenance uses the saved resource location. Running clients or other helper operations can hold files or installation locks. A conflict is reported as an error.
Reading events
Section titled “Reading events”Stdout contains UTF-8 JSON objects separated by newlines. Every event contains:
| Field | Type | Meaning |
|---|---|---|
protocolVersion |
integer | Version of the helper’s event protocol, currently 1. |
event |
string | Event name. |
A process read can contain part of a JSON line, several lines, or part of a UTF-8 character. Decode the stream incrementally and parse complete lines. Read stderr separately from the JSON stream.
Each invocation produces one terminal event. The successful event depends on
the command in the tables above. error and cancelled are terminal for any
command. Wait for process exit as well as the terminal event:
| Result | Exit code |
|---|---|
| Successful command | 0 |
error |
1 |
cancelled |
2 |
Report a protocol failure if the result and exit code disagree, the terminal
event is missing, or another event follows it. launch returns launched
directly when startup succeeds.
Progress events
Section titled “Progress events”status
Section titled “status”| Field | Type | Meaning |
|---|---|---|
stage |
string | Current operation stage. |
content |
optional string | Content group associated with the stage. |
cancellable |
optional boolean | Whether cancellation is currently available. |
Stages include checking_update, updating_helper, update_unavailable,
client, resolving, manifest, checking, downloading, preparing,
cleaning, moving, activating_storage, removing_project, authenticating,
launching, starting_launcher, waiting_for_game and bootstrapping.
Translate known stages into display text and use a generic working state for
unrecognized stages. When cancellable is absent, preserve the last known
value for the current operation. update_unavailable can be followed by normal
operation events. Use the terminal result to determine success or failure.
progress
Section titled “progress”| Field | Type | Meaning |
|---|---|---|
content |
string | helper, client or resources for downloads, or storage for a move. |
completedBytes |
integer | Bytes completed, including reused content. |
totalBytes |
integer | Total for the current content group. |
percent |
number | Progress percentage for that group. |
downloadedBytes |
optional integer | Bytes received over the network during this group’s preparation, including retransfers. |
path |
optional string | File associated with a download update. |
completedFiles, totalFiles |
optional integers | File progress for downloads. |
Storage moves report byte progress without download-specific fields.
Download totalBytes uses hosted sizes, including compression. Inspection’s
totalBytes describes installed file sizes.
Use downloadedBytes for network speed. Group changes, cached content and
resumed downloads affect the progress display as described in
Install and show progress.
cleanup
Section titled “cleanup”Automatic cleanup can emit removedBytes, removedFiles, removedBundles
and retainedBundles, or an error object with code and message if cleanup
could not finish. This event can occur during preparation. Continue reading
until the command’s terminal result.
Installation results
Section titled “Installation results”status is one of storage_required, download_required,
preparation_required, insufficient_space or ready.
Before storage is configured, the result contains only the common event fields,
status and clientStoragePath:
{"protocolVersion":1,"event":"state","status":"storage_required","clientStoragePath":"C:/Users/Player/AppData/Local/revo/client"}Once storage is configured, the result includes:
| Fields | Type | Meaning |
|---|---|---|
joinCode, serverId, projectId |
strings | Selected server identity. |
dev, hasPassword |
booleans | Server development and password flags. |
storagePath, clientStoragePath |
strings | Resource and shared client storage paths. |
resourceId, resourcePath, manifestSha256 |
string or null |
Resource bundle information, when available. |
downloadBytes |
integer | Estimated remaining transfer size. |
client, resources |
objects | Inspection results for each bundle. |
Both bundle objects contain ready, totalBytes, downloadBytes and
requiredBytes. client also contains version and path, each a string or
null. Its path becomes available when the client bundle is ready.
Disk-space fields appear at the top level:
| Field | Type | Meaning |
|---|---|---|
requiredBytes |
integer | Additional space required, including the reserve. |
reserveBytes |
integer | Reserve already included in requiredBytes. |
freeBytes |
integer or null |
Available space on a single volume, when known. |
sufficientSpace |
boolean or null |
Whether available space meets the requirement. null means the check could not establish it. |
shortfallBytes |
integer or null |
Missing space, 0 when sufficient, or null when unknown. |
When client files and resources use separate volumes, clientSpace and
resourceSpace contain these fields for each volume. Top-level requirements
are summed, freeBytes is null, and sufficientSpace is false if either
volume lacks space. It is null if one volume is unknown and neither is known
to lack space.
The requiredBytes inside each bundle object describes its files. The disk-space
objects add the reserve. Use the disk-space objects for installation decisions.
ready and launched
Section titled “ready and launched”Both include server identity, dev, hasPassword and resource bundle fields
from state, plus:
| Fields | Type | Meaning |
|---|---|---|
clientPath |
string | Prepared client directory. |
clientVersion |
string or null |
Selected client version, when available. |
dataPath, configPath |
strings | Client data directory and configuration file. |
storagePath, clientStoragePath |
strings | Resource and shared client storage paths. |
launched also contains the positive integer gamePid. It confirms client
initialization. Game loading and connection continue afterward.
For a server with no resource bundle, prepare returns null resource fields.
launch prepares an empty bundle, so resourceId and resourcePath are
populated while manifestSha256 remains null.
Other results
Section titled “Other results”| Event | Fields |
|---|---|
configured |
storagePath, clientStoragePath as strings. |
game |
path as a string or null, source as registry, custom or none, and valid as a boolean. |
diagnostics |
crashReports as a boolean. |
cleaned |
Integer removedBytes, removedFiles, removedBundles and retainedBundles. |
moved |
String storagePath and previousPath, integer copiedBytes, boolean sourceCleanupPending. |
project_removed |
String projectId, integer removedBytes, removedFiles and removedBundles. |
info, updated |
String configuration, executable and sha256, integer updateVersion. |
After moved, the new storage path is active. sourceCleanupPending: true
means some data remains at the previous path.
updateVersion identifies the helper update revision. Use protocolVersion
to select the event parser.
Errors and cancellation
Section titled “Errors and cancellation”An error result contains code, message, retryable and optional details.
For disk-space errors, details can contain the disk-space fields listed above.
For example:
{"protocolVersion":1,"event":"error","code":"cache_busy","message":"Another operation is using this installation","retryable":true}Use code for localized handling. retryable: true allows another attempt once
the cause has cleared. Keep a generic failure path for unknown codes.
To cancel, send {"command":"cancel"} followed by a newline to stdin. Keep
reading until the result and process exit. Once cancellable: false arrives,
startup or storage activation continues to its result. The
Pause and resume section describes
how to present cancellation in the launcher.
Compatibility
Section titled “Compatibility”Check protocolVersion before interpreting an event. A different version
requires an updated integration. Within the supported version, accept extra
fields and tolerate unfamiliar progress events and stage names.
Validate the fields used by the current action. A missing optional field keeps that part of the interface unavailable. An unknown terminal result must leave the action unsuccessful until the integration supports it.
Helper updates forward events through the original process. Apply the same version checks throughout the operation, including events emitted after an update.