• grandMA3 User Manual
    • About the manual
    • Device Overview
      • grandMA3 consoles
        • grandMA3 full-size
        • grandMA3 full-size CRV
        • grandMA3 light
        • grandMA3 light CRV
        • grandMA3 compact XT
        • grandMA3 compact
      • grandMA3 extension
      • grandMA3 replay unit
      • grandMA3 processing units
      • grandMA3 Nodes
      • grandMA3 Nodes DIN-Rail
      • grandMA3 I/O Node
      • grandMA3 I/O Node DIN-Rail
      • grandMA3 onPC command wing XT
      • grandMA3 onPC command wing
      • grandMA3 onPC fader wing
      • grandMA3 onPC rack-unit
      • Screen allocation
      • Keyboard shortcuts
      • Keys
        • . [Dot]
        • <<< [GoFastBackward] | Black
        • >>> [GoFastForward] | Flash
        • - [Minus]
        • + [Plus]
        • / [Slash] | * [Asterisk/Multiply]
        • At
        • Assign
        • Align
        • Blind
        • Clear
        • Channel
        • Copy
        • Ctrl
        • Cue
        • Down
        • Delete
        • Esc
        • Edit
        • Freeze
        • Full
        • Fixture
        • Group
        • Goto
        • Go+ [large]
        • Go- [large]
        • Go+ | Temp
        • Go- | Top
        • Help
        • Highlt [Highlight]
        • If
        • Learn | Rate1
        • List
        • MA
        • Menu
        • Move
        • Next
        • Numeric keys | arrows
        • Oops
        • On
        • Off
        • Pause [large]
        • Pause | Fix
        • Page+
        • Page-
        • Please
        • Power
        • Preset
        • Prvw [Preview]
        • Prev [Previous]
        • Select
        • SelFix [SelectFixture]
        • Sequ [Sequence]
        • Set
        • Solo
        • Stomp
        • Store
        • Thru
        • Time
        • Up
        • Update
        • U1
        • U2
        • X1 | Clone
        • X2 | Link
        • X3 | Grid
        • X4 | Layout
        • X5 | Step
        • X6 | TC
        • X7 | View
        • X8 | DMX
        • X9
        • X10
        • X11
        • X12
        • X13 | Phaser
        • X14 | Macro
        • X15 | Page
        • X16 | Exec
        • Xkeys
      • Control elements
        • Command area
        • Master area
        • Custom area
        • Dual encoders
        • Level wheel
        • Grand master
        • Executor elements
      • Connector pin assignment
    • System Overview
      • Standalone device
      • Locally networked devices
      • World server
      • Parameters
        • Calculate parameters
        • Expand the amount of parameters
    • First Steps
      • Unpack the device
      • Check scope of delivery
      • Position the device
      • Connect power
      • Connect desk light
      • Connect external screens
      • Connect USB devices
      • Connect DMX
      • Connect Audio In
      • Connect MIDI
      • Connect LTC
      • Connect Ethernet
      • Connect DC Remote In
      • Connect grandMA3 extension
      • Connect grandMA3 fader wing
      • Turn on the device the first time
    • grandMA3 onPC
      • System requirements grandMA3 onPC
      • Windows installation
      • Optimize Windows
      • macOS installation
      • Optimize macOS
      • onPC Terminal App
      • onPC settings
    • Show File Handling
    • Workspace
      • User interface
        • Configuration of displays
        • Desk lock
        • User-defined area
        • Command line
        • Control bar
        • View bar
        • Tables in general
        • Trackpad window
      • Gestures
      • Command area
      • Master controls
      • Playback controls
      • Displays in grandMA3 onPC
      • Encoder bar
        • Feature group control bar
        • Encoder toolbar
      • Calculator
      • Playback bar
      • Command wing bar
      • Colors
        • System
        • Markers
        • Color theme
    • Command Syntax and Keywords
      • General syntax rules
      • General keywords
        • ; [Semicolon]
        • / [Slash]
        • . [Dot]
        • .. [DotDot]
        • = [Equal]
        • <<< [GoFastBackward]
        • >>> [GoFastForward]
        • - [Minus]
        • * [Asterisk]
        • % [Percent]
        • + [Plus]
        • Absolute
        • Acceleration
        • Action
        • ActivationGroup
        • Agenda
        • Align
        • AlignTransition
        • Appearance
        • Assign
        • At
        • Attribute
        • AutoCreate
        • Black
        • Blind
        • Block
        • BPM
        • Call
        • Camera
        • Capture
        • ChangeDestination
        • Channel
        • ChannelSet
        • Chat
        • ChatJoin
        • ChatLeave
        • Cleanup
        • Clear
        • ClearActive
        • ClearAll
        • ClearSelection
        • Clone
        • CommandDelay
        • Collect
        • Collection
        • Color
        • ColorDef
        • ColorTheme
        • Configuration
        • Console
        • Cook
        • Copy
        • Cue
        • CueAbs
        • CueDelay
        • CueFade
        • CueInDelay
        • CueInFade
        • CueOutDelay
        • CueOutFade
        • CueRel
        • CueUpdate
        • CurrentEnvironment
        • CurrentUser
        • CurrentUserProfile
        • Cut
        • DataPool
        • Deceleration
        • Decimal8
        • Decimal16
        • Decimal24
        • Default
        • Delay
        • Delete
        • DeleteOtherVersions
        • DelGlobalVar
        • DelUserVar
        • Dismiss
        • Display
        • DMXLayer
        • DMXAddress
        • DMXReadout
        • DMXUniverse
        • DoubleSpeed
        • Down
        • DumpLog
        • Drive
        • Echo
        • Edit
        • EditSetting
        • Eject
        • Effect
        • EndIf
        • Environment
        • Exchange
        • Executor
        • Export
        • Extract
        • Extension
        • Fade
        • Fader
        • FaderMaster
        • FaderRate
        • FaderSpeed
        • FaderTemp
        • FaderTime
        • FaderX
        • FaderXA
        • FaderXB
        • FeatureGroup
        • Filter
        • Fix
        • FixtureClass
        • FixtureLayer
        • Fixture
        • FixtureType
        • Flip
        • Flash
        • Fog
        • Font
        • Freeze
        • Full
        • Gel
        • GetGlobalVar
        • GetUserVar
        • Go+
        • Go-
        • Goto
        • Grid
        • GridPos
        • Group
        • HalfSpeed
        • HardwareKey
        • Help
        • Helplua
        • Hex8
        • Hex16
        • Hex24
        • Highlight
        • Houselights
        • Hz
        • If
        • IfActive
        • IfOutput
        • IfProg
        • Image
        • Import
        • Index
        • Insert
        • Integrate
        • Interface
        • Invert
        • Invite
        • IP
        • JoinSession
        • Key
        • Keyboard
        • KeyboardShortcuts
        • Knockin
        • Knockout
        • Label
        • Language
        • Layout
        • LearnSpeed
        • LeaveSession
        • Library
        • List
        • ListOwner
        • ListRef
        • Load
        • Loaded
        • LoadShow
        • Lock
        • Login
        • Logout
        • Lowlight
        • Lua
        • LuaFile
        • Macro
        • MArker
        • Master
        • MAtricks
        • Measure
        • Media
        • MemInfo
        • Menu
        • Mesh
        • MessageCenter
        • Monitor
        • Move
        • Multipatch
        • MyRunningMacro
        • MyRunningPreset
        • MyRunningSequence
        • Natural
        • NDI
        • NewShow
        • NextY
        • NextZ
        • Next
        • Node
        • NonDim
        • Normal
        • Off
        • Offset
        • On
        • onPC
        • OSC
        • Oops
        • OutputLayer
        • Page
        • Part
        • Park
        • Paste
        • Patch
        • Pause
        • Percent
        • PercentFine
        • Phase
        • Physical
        • Plugin
        • Preset
        • PresetUpdate
        • Press
        • Preview
        • PreviousY
        • PreviousZ
        • Previous
        • Programmer
        • Property
        • PU
        • Pyro
        • Rate1
        • RDM
        • Readout
        • Reboot
        • Recast
        • Record
        • Relation
        • Relative
        • Release
        • ReloadPlugins
        • ReloadUI
        • Remote
        • RemoteHID
        • RemoteCommand
        • Remove
        • RenderQuality
        • Reset
        • Restart
        • Root
        • RTChannel
        • RunningMacro
        • RunningPreset
        • RunningSequence
        • RunningTimecode
        • SaveShow
        • ScreenConfig
        • ScreenContent
        • Scribble
        • Seconds
        • Select
        • Selection
        • SelFix
        • Sequence
        • SendMIDI
        • SendOSC
        • Set
        • SetGlobalVar
        • SetUserVar
        • Shuffle
        • Shutdown
        • SnapDelay
        • SoftwareImport
        • SoftwareUpdate
        • SoundChannel
        • Solo
        • SpecialExecutor
        • Speed
        • Speed1
        • Stage
        • Station
        • Step
        • Stomp
        • SwitchGma2Mode
        • Swop
        • Store
        • Temp
        • Texture
        • Thru
        • Time
        • Timecode
        • TimecodeSlot
        • Toggle
        • TopUp
        • Top
        • Transition
        • Type
        • UIChannel
        • UIGridSelection
        • UnBlock
        • Universal
        • UnLock
        • UnPark
        • UnPress
        • Up
        • Update
        • UpdateContent
        • User1
        • User2
        • User
        • UserProfile
        • Video
        • Version
        • View
        • ViewButton
        • Width
        • World
        • Xkeys
        • Zero
      • Option keywords
        • /Active
        • /ActiveForSelected
        • /AddNewContent
        • /All
        • /AllForSelected
        • /Ask
        • /Auto
        • /CopyCueDst
        • /CopyCueScr
        • /CreateReferenceObject
        • /CreateSecondCue
        • /CueOnly
        • /Date
        • /Default
        • /DiscardChanges
        • /DMX
        • /Embed
        • /Enumerate
        • /File
        • /ForceGlobal
        • /GDTF
        • /Gaps
        • /Global
        • /Indirect
        • /KeepActivation
        • /Look
        • /Merge
        • /NoConfirm
        • /OriginalContentOnly
        • /Overwrite
        • /Path
        • /Release
        • /Remove
        • /Screen
        • /Selective
        • /Universal
      • Extended command line syntax options
    • Windows, Views, and Menus
      • Add window
      • Rearrange
      • Store and recall views
      • Remove windows from a screen
      • Window settings
      • Menus
      • Change menu locations
      • Pool windows
        • Create pool object
        • Label pool objects
        • Move pool objects
        • Insert pool objects
        • Copy pool objects
        • Lock and unlock pool objects
        • Delete pool objects
    • Networking
      • Interfaces and IP
      • Session
        • Create a session
        • Join a session
        • Leave a session
        • Invite to a session
        • Dismiss from session
        • Create a custom key
      • Web remote
    • DMX In and Out
      • DMX port configuration
      • Ethernet DMX
        • Art-Net menu
        • sACN menu
        • Transmit DMX using Art-Net
    • Single User and Multi User Systems
      • Create User
      • User settings
    • Patch and Fixture Setup
      • What are fixtures
      • Add fixtures to the show
      • Add multipatch fixtures
      • MVR
      • Live patch
      • DMX sheet
      • DMX universes
      • Remove fixtures from the show
      • Position fixtures in the 3D space
      • 3D
      • Camera Pool
      • Stages
      • Classes and Layers
      • Attribute definitions
        • Activation group
        • Feature group
        • Deactivation group
      • Parameter list
      • DMX curves
    • Operate Fixtures
      • Select Fixtures
      • What is the programmer
      • Fixture sheet
      • Encoder resolution
      • Using the color picker
      • Gel pool
      • Selection bar
      • Align
      • Selection Grid
      • Smart view
    • Scribbles
      • Create scribbles
      • Edit scribbles
      • Assign scribbles
      • Delete scribbles
    • Images
      • Screenshots
    • Video
    • Appearances
      • Create appearances
      • Use appearances
      • Delete appearances
    • Groups
      • Create groups
      • Edit groups
      • Delete groups
      • Group masters
    • Presets
      • Preset pools
      • Create new presets
      • Recipe presets
      • Use preset
      • Edit or Update presets
    • Worlds and Filters
      • At filter
      • Create a world
      • Create a filter
      • Use a world or filter
      • Delete a world
      • Delete a filter
    • MAtricks and Shuffle
      • Blocks
      • Groups
      • Wings
      • Widths
      • Shuffle
      • Transform
    • Cues and Sequences
      • What is tracking
      • Sequences sheet
      • Content sheet
      • Sequence settings
      • Store cues
      • Update cues
      • Copy cues
      • Cue recipes
      • Store settings and preferences
      • Play back cues
      • Move in black
      • Cue timing
      • Renumber cues
      • Delete cues
    • Executors
      • Assign object to an executor
      • Executor configurations
      • Running playbacks
      • Special executors
    • Masters
      • Selected masters
      • Grand masters
        • Time Control
      • Speed masters
      • Playback masters
    • Recipes
    • Phasers
      • Phaser editor
      • Create sinus dimmer phaser
      • Create circle phaser
      • Create circle phaser around position
      • Create color rainbow phaser
    • XYZ
      • Activating XYZ for fixture types
      • MArker fixture
    • Macros
      • Create macros
      • Edit macros
      • Assign macros to keys and buttons
      • Variables
      • Examples
    • Agenda
      • View modes
      • Create an agenda entry
      • Edit an agenda entry
      • Agenda toolbar
    • Timecode
      • What are timecode slots
      • Timecode settings
      • Track groups
      • Time ranges and events
      • Toggle view mode
      • Record a timecode show
      • Record an external timecode show
      • Edit a timecode show
    • Layouts
      • Create a layout
      • Assign multipatch fixtures
      • Edit layout
      • Layout view settings
      • Edit layout view
      • Edit layout elements
      • Layout encoder bar
    • Plugins
      • What is Lua?
      • Functions - Object-Free API
        • BuildDetails
        • Cmd
        • CmdIndirect
        • CmdIndirectWait
        • CmdObj
        • Confirm
        • DataPool
        • DefaultDisplayPositions
        • DeskLocked
        • Echo
        • ErrEcho
        • ErrPrintf
        • Export
        • ExportCSV
        • ExportJson
        • GetPath
        • GetShowFileStatus
        • GetSubfixture
        • GetSubfixtureCount
        • HookObjectChange
        • HostOS
        • HostSubType
        • HostType
        • Import
        • MasterPool
        • MessageBox
        • ObjectList
        • Patch
        • PopupInput
        • Printf
        • ProgrammerPart
        • ProgressBar
        • Pult
        • SelectedSequence
        • Selection
        • SelectionCount
        • SelectionFirst
        • SelectionNext
        • SerialNumber
        • ShowData
        • ShowSettings
        • TextInput
        • Timer
        • UserVariables
        • Version
      • Functions - Object API
        • Children
        • Dump
        • Export
        • HasActivePlayback
        • Import
        • ToAddr
    • Data Pools
    • System
      • Date and time
      • Clock
      • Desk lights
      • System information
      • System monitor
      • Info Window
    • Sound
      • Sound Window
    • Remote In and Out
      • DC remotes
      • MIDI remotes
      • DMX remotes
      • OSC
      • PSN
    • RDM
    • Control other MA Devices
      • grandMA3 Nodes
      • MA Network Switch
      • RemoteHID
    • Update the Software
      • Update grandMA3 consoles
      • Update grandMA3 Nodes
      • Update grandMA3 onPC windows hardware
      • Update grandMA3 viz-key
      • Network update
      • Delete update files
      • Troubleshooting
    • Fixture Types
      • Import fixture types
        • Import GDTF
      • Build fixture types
        • Insert fixture types
        • Insert DMX modes
        • Insert geometries
        • Insert models
        • Link models to geometries
        • Link DMX modes to geometries
      • Export fixture types
        • Export GDTF
    • File Management
      • SFTP connection
      • Import / Export Menu
      • Folder Structure
    • Shut down the System
    • Troubleshooting
      • Clean start
  • grandMA3 Quick Start Guide
  • grandMA3 Quick Manual consoles
  • grandMA3 Quick Manual processing units
  • grandMA3 Quick Manual Nodes
  • grandMA3 Quick Manual Nodes DIN-Rail
  • grandMA3 Quick Manual onPC command wing XT
  • grandMA3 Quick Manual onPC command wing
  • grandMA3 Quick Manual onPC fader wing
  • grandMA3 Quick Manual onPC rack-unit
  • grandMA3 Quick Manual viz-key
  • grandMA3 Quick Manual I/O Nodes
  • Release Notes
Select different version
 
Version 1.8

Plugins

Plugins are pieces of Lua code that can add features or functionality to the grandMA3. 

With plugins, it is possible to do more than what can be achieved with macros.

Important:
The creation and use of plugins can go deeper into the system than the "normal" usage of a console. Therefore the technical support team of MA Lighting may not be able to help you in all circumstances when using complex plugins, and plugins might have to be rewritten when migrating show files to future grandMA3 software versions.

The plugins are stored in the Plugins Pool.

Plugin pool window

 The pool can be created like any other using the Add Window pop-up.

Create a New Plugin

To create or add a plugin to the plugin pool, edit an empty pool object using any edit method.

The Edit UserPlugin pop-up opens:

Edit Plugin window

This editor can show the settings for the plugin if Setting is On in the title bar.

These are the settings:

  • Name:
    The name of the plugin. Tap this to edit the name.
  • Scribble:
    The assigned scribble. Tap this to select a scribble or open the editor to create a new one.
  • Appearance:
    The assigned appearance. Tap this to select an appearance or open the editor to create a new one.
  • Lock:
    Toggle this On to lock the plugin from changes.
  • Author:
    This can be used to add the name of the plugin author.
  • Version:
    This custom field can be used to indicate a version of the plugin.
  • Path:
    This is a path (sub-folders) for the files inside the plugin folder (gma3_library/datapools/plugins).
  • UserRights:
    This can be used to set the needed user rights for running this plugin.

