But to write Lua scripts, some knowledge with the programming language Lua is required.
Minetest uses Lua 5.1. The reference document for Lua 5.1 is [here](https://www.lua.org/manual/5.1/). The book [Programming in Lua (first edition)](https://www.lua.org/pil/contents.html) is also a perfect source for learning Lua.
The Server block is used to store data from Lua Controllers nonvolatile. It can also be used for communication purposes between several Lua Controllers.
Only configured players have access to the server. Therefore, the server has a menu to enter player names.
The controller uses a subset of the language Lua, called SaferLua. It allows the safe and secure execution of Lua scripts, but has the following limitations:
- limited code length
- limited execution time
- limited memory use
- limited possibilities to call functions
SaferLua follows the standard Lua syntax with the following restrictions:
- no `while` or `repeat` loops (to prevent endless loops)
- no table constructor {..}, see "Arrays, Stores, and Sets" for comfortable alternatives
- limited runtime environment
SaferLua directly supports the following standard functions:
For own function definitions, the menu tab 'func' can be used. Here you write your functions like:
```lua
function foo(a, b)
return a + b
end
```
Each SaferLua program has access to the following system variables:
- ticks - a counter which increments by one each call of `loop()`
- elapsed - the amount of seconds since the last call of `loop()`
- event - a boolean flag (true/false) to signal the execution of `loop()` based on an occurred event
### Arrays, Stores, and Sets
It is not possible to easily control the memory usage of a Lua table at runtime. Therefore, Lua tables can't be used for SaferLua programs. Because of this, there are the following alternatives, which are secure shells over the Lua table type:
#### Arrays
_Arrays_ are lists of elements, which can be addressed by means of an index. An index must be an integer number. The first element in an _array_ has the index value 1. _Arrays_ have the following methods:
Unlike _arrays_, which are indexed by a range of numbers, _stores_ are indexed by keys, which can be a string or a number. The main operations on a _store_ are storing a value with some key and extracting the value given the key.
- keys(order) - return an _array_ with the keys. If _order_ is `"up"` or `"down"`, return the keys as sorted _array_, in order of the _store_ values.
Example:
```lua
s = Store("a", 4, "b", 5) --> {a = 4, b = 5}
s.set("val", 12) --> {a = 4, b = 5, val = 12}
s.get("val") --> returns 12
s.set(0, "hello") --> {a = 4, b = 5, val = 12, [0] = "hello"}
s.del("val") --> {a = 4, b = 5, [0] = "hello"}
s.size() --> function returns 3
s.memsize() --> function returns 9
for key,val in s.next() do
...
end
```
Keys sort example:
```lua
s = Store() --> {}
s.set("Joe", 800) --> {Joe=800}
s.set("Susi", 1000) --> {Joe=800, Susi=1000}
s.set("Tom", 60) --> {Joe=800, Susi=1000, Tom=60}
s.keys() --> {Joe, Susi, Tom}
s.keys("down") --> {Susi, Joe, Tom}
s.keys("up") --> {Tom, Joe, Susi}
```
#### Sets
A _set_ is an unordered collection with no duplicate elements. The basic use of a _set_ is to test if an element is in the _set_, e.g. if a player name is stored in the _set_.
The _set_ has the following methods:
- add(val) - add a value to the _set_
- del(val) - delete a value from the _set_
- has(val) - test if value is stored in the _set_
- size() - return the number of _set_ elements
- memsize() - return the needed _set_ memory space
All three types of data structures allow nested elements, e.g. you can store a _set_ in a _store_ or an _array_ and so on. But note that the overall size over all data structures can't exceed the predefined limit. This value is configurable for the server admin. The default value is 1000.
The configured limit can be determined via `memsize()`:
The TA4 Lua Controller distinguishes between the initialization phase (just after the controller was started) and the continuous operational phase, in which the normal code is executed.
During the initialization phase the function `init()` is executed once. The `init()` function is typically used to initialize variables, clean the display, or reset other blocks:
If an event occurs (a command was received from another block), the `loop()` is executed (in addition to the normal loop cycle). In this case the system variable 'event' is set:
-`$print(text)` - Output a text string on the 'outp' tab of the controller menu.
E.g.: `$print("Hello "..name)`
-`$loopcycle(seconds)` - This function allows to change the call frequency of the controller loop() function, witch is per default one second. For more info, see "Cyclic Task"
-`$events(bool)` - Enable/disable event handling. For more info, see "Events"
-`$get_input(num)` - Read an input value provided by an external block with the given number _num_. The block has to be configured with the number of the controller to be able to send status messages (on/off commands) to the controller. _num_ is the number (data type string) of the remote block, like "1234".
| "state" | one of: "running", "stopped", "blocked", "standby", "fault", or "unloaded" | Techage machine state, used by many machines |
| "state" | one of: "red", "amber", "green", "off" | Signal Tower state |
| "state" | one of: "empty", "loaded", "full" | State of a chest or Sensor Chest |
| "state" | one of: "on", "off" | State of a TA4 Button |
| "fuel" | number | fuel value of a fuel consuming block |
| "depth" | number | Read the current depth value of a quarry block (1..80) |
| "load" | number | Read the load value in percent (0..100) of a accu, or battery block. |
| "load" | number | Read the load value in percent (0..100) of a tank or silo. <br/>Silo and tank return two values: <br/>The percentage value and the absolute value in units.<br/> Example: percent, absolute = $send_cmnd("223", "load") |
| "load" | number | Read the grid storage amount (state of charge) in percent (0..100) from a TA3 Power Terminal. |
| "delivered" | number | Read the current delivered power value of a generator block. A power consuming block (accu) provides a negative value |
| "flowrate" | Total flow rate in liquid units | Only for TA4 Pumps |
| "action" | player-name, action-string | Only for Sensor Chests |
| "stacks" | Array with up to 4 Stores with the inventory content (see example) | Only for Sensor Chests |
| "count" | number | Read the item counter of the TA4 Item Detector block |
| "count" | number of items | Read the total amount of TA4 chest items. An optional number as `add_data` is used to address only one inventory slot (1..8, from left to right). |
| "count" | number of items | Read the number of pushed items for a TA4 Pusher in "flow limiter" mode |
| "count" | number of units | Read the number of pumped liquid units for a TA4 Pump in "flow limiter" mode |
| "itemstring" | item string of the given slot | Specific command for the TA4 8x2000 Chest to read the item type (technical name) of one chest slot, specified via `add_data` (1..8).<br/>Example: s = $send_cmnd("223", "itemstring", 1) |
| "output" | recipe output string, <br/>e.g.: "default:glass" | Only for the Industrial Furnace. If no recipe is active, the command returns "unknown" |
| "input" | \<index> | Read a recipe from the TA4 Recipe Block. `<index>` is the number of the recipe. The block return a list of recipe items. |
| "name" | \<player name> | Player name of the TA3/TA4 Player Detector or TA4 Button |
| "time" | number | Time in system ticks (norm. 100 ms) when the TA4 Button is clicked |
| "consumption" | number | TA4 Electric Meter: Amount of electrical energy passed through |
| "countdown" | number | TA4 Electric Meter: Countdown value for the amount of electrical energy passed through |
| "current" | number | TA4 Electric Meter: Current flow of electricity (current) |
| "limit" | number | Configure a TA4 Pusher with the number of items that are allowed to be pushed ("flow limiter" mode)<br/>limit = 0 turns off the "flow limiter" mode |
| "limit" | number | Configure a TA4 Pump with the number of liquid units that are allowed to be pumped ("flow limiter" mode)<br/>limit = 0 turns off the "flow limiter" mode |
| "exchange" | inventory slot number | TA3 Door Controller II (techage:ta3_doorcontroller2)<br/>Exchange a block<br/>*idx* is the inventory slot number (1..n) of/for the block to be exchanged |
| "set" | inventory slot number | TA3 Door Controller II (techage:ta3_doorcontroller2)<br/>Set/add a block<br/>*idx* is the inventory slot number (1..n) with the block to be set |
| "dig" | inventory slot number | TA3 Door Controller II (techage:ta3_doorcontroller2)<br/>Dig/remove a block<br/>*idx* is the empty inventory slot number (1..n) for the block |
| "move2" | x,y,z | TA4 Move Controller command to move the block(s) by the given<br/> x/y/z-distance. Valid ranges for x, y, and z are -100 to 100.<br/>Example: `$send_cmnd("1674", "move2", "0,4,0")` |
| "left" | nil | TA4 Turn Controller command to turn the block(s) to the left |
| "right" | nil | TA4 Turn Controller command to turn the block(s) to the right |
| "uturn" | nil | TA4 Turn Controller command to turn the block(s) 180 degrees |
| "recipe" | `<item_name>,<item_name>,...` | Set the TA4 Autocrafter recipe. <br/>Example for the torch recipe: `default:coal_lump,,,default:stick`<br/>Hint: Empty fields may only be left out at the end of the item list! |
| "recipe" | `<number>.<index>` | Set the TA4 Autocrafter recipe with a recipe from a TA4 Recipe Block.<br/>`<number>` is the TA4 Recipe Block number<br/>`<index>` is the number of the recipe in the TA4 Recipe Block |
| "goto" | `<slot>` | Start command for the TA4 Sequencer. `<slot>` is the time slot like `[1]` where the execution starts. |
| "stop" | nil | Stop command for the TA4 Sequencer. |
-`$server_write(num, key, value)` - Store a value on the server under the key _key_. _key_ must be a string. _value_ can be either a number, string, boolean, nil or data structure.
**This function does not allow nested data structures**.
Messages are used to transport data between Controllers. Messages can contain arbitrary data. Incoming messages are stored in order (up to 10) and can be read one after the other.
*`$get_msg([raw])` - Read a received message. The function returns the sender number as string and the message. (see example "Emails"). If the _raw_ parameter is not set or false, the message is guaranteed to be a string.
*`$send_msg(num, msg)` - Send a message to another Controller. _num_ is the destination number as string. (see example "Emails")
*`$display(num, row, text)` Send a text string to the display with number _num_. _row_ is the display row, a value from 1 to 5, or 0 to add the text string at the bottom (scroll screen mode). _text_ is the string to be displayed. If the first char of the string is a blank, the text will be horizontally centered.
*`$clear_screen(num)` Clear the screen of the display with number _num_.
*`$position(num)` Returns the position as string "'(x,y,z)" of the device with the given _num_.
For the `$get_input(...)` function, the Lua controller expects received `on`/`off` commands. However, the "TA4 4x Button" is not able to send an `on` command followed by an `off` command. To be able to receive commands from "TA4 4x Button", the `$get_msg()` function has to be used.
