Skip to main content

​
Quickstart Tutorial

This tutorial walks you through running your first MA2 plugin using Color Picker Update as an example. You’ll learn how to execute plugins, understand their behavior, and verify results.
Before starting, make sure you’ve installed the plugins on your console.

​
What You’ll Build

By the end of this tutorial, you’ll have:
  • ✅ Created 77 color presets (11 colors × 7 groups)
  • ✅ Generated 7 sequences with color cues
  • ✅ Assigned sequences to executors on page 100
  • ✅ Automated color selection for fixture groups A through G

​
Prerequisites

1

Create Fixture Groups

The Color Picker Update plugin expects groups 1-7 to exist in your show file. Create at least one group:
Group 1 Thru 10
Store Group 1
Label Group 1 "A"
The plugin will create presets for groups 1-7. If you don’t have all 7 groups, the plugin will still work but only create presets for existing groups.
2

Verify Plugin Installation

Open the Plugin Pool and confirm “Color Picker Update” appears:
  1. Press [View] → [Plugins]
  2. Locate “Color Picker Update” in the pool

​
Running the Plugin

1

Execute the Plugin

From the command line, execute the plugin:
Plugin "Color Picker Update"
Or click the plugin in the Plugin Pool window.You’ll immediately see feedback in the command line:
Color Picker Update Plugin Loaded :DD
---Color Picker Started :DDD---
2

Watch the Progress

The plugin runs in Blind Edit mode and provides status updates:
--- Presets Deleted ---
--- Sequences Deleted ---
--- Presets Created ---
--- Sequences Created ---
--- Cues Created ---
--- Color Picker Update Done---
Blind Edit mode ensures the plugin doesn’t affect your live output while it’s creating presets and sequences.
3

Observe the Demo Sequence

After completion, the plugin runs a demonstration sequence by triggering macros:
cmd("Go Macro ALLWHITE")
sleep(0.5)
cmd("Go Macro ALLRED")
sleep(0.5)
cmd("Go Macro ALLYELLOW")
sleep(0.5)
cmd("Go Macro ALLGREEN")
sleep(0.5)
cmd("Go Macro ALLBLUE")
sleep(0.5)
cmd("Go Macro ALLPINK")
You’ll see colors cycle through white → red → yellow → green → blue → pink → red.
This demo assumes macros named ALLWHITE, ALLRED, etc. exist. If they don’t, you’ll see error messages but the plugin still created all presets successfully.

​
Understanding What Happened

Let’s explore the plugin’s workflow by examining the code:

​
1. Configuration Variables

The plugin starts with configuration: 
local groups = {"A", "B", "C", "D", "E", "F", "G"}
local grpStart = 1
local presetStart = 1
local presetWidth = 16
local execPage = 100
local execStart = 101
local seqStart = 300
  • groups: Labels for the 7 groups (A-G)
  • presetStart: Starting preset number (1)
  • presetWidth: Spacing between group preset banks (16)
  • seqStart: Starting sequence number (300)

​
2. Color Swatch Selection

local colNb = 11
local colSwatchBook = {"White", "Red", "Orange", "Yellow", "Green", 
                       "Cyan", "Lavender", "Blue", "Violet", "Magenta", "Pink"}
local colSwatchIndex = {1, 2, 3, 4, 6, 8, 9, 10, 11, 12, 13}
The plugin uses 11 colors from GrandMA2’s gel library (swatch book 1). The colSwatchIndex maps to specific gel colors.

​
3. Preset Creation

for group=grpStart, #groups do
  local presetCurrent = presetStart + ((group-1)* presetWidth)
  
  for start=1,colNb do
    local preset = presetCurrent+start-1
    cmd("Group "..group.." At Gel 1."..colSwatchIndex[start])
    cmd("Store Preset 4."..preset)
    cmd("Label Preset 4."..preset.." \""..groups[group].." "..colSwatchBook[start].."\"")
  end
end
What this does:
  • For each group (1-7), creates 11 color presets
  • Uses gel swatch colors from the library
  • Stores in preset pool 4 (Color)
  • Labels presets like “A White”, “A Red”, “B White”, etc.
Result: Presets 4.1-4.11 for Group 1, 4.17-4.27 for Group 2, and so on.

​
4. Sequence and Cue Creation

for group=grpStart, #groups do
  local presetCurrent = presetStart + ((group-1)* presetWidth)
  for start=1, colNb do
    local preset = presetCurrent + start - 1
    local seqCurrent = seqStart + group - 1
    cmd("Group "..group.." At Preset 4."..preset)
    cmd("Store Cue "..start.." Sequence "..seqCurrent)
    cmd("Label Sequence "..seqCurrent.." Cue "..start.." \""..groups[group].." "..colSwatchBook[start].."\"")
  end
end
What this does:
  • Creates sequences 300-306 (one per group)
  • Each sequence has 11 cues (one per color)
  • Each cue references the appropriate color preset