A plugin can contain several Lua components but should at least have 1.

Create and Edit a Component

A Lua component contains the Lua code. Each component is usually one file.

Add the component by pressing and holding the New ComponentLua.

A new component can also be added by selecting a line in the component list and tapping Insert new ComponentLua. This creates a new line above the selected line.

Plugin with 1 added Lua component

Each component has some settings and some information. It is the different columns in the list.

  • Name:
    This is the name of the component.
  • Scribble:
    This is the assigned scribble - this is not displayed anywhere.
  • Appearance:
    This is the assigned appearance - this is not displayed anywhere.
  • FileName:
    This is the file name for the Lua component file. A file name is needed if the plugin is exported. Giving the component a name also creates a file name.
  • FilePath:
    This is a path (sub-folders) for the Lua file inside the plugin folder (gma3_library/datapools/plugins).
  • FileSize (Information only):
    This displays the file size of the Lua component file in bytes.
  • Installed:
    If this is set to Yes, the Lua components will be updated from the file archive they were imported from. This is useful when Lua files are edited and copied into the folder using an external editor.
    To update any changes in these Lua components, the ReloadPlugins keyword must be executed.
  • IsResource (Information only):
    This indicates if the Lua file is an internal resource stored in an internal library. These files are not stored in the showfile and are not streamed.
  • InStream (Information only):
    Yes means that the Lua code is saved in the show file and streamed in the session but stays as saved in the show file.
    No means that the Lua code is locally saved on the hard drive. The content of this Lua code can be updated using the ReloadPlugins keyword.
    Setting Installed to Yes will set InStream to No.
  • UserRights:
    This can be used to set user rights on specific components.
  • SyntaxError (Information only):
    If syntax errors prevent the Lua component from being loaded into the Lua engine, the SyntaxError property turns to Yes, and the component line turns red.

