gma2-plugins

A development workspace for grandMA2 lighting-console plugins, written in Lua. The goal is to use AI to generate plugins that drive grandMA2's native command syntax, so lighting designers spend less time on repetitive programming and memorizing keywords.

Table of Contents

• Overview
• Features
• Getting Started
  • Prerequisites
  • Installation
  • Usage
• Project Structure
• Plugin Development
• Building a Release
• Reference and Learning Resources
• Contributing
• License

Overview

grandMA2 is the mainstream lighting-programming software in Taiwan and much of the industry. It has its own command syntax and keywords, and it can be extended with plugins written in Lua.

The official plugin documentation, however, does not publicly document which API functions are available or how to write a compatible plugin -- it only states that Lua can be used. As a result, most plugins are written and shared by the lighting community rather than documented officially.

This repository takes the position that AI tooling can help close that gap: generate plugins that operate grandMA2's native command language, and in doing so reduce the repetitive work and keyword memorization that lighting programmers would otherwise carry. It collects the project's own first-party plugins, community plugins kept for study, and official reference material in one place.

grandMA2 runs only on Windows, and plugins execute inside the console. They cannot be run or tested from this repository -- iteration is: edit the Lua/XML here, import it into a grandMA2 console (or onPC), then run it and observe the System Monitor (gma.echo) output there.

Features

The first-party plugins maintained in this repository, all targeting grandMA2 3.9.60. Update Info and Append Info were split out of an earlier Edit Cue Info plugin.

• Update Info -- Reads and edits the Info field of a cue through a text-input dialog. Leaving the input empty clears the cue's Info.

• Append Info -- Appends text to a cue's existing Info field, using / as a separator so previous notes are preserved.

• Create Punch -- Stores the selected fixtures at full into the current cue, then inserts a blackout cue right after it (same fixtures at 0) with a prompted fade time, building a punch/bump in two cues.

• Correct Position Offset -- Bakes the difference between two Position presets into each fixture instance's Pan/Tilt offset. Enter an "original" and a "corrected" preset; for every fixture instance in both, it adds corrected - original to the current offset. Handles multi-instance fixtures (e.g. ACME Tornado TB5: .1 .3 .5 .7 .9), not just the first instance.

• Clean Showfile -- Walks a curated list of content pools (Macros, Presets, Groups, Sequences, Effects, Worlds, Filters, Layouts, Views, Timecodes, Pages), counting each pool live, and shows a Yes/No dialog for each one, e.g. "Delete all 14 macros?". Yes marks the pool, No skips it. Answers are collected first; after a final summary confirmation (Cancel there aborts the whole run) the selected pools are wiped in one batch. Patch, fixtures, and DMX are deliberately excluded.

Download the latest prebuilt plugins (always the newest release):

• Update Info (update-info.zip)
• Append Info (append-info.zip)
• Create Punch (create-punch.zip)
• Correct Position Offset (correct-position-offset.zip)
• Clean Showfile (clean-showfile.zip)

Getting Started

Prerequisites

• A grandMA2 console or grandMA2 onPC (Windows only). Plugins in this repo target version 3.9.60; the XML schema version must match your console.
• To open the bundled community archives: a tool that can extract .zip and .rar files.

Installation

Each plugin is a pair of files: a .lua script and an .xml descriptor that the console imports. The descriptor's luafile= attribute names the Lua file, so the two must keep their original filenames and stay together.

1. Download a plugin's .zip from the links above (or the Releases page) and unzip it (or take the .lua + .xml pair directly from plugins/<name>/).
2. In grandMA2, import the .xml -- it loads the paired .lua.
3. Run the plugin from the Plugin pool.

Usage

Run Update Info to read or change the selected cue's Info field; submit an empty value to clear it. Run Append Info to add a note to a cue's Info without overwriting what is already there. Run Create Punch with fixtures selected and an executor running a cue: it stores them at full into the current cue, asks for a fade time (empty defaults to 1 second), and writes a blackout cue just after the current one with those fixtures fading to 0. Run Correct Position Offset after re-focusing a rig into a corrected Position preset: enter the original and corrected preset numbers and it adds the per-instance Pan/Tilt difference into each fixture's offset, so existing cues using the original preset point correctly. Run Clean Showfile to recycle a show: it steps through the content pools, showing each pool's live object count and a Yes/No dialog; Yes marks a pool, No skips it. Review the summary and confirm once to wipe everything you selected (Cancel there aborts without deleting anything).

