# Avorion Script API Documentation

Home Functions Search
Search:

Sector [Server] Sector
Properties
name
numEntities
numPlayers
persistent
pvpDamage
seed
Member Functions
addScript
addScriptOnce
belongsToFaction
broadcastChatMessage
callbacksRegistered
clearTickLengthAnalysisQueue
clearValues
collectGarbage
copyEntity
createAsteroid
createEntity
createObject
createShip
createStation
createWormHole
createWreckage
deleteEntity
deleteEntityJumped
dropBundle
dropCargo
dropMoney
dropResources
dropSectorTurret
dropTurret
dropUpgrade
dropUsableItem
dropVanillaItem
exists
getAllies
getCoordinates
getEnemies
getEntities
getEntitiesByComponent
getEntitiesByComponents
getEntitiesByFaction
getEntitiesByLocation
getEntitiesByScript
getEntitiesByScriptValue
getEntitiesByType
getEntity
getEntityByFactionAndName
getNumAllies
getNumEnemies
getNumEntities
getNumEntitiesByComponent
getNumEntitiesByComponents
getNumEntitiesByFaction
getNumEntitiesByLocation
getNumEntitiesByScript
getNumEntitiesByScriptValue
getNumEntitiesByType
getPlayers
getPresentFactions
getScripts
getValue
getValues
hasEnemies
hasScript
intersectBeamRay
invokeFunction
isEntitySetForDeletion
registerCallback
removeScript
replaceEntity
resendEntity
resolveScriptPath
sendCallback
setValue
transferEntity
unregisterCallback

# Sector [Server]

This object is only available on the server.

function Sector()

Returns

A new instance of Sector

property string name |

Get the name of the sector, as specified by its SectorSpecifics

property unsigned int numEntities | [read-only]

property unsigned int numPlayers | [read-only]

property bool persistent |

property bool pvpDamage |

property Seed seed | [read-only]

function int addScript()

function var addScriptOnce()

function bool belongsToFaction(int factionIndex, var id)

Returns if the entity with the given id belongs to a specific faction. This is a performance optimization for quick checks of ids versus faction. Use if you have an id that you want to check for its faction, and not the entity. If you already have an Entity constructed, use the factionIndex property of the entity, that's faster than this function.

Parameters

factionIndex The index of the faction to test
id The id of the entity to test

Returns

A boolean indicating if the entity belongs to the faction

function var broadcastChatMessage(var sender, int messageType, string message, PluralForm... args)

Broadcast a chat message to all players that are currently in the sector. Supports sending of format arguments so that the chat message can be translated on the client.

Parameters

sender The sender that will be displayed for the chat message
messageType The type of chat message, 0 = Normal, 1 = Error, 2 = Warning, 3 = Info
message The message that will be sent
args The format arguments that will be sent

Returns

nothing

function int callbacksRegistered(string callbackName, var functionName)

Check how many functions are registered to a callback from the current script VM.

Parameters

callbackName The name of the callback
functionName The name of the function for which to check. If nil, will count all functions that are registered to this callback.

Returns

The amount of functions registered to the callback

function var clearTickLengthAnalysisQueue()

Returns

nothing

function var clearValues()

Removes all custom values of the object

Returns

nothing

function var collectGarbage(var entity)

Immediately deletes all entities in the sector that are set for deletion. Don't call this function from an entity script. Only call this if you know what you're doing.

Parameters

entity The entity to delete

Returns

nothing

function // see copyEntity(Entity entity, Matrix positoin)

Creates a copy of an existing entity

Parameters

entity The entity to copy
positoin The new position of the copy

Returns

The new entity

function Entity createAsteroid(BlockPlan plan, bool resources, Matrix position)

Convenience function to create an asteroid. Creates a new asteroid in the sector. This entity will have all components required for a default asteroid.

Parameters

plan The plan of the asteroid, this plan will be empty after the call since the plan is moved (instead of copied) into the created entity
resources 1 if the asteroid should have mineable resources, 0 if not
position The position of the asteroid

Returns

An entity representing the new asteroid

function Entity createEntity(EntityDescriptor descriptor, var arrivalType)

Creates a new arbitrary entity in the sector

Parameters

