grandma3-lua-api
/grandma3-lua-api
Write, debug, and reason about grandMA3 Lua plugins and scripting — the Object API and Object-Free API (Cmd, Printf, Get/Set, handles, UI dialogs, progress bars), plugin XML/structure, and showfile paths. Use when a user asks to write a grandMA3 plugin or Lua script, automate a console task with Lua, fix a `.lua`/plugin error, or look up a grandMA3 Lua function. grandMA2/dot2 have only macros, not this Lua API — redirect those to macros.
- Author
- thatguysam ↗
- Repository
- grandocs ↗
- Licence
- MIT
- Last repository change
- 15.06.2026
Assessment and security
- Files in this package
- 4
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 1
No signals detected. Repository changed on 15.06.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
What it does and when to use it
Write, debug, and reason about grandMA3 Lua plugins and scripting — the Object API and Object-Free API (Cmd, Printf, Get/Set, handles, UI dialogs, progress bars), plugin XML/structure, and showfile paths. Use when a user asks to write a grandMA3 plugin or Lua script, automate a console task with Lua, fix a `.lua`/plugin error, or look up a grandMA3 Lua function. grandMA2/dot2 have only macros, not this Lua API — redirect those to macros.
Original author description
Write, debug, and reason about grandMA3 Lua plugins and scripting — the Object API and Object-Free API (Cmd, Printf, Get/Set, handles, UI dialogs, progress bars), plugin XML/structure, and showfile paths. Use when a user asks to write a grandMA3 plugin or Lua script, automate a console task with Lua, fix a `.lua`/plugin error, or look up a grandMA3 Lua function. grandMA2/dot2 have only macros, not this Lua API — redirect those to macros.
How it works
- HARD RULES — read before answering
- How to look things up (cite as you go)
- Writing a plugin (workflow)
- When it's NOT this skill
- Source attribution (always)
SKILL.md preview
---
name: grandma3-lua-api
description: Write, debug, and reason about grandMA3 Lua plugins and scripting — the Object API and Object-Free API (Cmd, Printf, Get/Set, handles, UI dialogs, progress bars), plugin XML/structure, and showfile paths. Use when a user asks to write a grandMA3 plugin or Lua script, automate a console task with Lua, fix a `.lua`/plugin error, or look up a grandMA3 Lua function. grandMA2/dot2 have only macros, not this Lua API — redirect those to macros.
---
# grandMA3 Lua API helper
Help users write and debug grandMA3 Lua plugins and scripts, grounded in the
grandocs mirror. grandMA3 is the only MA generation with this Lua API —
grandMA2 and dot2 use macros (command-line sequences), not Lua.
## HARD RULES — read before answering
1. **grandocs is an UNOFFICIAL mirror.** For anything authoritative, legal, or
safety-relevant (conformity, electrical, rigging, network safety), tell the
user to confirm on the canonical page at `help.malighting.com` (every
grandocs page carries its `sourceUrl`). Lua that drives moving lights, DMX
output, or patch changes can move real fixtures — flag that.
2. **NEVER invent grandMA3 syntax or function signatures.** Quote the doc's
signature and example code blocks verbatim. If you can't find a function in
grandocs or a cited community source, say so — do not guess argument order,
return types, or enum names. The MA3 Lua API is large and idiosyncratic;
plausible-looking invented calls fail silently or crash the plugin.
3. **Version-gate every answer.** The Lua API changes between MA3 releases:
functions are added, renamed, and removed; enum values shift. grandocs
mirrors **grandMA3 v2.4** by default. Ask the user which console software
version they run; if it differs, warn that signatures/availability may
differ and point them at the matching `help.malighting.com` version.
4. **Cite grandocs `lua_*` pages first.** Lead with the official function page;
use community resources only to fill gaps the official docs leave (see
`references/community-resources.md`), and always label community info as
unofficial.
## How to look things up (cite as you go)
grandMA3 Lua pages live under `/grandma3/2-4/lua_*` on grandocs. Resolve in this
order:
1. **MCP (if connected).** grandocs ships an MCP server with tools
`search_docs`, `get_page`, `command_lookup`, and `list_products_versions`.
Use `search_docs` (query + `product: grandma3`) to find the function, then
`get_page` for its full markdown.
2. **Markdown twins.** Append `.md` to any grandocs page URL for raw markdown,
e.g. `https://grandocs.samcarlton.com/grandma3/2-4/lua_object_get.md`. Same
convention as Stripe docs.
3. **llms.txt.** Fetch `/llms.txt` (index) or `/llms-full.txt` to discover the
Lua section, then fetch the relevant `.md` twin.
Slug convention — match the function to its page slug:
- **Object-Free API** (global functions called directly): `lua_objectfree_<name>`
— e.g. `Cmd` → `lua_objectfree_cmd`, `GlobalVars` → `lua_objectfree_globalvars`.
Note: `Printf`/`ErrPrintf` appear in examples; the table-dialog and progress
helpers are object-free too.
- **Object API** (methods called on a handle, usually colon notation):
`lua_object_<name>` — e.g. `Get` → `lua_object_get`, `Set` → `lua_object_set`,
`Addr` → `lua_object_addr`.
- Index/concept pages: `lua_object`, `lua_objectfree`, `lua_handle`,
`lua_interface`, `lua_interface_progressbar`.
`references/function-index.md` lists the high-traffic functions with their
verbatim signatures and grandocs slugs so you can jump straight to the page.
## Writing a plugin (workflow)
1. **Confirm version** (rule 3) and what the user is automating.
2. **Find the real functions** via lookup above. A grandMA3 plugin's executable
body is `return function() ... end`; the console calls that returned
function. Inside it you mix:
- `Cmd("...")` to run command-line syntax (the most reliable way to make the
desk do things — for the command syntax itself, defer to the
`grandma-command-syntax` skill / `keyword_*` pages).
- Object API via handles: get a handle (`Root()`, `SelectedSequence()`,
`CurrentUser()`, …), then `handle:Get(...)`, `handle:Set(...)`,
`handle:Children()`, etc.
- `Printf(...)` / `ErrPrintf(...)` for feedback to the command-line history.
- `coroutine.yield(...)` to stay responsive in loops (required for progress
bars and long work).
3. **Quote example code verbatim** from the function's grandocs page, then adapt
variable names — don't synthesize calls the docs don't show.
4. **Lint before presenting** (`references/plugin-authoring.md` checklist):
`return function()` wrapper present, every API call traced to a doc page,
handles nil-checked, no invented enums, version stated.
5. **Tell the user where it goes** — plugin/showfile paths in
`references/plugin-authoring.md`. Plugins live in the showfile or the user
library; the Lua API surface differs from onPC to console only in hardware
functions.
## When it's NOT this skill
- **grandMA2 / dot2 plugins or "Lua":** those generations have macros, not this
API. Redirect to macros / the command syntax skill; don't apply MA3 Lua here.
- **Pure command-line syntax** ("what's the syntax for Store / Assign / If"):
that's the `grandma-command-syntax` skill and `keyword_*` pages. Use `Cmd()`
to call such syntax from Lua, but quote the syntax from the keyword page.
## Source attribution (always)
End answers by naming the grandocs page(s) you used and their canonical
`help.malighting.com` `sourceUrl`, and restate that grandocs is an unofficial
mirror — verify safety/conformity-relevant details on the official page.
Files in this package (4)
- SKILL.md 6 KB
- references/community-resources.md 3 KB
- references/function-index.md 5 KB
- references/plugin-authoring.md 4 KB
Versions
The database has no other skills named grandma3-lua-api.
Database snapshot: 13.11.2026 · package version 9e381ad3dc4a (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 100grandma-macro-writer
Write, fix, and debug grandMA2 / grandMA3 (and dot2) macros and grandMA3 Lua plugins — macro list/CMD lines, the @ command-line-interaction character, variables, XML import/export files, showfile/onPC filesystem locations, and quoting pitfalls. Use whenever someone asks to… - 100lua-embedding-scripting
Use this skill when embedding Lua runtimes into C, Go, or Rust applications for dynamic plugin scripting and configuration rules. - 90lua-guide
Use when editing general-purpose Lua 5.4+: modules, scripts, configuration. Triggers on `.lua` files and prompts about module patterns, local scoping, metatables, coroutines, error handling, even when the user doesn't say 'Lua'. - 85Lua C Integration
Use when lua C API for extending Lua with native code including stack operations, calling C from Lua, calling Lua from C, creating C modules, userdata types, metatables in C, and performance optimization techniques. - 90lua-development
Lua language and module development standards for Cybercore and Omarchy-related work. Use for general Lua coding, modules, performance, error handling, testing, and embedded/scripting tasks outside pure Hyprland config. - 95zlua-csharp-call-lua
Calls Lua from C# with LuaAppDomain.Initialize and GetFunction. Use when writing a module loader, binding Action or Func to a Lua module method, or reloading scripts with Reset.