Differences

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

--- usage:atlatc:api [2022-08-07 20:21]
62.138.2.14 ↷ Links adapted because of a move operation
+++ usage:atlatc:api [2023-07-05 17:48] (current)
maverick2797 Update to include FC shunting functions, reorganise to a more orderly structure
@@ Line 1: / Line 1: @@
 ====== 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 Standard Lua functions =====
 The standard Lua globals are available in the LuaATC environment:
@@ Line 27: / Line 29: @@
   * ''unpack''
-===== 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 ''pos'' designate a position. You can use either:
@@ Line 39: / Line 43: @@
 A shorthand function to designate a Minetest position vector like ''{x=?, y=?, z=?}''.
-==== Interacting with switches and other passive components ====
+===== Interacting with switches and other passive components =====
 Switches (turnouts), simple signals and mesecon switches are so-called "[[usage:atlatc:passive]]". These functions are used to interact with them.
-=== getstate(pos) ===
+== getstate(pos) ==
 Gets the state of a passive component at position ''pos''. The returned states are component-specific, see [[usage:atlatc:passive]].
-=== setstate(pos, new_state) ===
+== setstate(pos, new_state) ==
 Sets the state of a passive component at position ''pos'' to the value ''new_state''. The states are component-specific, see [[usage:atlatc:passive]].
-=== is_passive(pos) ===
+== is_passive(pos) ==
 Checks whether there is a passive component at position ''pos''. If ''pos'' is a string, checks whether this passive component name exists.
