Overview
The GrandMA2 console provides a Lua API for plugin development. The MA2 Plugins collection uses these core API functions to interact with the console’s show data, user interface, and command engine.
Command Execution
gma.cmd()
Executes GrandMA2 console commands from Lua code.
The console command to execute (e.g., “Store Preset 4.1”)
-- Execute a command
gma.cmd("Store Sequence 300")
gma.cmd("Label Sequence 300 \"A White\"")
gma.cmd("Group 1 At Gel 1.1")
gma.cmd("Store Preset 4.1")
-- Storing presets with options
cmd("Store Preset 4."..preset)
cmd("Label Preset 4."..preset.." \""..groups[group].." "..colSwatchBook[start].."\"")
-- Creating sequences and cues
cmd("Store Sequence "..seqCurrent.." /o")
cmd("Store Cue "..start.." Sequence "..seqCurrent)
-- Assigning executors
cmd("Assign Sequence "..seq.." At Executor "..executor)
cmd("Assign Exec "..PG_exec.." /restart=next /priority=htp /offtime=0.2")
-- Blind edit mode
cmd("BlindEdit On")
cmd("BlindEdit Off")
gma.textinput()
Prompts the user for text or numeric input via a dialog box.
The title shown in the input dialog
Default value shown in the input field
User’s input as a string, or nil if canceled
-- Get numeric input
local grp = text('Enter Group Number', PG_grp)
local amount = tonumber(text('Pulse Amount?', PG_amount))
-- Get boolean/string input
local white = text('White Bump Mode?', PG_white)
local batch = text("Batch mode? (true/false)", "false")
-- Collect multiple inputs
while true do
local t = text('Row '..loopct..' Group #', '[HIT ENTER W/O INPUT WHEN DONE]')
if tonumber(t) then
rows[loopct] = tonumber(t)
loopct = loopct + 1
elseif t == nil or t == '[HIT ENTER W/O INPUT WHEN DONE]' then
break
end
end
Console Feedback
gma.feedback()
Displays messages in the console’s command line feedback area.
The message to display to the user
-- Plugin loaded message
gma.feedback("Color Picker Update Plugin Loaded :DD")
-- Status updates
fb("--- Presets Deleted ---")
fb("--- Creating Cues")
fb("---Color Picker Started :DDD---")
fb("Setup done - creating wave sequence...")
-- Variable debugging
fb(PG_grp..PG_seq..PG_amount..PG_wing..PG_trigTime..PG_fade)
Timing Control
gma.sleep()
Pauses script execution for a specified duration.
Number of seconds to pause (supports decimals)
-- Short pause for command processing
gma.sleep(0.1)
gma.sleep(0.05)
-- Macro execution delays
sleep(0.5)
cmd("Go Macro ALLWHITE")
sleep(0.5)
cmd("Go Macro ALLRED")
-- Reduce CPU load in loops
for i = 1, count do
-- processing
gma.sleep(sleepPeriod)
end
Show Data Access
gma.show.getobj.handle()
Retrieves a handle to a show object for further manipulation.
Object reference (e.g., “Preset 4.1”, “Sequence 300”)
Handle to the object, or nil if not found
local getHandle = gma.show.getobj.handle
-- Check if object exists
local handle = getHandle("Preset 4."..presetNum)
if handle then
-- Object exists
end
gma.show.getobj.class()
Returns the class type of a show object.
function getClass(str)
return gma.show.getobj.class(getHandle(str))
end
-- Check if pool space is occupied
if getClass(poolType..' '..tostring(i)) then
-- Space is not empty
end
gma.show.getvar()
Retrieves GrandMA2 system variables.
System variable name (e.g., “PATH”, “PLUGINPATH”, “version”)
-- Get show file path
local path = gma.show.getvar('PATH')
local directory = path..'/'..'importexport'..'/'
-- Get plugin directory
local pluginDir = gma.show.getvar('PLUGINPATH')..'/'
-- Version detection
local version = gma.show.getvar('version')
if version:find('3.1.2') == 1 then
-- Version-specific handling
end
Progress Indication
gma.gui.progress.start()
Creates and displays a progress bar.
Title shown in the progress bar
Handle to the progress bar for further operations
PWG_progressHandle = gma.gui.progress.start("Creating Wave Sequence")
gma.gui.progress.setrange()
Sets the minimum and maximum values for the progress bar.
Progress bar handle from start()
Minimum value (usually 0 or 1)
gma.gui.progress.setrange(PWG_progressHandle, 1, totalPairs)
gma.gui.progress.setrange(pBars.main.handle, 0, timeCt)
gma.gui.progress.set()
Updates the current progress value.
for i = 1, totalPairs do
gma.gui.progress.set(PWG_progressHandle, i)
-- processing
end
gma.gui.progress.settext()
Updates the descriptive text shown in the progress bar.
gma.gui.progress.settext(PWG_progressHandle, "Cue pair " .. i .. " of " .. totalPairs)
gma.gui.progress.settext(PWG_progressHandle, "Adding G" .. grp .. " to Full cue")
gma.gui.progress.stop()
Closes and removes the progress bar.
Progress bar handle to stop
gma.gui.progress.stop(PWG_progressHandle)
PWG_progressHandle = nil
Best Practices
Always alias frequently-used API functions to local variables at the top of your plugin for better performance:local text = gma.textinput
local cmd = gma.cmd
local fb = gma.feedback
local getHandle = gma.show.getobj.handle
When building command strings with user input, always escape quotes properly:cmd('Label Preset 0.'..presetCurrent..' "'..timeList[i]..'s '..directionNames[loop]..'"')
Use gma.sleep() judiciously in loops to prevent CPU overload, especially when processing large amounts of data:for i = 1, #groups do
-- processing
gma.sleep(0.05) -- Reduce CPU load
end