Class: UnitAI

UnitAI()

new UnitAI()

Source:

Members

DefaultRelaxedMaxRange

How close to our goal do we consider it's OK to stop if the goal appears unreachable. Currently 3 terrain tiles as that's relatively close but helps pathfinding.
Source:

Methods

AbleToMove(cmpUnitMotion)

Parameters:
Name Type Description
cmpUnitMotion optionally pass unitMotion to avoid querying it here
Source:
Returns:
true if the entity can move, i.e. has UnitMotion and isn't immobile.

Attack()

Adds attack order to the queue, forced by the player.
Source:

AttackEntityInZone()

Try to find one of the given entities which can be attacked and which is close to the hold position, and start attacking it. Returns true if it found something to attack.
Source:

AttackVisibleEntity()

Try to find one of the given entities which can be attacked, and start attacking it. Returns true if it found something to attack.
Source:

CallMemberFunction(resetFinishedEntities)

Call UnitAI.funcname(args) on all formation members.
Parameters:
Name Type Description
resetFinishedEntities If true, call ResetFinishedEntities first. If the controller wants to wait on its members to finish their order, this needs to be reset before sending new orders (in case they instafail) so it makes sense to do it here. Only set this to false if you're sure it's safe.
Source:

CallPlayerOwnedEntitiesFunctionInRange()

Call obj.funcname(args) on UnitAI components owned by player in given range.
Source:

CanReturnResource(checkCarriedResource, cmpResourceGatherer)

Check if the entity can return carried resources at @param target
Parameters:
Name Type Description
checkCarriedResource check we are carrying resources
cmpResourceGatherer if present, use this directly instead of re-querying.
Source:

CheckFormationTargetAttackRange(target) → {boolean}

Check if the target is inside the attack range of the formation.
Parameters:
Name Type Description
target number The target entity ID to attack.
Source:
Returns:
- Whether the entity is within attacking distance.
Type
boolean

CheckPositionVisible()

Returns true if the given position is currentl visible (not in FoW/SoD).
Source:

CheckRange(iid, type)

Generic dispatcher for other Check...Range functions.
Parameters:
Name Type Description
iid Interface ID (optional) implementing GetRange
type Range type for the interface call
Source:

CheckTargetAttackRange()

Check if the target is inside the attack range For melee attacks, this goes straigt to the regular range calculation For ranged attacks, the parabolic formula is used to accout for bigger ranges when the target is lower, and smaller ranges when the target is higher
Source:

CheckTargetVisible()

Returns true if the target entity is visible through the FoW/SoD.
Source:

CollectTreasure()

Adds order to collect a treasure to queue, forced by the player.
Source:

CollectTreasureNearPosition()

Adds order to collect a treasure to queue, forced by the player.
Source:

ComputeWalkingDistance()

Returns the estimated distance that this unit will travel before either finishing all of its orders, or reaching a non-walk target (attack, gather, etc). Intended for Formation to switch to column layout on long walks.
Source:

ConstructionFinished()

Called directly by cmpFoundation and cmpRepairable to inform builders that repairing has finished. This not done by listening to a global message due to performance.
Source:

DropAtNearestDropSite()

The unit will drop all resources at the closest dropsite. If this unit is no gatherer or no dropsite is available, it will do nothing.
Source:

EnsureCorrectPackStateForAttack(requirePacked) → {boolean}

For a unit that is packing and trying to attack something, either cancel packing or continue with packing, as appropriate. Precondition: if the unit is packing/unpacking, then orderQueue should have the Attack order at index 0, and the Pack/Unpack order at index 1. This precondition holds because if we are packing while processing "Order.Attack", then we must have come from ReplaceOrder, which guarantees it.
Parameters:
Name Type Description
requirePacked boolean true if the unit needs to be packed to continue attacking, false if it needs to be unpacked.
Source:
Returns:
true if the unit can attack now, false if it must continue packing (or unpacking) first.
Type
boolean

FaceTowardsTarget(target)

