techpack/smartline/api.md

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

smartline.register_condition(name, {
	title = "my condition",
	formspec = {},
	on_execute = function(data, environ) 
	-- data:    table with the formspec data 
	-- environ: not relevant here
	end,
	button_label = function(data) 
	   return "button label"
	end,
})

smartline.register_action(name, {
	title = "my action",
	formspec = {},
	on_execute = function(data, environ, inputs) 
	-- data:    table with the formspec data 
	-- environ: not relevant here
	-- inputs:  table with the input values
	end,
	button_label = function(data) 
	   return "button label"
	end,
})

The 'name' parameter should be unique. External mods should use the mod name as prefix, like "mymod_mycond". 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:

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",
		name = "lbl",                            -- not really used, but internally needed
		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:

    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"
    }