grandma3-stuff

Research and examples for learning the GrandMA3 professional lighting control platform — scripting with Lua, building custom fixture definitions with GDTF, and controlling media servers over DMX.

What's in this repo

File	What it is
grandma3-notes.md	Starting-point notes on the GrandMA3 platform, Lua scripting, and key resources
Pixera@HypotheticalMS.description.xml	A fully annotated GDTF fixture definition for a hypothetical Pixera media server
CLAUDE.md	Codified technical reference for AI assistants (Claude Code) working on GrandMA3 projects

Getting started with GrandMA3

1. Install the free software

GrandMA3 onPC is free and gives you the full console interface on your computer. No hardware required.

Download: https://www.malighting.com/special/grandma3-software/

2. Hello World

Open GrandMA3 onPC, create or load a show file, then type this in the command line:

Lua "Printf('Hello World')"

Output appears in the System Monitor window (open it from the view bar if it's not visible).

To run from a file, save this as hello.lua in the plugins directory:

Printf("Hello World")

Then run it:

LuaFile "hello"

3. Explore the Lua API

Type HelpLua in the GrandMA3 command line to export a complete list of available Lua functions to grandMA3_lua_functions.txt. This is the best way to discover what's available.

The API has two halves:

• Object-Free API — standalone functions: Printf(), Cmd(), Echo(), GetPath(), etc.
• Object API — methods on handles to MA objects (fixtures, sequences, cue lists): obj:Children(), handle:GetClass(), handle:Name(), etc.

Fixture definitions (GDTF)

GrandMA3 uses the GDTF open standard for fixture definitions. A .gdtf file is just a ZIP archive containing a description.xml and optional resources (thumbnails, gobo images, 3D models).

The hierarchy

Every GDTF fixture definition follows this structure:

FixtureType
 ├── AttributeDefinitions
 │    ├── ActivationGroups    (attributes that move together, e.g. Pan+Tilt)
 │    ├── FeatureGroups       (UI groupings: Position, Color, Dimmer, etc.)
 │    └── Attributes          (individual parameters with physical units)
 ├── Wheels                   (color wheels, gobo wheels)
 ├── Geometries               (physical structure: base, yoke, head, beam)
 └── DMXModes
      └── DMXMode
           └── DMXChannels
                └── DMXChannel        (one per DMX address)
                     └── LogicalChannel    (links to an Attribute)
                          └── ChannelFunction  (DMX range → physical range)
                               └── ChannelSet   (named sub-ranges)

Media server fixtures

GDTF has dedicated geometry types for media servers:

• <MediaServerMaster> — global controls
• <MediaServerLayer> — video layers
• <MediaServerCamera> — outputs

The example file Pixera@HypotheticalMS.description.xml demonstrates a complete 46-channel media server fixture with:

• Master dimmer and cue triggering (snap channel with named cue ranges)
• Two video layers, each with media selection, playback, RGB color, color macros, video brightness/contrast/saturation, a video effect engine (type + 2 params), blend mode, XY position, scale, and rotation
• An output section with dimmer and freeze

Patching to a specific universe

Universe assignment happens at patch time in GrandMA3, not in the fixture file. The fixture defines channel offsets starting from 1. To place it in universe 600:

1. Menu > Patch
2. Add the fixture type
3. Set the DMX address to 600.1

Building your own

You can author GDTF files in three ways:

1. GrandMA3 Fixture Type Editor — built into the console/onPC software
2. GDTF Builder — web tool at https://fixturebuilder.gdtf-share.com/
3. By hand — write the description.xml directly (like the example in this repo), ZIP it, rename to .gdtf

Key resources

Official GrandMA3 documentation

• What is Lua
• Lua Object API
• Lua Object-Free API
• Lua Keyword
• Build Fixture Types
• Import GDTF
• Export Fixture Types
• DMX Universes
• Art-Net Configuration

GDTF standard

• GDTF Specification (GitHub)
• GDTF File Format Definition
• GDTF Attribute List
• GDTF Builder
• GDTF Share (community library)

Community / third-party

• MacTirney's GrandMA3 API Documentation
• hossimo's GMA3Plugins
• imhofroger's GMA3_LUA

---

Working with Claude on GrandMA3 topics

This repo was built collaboratively with Claude Code. The CLAUDE.md file gives Claude full context on GrandMA3 concepts, so it can assist with Lua scripting, fixture authoring, and protocol configuration without starting from scratch.

Example prompts

The following prompts were used during the creation of this repo. They serve as starting points for your own explorations — clone this repo, open it in Claude Code, and try variations of these or ask your own questions.

1. Orientation

read the notes file

Start by pointing Claude at existing reference material. It reads the file and summarizes the key concepts, giving both of you a shared foundation.

2. Scripting fundamentals

is it possible to write a hello world program for grandma3 and run it? what is needed to make that happen?

This prompt explores the practical workflow: what software to install, where to write code, how to execute it, and where output appears. Good for understanding the development loop.

3. Fixture authoring (deep dive)

i understand that GrandMA3 has a feature called Fixtures. Can you write an example fixture pack intended to control a hypothetical pixera media server? The fixture should include trigger cues and some color and effect controls. It should be scoped to the 600 universe. Do research and ask questions as needed. I'm not super concerned about executing this fixture construct if that is a thing, i just want to see how it is structured.

This is the big one. It asks Claude to research the GDTF format, understand media server fixture patterns, and produce a real annotated example. The "do research and ask questions as needed" part is important — it gives Claude permission to go deep rather than guess. The "not super concerned about executing" part sets expectations that this is about understanding structure.

4. Knowledge capture

Given the notes as a starting point, codify the results of your research. You need to create a CLAUDE.md file for you and a README.md for humans who wish to learn about your findings pursuant to becoming Grandma3 experts. Include in the readme all of the prompts I have given you to serve as hints for the human who will come after me and use this information about how to work with you. Then, use the gh cli to create a public repo under my github user such that enlore/grandma3-stuff, commit everything, and push it up.

This prompt turns a conversation into a permanent, shareable resource. The CLAUDE.md preserves technical context for future AI sessions. The README.md preserves it for humans. The repo makes it accessible to everyone.

Tips for prompting on this topic

• "Do research" — explicitly telling Claude to research rather than guess produces much better results for niche technical domains like lighting control.
• "Ask questions as needed" — lets Claude clarify ambiguities rather than making assumptions.
• Provide seed material — the grandma3-notes.md file gave Claude a foothold. Even a few bullet points of domain knowledge dramatically improve output quality.
• Ask for structure, not just code — "I want to see how it is structured" produces annotated, educational output rather than uncommented code.
• Name specific technologies — "Pixera media server", "universe 600", "GDTF" — specificity drives better research and more accurate results.