Differences

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

--- dev:core:path [2020-06-24 10:26]
orwell more documentation, note on invalidate_ahead
+++ dev:core:path [2023-01-11 14:13] (current)
56independent [Path generation] Add newline for clearer text
@@ Line 57: / Line 57: @@
 The path is generated on the fly, as path items are requested.
-Every call to ''advtrains.path_get()'' (or one of the related functions) automatically generates the path as far as needed. In order to access any of the secondary path tables (such as path_speed or path_cn), you need to make sure that ''advtrains.path_get()'' was called before. However, advtrains ensures that the range from ''train.index'' to ''train.end_index'' is always existent.
+Every call to ''advtrains.path_get()'' (or one of the related functions) automatically generates the path as far as needed.
+In order to access any of the secondary path tables (such as path_speed or path_cn), you need to make sure that ''advtrains.path_get()'' was called before. However, advtrains ensures that the range from ''train.index'' to ''train.end_index'' is always existent.
 The path system deletes path items that are behind the train and no longer needed automatically.
@@ Line 92: / Line 94: @@
 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>

Advanced Trains

User Tools

Site Tools

Differences

Page Tools