User Tools

Site Tools



This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revision Previous revision
dev:core:path [2020-06-24 12:26]
orwell more documentation, note on invalidate_ahead
dev:core:path [2020-06-24 12:49] (current)
orwell add callbacks
Line 92: Line 92:
 In the future, path_invalidate_ahead() is to be preferred over path_invalidate(). In the future, path_invalidate_ahead() is to be preferred over path_invalidate().
 +===== Callbacks =====
 +A callback system exists to react to path-related events. Most internal components (e.g. LZB) use these to hook into the path system.
 +==== Path callbacks ====
 +There's a relevant comment in occupation.lua:
 +Callback system for 3rd-party path checkers:
 +advtrains.te_register_on_new_path(func(id, train))
 +-- Called when a train's path is re-initalized, either when it was invalidated
 +-- or the saves were just loaded
 +-- It can be assumed that everything is in the state of when the last run
 +-- of on_update was made, but all indices are shifted by an unknown amount.
 +advtrains.te_register_on_update(func(id, train))
 +-- Called each step and after a train moved, its length changed or some other event occured
 +-- The path is unmodified, and train.index and train.end_index can be reliably
 +-- queried for the new position and length of the train.
 +-- note that this function might be called multiple times per step, and this 
 +-- function being called does not necessarily mean that something has changed.
 +-- It is ensured that on_new_path callbacks are executed prior to these callbacks whenever
 +-- an invalidation or a reload occured.
 +advtrains.te_register_on_create(func(id, train))
 +-- Called right after a train is created, right after the initial new_path callback
 +advtrains.te_register_on_remove(func(id, train))
 +-- Called right before a train is deleted
 +All callbacks are allowed to save certain values inside the train table, but they must ensure that
 +those are reinitialized in the on_new_path callback. The on_new_path callback must explicitly
 +set ALL OF those values to nil or to a new updated value, and must not rely on their existence.
 +''new_lzb'' adds another callback for invalidate_ahead:
 +advtrains.te_register_on_invalidate_ahead(func(id, train, start_idx))
 +==== Node Callbacks ====
 +The node callbacks are driven by a special Path Callback defined in trainlogic.lua:
 +-- enter/leave-node callbacks
 +-- signature is advtrains.tnc_register_on_enter/leave(function(pos, id, train, index) ... end)
 +advtrains.tnc_register_on_enter(func(pos, id, train, index))
 +advtrains.tnc_register_on_leave(func(pos, id, train, index))
 +-- Node callback for approaching
 +-- Might be called multiple times, whenever path is recalculated. Also called for the first node the train is standing on, then has_entered is true.
 +-- signature is function(pos, id, train, index, has_entered, lzbdata)
 +-- has_entered: true if the "enter" callback has already been executed for this train in this location
 +-- lzbdata: arbitrary data (shared between all callbacks), deleted when LZB is restarted.
 +-- These callbacks are called in order of distance as train progresses along tracks, so lzbdata can be used to
 +-- keep track of a train's state once it passes this point
 +advtrains.tnc_register_on_approach(func(pos, id, train, index, has_entered, lzbdata))
dev/core/path.txt · Last modified: 2020-06-24 12:49 by orwell