API Add on Züge umbauen

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

Add-ons: Züge umbauen und festhalten

Note

Neu in 0.0.20. train_transfer_started/train_transfer_finished gibt es seit 0.0.10.

Züge umbauen

Kuppelt man Wagen an oder ab, macht Factorio daraus neue Züge mit neuen IDs. Ohne Meldung bricht UTL die Lieferung des alten Zugs dann ab („rebuilt“). Meldet das Add-on den Umbau, zieht alles auf den neuen Zug um. UTL kuppelt dabei selbst nie – das tut das Add-on.

Funktion	Wirkung
begin_train_change(ids)	Umbau beginnt: Zug-ID oder Liste der IDs, die gleich verschwinden. Ruft man vor dem Kuppeln auf. Bis zum Ende bricht UTL deren Lieferungen nicht ab; der eigene Fahrplan wird gesichert.
end_train_change(old_ids, train)	Umbau fertig: Lieferung, Depot-Eintrag, Festhalten und Auftrag der alten IDs ziehen auf train (LuaTrain) um. Liefert true bei Erfolg.
forget_train(train_id)	Zug (alte oder neue ID) für UTL vergessen, z. B. den abgekuppelten Teil, der stehen bleiben soll. Eine Lieferung daran wird abgebrochen.
train_transfer_started(old_id) / train_transfer_finished(old_id, train)	ältere Form mit genau einer ID (z. B. für Mods, die Züge versetzen); den Weltraumaufzug von Space Exploration erkennt UTL selbst

Was end_train_change außerdem tut:

• Fahrplan: Fehlen danach die Halte der Lieferung, setzt UTL sie neu. Zeigt der Fahrplan auf keinen Halt mehr, schickt UTL den Zug zum nächsten Halt der Lieferung. Steht der Zug ganz ohne Fahrplan da, bekommt er den beim begin_train_change gesicherten zurück.
• Mehrere alte Züge mit Lieferung (zwei beladene Züge werden gekuppelt): train behält die erste, die anderen werden abgebrochen.
• Im Depot umgebaut: Der Zug wird neu eingeparkt und sein Laderaum neu gemessen.
• Danach kommt on_train_rebuilt mit changing = true.

-- Wagen abkuppeln, ohne die Lieferung zu verlieren
local old_id = train.id
local front, last = train.front_stock, train.back_stock
remote.call("utl", "begin_train_change", { old_id })
front.disconnect_rolling_stock(defines.rail_direction.back)
remote.call("utl", "end_train_change", { old_id }, front.train)   -- dieser Teil fährt weiter
remote.call("utl", "forget_train", last.train.id)                 -- der Rest bleibt stehen

Wird end_train_change nie aufgerufen, vergisst UTL die Meldung nach 10 Minuten.

Züge festhalten

Funktion	Wirkung
hold_train(train_id, mod)	Zug festhalten: kein Dispatcher, keine Anschlussfahrt, kein Tanken, kein Aufräumen, kein Abbruch – auch nicht im Handbetrieb, keine Warnung „steckt fest“. Eine laufende Lieferung bleibt bestehen. Liefert false, wenn ein anderer Mod ihn schon hält oder er frei im Depot eines anderen Add-ons steht.
release_train(train_id)	wieder freigeben. Steht er ohne Lieferung in einem Depot, ist er sofort wieder frei; sonst fährt er nach seinem Fahrplan weiter.
is_held(train_id)	Name des Mods, der ihn hält, oder nil (auch in get_train als held_by)
remeasure_train(train_id)	Laderaum eines freien Zugs neu messen, wenn das Add-on ihn im Depot umgebaut hat, ohne dass sich die Zug-ID geändert hat. Liefert true, wenn UTL den Zug als frei kennt.

Typischer Ablauf beim Rangieren mitten in einer Lieferung:

1. hold_train – UTL lässt den Zug in Ruhe.
2. Zug auf Handbetrieb, rangieren, mit begin_train_change/end_train_change kuppeln.
3. Zug auf Automatik, release_train – die Lieferung geht weiter.

Ein Auftrag hält den Zug von selbst fest, solange er läuft.