diff options
| -rw-r--r-- | advtrains_interlocking/signal_api.lua | 53 |
1 files changed, 53 insertions, 0 deletions
diff --git a/advtrains_interlocking/signal_api.lua b/advtrains_interlocking/signal_api.lua index ce8854a..743e8e1 100644 --- a/advtrains_interlocking/signal_api.lua +++ b/advtrains_interlocking/signal_api.lua @@ -19,6 +19,59 @@ advtrains.interlocking.FULL_FREE = { proceed_as_main = true, } +--[[ +Implementation plan orwell 2024-01-28: +Most parts of ywang's implementation are fine, especially I like the formspecs. But I would like to change a few aspects (no pun intended) of this. +- Signal gets distant assigned via field in signal aspect table (instead of explicitly) +- Signal speed/shunt are no longer free-text but rather they need to be predefined in the node definition +To do this: Differentiation between: +== Aspect Group == +This is what a signal is assigned by either the route system or the user. +It is a string key which has an appropriate entry in the node definition (where it has a description assigned) +The signal mod defines a function to set a signal to the most appropriate aspect. This function gets +a) the aspect group name +b) the distant signal's aspect group name & aspect table +EVERY signal must define the special aspect group "halt". This must always be the most restrictive aspect possible. +The "halt" aspect group should ignore any distant info, in most cases it is called without them anyway. + +== Aspect == +One concrete combination of lights/shapes that a signal signal shows. Handling these is at the discretion of +the signal mod defining the signal, and they are typically combinations of main aspect and distant aspect +Example: +- A Ks signal has the aspect_group="proceed_12" set for a route +- The signal at the end of the route shows aspect_group="proceed_8", advtrains also passes on that this means {main=8, shunt=false} +- The ndef.advtrains.apply_aspect(pos, asp_group, dst_aspgrp, dst_aspinfo) determines that the signal should now show + blinking green with main indicator 12 and dst indicator 8, and sets the nodes accordingly. + This function can now return the Aspect Info table, which will be cached by advtrains until the aspect changes again + and will be used when a train approaches the signal. If nil is returned, then the aspect will be queried next time + by calling ndef.advtrains.get_aspect_info(pos) + +Note that once apply_aspect returns, there is no need for advtrains anymore to query the aspect info. +When the signal, for any reason, wants to change its aspect by itself *without* going through the signal API then +it should update the aspect info cache by calling advtrains.interlocking.signal.update_aspect_info(pos) + +== Aspect Info == +The actual signal aspect in the already-known format. This is what the trains use to determine halt/proceed and speed. In this, the dst field has to be resolved. +asp = { + main = 0 (halt) / -1 (max speed) / false (no info) / <number> (speed limit) + shunt = true (shunt free) / false (shunt not free) + proceed_as_main = true (shunt move can proceed and become train move when main!=0) / false (no) + dst = (like main, informative character, not actually used) +} + +Node definition of signals: +- The signal needs some logic to figure out, for each combination of its own aspect group and the distant signal's aspect, what aspect info it can/will show. +ndef.advtrains = { + aspect_groups = { [name] = { description = "Proceed at full speed", <more data at discretion of signal>} } + apply_aspect = function(pos, asp_group, dst_aspgrp, dst_aspinfo) + -- set the node to show the desired aspect + -- called by advtrains when this signal's aspect group or the distant signal's aspect changes + -- MAY return the aspect_info. If it returns nil then get_aspect_info will be queried at a later point. + get_aspect_info(pos) + -- Returns the aspect info table (main, shunt, dst etc.)W +} +]] + advtrains.interlocking.signal_convert_aspect_if_necessary = advtrains.interlocking.aspect function advtrains.interlocking.update_signal_aspect(tcbs, skipdst) |