API Add on trips

🇩🇪 Deutsche Version · ⬅ For mod authors

Add-ons: trips

Note

New in 0.0.16.

An add-on can send trains off itself (jobs), start normal UTL deliveries, insert stops into running deliveries and have a say in choosing the train. The planning happens in the add-on – UTL writes the stops into the schedule and reports what happens.

Jobs

A job has nothing to do with goods: it is a list of stops with any wait conditions – to the siding, to the workshop, to the rebuild station, a round trip …

Function	Effect
send_job(train_id, mod, stops)	Send a train over own stops. Returns the job id or nil and a reason: "unknown-train", "bad-mod", "busy" (has a delivery or a job), "held-by-other", "no-stops", "bad-target" or "station-full" (each plus the number of the stop), "no-schedule".
cancel_job(id)	Cancel a job; its stops disappear, the train carries on with its schedule. Returns true if it existed.
get_job(id)	{ id, mod, train_id, stops (count), started (tick) } or nil

Each entry in stops is one of these, each with wait = wait conditions (as in LuaSchedule; without wait the train passes through):

Target	Meaning
{ station = unit }	a UTL station
{ stop = train_stop }	any train stop (LuaEntity or its unit_number) – also one without UTL
{ rail = rail, rail_direction = … }	a piece of rail (default direction defines.rail_direction.front)

Train limit: if a target train stop is full (the stop's train limit or "max trains" of the UTL station), send_job rejects with "station-full" and the number of the stop – just as UTL checks for deliveries. ignore_limit = true on a stop skips this. UTL drives to train stops via a waypoint in front of them and reserves the trip, so other trains count the stop as taken. If the train limit is set only after the train is on its way, it drives up to the stop and waits there – the add-on handles that itself (e.g. with cancel_job).

local job = remote.call("utl", "send_job", train_id, "my-mod", {
  { station = siding, wait = { { type = "time", ticks = 600 } } },
  { stop = workshop, wait = { { type = "inactivity", ticks = 300 } } },
})

What happens:

1. UTL removes old temporary UTL stops (e.g. the waypoint into the depot), writes the job's stops after the current stop and sends the train off (manual mode is switched off).
2. During the job the train is held: no dispatcher, no chained delivery, no refuelling, no cancelling (holding trains).
3. At UTL stations on_train_arrived/on_train_departed come with job_id.
4. When all stops are passed, on_job_finished comes; the train is free again and carries on with its own schedule, usually back to the depot.

If the train is rebuilt without the add-on announcing it, the job ends with reason = "rebuilt"; if the train disappears, with "train-lost".

Starting deliveries

Function	Effect
create_delivery{ provider, requester, type, name, quality, amount, train }	create a normal UTL delivery – with reservations, loading filters, statistics and events like any other.

• provider, requester = stations (unit); both need a train stop with rail.
• type = "item" (default) or "fluid", quality default "normal", amount = amount.
• train = train id of a free UTL train; without train UTL takes the nearest free train that fits (network, length, cargo space, fuel).
• More than the train holds is not loaded.
• Returns the delivery id or nil and a reason: "bad-spec", "bad-station", "not-enough" (the provider does not have that much free), "no-train", "unreachable", "schedule".

Inserting stops into deliveries

Function	Effect
add_delivery_stop(delivery_id, spec)	Insert a stop into a running delivery. Returns true or false and a reason ("unknown-delivery", "bad-position", "bad-target", "no-schedule", "stop-not-found").

spec = target as for jobs (station, stop or rail), wait = wait conditions and where:

where	allowed while the delivery …
"before_provider"	is still on its way to the provider
"after_provider" (default)	is on its way to the provider or loading there
"after_requester"	is not finished yet

Inserted stops do not count for the course of the delivery and disappear with it if it is cancelled. get_delivery shows their number in extra_stops.

Train filter

Function	Effect
register_train_filter{ mod, interface, filter }	have a say in choosing the train (register in on_init and on_configuration_changed)

Only when the provider or requester of a trip has an add-on role, UTL calls it – once per dispatch with all candidates, best first, also for the chained delivery right after a delivery:

remote.add_interface("my-mod", {
  filter = function(train_ids, info)
    -- info = { provider, requester, key, provider_role, requester_role }
    local allowed = {}
    for _, id in ipairs(train_ids) do
      if fits(id, info) then allowed[#allowed + 1] = id end
    end
    return allowed   -- empty list = none; nil = all as before
  end,
})
remote.call("utl", "register_train_filter", { mod = "my-mod", interface = "my-mod", filter = "filter" })

The order of the result is the preferred order. If the filter rejects all, UTL tries again on the next run – so keep the filter fast (Performance).