Animations

The Animations module provides a comprehensive animation system for FiveM resources with advanced features including prop handling, animation sequences, scenarios, and automatic cleanup.

play

Plays an animation on an entity with comprehensive options and tracking.

B2Lib.Animations.play(entity, animDict, animName, options)

Parameters:

• entity (number): The entity to animate (ped, vehicle, etc.)

• animDict (string): The animation dictionary name

• animName (string): The animation name within the dictionary

• options (table, optional): Animation configuration options

  • flag (number): Animation flags (default: 0)

  • blendInSpeed (number): Blend in speed (default: 8.0)

  • blendOutSpeed (number): Blend out speed (default: 8.0)

  • duration (number): Duration in ms (-1 for infinite, default: -1)

  • playbackRate (number): Animation speed multiplier (default: 1.0)

  • lockX (boolean): Lock X movement (default: false)

  • lockY (boolean): Lock Y movement (default: false)

  • lockZ (boolean): Lock Z movement (default: false)

  • onStart (function): Start callback

  • onComplete (function): Completion callback

  • onStop (function): Stop callback

Returns: number|nil - Animation ID for tracking, nil if failed

Example:

local animId = B2Lib.Animations.play(PlayerPedId(), "mp_player_inteat@burger", "mp_player_int_eat_burger", {
    duration = 5000,
    flag = 49,
    onComplete = function(id, entity)
        print("Animation completed!")
    end
})

playWithProp

Plays an animation with an attached prop.

B2Lib.Animations.playWithProp(entity, animDict, animName, propModel, options)

Parameters:

• entity (number): The entity to animate

• animDict (string): The animation dictionary name

• animName (string): The animation name

• propModel (string|number): The prop model name or hash

• options (table, optional): Animation and prop configuration options

  • bone (number): Attachment bone (default: 18905)

  • offset (table): Position offset {x, y, z} (default: {x=0, y=0, z=0})

  • rotation (table): Rotation offset {x, y, z} (default: {x=0, y=0, z=0})

  • deleteOnStop (boolean): Delete prop when animation stops (default: true)

  • networkOwned (boolean): Network ownership (default: false)

  • Plus all animation options from play

Returns: number|nil - Animation ID for tracking, nil if failed

Example:

local eatId = B2Lib.Animations.playWithProp(
    PlayerPedId(),
    "mp_player_inteat@burger",
    "mp_player_int_eat_burger",
    "prop_cs_burger_01",
    {
        duration = 8000,
        bone = 18905,
        offset = {x = 0.12, y = 0.028, z = 0.001},
        deleteOnStop = true
    }
)

stop

Stops a specific animation by its tracking ID.

B2Lib.Animations.stop(animId)

Parameters:

• animId (number): The animation ID to stop

Returns: boolean - True if animation was stopped, false if not found

stopAllOnEntity

Stops all animations currently playing on a specific entity.

B2Lib.Animations.stopAllOnEntity(entity)

Parameters:

• entity (number): The entity to stop animations on

Returns: number - The number of animations that were stopped

isPlaying

Checks if a specific animation is currently playing.

B2Lib.Animations.isPlaying(animId)

Parameters:

• animId (number): The animation ID to check

Returns: boolean - True if the animation is playing, false otherwise

getProgress

Gets the progress of a timed animation (0.0 to 1.0).

B2Lib.Animations.getProgress(animId)

Parameters:

• animId (number): The animation ID to check

Returns: number - Animation progress (0.0-1.0), or -1 if not found or infinite duration

playSequence

Plays a sequence of animations in order.

B2Lib.Animations.playSequence(entity, sequence, options)

Parameters:

• entity (number): The entity to animate

• sequence (table): Array of animation steps

• options (table, optional): Sequence configuration options

  • loop (boolean): Loop the sequence (default: false)

  • onSequenceComplete (function): Callback when sequence completes

  • onStepComplete (function): Callback when each step completes

Returns: number|nil - Sequence ID for tracking, nil if failed

playScenario

Plays a scenario animation (ambient animations).

B2Lib.Animations.playScenario(entity, scenarioName, options)

Parameters:

• entity (number): The entity to animate

• scenarioName (string): The scenario name

• options (table, optional): Scenario configuration options

  • duration (number): Duration in ms (-1 for infinite, default: -1)

  • onStart (function): Start callback

  • onComplete (function): Completion callback

Returns: number|nil - Scenario ID for tracking, nil if failed

stopScenario

Stops a scenario animation.

B2Lib.Animations.stopScenario(scenarioId)

Parameters:

• scenarioId (number): The scenario ID to stop

Returns: boolean - True if scenario was stopped, false if not found

getActiveAnimations

Gets all active animations for an entity.

B2Lib.Animations.getActiveAnimations(entity)

Parameters:

• entity (number): The entity to check (optional, returns all if not provided)

Returns: table - Array of active animation objects

cleanup

Manually triggers cleanup of expired animations.

B2Lib.Animations.cleanup()

Returns: number - Number of animations cleaned up

Configuration

Configure the animation system in config.lua:

Config.Animations = {
    cleanupInterval = 30000,        -- Cleanup every 30 seconds
    maxAnimationsPerEntity = 10,    -- Prevent animation spam
    defaultBlendSpeed = 8.0,        -- Default blend in/out speed
    debugMode = false              -- Enable debug logging
}

Troubleshooting

Animations Not Playing

1. Check that the animation dictionary exists and is loaded

2. Verify the animation name is correct

3. Ensure the entity is valid and exists

4. Check console for error messages

Props Not Attaching

1. Verify the prop model exists

2. Check bone ID is correct (18905 for right hand)

3. Ensure prop model is loaded before use

4. Verify offset and rotation values

Performance Issues

1. Use cleanup() to remove expired animations

2. Limit animations per entity using maxAnimationsPerEntity

3. Set reasonable durations to prevent buildup

4. Monitor active animations with getActiveAnimations()

Memory Leaks

1. Always stop animations when no longer needed

2. Enable automatic cleanup in configuration

3. Use deleteOnStop for props

4. Monitor animation count in production