Skip to content

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.

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

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

Terminal window
npm install --save-dev @revomp/types-server @revomp/types-client

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

Save this as resources/first-mod/server/index.js:

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.

Save this as resources/first-mod/client/scripts/client.js:

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.

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.

Start revo-server.exe from the server folder. Its console should show:

[First mod] Server script loaded.

Launch the client from the helper folder:

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

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

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.