Skip to content

Spawning and respawning

playerConnected runs after the handshake. From this point, the server can call player.spawn(position, heading). A mod with character selection can wait until the player chooses a character, apply its model and appearance, then spawn it. Keep that flow separate from loading-screen completion.

The position uses metres and heading uses radians. spawn() returns true when the server accepts the spawn. Invalid argument types throw, and calling it before the handshake or after disconnect is rejected.

The call restores health to maxHealth, clears death, zeroes linear and angular velocity and resets pitch and roll. It also releases the player’s vehicle seat. The selected model, appearance, inventory, armour and dimension remain in place. Set the properties your respawn rules should change explicitly.

Event or property Meaning
Server playerSpawned(player, position) The server committed the spawn. The position is the one used by that spawn.
Client playerSpawned() The local player’s spawn has been applied.
Client Player.local.isSpawned Whether the local player has spawned.
Client Player.local.ready Whether the GTA instance and initial network state are ready.

The server notification can arrive while the client is still loading. Client script listeners should be registered before using a custom readiness exchange. Use entityStreamIn for other players becoming available to an observer. Streaming and readiness covers those events.

The client Player object survives respawns and model changes. Reacquire GTA handles and recreate attachments tied to the previous ped instance.

Automatic respawning is controlled by the mod. This server example spawns new players and respawns them five seconds after death. Run it as the mod’s spawn handler, without also registering the initial spawn example from another guide:

Server
// @ts-check
/// <reference types="@revomp/types-server" />
/// <reference types="node" />
import * as revo from 'revo-server';
import { setTimeout, clearTimeout } from 'node:timers';
const spawnPoint = { x: -1223, y: -1768, z: 3.1 };
/** @type {Map<revo.Player, ReturnType<typeof setTimeout>>} */
const pending = new Map();
/** @param {revo.Player} player */
function cancelRespawn(player) {
const timer = pending.get(player);
if (timer !== undefined) clearTimeout(timer);
pending.delete(player);
}
revo.on('playerConnected', player => {
player.modelHash = 'mp_m_freemode_01';
player.maxHealth = 200;
if (!player.spawn(spawnPoint, 0)) revo.log(`Spawn rejected for player ${player.id}`);
});
revo.on('playerDied', player => {
if (!player.valid || !player.dead) return;
cancelRespawn(player);
pending.set(player, setTimeout(() => {
pending.delete(player);
if (!player.valid || !player.dead) return;
player.armour = 0;
if (!player.spawn(spawnPoint, 0)) revo.log(`Respawn rejected for player ${player.id}`);
}, 5000));
});
revo.on('playerSpawned', cancelRespawn);
revo.on('playerDisconnected', cancelRespawn);
revo.on('serverStop', () => {
for (const timer of pending.values()) clearTimeout(timer);
pending.clear();
});

The timer keeps the Player reference and checks it again before spawning. It is cancelled on disconnect, another spawn or server shutdown. Using the reference avoids accidentally targeting another player if an ID is reused. The example resets armour to zero and retains the player’s weapon inventory. Call removeAllWeapons() if death should clear the inventory.

After playerDied, assigning positive health is rejected. Use spawn() to revive the player. For healing a living player, see Health and damage.

After awaiting character data, check player.valid before applying it. If the player can change their selection while loading, also check that the result still belongs to the current selection. Apply the model, dimension and saved appearance before spawning.

playerDisconnected runs while the player is still valid. Copy the values needed for saving during that callback, before awaiting a database write. After the callback the object becomes invalid. Clear timers and remove mod-owned entities whose lifetime belongs to that connection, such as a temporary test vehicle or preview NPC. Shared world entities can remain.

For server-wide saving during shutdown, use the server lifecycle guide.