Menu
Lumberyard
Developer Guide (Version 1.11)

Signals Reference

A typical signal handler looks something like this:

Copy
OnEnemySeen = function(self, entity, distance) -- called when the AI sees a living enemy end,

Parameters self (behavior table) and entity (entity table) are passed to every signal. Additional parameters are specific to the signal being used.

See also: \Game\Scripts\AI\Behaviors\Template.lua.

Perception Signals

The following signals are sent to AI agents when perception types of their attention targets change.

Note that AITHREAT_SUSPECT < AITHREAT_INTERESTING < AITHREAT_THREATENING < AITHREAT_AGGRESSIVE.

No Target

Name Parameters Description
OnNoTarget Attention target is lost

Sound

Sound heard (no visible target).

Name Parameters Description
OnSuspectedSoundHeard Threat is AITHREAT_SUSPECT
OnInterestingSoundHeard Threat is AITHREAT_INTERESTING
OnThreateningSoundHeard Threat is AITHREAT_THREATENING
OnEnemyHeard Threat is AITHREAT_AGGRESSIVE

Memory

The target is not visible and is in memory.

Name Parameters Description
OnEnemyMemory Threat is AITHREAT_THREATENING
OnLostSightOfTarget Threat is AITHREAT_AGGRESSIVE
OnMemoryMoved Threat is AITHREAT_AGGRESSIVE and its location or owner has changed

Visual

The target is visible.

Name Parameters Description
OnSuspectedSeen Threat is AITHREAT_SUSPECT
OnSomethingSeen Threat is AITHREAT_INTERESTING
OnThreateningSeen Threat is AITHREAT_THREATENING
OnEnemySeen distance Threat is AITHREAT_AGGRESSIVE
OnObjectSeen distance, data AI sees an object registered for this signal. data.iValue = AI object type (e.g. AIOBJECT_GRENADE or AIOBJECT_RPG)
OnExposedToExplosion data AI is affected by explosion at data.point
OnExplosionDanger Destroyable object explodes

Awareness of Player

Name Parameters Description
OnPlayerLooking sender, data Player is looking at the AI for entity.Properties.awarenessOfPlayer seconds. data.fValue = player distance
OnPlayerSticking sender Player is staying close to the AI since <entity.Properties.awarenessOfPlayer> seconds
OnPlayerLookingAway sender Player has just stopped looking at the AI
OnPlayerGoingAway sender Player has just stopped staying close to the AI

Awareness of Attention Target

Name Parameters Description
OnTargetApproaching
OnTargetFleeing
OnNewAttentionTarget
OnAttentionTargetThreatChanged
OnNoTargetVisible
OnNoTargetAwareness
OnSeenByEnemy sender AI is seen by the enemy

Weapon Damage

Name Parameters Description
OnBulletRain sender Enemy is shooting
OnDamage sender, data AI was damaged by another friendly/unknown AI. data.id = damaging AI's entity id
OnEnemyDamage sender, data AI was damaged by an enemy AI. data.id = damaging enemy's entity id

Proximity

Name Parameters Description
OnCloseContact enemy gets at a close distance to an AI (defined by Lua Property "damageRadius" of this AI)
OnCloseCollision

Vehicles

Name Parameters Description
OnVehicleDanger sender, data vehicle is going towards the AI. data.point = vehicle movement direction, data.point2 = AI direction with respect to vehicle
OnEndVehicleDanger
OnTargetTooClose sender, data attention target is too close for the current weapon range (it works only if AI is a vehicle)
OnTargetTooFar sender, data attention target is too close for the current weapon range (it works only if AI is a vehicle)
OnTargetDead

User-defined

Custom signals can be sent when an attention target enters or leaves certain ranges. This is configured using the following Lua functions:

Copy
AI.ResetRanges(entityID); AI.AddRange(entityID,range, enterSignal, leaveSignal); AI.GetRangeState(entityID, rangeID); AI.ChangeRange(entityID, rangeID, distance);

Weapon-Related Signals

