Menu
Lumberyard
Developer Guide (Version 1.11)

ScriptBind_AI

CryLua is deprecated and will be removed in a future version of Lumberyard.

Lists C++ AI functions that can be called from Lua scripts.

AbortAction

Aborts execution of a specified action.

Syntax

Copy
AI.AbortAction(userId [, actionId ])

Parameter Description
userId The ID of the entity.
actionId (optional) Unique ID of the action to be aborted. If 0 (or nil), all actions on the specified entity are aborted.

AddAggressiveTarget

Adds a target to a specified entity's list as an aggressive potential target.

Syntax

Copy
AI.AddAggressiveTarget(entityId, targetId)

Returns True if successfully added.

Parameter Description
entityId The ID of the entity.
targetId Target's entity ID to add.

AddCombatClass

Creates new combat class.

Syntax

Copy
AI.AddCombatClass(int combatClass, SmartScriptTable pTable, const char* szCustomSignal)

Parameter Description
combatClass Combat class to add.
pTable Parameters table.
szCustomSignal Specifies optional custom OnSeen signal.

AddFormationPoint

Adds a follow-type node to a formation descriptor.

Syntax

Copy
AI.AddFormationPoint(name, sightangle, distance, offset, [unit_class [,distanceAlt, offsetAlt]])

Parameter Description
name Name of the formation descriptor.
sightangle Angle of sight of the node (-180,180; 0 = the entity looks forward).
distance Distance from the formation's owner.
offset Offset along the following line (negative = left, positive = right).
unit_class Class of soldier (see eSoldierClass definition in IAgent.h).

DistanceAlt (optional): alternative distance from the formation owner

offsetAlt (optional): alternative offset.

AddFormationPointFixed

Adds a node with a fixed offset to a formation descriptor.

Syntax

Copy
AI.AddFormationPointFixed(name, sightangle, x, y, z [,unit_class])

Parameter Description
name Name of the formation descriptor.
sightangle Angle of sight of the node (-180,180; 0 = the entity looks forward).
x, y, z Offset from formation owner.
unit_class Class of soldier (see eSoldierClass definition in IAgent.h).

AddPatternBranch

Creates a branch pattern at the specified node. When the entity has approached the specified node (nodeName) and it is time to choose a new point, the rules defined by this function are used to select the new point. This function can associate multiple target points and an evaluation rule.

Syntax

Copy
AI.AddPatternBranch(nodeName, method, branchNode1, branchNode2, ..., branchNodeN)

Parameter Description
nodeName Name of the node to add branches to.
method Method used to choose the next node. Valid values include:
  • AITRACKPAT_CHOOSE_ALWAYS – Choose the next point from the list in linear sequence.

  • AITRACKPAT_CHOOSE_LESS_DEFORMED – Choose the least deformed point in the list. Each node is associated with a deformation value (percentage), which describes how much it must move in order to stay within the physical world. These deformation values are summed down to the parent nodes so that deformation at the end of the hierarchy will be caught down the hierarchy.

  • AITRACKPAT_CHOOSE_RANDOM – Choose a point in the list randomly.

AddPatternNode

Adds a point to the track pattern.

When validating the points, the test is performed from the start position to the end position. Start position is either the pattern origin or, if the parent is provided, the parent position. The end position is either the relative offset from the start position or from the pattern origin; this position is chosen based on the node flag. The offset is clamped to the physical world based on the test method. The points will be evaluated in the same order they are added to the descriptor, and the system does not try to correct the evaluation order. If hierarchies are used (parent name is defined), it is up to the pattern creator to make sure the nodes are created in such an order that the parent is added before it is referenced.

Syntax

Copy
AI.AddPatternNode(nodeName, offsetx, offsety, offsetz, flags, [parent], [signalValue])

Parameter Description
nodeName Name of the new point. , Point names are local to the current pattern.
offsetx, offsety, offsetz Offset from the start position or from the pattern center. See AITRACKPAT_NODE_ABSOLUTE.
flags Track pattern functionality flags.

Node evaluation flags:

  • AITRACKPAT_NODE_START – Node can be used as the first node in the pattern. There can be multiple start nodes. In that case the closest one is chosen.

  • AITRACKPAT_NODE_ABSOLUTE – Interpret offset as an offset from the pattern center (otherwise the offset is from the start position).

  • AITRACKPAT_NODE_SIGNAL – A signal "OnReachedTrackPatternNode" will be sent when the node is reached.

  • AITRACKPAT_NODE_STOP – Advancing will be stopped. It can be continued by calling entity:ChangeAIParameter(AIPARAM_TRACKPATTERN_ADVANCE, 1).

  • AITRACKPAT_NODE_DIRBRANCH – For the direction at each pattern node, use the average direction to the branch nodes (otherwise use the direction from the node position to the center of the pattern).

parent (optional) Parent node position, which will be used as the start position instead of the pattern center.
signalValue (optional) If the signal flag is set, this value is passed as a signal parameter, accessible from the signal handler in data.iValue.

AddPersonallyHostile

Syntax

Copy
AI.AddPersonallyHostile(ScriptHandle entityID, ScriptHandle hostileID)

AgentLookAtPos

Causes the specified entity to look at a certain position.

Syntax

Copy
AI.AgentLookAtPos(entityId, Vec3 pos)

Parameter Description
entityId The ID of the entity.
pos Vec3 to look at.

AllowLowerBodyToTurn

Syntax

Copy
AI.AllowLowerBodyToTurn(entityID, bAllowLowerBodyToTurn)

Parameter Description
entityId Entity ID of the agent you want to set the look style to.
bAllowLowerBodyToTurn. True if you want to allow the turning movement of the body, false otherwise.

BeginTrackPattern

Begins the definition of a new track pattern descriptor. The pattern is created by calling AI.AddPatternPoint() and AI.AddPatternBranch(), and finalized by calling AI.EndTrackPattern().

Syntax