Project Structure

gma2-plugins/
├── plugins/                  # First-party plugins (one folder per plugin)
│   ├── update-info/          #   Update Info.lua + Update Info.xml
│   ├── append-info/          #   Append Info.lua + Append Info.xml
│   ├── create-punch/         #   Create Punch.lua + Create Punch.xml
│   ├── correct-position-offset/  # Correct Position Offset.lua + .xml
│   └── clean-showfile/       #   Clean Showfile.lua + Clean Showfile.xml
├── third-party/              # Community plugins, kept for study and attribution
│   ├── layoutfx/             #   extracted source + original archive
│   ├── midi-twister/
│   ├── presets-to-offsets/
│   └── recast-preset/
├── reference/                # Official and learning material
│   ├── ma-samples/           #   grandMA2 sample plugin + API reference (plugin_1)
│   ├── systemtests/          #   official MA console self-test scripts
│   ├── socket/               #   LuaSocket library (for networking plugins)
│   └── lua-lessons/          #   Lua tutorial PDFs
├── sandbox/                  # Unfinished experiments (color.lua, no .xml yet)
├── scripts/                  # build-release.sh — packages plugins into dist/
├── images/                   # README assets
├── CLAUDE.md                 # Guidance for AI agents working in this repo
├── LICENSE                   # MIT (first-party work only)
└── THIRD-PARTY-NOTICES.md    # Attribution and terms for bundled material

plugins/ holds the work this repository owns and releases. third-party/ keeps community plugins for reference -- each folder contains both the readable extracted source and the author's original release archive (see Third-Party Notices for terms). reference/ is read-only material: official MA samples and self-tests, the LuaSocket library, and Lua lesson PDFs.

Plugin Development

Every plugin is a .lua script plus an .xml descriptor that the console imports:

<MA ...>
    <Plugin index="0" execute_on_load="0" name="My Plugin" luafile="My Plugin.lua" />
</MA>

The XML's schema version (major_vers / minor_vers / stream_vers and the MA.xsd path) must match the target console version. When creating a new plugin, copy these from an existing .xml that targets the same version rather than inventing them.

The Lua file contract:

• It receives its names as varargs: local internal_name = select(1, ...) and local visible_name = select(2, ...).
• It must return Start, Cleanup at the end. Start is the entry point invoked when the plugin runs; Cleanup is optional and runs on termination.

Plugins interact with the console exclusively through the global gma table -- most notably gma.cmd("...") to execute a native command-line string, plus gma.echo / gma.feedback for logging, gma.show.getobj.* / gma.show.property.* to read showfile objects, and gma.gui.* / gma.textinput for dialogs. reference/ma-samples/plugin_1.lua is the most complete reference for the available API surface, since no official API documentation exists publicly.

Building a Release

scripts/build-release.sh packages each first-party plugin's .lua + .xml pair into dist/<name>.zip (filenames preserved so the console resolves luafile= on import):

./scripts/build-release.sh
gh release create vX.Y.Z --target main dist/*.zip

The dist/ directory is build output and is gitignored.

Reference and Learning Resources

There is little public material on writing grandMA2 plugins. The following are useful starting points:

• A rare plugin tutorial video (mostly basic Lua syntax).
• GrandMA2 LUA Reference
• grandMA2 Wiki
• CDS - MA2 Lua
• grandMA2 Plugins & Lua Scripts official forum

The Lua tutorial PDFs under reference/lua-lessons/ cover setup, variables, tables, control flow, and functions.

grandMA2 runs only on Windows. The latest version at the time of writing is 3.9.60.91; you can get the console and onPC software from the official download page.

Contributing

Issues and pull requests are welcome. The default working branch is dev; pull requests target main. Please keep first-party plugin .lua/.xml filenames unchanged so the console can still resolve luafile= on import, and add new community plugins under third-party/<name>/ with their original archive and an entry in THIRD-PARTY-NOTICES.md.

There is no build system or local test runner -- grandMA2 plugins can only be exercised inside the console, so treat all testing as manual on-console.

License

The first-party work in this repository is licensed under the MIT License. That license applies only to the original work authored by the repository owner. Bundled community plugins, official MA material, and the Lua PDFs remain under their respective owners' terms -- see THIRD-PARTY-NOTICES.md.