Avorion Script API Documentation
Entity Script Predefined Functions
Tip: Scroll down for an example script!
function initialize(...)
This function is always the very first function that is called in a script, and only once during the lifetime of the script. The function is always called on the server first, before client instances are available, so invoking client functions will never work. This function is both called when a script gets newly attached to an object, and when the object is loaded from the database during a load from disk operation. During a load from disk operation, no parameters are passed to the function, and a global variable '_restoring' is set to true.
Parameters
function update(timeStep)
Called every tick, both on client and server. See the documentation for getUpdateInterval() for details on the frequency of these calls.
Parameters
function getUpdateInterval()
Defines the update tick interval of the script. This interval can not be less than the update tick interval of the server or client, depending on where the script is running. The update(), updateParallelRead(), updateParallelSelf(), updateClient() and updateServer() functions will only be called after at least this much time has passed. The minimum update interval for the client varies with the framerate of the client. The minimum update interval for the server is 50 ms. This function is called after initialize() or after the update functions were called. If this function is not defined, the update functions will be called every tick.
Expected return values
The desired update tick interval in seconds
function onRemove()
Called when the script is about to be removed from the object, before the removal.
function onDelete()
Called when the script is about to be deleted from the object, before the deletion. This is the last call that will be done to an object script. This function is also called when the object it is attached to is deleted.
function secure()
Called to secure values from the script. This function is called when the object is unloaded from the server. It's called at other times as well to refresh data, or when objects are copied or during regular saves. The table returned by this function will be passed to the restore() function when the object is loaded and read from disk. All values that are in the table must be numbers, strings or other tables. Values that aren't of the above types will be converted to nil and an error message will be printed.
Expected return values
A table containing values that should be saved
function restore(values)
Called to restore previously secured values for the script. This is called after initialize(). Receives the values that were gathered from the last called to the secure() function. This function is called when the object is read from disk and restored, after initialize() was called.
Parameters
function initUI()
This function is called when the game initializes the UI of the script. This function is only called once per script. You should initialize all your UI elements in this function and register all interactions for the entity here as well, so that they will be visible when the player interacts with the entity.
Client Function: This function is only called on the client.
function onInteract(optionIndex)
Executed whenever the player starts interacting with the script, before the registered interaction callback function is executed.
Client Function: This function is only called on the client.
Parameters
function onShowWindow(optionIndex)
Executed when the player starts interacting with the script and the registered window is shown.
Client Function: This function is only called on the client.
Parameters
function onCloseWindow(optionIndex)
Executed when the player stops interacting with the script or closes the main window for the specific interaction.
Client Function: This function is only called on the client.
Parameters
function updateUI()
Executed every tick while the player is interacting with the script. This function is expensive, so only define it if you need your script to be updated every tick.
Client Function: This function is only called on the client.
function renderUI()
Executed every tick while the player is interacting with the script. During this function, render calls are valid and can be done. All render calls from this function will be drawn over the current window. This function is expensive, so only define it if you need it.
Client Function: This function is only called on the client.
function renderUIIndicator(x, y, size)
Executed every tick if the entity is selected by the player. During this function, render calls are valid and can be done. All render calls from this function will be drawn on the same 2D plane as other UI indicators. This function is expensive, so only define it if you need it.
Client Function: This function is only called on the client.
Parameters
y The y position of the target indicator
size The size of the target indicator
function renderUIPreHud()
Executed every tick. During this function, render calls are valid and can be done. All render calls from this function will be drawn below the main HUD. This function is expensive, so only define it if you need it.
Client Function: This function is only called on the client.
function renderUIPostHud()
Executed every tick. During this function, render calls are valid and can be done. All render calls from this function will be drawn over the main HUD. This function is expensive, so only define it if you need it.
Client Function: This function is only called on the client.
function onKeyboardEvent(key, pressed)
Executed whenever a keyboard event is sent to the script. Keyboard events might be caught by other active menus first. If this function returns true then the event will be interpreted as used and won't be sent to any other menus.
Client Function: This function is only called on the client.
Parameters
pressed A boolean indicating whether the key was pushed down or not
Expected return values
Return true to indicate that the event was used by this script
function onMouseEvent(key, pressed, x, y)
Executed whenever a mouse event is sent to the script. Mouse events might be caught by other active menus first. If this function returns true then the event will be interpreted as used and won't be sent to any other menus.
Client Function: This function is only called on the client.
Parameters
pressed A boolean indicating whether the key was pushed down or not
x The x position of the mouse cursor
y The y position of the mouse cursor
Expected return values
Return true to indicate that the event was used by this script
function interactionPossible(playerIndex, optionIndex)
Determines whether or not the entity can be interacted with. If no values are returned or the function isn't defined, interaction will be deemed not possible. The game checks for general interaction possibilities sometimes, for example when a player selects a station, to show the "Press F to interact" text. If a non-empty error message is returned, the result will be interpreted as "failed", even if the first value was true.
Client Function: This function is only called on the client.
Parameters
optionIndex The index of the specific registered interaction option that is being chosen. nil if only a general query for interaction is done.
Expected return values
A boolean indicating whether the interaction is possible and if not, an optional error message as string that says why the interaction failed
function updateClient(timeStep)
Update tick that is only executed on the client. See the documentation for getUpdateInterval() for details on the frequency of these calls. Execution order of the updateXXX() functions is: updateParallelRead(), updateParallelSelf(), update(), update[Server/Client]().
Client Function: This function is only called on the client.
Parameters
function getIcon()
A function that is used by the UI to get the icon that will be used for the script interaction button on the top right of the screen. This function should return a string containing the path to the icon (example: "data/textures/icons/jigsaw-piece.png"). If this function isn't defined, or if nothing or empty string is returned, the displayed icon will be a placeholder icon. This function will only be called if the interactionPossible(...) test didn't fail.
Client Function: This function is only called on the client.
Expected return values
A string containing the path to the icon
function updateServer(timeStep)
Update tick that is only executed on the server. See the documentation for getUpdateInterval() for details on the frequency of these calls. Execution order of the updateXXX() functions is: updateParallelRead(), updateParallelSelf(), update(), update[Server/Client]().
Server Function: This function is only called on the server.
Parameters
function isTransferrable(id, x, y)
Executed when the entity enters an area that triggers a sector transfer (ie. gate, wormhole). This should return a boolean value that indicates whether the entity can be transferred to the other sector or not. If any script that is attached to the entity and that implements this function returns false, the transfer fails and the entity won't be transferred. If a script doesn't implement this function, the value is interpreted as true.
Server Function: This function is only called on the server.
Parameters
x The x coordinate of the target sector
y The y coordinate of the target sector
Expected return values
A boolean whether or not the entity is allowed to transfer
function canTransfer(id)
Executed if the entity has an EntityTransferrer component and when an entity enters the area that triggers a sector transfer. This should return a boolean value that indicates whether the entity can be transferred to the other sector or not. If any script that is attached to the entity and that implements this function returns false, the transfer fails and the entity won't be transferred. If a script doesn't implement this function, the value is interpreted as true.
Server Function: This function is only called on the server.
Parameters
Expected return values
A boolean whether or not the entity is allowed to transfer
function getEnergy(seed, rarity, permanent)
Used to gather the energy requirements of a system upgrade. The returned value must be in Watts.
Parameters
rarity The rarity of the upgrade
permanent A bool indicating whether or not the upgrade was installed permanently
Expected return values
The amount of currently required energy, in Watts.
function getEnergy(seed, rarity, permanent)
Used to gather the energy requirements of a system upgrade. The returned value must be in Watts.
Parameters
rarity The rarity of the upgrade
permanent A bool indicating whether or not the upgrade was installed permanently
Expected return values
The amount of currently required energy, in Watts.
function updateParallelRead(timeStep)
Called every tick, both on client and server. See the documentation for getUpdateInterval() for details on the frequency of these calls. This function is executed in parallel with other entities, but not other scripts of the same entity. During this function, only reading values from the sector and its entities is allowed. Execution order of the updateXXX() functions is: updateParallelRead(), updateParallelSelf(), update(), update[Server/Client]()
Parameters
function updateParallelSelf(timeStep)
Called every tick, both on client and server. See the documentation for getUpdateInterval() for details on the frequency of these calls. This function is executed in parallel with other entities, but not other scripts of the same entity. During this function, only modifying the own entity is allowed, access to other entities in the sector is prohibited. Execution order of the updateXXX() functions is: updateParallelRead(), updateParallelSelf(), update(), update[Server/Client]()
Parameters
function onSectorChanged()
Executed whenever the entity changes sectors or when first inserted into a sector, for example while loading a sector or when the entity is first created.
function onIndexChanged(old, id)
Executed whenever the entity id changes, after the change took place. This happens *very* rarely and only when a database corruption was detected.
Parameters
id The new id of the entity
function initializationFinished()
Executed when a sector was loaded entirely and is ready. This function is called on the client after a new sector was received and once it has been completely created and initialized. On the server, this function is called after a sector was generated or loaded from disk and once it has been completely initialized. The function is also called on every Entity that is added to an existing, initialized sector, once it can access all other entities. Use this function if you need to access other Entity objects or the Sector object during initialization, since they may not be available in the initialize() call.
Entity Example Script
-- This function is always the very first function that is called in a script, and only once during
-- the lifetime of the script. The function is always called on the server first, before client
-- instances are available, so invoking client functions will never work. This function is both
-- called when a script gets newly attached to an object, and when the object is loaded from the
-- database during a load from disk operation. During a load from disk operation, no parameters
-- are passed to the function, and a global variable '_restoring' is set to true.
function initialize(...)
end
-- Called every tick, both on client and server. See the documentation for getUpdateInterval()
-- for details on the frequency of these calls.
function update(timeStep)
end
-- Defines the update tick interval of the script. This interval can not be less than the update
-- tick interval of the server or client, depending on where the script is running. The update(),
-- updateParallelRead(), updateParallelSelf(), updateClient() and updateServer() functions will
-- only be called after at least this much time has passed. The minimum update interval for the
-- client varies with the framerate of the client. The minimum update interval for the server
-- is 50 ms. This function is called after initialize() or after the update functions were called.
-- If this function is not defined, the update functions will be called every tick.
function getUpdateInterval()
end
-- Called when the script is about to be removed from the object, before the removal.
function onRemove()
end
-- Called when the script is about to be deleted from the object, before the deletion. This is
-- the last call that will be done to an object script. This function is also called when the
-- object it is attached to is deleted.
function onDelete()
end
-- Called to secure values from the script. This function is called when the object is unloaded
-- from the server. It's called at other times as well to refresh data, or when objects are copied
-- or during regular saves. The table returned by this function will be passed to the restore()
-- function when the object is loaded and read from disk. All values that are in the table must
-- be numbers, strings or other tables. Values that aren't of the above types will be converted
-- to nil and an error message will be printed.
function secure()
end
-- Called to restore previously secured values for the script. This is called after initialize().
-- Receives the values that were gathered from the last called to the secure() function. This
-- function is called when the object is read from disk and restored, after initialize() was called.
function restore(values)
end
-- This function is called when the game initializes the UI of the script. This function is only
-- called once per script. You should initialize all your UI elements in this function and register
-- all interactions for the entity here as well, so that they will be visible when the player
-- interacts with the entity.
-- Client Function: This function is only called on the client.
function initUI()
end
-- Executed whenever the player starts interacting with the script, before the registered interaction
-- callback function is executed.
-- Client Function: This function is only called on the client.
function onInteract(optionIndex)
end
-- Executed when the player starts interacting with the script and the registered window is shown.
-- Client Function: This function is only called on the client.
function onShowWindow(optionIndex)
end
-- Executed when the player stops interacting with the script or closes the main window for the
-- specific interaction.
-- Client Function: This function is only called on the client.
function onCloseWindow(optionIndex)
end
-- Executed every tick while the player is interacting with the script. This function is expensive,
-- so only define it if you need your script to be updated every tick.
-- Client Function: This function is only called on the client.
function updateUI()
end
-- Executed every tick while the player is interacting with the script. During this function,
-- render calls are valid and can be done. All render calls from this function will be drawn over
-- the current window. This function is expensive, so only define it if you need it.
-- Client Function: This function is only called on the client.
function renderUI()
end
-- Executed every tick if the entity is selected by the player. During this function, render calls
-- are valid and can be done. All render calls from this function will be drawn on the same 2D
-- plane as other UI indicators. This function is expensive, so only define it if you need it.
-- Client Function: This function is only called on the client.
function renderUIIndicator(x, y, size)
end
-- Executed every tick. During this function, render calls are valid and can be done. All render
-- calls from this function will be drawn below the main HUD. This function is expensive, so only
-- define it if you need it.
-- Client Function: This function is only called on the client.
function renderUIPreHud()
end
-- Executed every tick. During this function, render calls are valid and can be done. All render
-- calls from this function will be drawn over the main HUD. This function is expensive, so only
-- define it if you need it.
-- Client Function: This function is only called on the client.
function renderUIPostHud()
end
-- Executed whenever a keyboard event is sent to the script. Keyboard events might be caught by
-- other active menus first. If this function returns true then the event will be interpreted
-- as used and won't be sent to any other menus.
-- Client Function: This function is only called on the client.
function onKeyboardEvent(key, pressed)
end
-- Executed whenever a mouse event is sent to the script. Mouse events might be caught by other
-- active menus first. If this function returns true then the event will be interpreted as used
-- and won't be sent to any other menus.
-- Client Function: This function is only called on the client.
function onMouseEvent(key, pressed, x, y)
end
-- Determines whether or not the entity can be interacted with. If no values are returned or the
-- function isn't defined, interaction will be deemed not possible. The game checks for general
-- interaction possibilities sometimes, for example when a player selects a station, to show the
-- "Press F to interact" text. If a non-empty error message is returned, the result will be interpreted
-- as "failed", even if the first value was true.
-- Client Function: This function is only called on the client.
function interactionPossible(playerIndex, optionIndex)
end
-- Update tick that is only executed on the client. See the documentation for getUpdateInterval()
-- for details on the frequency of these calls. Execution order of the updateXXX() functions is:
-- updateParallelRead(), updateParallelSelf(), update(), update[Server/Client]().
-- Client Function: This function is only called on the client.
function updateClient(timeStep)
end
-- A function that is used by the UI to get the icon that will be used for the script interaction
-- button on the top right of the screen. This function should return a string containing the
-- path to the icon (example: "data/textures/icons/jigsaw-piece.png"). If this function isn't
-- defined, or if nothing or empty string is returned, the displayed icon will be a placeholder
-- icon. This function will only be called if the interactionPossible(...) test didn't fail.
-- Client Function: This function is only called on the client.
function getIcon()
end
-- Update tick that is only executed on the server. See the documentation for getUpdateInterval()
-- for details on the frequency of these calls. Execution order of the updateXXX() functions is:
-- updateParallelRead(), updateParallelSelf(), update(), update[Server/Client]().
-- Server Function: This function is only called on the server.
function updateServer(timeStep)
end
-- Executed when the entity enters an area that triggers a sector transfer (ie. gate, wormhole).
-- This should return a boolean value that indicates whether the entity can be transferred to
-- the other sector or not. If any script that is attached to the entity and that implements this
-- function returns false, the transfer fails and the entity won't be transferred. If a script
-- doesn't implement this function, the value is interpreted as true.
-- Server Function: This function is only called on the server.
function isTransferrable(id, x, y)
end
-- Executed if the entity has an EntityTransferrer component and when an entity enters the area
-- that triggers a sector transfer. This should return a boolean value that indicates whether
-- the entity can be transferred to the other sector or not. If any script that is attached to
-- the entity and that implements this function returns false, the transfer fails and the entity
-- won't be transferred. If a script doesn't implement this function, the value is interpreted
-- as true.
-- Server Function: This function is only called on the server.
function canTransfer(id)
end
-- Used to gather the energy requirements of a system upgrade. The returned value must be in Watts.
function getEnergy(seed, rarity, permanent)
end
-- Used to gather the energy requirements of a system upgrade. The returned value must be in Watts.
function getEnergy(seed, rarity, permanent)
end
-- Called every tick, both on client and server. See the documentation for getUpdateInterval()
-- for details on the frequency of these calls. This function is executed in parallel with other
-- entities, but not other scripts of the same entity. During this function, only reading values
-- from the sector and its entities is allowed. Execution order of the updateXXX() functions is:
-- updateParallelRead(), updateParallelSelf(), update(), update[Server/Client]()
function updateParallelRead(timeStep)
end
-- Called every tick, both on client and server. See the documentation for getUpdateInterval()
-- for details on the frequency of these calls. This function is executed in parallel with other
-- entities, but not other scripts of the same entity. During this function, only modifying the
-- own entity is allowed, access to other entities in the sector is prohibited. Execution order
-- of the updateXXX() functions is: updateParallelRead(), updateParallelSelf(), update(), update[Server/Client]()
function updateParallelSelf(timeStep)
end
-- Executed whenever the entity changes sectors or when first inserted into a sector, for example
-- while loading a sector or when the entity is first created.
function onSectorChanged()
end
-- Executed whenever the entity id changes, after the change took place. This happens *very* rarely
-- and only when a database corruption was detected.
function onIndexChanged(old, id)
end
-- Executed when a sector was loaded entirely and is ready. This function is called on the client
-- after a new sector was received and once it has been completely created and initialized. On
-- the server, this function is called after a sector was generated or loaded from disk and once
-- it has been completely initialized. The function is also called on every Entity that is added
-- to an existing, initialized sector, once it can access all other entities. Use this function
-- if you need to access other Entity objects or the Sector object during initialization, since
-- they may not be available in the initialize() call.
function initializationFinished()
end
Callbacks Alliance [Client] Callbacks Alliance [Server] Callbacks Alliance [Server] Callbacks Entity Callbacks Galaxy Callbacks Player Callbacks Player [Client] Callbacks Sector Callbacks Server Callbacks
Command Entity FactionDatabase PlanGenerator Player Sector Server UsableInventoryItem
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
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
EntityIcon EntityTooltip PlanMesh ReadOnlyIcon ReadOnlyPlanMesh ReadOnlyScriptUI ReadOnlyTooltip ScriptUI
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
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
EntityTransferrer FighterController Loot ReadOnlyEntityTransferrer ReadOnlyFighterController ReadOnlyLoot ReadOnlyTurretController ReadOnlyWreckageCreator TurretController WreckageCreator
Alliance [Server] Faction [Server] Galaxy [Server] Player [Server] ReadOnlySector Sector [Server] Server ShipDatabaseEntry [Server]
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 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.7 c8e4beec84f7