Differences

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

--- dev:proposals:new-ks [2022-02-10 16:54]
ywang [Example] formatting
+++ dev:proposals:new-ks [2023-03-26 10:10] (current)
ywang
@@ Line 1: / Line 1: @@
-====== Proposal: Distant signaling ======
+====== Implementation: new-ks branch ======
-//This is currently a draft. Feel free to discuss the implementation here.//
+//Please refer to the source code for implementation details and API documentation. This information is provided here. The filenames provided below are relative to ''[[http://git.bananach.space/advtrains.git/tree/advtrains_interlocking?h=new-ks|/advtrains_interlocking]]''.//
+  * The distant signaling API is implemented in ''[[http://git.bananach.space/advtrains.git/tree/advtrains_interlocking/distant.lua?h=new-ks|distant.lua]]''
+  * Formspecs have been partially modified to support distant signaling. Some formspecs are now implemented in various ''*_ui.lua'' files.
+  * Signal aspect accessors have been modified and are now found in ''[[http://git.bananach.space/advtrains.git/tree/advtrains_interlocking/signal_aspect_accessors.lua?h=new-ks|signal_aspect_accessors.lua]]''
+  * A signal aspect API is introduced. This allows manipulating signal aspect objects (implemented using tables) and creating signal aspect groups, the latter of which makes it possible to create route signals. The relevant code can be found in ''[[http://git.bananach.space/advtrains.git/tree/advtrains_interlocking/aspect.lua?h=new-ks|aspect.lua]]''
+  * A ''[[http://git.bananach.space/advtrains.git/tree/advtrains_interlocking/README.md?h=new-ks|README.md]]'' file is added that gives some information on working with the new signaling system.
+**The changes break a few minor things:**
+  * The signal aspect formspec uses dropdown indexing, which requires Minetest 5.4.0 or later.
+  * ''advtrains.interlocking.signal_get_aspect'' and ''advtrains.interlocking.signal_set_aspect'' are changed:
+    * The results are cached.
+    * The signal aspect is "adjusted" before being passed to the signal, i.e., the signal aspect passed to the signal is not guaranteed to be the same as the one passed to ''advtrains.interlocking.signal_set_aspect''.
+    * ''advtrains.interlocking.signal_get_real_aspect'' gets the aspect of the signal directly from the node definitions. Note that, especially for Ks signals, the result is not guaranteed to be constant.
+    * There is no API for setting the signal aspect while bypassing the cache and signal aspect adjustments, as the latter is necessary for distant signaling. **Do not call the ''advtrains.set_aspect'' function in the node definitions directly as doing so is not guaranteed to give the expected result.**
+    * ''advtrains.interlocking.signal_get_aspect'' returns signal aspect objects instead of plain tables.
+  * When setting a field of the signal aspect object to ''nil'' while an aspect is named, the default value for the named aspect is used instead of ''false''. In particular, this may break certain shunt setups.
+  * Certain features of signal aspect objects are implemented using metatables. These objects are therefore not suitable for serialization, and it is not recommended to use ''next''-related functions (e.g. ''pairs'') on these objects. If you want to get a plain table, call the ''plain'' method of these objects.
+It is planned to merge the newly introduced signal aspect cache with its counterpart in the routesetting system.
+Please refer to the source code (listed above) for details.
+====== Proposal: Distant signaling (second draft) ======
+//This draft has been superseded. Please refer to the actual implementation (mentioned above).//
+//This draft is mainly written to address the issues that appeared in the first draft. In particular, it addresses a request to implement route signaling.//
+===== Distant signal assignment =====
+==== Manual signal assignment ====
+Distant signals may be assigned to any signal. These distant signals are automatically set with the signals they are assigned to.
+==== Automatic signal assignment ====
+With automatic distant signal assignment, the user needs to assign distant signals to TCBs. A TCB may have multiple distant signals assigned to it. For combined main/distant signals, however, the main and distant aspects may not be assigned separately.
+These distant signals are then assigned to main signals when needed and unassigned when the aspect of the distant signal become irrelevant to rail operation. Specifically:
+  * When a route is set, the distant signals along the route are assigned to the upcoming signal (i.e. the signal first signal a train should encounter after passing the TCB). These distant signals are then set correspondingly.
+  * When a train leaves a TCB, the distant signal, if assigned to another signal, is unassigned. This should, at least theoretically, be safe as no other train is, at the moment, allowed to pass the TCB that the distant signal is assigned to.
+===== Setting distant signals =====
+  * When a signal aspect is set, the distant signals are set correspondingly.
+  * When a distant signal is unassigned, its distant aspect is set to ''nil''.
+===== API Changes =====
+The functions are given as indices of the ''advtrains.interlocking'' table.
+==== Signal aspect table ====
+  * The ''name'' field includes the name of the main aspect, if the alternative signal aspect table is used.
+  * The ''dst'' field includes the distant aspect. This is mentioned in the current source code, but not used at the moment and may need further discussion.
+  * The ''dst_name'' field includes the name of the distant aspect, if the alternative signal aspect table is used,
+  * The ''dst_repeater'' field is set if the signal is a distant signal repeater.
+  * The ''dst_shortened_distance'' field may, in the future, be used to indicate that the distance to the oncoming signal is shortened.
+==== Distant signal assignment ====
+  * ''assign_distant(pos, dst)'' - Assign ''dst'' to the signal at ''pos''
+  * ''unassign_distant(dst)'' - Unassign the distant signal ''dst''
+  * ''distant_of(pos)'' - Get the distant signals assigned to ''pos''
+  * ''get_assignment(pos)'' - Get the signal that ''pos'' is a distant signal of
+==== Setting signal aspect ====
+  * ''set_distant(pos, dst)'' - Set the distant aspect of ''pos'' to ''dst''
+  * ''set_main(pos, main)'' - Set the main aspect of ''pos'' to ''dst''
+==== Alternative signal aspect table ====
+The alternative signal aspect table is mainly intended for route signaling.
+=== Supported aspects ===
+The table of supported aspects should include the following fields:
+  * ''name'': A name identifying the signal aspect table. Note that this is //not// shown to the user
+  * ''label'': The name of the signal aspect to show to the user (e.g. in a UI). The use of ''attrans'' is recommended here.
+  * ''main'': A list of supported main aspects. An error is signaled if this list has less than two entries.
+  * ''dst'': A translation table where each key is the ''name'' field of the aspect and the value is a name that is passed to the set_aspect field of the distant signal.
+  * ''alt_translation'': A translation table where the key is the name of the table of supported aspects and the value is a table with key-value pairs of the original aspect name and the translated aspect name (as in the ''main'' field of the aspect)
+When registering, the signal should provide the following fields:
+  * ''aspects'': The name of the table of supported aspects (see above).
+  * ''is_dst'': A boolean indicating whether the current signal is a distant signal.
+Each main aspect entry should contain the following fields:
+  * ''name'': The internal name of the particular aspect.
+  * ''main'': The maximum allows speed. This is ''-1'' in a lot of cases.
+The last entry in the list of supported aspects should have the ''main'' field set to 0 (i.e. stop). The //n//th entry in the list (which is not the first or last entry) indicates that the next signal has the same aspect defined by the //n+1//th entry in the list. The first entry in the list indicates that the next signal has the same aspect of the first //or// the second entry in the list.
+=== Signal aspect translation ===
+  * When a distant signal defined with the alternative signal aspect definition table is assigned to a signal that is not defined with the same signal aspect table, the distant signal is always given the //n-1//th entry (with //n// being the number of defined main aspects of the distant signal) unless the main aspect of the upcoming signal is -1, in which case the distant signal is given the first entry of the defined main aspects of the distant signal, or an entry in the translation table can be used to determine the distant signal aspect.
+  * When a distant signal defined with the current signal aspect definition table is assigned to a signal defined with the alternative current signal aspect definition table, the ''main'' field of the signal aspect is passed to the distant signal.
+====== Proposal: Distant signaling (first draft) ======
+//This draft has been superseded.//
 In this proposal, error situations do not need to be detected unless it is explicitly stated that the error is signaled.

Advanced Trains

User Tools

Site Tools

Differences

Page Tools