AI Script Commands

This file documents the commands and features used to control AI Scripts.

AI Scripts augment the base Script Core system. Refer there for basic understanding of labels, conditionals, calls, variables, strings, etc. This document will describe new commands and other things specific to the AI Script subsystem.

In this document:

Detailed Command Reference
Metadata Information
Reserved Label Names
Brief Command Reference

Command Reference

Additional functions available to AI Scripts.

use [integer]
Perform an ability activation. The value used is the Ability ID. Consult the Ability Table to retrieve the ID.

Example:
; Performs the NPC version of Firebolt use 5173

getwill [variable]
Retrieve the object's current Will amount, and store in a variable.

Example:
getwill WILL

getwillcharge [variable]
Retrieve the object's current Will Charge count, and store in a variable.

Example:
getwillcharge WILLCH

getmight [variable]
Retrieve the object's current Might amount, and store in a variable.

Example:
getmight MIGHT

getmightcharge [variable]
Retrieve the object's current Might Charge count, and store in a variable.

Example:
getmightcharge MIGHTCH

has_target [variable]
Check whether the object has a currently selected target. If it does, [variable] will be set to 1. If no target, it will be set to 0.

Example:
has_target var

getlevel [variable]
Retrieve the object's level, and store in a variable.

Example:
getlevel var

debugprint [string:text]
Same as print. Prints a message to the server log.

Example:
debugprint "Reached a checkpoint!"

getcooldown [string] [variable]
Determine whether the object is currently waiting on a cooldown category to finish. This is useful if you want to determine whether a skill with a long cooldown is available to cast again. If not you may wish to conditionally perform some other effect.

Cooldown categories are specified by string name. Refer to the ability table to see which cooldown categories are used by a particular skill. If waiting on a cooldown, the variable will be set to 1. If not in cooldown, it will set to 0.

Example:
getcooldown "Concussion" var

is_busy [variable]
Determine if an ability is currently being performed. Channels and casting warmups take time to finish, so you may not want to interrupt a cast with another ability.

If an ability is currently active, sets the variable to 1. If not, sets to 0.

count_enemy_near [integer:range] [variable]
Count the number of valid enemy targets around the object, and store the result in a variable. This is useful if you want to determine whether to cast an Area of Effect ability that will hit multiple targets.

The integer takes the maximum range, in game units. Note: 10 units = 1 meter.

Example:
count_enemy_near 150 TCOUNT

count_enemy_at [integer:range] [variable]
Like count_enemy_near, but performs a search around the target creature, if there is a target. If there isn't a target, it defaults to searching around itself.

The integer takes the maximum range, in game units. Note: 10 units = 1 meter.

Example:
count_enemy_at 100 TCOUNT

health_percent [variable]
Retrieves the object's health percentage (a value from 0 to 100) and stores the result in a variable. target_health_percent [variable]
Retrieves the selected target's health percentage (a value from 0 to 100) and stores the result in a variable. If there is no target, the result will always be 0. set_elapsed_time [variable]
Retrieves the amount of time, in milliseconds, since the server was launched. Stores the result in a variable. time_offset [variable:elapsed] [variable:destination]
Calculates the current time difference (in milliseconds) with a variable holding a time (which should previously have been set using set_elapsed_time). The time difference is stored in the destination variable.

Example:
time_offset LASTABILITY
; ... (any code that happens as time passes)
time_offset LASTABILITY ELAPSEDTIME
if ELAPSEDTIME > 30000
  ; do something
endif

visual_effect [string]
Sends a visual effect to the object. This plays an animation in the client but has no effect on gameplay. visual_effect_t [string]
Sends a visual effect to the selected target. This plays an animation in the client but has no effect on gameplay. If the object does not have a target, the animation plays on itself. say [string]
Sends a /say message as speech and appears to all local players within chat range.

Example:
say "Furries ruined Sparkplay."

instance_call [string:label]
Performs an unconditional jump in the zone's instance script (not AI Script). The label is not checked for accuracy so make sure it exists in the instance script.

This is necessary for boss scripts that spawn minions.

Example:
instance_call "spawnmobs"

get_idle_mob [integer:CDefID] [variable]
Search the instance for any idle mob of a particular CreatureDef ID type. Updates the variable with the Creature Instance ID if found, or 0 if not found.

Note that this searches the entire instance, regardless of range. Should only be used within small areas, and on specific creature spawns. The search ends on the first creature found.

Example:
get_idle_mob 3632 ALLY

get_target [variable]
Set the variable to the current target's Creature Instance ID. Will be 0 if no target is found.

Example:
get_target TARGET

get_self [variable]
Set the variable to the actor's own Creature Instance ID.

Example:
get_self SELF

set_other_target [variable:first] [variable:second]
The first creature will set the second creature as an active target.

Both variables must contain Creature Instance IDs, retrieved by using commands like get_idle_mob, get_target, get_self, or similar.

Example:
get_idle_mob 3631 ALLY if ALLY > 0   get_self TARGET   set_other_target ALLY TARGET endif

aiscript_call [variable] [label]
Modify a different creature's actions by forcing it to jump to a specific label in its own AI Script. This can be used to allow a boss to give some rudimentary control over specially scripted minions.

The current script state of the target will be interrupted and reset, resuming operation at the specified label, if it exists. The label in the associated script is responsible for having commands that direct it back to normal operational flow. The target's call stack is erased so it will require an explicit goto back to its main loop.

The variable must contain a Creature Instance ID.

Example:
aiscript_call TARGET "extOnSummon"

is_target_enemy [variable]
Determine if the object's current target is an attackable enemy (and alive). Sets the variable to 1 if an active enemy, 0 if not. is_target_friendly [variable]
Determine if the object's current target is a friend (and alive). Sets the variable to 1 if an active friend, 0 if not. set_speed [integer]
Forcibly set the object's current walk/run speed. This is untested and may cause movement glitches. The AI movement control may also reset the speed to particular values which cannot be influenced by the script.

Note that 100 is normal movement speed.

get_target_cdef [variable]
Place the current target's CreatureDef ID into the variable.

This is used to determine if the target is of a certain type, like a boss, to perform actions based on that specific type.

get_property [string] [variable]
Retrieve a stat value from the creature, placing the result in a variable. Refer to Character Stats for valid properties. Property names must be lower case. Only works to retrieve integer values.

Example:
get_property "strength" var

get_target_property [string] [variable]
Retrieve a stat value from the current target, placing the result in a variable. Refer to Character Stats for valid properties. Property names must be lower case. Only works to retrieve integer values.

Example:
get_target_property "strength" var

dispel_target_property [string] [integer]
Indiscriminately purge all buffs to a particular stat from the target. Only erases buffs that were granted by abilities. Note that this includes passive gains, so use carefully and only for particular stats.

Refer to Character Stats for valid properties.

The integer is a sign value, must be either 1 or -1. Most buffs (like strength) are based on positive gains, but some like channeling_break_chance have negative values (counting down from 50%).

Example:
dispel_target_property "bonus_health" 1

randomize [integer] [variable]
Generate a random number from 1 to [integer] (inclusive) and store the result.

Example:
randomize 3 CHOICE

find_cdef [integer] [variable]
Search the instance for the first creature matching a particular CreatureDef ID. If found, store its Creature Instance ID. Sets to 0 if not found.

Note that this searches the entire active instance, regardless of range. Should only be used for very specific, unique creatures like bosses or NPCs.

Example:
find_cdef 3636 TARGET

play_sound [string]
Notify the client to play a sound effect. The sound string is composed of 2 parts, separated by a pipe (|). The first part is the package archive (.CAR file) to load and play from. The second part is the actual sound file to play (must be .OGG format).

Example:
play_sound "Sound-ModSound|Sound-Example.ogg"

get_buff_tier [int:AbilityGroupID] [var:dest]
Search the creature for a buff with the given Ability Group ID (refer to the ability table), and return the tier (1 = lev1, 2 = lev6, 3=lev20, etc). Returns zero for no buff found.

