Skip to content

Creating and configuring vehicles

Create a shared vehicle through the server’s Vehicle constructor. Use LocalVehicle in client scripts to create vehicles that are not synchronized with other players.

This server example creates a Sultan near the beach spawn and sets its plate, paint and engine state:

Server
// @ts-check
/// <reference types="@revomp/types-server" />
import * as revo from 'revo-server';
const vehicle = new revo.Vehicle(
'sultan',
{ x: -1220, y: -1765, z: 3.9 },
Math.PI / 2,
);
vehicle.numberPlate = 'REVO';
vehicle.primaryColor = { r: 30, g: 90, b: 160 };
vehicle.secondaryColor = 0;
vehicle.engineRunning = false;

The constructor returns the server object immediately. You can configure it without waiting for a client to load it. Players receive its current state when it enters their stream, including players who connect later.

Argument Accepted value
model A model name such as 'sultan', or a nonzero unsigned 32-bit model hash. Names are case-insensitive for ASCII letters.
position World coordinates { x, y, z } in metres.
rotation A heading in radians, XYZ Euler angles in radians, or a unit quaternion. The server constructor defaults to zero heading when omitted.

For example, Math.PI / 2 is a 90-degree heading. Use a vehicle model available to the clients. A valid server object does not confirm that GTA has loaded the model or that the model exists in the client’s game data.

The supplied position is the spawn position. Choose its height for the intended surface, with enough space for the vehicle.

These server properties can be set at creation time or changed later:

Property Use
pos, rot, quaternion Reposition or rotate the vehicle. Rotations use radians or a unit quaternion.
dimension Select the world in which the vehicle is visible. Defaults to 0.
modelHash Assign another vehicle model by name or hash. Clients load the replacement asynchronously.
engineRunning Set the engine’s running state.
visible Control whether the vehicle is rendered.
collisionEnabled Control collision separately from visibility.
numberPlate Set up to eight ASCII letters, digits or spaces. Letters become uppercase. An empty string blanks the plate.
primaryColor, secondaryColor Use a GTA color ID from 0 to 160 or { r, g, b } with integer channels from 0 to 255.

The plate reads as null until the server sets one. In that state, GTA supplies the original plate. Assigning a color ID replaces any custom RGB color.

Vector getters return copies. Assign the property to apply a change, for example vehicle.pos = { x: -1230, y: -1765, z: 3.9 }. Editing vehicle.pos.x alone does not move it.

Use position assignments for deliberate moves such as a teleport. Normal driving is synchronized through the simulation owner. Repeatedly assigning positions from the server interferes with that movement. See Synchronization.

The shared vehicle appears on clients according to distance, dimension and streaming capacity. Its server ID becomes the client’s networkId. Use Vehicle.getByNetworkId(serverId) to resolve it on a client.

Client work that needs the GTA instance belongs in entityStreamIn, or after a ready check for an existing reference. A replacement model can produce a new stream-in, so repeat any setup tied to the GTA instance. See Streaming and readiness.

Make shared vehicle property changes through the server API. Client setters apply to the creating resource’s local vehicles. Being the network owner does not grant permission to use those setters on a server-created vehicle.

This client example creates a separate display car and turns off its engine and radio each time it streams in:

Client
// @ts-check
/// <reference types="@revomp/types-client" />
import * as revo from 'revo-client';
const displayCar = new revo.LocalVehicle(
'sultan',
{ x: -1212, y: -1765, z: 3.9 },
Math.PI / 2,
);
displayCar.streamDistance = 80;
revo.on('entityStreamIn', (entity) => {
if (entity !== displayCar) return;
displayCar.engineRunning = false;
displayCar.radioStation = 0;
});

LocalVehicle requires the rotation argument. Pass 0 for zero heading. Its networkId is null, and other clients do not receive it.

Position, rotation, dimension and streaming settings can be assigned before stream-in. Settings such as engineRunning, radioStation and livery require the loaded GTA instance. The handler above applies them after each stream-in, including when the car returns after streaming out.

Local and server vehicle APIs expose different writable properties. Server paint and plate setters are not part of LocalVehicle. For local customization through GTA natives, use the vehicle’s current scriptId after it is ready.

Call vehicle.destroy() on the server to remove a shared vehicle. Dropping its JavaScript reference does not remove it from the world.

Destroy a local vehicle from the client resource that created it. Local vehicles are also removed when that resource stops.

Calling destroy() on an already destroyed vehicle throws. If another callback may have removed it, check valid before cleanup. Stream-out alone does not destroy the server vehicle. See Entity IDs and game handles for reference lifetime and ID reuse.

Vehicle (server), Vehicle (client), LocalVehicle (client).