# Avorion Script API Documentation

Home Functions Search
Search:

ShipAI ShipAI
Properties
attackedEntity
entity
entityId
flyTarget
isAttackingSomething
isBusy
isStuck
state
Member Functions
clearEnemyEntities
clearEnemyFactions
clearFriendEntities
clearFriendFactions
enemyFightersPresent
enemyShipsPresent
getEnemies
getEnemyFighters
getEnemyShips
getEscortTarget
getFollowTarget
getNearestEnemy
getRegisteredEnemyEntities
getRegisteredEnemyFactions
getRegisteredFriendEntities
getRegisteredFriendFactions
isEnemy
isEnemyPresent
isRegisteredEnemy
isRegisteredFriend
registerEnemyEntity
registerEnemyFaction
registerFriendEntity
registerFriendFaction
setAggressive
setAttack
setBoard
setEscort
setFly
setFlyLinear
setFollow
setGuard
setHarvest
setIdle
setJump
setPassive
setPassiveShooting
setPassiveTurning
setRepair
setRepairTarget
setStatus
setStatusMessage
stop
unregisterEnemyEntity
unregisterEnemyFaction
unregisterFriendEntity
unregisterFriendFaction

# ShipAI

function ShipAI(var id)

Parameters

id The id of the entity this component belongs to, or the entity itself, must be an id of an existing entity or nil for the entity in the current script context

Returns

A new instance of ShipAI

property uuid attackedEntity | [read-only]

The currently attacked entity.

property Entity entity | [read-only]

property uuid entityId | [read-only]

property vec3 flyTarget | [read-only]

The location the entity is currently flying to, if in state "Fly" or "FlyLinear".

property bool isAttackingSomething | [read-only]

True if the entity is currently attacking another entity.

property bool isBusy | [read-only]

True if the entity is currently doing something that prevents ambient chatter.

property bool isStuck | [read-only]

True if the entity is currently in state "Fly" and got stuck.

property int state | [read-only]

The AIStateType that the AI is currently in.

function var clearEnemyEntities()

Removes all registered entities from the enemy list so that this AI no longer always considers them their enemy.

Returns

nothing

function var clearEnemyFactions()

Removes all registered factions from the enemy list so that this AI no longer always considers them their enemy.

Returns

nothing

function var clearFriendEntities()

Removes all registered entities from the friend list so that this AI no longer always considers them their ally/friend.

Returns

nothing

function var clearFriendFactions()

Removes all registered factions from the friend list so that this AI no longer always considers them their ally/friend.

Returns

nothing

function bool enemyFightersPresent()

Returns true if there are enemy fighters present in the sector.

function bool enemyShipsPresent(var countCivilEnemies)

Returns true if there are enemy ships present in the sector.

Parameters

countCivilEnemies Set to true to also include civil ships like freighters and the like.

function Entity... getEnemies()

Returns a list of all entities that this AI considers hostile in the sector.

function Entity... getEnemyFighters()

Returns a list of all fighters that this AI considers hostile in the sector.

function Entity... getEnemyShips()

Returns a list of all non-fighter entities that this AI considers hostile in the sector.

function Uuid getEscortTarget()

Returns the Uuid of the escorted craft or nil if Escort is not active.

function Uuid getFollowTarget()

Returns the Uuid of the followed or escorted craft or nil if neither Follow nor Escort is active.

function Entity getNearestEnemy()

Finds the closest enemy of the AI in the sector.

function uuid... getRegisteredEnemyEntities()

Returns the list of entities that are always considered enemies.

function int... getRegisteredEnemyFactions()

Returns the list of factions that are always considered enemies.

function uuid... getRegisteredFriendEntities()

Returns the list of entities that are always considered friends.

function int... getRegisteredFriendFactions()

Returns the list of factions that are always considered friends.

function bool isEnemy(Entity target)

Checks if the given entity is considered an enemy.

Parameters

target The entity to check

function bool isEnemyPresent(var countCivilEnemies)

Returns true if there are any enemy entities present in the sector.

Parameters

countCivilEnemies Set to true to also include civil ships like freighters and the like.

function bool isRegisteredEnemy(Entity target)

Checks if the given entity is registered to always be considered hostile.

Parameters

target The entity to check

function bool isRegisteredFriend(Entity target)

Checks if the given entity is registered to always be considered friendly.

Parameters

target The entity to check

function var registerEnemyEntity(Uuid id)

