# Avorion Script API Documentation

Home Functions Search
Search:

Functions
addCountdownBar
addSectorProblem
addShipProblem
appTime
appTimeMs
AsteroidDescriptor
async
async
async
asyncf
asyncf
asyncf
broadcastInvokeClientFunction
calculateJumpPath
canBoard
canBuildAdvancedBlocksInCurrentEnvironment
canBuildInCurrentEnvironment
canRepairInCurrentEnvironment
CargoLootDescriptor
checkReadSecureFilename
checkWriteSecureFilename
ColorARGB
ColorHSV
ColorInt
ColorNone
ColorPalette
ColorRGB
copy
createDirectory
createMonetaryString
CreateTemplateFromTurret
credits
CrewLootDescriptor
cross
deferredCallback
deleteFile
displayChatMessage
displayMissionAccomplishedText
displaySpeechBubble
distance
distance2
dot
drawBorder
drawDebugBox
drawDebugLine
drawDebugSphere
drawFighterTooltip
drawRect
drawText
drawTextRect
drawTurretTooltip
DroneDescriptor
eprint
FighterDescriptor
GameSeed
GameVersion
GeneratePlanFromStyle
getColorPalette
getCurrentLanguage
getGlobal
getLanguage
GetLocalizedString
getParentEntity
getParentFaction
getParentFaction
getPlayerCraft
getReadableValue
getResolution
getSavedShips
getScriptPath
getSessionId
getTrackedMissionScriptIndex
getWorkshopShips
HighestRarity
InventoryItemLootDescriptor
invokeAllianceFunction
invokeClientFunction
invokeEntityFunction
invokeEntityFunction
invokeFactionFunction
invokeSectorFunction
invokeSectorFunction
invokeServerFunction
isAllianceScript
isBehemothDLCInstalled
isBlackMarketDLCInstalled
isEntityScript
isGalaxyScript
isIntoTheRiftDLCInstalled
isPlayerScript
isSectorScript
IsValidMaterial
keycodeFromScancode
length
length2
listFilesOfDirectory
loadInternalData
LoadPlanFromFile
LoadPlanFromString
LoadTurretDesignFromFile
lookAt
LowestRarity
makeFastHash
makeHash
makeHash64
MatrixLookUp
MatrixLookUpPosition
MatrixLookUpRight
MatrixYawPitchRoll
Mods
MoneyLootDescriptor
normalize
normalize_ip
NumMaterials
onClient
onClient
onClient
onServer
onServer
onServer
ownsBehemothDLC
ownsBlackMarketDLC
ownsIntoTheRiftDLC
perspective
play3DSound
playSound
plural_t
plural_with_context_t
print
printlog
projectPoint
registerBoss
removeCountdownBar
removeDirectory
removeSectorProblem
removeShipProblem
reportError
ResourceLootDescriptor
rotate
run
run
runEntityCode
runFactionCode
runSectorCode
scale
scancodeFromKeycode
scriptPath
SectorSeed
SeedStr
serializable
setBossBarTitle
setBossHealth
setBossHealthColor
setCountdownPriority
setGlobal
setTrackedMission
setTrackThisMission
ShipDescriptor
sleep
StationDescriptor
SystemUpgradeLootDescriptor
terminate
TorpedoDescriptor
translate
trim
TurretDescriptor
TurretLootDescriptor
unregisterBoss
valid
WormholeDescriptor
WreckageDescriptor
wreckify
writeTrace

# Global Functions

function Uuid addCountdownBar(float countdownTime, string text, var priority)

This function is only available on the client.

function var addSectorProblem(string type, string text, string icon, var color, var withHighlight)

This function is only available on the client.

Returns

nothing

function var addShipProblem(string type, Uuid uuid, string text, string icon, var color, var withHighlight)

This function is only available on the client.

Returns

nothing

function double appTime()

Returns the system time in seconds. Since lua doesn't support clocks that are accurate down to milliseconds.

Returns

The system time in seconds

function double appTimeMs()

Returns the system time in milliseconds. Since lua doesn't support clocks that are accurate down to milliseconds.

Returns

The system time in milliseconds

function EntityDescriptor AsteroidDescriptor()

function var async(string callbackFunction, string code, var... arguments)

Starts an asynchronous call that will be executed in a separate thread. Once finished, the given callback function will be called with the values returned by the run() function, which is required to be in the code to run. During the running of this function, only server, galaxy, players and factions can be accessed, other objects like sector and entities can't be accessed. The amount of threads in the thread pool responsible for running these async calls can be configured in the server.ini file.
This function is only available on the server.

