Skip to main content

sm.ai​

Utility functions for NPC Unit AI behavior.
Note that these are not restricted to UnitClass scripts and can be used anywhere.
Functions which do not require a Unit object are usable in client context as well.

Functions​

directPathAvailable​

local isReachable = sm.ai.directPathAvailable(unit, position, maxDistance)

Checks if the given Unit can reach the target position by moving straight.

Parameters:

  • unit (Unit): The unit.
  • position (Vec3): The target position.
  • maxDistance (number, optional): The maximum distance to allow.

Returns:

  • isReachable (boolean): Whether the position is directly reachable or not.

getAimPosition​

local canFire, aimPosition = sm.ai.getAimPosition(character, target, range, width)

Returns true if the given character can fire a projectile at the target within a given fire lane.
Also returns the aim position that allows the character to succeed.

Parameters:

  • character (Character): The firing character.
  • target (Character/Harvestable): The target.
  • range (number): The maximum firing distance.
  • width (number): The width of the firing lane.

Returns:

  • canFire (boolean): Whether the character can fire at the target or not.
  • aimPosition (Vec3/nil): The aim position, if available.

getBreachablePosition​

local breachable, attackPosition, target = sm.ai.getBreachablePosition(unit, position, range, attackLevel)

Checks if there is an attackable object between the given unit and a position.
Returns true if a breachable object or no object was found.
Returns false if an unbreachable object was found.

Parameters:

  • unit (Unit): The unit.
  • position (Vec3): The target position.
  • range (number): The raycast length.
  • attackLevel (int): The attacker's possible attack level.

Returns:

  • breachable (boolean): Whether the given position is breachable or not.
  • attackPosition (Vec3): The attack position.
  • target (Shape/Harvestable/Lift/nil): The object to attack, if found.

getClosestTree​

local tree = sm.ai.getClosestTree(position, world)

Find the closest "tree" harvestable to the given position in the current or given world.

Parameters:

  • position (Vec3): The position to check.
  • world (World, optional): The world. Defaults to script world context.

getClosestVisibleCharacterType​

local character = sm.ai.getClosestVisibleCharacterType(unit, uuid)

Returns the closest visible character with matching UUID.

Parameters:

  • unit (Unit): The unit.
  • uuid (Uuid): The character type UUID to look for.

Returns:

  • character (Character): The closest visible character.

getClosestVisibleCrop​

local crop = sm.ai.getClosestVisibleCrop(unit)

Returns the closest visible farming harvestable.

Parameters:

  • unit (Unit): The unit.

Returns:

  • crop (Harvestable): The closest visible farming harvestable.

getClosestVisiblePlayerCharacter​

local playerCharacter = sm.ai.getClosestVisiblePlayerCharacter(unit)

Returns the closest visible player character.

Parameters:

  • unit (Unit): The unit.

Returns:

  • playerCharacter (Character): The closest visible farming harvestable.

getClosestVisibleTeamOpponent​

local opponent = sm.ai.getClosestVisibleTeamOpponent(unit, color)

Returns the closest visible character that does not have the given color.

Parameters:

  • unit (Unit): The unit.
  • color (Color): The color.

Returns:

  • opponent (Character): The closest visible team opponent.

getRandomCreationPosition​

local position = sm.ai.getRandomCreationPosition(body)

Returns a random position on the given body.

Parameters:

  • body (Body): The body.

Returns:

  • position (Vec3): The random position.

isReachable​

local isReachable sm.ai.isReachable(unit, position)

Check if the unit can reach the target position by moving along a path.

Parameters:

  • unit (Unit): The unit.
  • position (Vec3): The target position.

Returns:

  • isReachable (boolean): Whether the target position is reachable or not.