Let an entity face its target.
Parameters:
Name Type Description
target number The entity-ID of the target.
Source:

FindNearbyFoundation()

Returns the entity ID of the nearest building that needs to be constructed. "Nearest" is nearest from @param position.
Source:

FindNearbyResource()

Returns the entity ID of the nearest resource supply where the given filter returns true, or undefined if none can be found. "Nearest" is nearest from @param position. TODO: extend this to exclude resources that already have lots of gatherers.
Source:

FindNearbyTreasure()

Returns the entity ID of the nearest treasure. "Nearest" is nearest from @param position.
Source:

FindNearestDropsite()

Returns the entity ID of the nearest resource dropsite that accepts the given type, or undefined if none can be found.
Source:

FindNewHealTargets()

Resets losHealRangeQuery, and if there are some targets in range that we can heal then we start healing and this returns true; otherwise, returns false.
Source:

FindNewTargets()

Resets losAttackRangeQuery, and if there are some targets in range that we can attack then we start attacking and this returns true; otherwise, returns false.
Source:

FindSightedEnemies() → {boolean}

Resets the losRangeQuery.
Source:
Returns:
- Whether there are targets in range that we ought to react upon.
Type
boolean

FinishOrder()

Call when the current order has been completed (or failed). Removes the current order from the queue, and processes the next one (if any). Returns false and defaults to IDLE if there are no remaining orders or if the unit is not inWorld and not garrisoned (thus usually waiting to be destroyed). Must be called from inside the FSM.
Source:

Flee()

Adds flee order to the queue, not forced, so it can be interrupted by attacks.
Source:

Garrison()

Adds garrison order to the queue, forced by the player.
Source:

Gather()

Adds gather order to the queue, forced by the player until the target is reached
Source:

GatherNearPosition()

Adds gather-near-position order to the queue, not forced, so it can be interrupted by attacks.
Source:

GetRange(iid, target, type) → {Object|undefined}

General getter for ranges.
Parameters:
Name Type Description
iid number
target number [Optional]
type string [Optional]
Source:
Returns:
- The range in the form { "min": number, "max": number } Returns undefined when the entity does not have the requested component.
Type
Object | undefined

Guard()

Adds guard/escort order to the queue, forced by the player.
Source:

Heal()

Adds heal order to the queue, forced by the player.
Source:

IsAnimal()

For now, entities with a RoamDistance are animals.
Source:

IsDangerousAnimal()

ToDo: Make this not needed by fixing gaia range queries in BuildingAI and UnitAI regarding animals and other gaia entities.
Source:

IsTurret(cmpTurretable) → {boolean}

Parameters:
Name Type Description
cmpTurretable cmpTurretable Optionally the component to save a query here.
Source:
Returns:
- Whether we are occupying a turret point.
Type
boolean

IsWalkingAndFighting()

Return true if the current order is WalkAndFight or Patrol.
Source:

LeaveFormation()

Order a unit to leave the formation it is in. Used to handle queued no-formation orders for units in formation.
Source:

LeaveFoundation()

Adds leave foundation order to queue, treated as forced.
Source:

MoveFormationToTargetAttackRange(target) → {boolean}

Move unit so we hope the target is in the attack range of the formation.
Parameters:
Name Type Description
target number The target entity ID to attack.
Source:
Returns:
- Whether the order to move has succeeded.
Type
boolean

MoveTo(iid, type)

Generic dispatcher for other MoveTo functions.
Parameters:
Name Type Description
iid Interface ID (optional) implementing GetRange
type Range type for the interface call
Source:
Returns:
whether the move succeeded or failed.

MoveToTargetAttackRange()

Move unit so we hope the target is in the attack range for melee attacks, this goes straight to the default range checks for ranged attacks, the parabolic range is used
Source:

MustKillGatherTarget()

Returns true if the target exists and needs to be killed before beginning to gather resources from it.
Source:

OccupyTurret()

Adds garrison order to the queue, forced by the player.
Source:

PerformGather()

