Differences

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

--- dev:core:path [2020-04-28 20:27]
orwell
+++ dev:core:path [2020-06-24 12:26]
orwell more documentation, note on invalidate_ahead
@@ 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.
+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.
+===== Invalidation and restoration =====
+Whenever the tracks in the world change (e.g. a switch is switched), it is required to update (say 'invalidate') the paths of trains that include the changed track. This happens by a call to ''advtrains.invalidate_all_paths(pos)''.
+//With the ''new_lzb'' branch, it is preferred to use ''advtrains.invalidate_all_paths_ahead(pos)''. See ''invalidate ahead'' below.//
+A path invalidation clears all path-related tables and variables. They remain cleared until the next call to ''train_ensure_init()'', which should be called before operating on a train, but is at least called before the next train step.
+To restore the path from save files or after a path invalidation, the following values are saved in the train (and in the save files) in every step:
+<code>
+train.last_pos -- the world position of the path item currently at floor(train.index)
+train.last_connid = the connid of the track connection pointing forward
+train.last_frac = the fractional part of train.index
+</code>
+To restore, train.last_pos becomes path item 0, train.index becomes last_frac, and path generation continues in last_connid direction. This causes an index shift, which also prevents integer overflows.
+Note that, to have an estimated rough position of a train, you can simply query ''train.last_pos''.
+A path invalidation can also occur when LZB checkpoints change, see [[dev:core:lzb]] for more info on that.
+===== Invalidate Ahead =====
+In order to prevent a complete path recalculation when a far-away rail changes, ''path_invalidate_ahead()'' was added in the ''new_lzb'' branch. This function clears path items that are **ahead of** (exclusive) the passed index, and does not cause an index shift.
+Obviously, due to the way the path restoration works, this would cause problems when the starting index is behind the train's current index. By default, when this case happens, ''path_invalidate_ahead()'' throws an error. However passing the ''ignore_when_passed = true'' parameter causes nothing to happen in this case, which is sometimes desirable and sufficient (e.g. when a switch is switched after the train has already passed it, it doesn't matter).
+''path_invalidate_ahead()'' also invalidates LZB checkpoints and re-calls approach callbacks up from the given index. Important: LZB invalidation occurs **inclusive**, so the first approach callback to be called again is the node at ''index'', although the first path item that was actually cleared was ''index + 1''. This is required for interlocking signals to work.
+In the future, path_invalidate_ahead() is to be preferred over path_invalidate().

Advanced Trains

User Tools

Site Tools

Differences

Page Tools