Parameters

callbackFunction The function in the current script that will be called once the asynchronous execution is finished
code The code that will be executed. Has to contain a function run(...). The run() function will be given the arguments that are passed after this parameter.
arguments The arguments that will be passed to the run() function

Returns

nothing

function var async(string callbackFunction, string code, var... arguments)

Returns

nothing

function var async(string callbackFunction, string code, var... arguments)

Starts an async call that will be executed in a separate thread. Once finished, the given callback function will be called with the values returned by the run() function, which is required to be in the code to run. During the running of this function, only players and factions can be accessed, other objects like sector and entities can't be accessed.
This function is only available on the client.

Parameters

callbackFunction The function in the current script that will be called once the asynchronous execution is finished
code The code that will be executed. Has to contain a function run(...). The run() function will be given the arguments that are passed after this parameter.
arguments The arguments that will be passed to the run() function.

Returns

nothing

function var asyncf(string callbackFunction, string fileName, var... arguments)

Returns

nothing

function var asyncf(string callbackFunction, string file, var... arguments)

Starts an asynchronous call that will be executed in a separate thread. Once finished, the given callback function will be called with the values returned by the run() function, which is required to be in the code to run. During the running of this function, only server, galaxy, players and factions can be accessed, other objects like sector and entities can't be accessed. The amount of threads in the thread pool responsible for running these async calls can be configured in the server.ini file.
This function is only available on the server.

Parameters

callbackFunction The function in the current script that will be called once the asynchronous execution is finished
file The file that will be executed. Path must be in format "data/scripts/path/to/file.lua". Will also files added or extended by mods. The file must contain a function run(...). The run() function will be given the arguments that are passed after this parameter.
arguments The arguments that will be passed to the run() function

Returns

nothing

function var asyncf(string callbackFunction, string file, var... arguments)

Starts an async call that will be executed in a separate thread. Once finished, the given callback function will be called with the values returned by the run() function, which is required to be in the code to run. During the running of this function, only players and factions can be accessed, other objects like sector and entities can't be accessed.
This function is only available on the client.

Parameters

callbackFunction The function in the current script that will be called once the asynchronous execution is finished
file The file that will be executed. Path must be in format "data/scripts/path/to/file.lua". Will also files added or extended by mods. The file must contain a function run(...). The run() function will be given the arguments that are passed after this parameter.
arguments The arguments that will be passed to the run() function.

Returns

nothing

function var broadcastInvokeClientFunction(string functionName, var... arguments)

Invokes a function on *all* remote clients, in the client instances of the caller script. Return values of the remotely executed functions cannot be retrieved.
This function is only available on the server.

Parameters

functionName The name of the scripting function that is to be executed
arguments An arbitrary number of arguments that will be given to the remote function

Returns

nothing

function table_t calculateJumpPath(Player [or nil] player, Alliance [or nil] alliance, vec2 origin, vec2 destination, float jumpRange, bool canPassRifts)

Calculates a jump path on the galaxy map. ATTENTION: this might take a while, depending on the distance and rifts
This function is only available on the server.

Parameters

player The player whose knowledge of gates is used (or nil)
alliance The alliance whose knowledge of gates is used (or nil)
origin The origin of the calculation
destination The desired target (may lie in a rift)
jumpRange How far the ship can jump
canPassRifts true if the ship can jump across rifts, false otherwise

function bool, var canBoard(Entity ship)

function bool canBuildAdvancedBlocksInCurrentEnvironment(Entity ship)

Checks if, everything considered, advanced blocks can be built on a ship in its current situation.

Parameters

ship The ship that should be modified

Returns

A bool holding the result

function gut::BuildError canBuildInCurrentEnvironment(Entity ship)

Checks if, everything considered, a ship can be modified by building in its current situation.

Parameters

ship The ship that should be modified

Returns

a BuildError enum value holding the result

function gut::BuildError canRepairInCurrentEnvironment(Entity ship)

Checks if, everything considered, a ship can be repaired in its current situation.

Parameters

ship The ship that should be repaired

Returns

a BuildError enum value holding the result

function EntityDescriptor CargoLootDescriptor()

function bool checkReadSecureFilename(string )

function bool checkWriteSecureFilename(string )

function Color ColorARGB(float a, float r, float g, float b)

function Color ColorHSV(float h, float s, float v)

function Color ColorInt(int i)

function Color ColorNone()

function Color... ColorPalette()

function Color ColorRGB(float r, float g, float b)

function UserObject copy(var value)

Copies the given Object

Parameters

value A non-POD, non-table object

