Instance Script Commands

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

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

Detailed Command Reference
Metadata Information
Reserved Label Names
Brief Command Reference

Command Reference

Additional functions available to Instance Scripts

spawn [int:PropID]
Force a SpawnPoint to activate. Use the build tool to determine the SpawnPoint's prop ID.

Example:
spawn 1056964748

spawn_at [int:PropID] [int:CDefID]
Force a SpawnPoint to activate. Use the build tool to determine the SpawnPoint's prop ID.

Takes an extra parameter to force a particular creature type to activate. If set to zero, it will choose according to the SpawnPoint's spawn package.

Example:
spawn_at 1358960407 1690

countalive [int:CDefID] [var:dest]
Search the instance to count all (alive) creatures of a particular CDefID. Place the result in the destination variable. If none are found, the result will be zero.

Example:
countalive 2074 result

spawnloc [int:CDefID] [int:x] [int:y] [int:z]
Deprecated. Do not use.

Spawns a creature at a specific coordinate.

Example:

spawnloc 1639 41387 640 66185

get_npc_id [int:CDefID] [var:dest]
Search the entire instance to find the first creature of a particular type. This was only meant to find single unique spawns like bosses. This command is not useful for finding common spawns, because the instance list is not sorted and the returned mob could be anywhere.

It will place the Creature Instance ID (CID) into the destination variable. If the creature was not found, the result will be zero.

Example:
get_npc_id 3630 BOSSID

set_target [var:CDefIDSource] [var:CDefIDTarget]
Forcibly assigns a target creature to the source creature. No distinction is made between friend/foe, so write scripts accordingly to cast appropriate abilities like attacks or heals.

Example:
set_target ALLYID BOSSID

scan_npc_cid [str:location name] [intarr:dest]
Scans the instance for all NPCs, filling an Integer Array with the CIDs of the result.

The location name must be supplied by the #location directive, which is used to define rectangular locations within a map.

Example:

#location BOSSROOM 3200 3800 3700 4200
...
scan_npc_cid BOSSROOM MOBLIST

get_cdef [var:CID] [var:destCDefID]
Looks up the creature with the given CID, and places its CDefID into the destination variable. This may be useful to filter out a specific creature from an Integer Array.

Example:
get_cdef TEMPCID TEMPCDEF

get_health_percent [var:CID] [var:dest]
Looks up the current health of an NPC CID, placing the result into a destination variable. The result will be an integer between 0 and 100. If the creature is not found, it will return zero.

Example:
get_health_percent CID TEMP

order_walk [var:CID] [int:X] [int:Z]
Looks up an NPC CID, and orders it to walk to the X,Z coordinates at 20% speed. The Y coordinate is elevation, and not changed.

This was recently added an experimental command for an unreleased dungeon and may not work correctly.

Example:
order_walk CID 3300 3800

get_target [var:CID] [var:dest]
Looks up an NPC CID, and places its current target CID in the destination variable. If the NPC does not have a target, the result will be zero.

Example:
get_target CID TEMP

ai_script_jump [var:CID] [str:label name]
Looks up an NPC CID, then forces that creature's AI script to perform an external jump to a certain label. It will perform as a goto or call, depending on how the AI script is set to handle external jumps. Refer to the ScriptCore Reference, exec_queue command, and the #queue_jumps directive for more information.

This may be used to trigger certain interactive behaviors between specially scripted creatures.

Example:
ai_script_jump CID "extTryCastShield"

info [str]
Sends a yellow information message to all players in the instance.

Example:
info "A harmless foe has appeared."

chat [str:name] [str:channel] [str:message]
Sends an arbitrary chat message to all players in the instance. The message will not be attached to a particular creature or player.

Example:
chat "conRed" "Instance" "It worked!"

Metadata Information

Some new directives are available to instance scripts.

#location [str:name] [int:X1] [int:Z1] [int:X2] [int:Z2]
Defines a rectangular location spanning from the top left corner X1,Z1 to the bottom right corner X2,Z2.

Locations are used by the scan_npc_cid command.

Example:
#location LOC_BOSS_ROOM 1800 2700 2400 3200

#location_br [str:name] [int:X] [int:Z] [int:radius]
Defines a square location centered over the X,Z coordinates and has a box radius of a particular width. So if the radius is 100, it will span 100 units east/west/north/south for a total coverage of 200x200 units.

Locations are used by the scan_npc_cid command.

Example:
#location_br LOC_BRAZIER_1 1900 3000 140

Reserved Labels

:onKill_%d
This label is called when an NPC dies, but only if the SpawnPoint allows it.

If the SpawnPoint Sequential property is set to true, then the label will be called directly.

If the mob was spawned by a SpawnPackage, and SpawnPackage::ScriptCall is enabled, it won't call "onKill" but instead a label with exact package name.

%d will reflect the CDefID of the creature that was killed.

Labels will fall through other labels so you can trap kills from multiple types to accomplish a trigger.

Example:

:init
set killcount 0
end

:onKill_1993
:onKill_1994
inc killcount
if killcount >= 6
  spawn 1291845744
endif
end

; Anglor Dren's chest
:onKill_1995
spawn 1291845811
end

:onUse_%d
Called whenever a player begins interacting with an object (except for henges). Interact objects change the mouse cursor to a paw when you hover over them. These objects are typically from quests with an activate or gather objective.

%d will reflect the CDefID of object.

:onUseHalt_%d
Called whenever a player breaks interacting, or is interrupted while attempting to use an object.

%d will reflect the CDefID of object.

:onUseFinish_%d
Called whenever a player successfully finishes using an object.

%d will reflect the CDefID of object.

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).

use [int:AbilityID]
getwill [var:dest]
getwillcharge [var:dest]
getmight [var:dest]
getmightcharge [var:dest]
has_target [var:dest]
getlevel [var:dest]
debugprint [string]
getcooldown [string:Cooldown Name] [var:dest]
is_busy [var:dest]
count_enemy_near [int:range (10 units=1 meter)] [var:dest]
count_enemy_at [int:range (10 units=1 meter)] [var:dest]
health_percent [var:dest]
target_health_percent [var:dest]
set_elapsed_time [var:dest]
time_offset [var:Elapsed Time (ms)] [var:dest Time Since Elapsed (ms)]
visual_effect [string]
visual_effect_t [string]
say [string]
instance_call [string]
get_idle_mob [int:CDefID] [var:dest]
get_target [var:dest CID]
get_self [var:dest CID]
set_other_target [var:CID to Modify] [var:CID to Target]
aiscript_call [var:CID] [label]
is_target_enemy [var:dest]
is_target_friendly [var:dest]
set_speed [integer]
get_target_cdef [var:dest]
get_property [string:Stat Name] [var:dest]
get_target_property [string:Stat Name] [var:dest]
dispel_target_property [string:Stat Name] [int:Sign]
randomize [int:Max Value] [var:dest]
find_cdef [int:CDefID] [var:dest]
play_sound [str:Package|FileName.ogg]
get_buff_tier [int:AbilityGroupID] [var:dest]
get_target_buff_tier [int:AbilityGroupID] [var:dest]
target_in_range [int:range (10 units=1 meter)] [var:dest]
get_target_range [var:dest]
set_gtae
get_speed [var:CID] [var:dest]
cid_is_busy [var:CID] [var:dest]