descriptor A descriptor representing the entity to create, this descriptor will be empty after the call since the data is moved (instead of copied) into the created entity
arrivalType The arrival type of the ship

Returns

The new entity

function Entity createObject(BlockPlan plan, Matrix position, var arrivalType)

Convenience function to create a default object. Creates a new default object in the sector. This object has basic components for appearance and physics simulation, such as a plan, velocity and physics

Parameters

plan The plan of the object, this plan will be empty after the call since the plan is moved (instead of copied) into the created entity
position The position of the object
arrivalType The arrival type of the ship

Returns

An entity representing the new object

function Entity createShip(Faction faction, string name, BlockPlan plan, Matrix position, var arrivalType)

Convenience function to create a ship. Creates a new ship in the sector. This entity will have all components required for a default ship.

Parameters

faction The faction the ship will belong to
name The name of the ship, pass "" for a random name; Ships for AIFactions will always get a random name
plan The plan of the ship, this plan will be empty after the call since the plan is moved (instead of copied) into the created entity
position The position of the ship
arrivalType The arrival type of the ship

Returns

An entity representing the new ship

function Entity createStation(Faction faction, BlockPlan plan, Matrix position, var script, var... args)

Convenience function to create a station. Creates a new station in the sector. A random name will be assigned in case of an AI station. This entity will have all components required for a default station.

Parameters

faction The faction the station will belong to
plan The plan of the station, this plan will be empty after the call since the plan is moved (instead of copied) into the created entity
position The position of the station
script An optional script that will be used on creation of the station
args Arguments to the script that will be passed to its "initialize" function

Returns

An entity representing the new station

function Entity createWormHole(int x, int y, Color color, float visualSize, var passageSize)

Convenience function to create a wormhole. Creates a new wormhole in the sector. This entity will have all components required for a default wormhole.

Parameters

x The destination sector's X coordinate
y The destination sector's Y coordinate
color The color of the wormhole
visualSize The size of the wormhole
passageSize The size that is used to determine if ships fit through. If nil max value will be used.

Returns

An entity representing the new wormhole

function Entity createWreckage(BlockPlan plan, Matrix position)

Convenience function to create a wreckage. Creates a new wreckage in the sector. This entity will have all components required for a default wreckage.

Parameters

plan The plan of the wreckage, this plan will be empty after the call since the plan is moved (instead of copied) into the created entity
position The position of the wreckage

Returns

An entity representing the new wreckage

function var deleteEntity(Entity entity)

Sets an entity for deletion. The entity is not deleted right away, but will be marked for deletion and will be deleted at the end of the current frame.

Parameters

entity The entity to delete

Returns

nothing

function var deleteEntityJumped(Entity entity)

Sets an entity for deletion. The entity is not deleted right away, but will be marked for deletion and will be deleted at the end of the current frame. This function also creates a hyperspace animation when deleting the entity.

Parameters

entity The entity to delete

Returns

nothing

function var dropBundle()

Returns

nothing

function Entity dropCargo(vec3 position, Faction [or nil] reservedFor, Faction [or nil] deniedFor, TradingGood good, int owner, int amount)

function Entity dropMoney(vec3 position, Faction [or nil] reservedFor, Faction [or nil] deniedFor, int amount)

function Entity dropResources(vec3 position, Faction [or nil] reservedFor, Faction [or nil] deniedFor, Material material, int amount)

function Entity dropSectorTurret(vec3 position, Faction [or nil] reservedFor, Faction [or nil] deniedFor)

Drops a random turret that is appropriate for this sector. Can return nil as well, since turrets with higher slot numbers won't always be dropped so that not too much money value is dropped all the time.

Parameters

position The position of where to drop the turret
reservedFor Faction the loot is reserved for, or nil
deniedFor Faction the loot is denied for, or nil

Returns

The new entity, or nil

function Entity dropTurret(vec3 position, Faction [or nil] reservedFor, Faction [or nil] deniedFor, TurretTemplate desc)

function Entity dropUpgrade(vec3 position, Faction [or nil] reservedFor, Faction [or nil] deniedFor, SystemUpgradeTemplate upgrade)

function Entity dropUsableItem(vec3 position, Faction [or nil] reservedFor, Faction [or nil] deniedFor, UsableInventoryItem item)

