API Add on Rollen und Daten

🇬🇧 English version · ⬅ Für Mod-Autoren

Add-ons: Rollen und Daten

Note

Neu in 0.0.20.

Ein Add-on ist eine Mod, die auf UTL aufbaut: eigene Bahnhofsrollen, eigene Fahrten, eigene Teile im Fenster. Beispiele: Rangieren und Kuppeln (Wagen bleiben in Ladebuchten, Rangierloks holen sie), Abstellgleise und Werkstätten, Zug-Bau-Mods, Statistik-Mods.

Die Aufteilung ist immer gleich: Das Add-on plant und rechnet, UTL führt Fahrpläne aus und meldet, was passiert. UTL kuppelt selbst nie und verwaltet keine Wagen.

Anmelden

Rollen, Fenster-Abschnitte, Manager-Reiter und Zugfilter meldet das Add-on in on_init und on_configuration_changed an. Sie liegen in UTLs storage; erneutes Anmelden überschreibt den alten Eintrag. mod ist immer der Name der eigenen Mod (wie in info.json) – UTL prüft, dass es sie gibt.

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

Wird das Add-on entfernt, räumt UTL auf: Stationen mit seiner Rolle werden zu Stationen ohne Aufgabe, seine Aufträge enden, festgehaltene Züge werden frei. Die Daten an den Stationen bleiben, falls es zurückkommt.

Fehler im Add-on: Rückrufe ruft UTL per remote.call auf und fängt Fehler ab. Ein Fehler steht einmal im Log (factorio-current.log), UTL macht ohne den Rückruf weiter.

Eigene Rollen

Funktion	Wirkung
register_role{ mod, name, caption, tooltip, base, own_trains }	Rolle anmelden. Schlüssel der Rolle: "mod/name". Liefert true oder false und einen Grund ("bad-spec", "unknown-mod", "bad-base").
set_station_role(unit, key)	Station auf die Rolle "mod/name" setzen; nil = zurück auf „ohne Aufgabe“. Liefert true oder false.

Die Rolle erscheint im Stationsfenster als eigenes Häkchen unter den UTL-Rollen. caption und tooltip dürfen LocalisedStrings sein und Rich-Text enthalten, z. B. "[virtual-signal=meine-mod-abstellgleis] Abstellgleis" – so passt ein eigenes Symbol zum Signal-Stil. Wählt der Spieler eine UTL-Rolle, fällt die Add-on-Rolle weg und umgekehrt.

base bestimmt, wie sich die Station für UTLs Dispatcher verhält:

base	Verhalten
nil	Eigene Rolle: UTL vermittelt hier nichts, meldet nur Ankunft und Abfahrt. Für Abstellgleise, Werkstätten …
"provider", "requester", "provider_requester"	wie Anbieter, Abnehmer oder beides – mit allen Werten und Abschnitten
"depot", "fuel", "cleanup", "storage"	wie Depot, Tankstelle, Cleanup oder Lager

Eigenes Depot

own_trains = true (nur mit base = "depot"): Züge in diesem Depot gehören dem Add-on. UTLs Dispatcher nimmt sie nie, UTL schickt sie auch nicht zum Tanken oder Aufräumen. Das Add-on findet freie Züge mit get_idle_trains{ role = "mod/name" } und über das Ereignis on_train_idle (Feld role) und schickt sie mit send_job los.

Stationen einer Rolle finden

• get_stations{ addon_role = "mod/name" } listet alle Stationen mit dieser Rolle.
• Jede Station hat in get_stations und in get_station(unit).config das Feld addon_role.
• copy_settings und Umschalt-Klick übernehmen die Rolle mit.
• In Blaupausen reist die Rolle mit. Fehlt das Add-on im anderen Spielstand, wird daraus eine Station ohne Aufgabe. Über Blaupausen-Parameter wird eine Add-on-Rolle nicht abgefragt.

Daten je Station

Funktion	Wirkung
set_station_data(unit, mod, key, value)	eigenen Wert an einer Station speichern; value = Zahl, Text, Wahrheitswert oder Tabelle daraus, nil löscht. Liefert true oder false.
get_station_data(unit, mod)	alle Werte des Mods an dieser Station (Kopie) oder nil

Die Daten reisen in Blaupausen und beim Einstellungen-Kopieren (Umschalt-Klick, copy_settings) mit. Sie stehen auch in get_station(unit).config.ext[mod].

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

Signale für Netz-Kombinatoren

Funktion	Wirkung
set_network_signals(surface_index, force, netz, mod, signale)	zusätzliche Signale für alle Netz-Kombinatoren eines Netzes; signale = Liste { signal = SignalID, count = Zahl }, nil löscht. Liefert true oder false.
get_network_signals(surface_index, force, netz)	alle zusätzlichen Signale eines Netzes je Mod (Kopie) oder nil

Jeder Netz-Kombinator des Netzes – mit „verbundene Netze“ auch die des Sterns – gibt die Signale in jedem Modus zusätzlich aus. Signale mehrerer Add-ons addieren sich. UTL gibt nur fest eingetragene Werte aus; das Add-on setzt sie neu, wenn sich bei ihm etwas ändert (nicht in jedem Tick).

-- Züge in der Werkstatt als Signal „Reparaturpaket“ im Netz „Erz“
remote.call("utl", "set_network_signals", surface.index, "player", "Erz", "meine-mod",
  { { signal = { type = "item", name = "repair-pack" }, count = 3 } })