This shows you the differences between two versions of the page.
Both sides previous revision Previous revision Next revision | Previous revision Next revision Both sides next revision | ||
usage:nodes:atc_rail [2019-07-02 17:06] 82.67.173.193 added information to wiki article (2/4) |
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:// | + | {{ :usage: |
- | //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 108: | Line 108: | ||
* a string, the name of a [[# | * a string, the name of a [[# | ||
- | === POS(x, y, z) === | + | == POS(x, y, z) == |
A shorthand function to designate a Minetest position vector like '' | A shorthand function to designate a Minetest position vector like '' | ||
- | === getstate(pos) | + | === Interacting with switches and other passive components |
- | Gets the state of a passive | + | Switches (turnouts), simple signals and mesecon switches are so-called "passive |
+ | Switch: | ||
+ | " | ||
+ | " | ||
+ | Signal: (simple signals, wall signals) | ||
+ | " | ||
+ | " | ||
+ | Mesecon Switch, Andrew' | ||
+ | " | ||
+ | " | ||
- | === setstate(pos, new_state) === | + | == getstate(pos) == |
- | Sets the state of a passive component at position '' | + | Gets the state of a passive component at position '' |
- | === is_passive(pos) | + | == setstate(pos, |
+ | |||
+ | Sets the state of a passive component at position '' | ||
+ | |||
+ | == is_passive(pos) == | ||
Checks whether there is a passive component at position '' | Checks whether there is a passive component at position '' | ||
- | === interrupt(time, | + | === Interrupts |
- | Causes the LuaAutomation mod to trigger an '' | + | These functions allow to schedule interrupts, a.k.a events to be executed at a later time. They are not available in init code. |
- | This function | + | The time counter and queue handling these interrupts |
+ | <code> | ||
+ | -- an example for an " | ||
+ | -- NEVER DO THIS! | ||
+ | if event.int then | ||
+ | interrupt(1," | ||
+ | interrupt(1," | ||
+ | -- run 1: {A,B} | ||
+ | -- run 2: {A,B,A,B} | ||
+ | -- run 3: {A, | ||
+ | </ | ||
+ | == interrupt(time, | ||
+ | |||
+ | Causes the LuaAutomation mod to trigger an '' | ||
- | === interrupt_pos(pos, | + | == interrupt_pos(pos, |
Triggers immediately an '' | Triggers immediately an '' | ||
- | **Use with care! This may lead to expotential growth of interrupts.** | + | === Railway Time === |
- | === digiline_send(channel, | + | When '' |
+ | |||
+ | For the available functions, see [[dev: | ||
+ | |||
+ | < | ||
+ | --Example: print the time of the next full minute | ||
+ | local now = rwt.now() | ||
+ | local next_minute = rwt.next_rpt(now, | ||
+ | </ | ||
+ | |||
+ | === Railway Time Scheduler === | ||
+ | |||
+ | This is a separate schedule queue. In contrast to the interrupt system, which is the original and established way to schedule interrupts, it relies on the Railway Time system and therefore is only accessible when '' | ||
+ | |||
+ | There are two important considerations to this: | ||
+ | |||
+ | - While the interrupt system is always synchronized to minetest step time, the RWT scheduler follows the RWT time flow. In particular, this means that you must be able to handle "time jumps" that occur when RWT is set up to adapt to real time. | ||
+ | - The RWT scheduler has a built-in protection against " | ||
+ | |||
+ | Clicking " | ||
+ | |||
+ | == schedule(rwtime, | ||
+ | |||
+ | Triggers a '' | ||
+ | The time value here is an absolute value. | ||
+ | msg can be any data type and is accessible in '' | ||
+ | |||
+ | == schedule_in(rwtime, | ||
+ | |||
+ | Like schedule(), but the passed time is relative. | ||
+ | < | ||
+ | -- Example: schedule a " | ||
+ | schedule_in(" | ||
+ | </ | ||
+ | |||
+ | === Digiline === | ||
+ | |||
+ | == digiline_send(channel, | ||
Sends a [[usage: | Sends a [[usage: | ||
Line 142: | Line 205: | ||
This function is not available in init code. | This function is not available in init code. | ||
- | ==== Interlocking functions | + | === Interlocking functions === |
Interlocking functions are available when the '' | Interlocking functions are available when the '' | ||
- | === can_set_route(pos, | + | == can_set_route(pos, |
Checks whether it is possible to set the route designated by '' | Checks whether it is possible to set the route designated by '' | ||
Line 164: | Line 227: | ||
> 2019-01-01 15:00:00: WARNING[Server]: | > 2019-01-01 15:00:00: WARNING[Server]: | ||
- | === set_route(pos, | + | == set_route(pos, |
Requests the route designated by '' | Requests the route designated by '' | ||
Line 172: | Line 235: | ||
If the route can't be set, the signal remains red and waits for conflicting problems to be solved. Execution continues **immediately**. | If the route can't be set, the signal remains red and waits for conflicting problems to be solved. Execution continues **immediately**. | ||
- | === cancel_route(pos, | + | == cancel_route(pos, |
Cancels the route designated by '' | Cancels the route designated by '' | ||
Line 180: | Line 243: | ||
If the route has already been canceled, nothing happens. | If the route has already been canceled, nothing happens. | ||
- | === get_aspect(pos) | + | == get_aspect(pos) == |
Gets the aspect of the signal at '' | Gets the aspect of the signal at '' | ||
Line 197: | Line 260: | ||
</ | </ | ||
+ | You can check for a specific event type by using | ||
+ | <code lua> | ||
+ | if event.type == "< | ||
+ | -- ... do stuff | ||
+ | end | ||
+ | </ | ||
+ | or | ||
+ | <code lua> | ||
+ | if event.< | ||
+ | -- ... do stuff | ||
+ | end | ||
+ | </ | ||
+ | |||
+ | === int === | ||
+ | <code lua> | ||
+ | event = { | ||
+ | type = " | ||
+ | int = true, | ||
+ | msg = < | ||
+ | message = < | ||
+ | } | ||
+ | </ | ||
+ | Fired when an interrupt set by the '' | ||
+ | For backwards compatibility reasons, the message is also contained in the '' | ||
+ | |||
+ | === ext_int === | ||
+ | <code lua> | ||
+ | event = { | ||
+ | type = " | ||
+ | ext_int = true, | ||
+ | message = < | ||
+ | } | ||
+ | </ | ||
+ | Fired when a node called '' | ||
+ | |||
+ | === digiline === | ||
+ | <code lua> | ||
+ | event = { | ||
+ | type = " | ||
+ | digiline = true, | ||
+ | channel = < | ||
+ | msg = < | ||
+ | } | ||
+ | </ | ||
+ | Fired when the rail receives a [[usage: | ||
+ | |||
+ | ==== Specific to the ATC rail ==== | ||
+ | |||
+ | === Functions === | ||
+ | == atc_send(cmd) == | ||
+ | Sends the specified [[usage: | ||
+ | |||
+ | == atc_reset(cmd) == | ||
+ | Resets the train' | ||
+ | |||
+ | '' | ||
+ | |||
+ | == atc_set_text_outside(text) == | ||
+ | Sets the text shown on the outside of the train and returns '' | ||
+ | |||
+ | == atc_set_text_inside(text) == | ||
+ | Sets the text shown inside the train and returns '' | ||
+ | |||
+ | == 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]: | ||
+ | |||
+ | == set_line(line) == | ||
+ | Sets the line property of the train, as a string. On [[usage: | ||
+ | |||
+ | 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]: | ||
+ | |||
+ | == 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]: | ||
+ | |||
+ | == 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]: | ||
+ | |||
+ | == set_shunt() == | ||
+ | Enables shunting mode for the currently passing train and returns '' | ||
+ | |||
+ | If there is no train, returns '' | ||
+ | |||
+ | == atc_set_ars_disable(value) == | ||
+ | Enables ('' | ||
+ | |||
+ | This function has essentially the same effect as the ATC command '' | ||
+ | |||
+ | **This function is available only in the '' | ||
+ | |||
+ | == 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 '' | ||
+ | |||
+ | This function has essentially the same effect as a [[usage: | ||
+ | |||
+ | * **This function is available only in the '' | ||
+ | * **This function is available only when the [[# | ||
+ | |||
+ | === Fields === | ||
+ | |||
+ | == atc_id == | ||
+ | The ID of the train passing the rail. '' | ||
+ | |||
+ | == atc_speed == | ||
+ | The current speed of the train passing the rail, in metres per second. '' | ||
+ | |||
+ | == atc_arrow == | ||
+ | Whether the train is driving in direction of the arrows on the ATC rail. '' | ||
+ | |||
+ | **Note: this code does not indicate whether there is a train on the rail, as both '' | ||
+ | <code lua> | ||
+ | -- BAD | ||
+ | if atc_arrow then | ||
+ | -- ...do stuff | ||
+ | end | ||
+ | |||
+ | -- GOOD | ||
+ | if not atc_arrow then | ||
+ | return | ||
+ | end | ||
+ | -- ...do stuff | ||
+ | </ | ||
+ | |||
+ | === Events === | ||
+ | The LuaATC rail currently supports the following events: | ||
+ | |||
+ | == train == | ||
+ | <code lua> | ||
+ | event = { | ||
+ | type = " | ||
+ | train = true, | ||
+ | id = < | ||
+ | } | ||
+ | </ | ||
+ | Fired when a train enters the rail. The field '' | ||
+ | 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 = true, | ||
+ | id = < | ||
+ | } | ||
+ | </ | ||
+ | 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 '' | ||
+ | * **This function is available only when the [[# | ||
+ | |||
+ | === 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: | ||
+ | |||
+ | **At the time of writing (2019-12-18), | ||
+ | |||
+ | 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 | ||
+ | </ | ||
+ | |||
+ | The event '' | ||
+ | |||
+ | 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 '' | ||
+ | * A reference to the train will be available while executing this event, so functions such as '' | ||
+ | * 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/ | ||
+ | * Accessing and setting global environment | ||
+ | * '' | ||
+ | * '' | ||
+ | * '' | ||
===== Trivia ===== | ===== Trivia ===== | ||
The LuaAutomation ATC rail has the same texture as the [[usage: | The LuaAutomation ATC rail has the same texture as the [[usage: |