Select the component that needs to be edited and tap Edit.

This opens the Lua Input pop-up:

Empty Lua Input pop-up

Text can be copied into the pop-up from an external editor (when using the grandMA3 onPC), or it can be written directly in the pop-up.

Editing existing code can also be done in the Lua Input pop-up.

Line numbers help when troubleshooting code or as general help (the numbers are not part of the code). The number of the active line is in white color, and the others are in gray color.

When Tab is used to indent text, a gray ">" appears where the tab was pressed.

When the desired code is input, it needs to be saved by tapping Save in the title bar.

The title bar has other buttons:

  •  (Virtual Keyboard):
    This toggles the on-screen virtual keyboard.
  • Lua Code Templates:
    This toggles the Lua Code Templates that can be used as templates for writing new code. Learn more about this below.
  • API Description:
    This toggles the grandMA3-specific Lua API description on the right-hand side of the Lua Input. Learn more about this below.
  • (Undo):
    This undoes the last edit.
  •  (Redo):
    Thie redoes undoed actions.

After the code is saved, the Lua Input pop-up can be closed by tapping the  in the upper right corner.

Run a Plugin

The plugins can be run by tapping them in the pool or using the Plugin keyword.

Running the plugin will execute the first component. This component needs to call other components, or specific components can be called directly using this syntax:

