Modding:Entity Behavior taskai

This server side entity behavior runs one or more tasks for the entity. The tasks are assigned through the aitasks property as part of applying the behavior to the entity.

Tasks are either active (aka executing or running) or inactive. Each task is assigned a slot, in the range 0 to 7. Multiple tasks are often assigned to the same slot, but only one task can be active per slot.

Tasks are assigned a priority. The behavior will run the highest priority task that is able to run for the slot. When there are multiple tasks with the same priority, the task's order in the list is used as a tie-breaker, where entries earlier in the list are preferred.

Sometimes a higher priority task is initially unable to run, but later is able to run, which causes the current active task to be cancelled and replaced with the higher priority task. When considering whether to cancel an active task, its cancel priority is considered instead of its regular priority. Setting the cancel priority high allows an otherwise low priority task to run to completion once it starts.

For example, consider the following two tasks inside locust.json.

  server: {
    behaviors: [
...
      {
        code: "taskai",
        aitasks: [
          {
            code: "meleeattack",
            entityCodes: ["player"],
            priority: 3,
...
          },
...
          {
            code: "seekentity",
            entityCodes: ["player"],
            priority: 1.5,
...
          },
...
        ]
      }
    ],
...
  },

The locust has the meleeattack at priority 3. Since the slot was not specified, it defaults to slot 0. seekentity has priority 1.5 (and cancel priority 1.5) on slot 0. Initially when the player is not in range, meleeattack is unable to run, because its ShouldExecute method returns false when the target entity is out of melee attack range. So the seekentity task is run first, even though it is lower priority. After the seekentity task gets the locust within range of the player, the meleeattack task is able to run. So the seekentity task is canceled and replaced with meleeattack, because they share the same slot. After the attack, meleeattack enters cooldown and becomes inactive. So the seekentity task resumes.

Debugging

Ram with the seekfoodandeat task active at priority 1.35

Turning on entitydebuginfo puts a text box above each entity. The text box shows the active tasks (along with their priority and cancel priority), emotional state, and currently running animations.

Entity debug info has to be turned on on both the server (with /entity debug 1) and client side (with .clientconfig showentitydebuginfo 1). With just the server side, the server sends the extra debug information to the client, but the client does not display it. With just the client side, it will display the active animations, but it will not get the task status from the server.

AiTaskBase properties

All vanilla AI tasks inherit from AiTaskBase. As such, all those AI tasks support the following properties defined in AiTaskBase.

slot: (integer, default 0)

The slot that this mod runs in. Out of all of the tasks assigned the same slot, only one can be active at a time. The inactive tasks still do a little processing on every tick to consider whether they should become active.; priority: (float, default 0) : The priority for starting this task compared to the other tasks assigned to the same slot.

priorityForCancel: (float, default 0)

This task's priority when considering canceling it to run a different task. Often a low priority task is given a higher priorityForCancel value so that the task starts at low priority but runs to completion after it starts.

id: (string, default "")

This is rarely used and typically as the default for most tasks. Other entity behaviors or tasks can read this field to find a specific task to inspect or modify. The bellalarm task will not start unless a task with the id "listen" is active. Typically other behaviors and tasks will search for tasks by type. However, in the bellalarm case, the bell entity has two idle type tasks. So one is given the id "listen" to differentiate it.

animation: (string)

Animation to play on the entity while the task executes. The animation is stopped when the task finishes, unless the animation is "attack" or "idle", in which case it plays to completion. The animation can either match an AnimationMetaData code from the entity properties, or it can be the name of an animation from the entity's shape file.

animationSpeed: (float, default 1)

Playback speed of the animation. If the animation refers to a AnimationMetaData code from the entity properties, then this field overrides the playback speed only if it is set (the default is not applied to AnimationMetaDatas). If the animation instead directly refers to an animation code from the entity shape file, and an explicit speed was not given, then the default playback speed of 1 is applied.

mincooldown: (int, default 0)

lower bound on the randomly selected cooldown time. See the description at maxcooldown

maxcooldown: (int, default 0)

upper bound on the randomly selected cooldown time. The cooldown means to wait at least this many milliseconds before starting the task again, relative to the last time the task started or finished (whichever is more recent). Even though the cooldown is calculated on AiTaskBase, only a few of the tasks that derive from it honor the cooldown. So the mincooldown and maxcooldown properties are still listed below on the tasks that do honor it.

initialmincooldown: (int, default mincooldown)

lower bound for the warmup time.

initialmaxcooldown: (int, default maxcooldown)

upper bound for randomly selecting the warmup time. The warmup time is the delay between creating the entity and the first time the task may execute. Tasks honor the warmup time if and only if they honor the cooldown time. Most tasks do not honor the warmup time.

All Tasks

Task Name	Explanation	Example entities	Properties
bellalarm
butterflychase
butterflyfeedonflowers
butterflyflee
butterflyrest
butterflywander
cometoowner
eidolonmeleeattack
eidolonslam
fishmovefast
fishoutofwater
fleeentity
flycircle
flyswoopattack
getoutofwater
gotoentity
idle
jealousmeleeattack
jealousseekentity
lookaround
lookatentity
meleeattack
meleeattacktargetingentity
seekblockandlay
seekentity
seekfoodandeat
seektargetingentity
stayclosetoentity
stayclosetoguardedentity
throwatentity
useinventory
wander

Wondering where some links have gone?
The modding navbox is going through some changes! Check out Navigation Box Updates for more info and help finding specific pages.