Skip to main content

​
Installing MA2 Plugins

This guide walks you through installing Lua plugins on GrandMA2 consoles and onPC software. Plugins consist of two files that work together to extend console functionality.

​
Understanding Plugin Files

Each GrandMA2 plugin requires two files:

​
1. Lua Script File (.lua)

The Lua file contains the actual plugin code that executes on your console. For example, ColorPickerUpdate.lua contains all the logic for creating presets and sequences. 
-- MADE BY HUGO OTTH - 2025

-- Color Picker Update Plugin
gma.feedback("Color Picker Update Plugin Loaded :DD")

function ColorPickerUpdate_Start()
  fb("---Color Picker Started :DDD---")
  cmd("BlindEdit On")
  -- Plugin code here...
end

return ColorPickerUpdate_Start
The Lua file defines functions and returns the main entry point that GrandMA2 calls when you execute the plugin.

​
2. XML Definition File (.xml)

The XML file tells GrandMA2 about the plugin’s metadata and which Lua file to execute. 
<?xml version="1.0" encoding="utf-8"?>
<MA xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
    xmlns="http://schemas.malighting.de/grandma2/xml/MA" 
    xsi:schemaLocation="http://schemas.malighting.de/grandma2/xml/MA http://schemas.malighting.de/grandma2/xml/3.0.187/MA.xsd" 
    major_vers="3" minor_vers="0" stream_vers="187">
  <Info datetime="2024-10-16T12:00:00" showfile="lua" />
  <Plugin index="2" execute_on_load="0" luafile="ColorPickerUpdate.lua" name="Color Picker Update"/>
</MA>
Key XML Attributes:
  • index - Plugin slot number (each plugin needs a unique index)
  • execute_on_load - Set to 0 (manual execution) or 1 (auto-run when show loads)
  • luafile - Name of the corresponding .lua file
  • name - Display name shown in the plugin pool
Never set execute_on_load="1" unless you fully understand the plugin’s behavior. Auto-executing plugins can modify your show file immediately on load.

​
Installation Steps

1

Locate the Plugin Directory

Find your console’s plugin directory. The location varies by platform:On Console:
/grandMA2/gma2_V_X.X.X/plugins/
On Windows (onPC):
C:\ProgramData\MA Lighting Technologies\grandma\gma2_V_X.X.X\plugins\
On Mac (onPC):
~/MALightingTechnology/gma2/gma2_V_X.X.X/plugins/
Replace X.X.X with your software version number (e.g., 3.9.60).
You can also find the plugin path by typing cd plugins in the console command line.
2

Copy Both Files

For each plugin you want to install, copy both the .lua and .xml files to the plugin directory.Example for Color Picker Update:
  • Copy ColorPickerUpdate.lua
  • Copy ColorPickerUpdate.xml
Both files must have matching names (except for the extension) and be in the same directory.
3

Import the Plugin

From the GrandMA2 command line, import the plugin:
Import "ColorPickerUpdate.xml" At Plugin [index]
Replace [index] with your desired plugin slot number (e.g., 1, 2, 3).
Each plugin needs a unique index. If you’re installing multiple plugins, use different index numbers (1, 2, 3, etc.).
4

Verify Installation

Open the Plugin Pool window to verify your plugin appears:
  1. Press [View] → [Plugins]
  2. Look for your plugin name in the pool
  3. You should see the plugin with the name defined in the XML file
If the plugin appears, installation was successful!

​
Installing All Five Plugins

To install the complete plugin collection, repeat the process for each:
PluginFiles to CopyRecommended Index
Color Picker UpdateColorPickerUpdate.lua
ColorPickerUpdate.xml		1
Pulse GeneratorPulseGenerator.lua
PulseGenerator.xml		2
Pulse Wave GeneratorPulseWaveGen.lua
PulseWaveGen.xml		3
Flyout WidthFlyoutWidth.lua
FlyoutWidth.xml		4
Color Sweep UpdatePlugin_5_Update_COLOR_Sweeps.lua
Plugin_5_Update_COLOR_Sweeps.xml		5
Plugin indices are just organizational - use any numbers you prefer. Just ensure each plugin has a unique index.

​
Alternative: USB Import Method

If you prefer not to access the file system directly:
1

Prepare USB Drive

Create a folder on your USB drive and copy all plugin files (.lua and .xml pairs) into it.
2

Select USB Drive

On the console:
SelectDrive [USB drive number]
3

Import Each Plugin

Import each plugin from the USB:
Import "ColorPickerUpdate.xml" At Plugin 1
Import "PulseGenerator.xml" At Plugin 2
Import "PulseWaveGen.xml" At Plugin 3
Import "FlyoutWidth.xml" At Plugin 4
Import "Plugin_5_Update_COLOR_Sweeps.xml" At Plugin 5

​
Troubleshooting

​
Plugin Doesn’t Appear in Pool

  • Check file names: Ensure the luafile attribute in the XML matches the actual .lua filename exactly (case-sensitive)
  • Verify both files: Both .lua and .xml must be present in the plugin directory
  • Check XML syntax: Open the XML file and verify it’s properly formatted

​
”Lua File Not Found” Error

  • The XML file’s luafile attribute must match the actual filename
  • Both files must be in the same directory
  • Check for typos in filenames

​
Plugin Runs But Does Nothing

  • Check console feedback messages (command line feedback)
  • Ensure your show file has the required groups/objects the plugin expects
  • Verify console software version compatibility

​
Index Conflict

Plugin index already in use
Choose a different index number that’s not already occupied.

​
Version Compatibility

These plugins are tested on:
  • GrandMA2 software version 3.0.187 and higher
  • Color Sweep Update requires 3.2.2 or higher for optimal compatibility
Some features may not work on software versions below 3.0.187. Always update to the latest GrandMA2 software for best results.

​
What’s Next?

Now that your plugins are installed, try running your first plugin:

Quickstart Guide

Follow a step-by-step tutorial to run the Color Picker Update plugin and see how plugins work

​
Uninstalling Plugins

To remove a plugin:
  1. Delete the plugin from the pool: 
    Delete Plugin [index]
  2. Optionally, remove the files from the plugin directory to free up space.
Deleting a plugin doesn’t remove any presets, sequences, or other show data the plugin created. You’ll need to manually delete those if desired.

Build docs developers (and LLMs) love

Get started for freeTalk to us