Plugin [Plugin_Number or "Plugin_Name"].[Component_Number or "Component_Name"]

Plugins can also be assigned to executors and view buttons. Learn how in the Assign Object to an Executor topic.

Lua Code Templates

The templates are example codes that can be copied into the editor.

Restriction:
Using a template will delete any existing code.

Tap Lua Code Templates in the title bar to show the templates.

The Lua code templates

The different templates are shown next to each other, and there is a horizontal scroll bar making it possible to scroll through the different templates.

To import one of the templates, select it (yellow frame), and tap Use Template.

The templates can be closed without importing a template by tapping Lua Code Templates in the title bar or the Back in the lower left corner.

API Description

The API description can be shown on the right side of the Lue Input pop-up. It can be toggled On or Off by tapping API Description in the title bar.

It lists all the grandMA3-specific Lua functions and shows a short explanation of the required arguments and the return values.

The API description

There are three elements to the description. At the top is a search input field where text can be input to search the list of functions.

Below is the actual list of functions in alphabetic order. Selecting one shows the description of the selected function below the list.

Tapping the  in the description area adds the function to the Lua input code, with the arguments, at the cursor's current location.

Export a Plugin

The plugin can be exported from the Edit UserPlugin by tapping Export.

This creates an XML file for the plugin.

If the Lua components have a file name ending in ".lua", an extra LUA file is exported for the component. If there is no valid file name for the component, it is then stored in the XML file, coded in the "base64" format.

Restriction:
The Lua files are only exported if the Lua component has "Yes" in the "InStream".

Import a Plugin

All the required files are needed to import a plugin successfully. The XML file is always needed; if the Lua components are stored as extra Lua files, they are also needed. These files must be in the ../gma3_library/datapools/plugins folder on the desired drive.

  1. Create a new plugin.
  2. Tap Import.
  3. Select the desired drive and XML file.
  4. Tap Import.
  5. The plugin is imported, and the editor can be closed.

 




Sub topics

Select different version