Internal function to abstract the force parameter.
Source:

PlaySound()

Play a sound appropriate to the current entity.
Source:

ProcessMessage(type, msg)

A general function to process messages sent from components.
Parameters:
Name Type Description
type string The type of message to process.
msg Object Optionally extra data to use.
Source:

PushOrder()

Add an order onto the back of the queue, and execute it if we didn't already have an order.
Source:

PushOrderAfterForced()

Insert an order after the last forced order onto the queue and after the other orders of the same type
Source:

PushOrderFront()

Add an order onto the front of the queue, and execute it immediately.
Source:

RelaxedMaxRangeCheck()

Source:
Returns:
true if the unit is in the relaxed-range from the target.

Repair()

Adds repair/build order to the queue, forced by the player until the target is reached
Source:

ResetIdle()

Used by formation controllers to toggle the idleness of their members.
Source:

RespondToHealableEntities()

Try to respond to healable entities. Returns true if it responded.
Source:

RespondToSightedEntities(ents) → {boolean}

Parameters:
Name Type Description
ents number An array of the IDs of the spotted entities.
Source:
Returns:
- Whether we responded.
Type
boolean

RespondToTargetedEntities()

Try to respond appropriately given our current stance, given a list of entities that match our stance's target criteria. Returns true if it responded.
Source:

ReturnResource()

Adds return resource order to the queue, forced by the player.
Source:

SetupAttackRangeQuery(enable)

Set up a range query for all enemy and gaia units within range which can be attacked.
Parameters:
Name Type Description
enable boolean Optional parameter whether to enable the query.
Source:

SetupHealRangeQuery(enable)

Set up a range query for all own or ally units within LOS range which can be healed.
Parameters:
Name Type Description
enable boolean Optional parameter whether to enable the query.
Source:

SetupLOSRangeQuery(enable)

Set up a range query for all enemy units within LOS range.
Parameters:
Name Type Description
enable boolean Optional parameter whether to enable the query.
Source:

SetupRangeQueries()

Wrapper function that sets up the LOS, healer and attack range queries. This should be called whenever our ownership changes.
Source:

SetupTradeRoute()

Adds trade order to the queue. Either walk to the first market, or start a new route. Not forced, so it can be interrupted by attacks. The possible route may be given directly as a SetupTradeRoute argument if coming from a RallyPoint, or through this.expectedRoute if a user command.
Source:

ShouldAbandonChase()

Returns true if we should stop following the target entity.
Source:

ShouldGuard() → {boolean}

Source:
Returns:
- Whether it makes sense to guard the given entity.
Type
boolean

StartTimer()

Set up the UnitAI timer to run after 'offset' msecs, and then every 'repeat' msecs until StopTimer is called. A "Timer" message will be sent each time the timer runs.
Source:

Stop()

Adds stop order to queue, forced by the player.
Source:

StopTimer()

Stop the current UnitAI timer.
Source:

TargetIsAlive()

Returns true if the target exists and has non-zero hitpoints.
Source:

TargetPosOrEntPos()

Returns the position of target or, if there is none, the entity's position, or undefined.
Source:

TestAllMemberFunction()

Call obj.functname(args) on UnitAI components of all formation members, and return true if all calls return true.
Source:

TryMatchTargetSpeed(target, mayRun)

Try to match the targets current movement speed.
Parameters:
Name Type Description
target number The entity ID of the target to match.
mayRun boolean Whether the entity is allowed to run to match the speed.
Source:

Ungarrison()

Adds ungarrison order to the queue.
Source:

Walk()

Adds walk order to queue, forced by the player.
Source:

WalkAndFight()

Adds walk-and-fight order to queue, this only occurs in response to a player order, and so is forced. If targetClasses is given, only entities matching the targetClasses can be attacked.
Source:

WalkToPointRange()

Adds walk to point range order to queue, forced by the player.
Source:

WalkToTarget()

Adds walk-to-target order to queue, this only occurs in response to a player order, and so is forced.
Source: