Skip to content

Moving entities and attaching props

Create a shared object on the server with new revo.Object(model, position, rotation, dynamic). The model accepts a name or hash. The final argument defaults to true for dynamic physics. Use false for a fixed object.

Use new revo.LocalObject(model, position, rotation, dynamic) on the client for local scenery or an attached visual prop. Its creating resource controls it and removes it when the script stops. Call destroy() to remove it sooner. Server objects are removed with destroy() on the server.

Constructors return before clients finish loading the model. Use the streaming events when a client needs the GTA instance. See custom objects for asset registration, NPCs for peds and vehicle creation for vehicles.

These properties apply to peds, vehicles and objects:

Property Value
pos World position in metres.
rot XYZ Euler angles in radians, applied X, then Y, then Z.
quaternion Quaternion rotation as { x, y, z, w }.
velocity Linear velocity in metres per second.
angVelocity Angular velocity in radians per second.

Getters return copies. Change a copy and assign it back, or assign a complete new value. entity.pos.z += 1 only changes the returned vector. On the server, quaternion assignments require a unit quaternion. Constructors also accept a numeric heading for rotation. Native angle parameters often use degrees, so check the called native before passing a wrapper’s rotation.

Set server-created entities through their server properties. On the client, transforms can be changed on the resource’s local entities, including before stream-in. Player.local.pos and heading are also writable. Other physical setters require a loaded local entity. Network ownership does not grant write access to the client wrapper’s server-controlled properties.

The following example provides a repositioning function and creates a moving beach ball. Choose a clear position above the ground for the ball:

Server
// @ts-check
/// <reference types="@revomp/types-server" />
import * as revo from 'revo-server';
/**
* @param {revo.Physical} entity
* @param {import('revo-shared').IVector3} position
* @param {number} heading Heading in radians.
*/
export function reposition(entity, position, heading) {
if (!entity.valid) return;
entity.velocity = { x: 0, y: 0, z: 0 };
entity.angVelocity = { x: 0, y: 0, z: 0 };
entity.pos = position;
entity.rot = { x: 0, y: 0, z: heading };
}
const ball = new revo.Object('prop_beachball_02', { x: -1223, y: -1768, z: 4 }, 0, true);
ball.velocity = { x: 2, y: 0, z: 1 };
revo.on('serverStop', () => {
if (ball.valid) ball.destroy();
});

Changing position or rotation preserves velocity unless it is set separately. The function resets both velocities for a stationary result. These are separate property assignments. For ordinary movement, let the simulation owner run the physics or ped task. Repeated position assignments can cause corrections and reset ped tasks.

Server collisionEnabled and visible are independent settings. Hiding an entity leaves its collision setting unchanged. Disabling collision can let a dynamic entity fall through the ground.

physicsAsleep reports whether an object is at rest. A server object’s activatePhysics() wakes a dynamic object and returns false for a fixed one. Changing a dynamic object’s transform or velocity also wakes it. Physics runs on the simulation owner.

For fade effects, objects expose alpha from 0 to 255 on the server. Local objects use setAppearance(alpha, textureVariation, lodDistance) after loading. Transparency does not change collision or streaming range.

Call entity.attachTo(parent, options) on the server to attach a ped, player, vehicle or object. The parent and child must be in the same dimension. Clients apply the attachment once both models are loaded and restore it after streaming.

Server
// @ts-check
import * as revo from 'revo-server';
/** @param {revo.Ped} ped */
export function attachCup(ped) {
const cup = new revo.Object('prop_cs_paper_cup', ped.pos, 0, false);
cup.dimension = ped.dimension;
const attached = cup.attachTo(ped, {
bone: 'SKEL_R_Hand', // Bone ID 57005 also works.
offset: { x: 0.08, y: 0.02, z: -0.02 },
rotation: { x: 0, y: 0, z: 0 },
});
if (!attached) {
cup.destroy();
return null;
}
// Call cup.detach() to keep the object, or cup.destroy() to remove it.
return cup;
}

bone selects a bone on the parent. ownBone selects a bone on the entity being attached. Both accept a name such as SKEL_R_Hand or an integer bone ID from 0 to 65535. The right hand also accepts 57005 (0xDEAD). Each selector is resolved against its entity’s loaded model. An omitted or unavailable bone uses that entity’s origin.

offset places the child’s attachment point in metres relative to the parent or its selected bone. For example, if a custom prop has a grip bone, pass ownBone: 'grip' to place that grip at the requested offset. rotation uses radians, matching rot. Both offset and rotation default to zero. Adjust them for your models. collision enables collision between the parent and child and defaults to false.

attachedTo returns the parent or null. Call detach() to keep the child at its last synchronized world transform. Destroying the parent also detaches its children. Parent teleports and dimension changes move the attached hierarchy. Setting the child’s transform, velocity or dimension detaches it.

attachTo() returns false for a cycle, a hierarchy deeper than 32, a ped in a vehicle, or an occupied or coupled vehicle. Detach before using an attached entity with vehicle seats or towing. See vehicle attachments for trailer and tow-truck connections.

Use a local object and attachEntityToEntity() for an accessory rendered on a client. This example attaches a cup to a loaded ped and returns a cleanup function. Call it when the action starts, and call the returned function when the cup should disappear. Stream-out and disconnect also remove the cup:

Client
// @ts-check
/// <reference types="@revomp/types-client" />
/// <reference types="@revomp/types-natives" />
import * as revo from 'revo-client';
import * as natives from 'natives';
/** @param {revo.Ped} ped */
export async function attachCup(ped) {
if (!ped.ready) throw new Error('The ped must be loaded before attaching a cup.');
const cup = new revo.LocalObject('prop_cs_paper_cup', ped.pos, 0, false);
cup.dimension = ped.dimension;
let removed = false;
function remove() {
if (removed) return;
removed = true;
revo.off('entityStreamOut', onStreamOut);
revo.off('disconnected', remove);
if (cup.valid) cup.destroy();
}
/** @param {revo.Entity} entity */
function onStreamOut(entity) {
if (entity === ped || entity === cup) remove();
}
revo.on('entityStreamOut', onStreamOut);
revo.on('disconnected', remove);
try {
await revo.waitFor(() => removed || cup.ready);
if (removed || !ped.ready) {
remove();
return remove;
}
const bone = natives.getPedBoneIndex(ped, revo.PedBone.SkelRHand);
natives.attachEntityToEntity(
cup, ped, bone,
0.08, 0.02, -0.02, 0, 0, 0,
false, false, false, false, 2, true, 0,
);
return remove;
} catch (error) {
remove();
throw error;
}
}

Adjust the offsets for the prop and ped model. The example disables collision between the cup and the ped. A PedBone value is a bone ID. Resolve it with getPedBoneIndex() for the loaded model before attaching. Damage’s PedBodyPart values describe hit components and serve a separate purpose. See the attachment native for the remaining parameters.