jim_bridge/documentation/main_functions/pedTasks.md

pedTasks.lua

This module wraps the GTA V Task* natives so scripted peds can be given orders without having to remember each native's argument list.

Every task is registered against its ped, so it can be queried and cancelled later. Finite tasks accept an onComplete callback and an optional timeout, and every function returns false, "reason" when it cannot run.

Coordinates can be passed as a vector3, a vector4, a plain {x=,y=,z=} table, or an entity handle, and are normalised automatically.

⚠️ The ped must not be frozen. GTA ignores movement and animation tasks on a frozen ped, so create peds with makePed(..., freeze = false, ...) or call FreezeEntityPosition(ped, false) before giving them tasks.

⚠️ Peds need a weapon and canShoot before pedTaskShootAt will make them fire. Use GiveWeaponToPed(ped, WEAPON_PISTOL, 50, false, true) and pedCombatAttributes(ped, { canShoot = true, canAim = true }). GTA also refuses to let a ped fire unless it is already aiming, so pass aim = true or call pedTaskAimAt first.

Movement

• pedTaskGoTo(ped, coords, opts)

  • Sends a ped to walk or run to a set of coordinates. The task completes once the ped is within opts.radius of the destination.
  • Options: run, speed, radius, heading, slide, nativeTimeout, timeout, onComplete, onTimeout
  • Example:

    pedTaskGoTo(ped, vec3(455.0, -975.0, 30.0), {
        run = true,
        onComplete = function(p) print("arrived") end,
    })
    

• pedTaskGoToEntity(ped, target, opts)

  • Sends a ped towards an entity for a set time or until it is within range.
  • Options: duration, distance, speed, run
  • Example:

    pedTaskGoToEntity(ped, vehicle, { run = true })
    

• pedTaskFollow(ped, target, opts)

  • Makes a ped follow another entity at a set offset. Completes when the ped catches up.
  • Options: offset, run, speed, radius, nativeTimeout, timeout, onComplete, onTimeout
  • Example:

    pedTaskFollow(ped, targetPed, { offset = vec3(2.0, 0.0, 0.0), run = true })
    

• pedTaskWander(ped, coords, opts)

  • Sends a ped wandering randomly inside a radius. Continuous task, no completion callback.
  • Options: radius, length, betweenWalks
  • Example:

    pedTaskWander(ped, vec3(455.0, -975.0, 30.0), { radius = 10.0 })
    

• pedTaskFlee(ped, threat, opts)

  • Makes a ped run away from a threat, which can be an entity or a set of coordinates.
  • Options: distance, time, timeout, onComplete, onTimeout
  • Example:

    pedTaskFlee(ped, threatPed, { distance = 60.0 })
    

• pedTaskFace(ped, target, opts)

  • Makes a ped turn to face an entity, or to reach a heading in degrees.
  • Options: duration
  • Example:

    pedTaskFace(ped, targetPed)
    

Vehicles

• pedTaskEnterVehicle(ped, vehicle, opts)

  • Tells a ped to get into a vehicle. Completes once the ped is seated.
  • Options: seat ("any", "driver", "passenger", "rearLeft", "rearRight"), speed, flag ("normal", "teleportToVehicle", "carjackFromSeat", "teleportDirectly"), nativeTimeout, timeout, onComplete, onTimeout
  • Example:

    pedTaskEnterVehicle(ped, vehicle, { seat = "driver" })
    

• pedTaskLeaveVehicle(ped, opts)

  • Tells a ped to get out of a vehicle. Completes once the ped is out.
  • Options: vehicle, flag ("normal", "normalSlow", "keepDoorOpen", "teleportOutside", "throwOutOfVehicle", "moveToPassengerFirst"), timeout, onComplete, onTimeout
  • Example:

    pedTaskLeaveVehicle(ped)
    

• pedTaskOpenDoor(ped, vehicle, door, opts)

  • Tells a ped to open a vehicle door. GTA opens the door nearest to the given seat, so use seat names rather than door names. Asking for "driver" may still open the passenger door if that one is closer.
  • Options: speed, nativeTimeout, timeout, onComplete
  • Example:

    pedTaskOpenDoor(ped, vehicle, "passenger")
    