Returns

A true copy of the given object

function var createDirectory(string directory)

Creates a new directory, including all required parent directories. Security-specific behavior: Creating directories is only possible in the moddata/ subdirectory of the Avorion settings folder.

Parameters

directory Path to the directory to create

Returns

A system error code indicating if the operation was successful

function string createMonetaryString(double number)

Inserts dots into a large number to create an easily human readable money string. Example: 10000000 will become 10.000.000

Parameters

number The large number

Returns

A string containing the readable number

function TurretTemplate CreateTemplateFromTurret(Entity turret)

function string credits()

function EntityDescriptor CrewLootDescriptor()

function var cross(var a, var b)

Calculates the dot product between two vec3s. The vectors must have the same underlying type (double or float).

Parameters

a vector a
b vector b

Returns

The cross product of the vectors

function bool deferredCallback(double time, string function, var... args)

Registers a deferred callback in the script. The given function will be executed after the given time. Depending on the tick rate of the simulation, the callback might get called slightly later than the given time. The callback will never happen before the given time hasn't passed.

Parameters

time The time in seconds to wait until the callback will be executed
function The function that is to be executed once the time has passed as a string
args... Arguments that will be passed to the callback function. Only non-user objects are supported. vec234 objects and uuids will be converted to tables/strings

Returns

true if the callback was registered, false otherwise

function var deleteFile(string file)

Deletes a file. Error codes behave the same way as rmdir(). Security-specific behavior: Removing files is only possible in the moddata/ subdirectory of the Avorion settings folder.

Parameters

file Path to the file to delete

Returns

A system error code indicating if the operation was successful

function var displayChatMessage(string message, string sender, int type)

This function displays a chat message on the Chat window of the client.
This function is only available on the client.

Parameters

message The message that will be displayed in the chat window
sender The sender that will be displayed for the chat message
type The type of chat message, 0 = Normal, 1 = Error, 2 = Warning, 3 = Info

Returns

nothing

function var displayMissionAccomplishedText(string bigText, string smallText)

This function is only available on the client.

Returns

nothing

function var displaySpeechBubble(Entity entity, string text)

This function displays a speech bubble next to the given entity. If text is too long then it will be shortened and a "..." will be added.
This function is only available on the client.

Parameters

entity The entity next to which the speech bubble should appear
text The text that will be displayed in the speech bubble

Returns

nothing

function var distance(var a, var b)

Calculates the linear distance between two vectors. The vectors must have the same type.

Parameters

a vector a
b vector b

Returns

The linear distance between the vectors

function var distance2(var a, var b)

Calculates the squared linear distance between two vectors. The vectors must have the same type.

Parameters

a vector a
b vector b

Returns

The squared linear distance between the vectors

function var dot(var a, var b)

Calculates the dot product between 2 vectors. The vectors must have the same type.

Parameters

a vector a
b vector b

Returns

The dot product between the two vectors

function var drawBorder(Rect rect, Color color)

Draw a border. This function should only be called in valid rendering steps. This function is expensive, don't overuse it.
This function is only available on the client.

Parameters

rect The rect that is to be drawn
color The color of the rect

Returns

nothing

function var drawDebugBox(Box box, Matrix matrix, Color color)

This function is only available on the client.

Returns

nothing

function var drawDebugLine(vec3 a, vec3 b, Color color)

This function is only available on the client.

Returns

nothing

function var drawDebugSphere(Sphere sphere, Color color)

This function is only available on the client.

Returns

nothing

function var drawFighterTooltip(FighterTemplate fighter)

This function is only available on the client.

Returns

nothing

function var drawRect(Rect rect, Color color)

Draw a rect. This function should only be called in valid rendering steps. This function is expensive, don't overuse it.
This function is only available on the client.

Parameters

rect The rect that is to be drawn
color The color of the rect

Returns

nothing

function var drawText(string text, int px, int py, Color color, int size, int bold, int italic, int style)

Draw text. This function should only be called in valid rendering steps. This function is expensive, don't overuse it.
This function is only available on the client.

Parameters

text The text that is to be rendered
px The x value in pixels of the position, ie. upper left
py The y value in pixels of the position, ie. upper left
color The color of the text
size The font size of the rendered text
bold Use 1 if the text should be bold, 0 otherwise
italic Use 1 if the text should be italic, 0 otherwise
style The style of the text, 0 is default style, 1 is shadowed, 2 is outlined

Returns

nothing

function var drawTextRect(string text, Rect rect, int horizontalAlignment, int verticalAlignment, Color color, int size, int bold, int italic, int style)

