Files
Jim Shield 40eed38dc2 Strengthen toggleItem security
- locked down `addItem` to be a lot more strict to reduce exploits
- fixed issue for if no supported inventory was found it now uses the correct functions
2026-11-05 18:03:24 +00:00

373 lines
12 KiB
Markdown

### 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:**
```lua
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:**
```lua
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:**
```lua
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:**
```lua
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:**
```lua
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:**
```lua
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:**
```lua
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:**
```lua
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:**
```lua
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:**
```lua
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:**
```lua
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:**
```lua
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:**
```lua
pedTaskChase(ped, targetVehicle)
```
#### Combat
- **pedTaskCombat(ped, target, opts)**
- Sends a ped to attack a target. Continuous task.
- **Options:** `style` ("melee" or "ranged")
- **Example:**
```lua
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:**
```lua
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:**
```lua
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:**
```lua
pedTaskAccuracy(ped, 80)
```
- **pedTaskFiringPattern(ped, pattern)**
- Sets the firing pattern a ped uses, by name or hash.
- **Example:**
```lua
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:**
```lua
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:**
```lua
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:**
```lua
pedTaskLookAt(ped, targetPed, { duration = 3000 })
```
- **pedTaskRagdoll(ped, duration, opts)**
- Makes a ped ragdoll for a set duration.
- **Options:** `type`
- **Example:**
```lua
pedTaskRagdoll(ped, 3000)
```
- **pedTaskStandStill(ped, duration)**
- Makes a ped stand still for a set duration.
- **Example:**
```lua
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:**
```lua
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:**
```lua
pedFleeAttributes(ped, { [15] = true })
```
- **pedSetFleeAttribute(ped, bit, enabled)**
- Sets a single flee attribute on a ped by its bit position.
- **Example:**
```lua
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:**
```lua
pedCombatRange(ped, "melee")
```
- **pedCombatAbility(ped, level)**
- Sets how well a ped fights, from `0` (poor) to `4` (very good).
- **Example:**
```lua
pedCombatAbility(ped, 3)
```
- **pedCombatMovement(ped, mode)**
- Sets how a ped moves while fighting. Accepts "hold", "strafe", "advance" or a raw value 0-2.
- **Example:**
```lua
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:**
```lua
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:**
```lua
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:**
```lua
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:**
```lua
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:**
```lua
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:**
```lua
pedTaskCancel(ped, "goTo")
```
- **pedTaskClear(ped)**
- Clears every task on a ped and resets its tracking.
- **Example:**
```lua
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:**
```lua
pedTaskWait(ped, function(p) return #(GetEntityCoords(p) - target) < 3.0 end, {
onComplete = function(p) pedTaskPlayAnim(p, "dict", "anim") end,
})
```
#### Chaining tasks together
```lua
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,
})
```