EntityAI API

EntityAI controls high-level AI behavior for an Entity.

Reference

  • setActive(active: Boolean) Enables (true) or disables (false) AI control for this entity.

  • isActive() Returns true when AI is currently active.

  • moveToSector(sector: LuaVec3i) Sets the AI’s sector navigation target.

  • getTargetSector() Returns the current sector target as LuaVec3i. Returns the entity’s current sector when no target is set.

  • setTarget(entity: RemoteEntity) Sets the combat/aim target. The target must be in the same or an adjacent sector.

  • getTarget() Returns the current target as RemoteEntity, or nil when no target is set.

  • getTargetType() Returns the exact current AI target preference name as a string.

  • getAvailableTargetTypes() Returns the currently available target preference names as a String[].

  • setTargetType(type: String) Changes the AI target preference to type.

Common built-in values for type are Any, Selected Target, Ships, Stations, Missiles, Astronauts, and Asteroids.

setTargetType(type) always expects a String. The running game may also provide additional custom target type names through CustomAITargetUtil.

Invalid target type names now raise a clear error that includes the currently available values.

Target type names

These built-in target type names are present in the current StarMade build used by Logiscript:

Target type

Expected arg type

Notes

Any

String

Default catch-all target preference

Selected Target

String

Use the currently selected target

Ships

String

Prefer ship targets

Stations

String

Prefer station targets

Missiles

String

Prefer missile targets

Astronauts

String

Prefer astronaut targets

Asteroids

String

Prefer asteroid targets

StarMade also appends any custom AI target program names registered through CustomAITargetUtil, so getTargetType() may return additional names and setTargetType(type) can accept them when they are present in the running build.

  • moveToPos(pos: LuaVec3i) Commands the AI to move toward world block position pos.

  • moveToEntity(entity: RemoteEntity) Commands the AI to move toward entity. The target must be in the same sector.

  • navigateToPos(pos: LuaVec3i, stopRadius: Number) Moves toward pos and automatically stops when the entity is within stopRadius blocks.

  • hasReachedPos(pos: LuaVec3i, radius: Number) Returns true if the entity is currently within radius blocks of pos.

  • stop() / stopNavigation() Stops current AI movement.

Heading and orientation

  • getHeading() Returns the ship’s normalized forward direction as a LuaVec3f.

  • isAlignedWith(direction: LuaVec3f, threshold: Number) Returns true if the ship’s heading dot-product with direction is >= threshold (range 0.0–1.0). Use 0.9 for roughly aligned, 0.99 for very tight.

  • isFacingTowards(entity: RemoteEntity, threshold: Number) Returns true if the ship is facing toward entity within the given dot-product threshold.

  • faceDirection(direction: LuaVec3f) Commands the AI to turn toward direction. Also causes the ship to begin moving in that direction — call stopNavigation() once aligned.

  • faceTowards(entity: RemoteEntity) Commands the AI to face toward entity. Computes direction from current position to target automatically.

Roll control

  • getUp() Returns the ship’s normalized up vector as a LuaVec3f (basis column 1 of the world transform).

  • getRoll() Returns the ship’s current roll angle in radians relative to galactic up (world Y axis). Positive values indicate counter-clockwise roll when viewed from behind; negative values indicate clockwise roll. Returns 0 when the ship is pointing straight up or down (roll is undefined in that orientation).

  • isRollAligned(threshold: Number) Returns true if the ship’s up vector Y-component is >= threshold. Equivalent to checking dot(shipUp, galacticUp) >= threshold. Use 0.99 for tight alignment, 0.9 for loose.

  • faceWithRoll(forward: LuaVec3f, up: LuaVec3f) Commands the AI to orient the ship so that it faces forward with up as the desired up vector, giving full roll control. Also applies thrust in the forward direction (equivalent to faceDirection plus roll). up does not need to be perfectly perpendicular to forward — it is Gram-Schmidt orthogonalized internally.

  • alignRollToGalacticUp() Corrects the ship’s roll so its up vector aligns with galactic up (0, 1, 0) while preserving the current heading. Does not apply thrust — use faceDirection or moveToPos for movement.

Typical alignment workflow

local station = ...
ai:faceTowards(station)
while not ai:isFacingTowards(station, 0.95) do sleep(0.5) end
ai:stopNavigation()

Typical roll alignment workflow

-- Correct roll while holding heading
while math.abs(ai:getRoll()) > 0.05 do
    ai:alignRollToGalacticUp()
    sleep(0.1)
end

-- Fly toward a point level with galactic up
local heading = ai:getHeading()
ai:faceWithRoll(heading, vec3f(0, 1, 0))