• pedCloseDoor(vehicle, door, opts)

  • Closes a vehicle door. GTA has no "close door" task, so this uses the door native directly.
  • Options: instant (snap it shut), ped (a ped whose tasks should be cancelled first, so they stop fighting the close)
  • Example:

    pedCloseDoor(vehicle, "passenger", { ped = ped })
    

• pedTaskDriveTo(ped, vehicle, coords, opts)

  • Makes a ped drive a vehicle to a set of coordinates.
  • Options: speed, drivingMode, model, stopRange, timeout, onComplete, onTimeout
  • Example:

    pedTaskDriveTo(ped, vehicle, vec3(100.0, 200.0, 30.0))
    

• pedTaskPark(ped, vehicle, coords, opts)

  • Makes a ped park a vehicle at a set of coordinates.
  • Options: heading, mode ("ignoreHeading", "forward", "reverse"), radius, keepEngineOn, timeout, onComplete, onTimeout
  • Example:

    pedTaskPark(ped, vehicle, vec3(100.0, 200.0, 30.0), { heading = 90.0 })
    

• pedTaskChase(ped, target)

  • Makes a ped in a vehicle chase another entity. Continuous task.
  • Example:

    pedTaskChase(ped, targetVehicle)
    

Combat

• pedTaskCombat(ped, target, opts)

  • Sends a ped to attack a target. Continuous task.
  • Options: style ("melee" or "ranged")
  • Example:

    pedTaskCombat(ped, targetPed, { style = "melee" })
    

• pedTaskShootAt(ped, target, opts)

  • Makes a ped shoot at an entity or a set of coordinates. Continuous task.
  • Options: duration, pattern (e.g. "FIRING_PATTERN_FULL_AUTO"), aim (aim at the target first, required for the ped to actually fire)
  • Example:

    pedTaskShootAt(ped, targetPed, { pattern = "FIRING_PATTERN_BURST_FIRE", aim = true })
    

• pedTaskAimAt(ped, target, opts)

  • Makes a ped aim a weapon at an entity or a set of coordinates. Continuous task.
  • Options: duration, instant, intro
  • Example:

    pedTaskAimAt(ped, vec3(100.0, 200.0, 30.0))
    

• pedTaskAccuracy(ped, level)

  • Sets how accurate a ped is when shooting, 0 is poor and 100 is perfect.
  • Example:

    pedTaskAccuracy(ped, 80)
    

• pedTaskFiringPattern(ped, pattern)

  • Sets the firing pattern a ped uses, by name or hash.
  • Example:

    pedTaskFiringPattern(ped, "FIRING_PATTERN_BURST_FIRE")
    

Animation

• pedTaskPlayAnim(ped, dict, anim, opts)

  • Plays an animation on a ped. Completes once the animation has finished, unless opts.loop is set.
  • Options: blendIn, blendOut, duration, flag ("looping", "holdLastFrame", "repositionWhenFinished", "notInterruptable", "upperBody"), playbackRate, lock, loop, timeout, onComplete, onTimeout
  • Example:

    pedTaskPlayAnim(ped, "amb@world_human_clipboard@male@idle_a", "idle_c")
    

• pedTaskScenario(ped, scenario, opts)

  • Starts a scenario on a ped, such as a sitting or leaning animation. Continuous task.
  • Options: duration, intro
  • Example:

    pedTaskScenario(ped, "WORLD_HUMAN_STAND_IMPATIENT")
    

• pedTaskLookAt(ped, target, opts)

  • Makes a ped look at an entity or a set of coordinates.
  • Options: duration
  • Example:

    pedTaskLookAt(ped, targetPed, { duration = 3000 })
    

• pedTaskRagdoll(ped, duration, opts)

  • Makes a ped ragdoll for a set duration.
  • Options: type
  • Example:

    pedTaskRagdoll(ped, 3000)
    

• pedTaskStandStill(ped, duration)

  • Makes a ped stand still for a set duration.
  • Example:

    pedTaskStandStill(ped, 3000)
    

Behaviour

