The Path is a mapping of whole (positive or negative) numbers to a world position, describing a continuous section of track.

Every path node corresponds to a piece of track in the world. The path is a property of every ''train'' Table and is used in various ways:

1. The wagons of a train use the path and their position in the train to determine their absolute position, rotation and movement direction in the world
2. The train-to-train collision system relies on nodes in the path being occupied or free. This includes coupling.
3. Nodes in the path are used as base positions for checking collisions with the environment and player damage (a cube centered around the nearest path node is scanned)
4. Node callbacks are run per path node

The index is a positive, fractional number that describes a certain position in a path.

index =  5   -> The position described is the path item 5
index =  3.5 -> The point halfway between path items 3 and 4
index =  2.75-> The point between path items 2 and 3, 3/4 of the distance towards item 3
index = -4   -> path item -4
index = -3.5 -> the point halfway between path items -4 and -3

A whole index always maps to a path item. In many places where the exact position between items doesn't matter, the index is rounded to map to the nearest path item directly, instead of interpolating between path items.

Every train has an 'index' property which tells the exact index on the train's path where the front of the train is. The 'end_index' is calculated every step and tells the exact index where the back of the train is.

A train is moved by advancing its index. It is important to note that the train's 'index' is always incremented, never decremented. See also “reversion” in ''train'' Table.

It is important to keep in mind that the index has little to no relation to actual distances in the cartesian space. Depending on the track orientation, the distance between path items can vary from 1 to >2 nodes. The real distance of every item from path item 0 is encoded in train.path_dist

To calculate an index for a given starting index and a given distance, you can use advtrains.path_get_index_by_offset()

The following tables in the train table are handled by the path system:

-- path      - path positions. 'indices' are relative to this. At the moment, at.round_vector_floor_y(path[i])
--              is the node this item corresponds to, however, this will change in the future.
-- path_node - (reserved)
-- path_cn   - Connid of the current node that points towards path[i+1]
-- path_cp   - Connid of the current node that points towards path[i-1]
--     When the day comes on that path!=node, these will only be set if this index represents a transition between rail nodes
-- path_dist - The total distance of this path element from path element 0
-- path_dir  - The direction of this path item's transition to the next path item, which is the angle of conns[path_cn[i]].c
--Variables:
-- path_speed   - Filled by the LZB subsystem. For every path item, if set, defines the maximum velocity the train is allowed to have in the moment it passes this path item.
--              - If 0, the train will stop 0.1 indices before this path item (definable by LZB_ZERO_APPROACH_DIST in trainlogic.lua)
-- path_ext_f/b - how far path[i] is set
-- path_trk_f/b - how far the path extends along a track. beyond those values, paths are generated in a straight line.
-- path_req_f/b - how far path items were requested in the last step

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.