Adds a single entity that this AI will always consider their enemy. This setting overrides normal faction relations. Registering a new enemy entity will do an internal unregisterFriendEntity(id) call and vice versa.

Parameters

id The id of the entity

Returns

nothing

function var registerEnemyFaction(int index)

Adds a faction that this AI will always consider their enemy. This setting overrides normal faction relations. Registering a new enemy faction will do an internal unregisterFriendFaction(index) call and vice versa.

Parameters

index The index of the new friend faction

Returns

nothing

function var registerFriendEntity(Uuid id)

Adds a single entity that this AI will always consider their ally/friend. This setting overrides normal faction relations. Registering a new friend entity will do an internal unregisterEnemyEntity(id) call and vice versa.

Parameters

id The id of the entity

Returns

nothing

function var registerFriendFaction(int index)

Adds a faction that this AI will always consider their ally/friend. This setting overrides normal faction relations. Registering a new friend faction will do an internal unregisterEnemyFaction(index) call and vice versa.

Parameters

index The index of the new friend faction

Returns

nothing

function var setAggressive(var attackCivilShips, var canFinish)

Sets the AI's current state to 'Aggressive'. The ship will attack its enemies and switch between enemies when taking damage (classic aggro principle).

Parameters

attackCivilShips Pass "true" to have it attack civil ships as well
canFinish Pass "true" to have the state change to 'Idle' once there are no more enemies.

Returns

nothing

function var setAttack(Entity target)

Sets the AI's current state to 'Attack'. The ship will attack the given target. It will also try to stay moving to make it harder for enemies to hit it. The state ends when the target can't be found any more, or when the target has been out of reach for more than 60 seconds. The ship will not follow through gates or jump after its target.

Parameters

target The attacked entity

Returns

nothing

function var setBoard(Entity target)

Sets the AI's current state to 'Board'. The ship will try to board the target. The state ends when the target can no longer be found or boarded, or when boarding was successful.

Parameters

target The targeted entity

Returns

nothing

function var setEscort(Entity escortedShip)

Sets the AI's current state to 'Escort'. The ship will follow the specified entity and attack enemies that try attacking the escorted ship. This state switches between the 'Follow' and the 'Attack' logic internally. The state ends when the escorted object can't be found any more. A ship set to escort will follow through hyperspace and gates.

Parameters

escortedShip The ship it should escort

Returns

nothing

function var setFly(vec3 location, float arrivalRadius, Entity collisionException, var fighterOrders, var lenientArrivalAllowed)

Sets the AI's current state to 'Fly'. The ship will fly towards a destination and evade obstacles. If it can't fly to its location without potentially colliding with other objects, it will remain still.

Parameters

location The location it should fly to
arrivalRadius The arrival radius of the location, once the ship is inside the radius it will stop flying
collisionException Pass an Entity as an exception, which won't be considered during flight path calculation. nil for no exception.
fighterOrders The desired fighter orders or nil
lenientArrivalAllowed A bool indicating whether the ship is allowed to arrive at the final waypoint instead of the actual destination

Returns

nothing

function var setFlyLinear(vec3 location, float arrivalRadius, var avoidCollisions)

Sets the AI's current state to 'Fly Linear'. The ship will fly towards a destination linearly and will not evade obstacles.

Parameters

location The location it should fly to
arrivalRadius The arrival radius of the location, once the ship is inside the radius it will stop flying

Returns

nothing

function var setFollow(Entity followedShip, var followedToOtherSectors)

Sets the AI's current state to 'Follow'. The ship will follow the specified entity. The state ends when the escorted object can't be found any more. A ship set to follow will follow through hyperspace and gates.

Parameters

followedShip The ship it should follow
followedToOtherSectors a bool indicating whether the ship should follow to other sectors (false, by default)

Returns

nothing

function var setGuard(vec3 location)

Sets the AI's current state to 'Guard'. The ship will remain around a specified location and attack enemies that get too close.

Parameters

location The location it should guard

Returns

nothing

function var setHarvest(Entity target)

Sets the AI's current state to 'Harvest'. The ship will try to mine/salvage the target. The state ends when the target can no longer be found.

Parameters

target The targeted entity

Returns

nothing

function var setIdle()

Sets the AI's current state to 'Idle', which can be compared to a player just stopping to move their hands. That means that any keys that the AI might still have pressed, will remain pressed until otherwise told so via the ControlUnit component.