Draw text inside a rect. This function should only be called in valid rendering steps. This function is expensive, don't overuse it.
This function is only available on the client.

Parameters

text The text that is to be rendered
rect The rect that functions as boundaries for the text
horizontalAlignment -1 to position the text at the left, 0 to center it horizontally, +1 to position the text at the right
verticalAlignment -1 to position the text at the top, 0 to center it vertically, +1 to position the text at the bottom
color The color of the text, as an int
size The font size of the rendered text
bold Use 1 if the text should be bold, 0 otherwise
italic Use 1 if the text should be italic, 0 otherwise
style The style of the text, 0 is default style, 1 is shadowed, 2 is outlined

Returns

nothing

function var drawTurretTooltip(TurretTemplate turret)

This function is only available on the client.

Returns

nothing

function EntityDescriptor DroneDescriptor()

function var eprint(var... args)

Prints errors to the console. In the ingame console, server output will be printed in magenta, client output will be printed in darkish red.

Parameters

args Any number of arguments. The first value can be a format string. If no formatting can be done then the function falls back to printing all given values.

Returns

nothing

function EntityDescriptor FighterDescriptor()

function Seed GameSeed()

function Version GameVersion()

function BlockPlan GeneratePlanFromStyle(PlanStyle style, Seed seed, float volume, int maxBlocks, var scaleToFit, Material material)

function static std::map<ScriptColor, std::string> getColorPalette()

function string getCurrentLanguage()

Returns the current language code.
This function is only available on the client.

Returns

The language code, e.g. "en", "de", "ru", etc.

function var getGlobal(string name)

Retrieves a global variable. These variables are shared over the entire process.

Parameters

name The name of the global variable

Returns

The queried variable, or nil if non-existant

function string getLanguage()

function string GetLocalizedString(string singular)

Parameters

singular The english string

Returns

The translated string, or, if no translation exists, the english string, with comment removed

function Entity getParentEntity()

function UserObject getParentFaction()

This function is only available on the server.

function UserObject getParentFaction()

This function is only available on the client.

function Entity getPlayerCraft()

This function is only available on the client.

function double, string getReadableValue(double number)

Rounds a large number and adds a suffix such as k or M. For example, 10.000 will become 10k.

Parameters

number The number to make readable

Returns

A string containing the rounded number and the suffix

function vec2 getResolution()

This function is only available on the client.

function string... getSavedShips()

This function is only available on the client.

function string getScriptPath()

Returns the exact path of the top-level script file that this function is called from. If the script has been required by other scripts, it will return the path that was given to, for example, the function Entity():addScript(path, args...). This function can be used to determine the script path that has to be used by, for example, calls to Entity():invokeFunction(script, args...)

Returns

A string containing the path to the top-level script file

function uuid getSessionId()

This function is only available on the client.

function var getTrackedMissionScriptIndex()

Get the script index of the currently tracked mission
This function is only available on the client.

Returns

The int index of the tracked mission script or nil

function string... getWorkshopShips()

This function is only available on the client.

function Rarity HighestRarity()

function EntityDescriptor InventoryItemLootDescriptor()

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

Invokes a function on the server on the alliance of the player, during its update step. Return values of the remotely executed function cannot be retrieved. The player must be in an alliance for this call to succeed. Due to technical, multithreading-related restrictions, there is no way to check at the time of the call, if the target script or function exists in the sector. If it doesn't this call will silently fail.
This function is only available on the client.

Parameters

scriptName The name of the called script
functionName The name of the called function
arguments The arguments that will be passed to the function.

Returns

nothing

function var invokeClientFunction(Player player, string functionName, var... arguments)

Invokes a function on a remote client, in the client instance of the caller script. Example usage would be a server Resource Trader calling the setData() function of its client instance. Return values of the remotely executed functions cannot be retrieved.
This function is only available on the server.

Parameters

player The player of the client the function should be invoked on
functionName The name of the scripting function that is to be executed
arguments An arbitrary number of arguments that will be given to the remote function

Returns

nothing

function var invokeEntityFunction(int x, int y, string errorMessage, var entityId, string scriptName, string functionName, var... arguments)

