Animations
Play a clip
Section titled “Play a clip”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.
// @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.
Timing and flags
Section titled “Timing and flags”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.
Shared peds and ownership
Section titled “Shared peds and ownership”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.
If the clip does not play
Section titled “If the clip does not play”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.