Skip to content
Skills Library
Programming · Building & coding

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.

Repository
grandocs ↗
Licence
MIT
Last repository change
15.06.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
4
Scripts
0
HTML comments
0
URLs in SKILL.md
1
Deprecation

No signals detected. Repository changed on 15.06.2026, without references to retired models or APIs.

Licence

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

  1. HARD RULES — read before answering
  2. How to look things up (cite as you go)
  3. Writing a plugin (workflow)
  4. When it's NOT this skill
  5. Source attribution (always)
Original SKILL.md headings · 97 lines, 722 words
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.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.