Client API

Animations & Scenarios

One call to load the dict and play — no more RequestAnimDict boilerplate scattered through every script. Covers one-shot anims, looping anims, world-position anims, and RDR2 scenarios.

PlayAnim(ped, dict, clip, opts)client

Loads the animation dictionary then plays the clip on ped. Returns true if the animation started.

Param	Type	Description
ped	number	Entity handle.
dict	string	Animation dictionary name.
clip	string	Animation clip name.
opts	table\|nil	See options below.

opts key	Default	Description
blendIn	8.0	Blend-in speed.
blendOut	-8.0	Blend-out speed.
duration	-1	Duration in ms. `-1` = play full clip once.
flags	0	TaskPlayAnim flags. Common: `0`=once, `1`=loop, `2`=hold last frame.
loop	false	Shorthand for `flags = 1`.
rate	1.0	Playback speed multiplier.
wait	false	Block the current thread until the clip ends.
waitTimeout	10000	Max ms to wait (only used when `wait = true`).
dictTimeout	5000	Max ms to wait for the dict to load.

example

-- play once and block until finished
wc:PlayAnim(ped, 'mech_busted@unapproved', 'idle_b', { wait = true })

-- loop with reduced speed
wc:PlayAnim(ped, 'amb_rest@world_human_stand_impatient@male_a@idle_a', 'idle_a', {
  loop = true, rate = 0.8
})

PlayAnimLooped(ped, dict, clip, opts) → functionclient

Plays a looping animation. Returns a stopper function — call it to stop the loop cleanly.

example

local stop = wc:PlayAnimLooped(npcPed, 'amb_rest@world_human_hang_out_street@male_a@idle_a', 'idle_a')

Wait(5000)
stop() -- blend out and end loop

PlayAnimAt(ped, dict, clip, pos, rot, opts)client

Plays an animation at a specific world position and rotation using TaskPlayAnimAdvanced. Useful for in-place actions at a map point regardless of where the ped is standing.

Param	Type	Description
pos	vector3	World position to play at.
rot	vector3\|nil	Rotation. Defaults to `vector3(0,0,0)`.
opts	table\|nil	Same blendIn/blendOut/duration/flags/rate as PlayAnim.

example

local pos = GetEntityCoords(prop)
wc:PlayAnimAt(ped, 'mini@repair', 'fixing_a_ped', pos, nil, { duration = 4000 })

IsAnimPlaying(ped, dict, clip) → booleanclient

Returns true if the ped is currently playing the given animation.

StopAnim(ped)client

Stop all animations on the ped with a smooth blend-out (ClearPedTasks).

StopAnimNow(ped)client

Stop all animations immediately with no blend (ClearPedTasksImmediately). Use when you need an instant hard cut.

Scenarios

PlayScenario(ped, scenario, opts) → functionclient

Starts a scenario in place. Scenarios loop automatically. Returns a stopper function.

Param	Type	Description
scenario	string	RDR2 scenario name.
opts	table \| boolean \| nil	Use a table for `duration` and `playEnterAnim`. A boolean is still accepted as the old `playEnterAnim` argument.
opts.duration	number \| nil	Scenario duration in milliseconds. Default `0`.
opts.playEnterAnim	boolean \| nil	Play the entry animation before the idle. Default `false` (snap instantly).

example

local stop = wc:PlayScenario(npcPed, 'WORLD_HUMAN_LEAN_WALL')

Wait(8000)
stop()

PlayScenarioAt(ped, scenario, x, y, z, heading, opts) → functionclient

Plays a scenario at a specific world position. Returns a stopper function.

opts key	Default	Description
duration	-1	Duration in ms. `-1` = indefinite.
standing	true	Play as a standing scenario.
playEnterAnim	false	Play the scenario entry animation.

example

local coords = GetEntityCoords(npcPed)
local stop = wc:PlayScenarioAt(npcPed,
  'WORLD_HUMAN_SMOKE_PIPE',
  coords.x, coords.y, coords.z,
  GetEntityHeading(npcPed),
  { duration = 10000 })

Wait(10000)
stop()

StopScenario(ped)client

Stops the scenario currently running on the ped.

Real Wild County example — trader idle scenario

wc_trader/client/main.lua

local stopIdle = wc:PlayScenario(traderPed, 'WORLD_HUMAN_STAND_IMPATIENT')

-- when the shop closes / resource stops
stopIdle()

Common mistakes

Never calling the returned stopper function for PlayAnimLooped/PlayScenario/PlayScenarioAt — the ped keeps looping forever, even after your interaction ends.
Using opts.wait = true on a ped that might get deleted mid-anim (e.g. by another script) without a sane waitTimeout — always leave the default or set an explicit cap.
Passing a raw scenario/dict/clip name that doesn't exist — these fail silently (no error, no animation) rather than throwing, so double check spelling against RedM scenario references if nothing plays.
Playing an anim before the ped exists (e.g. right after a spawn call that hasn't resolved yet) — always check the ped handle is valid first, which every function here already does internally, but your surrounding logic should too.

Troubleshooting

If PlayAnim returns false: the animation dictionary failed to load within dictTimeout — increase it, or check the dict name is correct.
If a looped anim/scenario never stops: confirm you kept and called the stopper function — there's no other way to stop it from outside.
If a scenario ped "pops" into position instead of walking in: that's expected with the default playEnterAnim = false — set it to true for a smoother transition at the cost of the ped taking longer to start.

← backDistance & proximity next →Emotes