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
usage:nodes:atc_rail [2019/11/07 09:20]
orwell never do this
usage:nodes:atc_rail [2019/12/18 14:38] (current)
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: 2019/12/18 14:38 by mlaunois