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:
- math.floor
- math.abs
- math.max
- math.min
- math.random
- tonumber
- tostring
- unpack
- type
- string.byte
- string.char
- string.find
- string.format
- string.gmatch
- string.gsub
- string.len
- string.lower
- string.match
- string.rep
- string.sub
- string.upper
- string.split
- string.trim
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_ms_time()` - Returns time with millisecond precision
-`$time_as_str()` - Read the time of day (ingame) as text string in 24h format, like "18:45"
-`$time_as_num()` - Read the time of day (ingame) as integer number in 24h format, like 1845
-`$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 of the remote block, like "1234".
- A Player Detector with number "456" is configured to send on/off commands to the TA4 Lua Controller with number "345".
- The TA4 Lua Controller will receive these commands as input value.
- The program on the SaferLua Controller can always read the last input value from the Player Detector with number "456" by means of:
`sts = $get_input("456")`
### Techage Command Functions
*`$read_data(num, ident)` - Read any kind of data from another block with the given number _num_. _ident_ specifies the data to be read. The result is block dependent (see table below):
*`$send_cmnd(num, cmnd, data)` - Send a command to another block. _num_ is the number of the remote block, like "1234". _cmnd_ is the command, _data_ is additional data (see table below):
*`$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.
-`$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 are text strings or any other data. Incoming messages are stored in order (up to 10) and can be read one after the other.
*`$get_msg()` - Read a received message. The function returns the sender number and the message. (see example "Emails")
*`$send_msg(num, msg)` - Send a message to another Controller. _num_ is the destination number. (see example "Emails")
