Tutorial:Script interfaces

Script interfaces allow direct communication between simultaneously running scripts. This is done in form of defining a public interface with given functions. All the code regarding the interfaces communication is in the remote namespace.

Defining interfaces

The interface is defined as follows:

 -- assuming name and table_of_functions are defined elsewhere
 remote.add_interface(interface_name, table_of_functions)

 -- It is possible to define the name and table inside the call
 remote.add_interface("my_interface", {
   my_getter = function()
     -- you can return 1 or more variables from the script
     return "foo"
   end,
 
   -- the values can be only primitive type or (nested) tables
   my_setter = function(foo, bar)
     global.foo = foo
     global.bar = bar
   end
 })

The interface functions cannot take function pointers or function closures. Primitive types, LuaObjects and tables work just fine.

Calling interface functions

The interface can be used for calling functions from a different script.

Example (in the different script than the one above):

 -- calls the my_interface.my_getter from the script above and prints the returning value
 print(remote.call("my_interface", "my_getter"))
 -- remote call takes the name of the interface, name of the function and then variable amount of parameters
 remote.call("my_interface', "my_setter", 5, {bar=baz})

Discovering interfaces

The script can check for expected interfaces and its functions via the remote.interfaces table. This is a table indexed by interface names where the values are set of functions for particular interfaces.

Example:

 -- check whether there is the "my_interface" interface and whether it contains the "my_getter" function
 if remote.interfaces.my_interface and remote.interfaces.my_interface.my_getter then
   -- the remote call for the function is safe to use
 end

Custom input

Keybindings can also be created. First the keybinding has to be defined in the data stage:

local button={
    type = "custom-input",
    name = "my-custom-input",
    key_sequence = "SHIFT + G",
    consuming = "none"
}
data:extend{button}

Available options for "consuming" are:

• none: default if not defined
• game-only: Blocks game inputs using the same key sequence but lets other custom inputs using the same key sequence fire.
• script-only and all were removed in version 0.15

Locale definition:

[controls]
my-custom-input=Potato controls

And then it can be used runtime by subscribing to the event of the name of the custom input:

script.on_event("my-custom-input", function(event)
    game.print("Ran on tick: " .. tostring(event.tick))
end)