Avorion Script API Documentation
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
Returns
The queried variable, or nil if non-existant
function string getLanguage()
function string GetLocalizedString(string singular)
Parameters
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
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
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
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
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
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
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
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
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
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
Returns
The length of the vector
function var length2(var vec)
Calculates the squared length of a vector
Parameters
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
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
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
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
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
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
Returns
nothing
function var printlog(var... args)
Similar to print, but prints to the log file.
Parameters
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
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
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
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
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
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
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
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
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
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
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
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
Returns
nothing
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