User Tools

Site Tools


usage:nodes:atc_rail

Differences

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

Link to this comparison view

Both sides previous revision Previous revision
Next revision Both sides next revision
usage:nodes:atc_rail [2019-11-07 09:20]
orwell never do this
usage:nodes:atc_rail [2019-12-18 14:38]
mlaunois completed page, with information on environment available from ATC rail
Line 1: Line 1:
 ====== LuaAutomation ATC rail ====== ====== LuaAutomation ATC rail ======
-{{ http://git.bananach.space/advtrains.git/plain/advtrains_train_track/textures/advtrains_dtrack_atc_placer.png?nolink&50 }} +{{ :usage:nodes:advtrains_dtrack_atc_placer.png?80 |}} 
-//Do anything you want with ATC rails.//+//Do anything you want with these ATC rails.//
  
 ---- ----
Line 7: Line 7:
 ---- ----
  
-//Note: this page has been written for Advtrains 2.0.1 TSS and Minetest 5.1.0. Examples and practices described in this page don't take advantage of improvements introduced in later releases.//+//Note: this page has been written for Advtrains 2.1.0 and Minetest 5.1.0. Examples and practices described in this page don't take advantage of improvements introduced in later releases.//
  
 ===== Properties ===== ===== Properties =====
Line 196: Line 196:
   schedule_in("01;00", "depart")   schedule_in("01;00", "depart")
 </code> </code>
 +
 === Digiline === === Digiline ===
  
Line 258: Line 259:
 } }
 </code> </code>
 +
 +You can check for a specific event type by using
 +<code lua>
 +if event.type == "<wanted>" then
 +    -- ... do stuff
 +end
 +</code>
 +or
 +<code lua>
 +if event.<wanted> == true then
 +    -- ... do stuff
 +end
 +</code>
 +
 +=== int ===
 +<code lua>
 +event = {
 +    type = "int",
 +    int = true,
 +    msg = <message>,
 +    message = <message>, -- For backwards compatibility only!
 +}
 +</code>
 +Fired when an interrupt set by the ''[[#interrupt_time_message|interrupt]]'' function runs out. ''<message>'' is the message passed to the function.  
 +For backwards compatibility reasons, the message is also contained in the ''event.message'' field.
 +
 +=== ext_int ===
 +<code lua>
 +event = {
 +    type = "ext_int",
 +    ext_int = true,
 +    message = <message>,
 +}
 +</code>
 +Fired when a node called ''[[#interrupt_pos_pos_message|interrupt_pos]]'' on this node's position. ''<message>'' is the message passed to the function.
 +
 +=== digiline ===
 +<code lua>
 +event = {
 +    type = "digiline",
 +    digiline = true,
 +    channel = <channel>,
 +    msg = <message>,
 +}
 +</code>
 +Fired when the rail receives a [[usage:mods:digiline|Digiline]] message.
 +
 +==== Specific to the ATC rail ====
 +
 +=== Functions ===
 +== atc_send(cmd) ==
 +Sends the specified [[usage:nodes:atc_controller#atc_command_syntax|ATC command]] to the train and returns ''true''. If there is no train, returns ''false'' and does nothing.
 +
 +== atc_reset(cmd) ==
 +Resets the train's current ATC command and returns ''true''. If there is no train, returns ''false'' and does nothing.
 +
 +''cmd'' is actually ignored by the current version of Advtrains.
 +
 +== atc_set_text_outside(text) ==
 +Sets the text shown on the outside of the train and returns ''true''. If there is no train, returns ''false'' and does nothing.
 +
 +== atc_set_text_inside(text) ==
 +Sets the text shown inside the train and returns ''true''. If there is no train, returns ''false'' and does nothing.
 +
 +== get_line() ==
 +Returns the line property of the train, as a string. This string can be used to distinguish trains of different lines and route them properly.
 +
 +This property is also used by the interlocking system for Automatic Routesetting.
 +
 +If there is no train, the Lua program stored in the rail will exit immediately:
 +
 +> 2019-01-01 15:00:00: WARNING[Server]: [advtrains]LuaAutomation ATC interface rail at (0,0,0) : LUA Error: .../mods/advtrains/advtrains_luaautomation/atc_rail.lua:93: attempt to index upvalue 'train' (a nil value)
 +
 +== set_line(line) ==
 +Sets the line property of the train, as a string. On [[usage:trains:subway_train|subway trains]] bundled with Advtrains, the line is automatically displayed on the outside of the trains, if it is a number between 0 and 9 (where 0 is displayed as "Line 10").
 +
 +This property is also used by the interlocking system for Automatic Routesetting.
 +
 +If there is no train, the Lua program stored in the rail will exit immediately:
 +
 +> 2019-01-01 15:00:00: WARNING[Server]: [advtrains]LuaAutomation ATC interface rail at (0,0,0) : LUA Error: .../mods/advtrains/advtrains_luaautomation/atc_rail.lua:88: attempt to index upvalue 'train' (a nil value)
 +
 +== get_rc() ==
 +Returns the routing code of the train, as a string. This property is used by the interlocking system for Automatic Routesetting.
 +
 +If there is no train, the Lua program stored in the rail will exit immediately:
 +
 +> 2019-01-01 15:00:00: WARNING[Server]: [advtrains]LuaAutomation ATC interface rail at (0,0,0) : LUA Error: .../mods/advtrains/advtrains_luaautomation/atc_rail.lua:104: attempt to index upvalue 'train' (a nil value)
 +
 +== set_rc(rc) ==
 +Sets the routing code of the train, as a string. This property is used by the interlocking system for Automatic Routesetting.
 +
 +If there is no train, the Lua program stored in the rail will exit immediately:
 +
 +> 2019-01-01 15:00:00: WARNING[Server]: [advtrains]LuaAutomation ATC interface rail at (0,0,0) : LUA Error: .../mods/advtrains/advtrains_luaautomation/atc_rail.lua:99: attempt to index upvalue 'train' (a nil value)
 +
 +== set_shunt() ==
 +Enables shunting mode for the currently passing train and returns ''true''. This mode permanently restricts the train speed to 6 m/s (or 21.6 km/h).
 +
 +If there is no train, returns ''false'' and does nothing.
 +
 +== atc_set_ars_disable(value) ==
 +Enables (''value == false'') or disables (''value == true'') interlocking for this train. The train will not trigger automatic route setting on signals based on ARS.
 +
 +This function has essentially the same effect as the ATC command ''[[usage:nodes:atc_controller#a_enable_interlocking|A<enable_interlocking>]]''.
 +
 +**This function is available only in the ''[[http://git.bananach.space/advtrains.git/tree/?h=luaatc-extensions|luaatc-extensions]]'' branch of Advtrains.**
 +
 +== atc_set_lzb_tsr(speed) ==
 +Adds a Temporary Speed Restriction at the current rail, so that the train is passing the rail at the specified ''speed'', or at a lower speed.
 +
 +This function has essentially the same effect as a [[usage:nodes:npr|Point Speed Restriction Rail]].
 +
 +  * **This function is available only in the ''[[http://git.bananach.space/advtrains.git/tree/?h=luaatc-extensions|luaatc-extensions]]'' branch of Advtrains.**
 +  * **This function is available only when the [[#approach_callback_mechanism|approach callback mechanism]] is enabled.**
 +
 +=== Fields ===
 +
 +== atc_id ==
 +The ID of the train passing the rail. ''nil'' if no there is no train.
 +
 +== atc_speed ==
 +The current speed of the train passing the rail, in metres per second. ''nil'' if no there is no train.
 +
 +== atc_arrow ==
 +Whether the train is driving in direction of the arrows on the ATC rail. ''nil'' if no there is no train.
 +
 +**Note: this code does not indicate whether there is a train on the rail, as both ''false'' and ''nil'' evaluate to false:**
 +<code lua>
 +-- BAD
 +if atc_arrow then
 +    -- ...do stuff
 +end
 +
 +-- GOOD
 +if not atc_arrow then
 +    return
 +end
 +-- ...do stuff
 +</code>
 +
 +=== Events ===
 +The LuaATC rail currently supports the following events:
 +
 +== train ==
 +<code lua>
 +event = {
 +    type = "train",
 +    train = true,
 +    id = <train_id>,
 +}
 +</code>
 +Fired when a train enters the rail. The field ''id'' is the unique ID of the train, which is a 6-digit random numerical string.  
 +If the world contains trains from an older Advtrains version, the string may be longer and contain a dot (''.'').
 +
 +== approach ==
 +<code lua>
 +event = {
 +    type = "approach",
 +    approach = true,
 +    id = <train_id>,
 +}
 +</code>
 +Fired when a train approaches the rail. This event may be generated multiple times for the same train.
 +
 +  * **This function is available only in the ''[[http://git.bananach.space/advtrains.git/tree/?h=luaatc-extensions|luaatc-extensions]]'' branch of Advtrains.**
 +  * **This function is available only when the [[#approach_callback_mechanism|approach callback mechanism]] is enabled.**
 +
 +=== Approach callback mechanism ===
 +The approach callback mechanism is a new feature that allows LuaAutomation ATC rails to hook into the approach callback system, which is used by the [[usage:nodes:npr|Point Speed Restriction Rails]] (from ''advtrains_interlocking'') or by [[usage:nodes:stoprail|Station/Stop Rails]] (by ''advtrains_line_automation''). Since it is relatively a recent feature, it needs to be explicitly enabled.
 +
 +**At the time of writing (2019-12-18), this feature is available only in ''[[http://git.bananach.space/advtrains.git/tree/?h=luaatc-extensions|luaatc-extensions]]'' branch of Advtrains. To use this branch, clone the Git repo in the Minetest mods directory and then ''git checkout luaatc-extensions'' on the mod directory.**
 +
 +To enable the feature, define the following global variable in the local environment of the ATC rail:
 +<code lua>
 +-- To enable approach callback only in arrow direction
 +__approach_callback_mode = 1
 +
 +-- To enable approach callback in both directions
 +__approach_callback_mode = 2
 +</code>
 +
 +The event ''[[#approach|approach]]'' will then be generated when a train approaches (which could happen anytime).
 +
 +You'll have to consider the following when setting up approach callbacks:
 +
 +  * Approach callbacks might be generated multiple trains for a same train. If you call ''[[#atc_set_lzb_tsr_speed|atc_set_lzb_tsr]]'', you'll have to call it on every run of the approach callback.
 +  * A reference to the train will be available while executing this event, so functions such as ''atc_send'' and ''atc_set_text_outside'' may be used. On subsequent interrupts however, this reference will no longer be available until the train enters the track.
 +  * The approach callbacks are executed **synchronously** during the train step. This may cause unexpected side effects when performing certain actions (such as switching turnouts, setting signals/routes) from inside such a callback. It is strongly encouraged to only run things that are absolutely necessary at this point in time, and defer anything else to an ''[[#interrupt_time_message|interrupt()]]''. Here are things that are safe to run from an approach callback:
 +    * Accessing and setting global environment
 +    * ''[[#digiline_send_channel_message|digiline_send(channel, message)]]''
 +    * ''[[#atc_set_text_inside_text|atc_set_text_inside(text)]]''/''[[#atc_set_text_outside_text|atc_set_text_outside(text)]]''
 +    * ''[[#atc_set_lzb_tsr_speed|atc_set_lzb_tsr(speed)]]''
  
 ===== Trivia ===== ===== Trivia =====
  
 The LuaAutomation ATC rail has the same texture as the [[usage:nodes:atc_controller|ATC controller rail]], but its functions are different. The LuaAutomation ATC rail has the same texture as the [[usage:nodes:atc_controller|ATC controller rail]], but its functions are different.
usage/nodes/atc_rail.txt · Last modified: 2023-12-12 02:41 by blockhead