User Tools

Site Tools


Sidebar



Minetest Forum
Content Database
Git Repository
Bug Tracker
Website

usage:atlatc:api

LuaATC Programming Interface

Available Lua functions

The standard Lua globals are available in the LuaATC environment:

  • string
  • math
  • table
  • from os:
    • os.clock()
    • os.difftime()
    • os.time()
    • os.date() 1)

The standard Lua functions are available in the LuaATC environment:

  • assert
  • error
  • ipairs
  • pairs
  • next
  • select
  • tonumber
  • tostring
  • type
  • unpack

LuaAutomation-specific functions

In the following functions, all parameters named pos designate a position. You can use either:

POS(x, y, z)

A shorthand function to designate a Minetest position vector like {x=?, y=?, z=?}.

Interacting with switches and other passive components

Switches (turnouts), simple signals and mesecon switches are so-called “Passive Components”. These functions are used to interact with them.

getstate(pos)

Gets the state of a passive component at position pos. The returned states are component-specific, see Passive Components.

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 Passive Components.

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

These functions allow to schedule interrupts, a.k.a events to be executed at a later time. They are not available in init code.

The time counter and queue handling these interrupts is synchronized to minetest's internal step time. It is written in a very simple fashion, and is NOT secured against “interrupt bombs”. Be careful!

-- an example for an "interrupt bomb"
-- NEVER DO THIS!
if event.int then
  interrupt(1,"A")
  interrupt(1,"B")
-- run 1: {A,B}
-- run 2: {A,B,A,B}
-- run 3: {A,B,A,B,A,B,A,B}...

interrupt(time, message)

Causes the LuaAutomation mod to trigger an int event (the Advtrains equivalent of Mesecons' interrupt) on this component after the given time, in seconds, with the specified message. message can be of any Lua data type.

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 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 event on the active component at pos. message can be of any Lua data type.

clear_interrupts()

since version 3.0

Removes any pending interrupts (both of type 'int' and 'ext_int') set on this node.

Railway Time

When advtrains_line_automation is enabled, all Railway time functions are exposed as rwt.* and can safely be used in LuaATC code.

For the available functions, see Railway Time API.

--Example: print the time of the next full minute
local now = rwt.now()
local next_minute = rwt.next_rpt(now, "01;00", 0)

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.

There are two important considerations to this:

  1. 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.
  2. The RWT scheduler has a built-in protection against “interrupt bombs”. There is a limit on how many interrupts can be enqueued from a single LuaATC component. At the time of this writing, this limit is set to 1.

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)

Triggers a schedule event AT the specified Railway Time. The time value here is an absolute value. msg can be any data type and is accessible in event.msg.

  -- 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")

schedule_in(rwtime, msg)

Like schedule(), but the passed time is relative.

  -- Example: schedule a "depart" event in 1 minute
  schedule_in("01;00", "depart")

Digiline

digiline_send(channel, message)

Sends a digiline message on the specified channel.

This function is not available in init code.

Interlocking functions

Interlocking functions are available when the advtrains_interlocking mod is enabled.

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.

It emits a warning and halts execution of Lua code in the following cases:

  • the node at specified position is not a signal:
LUA Error: …: There's no signal at (0,0,0)
  • pos is a string, and the named passive component does not exist:
LUA Error: …: Invalid position supplied to ???: “…”
  • the specified route does not exist:
LUA Error: …: No route called B at (0,0,0)

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.

Same warnings apply as for can_set_route.

If the route can't be set, the signal remains red and waits for conflicting problems to be solved. Execution continues immediately.

There is currently no way to emit an event when the signal becomes green.

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.

Same warnings apply as for can_set_route.

If the route has already been canceled, nothing happens.

get_aspect(pos)

Gets the aspect of the signal at pos. The aspect format is described in the Signal page.

Same warnings apply as for can_set_route.

Train Control

The following functions can only be used from LuaAutomation ATC rails. 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. 2)

Functions

atc_send(cmd)

Sends the specified 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.

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]: [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 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, 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.

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. (Missing Reference)

If there is no train, returns false and does nothing.

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.

This function has essentially the same effect as the ATC command A<enable_ARS>.

This function is experimental and currently available only in the luaatc-extensions branch of Advtrains.

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.

Calling this function from an approach event has essentially the same effect as a Point Speed Restriction Rail. Note that due to internal implementation details, you must call this function again on any subsequent approach events received. (see Events)

  • This function is available only when the approach callback mechanism is enabled.
  • This function is only accessible during approach events

This function is experimental and currently available only in the luaatc-extensions branch of Advtrains.

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:

-- BAD
if not atc_arrow then
    -- ...do stuff
end
 
-- GOOD
if atc_arrow == false then
    -- ...do stuff
end
1)
note that os.date() without parameters returns in table form (“*t”)
2)
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.
usage/atlatc/api.txt · Last modified: 2021/02/17 23:38 by orwell