Game launch and process lifecycle
Start GTA through the helper with the selected server’s join code:
.\client-helper.exe launch --join-code YOUR_CODEThe helper checks requirements and prepares files before starting the game. Keep handling download progress during launch. Password handling is covered in Server selection and join codes.
Show startup stages
Section titled “Show startup stages”After preparation, status events describe startup:
stage |
Suggested display |
|---|---|
launching |
Starting game |
starting_launcher |
Starting Rockstar Games Launcher |
waiting_for_game |
Waiting for GTA |
bootstrapping |
Initializing client |
These stages have no percentage. Show an indeterminate indicator and keep the latest status visible. Rockstar Games Launcher may restart during an update, so a stage can appear again.
At cancellable: false, disable cancellation and keep reading until the helper
finishes. If the player closes your launcher during this stage, defer closing
its helper process until the result arrives. The
Electron example
already handles this boundary.
Track the game after startup
Section titled “Track the game after startup”A successful launched event includes gamePid, the Windows process ID of GTA.
Wait for that event and helper exit code 0 before showing Running.
Client initialization has completed at this point. Loading the world and
connecting to the server continue inside GTA.
The helper process then exits. It sends no later game-exit or connection events. To keep a launcher open while playing:
- Start monitoring the process identified by
gamePidwhenlaunchedarrives. - Keep Play disabled while that process runs.
- When it exits, inspect the selected server again and update the available action.
Use a Windows process handle to track the process through its lifetime. If your integration polls instead, track its creation time as well as its PID because Windows can reuse process IDs. A process that has already exited should return the launcher to inspection. Treat monitoring failures separately from a confirmed game exit.
In Electron, keep process monitoring in the main process and send state updates
to the renderer. The child-process exit event for client-helper.exe only
completes the helper operation. Use the returned gamePid for GTA’s lifetime.
After a successful launch, your launcher can also close while GTA continues running.
Handle startup failures
Section titled “Handle startup failures”| Error | Launcher action |
|---|---|
game_start_timeout |
Ask the player to finish any Rockstar Games Launcher update or sign-in, then retry. The wait for GTA to start is limited to five minutes. |
client_startup_failed |
Show the error and offer to open the client log folder. Initialization has a two-minute limit, and a failed startup closes that GTA process. |
game_executable_running |
Ask the player to close running GTA clients, then retry. An executable or supporting library needs updating. |
release_client_running |
Ask the player to close the conflicting client before starting a public-server session. |
launch_protocol_error |
Retain the helper output for diagnostics and check that the client installation is current. |
Client runtime logs are under <storage>\projects\<projectId>\logs, named
revo-client-runtime-<session>.log. Use storagePath and projectId from
inspection to locate the folder. Keep the terminal error’s message and
available details with the launcher’s own logs.
Run multiple clients for local testing
Section titled “Run multiple clients for local testing”Release clients support concurrent sessions through dev or dev:PORT on
the same PC. Run the command again after the first launch finishes:
.\client-helper.exe launch --join-code devProfiles are assigned automatically and downloaded resources are shared.
Each successful launch returns its own gamePid. A launcher offering this
workflow can track each process separately and provide Launch another client.
A Release client connecting through a public join code requires other Release clients to be closed. A server’s development flag does not change this rule. Debug client builds allow concurrent connections to any server.
For WebView debugging in both clients, assign a different --cef-debug-port
to each launch as described in CEF debugging.
The server must enable the debugger.