Returns

nothing

function var setJump(int x, int y)

Sets the AI's current state to 'Jump'. The ship will turn towards a specified sector and try to jump into it. If it can't it will just turn towards the destination sector. The state ends when it arrives at its destination.

Parameters

x The x coordinate of the target sector
y The y coordinate of the target sector

Returns

nothing

function var setPassive()

Sets the AI's current state to 'Passive'. The ship will actively do nothing at all and try to stand still at all cost.

Returns

nothing

function var setPassiveShooting(bool enabled)

Enables or disables the ability to shoot enemy ships passively while flying around.

Parameters

enabled true to enable, false to disable

Returns

nothing

function var setPassiveTurning(vec3 location)

Sets the AI's current state to 'Passive Turning'. The ship will turn towards a position, but not fly there and will always set its desired velocity to 0.

Parameters

location The location it should turn towards.

Returns

nothing

function var setRepair()

Sets the AI's current state to 'Repair'. Similar to 'Aggressive', but for repairs. The ship will look for allies and heal them. This state does not end.

Returns

nothing

function var setRepairTarget(Entity target)

Sets the AI's current state to 'Repair Target'. Can repair itself. The state ends when the target can't be found any more.

Parameters

target The targeted entity

Returns

nothing

function var setStatus(string status, string_pair... arguments)

DEPRECATED, use ShipAI:setStatusMessage(). Sets the status that will be set in the ship info and other places (eg. ships/fleet tab)

Parameters

status a string that will be used as status, can be a format string for easier translation.
arguments Set the string arguments (if format string is used) as vector of string_pair.

Returns

nothing

function var setStatusMessage(string status, string_pair... arguments)

Sets the status that will be set in the ship info and other places (eg. ships/fleet tab)

Parameters

status a string that will be used as status, can be a format string for easier translation.
arguments Set the string arguments (if format string is used) as vector of string_pair.

Returns

nothing

function var stop()

Stops the ship and sets its state to 'Idle'.

Returns

nothing

function var unregisterEnemyEntity(Uuid id)

Removes a single entity from the enemy list so that this AI no longer always considers it their enemy.

Parameters

id The id of the entity

Returns

nothing

function var unregisterEnemyFaction(int index)

Removes a faction from the enemy list so that this AI no longer always considers them their enemy.

Parameters

index The index of the faction to remove

Returns

nothing

function var unregisterFriendEntity(Uuid id)

Removes a single entity from the friend list so that this AI no longer always considers it their ally/friend.

Parameters

id The id of the entity

Returns

nothing

function var unregisterFriendFaction(int index)

Removes a faction from the friend list so that this AI no longer always considers them their ally/friend.

Parameters

index The index of the faction to remove

Returns

nothing

