Differences

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

--- dev:proposals:distant [2022-11-02 09:28] – Add linnks to individual files; remove link to recent commit as it is not particularly useful ywang
+++ dev:proposals:new-ks [2023-03-26 10:10] (current) – ywang
@@ Line 1: / Line 1: @@
-====== Distant signaling (new-ks implementation) ======
+====== Implementation: new-ks branch ======
 //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]]''.//
@@ Line 5: / Line 5: @@
   * 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]]''
-  * Type 2 signals ("route signals") are introduced. Code related to signal aspect conversion and type 2 signal groups can be found in ''[[http://git.bananach.space/advtrains.git/tree/advtrains_interlocking/signal_aspects.lua?h=new-ks|signal_aspects.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).//