Useful to search if a buff ability has been activated.

Example:
;See if we have Vigor of Sargon active
get_buff_tier 38 RESULT

get_target_buff_tier [int:AbilityGroupID] [var:dest]
Search the creature's target for a buff with the given Ability Group ID (refer to the ability table), and return the tier (1 = lev1, 2 = lev6, 3=lev20, etc). Returns zero for no buff found.

Useful to search if a buff ability has been activated.

Example:
get_target_buff_tier 38 RESULT

target_in_range [int:Distance] [var:dest]
Determine if the currently selected target is in range. Distance is expressed in game units. 1 meter = 10 units. Melee range is 30 units.

The destination variable will hold the result. 0 = out of range, 1 = in range.

Example:
target_in_range RESULT

get_target_range [var:dest]
Get the current distance from the currently selected target. Distance is expressed in game units. 1 meter = 10 units. Melee range is 30 units.

The destination variable will hold the result. If no target is selected, the result will be 0. It is recommended to ensure a target exists before using this function.

Example:
get_target_range RESULT

set_gtae
Sets the location for ground target area-of-effect abilities to the currently selected target, or to current standing location if no target. This is required for GTAE abilities. When players cast such abilities, they have a large targeting circle on the ground. Abilities like Swarm, Frost Storm, and similar.

Make sure to use this before casting a GTAE ability, or it may fail.

Example:
set_gtae use 215   ; Swarm

get_speed [var:CID] [var:dest]
Look up the CID object and retrieve its current movement speed, placing the result in the destination variable. If the result is 0, the target is stationary.

Example:
get_target TARGID get_speed TARGID RESULT

cid_is_busy [var:CID] [var:dest]
Look up the CID object and determine if it's busy casting an ability. Only reliable to detect casting warmups or channels. Places the result in the destination variable. 0 = not busy, 1 = busy.

Example:
get_target TARGID cid_is_busy TARGID RESULT

Metadata Information

Some properties are of particular importance to AI Scripts.

#name [string]
Identifies the script by giving it a name. For easy organization, the name should match the file name of the AI Script. This property is especially important to AI Scripts because the CreatureDef ai_package property must correspond to an existing script name.

Example:
#name 4_druid_melee_30

#speed [integer]
Sets the execution speed of a script, as instructions per frame.

This is especially useful for AI Scripts because complex scripts with several if commands and call blocks, will require many frames to complete a full loop in the AI logic. Every cycle (or frame) of the server will iterate over every active NPC in the instance for processing.

Complex scripts will be slower to trigger multiple parts, and will appear less responsive if the speed is too slow. However, don't set the speed too high or it may degrade server performance by increasing CPU use, especially if several mobs in the instance use the same complex scripts.

Example:
#speed 10

#idlespeed [integer]
Like #speed, but sets the idle execution speed. The default idle speed is zero, which means NPCs will not run scripts when idle (not in combat).

This may be important for some boss scripts to keep mobs in a certain state of awareness. Also useful for inanimate objects to provide effects or animations.

Idle creatures don't necessarily require real-time responsiveness so the idle speed can usually be kept to a small amount, like 1 (one instruction per server frame).

Keep in mind that if too many mobs are performing additional commands and calculations when idle, server performance may be affected by higher CPU use.

Example:
#idlespeed 1

Reserved Labels

:onDeath
Normally a creature's script will not run if it's dead. This label is specially called when a creature dies, then several instructions are allowed to run. Scripts do not need this label unless a special death action is required.

There should be an explicit end command in the control flow to halt the script once death processing is finished. Don't loop back to the standard attack script.

Example:
:onDeath say "I'm not dying, I'm just going to nap here for a while." end

Quick Command Reference

A brief overview of the commands. Here is an explanation of abbreviations here:
var = Variable
int = Integer
dest = The destination variable where a result is stored.
CDefID = Creature Definition ID (base creature type).
CID = Creature Instance ID (specific active creature).