function Entity dropVanillaItem(vec3 position, Faction [or nil] reservedFor, Faction [or nil] deniedFor, VanillaInventoryItem item)

function bool exists(var id)

Returns if the entity with the given id exists in the sector. This is a performance optimization for quick checks of existance. Use if you have an id (but not a constructed Entity) that you want to check for existance. If you already have an Entity constructed, use the valid() function, which is faster.

Parameters

id The id of the entity to test

Returns

A boolean indicating if the entity with the index exists

function Entity... getAllies(int factionIndex)

Returns all allies of the given faction in the sector. Allies include ships of the same faction. Allied entities are determined as follows:
- they belong to the same faction
- they belong to factions whose relations are above 70.000
- they belong to players of the same group
- they belong to players of the same alliance
- they belong to a player and their alliance

Parameters

factionIndex The faction index of the faction whose ally ships are to be queried

Returns

Multiple values: All detected allies in the sector

function int, int getCoordinates()

Access the x, y coordinates of the sector

Returns

2 return values: x, y coordinates of the sector

function Entity... getEnemies(int factionIndex)

Returns all enemies of the given faction in the sector. Enemies are determined as ships of factions where relations are below -40.000

Parameters

factionIndex The faction index of the faction whose enemy ships are to be queried

Returns

Multiple return values: All detected enemies in the sector

function Entity... getEntities()

Returns all entities in the sector

Returns

Multiple return values: All entities in the sector

function Entity... getEntitiesByComponent(int type)

Returns all entities in the sector that have a specific component

Parameters

type The desired component type (See enum ComponentType)

Returns

Multiple return values: All matching entities in the sector

function Entity... getEntitiesByComponents(Type... types)

Returns all entities in the sector that have a specific set of components

Parameters

types The desired set of component types (See enum ComponentType)

Returns

Multiple return values: All matching entities in the sector

function Entity... getEntitiesByFaction(int factionIndex)

Returns all entities in the sector that belong to the given faction Complexity: O(n)

Parameters

factionIndex The desired faction

Returns

Multiple return values: All matching entities in the sector

function Entity... getEntitiesByLocation(Sphere sphere)

Returns all entities in the sector whose bounding spheres intersect with the given sphere. Entities without a bounding sphere component will not be considered.
Complexity: O(logn)

Parameters

sphere The intersected sphere

Returns

Multiple return values: All matching entities in the sector

function Entity... getEntitiesByScript(string script)

Returns all entities in the sector that have a specific script attached to them

Parameters

script The script that is to check for. This operation checks if the given script name is contained in the actual script name.

Returns

Multiple return values: All matching entities in the sector

function Entity... getEntitiesByScriptValue(string name, var value)

Returns all entities in the sector that have a specific value assigned to them. Values can be set with Entity:setValue(name, value) and read with Entity:getValue(name).

Parameters

name The value name to check for
value A value to check against. If this is set, only entities will be returned whose value is equal to the passed value. If this is nil, all entities will be returned that have any value with the given name assigned.

Returns

Multiple return values: All matching entities in the sector

function Entity... getEntitiesByType(int type)

Returns all entities in the sector that have a specific type

Parameters

type The desired entity type (See enum EntityType)

Returns

Multiple return values: All matching entities in the sector

function Entity getEntity(var index)

Find an entity by index in the sector.
Complexity: O(logn)

Parameters

index The index of the entity as Uuid or std::string

Returns

The entity or nil if not found

function Entity getEntityByFactionAndName(int factionIndex, string name)

function unsigned int getNumAllies(int faction)

function unsigned int getNumEnemies(int factionIndex)

function unsigned int getNumEntities()

function unsigned int getNumEntitiesByComponent(int component)

function unsigned int getNumEntitiesByComponents()

function unsigned int getNumEntitiesByFaction(int factionIndex)

function unsigned int getNumEntitiesByLocation(Sphere sphere)

function unsigned int getNumEntitiesByScript(string scriptName)

function unsigned int getNumEntitiesByScriptValue(string valueName, var value)

function unsigned int getNumEntitiesByType(int type)

function Player... getPlayers()

Returns all players that are currently in the sector

Returns

Multiple return values: All players in the sector

function int... getPresentFactions()

Returns all indices of all present factions

Returns

a list of int indices of all present factions

