User Tools

Site Tools


Sidebar



Minetest Forum
Content Database
Git Repository
Bug Tracker
Website

usage:nodes:atc_rail

This is an old revision of the document!


LuaAutomation ATC rail

Do anything you want with ATC rails.


FIXME This is a draft. Please improve this page by creating relevant pages, adding information and references to internal or external sources.


Note: this page has been written for Advtrains 2.0.1 TSS and Minetest 5.1.0. Examples and practices described in this page don't take advantage of improvements introduced in later releases.

Properties

Mod: advtrains_luaautomation
Node name: advtrains_luaautomation:dtrack_placer
Other names:

  • advtrains_luaautomation:dtrack_st
  • advtrains_luaautomation:dtrack_st_30
  • advtrains_luaautomation:dtrack_st_45
  • advtrains_luaautomation:dtrack_st_60

Craft recipe

This node has no craft recipe.

Extended description

  • When the rail is first built, this rail node does nothing. But once right-clicking (or double tapping on Android) the node, a formspec displays, allowing you to write Lua code for the current node.
  • Interacting with the ATC rail requires the atlatc privilege.
  • The code in the ATC rail is executed when an event is fired. See Events for a list of events this node supports.
  • This node can be rotated by the Trackworker.
  • Only straight nodes are supported. You can't put this node on a curve or as a switch.
  • This node is an active component.

Environments

Each active component is assigned to an environment. This is where all data are held. Components in different environments can't interfere with each other.

Note: the Environments and Coding guide sections also apply to the LuaAutomation operation panel.

Creating an environment

Main article: /env_create

An environment is created by using /env_create. We pass to this command the name of the environment to create. While this name may contain whitespaces and symbols, it is highly recommended that you use only uppercase, lowercase letters and underscores.

Setting up an environment

Main article: /env_setup

You've created your first LuaATC environment! If you execute /env_setup <your_env_name> in the chat window, you get a formspec like this:

It allows you to edit your environment initialization code.

  • The button “Run InitCode” runs immediately the initialization code.
  • The button “Clear S” removes all elements from the S table.
  • The button “Save” saves the initialization code for the current environment.
  • The button “Delete Env.” is to delete your environment. This may happen when you accidentally created the environment or you no longer need it. You will be asked to confirm by typing YES (in uppercase) into a second formspec. Once it is deleted, all data associated to the environment is lost and can't be recovered.

When the init code fails to execute, the F table is restored to previous state.

More information on how to use that initialization code to do amazing things is given below.

Coding guide

Predefined global variables

The following global variables are available inside a LuaAutomation ATC rail:

S

A table shared between all components of an environment. Its contents are persistent over server restarts. Any value is allowed, except functions:

Do not store functions in this table. Calling them from another component may work, but they will be discarded on server shutdown and this may lead to unexpected results.

F

A table shared between all components of an environment. Its contents are discarded on server shutdown or when the init code gets re-run. Any value is allowed, even functions.

This table is not made to store data, but to provide static value and function definitions. This table should be populated by the initialization code.

Available Lua functions

The standard Lua globals are available in the LuaATC environment:

  • string
  • math
  • table
  • os

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”. This is because they can be controlled passively by LuaATC (and by other means). From LuaATC, this happens via a “state” string. The states are as follows:

Switch:
  "st" - turnout is set to the straight branch
  "cr" - turnout is set to the diverting (curved) branch
Signal: (simple signals, wall signals)
  "red" - the signal is red
  "green" - the signal is green
Mesecon Switch, Andrew's Cross:
  "off" - switch is off, Andrew's cross does not blink
  "on" - switch is on, Andrew's cross blinks and bell rings
getstate(pos)

Gets the state of a passive component at position pos. The returned states are component-specific, as described above.

setstate(pos, new_state)

Sets the state of a passive component at position pos to the value new_state. The returned states are component-specific, as described above.

is_passive(pos)

Checks whether there is a passive component at position pos. If pos is a string, checks whether the passive component with the specified 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"
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.

interrupt_pos(pos, message)

Triggers immediately an ext_int event on the active component at pos (can't be a string). message can be of any Lua data type.

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 rwt.

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

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:
2019-01-01 15:00:00: WARNING[Server]: [advtrains]LuaAutomation ATC interface rail at (0,0,0) : LUA Error: …ds/advtrains/advtrains_luaautomation/environment.lua:168: There's no signal at (0,0,0)
  • pos is a string, and the named passive component does not exist:
2019-01-01 15:00:00: WARNING[Server]: [advtrains]LuaAutomation ATC interface rail at (0,0,0) : LUA Error: …/mods/advtrains/advtrains_luaautomation/pcnaming.lua:22: Invalid position supplied to ???: “invalid_pcnaming”
  • the specified route does not exist:
2019-01-01 15:00:00: WARNING[Server]: [advtrains]LuaAutomation ATC interface rail at (0,0,0) : LUA Error: …ds/advtrains/advtrains_luaautomation/environment.lua:185: 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.

cancel_route(pos, route_name)

Cancels the route designated by route_name 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.

Events

In a LuaAutomation ATC controller, an event has the following format:

event = {
    type = "<type>",
    <type> = true,
    -- additional content
}

Trivia

The LuaAutomation ATC rail has the same texture as the ATC controller rail, but its functions are different.

usage/nodes/atc_rail.1573114812.txt.gz · Last modified: 2019-11-07 09:20 by orwell