Skip to content

Animations

Animations are started from client scripts through GTA natives. A clip is identified by its animation dictionary and name. Request the dictionary with requestAnimDict() and wait for hasAnimDictLoaded() before taskPlayAnim().

This example creates a local preview, plays a looping idle for five seconds, then removes it. Call showIdlePreview(position, heading) near the current camera and handle a rejected promise if the ped or dictionary fails to load. The heading uses radians.

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 {import('revo-shared').IVector3} position
* @param {number} heading Heading in radians.
*/
export async function showIdlePreview(position, heading) {
const ped = new revo.LocalPed('mp_m_freemode_01', position, heading);
ped.dimension = revo.Player.local.dimension;
const dictionary = 'amb@world_human_hang_out_street@male_b@idle_a';
const clip = 'idle_a';
const looping = 1;
try {
await revo.waitFor(() => ped.ready);
natives.requestAnimDict(dictionary);
await revo.waitFor(() => natives.hasAnimDictLoaded(dictionary));
if (!ped.ready) return;
ped.setBlockingOfNonTemporaryEvents(true);
natives.taskPlayAnim(ped, dictionary, clip, 4, 4, -1, looping, 1, false, false, false);
await revo.wait(5000);
if (ped.ready) natives.stopAnimTask(ped, dictionary, clip, 4);
} finally {
if (ped.valid) ped.destroy();
natives.removeAnimDict(dictionary);
}
}

waitFor() has a five-second timeout by default. The finally block removes the ped and releases the dictionary on both success and failure. After waiting for an asset, check that the target is still ready before using it.

The preview is client-only. A shared NPC can use the same loading and playback calls on its simulation owner. For the local player, pass revo.Player.local to the natives once the player is spawned and ready.

taskPlayAnim() takes the blend-in speed, blend-out speed, duration in milliseconds, flags and playback rate after the dictionary and clip names. The example uses -1 duration and stops the clip explicitly.

Common flags can be combined with bitwise OR:

Flag Value Effect
Looping 1 Repeat the clip.
Hold last frame 2 Keep the final pose.
Upper body 16 Restrict the animation to the upper body.
Secondary task 32 Play it in the secondary task slot.

For example, 1 | 16 | 32 requests a looping upper-body secondary animation. Choose flags that suit the clip. The available flags are listed with TASK_PLAY_ANIM.

Use stopAnimTask(ped, dictionary, clip, blendOutSpeed) to stop that clip. Use a positive blend-out speed, as described by STOP_ANIM_TASK. Clearing all ped tasks can also interrupt navigation, aiming or vehicle entry. Issue a playback command when the action changes. Reissuing it every frame can continually restart the animation.

Walking, running, aiming, post-shot weapon stance, stealth, ragdolls and parachute state are synchronized. Scripted clips use the game’s supported task replication. Check the chosen clip and flags from another client, including after stream-in and ownership changes.

Start a shared NPC’s tasks on the client where isLocallySimulated is true. During dictionary loading the ped can lose ownership or be recreated. Before starting playback, check readiness, ownership and whether the requested action is still current. A cancelled or replaced action must not start when its old loading request finishes.

For an action that must survive handoff, store its dictionary, clip and options in server metadata and apply it through the events shown in NPCs and scripted behavior. Reset pending work on entityStreamOut. Store a revision with the action if multiple requests can overlap. A new owner restarts the instruction, so exact progress through an arbitrary clip is not retained by that pattern.

For a one-shot action, clear the stored instruction when the action ends so returning observers or future owners do not start it again. Any gameplay result, such as awarding an item, belongs to the server’s validated action flow.

Check the dictionary and clip names, model compatibility, loading result and whether another task immediately replaces it. For custom dictionaries, follow Additional asset types.

A seated, dead or ragdolling ped can reject or interrupt an incompatible task. Test the state your action permits instead of clearing the ped’s tasks every frame. Use the ownership guide when behavior stops only after another client takes over.