• pedCombatAttributes(ped, opts)

  • Sets what a ped is allowed to do in combat. The native takes one attribute at a time, so every option provided is applied individually and anything left out is not changed.
  • Options: any of alwaysFight, canShoot, canAim, canUseCover, aggressive, perfectAccuracy, disableFleeFromCombat, canFlank, canCharge and the rest of the game's combat attributes.
  • Example:

    pedCombatAttributes(ped, { alwaysFight = true, canShoot = true, canUseCover = true })
    

• pedFleeAttributes(ped, opts)

  • Sets what a ped is allowed to do when it is fleeing. The native takes a bitmask, so each attribute is applied as 1 << bit.
  • FiveM only documents bit 15 as "force cower", the rest follow the game's flee attribute ordering. Use pedSetFleeAttribute if you need a specific bit.
  • Example:

    pedFleeAttributes(ped, { [15] = true })
    

• pedSetFleeAttribute(ped, bit, enabled)

  • Sets a single flee attribute on a ped by its bit position.
  • Example:

    pedSetFleeAttribute(ped, 15, true)
    

• pedCombatRange(ped, range)

  • Sets how far a ped will engage in combat. Accepts "melee", "preferred", "far" or a raw value 0-2.
  • Example:

    pedCombatRange(ped, "melee")
    

• pedCombatAbility(ped, level)

  • Sets how well a ped fights, from 0 (poor) to 4 (very good).
  • Example:

    pedCombatAbility(ped, 3)
    

• pedCombatMovement(ped, mode)

  • Sets how a ped moves while fighting. Accepts "hold", "strafe", "advance" or a raw value 0-2.
  • Example:

    pedCombatMovement(ped, "strafe")
    

• pedSetConfigFlag(ped, flag, value) / pedGetConfigFlag(ped, flag)

  • Reads and writes raw ped config flags, for anything the helpers above do not cover.
  • Example:

    pedSetConfigFlag(ped, 17, true) -- block non temporary events
    

• pedState(ped, opts)

  • Sets a group of general states on a ped. Only the options provided are applied.
  • Options: invincible, canRagdoll, dropsWeapons, criticalHits, canSwitchWeapon, drunk, armour, health, canBeDamaged, blocksEvents, moveRate, density
  • Example:

    pedState(ped, { invincible = true, canRagdoll = false, armour = 100 })
    

Tracking

• pedTaskStatus(ped)

  • Returns the name of the task currently assigned to a ped, or nil.
  • Example:

    if pedTaskStatus(ped) == "goTo" then print("on the move") end
    

• pedTaskIsRunning(ped, name)

  • Checks if a named task is currently assigned to a ped.
  • Example:

    if pedTaskIsRunning(ped, "combat") then print("fighting") end
    

• pedTaskActive(ped, index)

  • Checks if a native task is active on a ped by its task index.
  • Example:

    if pedTaskActive(ped, pedTaskWanderIndex()) then print("wandering") end
    

• pedTaskWanderIndex()

  • Returns the native task index used by the wander task, for use with pedTaskActive.

• pedTaskCancel(ped, name)

  • Cancels a task on a ped. GTA has no per task cancellation, so the ped's whole task queue is cleared. The name confirms the task is still the one running first.
  • Example:

    pedTaskCancel(ped, "goTo")
    

• pedTaskClear(ped)

  • Clears every task on a ped and resets its tracking.
  • Example:

    pedTaskClear(ped)
    

• pedTaskWait(ped, condition, opts)

  • Waits for a condition to become true for a ped. Useful for chaining tasks together without a separate script thread.
  • Options: timeout, interval, onComplete, onTimeout
  • Example:

    pedTaskWait(ped, function(p) return #(GetEntityCoords(p) - target) < 3.0 end, {
        onComplete = function(p) pedTaskPlayAnim(p, "dict", "anim") end,
    })
    

Chaining tasks together

pedTaskGoTo(ped, coords, {
    run = true,
    onComplete = function(p)
        pedTaskPlayAnim(p, "amb@world_human_clipboard@male@idle_a", "idle_c", {
            onComplete = function(p2)
                pedTaskGoTo(p2, coords2)
            end,
        })
    end,
})