Skip to content

Client helper reference

The current protocol version is 1. For an Electron integration and the player-facing flow, see Create a custom launcher.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.