Invokes a function on the server of a script on an entity in an arbitrary sector, during its update step. Return values of the remotely executed function cannot be retrieved. The sector must be loaded in memory in order for this call to succeed. It will not be loaded from disk or generated. Due to technical, multithreading-related restrictions, there is no way to check at the time of the call, if the target entity or the script or the script function exists in the sector. If it doesn't this call will silently fail.
Example invocations:
invokeEntityFunction(x, y, error, {faction = player.index, name = "The Executor"}, "myscript.lua", "myfunction", arg1, arg2, arg3)
invokeEntityFunction(x, y, error, craftId, "myscript.lua", "myfunction", arg1, arg2, arg3)
invokeEntityFunction(x, y, error, "3d477214-4b7d-4fd0-9114-18b8cafa5a91", "myscript.lua", "myfunction", arg1, arg2, arg3)
This function is only available on the client.

Parameters

x The x-coordinate of the target sector
y The y-coordinate of the target sector
errorMessage If not nil, the error message that is sent back in case the target sector isn't loaded
entityId The Uuid of the entity whose script will be called. Can also be a uuid string. A table containing a faction index and craft name can also be passed, such as {faction = 1338, name = "MyAwesomeShip"}
scriptName The name of the called script
functionName The name of the called function
arguments The arguments that will be passed to the function.

Returns

nothing

function int invokeEntityFunction(int x, int y, bool printErrors, var entityId, string scriptName, string functionName, var... arguments)

Invokes a function of a script on an entity in an arbitrary sector, during its update step. Use this function to call functions on entities that are in other sectors than the current script. The sector must be loaded in memory in order for this call to succeed. It will not be loaded from disk or generated. The function will not be run immediately, but it might take up to one update tick until it is run. Therefore, return values of the executed functions will not be retrieved. Due to technical, multithreading-related restrictions, there is no way to check at the time of the call, if the target entity or the script or the script function exists in the sector. If it doesn't this call will silently fail. To get an error message printed out on failure as to why it failed, pass 'true' to the 'printErrors' parameter.
Example invocations:
invokeEntityFunction(x, y, dbgBool, {faction = player.index, name = "The Executor"}, "myscript.lua", "myfunction", arg1, arg2, arg3)
invokeEntityFunction(x, y, dbgBool, craftId, "myscript.lua", "myfunction", arg1, arg2, arg3)
invokeEntityFunction(x, y, dbgBool, "3d477214-4b7d-4fd0-9114-18b8cafa5a91", "myscript.lua", "myfunction", arg1, arg2, arg3)
This function is only available on the server.

Parameters

x The x-coordinate of the target sector
y The y-coordinate of the target sector
printErrors A bool indicating whether or not an error message should be printed on failure
entityId The Uuid of the entity whose script will be called. Can also be a uuid string. A table containing a faction index and craft name can also be passed, such as {faction = 1338, name = "MyAwesomeShip"}
scriptName The name of the called script
functionName The name of the called function
arguments The arguments that will be passed to the function

Returns

1 if the sector wasn't loaded into memory, 0 otherwise.

function int invokeFactionFunction(int factionIndex, bool printErrors, string scriptName, string functionName, var... arguments)

Invokes a function on a script of a player, during its sector's update step. Use this function to execute functions of scripts of a player that is in another sector than the one of the current script. The function will not be run immediately, but it might take up to one update tick until it is run. Therefore, return values of the executed functions will not be retrieved. Currently only invocations for logged-in players are supported. Due to technical, multithreading-related restrictions, there is no way to check at the time of the call, if the target script or function exists in the faction. If it doesn't this call will silently fail. To get an error message printed out on failure as to why it failed, pass 'true' to the 'printErrors' parameter.
This function is only available on the server.

Parameters

factionIndex The index of the targeted faction
printErrors A bool indicating whether or not an error message should be printed on failure
scriptName The name of the called script
functionName The name of the called function
arguments The arguments that will be passed to the function

Returns

1 if the player wasn't logged in, 0 otherwise.

function var invokeSectorFunction(int x, int y, var errorMessage, string scriptName, string functionName, var... arguments)

Invokes a function on the server on a script of a sector, during its update step. Return values of the remotely executed function cannot be retrieved. The sector must be loaded in memory in order for this call to succeed. It will not be loaded from disk or generated. Due to technical, multithreading-related restrictions, there is no way to check at the time of the call, if the target script or function exists in the sector. If it doesn't this call will silently fail.
This function is only available on the client.

Parameters

x The x-coordinate of the target sector
y The y-coordinate of the target sector
errorMessage If not nil, the error message that is sent back in case the target sector isn't loaded
scriptName The name of the called script
functionName The name of the called function
arguments The arguments that will be passed to the function.

Returns

nothing

function int invokeSectorFunction(int x, int y, bool printErrors, string scriptName, string functionName, var... arguments)

