techpack/smartline/api.md

99 lines
3.2 KiB
Markdown
Raw Normal View History

2018-03-10 22:14:57 +01:00
# SmartLine Controller API
The SmartLine Controller provides the following API to register additional condition and action commands from other mods:
* smartline.register_condition(name, condition definition)
* smartline.register_action(name, action definition)
Each registered condition and action has the function `on_execute` which is called for each rule (every second).
* The condition function has to return true or false, depending if the condition is true or not.
* The action function has to execute the defined action.
In addition each registered condition and action has the function `button_label`, which determines the button label
for the Controller main formspec. Please note that the maximum number of visible characters for the button label is
something about 15.
See `commands.lua` as reference. All predefined SmartLine Controller commands are registered via `commands.lua`.
## Prototypes
```LUA
2018-03-19 19:12:00 +01:00
smartline.register_condition(name, {
2018-03-10 22:14:57 +01:00
title = "my condition",
formspec = {},
2018-03-19 19:12:00 +01:00
on_execute = function(data, environ)
2018-03-10 22:14:57 +01:00
-- data: table with the formspec data
2018-03-19 19:12:00 +01:00
-- environ: not relevant here
2018-03-10 22:14:57 +01:00
end,
button_label = function(data)
return "button label"
end,
})
```
```LUA
smartline.register_action(name, {
title = "my action",
formspec = {},
2018-03-19 19:12:00 +01:00
on_execute = function(data, environ, inputs)
2018-03-10 22:14:57 +01:00
-- data: table with the formspec data
2018-03-19 19:12:00 +01:00
-- environ: not relevant here
2018-03-10 22:14:57 +01:00
-- inputs: table with the input values
end,
button_label = function(data)
return "button label"
end,
})
```
2018-03-19 19:12:00 +01:00
The 'name' parameter should be unique. External mods should use the mod name as prefix, like "mymod_mycond".
2018-03-10 22:14:57 +01:00
The 'title' is used in the main menu for the condition and action selection dialog.
The 'formspec' table defines the condition/action related form for additional user parameters.
It supports the following subset of the minetest formspec elements:
- textlist
- field
- label
Please note that size and position is automatically determined.
All other attributes are according to the original formspec.
Example:
```LUA
formspec = {
{
type = "field", -- formspec element
name = "number", -- reference key for the table 'data'
label = "input from node with number", -- label shown above of the element
default = "", -- default value
},
{
type = "textlist", -- formspec element
name = "value", -- reference key for the table 'data'
label = "is", -- label shown above of the element
choices = "on,off", -- list elements
default = 1, -- first list element as default value
},
{
type = "label",
2018-03-19 19:12:00 +01:00
name = "lbl", -- not really used, but internally needed
2018-03-10 22:14:57 +01:00
label = "Hint: Connect the input nodes with the controller",
},
}
```
The table 'data' includes the condition/action related 'formspec' data.
For the above 'formspec' example, it is:
```LUA
data = {
number = <string>, -- the entered value of the "field",
value = <number>, -- the number of the selected element of the "textlist"
value_text = <string>, -- in addition the text of the selected element of the "textlist"
}
```