Skip to content

Damage, doors and repairs

Vehicle damage is synchronized, including health, broken parts, tyres, deformation, glass damage and impact decals. Use the server API to apply scripted damage or repairs to a shared vehicle.

These properties are writable on the server:

Property Accepted range Purpose
bodyHealth 0 to 100000 Body health.
engineHealth -4000 to 100000 Engine health. Low values affect engine operation.
petrolTankHealth -1000 to 100000 Fuel tank health.
dirtLevel 0 to 15 Dirt on the vehicle, from clean to fully dirty.

The three health values default to 1000. Assignments outside the accepted range throw an error. Negative engine and tank health can cause fires and explosions in GTA.

Body health and visible deformation are separate. Increasing bodyHealth does not remove dents, restore glass or replace detached parts. Use repair() for a full repair.

This example creates a damaged vehicle with a flat front-left tyre and a detached front bumper:

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.bodyHealth = 600;
vehicle.engineHealth = 350;
vehicle.dirtLevel = 10;
vehicle.setWheelBurst(0, true);
vehicle.frontBumperState = {
state: revo.VehicleBumperState.Detached,
axis: revo.VehicleBumperAxis.X,
bounceScale: 0,
};

Call vehicle.repair() on the server. It restores health values to 1000, repairs damaged parts and clears deformation, impact decals and glass damage. The repaired state also applies to clients that stream the vehicle in later.

Paint, modifications and plate text are retained. Repair preserves the engine’s running state and the vehicle’s dirt level. Set dirtLevel = 0 separately if the service should also clean it:

Server
// @ts-check
/// <reference types="@revomp/types-server" />
import * as revo from 'revo-server';
/** @param {revo.Vehicle} vehicle */
export function repairAndClean(vehicle) {
if (!vehicle.repair()) return false;
vehicle.dirtLevel = 0;
return true;
}

The return value confirms that the server applied the repair. Clients receive it asynchronously. A vehicle can take new damage immediately afterward, so repair does not make it invulnerable.

setWheelBurst(wheel, true) punctures a tyre. Pass a third argument of true to put it on the rim. Use setWheelFixed(wheel) or setWheelBurst(wheel, false) to repair it. isWheelBurst(wheel) and isWheelOnRim(wheel) read the server state.

The server methods accept wheel indices from 0 to 5:

Index Wheel
0 Front left, or the front wheel of a bike.
1 Front right.
2 Middle left, where present.
3 Middle right, where present.
4 Rear left, or the rear wheel of a bike.
5 Rear right.

A typical four-wheel car uses 0, 1, 4 and 5. GTA’s extra native tyre indices 45 and 47 are outside this server API’s range.

The methods reject indices outside the supported range. setWheelBurst() returns false for onRim = true with burst = false. An accepted index can still refer to a wheel absent from the model. Wrong argument types throw an error.

setLightDamaged(light, true) marks a light as damaged. Pass false to repair it, and use isLightDamaged(light) to read its state. Light indices range from 0 to 21, with the visible result depending on the model. Switching the lights on or off uses the separate setLights() method.

frontBumperState and rearBumperState accept an object with state, axis and bounceScale:

  • state uses VehicleBumperState.Intact, Loose or Detached.
  • For Loose, select a VehicleBumperAxis and a bounceScale from 0 to 1.
  • For Intact and Detached, use VehicleBumperAxis.X and bounceScale: 0.

Assign the complete object to change a bumper. The getter returns a copy. Models without the corresponding bumper have no part to change.

These server events report changes to specific parts:

Event Arguments
tyreBurst (vehicle, wheel, source)
tyreFixed (vehicle, wheel, source)
lightDamageChanged (vehicle, light, oldDamaged, newDamaged, source)

source is StateChangeSource.Server for server changes or StateChangeSource.Sync for changes received from simulation. Repairs can also produce these events when they change the corresponding state.

Notifications are queued. Check vehicle.valid before reading its properties inside a handler. healthChanged tracks the inherited health property. Changes to bodyHealth, engineHealth and petrolTankHealth do not trigger this event.

Clients can read brokenDoors and looselyLatchedDoors after the vehicle is ready. These are bitmasks using GTA door indices. For example, (vehicle.brokenDoors & (1 << 4)) !== 0 checks the bonnet damage flag. They do not describe whether an intact door is open.

The server API currently has no setters for individual doors, windows or door locks. Opening a door through a native on one client does not create a shared open/closed setting. For a scripted shared door state, store the desired value in synced metadata and apply it through client scripts on stream-in and metadata changes.

For local display vehicles, a native call is sufficient. This function opens or closes the bonnet of a ready LocalVehicle:

Client
// @ts-check
/// <reference types="@revomp/types-client" />
/// <reference types="@revomp/types-natives" />
import * as revo from 'revo-client';
import { setVehicleDoorOpen, setVehicleDoorShut } from 'natives';
/**
* @param {revo.LocalVehicle} vehicle
* @param {boolean} open
*/
export function setBonnetOpen(vehicle, open) {
if (!vehicle.ready) return false;
const bonnet = 4;
if (open) {
setVehicleDoorOpen(vehicle.scriptId, bonnet, false, false);
} else {
setVehicleDoorShut(vehicle.scriptId, bonnet, false);
}
return true;
}

Use a model with that door. Reapply local display settings after another stream-in.

Supported Cargobob and Avenger cargo ramps have separate synchronization for their target position. The pilot’s ramp control is replicated automatically. This does not add a general server-side door or trailer-ramp API.

Client vehicle health and damage properties are read-only snapshots of the local GTA instance. Read them after the vehicle is ready. Replicas can clamp negative engine and tank health to prevent duplicate fires or explosions, so use server values for game-mode decisions.

The client repair() method is available for a loaded LocalVehicle created by the calling resource. Repair shared vehicles through the server, including when the local player owns their simulation.