Invokes a function on a script of a sector, during its update step. Use this function to call functions on sectors other than the sector of the current script. The sector must be loaded in memory in order for this call to succeed. It will not be loaded from disk or generated. The function will not be run immediately, but it might take up to one update tick until it is run. Therefore, return values of the executed functions will not be retrieved. Due to technical, multithreading-related restrictions, there is no way to check at the time of the call, if the target script or function exists in the sector. If it doesn't this call will silently fail. To get an error message printed out on failure as to why it failed, pass 'true' to the 'printErrors' parameter.
This function is only available on the server.

Parameters

x The x-coordinate of the target sector
y The y-coordinate of the target sector
printErrors A bool indicating whether or not an error message should be printed on failure
scriptName The name of the called script
functionName The name of the called function
arguments The arguments that will be passed to the function

Returns

1 if the sector wasn't loaded into memory, 0 otherwise.

function var invokeServerFunction(string functionName, var... arguments)

Invokes a function on the remote server, in the server instance of the caller script. Example usage would be a server Resource Trader calling the getData() function of its server instance. Return values of the remotely executed functions are not retrieved. On the server side, a variable called "callingPlayer" will be created or set before executing the called function. callingPlayer contains the index of the calling player. Use this variable to verify that the calling player is actually the player you'd expect. After the call finishes on the server, callingPlayer is set to nil.
This function is only available on the client.

Parameters

functionName The name of the scripting function that is to be executed
arguments An arbitrary number of arguments that will be given to the remote function

Returns

nothing

function bool isAllianceScript()

function bool isBehemothDLCInstalled()

returns true if the Behemoth DLC is owned and installed according to local Steam
This function is only available on the client.

function bool isBlackMarketDLCInstalled()

returns true if the Black Market DLC is owned and installed according to local Steam
This function is only available on the client.

function bool isEntityScript()

function bool isGalaxyScript()

This function is only available on the server.

function bool isIntoTheRiftDLCInstalled()

returns true if the Into The Rift DLC is owned and installed according to local Steam
This function is only available on the client.

function bool isPlayerScript()

function bool isSectorScript()

function bool IsValidMaterial(int i)

function int keycodeFromScancode(int scancode)

This function is only available on the client.

function var length(var vec)

Calculates the length of a vector

Parameters

vec the vector

Returns

The length of the vector

function var length2(var vec)

Calculates the squared length of a vector

Parameters

vec the vector

Returns

The squared length of the vector

function string... listFilesOfDirectory(string directory)

Lists all files in a directory. Security-specific behavior: Listing files of directories is only possible in the moddata/ subdirectory of the Avorion settings folder.

Parameters

directory Path to the directory to remove

Returns

A list of files

function string loadInternalData(string path)

function BlockPlan LoadPlanFromFile(string file)

function BlockPlan LoadPlanFromString(string content)

function TurretDesign LoadTurretDesignFromFile(string path)

function Matrix lookAt(vec3 eye, vec3 at, vec3 up)

function Rarity LowestRarity()

function int makeFastHash(int x, int y, int seed)

function int makeHash(var... values)

function double makeHash64(var... values)

function Matrix MatrixLookUp(vec3 look, vec3 up)

function Matrix MatrixLookUpPosition(vec3 look, vec3 up, vec3 pos)

function Matrix MatrixLookUpRight(vec3 look, vec3 up, vec3 right)

function Matrix MatrixYawPitchRoll(float yaw, float pitch, float roll)

function table_t... Mods()

Returns a table containing all mods that are currently active. Order is the load order of the mods.

Returns

table containing all mods

function EntityDescriptor MoneyLootDescriptor()

function var normalize(var vec)

Normalizes a given vector. This function creates a new normalized vector, the given vector is not changed.

Parameters

vec the vector to normalize

Returns

The normalized result of the given vector

function var normalize_ip(var vec)

Normalizes a given vector. This function normalizes the vector in place.

Parameters

vec the vector to normalize

function int NumMaterials()

function bool onClient()

A function to find out in a script, whether it's currently executed on the client.
This function is only available on the client.

Returns

true when called on the client, false otherwise

function bool onClient()

This function is only available on the server.

function var onClient()

Returns

nothing

function bool onServer()

This function is only available on the server.

function var onServer()

Returns

nothing

function bool onServer()

A function to find out in a script, whether it's currently executed on the server.
This function is only available on the client.

Returns

true when called on the server, false otherwise

function bool ownsBehemothDLC()

returns true if the player owns the Behemoth DLC according to server
This function is only available on the client.

function bool ownsBlackMarketDLC()

returns true if the player owns the Black Market DLC according to server
This function is only available on the client.

function bool ownsIntoTheRiftDLC()

