# Advtrains - Lua Automation features

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 'LuaATC' or '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.

A probably more complete documentation of LuaATC is found on the [Advtrains Wiki](http://advtrains.de/wiki/doku.php?id=usage:atlatc:start)

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

## Environments

Each active component is assigned to an environment where all atlac data is held. Components in different environments can't inferface with each other.
This system allows multiple independent automation systems to run simultaneously without polluting each other's environment.

 - `/env_create <env_name>`:
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.

 - `/env_setup <env_name>`:
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.

 - `/env_subscribe <env_name>`, `/env_unsubscribe <env_name>`:
Subscribe or unsubscribe from log/error messages originating from this environment

 - `/env_subscriptions [env_name]`:
List your subscriptions or players subscribed to an environment.


## Functions and variables
### General Functions and Variables
The following standard Lua libraries are available:
 - `string`
 - `math`
 - `table`
 - `os`
 
The following standard Lua functions are available:
 - `assert`
 - `error`
 - `ipairs`
 - `pairs`
 - `next`
 - `select`
 - `tonumber`
 - `tostring`
 - `type`
 - `unpack`

Any attempt to overwrite the predefined values results in an error.

### LuaAutomation Global Variables
 - `S`
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.

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

### LuaAutomation Global Functions
> Note: in the following functions, all parameters named `pos` designate a position. You can use the following:  
> - a default Minetest position vector (eg. {x=34, y=2, z=-18})  
> - the POS(34,2,-18) shorthand below.  
> - A string, the passive component name. See 'passive component naming'. 
  


 - `POS(x,y,z)`
Shorthand function to create a position vector {x=?, y=?, z=?} with less characters.

 - `getstate(pos)`
Get the state of the passive component at position `pos`.

 - `setstate(pos, newstate)`
Set the state of the passive component at position `pos`.

 - `is_passive(pos)`
Checks whether there is a passive component at the position pos (and/or whether a passive component with this name exists)

 - `interrupt(time, message)`
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. Returns true. *Not available in init code.*

 - `interrupt_safe(time, message)`
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)`
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_**.

 - `clear_interrupts()`
Removes any pending interrupts of this node.

 - `digiline_send(channel, message)`
Make this active component send a digiline message on the specified channel.
Not available in init code.

 - `atc_send_to_train(<train_id>, <atc_command>)`
	Sends the specified ATC command to the train specified by its train id. This happens regardless of where the train is in the world, and can be used to remote-control trains. Returns true on success. If the train ID does not exist, returns false and does nothing. See [atc_command.txt](../atc_command.txt) for the ATC command syntax.

#### Interlocking Route Management Functions
If `advtrains_interlocking` is enabled, the following aditional functions can be used:

 - `can_set_route(pos, route_name)`
Returns whether it is possible to set the route designated by route_name from the signal at pos.

 - `set_route(pos, route_name)`