This shows you the differences between two versions of the page.
Next revision | Previous revision | ||
usage:atlatc:api [2020-01-24 10:24] orwell created |
usage:atlatc:api [2023-07-05 17:48] maverick2797 Update to include FC shunting functions, reorganise to a more orderly structure |
||
---|---|---|---|
Line 1: | Line 1: | ||
====== LuaATC Programming Interface ====== | ====== LuaATC Programming Interface ====== | ||
- | ===== Available Lua functions ===== | + | LuaATC (Lua Advanced Train Control, also called LuaAutomation) utilises the Lua programming language to provide an immensely powerful automation system for Advtrains. Prior knowledge of Lua is highly reccommended. |
+ | |||
+ | ===== Available | ||
The standard Lua globals are available in the LuaATC environment: | The standard Lua globals are available in the LuaATC environment: | ||
Line 8: | Line 10: | ||
* '' | * '' | ||
* '' | * '' | ||
- | * '' | + | * from '' |
+ | * '' | ||
+ | * '' | ||
+ | * '' | ||
+ | * '' | ||
The standard Lua functions are available in the LuaATC environment: | The standard Lua functions are available in the LuaATC environment: | ||
Line 23: | Line 29: | ||
* '' | * '' | ||
- | ===== LuaAutomation-specific functions | + | ===== Important Helpers and Notes ===== |
+ | |||
+ | Certain aspects of LuaAutomation can only be done at certain times, and others require specific conditions to be useful. These are noted under the section headings. | ||
In the following functions, all parameters named '' | In the following functions, all parameters named '' | ||
Line 35: | Line 43: | ||
A shorthand function to designate a Minetest position vector like '' | A shorthand function to designate a Minetest position vector like '' | ||
- | ==== Interacting with switches and other passive components ==== | + | ===== Interacting with switches and other passive components |
Switches (turnouts), simple signals and mesecon switches are so-called " | Switches (turnouts), simple signals and mesecon switches are so-called " | ||
Line 51: | Line 59: | ||
Checks whether there is a passive component at position '' | Checks whether there is a passive component at position '' | ||
- | === Interrupts === | + | ===== Train Control ===== |
+ | |||
+ | Train control is arguably the most important aspect of automating a rail system. The following functions can only be used from [[usage: | ||
+ | |||
+ | To control a train, this train must be positioned on the ATC rail.((Exceptions: | ||
+ | |||
+ | ==== Fields ==== | ||
+ | |||
+ | These fields are populated every time a train is occupying a LuaATC track. | ||
+ | |||
+ | == atc_id == | ||
+ | The 6 digit ID of the train passing the rail as a string. '' | ||
+ | |||
+ | == 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 not atc_arrow then | ||
+ | -- ...do stuff | ||
+ | end | ||
+ | |||
+ | -- GOOD | ||
+ | if atc_arrow == false then | ||
+ | -- ...do stuff | ||
+ | end | ||
+ | </ | ||
+ | |||
+ | ==== Functions ==== | ||
+ | == atc_send(cmd) == | ||
+ | Sends the specified [[usage: | ||
+ | |||
+ | == atc_send_to_train(train_id, | ||
+ | //since version 2.3.0// | ||
+ | |||
+ | Sends the specified [[usage: | ||
+ | |||
+ | Note: '' | ||
+ | |||
+ | == atc_reset() == | ||
+ | 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 '' | ||
+ | |||
+ | == atc_get_text_outside() / atc_get_text_inside() == | ||
+ | Gets the outside/ | ||
+ | |||
+ | == 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 [[wiki: | ||
+ | |||
+ | If there is no train, the Lua program stored in the rail will exit immediately: | ||
+ | |||
+ | > 2019-01-01 15:00:00: WARNING[Server]: | ||
+ | |||
+ | This is a bug. | ||
+ | |||
+ | == set_line(line) == | ||
+ | Sets the line property of the train, as a string. | ||
+ | |||
+ | On [[usage: | ||
+ | |||
+ | If there is no train, same behavior as [[# | ||
+ | |||
+ | == 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, same behavior as [[# | ||
+ | |||
+ | == 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, same behavior as [[# | ||
+ | |||
+ | == atc_set_ars_disable(value) == | ||
+ | |||
+ | //since version 2.3.0// | ||
+ | |||
+ | Enables ('' | ||
+ | |||
+ | This function has essentially the same effect as the ATC command '' | ||
+ | |||
+ | == atc_set_lzb_tsr(speed) == | ||
+ | |||
+ | //since version 2.3.0// | ||
+ | |||
+ | Adds a Temporary Speed Restriction at the current rail, so that the train is passing the rail at the specified '' | ||
+ | |||
+ | Calling this function from an '' | ||
+ | |||
+ | * This function is available only when the [[wiki: | ||
+ | * This function is only accessible during '' | ||
+ | |||
+ | |||
+ | ==== Shunting-Specific Functions ==== | ||
+ | |||
+ | Aside from basic train control, LuaAutomation enables automatic and complex shunting operations to be performed. | ||
+ | |||
+ | There are several functions available especially for shunting operations. Some of these functions make use of Freight Codes (FC) set in the Wagon Properties of each wagon.((For the purpose of this document, locomotives are also classed as wagons in this respect.)) | ||
+ | |||
+ | FCs are composed of strings separated by '' | ||
+ | |||
+ | == split_at_index(index, | ||
+ | |||
+ | Splits the train at the specified index, into a train with '' | ||
+ | |||
+ | == get_fc() == | ||
+ | |||
+ | //since version 2.4.3// | ||
+ | |||
+ | Returns a table with the entire FC list for each wagon in the train. | ||
+ | |||
+ | == set_fc(fc_list) == | ||
+ | |||
+ | //since version 2.4.3// | ||
+ | |||
+ | Overwrites the FC list of the entire train according to a table '' | ||
+ | |||
+ | Useful for mass-programming freight trains that use FC shunting instead of walking to each wagon individually. | ||
+ | |||
+ | //**NOTE**: '' | ||
+ | |||
+ | == split_at_fc(atc_command, | ||
+ | |||
+ | Splits the train in such a way thay all wagons with non-empty current FC of the first part of the train have the same FC. '' | ||
+ | |||
+ | The optional arguement '' | ||
+ | |||
+ | == split_off_locomotive(atc_command, | ||
+ | |||
+ | Similar to '' | ||
+ | |||
+ | == step_fc() == | ||
+ | |||
+ | Steps the FCs of all wagons forward, selecting the next code after the '' | ||
+ | |||
+ | == train_length() == | ||
+ | |||
+ | Returns the number of wagons in a train. | ||
+ | |||
+ | == set_autocouple() == | ||
+ | |||
+ | Enables Autocouple mode. When the train hits another standing train, it couples to it and continues with its current ATC target speed in the same direction. | ||
+ | |||
+ | In contrast to the '' | ||
+ | |||
+ | //since version 2.4.0// | ||
+ | |||
+ | The train that is initiating the coupling (that is, the train that is driving and whose mode is set to autocouple) is guaranteed to retain its Train ID. | ||
+ | |||
+ | == unset_autocouple() == | ||
+ | |||
+ | Disables the Autocouple mode. | ||
+ | |||
+ | |||
+ | == set_shunt() == | ||
+ | |||
+ | // | ||
+ | |||
+ | Enables shunting mode for the currently passing train and returns '' | ||
+ | |||
+ | Further details on the "Shunt Mode" are explained in the Interlocking section. ([[wiki: | ||
+ | |||
+ | If there is no train, returns '' | ||
+ | |||
+ | == unset_shunt() == | ||
+ | |||
+ | // | ||
+ | |||
+ | Disables shunting mode as set above | ||
+ | |||
+ | ===== Interrupts | ||
These functions allow to schedule interrupts, a.k.a events to be executed at a later time. They are not available in init code. | These functions allow to schedule interrupts, a.k.a events to be executed at a later time. They are not available in init code. | ||
Line 69: | Line 257: | ||
Causes the LuaAutomation mod to trigger an '' | Causes the LuaAutomation mod to trigger an '' | ||
+ | |||
+ | Use of this function is discouraged, | ||
+ | |||
+ | == interrupt_safe(time, | ||
+ | |||
+ | //since version 2.3.0// | ||
+ | |||
+ | Like '' | ||
== interrupt_pos(pos, | == interrupt_pos(pos, | ||
Line 74: | Line 270: | ||
Triggers immediately an '' | Triggers immediately an '' | ||
- | === Railway Time === | + | == clear_interrupts() == |
+ | |||
+ | //since version 2.3.0// | ||
+ | |||
+ | Removes any pending interrupts (both of type ' | ||
+ | |||
+ | ===== Railway Time ===== | ||
When '' | When '' | ||
- | For the available functions, see [[dev:lines:rwt]]. | + | For the available functions, see [[dev:api:railway_time_api]]. |
< | < | ||
Line 86: | Line 288: | ||
</ | </ | ||
- | === Railway Time Scheduler === | + | ==== 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 '' | 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 '' | ||
Line 102: | Line 304: | ||
The time value here is an absolute value. | The time value here is an absolute value. | ||
msg can be any data type and is accessible in '' | msg can be any data type and is accessible in '' | ||
+ | < | ||
+ | -- Example: schedule a " | ||
+ | local now = rwt.now() | ||
+ | local next_5minutes = rwt.next_rpt(now, | ||
+ | schedule(next_5minutes, | ||
+ | </ | ||
== schedule_in(rwtime, | == schedule_in(rwtime, | ||
Line 111: | Line 319: | ||
</ | </ | ||
- | === Digiline === | + | ===== Digiline |
== digiline_send(channel, | == digiline_send(channel, | ||
- | Sends a [[usage: | + | Sends a digiline message on the specified '' |
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 '' | ||
Line 164: | Line 372: | ||
Same warnings apply as for '' | Same warnings apply as for '' | ||
- | |||
- | ===== Train Control ===== | ||
- | |||
- | The following functions can only be used from [[usage: | ||
- | |||
- | To control a train, this train must be positioned on the ATC rail. It does not matter which portion of the train is on the ATC rail, and whether the train is moving or not. ((An exception applies to events of type '' | ||
- | |||
- | == atc_send(cmd) == | ||
- | Sends the specified [[usage: | ||
- | |||
- | == atc_reset() == | ||
- | 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 [[wiki: | ||
- | |||
- | If there is no train, the Lua program stored in the rail will exit immediately: | ||
- | |||
- | > 2019-01-01 15:00:00: WARNING[Server]: | ||
- | |||
- | This is a bug. | ||
- | |||
- | == 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 experimental and currently 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 experimental and currently available only in the '' | ||
- | * **This function is available only when the [[wiki: | ||
- | |||
- | === 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 not atc_arrow then | ||
- | -- ...do stuff | ||
- | end | ||
- | |||
- | -- GOOD | ||
- | if atc_arrow == false then | ||
- | -- ...do stuff | ||
- | end | ||
- | </ |