Copy
AI.BeginTrackPattern(patternName, flags, validationRadius, [stateTresholdMin],

Parameter Description
patternName Name of the new track pattern descriptor.
flags Track pattern functionality flags.

Validation flags describe how the pattern is validated to fit the physical world:

  • AITRACKPAT_VALIDATE_NONE – No validation. AITRACKPAT_VALIDATE_SWEPTSPHERE – Validate using swept sphere tests, where the spehre radius equals the validation radius plus the entity pass radius.

  • AITRACKPAT_VALIDATE_RAYCAST – Validate using raycasting, where the hit position is pulled back by the amount of validation radius plus the entity pass radius.

Alignment flags describe how, when the pattern is selected to be used, the alignment of the pattern can be changed. Flags are evaluated in the following order:

  • AITRACKPAT_ALIGN_TO_TARGET – Align the pattern so that the y-axis points towards the target each time it is set. If the agent does not have a valid attention target at the time, the pattern is aligned to the world.

  • AITRACKPAT_ALIGN_RANDOM – Align the pattern randonly each time it is set. The rotation ranges are set using SetRandomRotation().

validationRadius Validation radius is added to the entity pass radius when validating the pattern along the offsets.
stateTresholdMin (optional) If the state of the pattern is 'enclosed' (high deformation) and the global deformation < stateTresholdMin, the state becomes exposed. Default 0.35.
stateTresholdMax (optional) If the state of the pattern is 'exposed' (low deformation) and the global deformation > stateTresholdMax, the state becomes enclosed. Default 0.4.
globalDeformTreshold (optional) Deformation of the whole pattern is tracked in range [0..1]. This treshold value can be used to clamp the bottom range, so that values in range [trhd..1] becomes [0..1], default 0.0.
localDeformTreshold (optional) Deformation of the each node is tracked in range [0..1]. This treshold value can be used to clamp the bottom range, so that values in range [trhd..1] becomes [0..1], default 0.0.
exposureMod (optional) Importance of the node exposure (how much it is seen by the tracked target) to consider when branching. Valid range is [-1..1], where -1 means to favor unseen nodes and 1 means to favor seen, exposed nodes. Default is 0 (no effect).
randomRotAng (optional) Flag indicating whether or not to randomly rotate the pattern each time it is set. Rotation is performed in XYZ order. This parameter defines angles (in degrees) around each axis.

CanFireInStance

Syntax

Copy
AI.CanFireInStance(entityId, stance)

Returns true if AI can fire at his target in the specified stance at his current position

Parameter Description
entityId The ID of the entity.
stance. Stance Id (STANCE_*).

CanMelee

Determines whether or not the AI is able to do melee attack.

Syntax

Copy
AI.CanMelee(entityId)

Returns True or false (1 or 0).

Parameter Description
entityId The ID of the entity.

CanMoveStraightToPoint

Determines whether or not a specified entity can move in a straight line from its current position to a specified point.

Syntax

Copy
AI.CanMoveStraightToPoint(entityId, position)

Parameter Description
entityId The ID of the entity.
position Position to check path to.

ChangeFormation

Changes the formation descriptor for the current formation of a specified entity's group (if one exists).

Syntax

Copy
AI.ChangeFormation(entityId, name [,scale])

Returns True if the formation change was successful.

Parameter Description
entityId Unique entity ID used to identify the group.
name Name of the formation descriptor.
scale (optional) Scale factor for the formation (1 = default).

ChangeMovementAbility

Changes the value of an AI movement ability parameter for the entity specified.

Syntax

Copy
AI.ChangeMovementAbility(entityId, paramEnum, paramValue)

Parameter Description
entityId The ID of the entity.
paramEnum Index of the parameter to change. Valid values include:
  • AIMOVEABILITY_OPTIMALFLIGHTHEIGHT – Optimal flight height in meters while finding path.

  • AIMOVEABILITY_MINFLIGHTHEIGHT – Minimum flight height in meters while finding path.

  • AIMOVEABILITY_MAXFLIGHTHEIGHT – Maximum flight height in meters while finding path.

paramValue New value for the specified parameter.

ChangeParameter

Updates a parameter value for a specified entity.

Syntax

Copy
AI.ChangeParameter(entityId, paramEnum, paramValue)

Parameter Description
entityId The ID of the entity.
paramEnum The enum of the parameter.
paramValue The new value for the specified parameter.

CheckForFriendlyAgentsAroundPoint

Syntax

Copy
AI.CheckForFriendlyAgentsAroundPoint(ScriptHandle entityID, Vec3 point, float radius)

CheckMeleeDamage

Determines whether or not the AI performing melee is actually hitting target.

Syntax

Copy
AI.CheckMeleeDamage(entityId, targetId, radius, minheight, maxheight, angle)

Returns (distance,angle) pair between entity and target (degrees) if melee is possible, nil otherwise

Parameter Description
entityId The ID of the entity.
targetId Target's entity ID.
radius. max distance in 2d to target.
minheight. min distance in height.
maxheight. max distance in height.
angle. FOV to include target.

ClearAnimationTag

Syntax

Copy
AI.ClearAnimationTag(ScriptHandle entityID, const char* tagName)

Parameter Description
entityId AI's entity.
tagName. .

ClearMovementContext

Resets the specified entity's movement context.

Syntax

Copy
AI.ClearMovementContext(entityId)

Parameter Description
entityId The ID of the entity.
context. context value.

ClearPotentialTargets

Clears all the potential targets from a specified entity's perception handler.

Syntax

Copy
AI.ClearPotentialTargets(entityId)

Parameter Description
entityId The ID of the entity.

ClearTempTarget

Removes the specified entity's temporary potential target so that it is no longer considered for target selection.

Syntax

Copy
AI.ClearTempTarget(entityId)

Returns True if successfully updated.

Parameter Description
entityId The ID of the entity.

ConstrainPointInsideGenericShape

Syntax

Copy
AI.ConstrainPointInsideGenericShape(position, shapeName[, checkHeight])

Returns Nearest point inside the specified shape.

Parameter Description
position Position to check.
shapeName Name of the shape to test (returned by AI.GetEnclosingGenericShapeOfType).
checkHeight (optional) Flag indicating whether or not to test for shape height. (default=false). If set to true, the test will check the space between shape.aabb.min.z and shape.aabb.min.z+shape.height.

CreateFormation

Creates a formation descriptor and adds a fixed node at 0,0,0 (owner's node).

Syntax

Copy
AI.CreateFormation(name)

Parameter Description
name Name of the new formation descriptor.

CreateGroupFormation

Creates a group formation with leader (or updates leader).

Syntax

Copy
AI.CreateGroupFormation(entityId, leaderId)

Parameter Description
entityId AI's entity.
leaderId. New leader.

CreateStimulusEvent

Creates a target track stimulus event for the specified entity.

Syntax

Copy
AI.CreateStimulusEvent(ScriptHandle ownerId, ScriptHandle targetId, const char* stimulusName, SmartScriptTable pData)

Parameter Description
ownerId Unique ID of the entity that owns and receives the event.
targetId Unique ID of the entity that sends the event and becomes the target.
stimulusName Name of the stimulus event.
pData Event data (see TargetTrackHelpers::SStimulusEvent).

CreateTempGenericShapeBox

Creates a temporary box-shaped generic shape. This temporary shape will be destroyed upon an AI system reset.

Syntax

Copy
AI.CreateTempGenericShapeBox(Vec3 center, float radius, float height, int type)

Returns Shape name.

Parameter Description
center. Center point of the box.
radius. Size of the box in x and y directions.
height Height of the box.
type Box shape type (AIAnchor).

DebugReportHitDamage

Creates a debug report for the hit damage.

Syntax

Copy
AI.DebugReportHitDamage(pVictimEntity, pShooterEntity)

Parameter Description
pVictimEntity. Victim ID.
pShooterEntity. Shooter ID.

DestroyAllTPSQueries

Destroys all the tactical point system queries.

Syntax

Copy
AI2.DestroyAllTPSQueries()

DistanceToGenericShape

Syntax

Copy
AI.DistanceToGenericShape(Vec3 position, const char* shapeName[, int checkHeight])

Returns True if the point is inside the specified shape.

Parameter Description
position Position to check.
shapeName Name of the shape to test (returned by AI.GetEnclosingGenericShapeOfType).
checkHeight (optional) Flag indicating whether or not to test for shape height. (default=false). If set to true, the test will check the space between shape.aabb.min.z and shape.aabb.min.z+shape.height.

DropTarget

Clears the target from a specified entity's perception handler.

Syntax

Copy
AI.DropTarget(entityId, targetId)

Parameter Description
entityId The ID of the entity.
targetId Target's entity ID.

EnableCoverFire

Enables or disables fire when the FIREMODE_COVER is selected.

Syntax

Copy
AI.EnableCoverFire(entityId, enable)

Parameter Description
entityId The ID of the entity.
enable Boolean.

EnableFire

Enables or disables fire.

Syntax

Copy
AI.EnableFire(entityId, enable)

Parameter Description
entityId The ID of the entity.
enable Boolean.

EnableUpdateLookTarget

Syntax

Copy
AI.EnableUpdateLookTarget(ScriptHandle entityID, bool bEnable)

EnableWeaponAccessory

Enables or disables certain weapon accessory usage.

Syntax

Copy
AI.EnableWeaponAccessory(entityId, int accessory, bool state)

Parameter Description
entityId The ID of the entity.
accessory Enum of the accessory to enable. Possible values (see enum EAIWeaponAccessories in the IAgent.h file):
Copy
AIWEPA_NONE = 0, AIWEPA_LASER = 0x0001 AIWEPA_COMBAT_LIGHT = 0x0002 AIWEPA_PATROL_LIGHT = 0x0004
state Set to true or false to enable or disable.

EndTrackPattern

Finalizes the track pattern definition. This function should always called to finalize the pattern. Failing to do so will cause erratic behavior.

Syntax

Copy
AI.EndTrackPattern()

Error

The fallback error message used when the system experiences an unhandled exception. The code following should continue if it is running in the editor so that the original cause of the problem can be fixed, but halt execution when it is running in the game.

Syntax

Copy
AI.Error(szMessage)

Parameter Description
szMessage The message to write to the log.

EvalPeek

Determines whether or not specified entity can peek from its current position.

Syntax

Copy
AI.EvalPeek(entityId [, bGetOptimalSide])

Returns One of the following values:

  • -1 – don't need to peek

  • 0 – cannot peek

  • 1 – can peek from left

  • 2 – can peek from right

  • 3 – can peek from left & right

Parameter Description
entityId The ID of the entity.
bGetOptimalSide (optional) Flag indicating whether or not to return the side that best fits the attention target's current location, if the AI object can peek from both sides. The default is false.

ExecuteAction

Executes an action on a set of participants.

Syntax

Copy
AI.ExecuteAction(action, participant1 [, participant2 [, ... , participantN ] ])

Parameter Description
action The smart object action name or ID.
participant1 The entity ID of the first participant in the action.
participant2..N (optional) The entity ID of additional participants.

FindObjectOfType

Searches for the closest AIObject of a specified type in an area around a specified entity or position. Once an AIObject is found, it is devalued and can't be found again for a certain number of seconds (unless turned off in flags).

Syntax

Copy
AI.FindObjectOfType(entityId, radius, AIObjectType, flags [,returnPosition [,returnDirection]]) AI.FindObjectOfType(position, radius, AIObjectType, [,returnPosition [,returnDirection]])

Returns The found AIObject's name.

Parameter Description
entityId Unique entity ID used to determine the center position of the search.
position Vector specifying the center position of the search.
radius Radius of the search area.
AIObjectType AIObject type to search for (see ScriptBindAI.cpp and Scripts/AIAnchor.lua for a complete list of AIObject types).
flags. A combination of one or more of the following search filter flags:
  • AIFAF_VISIBLE_FROM_REQUESTER – Requires whoever is requesting the object to also have a line of sight to it.

  • AIFAF_VISIBLE_TARGET– Requires a line of sight between target and anchor.

  • AIFAF_INCLUDE_DEVALUED – Include devalued objects.

  • AIFAF_INCLUDE_DISABLED – Include disabled objects.

returnPosition (optional) Position of the found object.
returnDirection (optional) Direction of the found object.

FindStandbySpotInShape

Syntax

Copy
AI.FindStandbySpotInShape(centerPos, targetPos, anchorType)

FindStandbySpotInSphere

Syntax

Copy
AI.FindStandbySpotInSphere(centerPos, targetPos, anchorType)

FreeSignal

Sends a signal to anyone in a specified radius around a position.

Syntax

Copy
AI.FreeSignal(signalType, signalText, position, radius [, entityID [,signalExtraData]])

Parameter Description
signalType See AI.Signal.
signalText See AI.Signal.
position The center point ({x,y,z} coordinates) from which the signal is sent.
radius The inside radius of the area to which the signal is sent.
entityID Optional. The ID of an entity that is a member of a group that should not receive the signal. Entities whose group ID is the value specified will not be sent the signal.
signalExtraData Optional. See AI.Signal.

GetAIObjectPosition

Retrieves a specified AIObject's position.

Syntax

Copy
AI.GetAIObjectPosition(entityId | AIObjectName)

Returns AI Object position vector {x,y,z}.

Parameter Description
entityId | AIObjectName Unique entity ID or AIObject name.

GetAnchor

Searches for the closest anchor of a specified type in an area around a specified entity. Once an anchor is found, it is devalued and can't be found again for a certain number of seconds (unless turned off in flags).

Syntax

Copy
AI.GetAnchor(entityId, radius, AIAnchorType, searchType [,returnPosition [,returnDirection]])

Returns The found anchor's name.

Parameter Description
entityId Unique entity ID used to determine the center position of the search.
radius Radius of the search area. Alternatively a search range can be specified (min=minRad,max=maxRad).
AIAnchorType Anchor type to search for. See Scripts/AIAnchor.lua for a complete list of anchor types available.
searchType A combination of one or more of the following search filter flags:
  • AIANCHOR_NEAREST – Nearest anchor of the specified type (default).

  • AIANCHOR_NEAREST_IN_FRONT – Nearest anchor of the specified type inside the front cone of the entity.

  • AIANCHOR_NEAREST_FACING_AT – Nearest anchor of the specified type that is oriented towards entity's attention target

  • AIANCHOR_RANDOM_IN_RANGE – Random anchor of the specified type.

  • AIANCHOR_NEAREST_TO_REFPOINT – Anchor of the specified type that is nearest to the entity's reference point.

(optional) returnPosition Position of the found object.
(optional) returnDirection Direction of the found object.

GetAttentionTargetAIType

Retrieves the AI type (AIOBJECT_*) of a specified entity's attention target .

Syntax

Copy
AI.GetAttentionTargetAIType(entityId)

Returns Attention target's AI type, or AIOBJECT_NONE if no target.

Parameter Description
entityId The ID of the entity.

GetAttentionTargetDirection

Retrieves the direction of a specified entity's attention target.

Syntax

Copy
AI.GetAttentionTargetDirection(entityId, returnDir)

Returns Attention target's direction vector {x,y,z}, passed as a return value.

Parameter Description
entityId The ID of the entity.

GetAttentionTargetDistance

Retrieves the distance from a specified entity to its attention target.

Syntax

Copy
AI.GetAttentionTargetDistance(entityId)

Returns distance to the attention target.

Parameter Description
entityId The ID of the entity.

GetAttentionTargetEntity

Retrieves a specified entity's attention target entity (if it is a specified entity), or the owner entity of a dummy object's attention target (if there is an owner entity).

Syntax

Copy
AI.GetAttentionTargetEntity(ScriptHandle entityID)

Returns Attention target's entity.

Parameter Description
entityId The ID of the entity.

GetAttentionTargetOf

Retrieves a specified entity's attention target.

Syntax

Copy
AI.GetAttentionTargetOf(entityId)

Returns Name of attention target. Null if there is no target.

Parameter Description
entityId The ID of the entity.

GetAttentionTargetPosition

Retrieves the position of a specified entity's attention target.

Syntax

Copy
AI.GetAttentionTargetPosition(entityId, returnPos)

Returns Attention target 's position vector {x,y,z}, passed as a return value ().

Parameter Description
entityId The ID of the entity.

GetAttentionTargetThreat

Syntax

Copy
AI.GetAttentionTargetThreat(ScriptHandle entityID)

GetAttentionTargetType

Retrieves the type (AITARGET_*) of a specified entity's attention target.

Syntax

Copy
AI.GetAttentionTargetType(entityId)

Returns Attention target's type, or AITARGET_NONE if no target.

Parameter Description
entityId The ID of the entity.

GetAttentionTargetViewDirection

Retrieves the view direction of a specified entity's attention target.

Syntax

Copy
AI.GetAttentionTargetViewDirection(entityId, returnDir)

Returns Attention target's view direction vector {x,y,z}, passed as a return value.

Parameter Description
entityId The ID of the entity.

GetBeaconPosition

Gets the beacon position for a specified entity/object's group.

Syntax

Copy
AI.GetBeaconPosition(entityId | AIObjectName, returnPos)

Returns True if the beacon is found and the position set.

Parameter Description
entityId | AIObjectName Unique entity ID or AI object name.
returnPos Beacon position vector {x,y,z}.

GetBehaviorBlackBoard

Retrieves a specified AIActor current behaviour's black board (a Lua table).

Syntax

Copy
AI.GetBehaviorBlackBoard(entity)

Returns black board – if there was one nil – Otherwise

Parameter Description
entityId or entityName. An AIActor identifier.

GetBehaviorVariable

Returns a behavior variable for the specified actor.

Syntax

Copy
AI.GetBehaviorVariable(ScriptHandle entityId, const char* variableName)

GetBiasedDirection

Retrieves biased direction of certain point.

Syntax

Copy
AI.GetBiasedDirection(entityId)

Parameter Description
entityId The ID of the entity.

GetCurrentHideAnchor

Retrieves the name of the anchor that the entity currently is using for cover.

Syntax

Copy
AI.GetCurrentHideAnchor(entityId)

Parameter Description
entityId The ID of the entity.

GetDirectAnchorPos

Retrieves the position of a cover point that a specified entity can use to directly attack its attention target.

Syntax

Copy
AI.GetDirectAttackPos(entityId, searchRange, minAttackRange)

Returns Point value, or none if no attack point is available.

Parameter Description
entityId The ID of the entity.
AIAnchorType Anchor type (see Scripts/AIAnchor.lua for a complete list of anchor types).
maxDist Maximum size of search range.

GetDirLabelToPoint

Retrieves a direction label (front=0, back=1, left=2, right_3, above=4, -1=invalid) to the specified point.

Syntax

Copy
AI.GetDirLabelToPoint(entityId, point)

Parameter Description
entityId The ID of the entity.
point The point to evaluate.

GetEnclosingSpace

Returns the estimated surrounding navigable space in meters.

Syntax

Copy
AI.GetEnclosingSpace(entityId, Vec3 pos, float rad)

Parameter Description
entityId The ID of the entity.
pos Check position.
rad Check radius.

GetDistanceAlongPath

Retrieves the distance between a first and second entity, measured along the first entity's path.

Syntax

Copy
AI.GetDistanceAlongPath(entityId1, entityid2)

Returns Distance along a path. Value can be negative if the second entity is ahead along the path.

Parameter Description
entityId1 ID for the first entity.
entityId2 ID for the second entity.

GetDistanceToClosestGroupMember

Syntax

Copy
AI.GetDistanceToClosestGroupMember(ScriptHandle entityId)

GetEnclosingGenericShapeOfType

Retrieves the first shape of a certain type that encloses a specified point.

Syntax

Copy
AI.GetEnclosingGenericShapeOfType(position, type[, checkHeight])

Returns Shape name.

Parameter Description
position Point to search for an enclosing shape.
type Shape type to search for (uses anchor types).
checkHeight (optional) Flag indicating whether or not to test for shape height. (default=false). If set to true, the test checks the space between shape.aabb.min.z and shape.aabb.min.z+shape.height.

GetExtraPriority

Retrieves the extra priority value for a specified enemy entity.

Syntax

Copy
AI.GetExtraPriority(enemyEntityId)

Parameter Description
enemyEntityId. The ID of the entity.

GetFactionOf

Retrieves the faction of the specified entity.

Syntax

Copy
AI.GetFactionOf(ScriptHandle entityID)

Returns the faction of the specified entity.

Parameter Description
entityId The ID of the entity whose faction to return.

GetFormationLookingPoint

Retrieves the looking point position inside the formation.

Syntax

Copy
AI.GetFormationLookingPoint(entityId)

Returns v3 – table with format {x,y,z} storing the looking point position

Parameter Description
entityId AI's entity.

GetFormationPointClass

Adds a follow-type node to a formation descriptor.

Syntax

Copy
AI.GetFormationPointClass(name, position)

Returns class of formation point (-1 if none found).

Parameter Description
name Name of the formation descriptor.
position Point index in the formation (1..N).

GetFormationPointPosition

Retrieves an entity's formation point position.

Syntax

Copy
AI.GetFormationPointPosition(entityId, pos)

Returns true if the formation point has been found.

Parameter Description
entityId The ID of the entity.
pos Return value for the position of the entity's formation point.

GetFormationPosition

Retrieves the relative position inside the formation.

Syntax

Copy
AI.GetFormationPosition(entityId)

Returns v3 – table with format {x,y,z} storing the relative position

Parameter Description
entityId AI's entity.

GetGroupAveragePosition

Retrieves the average position of a group's members.

Syntax

Copy
AI.GetGroupAveragePosition(entityId, properties, returnPos)

Returns the average position.

Parameter Description
entityId Unique entity ID used to determine the group.
unitProperties Binary mask of unit properties type for which the attack is requested, in the following form:

UPR_* + UPR* (UPR_COMBAT_GROUND + UPR_COMBAT_FLIGHT)

See IAgent.h for a definition of unit properties UPR_*.

GetGroupCount

Retrieves the member count of a specified entity's group.

Syntax

Copy
AI.GetGroupCount(entityId, flags, type)

Returns the count of members for the specified group.

Parameter Description
entityId The entity or group ID.
flags A combination of one or more of the following flags:
  • GROUP_ALL – Counts all agents in the group (default).

  • GROUP_ENABLED – Counts enabled agents only (exclusive with all).

  • GROUP_MAX – Include the maximum number of agents during the game (can be combined with all or enabled).

type The AI object type for which to filter. Counts only the AI objects of the type specified. This parameter cannot be used with the GROUP_MAX flag.

GetGroupMember

Returns entity that is at a specified index position in the specified group.

Syntax

Copy
AI.GetGroupMember(entityId|groupId, idx, flags, type)

Returns the script handler of the requested entity, or null if the requested index value is out of range.

Parameter Description
entityId|groupId The entity ID or group ID.
idx Position in the index from 1 to n.
flags A combination of one or more of the following flags:
  • GROUP_ALL – Counts all agents in the group (default).

  • GROUP_ENABLED – Counts enabled agents only (exclusive with all).

type The AI object type for which to filter. Returns only the AI objects of the type specified. This parameter cannot be used with the GROUP_MAX flag..

GetGroupOf

Retrieves the group ID of a specified entity ID.

Syntax

Copy
AI.GetGroupOf(entityId)

Returns the group ID of the specified entity.

Parameter Description
entityId The ID of the entity whose group ID to return.

GetGroupScopeUserCount

Syntax

Copy
AI.GetGroupScopeUserCount(ScriptHandle entityIdHandle, const char* groupScopeName)

Returns the number of actors inside the group scope if greater than or equal to zero, or nil if an error occurs.

Parameter Description
entityId The entity ID of the agent for whom you want to access the group scope.
groupScopeName. The group scope name.

GetGroupScriptTable

Syntax

Copy
AI.GetGroupScriptTable(int groupID)

GetGroupTarget

Retrieves the most threatening attention target among the AI agents in a specified entity's group. See IAgent.h for a definition of alert status.

Syntax

Copy
AI.GetGroupTarget(entityId [,bHostileOnly [,bLiveOnly]])

Parameter Description
entityId Unique entity ID used to determine the group.
bHostileOnly (optional) Flag indicating whether or not to include only hostile targets in group.
bLiveOnly (optional) Flag indicating whether or not to include only live targets in group.

GetGroupTargetCount

Retrieves the number of attention targets among the AI agents in a specified entity's group.

Syntax

Copy
AI.GetGroupTargetCount(entityId [,bHostileOnly [,bLiveOnly]])

Parameter Description
entityId Unique entity ID used to determine the group.
bHostileOnly (optional) Flag indicating whether or not to include only hostile targets in group.
bLiveOnly (optional) Flag indicating whether or not to include only live targets in group.

GetGroupTargetEntity

Syntax

Copy
AI.GetGroupTargetEntity(int groupID)

GetGroupTargetThreat

Syntax

Copy
AI.GetGroupTargetThreat(int groupID)

GetGroupTargetType

Syntax

Copy
AI.GetGroupTargetType(int groupID)

GetLastUsedSmartObject

Retrieves the smart object last used by the user specified.

Syntax

Copy
AI.GetLastUsedSmartObject(userEntityId)

Returns nil if there is no last used smart object or if an error has occurred; otherwise, returns the script table of the entity that was the smart object last used by the user specified.

Parameter Description
userEntityId The entity ID of the user to query for the last used smart object.

GetLeader

Gets the name of a specified group leader.

Syntax

Copy
AI.GetLeader(groupID | entityID)

Returns the leader name.

Parameter Description
groupID Unique group ID.
entityID The ID of the entity.

GetMemoryFireType

Syntax

Copy
AI.GetMemoryFireType(entityId)

Returns the method that the puppet uses for firing at its memory target.

Parameter Description
entityId The ID of the entity.

GetNavigationType

Retrieves the navigation type at a specified entity's position.

Syntax

Copy
AI.GetNavigationType(entityId)

Returns Navigation type, such as NAV_TRIANGULAR, NAV_WAYPOINT_HUMAN, NAV_ROAD, NAV_VOLUME, NAV_WAYPOINT_3DSURFACE, NAV_FLIGHT, NAV_SMARTOBJECT. See the IAISystem::ENavigationType definition for a complete list.

Parameter Description
entityId The ID of the entity.

GetNearestEntitiesOfType

Syntax

Copy
AI.GetNearestEntitiesOfType(entityId|objectname|position, AIObjectType, maxObjects, returnList [,objectFilter [,radius]])

Returns the number of found entities.

Parameter Description
entityId | objectname |position. Unique entity ID, AI object name, or position used to pinpoint the center position of the search.
radius Radius of the search area.
AIObjectType AIObject type to search for (see ScriptBindAI.cpp and Scripts/AIAnchor.lua for a complete list of AIObject types).
maxObjects Maximum number of objects to find.
return list Lua table to hold the list of found entities (Lua handlers).
(optional) objectFilter A combination of one or more of the following search filter flags:
  • AIOBJECTFILTER_SAMEFACTION – Include only AI objects of the same species as the querying object.

  • AIOBJECTFILTER_SAMEGROUP – Include only AI objects of the same group as the querying object (or with no group).

  • AIOBJECTFILTER_NOGROUP – Include only AI objects with a Group ID of AI_NOGROUP.

  • AIOBJECTFILTER_INCLUDEINACTIVE – Include objects that are inactive.

GetNearestHidespot

Retrieves a specified entity's nearest hidepoint within a specified range.

Syntax

Copy
AI.GetNearestHidespot(entityId, rangeMin, rangeMax [, center])

Returns Point position, if found.

Parameter Description
entityId The ID of the entity.
rangeMin Minimum range of search area.
rangeMax Maximum range of search area
centre (optional) Center point of the search area. If not specified, the entity's current position is used.

GetNearestPathOfTypeInRange

Retrieves the type of path nearest to a specified point of interest for a specified entity. Paths use the same types as anchors and are specified in the path properties. The function only returns paths that match the entity's navigation caps. Navigation type is also specified in the path properties.

Syntax

Copy
AI.GetNearestPathOfTypeInRange(entityId, pos, range, type [, devalue, useStartNode])

Parameter Description
entityId The ID of the entity.
pos Vector specifying to the point of interest.
range Search range.
type Type of path to search for.
devalue (optional) Time the returned path is marked as occupied.
useStartNode (optional) Flag indicating whether or not to look a path with any point inside the range (useStartNode=0) or one with a start node inside the range (useStartNode=0).

GetNearestPointOnPath

Locates the point on a path nearest to a specified position.

Syntax

Copy
AI.GetNearestPointOnPath(entityId, pathname, vPos)

Parameter Description
entityId The ID of the entity.
pathname Name of path.
vPos Position to measure from.

GetObjectBlackBoard

Retrieves a specified object's black board (a Lua table).

Syntax

Copy
AI.GetObjectBlackBoard(entity)

Returns black board – if there is one; otherwise, nil.

Parameter Description
entityId or entityName. An AI entity identifier.

GetObjectRadius

Retrieves the radius of a specified AI object.

Syntax

Copy
AI.GetObjectRadius(entityId)

Returns the radius size.

Parameter Description
entityId The ID of the entity.

GetParameter

Retrieves the value of an enumerated AI parameter for a specified entity.

Syntax

Copy
AI.GetParameter(entityId, paramEnum)

Returns the value of the parameter.

Parameter Description
entityId The ID of the entity.
paramEnum The index of the parameter to get. See AI.ChangeParameter() for a complete list.

GetPathLoop

Syntax

Copy
AI.GetPathLoop(entityId, pathname)

Returns true if path is successfully looped.

Parameter Description
entityId The ID of the entity.
pathname Name of the path.

GetPathSegNoOnPath

Syntax

Copy
AI.GetPathSegNoOnPath(entityId, pathname, vPos)

Returns Segment ratio (0.0 start point, 100.0 end point).

Parameter Description
entityId The ID of the entity.
pathname Name of path.
vPos Position.

GetPeakThreatLevel

Syntax

Copy
AI.GetPeakThreatLevel(ScriptHandle entityID)

GetPeakThreatType

Syntax

Copy
AI.GetPeakThreatType(ScriptHandle entityID)

GetPointOnPathBySegNo

Syntax

Copy
AI.GetPointOnPathBySegNo(entityId, pathname, segNo)

Returns Point by segment ratio (0.0 start point, 100.0 end point).

Parameter Description
entityId The ID of the entity.
pathname Name of path.
segNo Segment ratio.

GetPosturePriority

Sets the specified entity's posture priority.

Syntax

Copy
AI.GetPosturePriority(ScriptHandle entityId, const char* postureName)

GetPotentialTargetCount

Retrieves the total number of a specified entity's potential targets.

Syntax

Copy
AI.GetPotentialTargetCount(ScriptHandle entityID)

Parameter Description
entityId The ID of the entity.

GetPotentialTargetCountFromFaction

Retrieves the number of an entity's potential targets that belong to a specified faction.

Syntax

Copy
AI.GetPotentialTargetCountFromFaction(ScriptHandle entityID, const char* factionName)

Parameter Description
entityId The ID of the entity.
name Faction name.

GetPredictedPosAlongPath

Retrieves the predicted position of an AI agent along its path at a specified time.

Syntax

Copy
AI.GetPredictedPosAlongPath(entityId, time, retPos)

Returns True if successful.

Parameter Description
entityId The ID of the entity.
time Time (in seconds) to predict position.
retPos Return point value of the predicted position .

GetPreviousBehaviorName

Syntax

Copy
AI.GetPreviousBehaviorName(ScriptHandle entityID)

GetPreviousPeakThreatLevel

Syntax

Copy
AI.GetPreviousPeakThreatLevel(ScriptHandle entityID)

GetPreviousPeakThreatType

Syntax

Copy
AI.GetPreviousPeakThreatType(ScriptHandle entityID)

GetProbableTargetPosition

Retrieves the probable target position of a specified entity.

Syntax

Copy
AI.GetProbableTargetPosition(entityId)

Parameter Description
entityId The ID of the entity.

GetRefPointDirection

Retrieves a specified entity's reference point direction.

Syntax

Copy
AI.GetRefPointDirection(entityId)

Returns a script vector (x,y,z) reference point direction.

Parameter Description
entityId The ID of the entity.

GetRefPointPosition

Retrieves a specified entity's reference point "world" position.

Syntax

Copy
AI.GetRefPointPosition(entityId)

Returns a script vector (x,y,z) reference point position.

Parameter Description
entityId The ID of the entity.

GetRefShapeName

Retrieves the name of a specified entity's reference shape.

Syntax

Copy
AI.GetRefShapeName(entityId)

Returns a reference shape name.

Parameter Description
entityId The ID of the entity.

GetSoundPerceptionDescriptor

Retrieves information about how the specified entity perceives sound types.

Syntax

Copy
AI.GetSoundPerceptionDescriptor(entityId, soundType, descriptorTable)

Returns true if the information is successfully returned.

Parameter Description
entityId Entity to get perception data on.
soundType Type of sound stimulus to get data for.
descriptorTable Location to store retrieved data.

GetStance

Retrieves the specified entity's stance.

Syntax

Copy
AI.GetStance(entityId)

Returns entity stance (STANCE_*)

Parameter Description
entityId The ID of the entity.

GetSubTypeOf

Retrieves a specified entity's sub type.

Syntax

Copy
AI.GetSubTypeOf(entityId)

Returns the entity sub type (as defined in IAgent.h).

Parameter Description
entityId The ID of the entity.

GetTacticalPoints

Retrieves a point matching a description, related to a specified entity. Format of a point is: { x,y,z }.

Syntax

Copy
AI.GetTacticalPoints(entityId, tacPointSpec, point)

Returns true if a valid point is found; otherwise, false.

Parameter Description
entityId AI's entity.
tacPointSpec. A table specifying the points required.
point Coordinates of the point found.

GetTargetSubType

Retrieves the subtype of a specified entity's current attention target.

Syntax

Copy
AI.GetTargetSubType(entityId)

Returns an attention target subtype. See IAgent.h for a list of target type definitions.

Parameter Description
entityId The ID of the entity.

GetTargetType

Retrieves the type of a specified entity's current attention target.

Syntax

Copy
AI.GetTargetType(entityId)

Returns an attention target type, such as AITARGET_NONE, AITARGET_MEMORY, AITARGET_BEACON, AITARGET_ENEMY. See IAgent.h for a list of target type definitions.

Parameter Description
entityId The ID of the entity.

GetTotalLengthOfPath

Retrieves total length of the specified path.

Syntax

Copy
AI.GetTotalLengthOfPath(entityId, pathname)

Parameter Description
entityId The ID of the entity.
pathname Name of path.

GetTypeOf

Retrieves a specified entity's type.

Syntax

Copy
AI.GetTypeOf(entityId)

Returns the entity type (as defined in IAgent.h).

Parameter Description
entityId The ID of the entity.

GetUnitCount

Retrieves the number of units the leader knows about. The leader is identified based on the group ID of the entity.

Syntax

Copy
AI.GetUnitCount(entityId, unitProperties)

Parameter Description
entityId The ID of the entity.
unitProperties Binary mask of unit properties type for which the attack is requested, in the following form:

UPR_* + UPR* (UPR_COMBAT_GROUND + UPR_COMBAT_FLIGHT)

See IAgent.h for a definition of unit properties UPR_*.

GetUnitInRank

Retrieves the entity that holds the specified rank position in the specified group.

Syntax

Copy
AI.GetUnitInRank(groupID [,rank])

Returns entity script table of the ranked unit.

Parameter Description
groupID The ID of the group that contains the entity to retrieve.
rank The rank position of the entity to retrieve. If null or a value less than or equal to zero is specified, retrieves the entity with the highest rank in the entity. The value of the highest rank is 1.

GoTo

Allows the specified entity to move to a certain destination.

Syntax

Copy
AI.GoTo(entityId, vDestination)

Parameter Description
entityId AI's entity.
vDestination. .

Hostile

Determines whether or not two entities are hostile.

Syntax

Copy
AI.Hostile(entityId, entity2Id|AIObjectName)

Returns true if the entities are hostile.

Parameter Description
entityId ID of the first AI entity.
entity2Id | AIObjectName ID of the second AI entity, or AIobject name.

IgnoreCurrentHideObject

Marks the current hide object as unreachable; it will be omitted from future hidespot selections.

Syntax

Copy
AI.IgnoreCurrentHideObject(entityId)

Parameter Description
entityId The ID of the entity.

IntersectsForbidden

Determines whether or not the specified line is in a forbidden region.

Syntax

Copy
AI.IntersectsForbidden(Vec3 start, Vec3 end)

Returns intersected position or end (if there is no intersection).

Parameter Description
start Vector in format {x,y,z}.
end Vector in format {x,y,z}.

IsAgentInAgentFOV

Determines whether or not one entity is in the field of view of another entity.

Syntax

Copy
AI.IsAgentInAgentFOV(entityId, entityId2)

Returns the first value true if the agent is within the entity FOV; the second value true if the agent is within the entity's primary FOV, or false if the agent is within the entity's secondary FOV.

Parameter Description
entityId The AI entity whose FOV to check.
entityId2. The entity ID of the agent.

IsAgentInTargetFOV

Determines whether or not the entity is in the FOV of the attention target.

Syntax

Copy
AI.IsAgentInTargetFOV(entityId, fov)

Returns true if in the FOV of the attention target; otherwise, false.

Parameter Description
entityId The ID of the entity.
fov FOV of the enemy in degrees.

IsAimReady

Syntax

Copy
AI.IsAimReady(ScriptHandle entityIdHandle)

IsCoverCompromised

Syntax

Copy
AI.IsCoverCompromised(entityId)

Returns true if the cover has been compromised; otherwise, nil.

Parameter Description
entityId AI's entity.

IsEnabled

Checks that the entity is AI-enabled.

Syntax

Copy
AI.IsEnabled(entityId)

Parameter Description
entityId The ID of the entity.

IsFireEnabled

Determines whether or not the AI is allowed to fire or not.

Syntax

Copy
AI.IsFireEnabled(entityId)

Returns true if AI is enabled to fire

Parameter Description
entityId The ID of the entity.

IsInCover

Determines whether or not the agent is using cover.

Syntax

Copy
AI.IsInCover(entityId)

IsLowHealthPauseActive

Syntax

Copy
AI.IsLowHealthPauseActive(ScriptHandle entityID)

IsLowOnAmmo

Syntax

Copy
AI.IsLowOnAmmo(entityId)

Parameter Description
entityId AI's entity.
threshold The ammo percentage threshold.

IsMoving

Determines whether or not the agent wants to move.

Syntax

Copy
AI.IsMoving(entityId)

Parameter Description
entityId The ID of the entity.

IsMovingInCover

Syntax

Copy
AI.IsMovingInCover(entityId)

Returns true – Agent is moving in cover nil – if not

Parameter Description
entityId AI's entity.

IsMovingToCover

Determines whether or not the agent is running to cover.

Syntax

Copy
AI.IsMovingToCover(entityId)

Parameter Description
entityId AI's entity.

IsOutOfAmmo

Syntax

Copy
AI.IsOutOfAmmo(entityId)

Returns true if the specified entity is out of ammunition; otherwise, nil.

Parameter Description
entityId The ID of the AI entity.

IsPersonallyHostile

Syntax

Copy
AI.IsPersonallyHostile(ScriptHandle entityID, ScriptHandle hostileID)

IsPointInFlightRegion

Determines whether or not a specified point is in the flight region.

Syntax

Copy
AI.IsPointInFlightRegion(point)

Returns true if the point is in the flight region.

Parameter Description
point Vector in format {x,y,z}.

IsPointInsideGenericShape

Determines whether or not a point is inside a specified shape.

Syntax

Copy
AI.IsPointInsideGenericShape(position, shapeName[, checkHeight])

Parameter Description
position Position to check.
shapeName Name of the shape to test (returned by AI.GetEnclosingGenericShapeOfType).
checkHeight (optional) Flag indicating whether or not to test for shape height. (default=false). If set to true, the test will check the space between shape.aabb.min.z and shape.aabb.min.z+shape.height.

IsPointInWaterRegion

Determines whether or not the point is in the water region.

Syntax

Copy
AI.IsPointInWaterRegion(point)

Returns a value that indicates water or ground level. Values greater than 0 mean there is water.

IsPunchableObjectValid

Determines whether or not a punchable object is valid.

Syntax

Copy
AI.IsPunchableObjectValid(userId, objectId, origPos)

Parameter Description
userId. User ID.
objectId. Object ID.
origPos. Object position in the world.

IsTakingCover

Syntax

Copy
AI.IsTakingCover(entityId, [distanceThreshold])

Returns true if the specfied agent is either in cover or running to cover; otherwise, nil.

Parameter Description
entityId AI's entity.
distanceThreshold. (Optional) Distance over which an agent that is running to cover is considered to not yet have taken cover.

LoadBehaviors

Syntax

Copy
AI.LoadBehaviors(const char* folderName, const char* extension)

LogComment

Writes additional information to the log for debugging purposes.

Syntax

Copy
AI.LogComment(szMessage)

Parameter Description
szMessage The message to write to the log.

LogEvent

Writes event-driven information to the log that for debugging purposes. Events may occur on a per-frame or a per AI update basis.

Syntax

Copy
AI.LogEvent(szMessage)

Parameter Description
szMessage The message to write to the log.

LogProgress

Writes progress messages to the log.

Syntax

Copy
AI.LogProgress(szMessage)

Parameter Description
szMessage The message to write to the log.

MeleePunchableObject

Syntax

Copy
AI.MeleePunchableObject(entityId, objectId, origPos)

Parameter Description
entityId The ID of the AI entity.
objectId Object ID.
origPos Position of the melee punchable object.

ModifySmartObjectStates

Adds or removes smart object states for a specified entity.

Syntax

Copy
AI.ModifySmartObjectStates(entityId, listStates)

Parameter Description
entityId The ID of the entity.
listStates The list of state names to be added or removed (such as "Closed, Locked", "Open, Unlocked, Busy").

ParseTables

Syntax

Copy
AI.ParseTables(int firstTable, bool parseMovementAbility, IFunctionHandler* pH, AIObjectParams& aiParams, bool& updateAlways)

Parameter Description
firstTable Properties table.
parseMovementAbility True to parse movement ability, false otherwise.
aiParams AI parameters.
updateAlways True to always update; false otherwise.

PlayCommunication

Plays communication on the AI agent.

Syntax

Copy
AI.PlayCommunication(ScriptHandle entityId, const char* commName, const char* channelName, float contextExpiry)

Parameter Description
entityId The ID of the entity.
commName The name of the communication to play.
channelName The name of the channel where the communication will play.

PlayReadabilitySound

Plays readability sound on the AI agent. This call does not do any filtering like playing readability using signals.

Syntax

Copy
AI.PlayReadabilitySound(entityId, soundName)

Parameter Description
entityId The ID of the entity.
soundName The name of the readability sound signal to play.
stopPreviousSounds (Optional) True if any currently playing readability should be stopped in favor of this one.
responseDelayMin (Optional) Minimum (or exact, if no maximum) delay for the response readability to play.
repsonseDelayMax (Optional) Maximum delay for the response readability to play.

ProcessBalancedDamage

Processes balanced damage.

Syntax

Copy
AI.ProcessBalancedDamage(pShooterEntity, pTargetEntity, damage, damageType)

Parameter Description
pShooterEntity Shooter ID.
pTargetEntity Target ID.
damage Hit damage.
damageType Hit damage type.

QueueBubbleMessage

Syntax

Copy
AI.QueueBubbleMessage(ScriptHandle entityID, const char* message)

RecComment

Records a comment with AI Debug Recorder. For information about the AI Debug Recorder, see Using the AI Debug Recorder.

Syntax

Copy
AI.RecComment(szMessage)

Parameter Description
szMessage Message line to be displayed in Recorder view.

RegisterDamageRegion

Registers a spherical region that causes damage (so should be avoided in pathfinding). The owner entity position is used as the region center. The function can be called multiple times to update the region position.

Syntax

Copy
AI.RegisterDamageRegion(entityId, radius)

Parameter Description
entityId The ID of the entity.
radius The radius of the spherical region. If less than or equal to zero, the region is disabled.

RegisterInterestedActor

Registers the interested actor with the interest system. Any errors go to the error log.

Syntax

Copy
AI.RegisterInterestedActor(ScriptHandle entityId, float fInterestFilter, float fAngleInDegrees)

Returns true if a valid update was performed; otherwise, nil. Nil can be returned if the interest system is disabled or the parameters are not valid.

Parameter Description
entityId The ID of the AI entity.

RegisterInterestingEntity

Registers the specified entity with the interest system. Any errors go to the error log.

Syntax

Copy
AI.RegisterInterestingEntity(ScriptHandle entityId, float radius, float baseInterest, const char* actionName, Vec3 offset, float pause, int shared)

Returns true if a valid update was performed; otherwise, nil. Nil can be returned if the interest system is disabled or the parameters are not valid.

Parameter Description
entityId The ID of the entity.

RegisterTacticalPointQuery

Retrieves a query ID for the specified tactical point query.

Syntax

Copy
AI.RegisterTacticalPointQuery(querySpecTable)

Returns > 0 – If the query was parsed successfully 0 – Otherwise

Parameter Description
querySpecTable Table specifying the query. For more information, see AI Tactical Point System.

RegisterTargetTrack

Registers an AI entity to use a specified target track configuration for target selection. The parameter ai_TargetTracking must be set to '2'.

Syntax

Copy
AI.RegisterTargetTrack(entityId, configuration, targetLimit, classThreat)

Returns true if successfully registered.

Parameter Description
entityId The ID of the entity.
configuration Target track configuration.
targetLimit The number of agents who can target the AI at any specified time (0 for infinite).
classThreat (optional) Initial class threat value.

RemovePersonallyHostile

Syntax

Copy
AI.RemovePersonallyHostile(ScriptHandle entityID, ScriptHandle hostileID)

RequestAttack

In a group with a leader, allows the leader to issue a request for a group attack behavior against the enemy. After this request, the Cleader may create an attack leader action (CLeaderAction_Attack_*).

Syntax

Copy
AI.RequestAttack(entityId, unitProperties, attackTypeList [,duration])

Parameter Description
entityId Unique entity ID used to determine the group leader.
unitProperties Binary mask of unit properties type for which the attack is requested, in the following form:

UPR_* + UPR* (UPR_COMBAT_GROUND + UPR_COMBAT_FLIGHT)

See IAgent.h for a definition of unit properties UPR_*.
attackTypeList Lua table containing a prioritized list of preferred attack strategies (leader action subtypes). The list must be in the following format:

{LAS_*, LAS_*,..} (LAS_ATTACK_ROW,LAS_ATTACK_FLANK)

which means that the first attempt will be an Attack_row action , and if that fails an attack_flank.

See IAgent.h for a definition of LeaderActionSubtype (LAS_*) action types.

duration (optional) Maximum duration in seconds (default = 0).

RequestToStopMovement

Syntax

Copy
AI.RequestToStopMovement(ScriptHandle entityId)

ResetAgentLookAtPos

Resets the specified entity's previous call to AgentLookAtPos().

Syntax

Copy
AI.ResetAgentLookAtPos(entityId)

Parameter Description
entityId The ID of the entity.

ResetAgentState

Resets a particular aspect of the agent's state, such as "lean".

Syntax

Copy
AI.ResetAgentState(ScriptHandle entityId, const char * stateLabel)

Returns nil

Parameter Description
entityId The ID of the AI entity.
stateLabel String describing the state that must be reset to default.

ResetParameters

Resets all parameters for a specified entity.

Syntax

Copy
AI.ResetParameters(entityId, bProcessMovement, PropertiesTable, PropertiesInstanceTable)

Parameter Description
entityId The ID of the entity whose parameters you want to reset.
bProcessMovement True to reset movement data; otherwise, false.
PropertiesTable The Lua table that contains the entity's properties.
PropertiesInstanceTable The Lua table that contains instance-specific entity properties.

ResetPersonallyHostiles

Syntax

Copy
AI.ResetPersonallyHostiles(ScriptHandle entityID, ScriptHandle hostileID)

ScaleFormation

Changes the scale factor of a specified entity's formation (if one exists).

Syntax

Copy
AI.ScaleFormation(entityId, scale)

Returns true if formation scaling was successful.

Parameter Description
entityId The ID of the entity.
scale Scale factor.

SequenceBehaviorReady

Syntax

Copy
AI.SequenceBehaviorReady(ScriptHandle entityId)

SequenceInterruptibleBehaviorLeft

Syntax

Copy
AI.SequenceInterruptibleBehaviorLeft(ScriptHandle entityId)

SequenceNonInterruptibleBehaviorLeft

Syntax

Copy
AI.SequenceNonInterruptibleBehaviorLeft(ScriptHandle entityId)

SetAlarmed

Sets the entity to be "perception alarmed".

Syntax

Copy
AI.SetAlarmed(entityId)

SetAnimationTag

Sets a mannequin animation tag.

Syntax

Copy
AI.SetAnimationTag(ScriptHandle entityID, const char* tagName)

Returns a default result code (in Lua: void).

Parameter Description
entityId The ID of the AI entity on which to set the animation tag.
tagName The name of the animation tag that should be set (case insensitive).

SetAssesmentMultiplier

Sets the assesment multiplier factor for the specified AIObject type.

Syntax

Copy
AI.SetAssesmentMultiplier(AIObjectType, multiplier)

Parameter Description
AIObjectType Type of AIObject. See ScriptBindAI.cpp for a complete list of AIObject types.
multiplier Assesment multiplier factor.

SetAttentiontarget

Sets a new attention target.

Syntax

Copy
AI.SetAttentiontarget(entityId, targetId)

Parameter Description
entityId The ID of the entity.
targetId Target's entity ID.

SetBeaconPosition

Sets the beacon's position for the specified entity/object's group.

Syntax

Copy
AI.SetBeaconPosition(entityId | AIObjectName, pos)

Parameter Description
entityId | AIObjectName Unique entity ID or AI object name.
pos Vector {x,y,z} where the beacon position will be set.

SetBehaviorTreeEvaluationEnabled

Syntax

Copy
AI.SetBehaviorTreeEvaluationEnabled(ScriptHandle entityID, bool enable)

SetBehaviorVariable

Sets a behaviour variable for the specified actor.

Syntax

Copy
AI.SetBehaviorVariable(ScriptHandle entityId, const char* variableName, bool value)

SetCollisionAvoidanceRadiusIncrement

Syntax

Copy
AI.SetCollisionAvoidanceRadiusIncrement(ScriptHandle entityId, float radius)

SetContinuousMotion

Syntax

Copy
AI.SetContinuousMotion(ScriptHandle entityID, bool continuousMotion)

SetCoverCompromised

Syntax

Copy
AI.SetCoverCompromised(entityId)

Parameter Description
entityId The ID of the AI entity.

SetEntitySpeedRange

Syntax

Copy
AI.SetEntitySpeedRange(userEntityId, urgency, defaultSpeed, minSpeed, maxSpeed, stance = all)

Returns true if the operation was successful and false otherwise

Parameter Description
usedEntityId The entity ID of the user for which its last used smart object is needed.
urgency The integer value specifying the movement urgency (see AgentMovementSpeeds::EAgentMovementUrgency).
defaultSpeed Floating point value that specfies the default speed.
minSpeed Floating point value that specifies the minimum speed.

SetExtraPriority

Sets a extra priority value to the specified enemy entity.

Syntax

Copy
AI.SetExtraPriority(enemyEntityId, increment)

Parameter Description
enemyEntityId The ID of the entity.
float increment Value to add to the target's priority.

SetFactionOf

Sets the faction to which the specified entity belongs.

Syntax

Copy
AI.SetFactionOf(ScriptHandle entityID, const char* factionName)

Parameter Description
entityId The ID of the entity whose faction to return.
factionName The name of the faction to assign to the specified entity.

SetFactionThreatMultiplier

Sets the threat multiplier factor for the specified species. A return value of 0 indicates that the species is not hostile to any other species.

Syntax

Copy
AI.SetFactionThreatMultiplier(nSpecies, multiplier)

SetFireMode

Sets fire mode immediately.

Syntax

Copy
AI.SetFireMode(entityId, mode)

Parameter Description
entityId The ID of the entity.
firemode New fire mode.

SetFormationAngleThreshold

Sets the relative position inside the formation.

Syntax

Copy
AI.SetFormationAngleThreshold(entityId, fAngleThreshold)

Parameter Description
entityId The ID of the AI entity.
fAngleThreshold New leader orientation angle threshold in degrees.

SetFormationLookingPoint

Sets the relative looking point position inside the formation.

Syntax

Copy
AI.SetFormationLookingPoint(entityId, v3RelativePosition)

Parameter Description
entityId The ID of the AI entity.
v3RelativePosition Table with format {x,y,z} storing the new relative looking point.

SetFormationPosition

Sets the relative position inside the formation.

Syntax

Copy
AI.SetFormationPosition(entityId, v2RelativePosition)

Parameter Description
entityId The ID of the AI entity.
v2RelativePosition Table with format {x,y} storing the new relative position.

SetFormationUpdate

Sets the update flag for a specified entity's formation (if one exists). If this flag is false, the formation is no longer updated.

Syntax

Copy
AI.SetFormationUpdate(entityId, update)

Returns true if the request was successful.

Parameter Description
entityId The ID of the entity.
update True to update the flag; otherwise, false.

SetFormationUpdateSight

Sets a random angle rotation for a specified entity's formation sight directions.

Syntax

Copy
AI.SetFormationUpdateSight(entityId, range, minTime, maxTime)

Parameter Description
entityId The ID of the entity.
range Angle of rotation (0,360) around the default sight direction.
minTime (optional) Minimum timespan for changing the direction (default = 2).
maxTime (optional) Minimum timespan for changing the direction (default = minTime).

SetIgnorant

Sets the specified AI entity to ignore system signals, visual stimuli and sound stimuli.

Syntax

Copy
AI.SetIgnorant(entityId, ignorant)

Parameter Description
entityId The ID of the AI entity.
ignorant A flag indicating whether or not the entity ignores system signals. 0 specifies do not ignore; 1 specifies ignore.

SetInCover

Syntax

Copy
AI.SetInCover(entityId, bool inCover)

Parameter Description
entityId The ID of the AI entity.
inCover Specifies whether the entity should be set to be in cover or not.

SetLeader

Sets a specified entity as the group leader. This action associates a CLeader object with the entity, creating it if one doesn't exist. Only one leader can be set per group.

Syntax

Copy
AI.SetLeader(entityID)

Returns true if successful.

Parameter Description
entityID Unique entity ID to set as leader.

SetMemoryFireType

Sets how the AI agent handles firing at its memory target.

Syntax

Copy
AI.SetMemoryFireType(entityId, type)

Parameter Description
entityId The ID of the entity.
type Memory fire type. Possible values from enum EMemoryFireType in IAgent.h:
Copy
eMFT_Disabled = 0, // Never allowed to fire at memory eMFT_UseCoverFireTime, // Can fire at memory using the weapon's cover fire time eMFT_Always, // Always allowed to fire at memory

SetMovementContext

Sets the specified entity's movement context.

Syntax

Copy
AI.SetMovementContext(ScriptHandle entityId, int context)

Parameter Description
entityId The ID of the entity.
context context value .

SetPathAttributeToFollow

Sets the attribute of a specified entity's path.

Syntax

Copy
AI.SetPathAttributeToFollow(entityId, flag)

Parameter Description
entityId The ID of the entity.
flag Attribute to set.

SetPathToFollow

Sets the path for a specified entity to follow.

Syntax

Copy
AI.SetPathToFollow(entityId, pathName)

Parameter Description
entityId The ID of the entity.
pathName Name of the path to be followed.

SetPFBlockerRadius

Syntax

Copy
AI.SetPFBlockerRadius(entityId, blocker, radius)

Parameter Description
entityId The ID of the entity.

SetPointListToFollow

Sets a point list for a specified entity's path.

Syntax

Copy
AI.SetPointListToFollow(entityId, pointlist, howmanypoints, bspline [, navtype])

Parameter Description
entityId The ID of the entity.
pointList List of points for the entity to follow, expressed as a set of local vectors: {{x=0.0, y=0.0, z=0.0}, .
howmanypoints Number of points in the list.
bspline Flag indicating whether or not the path line is recalculated using spline interpolation.
navtype (Optional) Navigation type (default = IAISystem::NAV_FLIGHT).

SetPosturePriority

Sets the specified entity's posture priority.

Syntax

Copy
AI.SetPosturePriority(ScriptHandle entityId, const char* postureName, float priority)

SetPostures

Sets the specified entity's postures.

Syntax

Copy
AI.SetPostures(ScriptHandle entityId, SmartScriptTable postures)

Parameter Description
entityId The ID of the entity.
postures The table of postures.

SetRefPointAtDefensePos

Sets a specified entity's reference point position to an intermediate distance between the entity's attention target and a specified point.

Syntax

Copy
AI.SetRefPointAtDefensePos(entityId, point2defend, distance)

Parameter Description
entityId The ID of the entity.
point2defend Point to defend.
distance Maximum distance between reference point and point to defend.

SetRefPointDirection

Sets a specified entity's reference point direction.

Syntax

Copy
AI.SetRefPointDirection(vRefPointDir)

Parameter Description
vRefPointDir Direction as a (script)vector (x,y,z) value.

SetRefPointPosition

Sets a specified entity's reference point "world" position.

Syntax

Copy
AI.SetRefPointPosition(entityId, vRefPointPos)

Parameter Description
entityId The ID of the entity.
vRefPointPos World position as a (script)vector (x,y,z) value.

SetRefPointRadius

Sets a specified entity's reference point radius.

Syntax

Copy
AI.SetRefPointRadius(entityId, radius)

Parameter Description
entityId The ID of the entity.
radius The reference point radius.

SetRefpointToAnchor

Sets a reference point to an anchor.

Syntax

Copy
AI.SetRefpointToAnchor(entityId, rangeMin, rangeMax, findType, findMethod)

Parameter Description
entityId The ID of the AI entity.
rangeMin Minimum range.
rangeMax Maximum range.
findType Finding type.
findMethod Finding method.

SetRefpointToPunchableObject

Sets the reference point to the punchable object.

Syntax

Copy
AI.SetRefpointToPunchableObject(entityId, range)

Parameter Description
entityId The ID of the AI entity.
range Range for the punchable object.

SetRefShapeName

Sets the name of a specified entity's reference shape.

Syntax

Copy
AI.SetRefShapeName(entityId, name)

Parameter Description
entityId The ID of the entity.
name Name of the reference shape.

SetSmartObjectState

Sets a single smart object state, replacing all other states.

Syntax

Copy
AI.SetSmartObjectState(entityId, stateName)

Parameter Description
entityId The ID of the entity.
stateName The name of the new state to set for the smart object (such as "Idle").

SetSoundPerceptionDescriptor

Sets information about how the specified entity perceives sound types.

Syntax

Copy
AI.SetSoundPerceptionDescriptor(entityId, soundType, descriptorTable)

Returns True if information successfully saved.

Parameter Description
entityId Entity to set perception data for.
soundType Type of sound stimulus to set data for.
descriptorTable Perception data to saved.

SetSpeed

Sets the entity's current speed (urgency).

Syntax

Copy
AI.SetSpeed(entityId, urgency)

Parameter Description
entityId AI's entity.
urgency A float value that specifies the movement urgency (see AgentMovementSpeeds::EAgentMovementUrgency).

SetStance

Sets the specified entity's stance.

Syntax

Copy
AI.SetStance(entityId, stance)

Parameter Description
entityId The ID of the entity.
stance The stance value (STANCE_*).

SetTargetTrackClassThreat

Sets the class threat for a specified entity's target track.

Syntax

Copy
AI.SetTargetTrackClassThreat(entityId, classThreat)

Parameter Description
entityId The ID of the entity.
classThreat New class threat value.

SetTempTargetPriority

Sets a specified entity's selection priority for a temporary target over other potential targets.

Syntax

Copy
AI.SetTempTargetPriority(entityId, priority)

Returns True if successfully updated.

Parameter Description
entityId The ID of the entity.
priority New priority value.

SetTerritoryShapeName

Sets the territory shape of the specified AI entity.

Syntax

Copy
AI.SetTerritoryShapeName(entityId, shapeName)

Parameter Description
entityId The ID of the entity.
shapeName Name of the shape to set.

SetUnitProperties

Sets the leader's knowledge about the unit's combat capabilities. The leader is identified based on the group ID of the entity.

Syntax

Copy
AI.SetUnitProperties(entityId, unitProperties)

Parameter Description
entityId The ID of the entity.
unitProperties Binary mask of unit properties in the following form:

UPR_* + UPR* (UPR_COMBAT_GROUND + UPR_COMBAT_FLIGHT)

See IAgent.h for a definition of the UPR_* unit properties.

SetUseSecondaryVehicleWeapon

Enables or disables the AI object's ability to use the secondary weapon when firing from a vehicle gunner seat if possible.

Syntax

Copy
AI.SetUseSecondaryVehicleWeapon(entityId, bUseSecondary)

Parameter Description
entityId The ID of the entity.
bUseSecondary Specify true to use the secondary weapon; otherwise, false.

Signal

Adds a signal to the sender's signal queue even if another signal with same text is present.

Syntax

Copy
AI.Signal(signalFilter, signalType, signalText, senderId [, signalExtraData])

Parameter Description
signalFilter The signal filter.
signalType The signal type.
signalText Signal text that is processed by the receivers, either in a Lua callback with the same name as the text or directly by the CAIObject.
senderId The ID of the sender.
signalExtraData Optional. A Lua table containing additional data. It can contain the following data types:
  • point – A vector in the format {x,y,z}.

  • point2 – A vector in the format {x,y,z}.

  • ObjectName – A string.

  • id – An entity ID.

  • fValue – A float value.

  • iValue – An integer value.

  • iValue2 – A second integer value.

SmartObjectEvent

Executes a smart action.

Syntax

Copy
AI.SmartObjectEvent(actionName, userEntityId, objectEntityId [, vRefPoint])

Returns 0 if a smart object rule was not found or if a non-zero ID was inserted to execute the action.

Parameter Description
actionName The name of the smart action.
usedEntityId The entity ID of the user who wants to execute the smart action, or none if the user is unknown.
objectEntityId The entity ID of the object on which the smart action is to be executed, or none if the object is unknown.
vRefPoint Optional. The reference point to be used instead of the user's attention target position.

SoundEvent

Generates a sound event with the specified parameters in the AI system.

Syntax

Copy
AI.SoundEvent(position, radius, threat, interest, entityId)

Parameter Description
position Origin of the sound event.
radius Area the sound event is heard in.
threat Sound event property.
interest Sound event property.
entityId Unique entity ID that generates the sound event.

StopCommunication

Stops specified communication.

Syntax

Copy
AI.StopCommunication(ScriptHandle playID)

Parameter Description
playID The ID of the communication to stop.

ThrowGrenade

Throws a specified grenade at a target type without interrupting the fire mode.

Syntax

Copy
AI.ThrowGrenade(entityId, grenadeType, regTargetType)

Parameter Description
entityId The ID of the entity.
grenadeType Requested grenade type (see ERequestedGrenadeType).
regTargetType The grenade target type (see AI_REG_*).

UnregisterInterestedActor

Unregisters the entity with the interest system. Any errors are recorded in the error log.

Syntax

Copy
AI.UnregisterInterestedActor(ScriptHandle entityId)

Parameter Description
entityId The ID of the entity.

UnregisterInterestingEntity

Unregisters the specified entity with the interest system. Any errors are recorded in the error log.

Syntax

Copy
AI.UnregisterInterestingEntity(ScriptHandle entityId)

Parameter Description
entityId The ID of the entity.

UnregisterTargetTrack

Unregisters an AI object from the target track manager. The parameter ai_TargetTracking must be set to '2'.

Syntax

Copy
AI.UnregisterTargetTrack(entityId)

Returns true if successfully unregistered.

Parameter Description
entityId The ID of the entity.

UpdateGlobalPerceptionScale

Syntax

Copy
AI.UpdateGlobalPerceptionScale(float visualScale, float audioScale)

UpdateTempTarget

Updates the position of the specified entity's temporary potential target.

Syntax

Copy
AI.UpdateTempTarget(entityId, vPos)

Returns true if successfully updated.

Parameter Description
entityId The ID of the entity.
vPos New position of the temporary target.

UpTargetPriority

Changes a specified entity's target priority value for a specified target, if the target is on the entity's target list.

Syntax

Copy
AI.UpTargetPriority(entityId, targetId, increment)

Parameter Description
entityId The ID of the entity.
targetId The entity ID of the target.
increment New value for the target priorty.

VisualEvent

Generates a visual event with the specified parameters in the AI system.

Syntax

Copy
AI.VisualEvent(entityId, targetId)

Parameter Description
entityId The ID of the entity that receives the visual event.
targetId The ID of the visual target (that the entity is seeing).

Warning

Writes a warning message to the log about data or script errors.

Syntax

Copy
AI.Warning(szMessage)

Parameter Description
szMessage The message to write to the log.

On this page: