Differences

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

--- dev:proposals:new-ks [2022-07-03 10:38]
ywang
+++ dev:proposals:new-ks [2023-03-26 12:10] (current)
ywang
@@ Line 1: / Line 1: @@
-====== Proposal: Distant signaling (new-ks implementation) ======
+====== Implementation: new-ks branch ======
-//This draft documents the actual implementation.//
+//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]]''.//
-===== Distant signal API =====
+  * The distant signaling API is implemented in ''[[http://git.bananach.space/advtrains.git/tree/advtrains_interlocking/distant.lua?h=new-ks|distant.lua]]''
-The distant signal API is available as ''advtrains.distant'' and implemented by ''advtrains_interlocking/distant.lua''. The API is not documented at the moment as it is not considered stable.
+  * 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.
-Internally, the method of assignment (i.e. whether the signal is assigned manually or by the routesetting system) is irrelevant to the API. However, this information is kept.
+**The changes break a few minor things:**
-Distant signals are automatically updated when (un)assigned.
+  * 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.
-===== Signal assignment =====
+It is planned to merge the newly introduced signal aspect cache with its counterpart in the routesetting system.
-The signal formapecs have been slightly reworked to allow manually assigning distant signals.
-Automatic signal assignment is partially implemented. Distant signals are assigned when the route is set. However, automatically unassigning signals is not yet implemented.
-===== Signal aspect accessors =====
-  * The signal aspect accessors (''advtrains.interlocking.signal_set_aspect'' and ''advtrains.interlocking.signal_get_aspect'') have been modified to cache signal aspects. The ''advtrains.interlocking.signal_get_real_aspect'' function is added to access the signal aspect directly.
-  * ''advtrains.interlocking.signal_set_aspect'' has been modified to
-    * Update the distant signals
-    * Adjust the signal aspect based on the signal type and the distant signal assignment.
-  * The ''advtrains.interlocking.signal_readjust_aspect'' function is added to readjust the aspect of the signal.
-===== Route signaling =====
-Route signals share a similar aspect table as traditional speed signals, with two additional fields:
-  * ''type2group'': the type of route signal
-  * ''type2name'': the name of the signal aspect
-Conversion between speed signal aspect tables and route signal aspect tables is possible, although currently with a few minor issues.
-The corresponding API is implemented in ''advtrains_interlocking/signal_aspects.lua'' and available as ''advtrains.interlocking.aspects''.
+Please refer to the source code (listed above) for details.
 ====== Proposal: Distant signaling (second draft) ======
-//There is currently some work on implementing distant signaling. Differences between the proposal and the implementation will be addressed in a later draft, along with other issues not mentioned here.//
+//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.//

Advanced Trains

User Tools

Site Tools

Differences

Page Tools