API Add on roles and data

🇩🇪 Deutsche Version · ⬅ For mod authors

Add-ons: roles and data

Note

New in 0.0.20.

An add-on is a mod that builds on UTL: own station roles, own trips, own parts in the windows. Examples: shunting and coupling (wagons stay in loading bays, shunting locomotives fetch them), sidings and workshops, train building mods, statistics mods.

The split is always the same: the add-on plans and calculates, UTL runs schedules and reports what happens. UTL never couples anything itself and does not manage wagons.

Registering

The add-on registers roles, window sections, manager tabs and train filters in on_init and on_configuration_changed. They live in UTL's storage; registering again replaces the old entry. mod is always the name of your own mod (as in info.json) – UTL checks that it exists.

local function register()
  remote.call("utl", "register_role", { mod = "my-mod", name = "siding",
    caption = { "my-mod.siding" } })
end
script.on_init(register)
script.on_configuration_changed(register)

When the add-on is removed, UTL cleans up: stations with its role become stations without a task, its jobs end, held trains are released. The data on the stations stays, in case it comes back.

Errors in the add-on: UTL calls callbacks via remote.call and catches errors. An error is written once to the log (factorio-current.log), UTL carries on without that callback.

Own roles

Function	Effect
register_role{ mod, name, caption, tooltip, base, own_trains }	Register a role. Key of the role: "mod/name". Returns true or false and a reason ("bad-spec", "unknown-mod", "bad-base").
set_station_role(unit, key)	Put a station on role "mod/name"; nil = back to "no task". Returns true or false.

The role shows up in the station window as its own checkbox below the UTL roles. caption and tooltip may be LocalisedStrings and contain rich text, e.g. "[virtual-signal=my-mod-siding] Siding" – that way your own icon matches the signal style. If the player picks a UTL role, the add-on role goes away and vice versa.

base decides how the station behaves for UTL's dispatcher:

base	Behaviour
nil	Own role: UTL dispatches nothing here, it only reports arrival and departure. For sidings, workshops …
"provider", "requester", "provider_requester"	like provider, requester or both – with all values and sections
"depot", "fuel", "cleanup", "storage"	like depot, fuel station, cleanup or storage

Own depot

own_trains = true (only with base = "depot"): trains in this depot belong to the add-on. UTL's dispatcher never takes them, and UTL does not send them to refuel or clean up either. The add-on finds free trains with get_idle_trains{ role = "mod/name" } and through the event on_train_idle (field role), and sends them off with send_job.

Finding the stations of a role

• get_stations{ addon_role = "mod/name" } lists all stations with this role.
• Every station has the field addon_role in get_stations and in get_station(unit).config.
• copy_settings and shift-click carry the role over.
• The role travels with blueprints. If the add-on is missing in the other save, the station becomes a station without a task. Blueprint parameters do not ask for an add-on role.

Data per station

Function	Effect
set_station_data(unit, mod, key, value)	store a value on a station; value = number, string, boolean or a table of those, nil deletes. Returns true or false.
get_station_data(unit, mod)	all values of the mod on this station (copy) or nil

The data travels with blueprints and with copying settings (shift-click, copy_settings). It is also in get_station(unit).config.ext[mod].

remote.call("utl", "set_station_data", unit, "my-mod", "tracks", 3)
local data = remote.call("utl", "get_station_data", unit, "my-mod")  -- { tracks = 3 }

Signals for network combinators

Function	Effect
set_network_signals(surface_index, force, network, mod, signals)	extra signals for all network combinators of a network; signals = list { signal = SignalID, count = number }, nil clears. Returns true or false.
get_network_signals(surface_index, force, network)	all extra signals of a network per mod (copy) or nil

Every network combinator of the network – with "linked networks" also those of the star – outputs the signals in every mode on top. Signals of several add-ons add up. UTL only outputs stored values; the add-on sets them again when something changes on its side (not every tick).

-- trains in the workshop as signal "repair pack" in network "Ore"
remote.call("utl", "set_network_signals", surface.index, "player", "Ore", "my-mod",
  { { signal = { type = "item", name = "repair-pack" }, count = 3 } })