This mod offers components that run LUA code and interface with each other through a global environment. It makes complex automated railway systems possible. The mod is sometimes abbreviated as 'atlatc'. This stands for AdvTrainsLuaATC. This short name has been chosen for user convenience, since the name of this mod ('advtrains_luaautomation') is very long.
To perform any operations using this mod (except executing operation panels), players need the "atlatc" privilege.
This privilege should never be granted to anyone except trusted administrators. Even though the LUA environment is sandboxed, it is still possible to DoS the server by coding infinite loops or requesting expotentially growing interrupts.
Each active component is assigned to an environment where all atlac data is held. Components in different environments can't inferface with each other.
Create environment with the given name. To be able to do anything, you first need to create an environment. Choose the name wisely, you can't change it afterwards without deleting the environment and starting again.
Invoke the form to edit the environment's initialization code. For more information, see the section on active components. You can also delete an environment from here.
The variable 'S' contains a table which is shared between all components of the environment. Its contents are persistent over server restarts. May not contain functions, every other value is allowed.
The variable 'F' also contains a table which is shared between all components of the environment. Its contents are discarded on server shutdown or when the init code gets re-run. Every data type is allowed, even functions.
The purpose of this table is not to save data, but to provide static value and function definitions. The table should be populated by the init code.
Cause LuaAutomation to trigger an `int` event on this component after the given time in seconds with the specified `message` field. `message` can be of any Lua data type. *Not available in init code.*
Immediately trigger an `ext_int` event on the active component at position pos. `message` is like in interrupt(). Use with care, or better **_don't use_**! Incorrect use can result in **_expotential growth of interrupts_**.
The event table is a table of the following format:
{
type = "<type>",
<type> = true,
... additional content ...
}
You can check for the event type by either using
if event.type == "wanted" then ...do stuff... end
or
if event.wanted then ...do stuff... end
(if 'wanted' is the event type to check for)
# Init code
The initialization code is not a component as such, but rather a part of the whole environment. It can (and should) be used to make definitions that other components can refer to.
Examples:
A function to define behavior for trains in subway stations:
function F.station()
if event.train then atc_send("B0WOL") end
if event.int and event.message="depart" then atc_send("OCD1SM") end
The init code is run whenever the F table needs to be refilled with data. This is the case on server startup and whenever the init code is changed and you choose to run it.
Functions are run in the environment of the currently active node, regardless of where they were defined. So, the 'event' table always reflects the state of the calling node.
The 'event' table of the init code is always {type="init", init=true}.
Sends the specified ATC command to the train (a string) and returns true. If there is no train, returns false and does nothing. See [atc_command.txt](../atc_command.txt) for the ATC command syntax.
If the first digit of this string is a number (0-9), any subway wagons on the train (from advtrains_train_subway) will have this one displayed as line number
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 and/or locomotive:
- `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.
Example: train has wagons `"foo","foo","foo","bar","bar","bar"`
Command: `split_at_index(4,"S0")`
Result: first train (continues at previous speed): `"foo","foo","foo"`, second train (slows at S0): `"bar","bar","bar"`
- `split_at_fc(atc_command, len)`
Splits the train in such a way that all cars with non-empty current FC of the first part of the train have the same FC. The
`atc_command` specified is sent to the rear part, as with split_at_index. It returns the fc of the cars of the first part.
Example : Train has current FCs `"" "" "bar" "foo" "bar"`
Command: `split_at_fc(<atc_command>)`
Result: `train "" "" "bar"` and `train "foo" "bar"`
The function returns `"bar"` in this case.
The optional argument `len` specifies the maximum length for the
first part of the train.
Example: Train has current FCs `"foo" "foo" "foo" "foo" "bar" "bar"`
Command: `split_at_fc(<atc_command>,3)`
Result: `"foo" "foo" "foo"` and `"foo" "bar" "bar"`
The LuaATC interface provides a way to hook into the approach callback system, which is for example used in the TSR rails (provided by advtrains_interlocking) or the station tracks (provided by advtrains_lines). However, for compatibility reasons, this behavior needs to be explicitly enabled.
Enabling the receiving of approach events works by setting a variable in the local environment of the ATC rail, by inserting the following code:
__approach_callback_mode = 1
-- to receive approach callbacks only in arrow direction
-- or alternatively
__approach_callback_mode = 2
-- to receive approach callbacks in both directions
The following event will be emitted when a train approaches:
{type="approach", approach=true, id="<train_id>"}
Please note these important considerations when using approach callbacks:
- Approach events might be generated multiple times for the same approaching train. If you are using atc_set_lzb_tsr(), you need to call this function on every run of the approach callback, even if you issued it before for the same train.
- A reference to the train is available while executing this event, so that functions such as atc_send() or atc_set_text_outside() can be called. On any consecutive interrupts, that reference will no longer be available until the train enters the track ("train" event)
- Unlike all other callbacks, approach callbacks are executed synchronous during the train step. This may cause unexpected side effects when performing certain actions (such as switching turnouts, setting signals/routes) from inside such a callback. I strongly encourage you to only run things that are absolutely necessary at this point in time, and defer anything else to an interrupt(). Be aware that certain things might trigger unexpected behavior.
Operations that are safe to execute in approach callbacks:
- anything related only to the global environment (setting things in S)
- digiline_send()
- atc_set_text_*()
- atc_set_lzb_tsr() (see below)
In the context of approach callbacks, one more function is available:
atc_set_lzb_tsr(speed)
Impose a Temporary Speed Restriction at the location of this rail, making the train pass this rail at the specified speed. (Causes the same behavior as the TSR rail)
The advtrains_line_automation component adds a few contraptions that should make creating timeable systems easier.
Part of its functionality is also available in LuaATC:
- `rwt.*`
All Railway Time functions are included as documented in https://advtrains.de/wiki/doku.php?id=dev:lines:rwt
- `schedule(rw_time, msg)`
- `schedule_in(rw_dtime, msg)`
Schedules the following event `{type="schedule", schedule=true, msg=msg}` at (resp. after) the specified railway time (which can be in any format). You can only schedule one event this way. Uses the new lines-internal scheduler.
#### Operator panel
This simple node executes its actions when punched. It can be used to change a switch and update the corresponding signals or similar applications. It can also be connected to by the`digilines` mod.
The event fired is `{type="punch", punch=true}` by default. In case of an interrupt or a digiline message, the events are similar to the ones of the ATC rail.
#### Init code
The initialization code is not a component as such, but rather a part of the whole environment. It can (and should) be used to make definitions that other components can refer to.
A basic example function to define behavior for trains in stations:
```lua
function F.station(station_name)
if event.train then
atc_send("B0WOL")
atc_set_text_inside(station_name)
interrupt(10,"depart")
end
if event.int and event.message="depart" then
atc_set_text_inside("") --an empty string clears the displayed text
atc_send("OCD1SM")
end
end
````
The corresponding Lua ATC Rail(s) would then contain the following or similar:
The init code is run whenever the F table needs to be refilled with data. This is the case on server startup and whenever the init code is changed and you choose to run it.
The event table of the init code is always `{type="init", init=true}` and can not be anything else.
Functions are run in the environment of the currently active node, regardless of where they were defined.
The red/green light signals `advtrains:signal_on/off` are interfaceable. Others such as `advtrains:retrosignal_on/off` are not. If advtrains_interlocking is enabled, trains will obey the signal if the influence point is set.
The Mesecon switch can be switched using LuaAutomation. Note that this is not possible on levers or protected mesecon switches, only the unprotected full-node 'Switch' block `mesecons_switch:mesecon_switch_on/off`.
Use `setstate("Stn_P1_out", "green")` instead of `setstate(POS(1,2,3), "green")`
If `advtrains_interlocking` is enabled, PC-Naming can also be used to name interlocking signals for route setting via the `set_route()` functions.
**Important**: The "Signal Name" field in the signalling formspec is completely independent from PC-Naming and can't be used to look up the position. You need to explicitly use the PC-Naming tool.