Result: Sequence 300 for Group 1 with cues 1-11, Sequence 301 for Group 2, etc.

​
5. Executor Assignment

for seq = seqStart, seqStart + #groups - 1 do
  local executor = execPage..".".(execStart + seq - seqStart)
  cmd("Assign Sequence "..seq.." At Executor "..executor)
end
What this does:
  • Assigns sequences to executors on page 100
  • Executor 100.101 gets Sequence 300 (Group A)
  • Executor 100.102 gets Sequence 301 (Group B)
  • And so on…

​
Verifying Results

1

Check Presets

Open the Color Preset Pool:
  1. Press [View] → [Presets]
  2. Select preset type 4 (Color)
  3. You should see presets labeled “A White”, “A Red”, “A Orange”, etc.
Expected Range: Presets 4.1 through 4.123 (if all 7 groups exist)
2

Check Sequences

Open the Sequence Pool:
  1. Press [View] → [Sequences]
  2. Look for sequences 300-306
  3. Each sequence should be labeled “A” through “G”
Click a sequence to view its cues - you’ll see 11 cues per sequence.
3

Test an Executor

Navigate to executor page 100:
  1. Press [Page] [1] [0] [0] [Please]
  2. You’ll see executors 101-107 with sequence names
  3. Press one of the executor buttons to trigger a cue
  4. Use the executor’s fader to fade between colors

​
Customizing the Plugin

You can modify the plugin behavior by editing ColorPickerUpdate.lua:

​
Change Preset Starting Number

local presetStart = 200  -- Start at preset 200 instead of 1

​
Change Sequence Numbers

local seqStart = 500  -- Use sequences 500-506 instead of 300-306

​
Change Executor Page

local execPage = 1    -- Assign to page 1 instead of page 100
local execStart = 1   -- Start at executor 1

​
Add More Colors

Expand the color list: 
local colNb = 13
local colSwatchBook = {"White", "Red", "Orange", "Yellow", "Green", 
                       "Sea Green", "Cyan", "Lavender", "Blue", "Violet", 
                       "Magenta", "Pink", "Warm White"}
local colSwatchIndex = {1, 2, 3, 4, 5, 6, 8, 9, 10, 11, 12, 13, 14}
After editing the .lua file, you must re-import the plugin for changes to take effect:
Import "ColorPickerUpdate.xml" At Plugin [index]

​
How the Plugin Works: Code Flow

Here’s the complete execution flow: 
function ColorPickerUpdate_Start()
  fb("---Color Picker Started :DDD---")
  cmd("BlindEdit On")              -- Enable blind edit mode
  deletePresets()                  -- Clear old presets
  deleteSequence()                 -- Clear old sequences
  sleep(0.1)                       -- Brief pause
  createPresets()                  -- Create new color presets
  createSequences()                -- Create new sequences
  createCues()                     -- Create cues in sequences
  assignSequences()                -- Assign to executors
  cmd("BlindEdit Off")             -- Exit blind edit mode
  fb("--- Color Picker Update Done---")
  -- Demo sequence follows...
  resetValues()                    -- Clean up variables
end
Each function is self-contained and performs a specific task, making the code easy to understand and modify.

​
Common Issues

​
No Presets Created

Cause: Groups 1-7 don’t exist in your show file. Solution: Create at least one group before running the plugin.

​
Executor Page is Empty

Cause: You’re on the wrong executor page. Solution: Navigate to page 100 using [Page] [1] [0] [0] [Please].

​
Plugin Runs But No Feedback

Cause: Console feedback is disabled. Solution: Enable command line feedback in console settings.

​
Next Steps

Now that you understand how plugins work, try the other plugins:

Pulse Generator

Create dynamic pulse sequences with interleaved patterns

Pulse Wave Generator

Generate complex directional wave effects

​
Plugin Workflow Summary

1

Delete Old Data

The plugin removes existing presets and sequences in the configured range to avoid conflicts
2

Create Presets

Creates 11 color presets per group using gel library swatches
3

Build Sequences

Creates 7 sequences (one per group) and populates each with 11 color cues
4

Assign to Executors

Maps sequences to executor page 100, starting at executor 101
5

Run Demo

Triggers color macros to demonstrate the created presets
The plugin uses gma.sleep() between operations to give the console time to process commands. This prevents overwhelming the command parser.

​
Understanding Blind Edit Mode

The plugin uses Blind Edit mode to work safely: 
cmd("BlindEdit On")
-- All preset and sequence creation happens here
cmd("BlindEdit Off")
Benefits:
  • Changes don’t affect live output
  • You can keep running your show while the plugin works
  • Only exits blind edit after all operations complete
Important: If the plugin crashes mid-execution, you may need to manually exit blind edit: 
BlindEdit Off
You’ve successfully run your first MA2 plugin! You now understand how to execute plugins, interpret feedback, verify results, and customize behavior. Try experimenting with the other plugins in the collection to discover more advanced features.

Build docs developers (and LLMs) love

Get started for freeTalk to us