Name Parameters Description
OnLowAmmo
OnMeleeExecuted
OnOutOfAmmo
OnReload AI goes into automatic reload after its clip is empty
OnReloadDone reload is done
OnReloaded

Navigation Signals

Pathfinding

Name Parameters Description
OnEndPathOffset sender AI has requested a path and the end of path is far from the desired destination
OnNoPathFound sender AI has requested a path which is not possible
OnPathFindAtStart
OnBackOffFailed sender AI tried to execute a "backoff" goal which failed
OnPathFound sender AI has requested a path and it's been computed successfully

Steering

Name Parameters Description
OnSteerFailed

Smart Objects

Name Parameters Description
OnEnterNavSO
OnLeaveNavSO
OnUseSmartObject

Navigation Shapes

Name Parameters Description
OnShapeEnabled
OnShapeDisabled

Tactics Signals

Tactical Point System

Name Parameters Description
OnTPSDestNotFound
OnTPSDestFound
OnTPSDestReached

Cover

Name Parameters Description
OnHighCover
OnLowCover
OnMovingToCover
OnMovingInCover
OnEnterCover
OnLeaveCover
OnCoverCompromised

Groups Signals

Name Parameters Description
OnGroupChanged
OnGroupMemberMutilated
OnGroupMemberDiedNearest

Formation

Name Parameters Description
OnNoFormationPoint sender AI couldn't find a formation point
OnFormationPointReached
OnGetToFormationPointFailed

Group Coordination

Group target is the most threatening target of the group.

Name Parameters Description
OnGroupTargetNone
OnGroupTargetSound
OnGroupTargetMemory
OnGroupTargetVisual
PerformingRole

Flow Graph Signals

These are signals sent by corresponding Flow Graph nodes when they are activated.

Name Parameters Description
ACT_AIMAT AI:AIShootAt
ACT_ALERTED AI:AIAlertMe
ACT_ANIM AI:AIAnim
ACT_ANIMEX AI:AIAnimEx
ACT_CHASETARGET Vehicle:ChaseTarget
ACT_DIALOG AI:ReadabilityDialog (also sent by Dialog System)
ACT_DIALOG_OVER Sent by Dialog System
ACT_DUMMY
ACT_DROP_OBJECT AI:AIDropObject
ACT_ENTERVEHICLE Vehicle:Enter
ACT_EXECUTE AI:AIExecute
ACT_EXITVEHICLE Vehicle:Exit, Vehicle:Unload
ACT_FOLLOW AI:AIFollow
ACT_FOLLOWPATH AI:AIFollowPath, AI:AIFollowPathSpeedStance, Vehicle:FollowPath
ACT_GRAB_OBJECT AI:AIGrabObject
ACT_GOTO AI:AIGoto, AI:AIGotoSpeedStance, and the AI Debugger when the user clicks the middle mouse button.
ACT_JOINFORMATION AI:AIFormationJoin
ACT_SHOOTAT AI:AIShootAt
ACT_USEOBJECT AI:AIUseObject
ACT_VEHICLESTICKPATH Vehicle:StickPath
ACT_WEAPONDRAW AI:AIWeaponDraw
ACT_WEAPONHOLSTER AI:AIWeaponHolster
ACT_WEAPONSELECT AI:AIWeaponSelect

Other Signals

Forced Execute

Name Parameters Description
OnForcedExecute
OnForcedExecuteComplete

Animation

Name Parameters Description
AnimationCanceled

Game

Name Parameters Description
OnFallAndPlay

Vehicle-related

Name Parameters Description
OnActorSitDown Actor has entered a vehicle

Squads

Name Parameters Description
OnSomebodyDied
OnBodyFallSound
OnBodyFallSound
OnUnitDied
OnSquadmateDied
OnPlayerTeamKill
OnUnitBusy
OnPlayerDied

Name Parameters Description
OnFriendInWay sender AI is trying to fire and another friendly AI is on his line of fire
URPRISE_ACTION
OnActionDone data AI action of this agent was finished. data.ObjectName is the action name, data.iValue is 0 if action was cancelled or 1 if it was finished normally, data.id is the entity id of "the object" of the AI action