Animation Module

The Animation module provides utility functions for handling RedM animations, movement, and heading controls.

Getting Started

-- Get animation module instance
local Animation = exports.bln_lib:animation()

Constants

Animation.easeIn

Default ease-in value for animations (4.0)

Animation.easeOut

Default ease-out value for animations (-4.0)

Methods

Animation.load

Load an animation dictionary.

Animation.load(dict, waiter)

Parameters

• dict (string): Animation dictionary name
• waiter (boolean): Wait for dictionary to load if true

Example

-- Load animation dictionary without waiting
Animation.load('script@story@mob3@ig@ig1_dutch_holds_up_cashier', false)

-- Load and wait for completion
Animation.load('script@story@mob3@ig@ig1_dutch_holds_up_cashier', true)

Animation.play

Play an animation on a specified ped.

Animation.play(ped, dict, name, duration, flag, offset)

Parameters

• ped (integer): Ped handle
• dict (string): Animation dictionary name
• name (string): Animation name
• duration (number, optional): Animation duration in milliseconds (-1 for full duration)
• flag (integer, optional): Animation flags (0 by default)
• offset (number, optional): Animation offset (0.0 by default)

Returns

• number: Animation duration in milliseconds

Example

local ped = PlayerPedId()
local duration = Animation.play(ped, 
    'script@story@mob3@ig@ig1_dutch_holds_up_cashier', 
    'ig1_cashier_idle', 
    -1,    -- Play full animation
    1,     -- Use animation flag 1
    0.0    -- No offset
)

Animation.goToCoords

Make a ped move to specified coordinates.

Animation.goToCoords(ped, coords, speed, waiter, distanceToStop)

Parameters

• ped (integer): Ped handle
• coords (vector3/vector4): Target coordinates (if vector4, w component is used as final heading)
• speed (number, optional): Movement speed (1.0 by default)
• waiter (boolean, optional): Wait for movement to complete
  • Default: true if coords is vector4, false otherwise
• distanceToStop (number, optional): Distance at which to consider movement complete

Example

local ped = PlayerPedId()

-- Simple movement without waiting
local targetPos = vector3(1234.0, 5678.0, 90.0)
Animation.goToCoords(ped, targetPos)

-- Move with specific speed
Animation.goToCoords(ped, targetPos, 2.0)

-- Move and face specific direction
local targetPosWithHeading = vector4(1234.0, 5678.0, 90.0, 180.0)
Animation.goToCoords(ped, targetPosWithHeading)

-- Move with custom stop distance
Animation.goToCoords(ped, targetPos, 1.0, true, 2.0)

Animation.setDesiredHeading

Make a ped face a specific direction.

Animation.setDesiredHeading(ped, heading, waiter)

Parameters

• ped (integer): Ped handle
• heading (number): Target heading in degrees (0-360)
• waiter (boolean, optional): Wait for rotation to complete (true by default)

Example

local ped = PlayerPedId()

-- Turn ped and wait for completion
Animation.setDesiredHeading(ped, 180.0)

-- Turn ped without waiting
Animation.setDesiredHeading(ped, 90.0, false)

Common Animation Flags

For the flag parameter in Animation.play:

Flag	Description
0	Default
1	Looping
2	Hold last frame
16	Upper body only
32	Allow rotation
120	Cancelable

Examples

Complete Movement Sequence

local ped = PlayerPedId()

-- Move to position
local target = vector4(1234.0, 5678.0, 90.0, 180.0)
Animation.goToCoords(ped, target)

-- Play animation
Animation.play(ped, 
    'script@story@mob3@ig@ig1_dutch_holds_up_cashier', 
    'ig1_cashier_idle'
)

-- Turn to specific direction
Animation.setDesiredHeading(ped, 270.0)

Loading and Playing Animation

local ped = PlayerPedId()
local dict = 'script@story@mob3@ig@ig1_dutch_holds_up_cashier'

-- Load dictionary first
Animation.load(dict, true)

-- Then play animation
Animation.play(ped, dict, 'ig1_cashier_idle', -1, 1)