Write a Plugin

Plugin structure

By Default, grandMA expects a .xml plugin file which references all the .lua components for the plugin. Most plugins will only require one LUA component but multiple is permitted.

The .xml and .lua files should be in the gma3_library/datapools/plugins directory of your MA installation:

macOS: ~/MALightingTechnology/...
Windows: C:\ProgramData\MALightingTechnology\...
USB key: /grandMA3/...

Directorygma3_library/datapools/plugins
- DirectoryPluginTemplate
  - PluginTemplate.xml
  - PluginTemplate.lua
  - … (Other lua components)
- … Other plugin files

Plugin files

XML

<?xml version="1.0" encoding="UTF-8"?>
<GMA3 DataVersion="2.0.2.0">
  <UserPlugin Name="MyPlugin" Author="Alban Moreon" Version="0.0.0.0" Path="PluginTemplate">
    <ComponentLua Name="PluginTemplate" FileName="PluginTemplate.lua"/>
    <!-- <ComponentLua Name="OtherComponent" FileName="OtherComponent.lua"/> -->
  </UserPlugin>
</GMA3>

Lua

local pluginName    = select(1,...)
local componentName = select(2,...)
local signalTable   = select(3,...)
local my_handle     = select(4,...)

-- Minimal example of plugin structure


-- Parameters
local DEBUG_FILE = true


-- Helpers
local function Debugf(...)
    if DEBUG_FILE then
        Echo(...)
    end
end


-- Main Entrypoint of plugin
--  Called when `Call Plugin X` is run or Pool object is clicked
function Main(display_handle, args)
    Printf(pluginName .. ": Main")
    Debugf("Hello from %s", componentName)
    if args ~= nil then
        Debugf("Arguments: %s", args)
    end

    Debugf("ToAddr: " .. handle:ToAddr())
    Debugf("Addr:   " .. handle:Addr())

    ErrPrintf("This is an error")
end


-- Called after the Main function returns
function Cleanup()
    Printf(pluginName .. ": Cleaning up")
end


-- Called when plugin is run with `Go+ Plugin X`
function Execute(type, ...)
    Printf(pluginName .. ": Executed")
    Debugf(type .. ": " .. ...)
end



-- Export plugin functions
return Main, Cleanup, Execute

Usage

When a plugin DataPool object is clicked or the Plugin X keyword is used, the first returned function from the module is called (called Main in the example file above).
If a Cleanup function is provided (2nd returned function), it will be executed after the Main function is run.
If the plugin is called with any Action keyword, for example: Go+ Plugin X or On Plugin X, the third returned function (called Execute in the example file above) is run.

Arguments

Any arguments can be passed to the plugin:

Plugin "PluginTemplate" "<args>"

These arguments are only available in the Main function.

Lua version

The LUA version of the grandMA3 LUA Engine is 5.4.

LUA 5.4.4 (grandMA3 <= v2.0)
LUA 5.4.6 (grandMA3 >= v2.1)