-==== 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:nodes:atc_rail|ATC Tracks]].
+To control a train, this train must be positioned on the ATC rail.((Exceptions: [[usage:atlatc:events#approach|event.type == "appraoch"]] and ''atc_send_to_train()'')) It does not matter which portion of the train is on the ATC rail, and whether the train is moving or not.
+==== 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. ''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 not atc_arrow then
+    -- ...do stuff
+end
+-- GOOD
+if atc_arrow == false then
+    -- ...do stuff
+end
+</code>
+==== 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_send_to_train(train_id, command) ==
+//since version 2.3.0//
+Sends the specified [[usage:nodes:atc_controller#atc_command_syntax|ATC command]] to the train specified by its 6 digit train ID and returns ''true''. If there is no train with such an ID, returns ''false'' and does nothing. Calling this function from an ATC rail is independent of any train that stands on the rail and does not affect it (except of course when train_id happens to be the ID of the train on the rail).
+Note: ''train_id'' **MUST** be a string. Train IDs can begin with ''0'', which is ignored when the variable is of type ''number'', resulting in an invalid 5 digit ID.
+== atc_reset() ==
+Resets the train's current ATC command and returns ''true''. If there is no train, returns ''false'' and does nothing.
+== 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.
+== atc_get_text_outside() / atc_get_text_inside() ==
+Gets the outside/inside text currently set on the train.
+== 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:todo|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)
+This is a bug.
+== set_line(line) ==
+Sets the line property of the train, as a string.
+On [[usage:trains:basic_trains:advtrains_subway|subway trains]], in the Basic Trains modpack, the line is automatically displayed on the outside of the trains, if the first character is a number between 0 and 9 (where 0 is displayed as "Line 10").
+If there is no train, same behavior as [[#get_line()]] applies.
+== 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 [[#get_line()]] applies.
+== 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 [[#get_line()]] applies.
+== atc_set_ars_disable(value) ==
+//since version 2.3.0//
+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_ARS|A<enable_ARS>]]''.
+== 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 ''speed'', or at a lower speed.
+Calling this function from an ''approach'' event has essentially the same effect as a [[usage:nodes:npr|Point Speed Restriction Rail]]. Note that due to internal implementation details, you must call this function again on any subsequent ''approach'' events received. (see [[usage:atlatc:events]])
+  * This function is available only when the [[wiki:todo|approach callback mechanism]] is enabled.
+  * This function is only accessible during ''approach'' events
+==== 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 ''!'', for instance ''foo!bar!baz''. Lists ending in ''?'' have a special function (see ''step_fc()'' below.) Each wagon has a current FC, indicating its next destination. By default this is an empty string.
+== split_at_index(index, atc_command) ==
+Splits the train at the specified index, into a train with ''index-1'' wagons and a second train starting with the ''index-th'' wagon. The ''atc_command'' specified is sent to the second train after decoupling. ''S0'' or ''B0'' is common to ensure any locomotives in the remaining train don't continue to move.
+== 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 ''fc_list''. A false or nil entry in the table will leave the wagon unaffecetd, however all others will be overwritten.
+Useful for mass-programming freight trains that use FC shunting instead of walking to each wagon individually.
+//**NOTE**: ''get_fc()'' and ''set_fc()'' currently only work when the wagon is in a loaded area. They will fail silently when not in a loaded area. This is a bug.//
+== split_at_fc(atc_command, len) ==
+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. ''atc_command'' is sent to the remainder of the train, as with ''split_at_index''. It returns the FC of the wagons of the first part.
+The optional arguement ''len'' specifies a maximum train length to be split off.
+== split_off_locomotive(atc_command, len) ==
+Similar to ''split_at_fc'', this function will separate the first group of wagons with an empty FC, generally locomotives. ''atc_command'' and ''len'' area as above with ''split_at_fc''.
+== step_fc() ==
+Steps the FCs of all wagons forward, selecting the next code after the ''!''. If the end of the string is reached, then the code loops back and the first code is selected. If the string ends in a ''?'' however, the order of codes is reversed instead.
+== 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 ''Cpl'' ATC command, the autocouple property does not reset after coupling. It needs to be explicitly disabled using ''unset_autocouple()''. Note that the ATC ''Cpl'' command and the LuaATC autocouple flag are independent and can be used at the same time.
+//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() ==
+//Deprecated//
+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). When in shunt mode, the train will couple to trains it collides with, and will obey shunt signals.
+Further details on the "Shunt Mode" are explained in the Interlocking section. ([[wiki:todo]])
+If there is no train, returns ''false'' and does nothing.
+== unset_shunt() ==
+//Deprecated//
+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.
@@ Line 70: / Line 254: @@
 -- run 3: {A,B,A,B,A,B,A,B}...
 </code>
-=== interrupt(time, message) ===
+== interrupt(time, message) ==
 Causes the LuaAutomation mod to trigger an ''int'' [[usage:atlatc:events|event]] (the Advtrains equivalent of [[usage:mods:mesecons|Mesecons]]' ''interrupt'') on this component after the given ''time'', in seconds, with the specified ''message''. ''message'' can be of any Lua data type.
@@ Line 76: / Line 260: @@
 Use of this function is discouraged, as "fork bombs" can easily be built. Please use ''interrupt_safe()'' or make sure to ''clear_interrupts()'' in appropriate places.
-=== interrupt_safe(time, message) ===
+== interrupt_safe(time, message) ==
 //since version 2.3.0//
@@ Line 82: / Line 266: @@
 Like ''interrupt()'', but returns false when an interrupt (of any type) is already present for this component and does not add an interrupt. Returns true when interrupt was successfully added.
-===interrupt_pos(pos, message) ===
+== interrupt_pos(pos, message) ==
 Triggers immediately an ''ext_int'' [[usage:atlatc:events|event]] on the active component at ''pos''. ''message'' can be of any Lua data type.
-=== clear_interrupts() ===
+== clear_interrupts() ==
 //since version 2.3.0//
@@ Line 92: / Line 276: @@
 Removes any pending interrupts (both of type 'int' and 'ext_int') set on this node.
-==== Remote ATC ====
+===== Railway Time =====
-//since version 2.3.0//
-In addition to ''atc_send()'' described below, LuaATC provides the possibility to send ATC commands to any train in the world knowing its train ID, by means of the following function.
-=== atc_send_to_train(train_id, command) ===
-Sends the specified [[usage:nodes:atc_controller#atc_command_syntax|ATC command]] to the train specified by its 6-digit train ID and returns ''true''. If there is no train with such an ID, returns ''false'' and does nothing.
-The ATC command is instantly applied to the train in question, regardless of where it is and what it is doing. It also cancels any active ATC command of the train.
-Calling this function from an ATC rail is independent of any train that stands on the rail and does not affect it (except of course when train_id happens to be the ID of the train on the rail).
-==== Railway Time ====
 When ''advtrains_line_automation'' is enabled, all Railway time functions are exposed as rwt.* and can safely be used in LuaATC code.
@@ Line 129: / Line 299: @@
 Clicking "Save" on the code edit form clears all events currently scheduled in the RWT scheduler. It does NOT clear the interrupt scheduler events.
-=== schedule(rwtime, msg) ===
+== schedule(rwtime, msg) ==
 Triggers a ''schedule'' event AT the specified Railway Time.
@@ Line 141: / Line 311: @@
 </code>
-=== schedule_in(rwtime, msg) ===
+== schedule_in(rwtime, msg) ==
 Like schedule(), but the passed time is relative.
@@ Line 149: / Line 319: @@
 </code>
-==== Digiline ====
+===== Digiline =====
-=== digiline_send(channel, message) ===
+== digiline_send(channel, message) ==
-Sends a [[https://content.minetest.net/packages/Jeija/digilines/|digiline]] message on the specified ''channel''.
+Sends a digiline message on the specified ''channel''. See the digilines [[https://content.minetest.net/packages/Jeija/digilines/|ContentDB]] page for more information.
 This function is not available in init code.
-==== Interlocking functions ====
+===== Interlocking functions =====
 Interlocking functions are available when the ''[[usage:mods#advtrains_interlocking|advtrains_interlocking]]'' mod is enabled.
-=== can_set_route(pos, route_name) ===
+== can_set_route(pos, route_name) ==
 Checks whether it is possible to set the route designated by ''route_name'' from the signal at position ''pos''.
@@ Line 179: / Line 349: @@
 > LUA Error: ...: No route called B at (0,0,0)
-=== set_route(pos, route_name) ===
+== set_route(pos, route_name) ==
 Requests the route designated by ''route_name'' from the signal at position ''pos''. Has the same effect as clicking the "Set Route" in the formspec from the designated signal.
@@ Line 189: / Line 359: @@
 There is currently no way to emit an event when the signal becomes green.
-=== cancel_route(pos) ===
+== cancel_route(pos) ==
 Cancels the route that is set from the signal at position ''pos''. Has the same effect as clicking the "Cancel Route" in the formspec from the designated signal.
@@ Line 197: / Line 367: @@
 If the route has already been canceled, nothing happens.
-=== get_aspect(pos) ===
+== get_aspect(pos) ==
 Gets the aspect of the signal at ''pos''. The aspect format is described in the [[wiki:todo|Signal]] page.
 Same warnings apply as for ''[[#can_set_route_pos_route_name|can_set_route]]''.
-===== Train Control =====
-The following functions can only be used from [[usage:nodes:atc_rail]]s. They are used to control trains.
-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 ''approach'', where the approaching train can be controlled. The train is no longer available on subsequent ''int'' or ''schedule'' events.))
-==== 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() ===
-Resets the train's current ATC command and returns ''true''. If there is no train, returns ''false'' and does nothing.
-=== 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.
-=== atc_get_text_outside() / atc_get_text_inside() ===
-Gets the outside/inside text currently set on the train.
-=== 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:todo|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)
-This is a bug.
-=== set_line(line) ===
-Sets the line property of the train, as a string.
-On [[usage:trains:basic_trains:advtrains_subway|subway trains]], in the Basic Trains modpack, the line is automatically displayed on the outside of the trains, if the first character is a number between 0 and 9 (where 0 is displayed as "Line 10").
-If there is no train, same behavior as [[#get_line()]] applies.
-=== 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 [[#get_line()]] applies.
-=== 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 [[#get_line()]] applies.
-=== train_length() ===
-Returns the number of wagons in a train.
-=== 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). When in shunt mode, the train will couple to trains it collides with, and will obey shunt signals.
-Further details on the "Shunt Mode" are explained in the Interlocking section. ([[wiki:todo]])
-If there is no train, returns ''false'' and does nothing.
-=== atc_set_ars_disable(value) ===
-//since version 2.3.0//
-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_ARS|A<enable_ARS>]]''.
-=== 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 ''speed'', or at a lower speed.
-Calling this function from an ''approach'' event has essentially the same effect as a [[usage:nodes:npr|Point Speed Restriction Rail]]. Note that due to internal implementation details, you must call this function again on any subsequent ''approach'' events received. (see [[usage:atlatc:events]])
-  * This function is available only when the [[wiki:todo|approach callback mechanism]] is enabled.
-  * This function is only accessible during ''approach'' events
-=== 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 ''Cpl'' ATC command, the autocouple property does not reset after coupling. It needs to be explicitly disabled using ''unset_autocouple()''. Note that the ATC ''Cpl'' command and the LuaATC autocouple flag are independent and can be used at the same time.
-//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.
-==== 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 not atc_arrow then
-    -- ...do stuff
-end
--- GOOD
-if atc_arrow == false then
-    -- ...do stuff
-end
-</code>

Advanced Trains

User Tools

Site Tools

Differences

Page Tools