User Tools

Site Tools


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:31]
orwell
usage:atlatc:api [2021-05-26 22:03]
56independent added an function wich didnt exist.
Line 43: 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 70: 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) ==+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) === 
 + 
 +//since version 2.3.0// 
 + 
 +Like ''interrupt()'', but does not add an interrupt and returns false when an interrupt (of any type) is already present for this component. Returns true when interrupt was successfully added. 
 + 
 +===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 ===+=== clear_interrupts() === 
 + 
 +//since version 2.3.0// 
 + 
 +Removes any pending interrupts (both of type 'int' and 'ext_int') set on this node. 
 + 
 +==== Remote ATC ==== 
 + 
 +//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. When ''advtrains_line_automation'' is enabled, all Railway time functions are exposed as rwt.* and can safely be used in LuaATC code.
Line 90: Line 118:
 </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 101: Line 129:
 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.
 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 ''event.msg''. msg can be any data type and is accessible in ''event.msg''.
 +<code>
 +  -- Example: schedule a "depart" event on the next full 5 minutes
 +  local now = rwt.now()
 +  local next_5minutes = rwt.next_rpt(now, "05;00", 0)
 +  schedule(next_5minutes, "depart")
 +</code>
  
-== 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 115: Line 149:
 </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 123: Line 157:
 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 145: Line 179:
 > 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 155: Line 189:
 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 163: Line 197:
 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 175: Line 209:
 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() ==+=== 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. 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 200: Line 237:
 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:+
  
-> 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)+If there is no train, same behavior as [[#get_line()]] applies.
  
-== 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)+=== train_length() ===  
 +Returns the length of the Train in carragesexample ''if train_length() < 5 then set_line("short") end'' 
  
-== 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) ==
 + 
 +//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. 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>]]''. This function has essentially the same effect as the ATC command ''[[usage:nodes:atc_controller#a_enable_ARS|A<enable_ARS>]]''.
  
-**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) === 
 + 
 +//since version 2.3.0//
  
-== 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 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. 
-  * **This function is available only when the [[wiki:todo|approach callback mechanism]] is enabled.**+  This function is only accessible during ''approach'' events
  
-=== 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