diff options
Diffstat (limited to 'advtrains_interlocking/README.md')
| -rw-r--r-- | advtrains_interlocking/README.md | 96 |
1 files changed, 96 insertions, 0 deletions
diff --git a/advtrains_interlocking/README.md b/advtrains_interlocking/README.md new file mode 100644 index 0000000..636ad67 --- /dev/null +++ b/advtrains_interlocking/README.md @@ -0,0 +1,96 @@ +# Interlocking for Advtrains + +The `advtrains_interlocking` mod provides various interlocking and signaling features for Advtrains. + +## Signal types +There are two types of signals in Advtrains: + +* Type 1 (speed signals): These signals only give speed information. +* Type 2 (route signals): These signals mainly provide route information, but sometimes also provide speed information. + +## Signal aspect tables + +Signal aspects are represented using tables with the following (optional) fields: + +* `main`: The main signal aspect. It provides information on the permitted speed after passing the signal. +* `dst`: The distant signal aspect. It provides information on the permitted speed after passing the next signal. +* `shunt`: Whether the train may proceed in shunt mode and, if the main aspect is danger, proceed in shunt mode. +* `proceed_as_main`: Whether the train should exit shunt mode when proceeding. +* `type2group`: The type 2 group of the signal. +* `type2name`: The type 2 signal aspect name. + +The `main` and `dst` fields may be: + +* An positive number indicating the permitted speed, +* The number 0, indicating that the train should expect to stop at the current signal (or, for the `dst` field, the next signal), +* The number -1, indicating that the train can proceed (or, for the `dst` field, expect to proceed) at maximum speed, or +* The constant `false` or `nil`, indicating no change to the speed restriction. + +### Node definitions + +Signals should belong the following node groups: + +* `advtrains_signal`: `1` for static signals, `2` for signals with variable aspects. +* `save_in_at_nodedb`: This should be set to `1` to make sure that Advtrains always has access to the signal. +* `not_blocking_trains`: Setting this to `1` prevents trains from colliding with the signal. Setting this is not necessary, but recommended. + +The node definition should contain an `advtrains` field. + +The `advtrains` field of the node definition should contain a `supported_aspects` table for signals with variable aspects. + +For type 1 signals, the `supported_aspects` table should contain the following fields: + +* `main`: A list of values supported for the main aspect. +* `dst`: A list of values supported for the distant aspect. +* `shunt`: The value for the `shunt` field of the signal aspect or `nil` if the value is variable. +* `proceed_as_main`: The value for the `proceed_as_main` field of the signal aspect. + +For type 2 signals, the `supported_aspects` table should contain the following fields: + +* `type`: The numeric constant `2`. +* `group`: The type 2 signal group. +* `dst_shift`: The phase shift for distant/repeater signals. This field should not be set for main signals. + +The `advtrains` field of the node definition should contain a `get_aspect` function. This function is given the position of the signal and the node at the position. It should return the signal aspect table or, in the case of type 2 signals, the name of the signal aspect. + +For signals with variable aspects, a corresponding `set_aspect` function should also be defined. This function is given the position of the signal, the node at the position, and the new aspect (or, in the case of type 2 signals, the name of the new signal aspect). For type 1 signals, the new aspect is not guranteed to be supported by the signal itself. + +Signals should also have the following callbacks set: + +* `on_rightclick` should be set to `advtrains.interlocking.signal_rc_handler` +* `can_dig` should be set to `advtrains.interlocking.signal_can_dig` +* `after_dig_node` should be set to `advtrains.interlocking.signal_after_dig` + +Alternatively, custom callbacks should call the respective functions. + +## Type 2 signal groups + +Type 2 signals belong to signal gruops, which are registered using `advtrains.interlocking.aspects.register_type2`. + +Signal group definitions include the following fields: + +* `name`: The internal name of the signal group. It is recommended to use the mod name as a prefix to avoid name collisions. +* `label`: The description of the signal group. +* `main`: A list of signal aspects, from the least restrictive (i.e. proceed) to the most restrictive (i.e. danger). + +Each aspect in the signal group definition table should contain the following fields: + +* `name`: The internal name of the signal aspect. +* `label`: The description of the signal aspect. +* `main`, `shunt`, `proceed_as_main`: The fields corresponding to the ones in signal aspect tables. + +Type 2 signal aspects are then referred to with the aspect names within the group. + +## Notes + +It is allowed to provide other methods of setting the signal aspect. However: + +* These changes are ignored by the routesetting system. +* Please call `advtrains.interlocking.signal_readjust_aspect` after the signal aspect has changed. + +## Examples +An example of type 1 signals can be found in `advtrains_signals_ks`, which provides a subset of German signals. + +An example of type 2 signals can be found in `advtrains_signals_japan`, which provides a subset of Japanese signals. + +The mods mentioned above are also used for demonstation purposes and can also be used for testing. |