Stats GUI Remote Interface Documentation - raiguard/Factorio-SmallMods GitHub Wiki

The remote interface is named StatsGui.

The current interface version is 1.

HOW-TO:

See the Factorio documentation for instructions on using remote interfaces.

Usage

The Stats GUI remote interface works by external mods specifying a set of remote interface functions to call. Stats GUI will then call these functions when it updates. There are two types of functions that can be registered to Stats GUI:

• Preprocessors are used to execute some logic that only needs to run once per update cycle, and produces some kind of output that a sensor will use. For example, Stats GUI itself registers a preprocessor to update the current research ETA, since it needs to be done on a per-force basis, instead of a per-player basis. These functions are not provided with any parameters.
• Sensors return the actual strings that are displayed in the GUI, and are called for each player individually. Sensors are provided with a player parameter, specifying the LuaPlayer whose GUI is being updated. If a sensor returns nil instead of a string, the GUI will adjust to remove that sensor (e.g. the research complete ETA).

Here is a sample mod demonstrating basic use of the interface by adding a global pollution sensor:

local function sensor(player)
  return {
    "",
    "Global pollution = ",
    math.ceil(player.surface.get_total_pollution()),
    " PU"
  }
end

local function register_sensor()
  -- always call the `version` function first to avoid crashes if the interface changes in the future
  if script.active_mods["StatsGui"] and remote.call("StatsGui", "version") == 1 then
    remote.call("StatsGui", "add_sensor", "MyMod", "pollution_sensor")
  end
end

script.on_init(function()
  register_sensor()
end)

script.on_load(function()
  register_sensor()
end)

remote.add_interface("MyMod", {
  pollution_sensor = sensor
})

Functions

add_preprocessor

remote.call("StatsGui", "add_preprocessor", interface_name, function_name)

Register a preprocessor. Preprocessors fire once, and only once, every time the Stats GUI updates.

Parameters

• interface_name :: string: The name of the interface to call.
• function_name :: string: The name of the sensor function to call.

add_sensor

remote.call("StatsGui", "add_sensor", interface_name, function_name)

Register a sensor. Sensors fire for each player every time the Stats GUI updates.

Parameters

• interface_name :: string: The name of the interface to call.
• function_name :: string: The name of the sensor function to call.

version

remote.call("StatsGui", "version")

Returns the current interface version. This number will increase if a backwards-incompatible change is made to the interface. Recommended usage is to check against this version number and disable compatibility if the version is higher than what you support, to avoid errors.

Returns

• version :: int: The current interface version.