API Events

🇩🇪 Deutsche Version · ⬅ For mod authors

Events

UTL reports what happens as its own events. Get the ids with get_event_ids() and register in on_init and on_load (the ids are created anew on every load, in the same order):

local function listen()
  local ids = remote.call("utl", "get_event_ids")
  script.on_event(ids.on_delivery_completed, function(event)
    game.print("Delivery " .. event.id .. " done: " .. event.from .. " → " .. event.to)
  end)
end
script.on_init(listen)
script.on_load(listen)

Events are always raised at the end of UTL's own processing. They only happen when something really happens (no timer) – more under Performance.

Deliveries

Event	When
on_delivery_created	delivery created, train sent off
on_delivery_state_changed	new state: loading, to_requester, unloading (with a second provider also to_provider again)
on_delivery_completed	unloaded at the requester and departed
on_delivery_canceled	cancelled; field reason: "station-lost", "manual", "rebuilt", "provider-empty", "remote"

The data has the same fields as get_delivery (Queries), plus train (the LuaTrain).

Trains

Note

New in 0.0.20.

Event	When	Fields
on_train_arrived	a train waits at a UTL station	train, train_id, station (unit), stop (train stop), mode, roles, delivery_id, job_id, held_by
on_train_departed	a train leaves a UTL station	as on_train_arrived
on_train_idle	a train stands free in a depot	train, train_id, station, stop, network; in an add-on's depot also role
on_train_rebuilt	a train UTL knew was rebuilt (wagons coupled or uncoupled)	train, train_id, old_train_ids, canceled (ids of cancelled deliveries), changing (true if the rebuild was announced)
on_job_finished	an add-on's job is done or cancelled	job_id, mod, train, train_id, canceled, reason ("remote", "rebuilt", "train-lost", "mod-removed")

Arrival and departure only come at UTL stations, not at other train stops.

Stations, alerts, requests

Note

New in 0.0.20.

Event	When	Fields
on_station_created	a UTL station was built (also from blueprints)	station (unit), kind ("stop" or "combinator"), stop, stop_name, network, mode, roles, addon_role
on_station_changed	a station's settings changed (window, copying, interface)	as on_station_created
on_station_removed	a UTL station was removed	station, kind
on_alert	a UTL alert (no train, stuck, leftover cargo, no path …) – exactly as often as the alert itself	group, icon, entity, message (LocalisedString), key, force (name), surface (index)
on_request_unserved	a requester waits longer than the map setting “No train” alert after (minutes) and no train is free or fits – at most once per minute and request	station, key (good), network, since (tick), reason ("no-free-train" or "no-fitting-train"), provider (unit or nil)

on_request_unserved suits e.g. mods that build or lend a train then.