Create your first game mode
This example uses JavaScript to spawn a player on the beach and exchange a message between the client and server. Start with the server and helper configured in Run locally.
1. Create the files
Section titled “1. Create the files”Close GTA and stop the server for this initial switch from freeroam. Removing freeroam’s native assets from the loaded game requires a fresh session.
Create resources/first-mod inside the server folder:
server/ revo-server.exe config.toml resources/ first-mod/ package.json server/ index.js client/ scripts/ client.jsIn resources/first-mod/package.json, enable ES modules:
{ "private": true, "type": "module"}The examples below run without a build step. Revo provides the revo-server and
revo-client modules at runtime.
Editor types for JavaScript
For completion and type checking, install the declarations from npm in
resources/first-mod:
npm install --save-dev @revomp/types-server @revomp/types-clientThis requires Node.js with npm on your development PC. The declaration packages are development dependencies. The reference at the top of each example selects its API types. For TypeScript configuration and builds, see TypeScript setup.
2. Add the server script
Section titled “2. Add the server script”Save this as resources/first-mod/server/index.js:
// @ts-check/// <reference types="@revomp/types-server" />import * as revo from 'revo-server';
const spawnPosition = { x: -1225.6, y: -1768.9, z: 3.9 };
revo.on('playerConnected', (player) => { player.modelHash = 'mp_m_freemode_01';
if (!player.spawn(spawnPosition, 0)) { revo.log(`[First mod] Could not spawn player ${player.id}.`); }});
revo.onClient('hello:message', (player, message) => { if (typeof message !== 'string' || message.length > 120) return;
revo.log(`[First mod] Player ${player.id}: ${message}`); revo.emitClient(player, 'hello:reply', 'Hello from the server!');});
revo.log('[First mod] Server script loaded.');playerConnected runs after the connection handshake, when player.spawn() is
available. The second spawn argument is the heading in radians.
onClient receives the sender as its first argument. Revo supplies this Player
from the connection. The remaining arguments come from the client, so the handler
checks the message before using it. emitClient sends the reply to that player.
3. Add the client script
Section titled “3. Add the client script”Save this as resources/first-mod/client/scripts/client.js:
// @ts-check/// <reference types="@revomp/types-client" />import * as revo from 'revo-client';
revo.onServer('hello:reply', (message) => { revo.log(`[First mod] ${message}`);});
revo.log('[First mod] Client script loaded.');revo.emitServer('hello:message', 'Hello from the client!');The client loads scripts/client.js from the resource bundle after connecting.
It registers the reply handler before sending its message. This also tells the
server that the handler is ready. Client scripts may still be loading
when playerConnected runs on the server.
hello:message and hello:reply are custom event names. Use the same names on both
sides. onClient and onServer receive network events, while on handles local
events such as playerConnected.
4. Select the mod
Section titled “4. Select the mod”In the existing config.toml, change these two settings. Keep the other settings
from the development server guide:
[scripting.js]entry = "resources/first-mod/server/index.js"
[resources.pack]path = "resources/first-mod/client"Update the existing sections to avoid duplicate TOML tables. Only the
client folder is packaged for players. The server script and npm dependencies
stay outside that folder. The freeroam files can remain in place.
5. Run it
Section titled “5. Run it”Start revo-server.exe from the server folder. Its console should show:
[First mod] Server script loaded.Launch the client from the helper folder:
.\client-helper.exe launch --join-code devYour player should appear on the beach. The server console should then contain
Hello from the client! alongside the player’s ID.
Press F2 in GTA to open the console. It should contain:
[First mod] Client script loaded.[First mod] Hello from the server!The in-game console requires console = true under [client_features] in the
server configuration. It is enabled by default. The same messages are written to
the client runtime log.
After editing either script, restart the server and reconnect. The client downloads the updated bundle and reloads its scripts during reconnect. GTA can stay open.
Changes to some native assets or game metadata require a full GTA restart. The client reports when this is needed.
Common issues
Section titled “Common issues”| Symptom | Check |
|---|---|
| Freeroam still loads | Check both paths in step 4 and restart the server. |
The server cannot use import |
Check that resources/first-mod/package.json contains "type": "module". |
| No client script message | Check that the client entry is named scripts/client.js relative to the folder being packaged. Reconnect after restarting the server. |
| The server receives the message but no reply appears | Check that both scripts use hello:reply and that the client registers its handler before sending. |
For death handling and delayed respawns, see Spawning and respawning.