AI Behavior

An AI Behavior asset describes when a behavior is useful and what executes when it is selected. Add behavior assets to an AI Archetype to make them available to an agent.

Author a behavior

Create an AI Behavior asset from the Asset Browser's asset creation menu, then open it.

1. Give it a descriptive Name and choose a Category.
2. Choose its Logic. State Machine references a state-machine asset; game plugins can provide additional reflected logic types.
3. Use + Add Consideration to select inputs. Each card exposes its raw input range and response curve.
4. Set Weight, Commit, and Cooldown, then test the score before connecting it to an archetype.

This combat example combines two consideration outputs of about 0.36 into a utility score of about 0.20. Score Preview tests authoring values without running the character's state machine.

Considerations and scoring

Each consideration reads an input, maps InputMin–InputMax to 0–1, clamps it, and evaluates its response curve. With an empty curve it uses the normalized input directly.

Inputs include target distance, target confidence, angle to target, blackboard values, distance to a blackboard position, time since activation/deactivation, and tactical or squad information. A TARGET chip identifies inputs that require a perceived target. Such behaviors cannot compete without an available target.

Consideration values are multiplied. Any zero vetoes the behavior. A compensation step reduces the disadvantage of having many considerations; Weight and the archetype's WeightScale then scale the utility, which is clamped to 0–1.

Categories rank eligible candidates in this order, highest first:

Interrupt > Combat > Command > Investigate > ActiveIdle > Idle > Fallback

Use categories for priority and weights for preferences within a category. A high weight cannot make a lower-category candidate outrank an eligible higher-category candidate. Switching still respects the running behavior's lock and commit threshold.

• CommitBonus (shown as Commit) is the margin a challenger must beat above the active behavior's score. It reduces rapid switching.
• CooldownDuration (shown as Cooldown) prevents reselection for that duration after deactivation.
• An active logic instance can lock behavior switching until it releases the lock.

Avoid accidental vetoes. For example, use a curve with a small nonzero floor when distance should merely discourage a behavior. Use a zero floor when distance should make it impossible.

Use Score Preview

The Score Preview panel provides a slider for each consideration's raw input. Change these to inspect the curved outputs, product of factors, compensated score, and final utility.

• Archetype ×scale tests the effect of an archetype's weight scale.
• running shows the commit-bonus threshold.
• on cooldown demonstrates the cooldown veto.
• Clicking a curve opens the curve editor; its menu provides presets such as Linear Rise, Linear Fall, Gate, Bell, and Constant 1.

For a distance range of 0–20 m with a Linear Fall curve, 5 m normalizes to 0.25 and produces 0.75. At 20 m it produces zero and vetoes the behavior. Test those endpoints before tuning weights.

The horizontal axis is normalized input; the vertical axis is the consideration output. This example increases the contribution as target confidence rises.

The preview uses simulated inputs. Use the runtime score overlay to verify real sensor values, targets, and competing behaviors.

State-machine execution

Utility AI chooses the behavior; the referenced state machine executes it. The agent publishes Ai_TargetPosition, Ai_TargetObject, and Ai_TargetConfidence to its blackboard.

State	Purpose
AiNavigateTo	Navigate to the vector in TargetPositionEntry; report 0 = navigating, 1 = arrived, 2 = failed in ResultEntry.
AiWait	Wait between MinDuration and MaxDuration; report completion through its result entry.
AiPickPatrolPoint	Choose child waypoints, a random navmesh point around home, or a point along a spline route.
AiSetBlackboardEntries	Write configured entries on entry and exit.
AiRunActions	Execute an ordered list of actions such as Wait, Turn Towards Target, Log, or Spawn.
AiRunEqsQuery	Run an EQS asset and store its chosen destination.
AiPickTacticalPoint, AiPickPeekPosition, AiReleaseCover	Select and manage cover positions.
AiPickSmartObject, AiUseSmartObject, AiReleaseSmartObject	Find, use, and release an interaction slot.

Set Ai_BehaviorDone or Ai_BehaviorFailed to true to finish the behavior. Set Ai_LockBehavior while it must not be interrupted, then clear it when interruption is safe.

Example: patrol, walk, wait

Use Ai Pick Patrol Point → Ai Navigate To → Ai Wait, with blackboard-condition transitions and a failure branch.

1. Give a route object a global key and add child waypoint objects. Set the patrol state's RouteGlobalKey and choose Waypoints.
2. The patrol state writes Ai_PatrolTarget and Ai_PatrolResult. Transition on result 1 to navigation; handle result 2 with a retry wait.
3. Set navigation's TargetPositionEntry to Ai_PatrolTarget. Disable EndBehaviorWhenDone while chaining to the wait state.
4. On navigation result 1, wait briefly; on 2, retry or report failure.
5. Transition from the completed wait back to the picker. Leave wait's EndBehaviorWhenDone off for this loop.

Keep the patrol behavior in ActiveIdle so eligible investigate or combat behaviors can take over. For a one-state idle behavior, use Ai Wait with EndBehaviorWhenDone enabled instead.

See also

• AI Agent and Archetype
• AI EQS Query
• Blackboards