src/client


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

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

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

## Components and Events

### Components
Atlac components introduce automation-capable components that fall within two categories:
 - Active Components are components that are able to run Lua code, triggered by specific events.
 - Passive Components can't perform actions themselves. Their state can be read and set by active components or manually by the player.
 

## Functions and Variables

### Events
The event table is a variable created locally by the component being triggered. It is a table with the following format:
```lua
event = {
	type = "<event type>",
	<event type> = true,
	--additional event-specific content
}
```
You can check the event type by using the following:
```lua 
if event.type == "wanted" then
	--do stuff
end
```
or
```lua
if event.wanted then
	--do stuff
end
````
where `wanted` is the event type to check for.  
See the "Active Components" section below for details on the various event types as not all of them are applicable to all components.

### 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. *Not available in init code.*

 - `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_**.

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

#### 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)`
Requests the given route from the signal at pos. Has the same effect as clicking "Set Route" in the signalling dialog.

 - `cancel_route(pos)`
Cancels the route that is set from the signal at pos. Has the same effect as clicking "Cancel Route" in the signalling dialog.

 - `get_aspect(pos)`
Returns the signal aspect of the signal at pos. A signal aspect has the following format:
```lua
asp = {
	main = <int speed>,
		-- Main signal aspect, tells state and permitted speed of next section
		-- 0 = section is blocked
		-- >0 = section is free, speed limit is this value
		-- -1 = section is free, maximum speed permitted
		-- false = Signal doesn't provide main signal information, retain current speed limit.
	shunt = <boolean>,
		-- Whether train may proceed as shunt move, on sight
		-- main aspect takes precedence over this
		-- When main==0, train switches to shunt move and is restricted to speed 8
	proceed_as_main = <boolean>,
		-- If an approaching train is a shunt move and 'shunt' is false,
		-- the train may proceed as a train move under the "main" aspect
		-- if the main aspect permits it (i.e. main!=0)
		-- If this is not set, shunt moves are NOT allowed to switch to
		-- a train move, and must stop even if "main" would permit passing.
		-- This is intended to be used for "Halt for shunt moves" signs.
	
	dst = <int speed>,
		-- Distant signal aspect, tells state and permitted speed of the section after next section
		-- The character of these information is purely informational
		-- At this time, this field is not actively used
		-- 0 = section is blocked
		-- >0 = section is free, speed limit is this value
		-- -1 = section is free, maximum speed permitted
		-- false = Signal doesn't provide distant signal information.
	
	-- the character of call_on and dead_end is purely informative
	call_on = <boolean>, -- Call-on route, expect train in track ahead (not implemented yet)
	dead_end = <boolean>, -- Route ends on a dead end (e.g. bumper) (not implemented yet)

	w_speed = <integer>,
	-- "Warning speed restriction". Supposed for short-term speed
	-- restrictions which always override any other restrictions
	-- imposed by "speed" fields, until lifted by a value of -1
	-- (Example: german Langsamfahrstellen-Signale)
}
```
As of January 2020, the 'dst', 'call_on' and 'dead_end' fields are not used.

# Lines

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 an event of type {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)

## Components and events

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
Mode	Name	Size
-rw-r--r--	CMakeLists.txt	1140	log plain
-rw-r--r--	clientevent.h	3195	log plain
-rw-r--r--	clientlauncher.cpp	17208	log plain
-rw-r--r--	clientlauncher.h	2096	log plain
-rw-r--r--	event_manager.h	2255	log plain
-rw-r--r--	gameui.cpp	9688	log plain
-rw-r--r--	gameui.h	3044	log plain
-rw-r--r--	hud.cpp	25480	log plain
-rw-r--r--	hud.h	3645	log plain
-rw-r--r--	inputhandler.cpp	7929	log plain
-rw-r--r--	inputhandler.h	9479	log plain
-rw-r--r--	joystick_controller.cpp	7448	log plain
-rw-r--r--	joystick_controller.h	3818	log plain
-rw-r--r--	keys.h	1873	log plain
d---------	meshgen	80	log plain
d---------	render	612	log plain
-rw-r--r--	renderingengine.cpp	16180	log plain
-rw-r--r--	renderingengine.h	4676	log plain
-rw-r--r--	sound.cpp	880	log plain
-rw-r--r--	sound.h	3597	log plain
-rw-r--r--	sound_openal.cpp	17580	log plain
-rw-r--r--	sound_openal.h	1114	log plain
-rw-r--r--	tile.cpp	68522	log plain
-rw-r--r--	tile.h	9629	log plain