Moving entities and attaching props
Shared objects and local props
Section titled “Shared objects and local 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.
Position, rotation and velocity
Section titled “Position, rotation and velocity”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:
// @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.
Physics and visibility
Section titled “Physics and visibility”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.
Synchronized attachments
Section titled “Synchronized attachments”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.
// @ts-checkimport * 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.
Attach a local prop
Section titled “Attach a local prop”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:
// @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.