Skip to main content

Ped tasks

In GTA V, you never control a pedestrian's limbs directly. You do not calculate bone rotations or manually step coordinates forward every millisecond. Instead, you issue high-level instructions to the engine's AI subsystem called Tasks.

How the task queue works​

Every Ped exposes a Task property giving access to hundreds of built-in engine behaviors:

// Tell a ped to walk to a coordinate
ped.Task.GoTo(targetPosition);

// Tell a ped to flee from the player
ped.Task.FleeFrom(player);

// Tell a ped to stand guard and play an idle animation
ped.Task.StartScenarioInPlace("WORLD_HUMAN_GUARD_STAND", 0, false);

When you assign a task, the game's native AI planner takes over. It handles pathfinding around walls, collision avoidance, foot-planting animations, and physics until the task finishes or is interrupted.

Task interruption: the ClearAll pattern​

If a ped is in the middle of walking or in combat, assigning a new task does not always immediately take effect unless you clear previous orders:

// Cancel all active and queued tasks immediately
ped.Task.ClearAll();

// Assign new orders
ped.Task.FleeFrom(player);

If you want the ped to finish immediately and drop any ongoing animation, ClearAllImmediately() forces a hard reset.

Playing animations​

Playing custom animations requires streaming the animation dictionary (AnimationDictionary) first, just like 3D models:

string dict = "amb@world_human_cheering@male_a";
string anim = "base";

// Load animation dictionary
GTA.Native.Function.Call(GTA.Native.Hash.REQUEST_ANIM_DICT, dict);
ped.Task.PlayAnimation(dict, anim, 8f, -1, AnimationFlags.Loop);

For simple ambient gestures, scenarios like WORLD_HUMAN_GUARD_STAND or WORLD_HUMAN_SMOKING are safer because the engine handles animation streaming automatically.

Task sequencing and cooperative yielding​

When you want a ped to perform a sequence of actions (e.g., walk to a car, wait two seconds, then wave), you have two choices:

  1. TaskSequence: A native container that queues tasks in order.
  2. State machine with yielding: Letting OnTick track the current step across frames without blocking.

Never use Thread.Sleep() to wait between tasks. If you must pause inside a dedicated fiber loop, call Script.Yield():

ped.Task.GoTo(position);

// Wait cooperatively until the ped is close
while (ped.Position.DistanceTo(position) > 1.5f)
{
    Script.Yield();
}

ped.Task.StartScenarioInPlace("WORLD_HUMAN_CHEERING", 4000, false);

Next, we look at combat tasks: arming characters, assigning targets, and managing hostility.