User Tools

Site Tools


dev:core:path

Differences

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:​
 +<​code>​
 +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.
 +</​code>​
 +
 +''​new_lzb''​ adds another callback for invalidate_ahead:​
 +
 +<​code>​
 +advtrains.te_register_on_invalidate_ahead(func(id,​ train, start_idx))
 +</​code>​
 +
 +==== Node Callbacks ====
 +
 +The node callbacks are driven by a special Path Callback defined in trainlogic.lua:​
 +<​code>​
 +-- 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))
 +</​code>​
 +
  
dev/core/path.txt · Last modified: 2020/06/24 12:49 by orwell