returns true if the player owns the Into The Rift DLC according to server
This function is only available on the client.

function Matrix perspective(float fov, float aspect, float nearClip, float farClip)

function var play3DSound(string soundName, int type, vec3 position, float radius, float volume, Entity [or nil] entity)

This function is only available on the client.

Returns

nothing

function var playSound(string soundName, int type, float volume)

This function is only available on the client.

Returns

nothing

function string plural_t(string singular, string plural, int number)

Parameters

singular The english singular string, will be used directly and no numbers will be formatted into it
plural The english plural string, may contain a ${i} variable that will be replaced by the number
number The number that is to be displayed

function string plural_with_context_t(string singular, string plural, string context, int number)

Parameters

singular The english singular string, will be used directly and no numbers will be formatted into it
plural The english plural string, may contain a ${i} variable that will be replaced by the number
context The context that is to be shown in the .po file
number The number that is to be displayed

function var print(var... args)

Prints to the console. In the ingame console, server output will be printed in cyan, client output will be printed in grey.

Parameters

args Any number of arguments. The first value can be a format string. If no formatting can be done then the function falls back to printing all given values.

Returns

nothing

function var printlog(var... args)

Similar to print, but prints to the log file.

Parameters

args Any number of arguments. The first value can be a format string. If no formatting can be done then the function falls back to printing all given values.

Returns

nothing

function vec3 projectPoint(vec3 p)

This function is only available on the client.

function var registerBoss(Uuid entityId, var healthColor, var shieldColor, var track, var name, var miniBoss)

This function is only available on the client.

Returns

nothing

function var removeCountdownBar(Uuid countdownId)

This function is only available on the client.

Returns

nothing

function var removeDirectory(string directory)

Removes an empty directory. Error codes behave the same way as rmdir(). Security-specific behavior: Removing directories is only possible in the moddata/ subdirectory of the Avorion settings folder.

Parameters

directory Path to the directory to remove

Returns

A system error code indicating if the operation was successful

function var removeSectorProblem(string type)

This function is only available on the client.

Returns

nothing

function var removeShipProblem(string type, Uuid uuid)

This function is only available on the client.

Returns

nothing

function var reportError(string string)

Sends an error report to avorion.net, including DebugInfo and StackTrace

Parameters

string containing the error that happened

Returns

nothing

function EntityDescriptor ResourceLootDescriptor()

function Matrix rotate(Matrix in, float angle, vec3 axis)

function var... run(string script, string func, var... params)

Loads a script into a separate, temporary VM and runs a single function in it. The script will be run in the same context as the script calling this function. When the script has a namespace defined, only functions within that namespace can be called. The first return value is an int indicating if the call succeeded, followed by any return values of the invoked function. 0 = success, 1 = invalid script path, 2 = error during script loading, 3 = error during execution
This function is only available on the client.

Parameters

script Name of the script to load
func Name of the function to call
params Parameters that will be passed to the function

Returns

An int indicating if the call succeeded, followed by the return values of the called function

function var... run(string script, string func, var... params)

Loads a script into a separate, temporary VM and runs a single function in it. The script will be run in the same context as the script calling this function. When the script has a namespace defined, only functions within that namespace can be called. The first return value is an int indicating if the call succeeded, followed by any return values of the invoked function. 0 = success, 1 = invalid script path, 2 = error during script loading, 3 = error during execution
This function is only available on the server.

Parameters

script Name of the script to load
func Name of the function to call
params Parameters that will be passed to the function

Returns

An int indicating if the call succeeded, followed by the return values of the called function

function int runEntityCode(int x, int y, bool printErrors, var entityId, string code, string functionName, var... arguments)

Runs code in the context of an entity in a sector, during its update step. Use this function to execute arbitrary code in the context of entities that are in other sectors than the current script. The sector must be loaded in memory in order for this call to succeed. It will not be loaded from disk or generated. The code will not be run immediately, but it might take up to one update tick until it is run. Therefore, return values of the executed functions will not be retrieved. Due to technical, multithreading-related restrictions, there is no way to check at the time of the call, if the target entity exists in the sector. If it doesn't this call will silently fail. To get an error message printed out on failure as to why it failed, pass 'true' to the 'printErrors' parameter.
This function is only available on the server.

Parameters

x The x-coordinate of the target sector
y The y-coordinate of the target sector
printErrors A bool indicating whether or not an error message should be printed on failure
entityId The Uuid of the entity whose script will be called. Can also be a uuid string. A table containing a faction index and craft name can also be passed, such as {faction = 1338, name = "MyAwesomeShip"}
code The code that will be run, must have at least one function defined that will be run
functionName The name of the called function
arguments The arguments that will be passed to the function

