AI Scripting Reference

Commands for Unreal 2's AI Scripting system.

Commands

addammo: ammostring amount [maxclip] gives N units of specified ammo to NPC, if maxclip=1 makes sure clip is as full as possible
agentbind: inputname valuename sets and locks an agent input to a given value, for characters with agent-driven meshes
agentcall: actionname [wait] calls an agent action of the given name, for characters with agent-driven meshes
agentexecute: actiontext [wait] compiles and executes a GAL string on-the-fly as if were inside an action, and calls it
agentunbind: inputname unlocks an agent input previously locked and set with AgentBind
animloop: name [rate tweentime [wait]] loops specified anim on channel 0
animloopex: channel name [rate tweentime [wait]] loops specified anim on arbitrary channel
animplay: name [rate tweentime [wait]] plays specified anim on channel 0
animplayex: channel name [rate tweentime [wait]] plays specified anim on arbitrary channel
animrelease: allow NPC to control anims (currently idle only)
animtween: name [tweentime [wait]] tweens specified anim on channel 0
animtweenex: channel name [tweentime [wait]] tweens specified anim on arbitrary channel
call: label pushes line after current one and jumps to given label
callscript: scriptname pushes current script state and switches to specified file
callend: aborts any previously pushed call (can no longer return)
clearevents: clears any current onevents
cleartimers: clears any current general timers
cleartriggers: clears any current ontriggers
consolecommand: command executes given console command
debugai: 0/1 enables/disables debug AI mode in controlled NPC
debugaievents: 0/1 enables/disables debug events mode in controlled NPC
debugaiflags: ### explicitely sets debug AI flags in controlled NPC
debugmode: flags enables/disables various debug modes for the script controller
decproperty: name property value [#] decrements (integer) property in named actor by 1 or by #
deployinventory: S [1] deploy given inventory item [alt deploy it]
destroy: destroy controlled NPC (and controller)
dialogdisable: topicname disable this dialog node
dialogenable: topicname enable this dialog node
dialogfar: topicname speaker1 [speaker2] starts dialog b/w 2 npcs regardless of distance
dialogfarwait: topicname speaker1 [speaker2] waits for dialog b/w 2 npcs to finish
dialoginitiate: speaker topicname tries to initiate given dialog with given target
dialogterminate: speaker tries to remove NPC from dialog
directionalpatrol: 0/1 whether NPC faces in direction of patrol destination
dormant: 0/1 [1] toggle whether NPC (Pawn and Controller) is dormant (bStasis=true and Physics=PHYS_None) [1] means stay dormant even if script removed?
dropinventory: S drop given inventory item
enableprobeevent: probename 0|1 enables/disables NPC probe event (for performance) e.g. enableprobeevent seeplayer 0 → no more seeplayer events
enablexmphandling: 0/1 enables/disables NPC reacting to XMP items (inert 0/1 sets this to 1/0 use enablexmphandling 0/1 to override this).
error: used internally
eventdisable: event disables event
eventenable: event enables event
eventwait: event waits until event occurs
findactor: [name Min Max Type Vis Num gotolabel targetlabel] searches for actors in level (all args optional)
fire: [duration] fire (weapon / animation-based) for given duration
firealt: [duration] alt fire (weapon / animation-based) for given duration
gib: [bDestroy] [gorelevel] gib controlled NPC. If gib fails, bDestroy determines if npc is killed or destroyed. Gore level overrides the gibset's default gore level
giball: targetclass [bDestroy] [gorelevel] gib all actors of the given class. . If gib fails, bDestroy determines if npc is killed or destroyed. Gore level overrides the gibset's default gore level
giveinventory: inventorystring gives the specified inventory item to the NPC
giveitemtoplayer: inventorystring [ammocount] give item to player, if ammocount treats as ammo and adds this much ammo to player's inventory
givetosseditem: inventorystring add item to tossed items list
gotoactor: targetname [dist [face]] sends NPC to specifed actor at specified dist (error if target not found), face=1 ==> try to face target (e.g. for initiating dialog)
gotoactorsafe: targetname [dist [face]] sends NPC to specifed actor at specified dist (not an error if target not found), face=1 ==> try to face target (e.g. for initiating dialog)
gotolabel: label jumps to given label
incproperty: name property value [#] increments (integer) property in named actor by 1 or by #
inert: 0/1 toggles NPC reacting to sensory input – shorthand for toggling bump, hearnoise, seeplayer, tookdamage
handlergroup: denotes start of a new handler groups (can't be in one currently?)
handlergroupend: denotes end of a new handler groups (must be in one currently)
headtracking: 0/1
jump: X Y Z launch NPC in given direction
kill: kill controlled NPC (goes into dying state)
killall: targetclass kill all actors of the given class
lockstep: name [f] maintain given or current distance from named actor (for keeping squads in formation)
message: string [0|1|2] displays the given message in-game (surround with "" for multiple words) 0: onscreen 1: log 2: onscreen and log
onevent: xxx [gotolabel ### [clear]] when event xxx occurs, jumps to given label (or disables previous onevent)
ontimer: index [delay repeat gotolabel ###] adds a general-purpose timer
ontrigger: name [gotolabel ###] when trigger with given event name occurs, jumps to given label (or disables previous ontrigger)
playsound: name sound [slot [volume [bNoOverride [Radius [Pitch]]]]] plays sound through named actor (or self=controlled NPC)
playsoundwait: name sound [slot [volume [bNoOverride [Radius [Pitch]]]]] plays sound through named actor (or self=controlled NPC) and script waits for sound to finish
playsoundtableslot: name slot play sound belonging to the specified group from named pawn's sound table
playsoundtableslotwait: name slot play sound belonging to the specified group from named pawn's sound table and script waits for sound to finish
removeinventory: [string] removes all [or the specified] inventory from the NPC
removeinventoryfromplayer: [string] removes all [or the specified] inventory from the player
removeitemfromplayer: inventorystring add item to player's inventory
removetosseditem: inventorystring remove item from tossed items list
resumepatrol: startlabel endlabel finds the "best" destination at which the resume patrolling and jumps to that line
return: returns to most recently pushed line or script state (error if no applicable)
rotate: #.# rotate #.# degrees clockwise (right) relative to forward
savedestination: copies GotoActorTarget into SavedDestination for later use with resumepatrol
sendevent: EventName [triggerpawns] triggers all Actors with tag that matches given Event, or all NPCs
setactorrangetest: target distance sets the InRangeActor and InRangeDistance for ActorInRange/ActorOutOfRange events
setaimodds: odds sets odds of hitting target when firing weapon under script control
setalert: 0/1 controls whether NPC uses "alert" animations
setammo: ammostring amount [maxclip] makes sure NPC has exactly specified amount of given type of ammo, if maxclip=1 makes sure clip is as full as possible
setfocus: [name] set scripted focus to given actor or clear focus
sethealth: x.x sets controlled NPC's health to x.x
setinventory: targetname inventorystring sets target's selected inventory to x.x
setlocation: locationname [allowfail] move pawn to location of locationame
setlocationnamed: targetname locationname [allowfail] move actor matching targetname to location of locationame
setlocationvector: targetname X Y Z move targetname to given coordinates
setmovespeed: speed [stance] 0.01 to MaxDesiredSpeed (usually 1.0) – set speed used for scripted movement
setmovespeedauto: speed 0.01 to MaxDesiredSpeed (usually 1.0) – set speed used for autonomous movement
setorders: orders [OrdersObject [fparam [ordergiver]]] sets/clears orders
setphysics: physics
setproperty: targetname property value sets property in named actor to value
setproperties: classname property value sets given property in all actors which are a classname
setsatellite: satellitename [targetname] binds a mesh satellite node of the given name to the given target, for dynamic animations
setscript: filename [startlabel] switches over to the given script [at the given label]
setskill: skill set NPC's skill to given value (0.0..1.0)
setstance: stand / crouch / prone specifies stance that NPC should use while patrolling
setstationary: 1/0 [1] makes NPC immobile/mobile, optionally forever
settacticalmovetype: 0/1/2 sets tactical move type to use during scripted movement (0: none 1: basic 2: serpentine)
setweapon: weaponstring set NPC's weapon to specified one, spawning it if necessary
shutdown: 1/0 makes NPC as inert as possible without actually making it dormant or removing its controller
sleep: [x.x] puts controller to sleep for x.x seconds (defaults to "forever")
sleeprand: [x.x] puts controller to sleep for random time in 0..x.x seconds (x.x defaults to 1.0)
spawn: targetname S [1 [filename [startlabel]]] spawn given actor at targetname's location, if 1 is given, failure = error, optionally gives spawned NPCs a script
stop: stops execution, detaches script controller
stopmovement: stops NPC movement
stopsound: slot [bStopNoOverrideSounds] stops any sounds played through the named actor on the specified sound slot
testactorinrange: name distance if given actor is outside given distance of pawn ==> next command skipped
testproperty: name property value property != value ==> next command skipped (string comparison)
testpropertyci: name property value property != value ==> next command skipped (case-insensitive string comparison)
testpropertye: name property value property != value ==> next command skipped (numerical comparison)
testpropertyg: name property value property <= value ==> next command skipped (numerical comparison)
testpropertyge: name property value property < value ==> next command skipped (numerical comparison)
testpropertyl: name property value property >= value ==> next command skipped (numerical comparison)
testpropertyle: name property value property > value ==> next command skipped (numerical comparison)
testrandom: float (if random number in 0.0..1.0 > value ==> next command skipped)
teststate: name name (false ==> next command skipped)
turntoactor: targetname [LOS [Lock]] turn NPC to face named actor, LOS=0 ==> LOS not needed, LOS=1 ==> LOS needed, LOS=2 ==> LOS not needed but turn anyway, Lock means target actor won't be cleared
unuse: name unuse the named actor
use: name use the named actor
usepickups: 0/1 if 0, won't go after or pickup pickups
weaponload: load current weapon
WeaponSetAmmoType: ammoname
WeaponSupportsAltFire: weaponname 0/1 disables/enables NPC being able to alt fire weapon
WeaponSupportsFire: weaponname 0/1 disables/enables NPC being able to primary fire weapon

Events

ActorInRange: generated when the InRangeActor comes within the InRangeDistance
ActorOutOfRange: generated once when the InRangeActor comes goes out of the InRangeDistance
AnimEnd: goes to Controller unless Pawn has no Controller (dying state)
AutoBegin: goes to Controller, generated by U2NPCControllerScriptable
AutoEnd: goes to Controller, generated by Controller : seems to be used for after fighting conditions
BumpEnemy: NotifyBump –> Controller –> BumpEnemy/Friend/Other
BumpFriend: NotifyBump –> Controller –> BumpEnemy/Friend/Other
BumpOther: NotifyBump –> Controller –> BumpEnemy/Friend/Other
BumpPlayer: not an actual event: eventwait BumpPlayer –> BumpEnemy/BumpFriend checked for player
DestinationReached: goes to Controller
DialogBegin: generated by Controller before destroyed
DialogUnPause: generated when dialog unpauses npc's script
Died: generated by Controller before destroyed
EnemyNotVisible: goes to Controller
HearNoiseFriendly: HearNoise –> Controller –> HearNoiseFriendly
HearNoiseOther: HearNoise –> Controller –> HearNoiseOther
HearNoiseThreat: HearNoise –> Controller –> HearNoiseThreat
InheritEnemy: generated when NPC could inherit another NPC's Enemy
ScriptedLanding: generated when NPC in scripted state lands (not passed back to NPC)
SeeAlertFriend: SeeAlertFriend –> Controller
SeeEnemy: SeeEnemy –> Controller
SeeFriend: SeeFriend –> Controller –> SeeFriend
SeeOther: SeeOther –> Controller –> SeeOther
SeePlayer: not an actual event: eventwait SeePlayer –> SeeEnemy/SeeFriend checked for player
TakeDamage: goes to Pawn
TookDamage: eventTakeDamage –> TookDamage generated by U2NPCControllerScriptable
TookDamageEnemy: generated internall from TookDamage for use by scripts only
TookDamageFriend: generated internall from TookDamage for use by scripts only
Trigger: goes to Pawn then Controller

Discussion

Unknown: Maybe explain what these are and where to put them?

Unknown: I'll put that stuff in Basic AI Scripting Tutorial when I make it.

SuperApe: This page needs help. Is it purely U2? It should be applicable to all versions. Since, I'm working on the Basic AI Scripting Tutorial, I may revise this.

Category Mapping

Category To Do – This page needs to be updated and made relevant to all Unreal versions as well as the current wiki structure.

AI Scripting Reference

Commands

Events

Related Topics

Discussion