# 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

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

## Typical roll alignment workflow

```lua
-- 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))
```