Returns

1 if the sector wasn't loaded into memory, 0 otherwise.

function int runFactionCode(int factionIndex, bool printErrors, string code, string functionName, var... arguments)

Runs code in the context of a player, during its sector's update step. Use this function to execute code in the context of a player that is in another sector than the one of the current script. The code will not be run immediately, but it might take up to one update tick until it is run. Therefore, return values of the remotely executed functions will not be retrieved. Currently only invocations for logged-in players are supported.
This function is only available on the server.

Parameters

factionIndex The index of the targeted faction
printErrors A bool indicating whether or not an error message should be printed on failure
code The code that will be run, must have at least one function defined that will be run
functionName The name of the called function
arguments The arguments that will be passed to the function

Returns

1 if the player wasn't logged in, 0 otherwise.

function int runSectorCode(int x, int y, bool printErrors, string code, string functionName, var... arguments)

Runs code in the context of a sector, during its update step. Use this function to execute code in the context of sectors other than the sector of the current script. The sector must be loaded in memory in order for this call to succeed. It will not be loaded from disk or generated. The code will not be run immediately, but it might take up to one update tick until it is run. Therefore, no return values of any executed functions will be retrieved.
This function is only available on the server.

Parameters

x The x-coordinate of the target sector
y The y-coordinate of the target sector
printErrors A bool indicating whether or not an error message should be printed on failure
code The code that will be run, must have at least one function defined that will be run
functionName The name of the called function
arguments The arguments that will be passed to the function

Returns

1 if the sector wasn't loaded into memory, 0 otherwise.

function Matrix scale(Matrix in, vec3 size)

function int scancodeFromKeycode(int key)

This function is only available on the client.

function string scriptPath()

Returns the path of the script that is currently being executed

Returns

string containing the path

function Seed SectorSeed(int x, int y, var seed)

function Seed SeedStr(string str)

function bool serializable(var value)

Checks if the given object is serializable (sendable via network).

Parameters

value

Returns

A boolean indicating whether the object is serializable. Returns false when given nil.

function var setBossBarTitle(Uuid id, string name)

This function is only available on the client.

Returns

nothing

function var setBossHealth(Uuid id, var health, var maxHealth, var shield, var maxShield)

This function is only available on the client.

Returns

nothing

function var setBossHealthColor(Uuid id, var health, var shield)

This function is only available on the client.

Returns

nothing

function var setCountdownPriority(Uuid countdownId, int newPriority)

This function is only available on the client.

Returns

nothing

function var setGlobal(string name, var value)

Sets a global variable. These variables are shared over the entire process.

Parameters

name The name of the global variable
value The value of the global variable. POD datatypes only. Nil deletes the variable.

Returns

nothing

function var setTrackedMission(int )

This function is only available on the client.

Returns

nothing

function var setTrackThisMission()

This function is only available on the client.

Returns

nothing

function EntityDescriptor ShipDescriptor()

function var sleep(float seconds)

sleeps for the given time

Returns

nothing

function EntityDescriptor StationDescriptor()

function EntityDescriptor SystemUpgradeLootDescriptor()

function var terminate()

Terminates the script. This function returns normally and the current function will run until finished, but no more following calls will be made to the script. The script will be removed from the entity on the next occasion.

Returns

nothing

function EntityDescriptor TorpedoDescriptor()

function Matrix translate(Matrix in, vec3 pos)

function string trim(string in)

function EntityDescriptor TurretDescriptor()

function EntityDescriptor TurretLootDescriptor()

function var unregisterBoss(Uuid entityId)

This function is only available on the client.

Returns

nothing

function bool valid(var value)

Checks if the given object is valid. Some objects can become invalid, for example when an entity is deleted the instances of the Entity in the scripts will become invalid.

Parameters

value A non-POD, non-table object

Returns

A boolean indicating whether the object is valid. Returns false when given nil.

function EntityDescriptor WormholeDescriptor()

function EntityDescriptor WreckageDescriptor()

function var wreckify(BlockPlan plan)

Removes holo blocks, darkens light blocks and replaces some blocks with wreckage blocks

Parameters

plan The plan that will be modified

Returns

nothing

function var writeTrace(var... args)

Similar to print, but prints to the user trace stream. This trace stream can be enabled by passing "-t user" to the command line arguments of client or server.

Parameters

args Any number of arguments. The first value can be a format string. If no formatting can be done then the function falls back to printing all given values.

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