function table<int, string> getScripts()

function var getValue(string key)

Retrieves a custom value saved in the entity with the given key

Parameters

key A string that serves as the name of the value

Returns

The value if the key exists, otherwise nil

function table<string, var> getValues()

Retrieves all key-value pairs of custom values of the entity

Returns

A table containing all custom key-value pairs

function bool hasEnemies(int factionIndex)

Checks if the given faction has any enemy ships or objects in the sector

Parameters

factionIndex The index of the faction

Returns

true if there are enemies present, false otherwise

function bool hasScript(string name)

function UserObject... intersectBeamRay(Ray ray, Uuid [or nil] ignoredEntity, Uuid [or nil] ignoredEntityShields)

Intersects a beam in the sector, similar to the way that weapon beams are intersected. If an entity has a shield, that shield will be part of the test. If the beam would intersect with multiple entities, then the entity with its intersection point closest to the ray origin is chosen.

Parameters

ray The ray that should be intersected
ignoredEntity A uuid that can be optionally set. If this was set, the entity with this ID will be ignored during the intersection.
ignoredEntityShields A uuid that can be optionally set. If this was set, the shields of the entity with this ID will be ignored during the intersection.

Returns

The entity closest to the origin of the ray, that was hit (if one or more were hit), as well as the point where the ray intersects with the object (or its shield).

function var... invokeFunction(var scriptName, string functionName, var... arguments)

Invokes a function in a script of the sector. Use this function to invoke functions from one script in another script. The first return value of the function is an integer indicating whether or not the call was successful. When it was, this integer is followed by the return values of the invoked function.

Parameters

scriptName The name of the script containing the function
functionName The name of the function that will be executed
arguments An arbitrary list of arguments that will be given to the invoked function

Returns

Returns at least 1 value indicating if the call succeeded:
0 The call was successful. In this case, the return values of the script are returned in addition to the call result, following the call result
3 The call failed because the given script was not found in the sector
4 The call failed because the given function was not found in the script

function bool isEntitySetForDeletion(Entity entity)

function int registerCallback(string callbackName, string functionName)

Register a callback in the sector. The callback receiver has to be inside the sector for the registration to succeed. The callback will be removed if the receiver leaves the sector or gets destroyed, or the sector gets unloaded. Double registration of callbacks doesn't work. When the same callback to the same callback of the same script instance is registered twice, it will still only be called once.

Parameters

callbackName The name of the callback
functionName The name of the function that will be executed in the script when the callback happens

Returns

0 on success, 1 if the registration failed

function var removeScript(var script)

Returns

nothing

function Entity replaceEntity(var toReplace, EntityDescriptor descriptor, var arrivalType)

Creates a new arbitrary entity in the sector, and deletes the previous entity. The replacement will be seamless on the client

Parameters

toReplace The entity to replace, can be of type Entity, Uuid or string
descriptor A descriptor representing the entity to create, this descriptor will be empty after the call since the data is moved (instead of copied) into the created entity
arrivalType The arrival type of the ship

Returns

The new entity

function var resendEntity(Entity entity)

Returns

nothing

function string resolveScriptPath(string path)

function var sendCallback()

Returns

nothing

function var setValue(string key, var value)

Sets a custom value

Parameters

key A string that serves as the name of the value
value The value to save. Must be bool, number, string or nil. If nil is given, the value will be deleted.

function var transferEntity(Entity entity, int x, int y, int type)

Marks an entity for transfer to another sector. Child entities such as turrets will be transferred as well. The entity will be removed from the sector after the frame ends. Default transfer type will just move the entity without any effects or other behaviours and the entity will be placed at the exact same position as in the previous sector. Jump transfer will simulate a jump behavior, including an effect on the client and placing the entity at the edge of the destination sector. Gate and Wormhole transfer will place the entity in front of the outgoing gate or wormhole, if there is any that leads to the origin sector. Otherwise, same behavior as Default transfer. While technically, Wormhole transfer and Gate transfer is the exact same thing internally, we have to distinguish it for different things like for example achievements.

Parameters

entity The entity that is to be transferred
x The x coordinate of the target sector
y The y coordinate of the target sector
type The type of transfer: SectorChangeType

Returns

nothing

function var unregisterCallback(string callbackName, string functionName)

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