User Tools

Site Tools

Urban Games

modding:gamescripts

Game Scripts

With game scripts, it is possible to provide functions that are called in certain situations. Game script files are located in res/config/game_script and they contain a data() function:

function data()
  return {
    save = function() end,
    load = function(loadedstate) end,
    update = function() end,
    guiHandleEvent = function (id, name, param) end,
    handleEvent = function (src, id, name, param) end,
    ...
  }

The returned table has a list of callbacks which may called by the game. Actually, the game has two seperate threads:

  • the engine thread that deals with the simulation
  • the ui thread that deals with the visualization

Both threads are seperated and it is not possible to directly share variables between them!

The list in a game script consist of functions some of which are called by the engine (e.g. save, update), some of which are called by the ui (e.g. guiUpdate) and some of which are called by both (e.g. load).

It is possible to use api functions in the callback functions. See the API reference for further details.

Engine Callbacks

There are four callbacks that are used by the engine thread:

  • load = function (allState) is the callback that is called once on savegame load to retrieve the state data that was stored with the savegame.
  • save = function () is a callback that can be triggered to save data to the shared state from where it can be persisted on savegame save.
  • update = function() is a callback that is regularily called to do update processing in the engine simulation.
  • handleEvent = function (src, id, name, param) is a callback that is called whenever an engine event happens.

UI Callbacks

There are four callbacks that are used by the ui thread:

  • load = function (allState) is the callback that is regularily called to fetch data from the shared state.
  • guiInit = function() is a callback that is called once on startup.
  • guiUpdate = function() is a callback that is regularily called to refresh the gui.
  • guiHandleEvent = function (id, name, param) is a callback that is called whenever a gui event happens.

See the user interface documentation for detailed information on the ui callbacks.

Communication between Threads

To send information from the ui thread to the engine thread, it is possible to invoke an engine thread event that will be called later by the engine thread with

game.interface.sendScriptEvent(...)

The same game script or any other game script can then deal with it in its handleEvent callback.

To send information from the engine thread to the ui thread, the engine thread should use the save function to store some data. It can be accessed from the gui thread at a later point with the load callback that is triggered several times in a second.

Serialization

Some game scripts need the possibility to store some information into savegames and restore them at a later point. The save and load callbacks are used for this purpose too:

Save

The save callback is used to store information in a shared state that can be read by both threads to update their local state variables. When the game is saved, this state will be serialized and stored in the .sav.lua file that comes with the savegame.

  ...
  save = function ()
    return ...
  end,
  ...

The function has no parameters but returns a table that is then stored in

Load

The load callback is used to fetch the information from the shared state on savegame load and during the game. Both thread call it once on savegame load and it is repeatedly called during the game for the ui thread.

local state = { counter = 0 }
 
  ...
  load = function (allState)
    state = allState or state
  end,
  ...

The stored information is provided as a parameter and can then be proceeded in the callback method. As it is possible that savegames do not contain stored data, e.g. when the game script with the load callback was added with a new mod just before the load of the savegame, it is recommended to have a default state as fallback.

Please note that the game scripts only receive stored data that was saved from a game script file with the same filename. They do not get access to stored data of another script.

modding/gamescripts.txt · Last modified: 2021/03/03 08:27 by thomas