Overview
Home Functions Search
Search:
Callbacks
Callbacks Alliance [Client] Callbacks Alliance [Server] Callbacks Alliance [Server] Callbacks Entity Callbacks Galaxy Callbacks Player Callbacks Player [Client] Callbacks Sector Callbacks Server Callbacks
Predefined Functions & Example Scripts
Command Entity FactionDatabase PlanGenerator Player Sector Server UsableInventoryItem
Common Components
Boarding BspTree CargoBay CargoLoot ControlUnit CrewComponent DeletionTimer DirectFlightPhysics DockingClamps DockingParent DockingPositions Durability EnergySystem Engine FighterAI Hangar HyperspaceEngine InteractionText InventoryItemLoot Owner Physics Plan ReadOnlyBoarding ReadOnlyBspTree ReadOnlyCargoBay ReadOnlyControlUnit ReadOnlyCrew ReadOnlyDeletionTimer ReadOnlyEnergySystem ReadOnlyEngine ReadOnlyFighterAI ReadOnlyHangar ReadOnlyHyperspaceEngine ReadOnlyInteractionText ReadOnlyOwner ReadOnlyPhysics ReadOnlyPlan ReadOnlyShipAI ReadOnlyShipSystem ReadOnlyTorpedoAI [Server] [Client] [Server] [Client] ReadOnlyTorpedoAI [Server] [Client] [Server] [Client] ReadOnlyTorpedoLauncher ReadOnlyTurretBases ReadOnlyVelocity ReadOnlyWeapons ReadOnlyWormHole Shield ShipAI ShipSystem StructuralIntegrity SystemUpgradeLoot Thrusters Torpedo TorpedoAI TorpedoLauncher Turret TurretAI TurretBases Velocity Weapons WormHole
Common Objects
AllianceMember AllianceRank BlockPlan BlockPlanBlock BlockStatistics Box Captain Color ControlUnitSeat CraftDesign CraftStatsOverview Crew CrewMan CrewProfession DebugInfo dvec2 dvec3 dvec4 Entity EntityDescriptor FighterTemplate Format GameSettings Group HighResolutionTimer Inventory InventoryTurret ivec2 ivec3 ivec4 Language Mail Material Matrix ModManager NamedFormat PlanBspTree PlanetSpecifics PlanGenerationStage PlanPart PlanStyle PlayerId PluralForm Profiler QuadTree Random Rarity Ray ReadOnlyEntity Rect Relation Scenario SectorView Seed Sphere Squad SystemUpgradeTemplate Timer Tooltip TooltipLine TorpedoShaft TorpedoTemplate TradingGood TurretDesign TurretDesignPart TurretTemplate UsableInventoryItem Uuid VanillaInventoryItem vec2 vec3 vec4 Version Weapon
Client Components
EntityIcon EntityTooltip PlanMesh ReadOnlyIcon ReadOnlyPlanMesh ReadOnlyScriptUI ReadOnlyTooltip ScriptUI
Client Objects
Achievements Alliance [Client] CameraKeyFrame CaptainSelectionItem Client ClientSettings ColorSelectionItem CraftDesignSelectionItem Faction [Client] Galaxy [Client] GalaxyMap GameInput GlowFX IconSelectionItem InputWindow InventoryReferenceSelectionItem InventorySelectionItem Keyboard LaserFX Mouse Music PixelIconSelectionItem Planet Player [Client] PlayerWindow RefractionFX Sector [Client] SelectionItem ShipDatabaseEntry [Client] SoundSource StrategyState TargetIndicator TooltipRenderer TurretDesignSelectionItem
Client UI Objects
AllianceEmblem AllianceTab ArrowLine Button [Client] [Client] Button [Client] [Client] CaptainIcon CaptainProfile CheckBox ComboBox ContextMenu CraftPortrait CrewBar Frame Hud InventorySelection Label Line ListBox ListBoxEx MapArrowLine MapIcon MultiLineTextBox NumbersBar Picture PlanDisplayer ProgressBar SavedDesignsSelection ScrollFrame Selection ShipWindow Slider StatisticsBar Tab TabbedWindow TextBox TextField TooltipDisplayer Tree UIArbitraryHorizontalSplitter UIArbitraryVerticalSplitter UIContainer UIElement UIGridSplitter UIHorizontalLister UIHorizontalMultiSplitter UIHorizontalSplitter UIOrganizer UIRect UIRenderer UIVerticalLister UIVerticalMultiSplitter UIVerticalSplitter ValueComboBox Window
Server Components
EntityTransferrer FighterController Loot ReadOnlyEntityTransferrer ReadOnlyFighterController ReadOnlyLoot ReadOnlyTurretController ReadOnlyWreckageCreator TurretController WreckageCreator
Server Objects
Alliance [Server] Faction [Server] Galaxy [Server] Player [Server] ReadOnlySector Sector [Server] Server ShipDatabaseEntry [Server]
Enums
AIState AlliancePrivilege BeamShape BlockShading BlockStructure BlockType BlockType2 BoxType BuildError CaptainGenderId ChatChannel ChatMessageType ComponentType ControlAction ControlActionBit ControlStyle CoolingType CraftStatsOverviewStat CrewProfessionType CrewRank DamageSource DamageType DeletionType Difficulty EntityArrivalType EntityType FighterOrders FighterStartError FighterType FontType ImpactParticles InventoryItemType JumpError KeyboardKey ListBoxEntryType MalusReason MaterialType MoonType MouseButton PlanetType PlanTypeFilter PlayerStateType ProjectileShape RarityType RelationStatus SavedDesignType ScenarioType SectorChangeType ShipAvailability SoundType StatsBonuses TargetIndicatorVisuals TransformationFeature TurretAutoFireMode TurretSlotType WeaponAppearance WeaponCategory

This is the official documentation for the scripting API of Avorion. This documentation is automatically generated and not necessarily complete. Depending on the context in which functions exist, some documentation such as descriptions, return values or variable names or types may be missing.

Work in Progress. Documentation of Avorion Version: 2.5.8 a0d3f0b5b065