From Avorion Wiki
Jump to: navigation, search

Avorion can be modded by changing existing or adding new scripts to the game.

As of now, there are 3 different script types that are used by the game. Those are entity scripts, sector generator scripts and the server startup script. These scripts are loaded by the game and provide functions that will be executed by the game, all during runtime. This interface varies from script type to script type.

There are already a lot of scripts running in the game. There are scripts doing the generation of new sectors, as well as scripts running in entities. Every station you find and their interactions are implemented via scripts.

Disclaimer: In order to mod the game, you should have a basic understanding of programming and the programming language lua.

General Interface[edit | edit source]

Script Functions[edit | edit source]

Scripts need to have a certain methods defined, depending on the type of the script. When a script is loaded, the entire script will be executed once. After this, the game will try to invoke certain functions defined in the script. The exact name and arguments of functions depend on the type of the script.

The general interface for a script function looks something like this:

function generate(context, playerIndex, seed, x, y)
    -- do some stuff here

Script functions that are not used by the script (especially those that would be called every update frame) should not be defined in the script in order to improve performance. Executing an empty function is slower than not even calling it.

API Functions[edit | edit source]

The game offers an API of various functions that can be called from scripts. These functions are either bound to an object, or can be called without a specific object.

Functions that are associated with an object follow a naming pattern, where the object type name comes first, followed by an underscore character, followed by the name of the function.

An example for such a function would be:

Entity_SetPosition(context, entityIndex, x, y, z)

This function is called "SetPosition" and is associated with the object type "Entity".

The context argument[edit | edit source]

The variable context is a variable that connects the lua script instance to the actual script running in the game's lua VM. When the game invokes a function of a script, it will always provide the variable context. This variable needs to be given to nearly every API call of the game API.

This variable should not be changed, as this will lead to execution of API calls in the wrong context, which may very easily crash the game and lead to data loss.

The only thing that has to be done with this variable is to subsequently pass it to each game API call invoked by the script.

Callbacks[edit | edit source]

Scripts can register callback handlers for different callbacks. These handlers will then be executed whenever a certain event happens.

To register a callback handler, use the callback registration functions. Registering a callback would look something like this:

Server_RegisterCallback(context, "onPlayerLogOff", "handlePlayerLogoff")

function handlePlayerLogoff(context, player)
    writeConsole("A player has logged out.")

In this example, a function called "handlePlayerLogOff" is registered at the server as the callback handler for the event "onPlayerLogOff". So, whenever a player logs out of the server this function will be executed.

For a complete documentation on the callbacks, see the document ScriptingCallbacks.html in your Documentation/ folder in your Avorion installation folder.