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.
Health and dirt
Section titled “Health and dirt”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:
// @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,};Full repair
Section titled “Full repair”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:
// @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.
Lights and bumpers
Section titled “Lights and bumpers”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:
stateusesVehicleBumperState.Intact,LooseorDetached.- For
Loose, select aVehicleBumperAxisand abounceScalefrom0to1. - For
IntactandDetached, useVehicleBumperAxis.XandbounceScale: 0.
Assign the complete object to change a bumper. The getter returns a copy. Models without the corresponding bumper have no part to change.
Damage events
Section titled “Damage events”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.
Doors, windows and ramps
Section titled “Doors, windows and ramps”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:
// @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 access
Section titled “Client access”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.