-
Notifications
You must be signed in to change notification settings - Fork 5
Task Builder
The Task Builder lets you create AI behavior sequences for peds. Chain together actions like walking, playing animations, driving vehicles, and engaging in combat to bring your scenes to life.
A task sequence is an ordered list of steps that a ped executes one after another. For example, you might create a sequence where a guard walks to a door, plays a standing animation, waits for 10 seconds, then walks back -- and loops forever.
The Task Builder is a dedicated window with a two-column layout:
- Left column -- The step list, showing all steps in execution order
- Right column -- The step editor, showing configuration for the currently selected step
Select a ped, then open the Task Builder window. The builder follows your selection -- clicking a different ped auto-saves the current sequence and loads the new ped's sequence.
Steps fall into several categories. Some steps take time to complete (the ped performs an action), while others apply instantly and move on to the next step immediately.
| Step | Description | Key Options |
|---|---|---|
| Go To Coord | Walk or run to a world coordinate | Speed (walk/run), stopping distance, timeout |
| Wander | Roam freely within an area | Center point, radius, duration |
| Idle | Stand still and do nothing | Optional duration (0 = indefinite) |
| Wait | Pause the sequence for a set time | Duration in milliseconds |
Tip: Go To Coord and Drive To Coord steps can capture your current crosshair position as the target coordinate -- no need to type coordinates manually.
| Step | Description | Key Options |
|---|---|---|
| Animation | Play a specific animation clip from the game's 269,000+ clip library | Dictionary, clip name, playback mode, upper body only |
| Scenario | Play an ambient scenario behavior (smoking, drinking, using clipboard, etc.) | Scenario name, optional position/heading, duration |
Animation Playback Modes:
| Mode | Behavior |
|---|---|
| Once | Play to end, then move to next step |
| Hold | Play and freeze on the last frame (step completes immediately, pose holds) |
| Loop | Loop indefinitely -- the ped will keep playing this animation until the sequence is stopped |
| Timed | Play for a specified duration, then move to next step |
Upper Body Only: When enabled, the animation only plays on the ped's upper body, allowing them to walk or turn while the animation runs.
Prop Targeting: Animation and scenario steps can optionally target a prop. The ped will be positioned at the prop before the animation plays -- useful for seated animations (e.g., sitting on a chair or bench).
| Step | Description | Key Options |
|---|---|---|
| Enter Vehicle | Walk to and enter a vehicle | Target vehicle, seat (driver/passenger), speed, warp option |
| Leave Vehicle | Exit the current vehicle | Warp option (animated or instant exit) |
| Drive To Coord | Drive to a destination | Destination, speed, driving style, stop distance |
| Vehicle Cruise | Cruise around aimlessly | Speed, driving style, duration |
Note: The target vehicle must be spawned in the same scene. Select it from the step editor's vehicle picker.
Seat options: -1 = driver, 0 = front passenger, 1 = rear left, 2 = rear right.
Warp: When enabled, the ped teleports instantly into or out of the vehicle instead of playing the enter/exit animation.
| Step | Description | Key Options |
|---|---|---|
| Combat | Attack a target entity | Target entity, duration |
| Flee | Run away from a target entity | Target entity, flee distance, duration |
| Hands Up | Surrender pose with hands raised | Duration, optional entity to face |
| Protect | Bodyguard a target -- follow and fight for them | Target entity, formation, follow distance, combat settings |
Protect turns the ped into a bodyguard. They will follow the target entity (another ped or a player), match their movement, and engage hostile NPCs. You can configure:
| Option | Description |
|---|---|
| Formation | Default, Circle, Alternate Circle, or Line |
| Follow Distance | Spacing in meters (default: 2.0) |
| Combat Ability | Poor, Average, or Professional |
| Combat Movement | Stationary, Defensive, or Offensive |
| Combat Range | Near, Medium, or Far |
| Seeing/Hearing Range | Detection distance in meters (0--100) |
| Duration | 0 = follow forever, or set a time limit |
These steps apply immediately and do not pause the sequence. They change the ped's state before the next action begins.
| Step | Description | Key Options |
|---|---|---|
| Set Behavior | Configure AI attributes | Alertness, combat ability, combat movement, combat range, seeing/hearing range |
| Clear Behavior | Reset AI to defaults | -- |
| Set Block Events | Block or unblock reactions to the world | On/Off |
| Set Relationship | Change relationship between ped groups | Group name, target group, relationship level |
| Set Config Flags | Toggle low-level ped configuration flags | Flag ID and on/off state |
| Clear Tasks | Immediately cancel all ped tasks | -- |
| Properties | Apply state changes with no action (see Frame Properties below) | Weapon, faction, behavior, invincibility, etc. |
Every sequence starts with a special Properties step at position 0. This step defines the ped's initial state before any actions run:
- Which weapon to equip
- Which faction to assign
- Behavior preset (passive, aggressive, etc.)
- Whether the ped is invincible
- Whether events are blocked
- Config flags
When a sequence is restarted or reset, the Properties step is re-applied to restore the ped to its initial configuration.
Any step in a sequence can include property modifiers that are applied at the start of that step, before its action begins. This lets you change a ped's state mid-sequence without adding a separate configuration step.
For example, you can add a weapon equip to a Go To Coord step -- the ped will equip the weapon and then start walking.
Available frame properties:
| Property | Description |
|---|---|
| Weapon | Equip a weapon (or unequip) |
| Faction | Change faction assignment |
| Behavior | Modify AI attributes (alertness, combat ability, etc.) |
| Block Events | Block or allow reactions |
| Invincible | Toggle damage immunity |
| Config Flags | Toggle ped configuration flags |
| Alpha | Change transparency |
When creating a sequence, you choose a mode that determines what happens after the last step completes:
| Mode | Behavior |
|---|---|
| Once | Execute all steps from first to last, then stop |
| Loop | Execute all steps, then restart from the beginning indefinitely |
| Ping Pong | Execute all steps forward, then execute them in reverse, then forward again, repeating indefinitely |
Triggers let you coordinate sequences across multiple peds. They are the key to creating synchronized multi-character scenes.
Any step can have two trigger fields:
- Fire Trigger -- When this step completes, fire a named trigger signal
- Wait For Trigger -- Do not start this step until a named trigger signal has been fired
Triggers are named (you choose the name) and scene-scoped (all peds in the same scene share the same trigger namespace).
Suppose you have two guards, A and B, and you want Guard B to start moving only after Guard A reaches the door:
Guard A's sequence:
- Go To Coord (the door) -- Fire Trigger:
guard_at_door - Play animation (standing guard)
Guard B's sequence:
- Wait -- Wait For Trigger:
guard_at_door - Go To Coord (patrol point)
- Play animation (looking around)
Guard B will remain at step 1 (waiting) until Guard A completes step 1 and fires the guard_at_door trigger. Then Guard B proceeds.
- Triggers stay active until the scene is reset or sequences are reassigned
- You can reuse the same trigger name across different steps for complex choreography
- While waiting for a trigger, the ped's status shows "waiting" in the Task Builder
The Task Builder footer has playback controls for testing sequences:
| Button | Action |
|---|---|
| Play | Restart the saved sequence from step 0 |
| Stop | Halt execution but keep the ped at its current position |
| Reset | Stop execution, teleport the ped back to its saved position, and reset state |
| Revert | Discard unsaved edits and reload the last saved version |
| Clear All | Remove every step from the draft sequence |
| Save & Assign | Save the sequence and assign it to the ped |
Important: Play, Stop, and Reset operate on the last saved version of the sequence. If you have unsaved changes, save first to see them reflected in playback.
The Scene Director provides room-level playback controls that affect all peds in the scene at once. These controls are found in the Scene panel:
| Button | Action |
|---|---|
| Play | Start all ped sequences from the beginning |
| Stop | Stop all ped tasks (peds stay where they are) |
| Reset | Stop all tasks and teleport every entity back to its saved position |
This is how you orchestrate an entire scene: build individual sequences for each ped using the Task Builder, then use the Scene Director to play, stop, and reset everything together.
The Scene Director also handles dead peds during a reset -- if a ped was killed during playback, resetting will respawn it automatically.
When you click a different ped while the Task Builder is open, any unsaved changes to the current ped's sequence are automatically saved before loading the new ped's sequence.
Click Save & Assign to explicitly save the sequence and assign it to the ped. The sequence is persisted to the database and will survive server restarts.
Saved sequences are stored per-entity. When a ped is spawned from the database (e.g., after a server restart or when joining a scene), its saved sequence is loaded and can be played again.
Task sequences can also be shared across peds in the same scene -- the Scene Director's play command starts every ped's assigned sequence simultaneously.
-
Save before Play -- Playback always uses the last saved version. Unsaved edits are not reflected until you click Save & Assign.
-
Use the crosshair for coordinates -- Go To Coord and Drive To Coord steps have a "capture" button that grabs your current crosshair position as the target. This is much faster than typing coordinates.
-
Drag to reorder -- Steps in the left panel can be dragged to rearrange execution order.
-
Properties step for setup -- Use the Properties step (step 0) to set up the ped's initial state. This ensures the ped always starts correctly when the sequence is played or reset.
-
Frame properties for mid-sequence changes -- Instead of adding separate Set Behavior or Properties steps, attach property modifiers directly to action steps. The ped will apply the changes at the start of that step.
-
Triggers for choreography -- Use triggers to synchronize multiple peds. Name triggers descriptively (e.g.,
car_arrived,speech_done,door_opened) so your sequences are easy to understand. -
Test individual peds first -- Build and test each ped's sequence individually with the Task Builder's Play button, then use the Scene Director to test the full scene.
-
Reset to recover -- If a ped gets stuck or dies during testing, use Reset to teleport it back and restore its initial state.