Lua API reference
The grandMA3 Lua API, made searchable. Filter by name or category; every signature links to its full page with arguments, return values, and examples. The official API is admittedly thin — this index plus the per-page detail is the human-readable reference.
| Signature | Summary | Category |
|---|---|---|
| Handle (light_userdata) | Many functions require a handle as an argument or return a handle. The handle is a custom data type called "light_userdata" - a unique identifier referring to a grandMA3 object (sequence, cue, preset, fixture, etc.). | Concepts |
| Object API (overview) | Object API means Lua functions that are methods of an object. All object functions take a handle; the handle can be omitted with the colon notation object:function(). See for the notation rules. | Concepts |
| Object-Free API (overview) | Object-Free API means Lua functions that are not functions/methods of objects (called directly, e.g. Cmd(...) rather than obj:Cmd()). | Concepts |
| Variable Functions (overview) | Interactions with variables outside the plugins (the same user and global variables used in macros and the command line). Covers UserVars/GlobalVars sets and the GetVar/SetVar/DelVar functions. | Concepts |
| Interface Functions (overview) | Several Lua functions related to creating and displaying interface elements - often the most complex functions, some of which return user input. Known limitation: not all interface functions are documented yet. | Interface / UI |
| Progress Bar (function set) ex | The Progress Bar is a Lua function set that creates a moving progress bar on the screens. Shows StartProgress, SetProgressRange, SetProgress, SetProgressText, IncProgress, and StopProgress used together. | Interface / UI |
| Addr(handle[, handle[, boolean]]) ex | The Addr Lua object function converts a handle to an address string that can be used in commands. | Object API |
| AddrNative(handle[, handle[, boolean]]) ex | The AddrNative Lua object function converts a handle to an address string that can be used in commands. | Object API |
| Children(handle) ex | The Children Lua function creates a table of handles for the children of an object. | Object API |
| Count(handle) ex | The Count function returns an integer number indicating the number of child objects. | Object API |
| Dump(handle) ex | The Dump function returns a string with information about the object, for instance, the name, class, path of the object, its properties, and children. | Object API |
| Export(handle, string, string) ex | The Export object Lua function exports an object into an XML file. | Object API |
| Get(handle, string[, integer]) ex | The Get function returns a string with information about a specified property of the object, for instance, the object's name, class, or path. | Object API |
| GetChildClass(handle) ex | The GetChildClass function returns a string with the name of the class of the object's children. | Object API |
| GetClass(handle) ex | The GetClass function returns a string with information about the class for the object. | Object API |
| GetDependencies(handle) ex | The GetDependencies function returns a table with the objects' dependencies. | Object API |
| GetFaderText(handle, {[string], [integer]}) ex | The GetFaderText function returns a text string indicating a fader value for the object. | Object API |
| GetReferences(handle) ex | The GetReferences function returns a table with handles for the objects referencing this object. | Object API |
| GetUIEditor(handle) ex | The GetUIEditor function returns a text string with the name of the UI editor for the object. | Object API |
| GetUISettings(handle) ex | The GetUISettings function returns a text string with the name of the UI settings for the object. | Object API |
| HasActivePlayback(handle) ex | The HasActivePlayback Lua function returns a boolean indicating if an object has a currently active playback, for instance, if a sequence has an active cue. | Object API |
| Import(handle, string, string) ex | The Import object Lua function imports an object written in XML format. | Object API |
| Ptr(handle, integer) ex | The Ptr Lua function returns the handle to a child object. | Object API |
| Set(handle, string, string[, integer]) ex | The Set function sets a value to a specified property of the object, for instance, the object's name. | Object API |
| SetFader(handle, {[number], [boolean], [string]}) ex | The SetFader function sets a fader to a specified level. It must be used on an object that has faders. | Object API |
| AddFixtures(table) ex | The AddFixtures Lua function adds fixtures to the patch. The argument is a table which must contain valid data for the function to succeed. | Object-Free API |
| AddonVars(string) ex | The AddonVars function returns a handle to the set of variables connected to a specific addon. | Object-Free API |
| BuildDetails() ex | The BuildDetails function returns a table with key-value pairs about the software build. | Object-Free API |
| CheckDMXCollision(handle, string[, integer[, integer]]) ex | The CheckDMXCollision Lua function checks if a specific DMX address range is available or already used. | Object-Free API |
| CheckFIDCollision(integer[, integer[, integer]]) ex | The CheckFIDCollision Lua function checks if a specific (range of) ID is available or already used. It can be used to check FID and any type of CID. | Object-Free API |
| ClassExists(string) ex | The ClassExists Lua function returns a boolean indicating whether the provided string is a class. | Object-Free API |
| CloseAllOverlays() ex | The CloseAllOverlays function closes any pop-ups or menus (overlays) open on any screen. | Object-Free API |
| CloseUndo(handle) ex | The CloseUndo Lua function closes an open undo list. The function returns a boolean indicating if the function succeeds. | Object-Free API |
| Cmd(string[, handle]) ex | The Cmd Lua function executes a command in the grandMA3 command line. It runs in a Lua task (not the Main task), executes synchronously, and blocks the Lua task while executing. | Object-Free API |
| CmdIndirect(string[, handle[, handle]]) ex | The CmdIndirect Lua function executes a command within the grandMA3 command line. It is executed asynchronously in the Main task and does not block the Lua execution. | Object-Free API |
| CmdIndirectWait(string[, handle[, handle]]) ex | The CmdIndirectWait Lua function executes a command within the grandMA3 command line. It does not block the Lua execution and is executed synchronously in the main task. | Object-Free API |
| CmdObj() ex | The CmdObj Lua function returns information about the command line object. | Object-Free API |
| ConfigTable() ex | The ConfigTable Lua function returns a table with some configuration information. This is information only; the function does not have any actual functions. | Object-Free API |
| Confirm(string[, string[, integer[, boolean]]]) ex | The Confirm Lua function provides a simple confirmation pop-up for a true/false query. It is part of the user interface functions. | Object-Free API |
| CreateMultiPatch({handles}, integer[, string]) ex | The CreateMultiPatch Lua function creates a series of multi patch fixtures to a table of fixtures. | Object-Free API |
| CreateUndo(string) ex | The CreateUndo Lua function returns a handle to a list of commands and function calls grouped in the same oops action. | Object-Free API |
| CurrentEnvironment() ex | The CurrentEnvironment Lua function returns a handle to the current users' selected environment. | Object-Free API |
| CurrentExecPage() ex | The CurrentExecPage Lua function returns a handle to the current users' selected executor page. | Object-Free API |
| CurrentProfile() ex | The CurrentProfile Lua function returns a handle to the current users' profile. | Object-Free API |
| CurrentScreenConfig() ex | The CurrentScreenConfig Lua function returns a handle to the current users' screen configuration. | Object-Free API |
| CurrentUser() ex | The CurrentUser Lua function returns a handle to the current user. | Object-Free API |
| DataPool() ex | The DataPool Lua function references the currently selected DataPool and is used to read or edit properties within the data pool. | Object-Free API |
| DefaultDisplayPositions() ex | The DefaultDisplayPositions Lua function returns the handle of the conventional default display positions, which contains the first seven screens as children. | Object-Free API |
| DelVar(handle, string) ex | The DelVar Lua function deletes a specific variable in a set of variables. | Object-Free API |
| DeskLocked() ex | The DeskLocked Lua function returns a boolean indicating if the station is locked. | Object-Free API |
| DeviceConfiguration() ex | The DeviceConfiguration Lua function returns a handle to the DeviceConfiguration object. | Object-Free API |
| DirList(string[, string]) ex | The DirList Lua function returns a table of files at a specified path. The returned list can be filtered using an optional filter argument. | Object-Free API |
| DrawPointer(integer, table[, integer]) ex | The DrawPointer function draws a red pointer on the display. There can only be one pointer at a time on each station. | Object-Free API |
| DumpAllHooks() ex | The DumpAllHooks function prints a list of the hooks in the system. The list is only shown in the System Monitor. | Object-Free API |
| Echo(string) ex | The Echo Lua function prints a string in the System Monitor. | Object-Free API |
| ErrEcho(string) ex | The ErrEcho Lua function prints a red error message on the System Monitor. | Object-Free API |
| ErrPrintf(string) ex | The ErrPrintf Lua function prints a red error message in the Command Line History and System Monitor. | Object-Free API |
| Export(filename, export_data) ex | The object-free Export Lua function exports a Lua table in XML format. | Object-Free API |
| ExportCSV(filename, export_data) ex | The object-free ExportCSV Lua function exports a Lua table in CSV format. | Object-Free API |
| ExportJson(filename, export_data) ex | The object-free ExportJson Lua function exports a Lua table in JSON format. | Object-Free API |
| FileExists(string) ex | The FileExists Lua function checks if a file exists and returns a boolean with the result. | Object-Free API |
| FindTexture(string) ex | The FindTexture Lua function returns a handle to the texture matching the input text string - if the texture exists. | Object-Free API |
| FirstDmxModeFixture(handle) ex | The FirstDmxModeFixture Lua function returns a handle to the first fixture matching the supplied DMX mode. | Object-Free API |
| FixtureType() ex | The FixtureType Lua function returns a handle to the fixture type. The function does not accept any arguments but must be executed in the right command context. | Object-Free API |
| FromAddr(string[, handle]) ex | The FromAddr Lua function converts a numbered string address into a handle that can be used in commands. | Object-Free API |
| GetApiDescriptor() ex | The GetApiDescriptor Lua function returns a table with a description of all the object-free Lua functions. These are descriptions only. | Object-Free API |
| GetAttributeByUIChannel(integer) ex | The GetAttributeByUIChannel Lua function returns the handle to an attribute based on a "UI Channel Index". The index can be found in the Parameter List. | Object-Free API |
| GetAttributeCount() ex | The GetAttributeCount Lua function returns the total number of attribute definitions in the show. | Object-Free API |
| GetAttributeIndex(string) ex | The GetAttributeIndex Lua function returns the (0 based) index number of the attribute definition based on the system name of the attribute. | Object-Free API |
| GetButton(handle) ex | The GetButton Lua function returns a key-value pairs table indicating, with a boolean value, whether a button is pressed on an MA3Module. | Object-Free API |
| GetChannelFunction(integer, integer) ex | The GetChannelFunction Lua function returns a handle to a channel function based on two index inputs. | Object-Free API |
| GetChannelFunctionIndex() ex | The GetChannelFunctionIndex Lua function returns the integer matching a channel function based on two index inputs. | Object-Free API |
| GetClassDerivationLevel(string) ex | The GetClassDerivationLevel Lua function returns an integer indicating the derivation level index for a class based on a class name. | Object-Free API |
| GetCurrentCue() ex | The GetCurrentCue Lua function returns a handle to the last activated cue in the selected sequence. | Object-Free API |
| GetDebugFPS() ex | The GetDebugFPS Lua function returns a float number with the frames per second. | Object-Free API |
| GetDisplayByIndex(integer) ex | The GetDisplayByIndex Lua function returns a handle to the display object matching the provided index number. | Object-Free API |
| GetDisplayCollect() ex | The GetDisplayCollect Lua function returns a handle to the DisplayCollect object. | Object-Free API |
| GetDMXUniverse(integer[, boolean]) ex | The GetDMXUniverse Lua function returns a table with the DMX channels and their current value. | Object-Free API |
| GetDMXValue(integer[, integer, boolean]) ex | The GetDMXValue Lua function returns a number indicating the DMX value of a specified DMX address. | Object-Free API |
| GetExecutor(integer) ex | The GetExecutor Lua function returns the handles of the executor and the page based on the executor number. | Object-Free API |
| GetFocus() ex | The GetFocus Lua function returns a handle to the object that currently has focus in the UI. | Object-Free API |
| GetFocusDisplay() ex | The GetFocusDisplay Lua function returns a handle to the display object that currently has focus in the UI. | Object-Free API |
| GetObjApiDescriptor() ex | The GetObjApiDescriptor Lua function returns a table with a description of all the object Lua functions. These are descriptions only. | Object-Free API |
| GetPath(string[, boolean] | integer) ex | The GetPath Lua function returns a string with the path of a grandMA3 folder. | Object-Free API |
| GetPathOverrideFor(string|integer, string[, boolean]) ex | The GetPathOverrideFor Lua function delivers a string with the path of a grandMA3 folder. Relevant when the path should be on a removable drive. | Object-Free API |
| GetPathSeparator() ex | The GetPathSeparator function returns a string with the path separator for the operating system. | Object-Free API |
| GetPathType(handle[, integer]) ex | The GetPathType Lua function returns a string with a name for the path type. This function can be useful when importing objects. | Object-Free API |
| GetPresetData(handle[, boolean[, boolean]]) ex | The GetPresetData Lua function returns a table with the preset data based on the preset handle. | Object-Free API |
| GetRTChannel(integer) ex | The GetRTChannel Lua function returns a table with information about the related RT Channel. | Object-Free API |
| GetRTChannelCount() ex | The GetRTChannelCount Lua function returns a number indicating the total amount of RT channels. | Object-Free API |
| GetRTChannels(integer[, boolean] OR handle[, boolean]) ex | The GetRTChannels Lua function returns a table with RT Channel indexes or a table with handles to the RT Channel objects. Two different argument types are accepted. | Object-Free API |
| GetSample(string) ex | The GetSample Lua function returns a number representing a percentage usage based on a string input. | Object-Free API |
| GetScreenContent(handle) ex | The GetScreenContent Lua function returns a handle to the screen content based on a provided handle to a screen configuration. | Object-Free API |
| GetSelectedAttribute() ex | The GetSelectedAttribute Lua function returns a handle to the currently selected attribute. | Object-Free API |
| GetShowFileStatus() ex | The GetShowFileStatus Lua function returns a string with the current device's show file status, for example, "NoShow", "ShowLoaded", "ShowDownloaded", "ShowSaving". | Object-Free API |
| GetSubfixture(integer) ex | The GetSubfixture Lua function returns the handle of the fixture specified by its patch index number. | Object-Free API |
| GetSubfixtureCount() ex | The GetSubfixtureCount Lua function returns the total number of fixtures that are patched within the show file. | Object-Free API |
| GetTokenName(string) ex | The GetTokenName Lua function returns a string with the full keyword based on the short version string input, or nil if there is no corresponding keyword. | Object-Free API |
| GetTokenNameByIndex(int) ex | The GetTokenNameByIndex Lua function returns a string with the keyword based on the index number provided. | Object-Free API |
| GetTopModal() ex | The GetTopModal Lua function returns a handle for the modal at the top. Modal is the internal name for pop-ups that interrupt the system's normal operation. | Object-Free API |
| GetTopOverlay() ex | The GetTopOverlay Lua function returns a handle for the overlay at the top of the display. Overlay is the internal name for pop-ups/menus. | Object-Free API |
| GetUIChannelCount() ex | The GetUIChannelCount Lua function returns a number indicating the total amount of UI channels. | Object-Free API |
| GetUIChannelIndex(integer, integer) ex | The GetUIChannelIndex Lua function returns the index integer matching a UI channel based on two index inputs. | Object-Free API |
| GetUIChannels(integer[, boolean] OR handle[, boolean]) ex | The GetUIChannels Lua function returns a table with UI Channel indexes or a table with handles to the UI Channel objects. Two different argument types are accepted. | Object-Free API |
| GetUIObjectAtPosition(integer, table) ex | The GetUIObjectAtPosition Lua function returns the handle of the UI Object at a specified position on a specified display. | Object-Free API |
| GetVar(handle, string) ex | The GetVar Lua function returns the value of a specific variable in a set of variables. | Object-Free API |
| GlobalVars() ex | The GlobalVars function returns a handle to the set of global variables. | Object-Free API |
| HandleToInt(handle) ex | The HandleToInt Lua function converts a handle into an integer format. | Object-Free API |
| HandleToStr(handle) ex | The HandleToStr Lua function converts a handle into a string in a hexadecimal number format. | Object-Free API |
| HookObjectChange(function, handle, handle[, handle]) ex | The HookObjectChange Lua function automatically calls a function when a grandMA3 object changes. | Object-Free API |
| HostOS() ex | The HostOS Lua function returns a string with the type of operating system of the device where the plugin is executed (for instance, "Windows", "Linux", or "Mac"). | Object-Free API |
| HostSubType() ex | The HostSubType Lua function returns a string with the host sub type of the station where the plugin is executed (for example, "FullSize", "Light", "RPU", "onPC"). | Object-Free API |
| HostType() ex | The HostType Lua function returns a string with the host type of the device where the plugin is executed (for example, "Console" or "onPC"). | Object-Free API |
| Import(string) | Object-Free API | |
| IncProgress(handle, integer) | Object-Free API | |
| IntToHandle(integer) ex | The IntToHandle Lua function converts an integer number into a handle. The integer needs to correlate with an actual handle. | Object-Free API |
| IsClassDerivedFrom(string, string) ex | The IsClassDerivedFrom Lua function returns a boolean indicating if a class is derived from a different class. | Object-Free API |
| IsObjectValid(handle) ex | The IsObjectValid function returns a boolean true or nil depending on whether the supplied argument is a valid object. | Object-Free API |
| KeyboardObj() ex | The KeyboardObj function returns the handle to the first found keyboard object. | Object-Free API |
| MasterPool() ex | The MasterPool Lua function returns the handle to the masters. | Object-Free API |
| MessageBox(table) ex | The MessageBox Lua function is used to create pop-up message boxes. These can be simple or complex information pop-ups with many different options and user inputs. | Object-Free API |
| MouseObj() ex | The MouseObj function returns the handle to the first found mouse object. | Object-Free API |
| NeedShowSave() ex | The NeedShowSave Lua function returns a boolean indicating if there are unsaved changes to the showfile. | Object-Free API |
| Patch() ex | The Patch Lua function returns a handle to the patch object. | Object-Free API |
| Printf(string) ex | The Printf Lua function prints a string in the Command Line History and System Monitor. | Object-Free API |
| Programmer() ex | The Programmer Lua function references the current programmer object. | Object-Free API |
| ProgrammerPart() ex | The ProgrammerPart Lua function references the current programmer part object. | Object-Free API |
| Pult() ex | The Pult Lua function returns a handle to the current "Pult" object at position Root/GraphicsRoot/PultCollect. The "Pult" object contains display and device info. | Object-Free API |
| ReleaseType() ex | The ReleaseType Lua function returns a string with the type of release for the MA software. All versions available from MA Lighting return "Release". | Object-Free API |
| Root() ex | The Root Lua function returns a handle to the object at the root position. | Object-Free API |
| SelectedFeature() ex | The SelectedFeature Lua function returns the handle of the selected feature. | Object-Free API |
| SelectedLayout() ex | The SelectedLayout Lua function returns the handle of the selected layout. | Object-Free API |
| SelectedSequence() ex | The SelectedSequence Lua function returns the handle of the selected sequence. | Object-Free API |
| SelectedTimecode() ex | The SelectedTimecode Lua function returns the handle of the selected timecode object. | Object-Free API |
| SelectedTimer() ex | The SelectedTimer Lua function returns the handle of the selected timer object. | Object-Free API |
| Selection() ex | The Selection Lua function returns a handle to the object holding the current selection of fixtures. | Object-Free API |
| SelectionCount() ex | The SelectionCount Lua function returns a number indicating the total amount of currently selected fixtures. | Object-Free API |
| SelectionFirst() ex | The SelectionFirst Lua function returns a set of integers for the selection's first fixture. It is the patch index number and the XYZ grid values in the selection grid. | Object-Free API |
| SelectionNext() ex | The SelectionNext function returns a set of integers for the next fixture in a selection based on the index number input as an argument. | Object-Free API |
| SerialNumber() ex | The SerialNumber Lua function returns the serial number of the grandMA3 hardware or grandMA3 onPC. | Object-Free API |
| SetLED(handle, table) ex | The SetLED Lua function sends a table with a set of LED brightness values to an MA3Module. After around two seconds, the system automatically resets the LED values. | Object-Free API |
| SetProgress(handle, integer) ex | The SetProgress Lua function defines a value on the range for a progress bar. A handle input argument defines the progress bar, which must already exist. | Object-Free API |
| SetProgressRange(handle, integer, integer) ex | The SetProgressRange Lua function defines a range for a progress bar. | Object-Free API |
| SetProgressText(handle, string) ex | The SetProgressText Lua function defines a text string to be displayed in a progress bar next to the progress bar title text. | Object-Free API |
| SetVar(handle, string, value) ex | The SetVar Lua function sets a value to a specific variable in a set of variables. This also creates the variable if it does not exist. | Object-Free API |
| ShowData() ex | ShowData is an object-free function that returns a handle to the object at position Root/ShowData. | Object-Free API |
| ShowSettings() ex | ShowSettings is an object-free function that returns a handle to the object at Root/ShowData/ShowSettings. | Object-Free API |
| StartProgress(string) ex | The StartProgress Lua function creates and displays a progress bar on all screens. A string input argument creates a title; the function returns a handle. | Object-Free API |
| StopProgress(handle) ex | The StopProgress Lua function removes a progress bar. A handle input argument defines which progress bar it removes; the progress bar must exist. | Object-Free API |
| StrToHandle(string) ex | The object-free StrToHandle Lua function converts a string with a hexadecimal number format into a handle. The string needs to correlate with an actual handle. | Object-Free API |
| TextInput([string[, string[, integer[, integer]]]]) ex | The TextInput Lua function opens a text input pop-up and returns the typed input as a string. It is part of the user interface functions. | Object-Free API |
| Time() ex | The Time function returns the time (in seconds) the station has been on, as a number (float). It is basically a stopwatch that starts when grandMA3 starts. | Object-Free API |
| Timer(string, integer, integer[, string[, handle]]) | Object-Free API | |
| TouchObj() ex | The TouchObj function returns the handle to the first found touch object. | Object-Free API |
| Unhook(integer) | The Unhook Lua function removes a hook. Hooks are automatically triggered functions created with HookObjectChange. | Object-Free API |
| UnhookMultiple(function, handle, handle) ex | The UnhookMultiple Lua function unhooks multiple hooks based on an input. This input acts like a filter to identify all the hooks that should be unhooked. | Object-Free API |
| UserVars() ex | The UserVars function returns a handle to the set of user variables. | Object-Free API |
Signatures are grandMA3 v2.4 and shift between releases — re-check on the matching
help.malighting.com version for your console's
software. The in-app
HelpLua dump lists everything the console exposes.