Advanced Trains

User Tools

Site Tools

You are here: Advanced Trains » User Guide » Lua ATC » LuaATC Programming Interface
usage:atlatc:api

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 		Previous revision
Next revision Both sides next revision
usage:atlatc:api [2020-01-24 10:27]
orwell Note: most of this page has been moved from usage:nodes:atc_rail (by mlaunois) 		usage:atlatc:api [2020-02-23 09:10]
orwell
Line 8: Line 8:
   * ''math''   * ''math''
   * ''table''   * ''table''
-  * ''os''+  * from ''os'': 
 +    * ''os.clock()'' 
 +    * ''os.difftime()'' 
 +    * ''os.time()'' 
 +    * ''os.date()'' ((note that ''os.date()'' without parameters returns in table form ''("*t")''))
  
 The standard Lua functions are available in the LuaATC environment: The standard Lua functions are available in the LuaATC environment:
Line 39: Line 43:
 Switches (turnouts), simple signals and mesecon switches are so-called "[[usage:atlatc:passive]]". These functions are used to interact with them. 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]]. 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]]. 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. Checks whether there is a passive component at position ''pos''. If ''pos'' is a string, checks whether this passive component name exists.
  
-=== Interrupts ===+==== 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 66: Line 70:
 -- run 3: {A,B,A,B,A,B,A,B}... -- run 3: {A,B,A,B,A,B,A,B}...
 </code> </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. 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.
  
-== 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. Triggers immediately an ''ext_int'' [[usage:atlatc:events|event]] on the active component at ''pos''. ''message'' can be of any Lua data type.
  
-=== Railway Time ===+==== Railway Time ====
  
 When ''advtrains_line_automation'' is enabled, all Railway time functions are exposed as rwt.* and can safely be used in LuaATC code. When ''advtrains_line_automation'' is enabled, all Railway time functions are exposed as rwt.* and can safely be used in LuaATC code.
Line 86: Line 90:
 </code> </code>
  
-=== 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 ''advtrains_line_automation'' is enabled. 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 ''advtrains_line_automation'' is enabled.
Line 97: Line 101:
 Clicking "Save" on the code edit form clears all events currently scheduled in the RWT scheduler. It does NOT clear the interrupt scheduler events. 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. Triggers a ''schedule'' event AT the specified Railway Time.
Line 103: Line 107:
 msg can be any data type and is accessible in ''event.msg''. msg can be any data type and is accessible in ''event.msg''.
  
-== schedule_in(rwtime, msg) ==+=== schedule_in(rwtime, msg) ===
  
 Like schedule(), but the passed time is relative. Like schedule(), but the passed time is relative.
Line 111: Line 115:
 </code> </code>
  
-=== Digiline ===+==== Digiline ====
  
-== digiline_send(channel, message) ==+=== digiline_send(channel, message) ===
  
 Sends a [[usage:mods:digilines|digiline]] message on the specified ''channel''. Sends a [[usage:mods:digilines|digiline]] message on the specified ''channel''.
Line 119: Line 123:
 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 ''[[usage:mods#advtrains_interlocking|advtrains_interlocking]]'' mod is enabled. 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''. Checks whether it is possible to set the route designated by ''route_name'' from the signal at position ''pos''.
Line 141: Line 145:
 > LUA Error: ...: No route called B at (0,0,0) > 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. 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 151: Line 155:
 There is currently no way to emit an event when the signal becomes green. 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. 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 159: Line 163:
 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 ''pos''. The aspect format is described in the [[wiki:todo|Signal]] page. Gets the aspect of the signal at ''pos''. The aspect format is described in the [[wiki:todo|Signal]] page.
Line 171: Line 175:
 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.)) 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 ===+==== Functions ====
  
-== atc_send(cmd) ==+=== 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. 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() ==+=== atc_reset() ===
 Resets the train's current ATC command and returns ''true''. If there is no train, returns ''false'' and does nothing. 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) ==+=== 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. 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) ==+=== 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. Sets the text shown inside the train and returns ''true''. If there is no train, returns ''false'' and does nothing.
  
-== get_line() ==+=== 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. 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.
  
Line 196: Line 200:
 This is a bug. This is a bug.
  
-== set_line(line) == +=== 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 the first character is a number between 0 and 9 (where 0 is displayed as "Line 10").+Sets the line property of the train, as a string.
  
-This property is also used by the interlocking system for Automatic Routesetting.+On [[usage:trains:subway_train|subway trains]] bundled with Advtrains, 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, the Lua program stored in the rail will exit immediately: +If there is no train, same behavior as [[#get_line()]] applies.
- +
-> 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() ==+=== get_rc() ===
 Returns the routing code of the train, as a string. This property is used by the interlocking system for Automatic Routesetting. 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: +If there is no train, same behavior as [[#get_line()]] applies.
- +
-> 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) ==+=== set_rc(rc) ===
 Sets the routing code of the train, as a string. This property is used by the interlocking system for Automatic Routesetting. 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: +If there is no train, same behavior as [[#get_line()]] applies.
- +
-> 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() ==+=== 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. 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. If there is no train, returns ''false'' and does nothing.
  
-== atc_set_ars_disable(value) ==+=== 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. Enables (''value == false'') or disables (''value == true'') interlocking for this train. The train will not trigger automatic route setting on signals based on ARS.
  
Line 231: Line 231:
 **This function is experimental and currently available only in the ''[[http://git.bananach.space/advtrains.git/tree/?h=luaatc-extensions|luaatc-extensions]]'' branch of Advtrains.** **This function is experimental and currently available only in the ''[[http://git.bananach.space/advtrains.git/tree/?h=luaatc-extensions|luaatc-extensions]]'' branch of Advtrains.**
  
-== atc_set_lzb_tsr(speed) ==+=== 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. 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]].+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
  
 **This function is experimental and currently available only in the ''[[http://git.bananach.space/advtrains.git/tree/?h=luaatc-extensions|luaatc-extensions]]'' branch of Advtrains.** **This function is experimental and currently 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 [[wiki:todo|approach callback mechanism]] is enabled.** 
  
-=== Fields ===+==== Fields ====
  
-== atc_id ==+=== atc_id ===
 The ID of the train passing the rail. ''nil'' if no there is no train. The ID of the train passing the rail. ''nil'' if no there is no train.
  
-== atc_speed ==+=== atc_speed ===
 The current speed of the train passing the rail, in metres per second. ''nil'' if no there is no train. The current speed of the train passing the rail, in metres per second. ''nil'' if no there is no train.
  
-== atc_arrow ==+=== atc_arrow ===
 Whether the train is driving in direction of the arrows on the ATC rail. ''nil'' if no there is no train. Whether the train is driving in direction of the arrows on the ATC rail. ''nil'' if no there is no train.
  
usage/atlatc/api.txt · Last modified: 2023-07-05 17:48 by maverick2797

Page Tools

Except where otherwise noted, content on this wiki is licensed under the following license: CC Attribution-Share Alike 4.0 International
CC Attribution-Share Alike 4.0 International Donate Powered by PHP Valid HTML5 Valid CSS Driven by DokuWiki