Check whether the gma3_mcp_bridge plugin inside grandMA3 onPC is reachable and report software version, show file, user, the Lua execution policy (whether gma3_lua is enabled on the console and its per-request time/instruction budget), the configured OSC fallback, and whether this server build matches its source checkout (server.build.state 'stale' means tools added or changed since the build are missing or out of date).

Fallback for when the bridge is not running: sends the command Plugin "gma3_mcp_bridge" to onPC over OSC (/cmd). Requires the OSC configuration in onPC (Menu > In & Out > OSC) to have Enable Input on and Receive Command = Yes on a line matching GMA3_OSC_PORT. Then waits briefly and pings the bridge.

Execute a grandMA3 command-line command exactly as it would be typed (without Please/Enter). Examples: "Go+ Sequence 1", "Fixture 1 Thru 10 At 50", "Store Cue 2 /Merge /NoConfirmation", "ClearAll", "FaderMaster Page 1.201 At 75 Fade 2". Returns the command line feedback (OK, Syntax Error, Illegal Command). Commands that produce output (List, etc.) print to the console history, not here; use gma3_get_object / gma3_list_children to read data. Via "osc" the command is sent fire-and-forget over OSC and no feedback is available.

Evaluate Lua 5.4 code inside the grandMA3 Lua engine and return the result(s) as JSON. The code is first compiled as an expression ('return '), then as a statement block. All grandMA3 Lua API functions are available (Cmd, ObjectList, DataPool, Root, ShowData, Patch, Programmer, SelectedSequence, GetCurrentCue, GetExecutor, GetVar/SetVar, Printf, Echo, Enums, ...). Object handles are returned as {name, class, addr, addrNative, index, childCount}; use handle:Get('Prop') to read properties, :Children(), :Count(), :Ptr(i). Examples: 'SelectedSequence().name', 'GetCurrentCue():Get("No")', 'DataPool().Sequences:Count()', 'local t={} for i,c in ipairs(ObjectList("Fixture Thru")) do t[#t+1]=c.name end return t'. Use gma3_lua_api to look up function signatures. This capability is OFF by default on the console: the operator enables it by starting the bridge with Plugin "gma3_mcp_bridge" "lua" or running Plugin "gma3_mcp_bridge" "lua on" (gma3_status shows the policy). Each request runs under the console's execution budget (default 5 s wall-clock / 20 M VM instructions, operator-configurable) and is aborted with an error when it exceeds it, so keep scripts short and prefer the structured tools (gma3_get_object, gma3_list_children, gma3_objects) for bulk reads. By default the console's own hook on the plugin thread is preserved, which means the instruction budget is NOT enforced and the deadline is only checked when the script yields or returns: a script that loops without yielding cannot be stopped (gma3_status shows lua.bounded; the result's budget.instructionHookEnforced says what applied). The operator can start the bridge with luahook=replace to enforce hard quotas. Because a script may call Cmd() or Set(), every gma3_lua request is serialised with this server's other mutations (it waits for a running workflow and blocks later ones while it runs).

Search the live grandMA3 Lua API descriptor (function name, arguments, return values) for both object-free functions (Cmd, ObjectList, …) and object methods (Get, Children, SetFader, …). Leave query empty to list everything.

Read an object from the show data: name, class, address, all properties (as display text), optionally the property schema and a listing of its children. Use this to inspect sequences, cues, executors, fixtures, presets, groups, macros, pages, settings, etc.

List the children of an object (e.g. cues of a sequence, items of a pool, executors of a page) with name, class, address and index, plus optional property values per child. Paginated.

Resolve a command-line object range to a list of objects with optional property values. Examples: "Fixture 1 Thru 20", "Fixture Thru" (all fixtures), "Group Thru", "Sequence 1 Thru 10", "Preset 4.1 Thru 4.20", "Page 1.201 Thru 1.215".

Return the raw grandMA3 Dump() text for an object: class, path, every property and child. Verbose; prefer gma3_get_object for structured data.

Set a property of a show object via the Lua Set() API, e.g. ref 'Sequence 1', property 'Name' or 'Tracking'; ref 'Sequence 1 Cue 2', property 'TrigTime'. Values are passed as text the way they would be typed in the editor (e.g. 'Yes', 'No', '2.5', 'Follow'). This modifies the show file.

Trigger a playback function on a sequence or executor. Equivalent to commands like 'Go+ Sequence 1', 'Off Executor 201', 'Load Sequence 1 Cue 5'. Targets: 'Sequence 3', 'Executor 201', 'Page 2.201', 'Sequence 1 Cue 4' (for load/go to a cue), 'Master 3.1', 'Macro 5', 'Group 2'.

Set a fader of a playback object (sequence, executor's assigned object, master) to a value 0..100 via the Lua SetFader API. Tokens: FaderMaster (default), FaderX, FaderXA, FaderXB, FaderTemp, FaderRate, FaderSpeed, FaderHighlight, FaderLowlight, FaderTime, FaderSolo. For a timed fade use gma3_command with e.g. 'FaderMaster Sequence 1 At 50 Fade 3'.

Read fader values and display text of a playback object (sequence, master, executor's object).

List all sequences in the selected data pool with cue count and whether they have active playback.

List the cues of a sequence with cue number, name, trigger and timing properties.

List executors on the current executor page with their assigned object, key/fader functions and master fader level. Executor numbers: 101-115 top row, 201-215 faders, 301-315 etc.

List fixtures in the patch with ID, name, fixture type and DMX patch. Paginated; use filter to restrict (e.g. 'Fixture 1 Thru 50').

List the objects of a pool in the selected data pool: Sequences, Groups, Presets (pool name like 'Presets' lists preset pools; use 'Preset 4' style ref via gma3_list_children for one pool), Macros, Pages, Worlds, Filters, Timecodes, Timers, Layouts, Views, Appearances, MAtricks, Plugins, Cameras, Sounds, ScreenConfigurations, Agendas, Images, Videos, Scribbles, Gels, Datapools.

Look up a topic in the grandMA3 user manual shipped with onPC. Pass a command keyword (e.g. 'Go', 'Store', 'Assign', 'SendOSC', 'Lua', 'At', 'Fade') or a topic phrase (e.g. 'osc', 'cue timing', 'phaser'). Returns the page text, or a list of matching pages to choose from.

Select fixtures by range or group in the programmer. Sends the selection expression as a command (e.g. Fixture 1 Thru 5, Group 3). CHANGES THE SELECTION: grandMA3 adds to the current selection when it has no active values and replaces it when values are active; set clear_first to send ClearSelection first for a deterministic result. Does NOT clear programmer values (ClearSelection only deselects). Verifies that Selection.CountTotalSelected is >= 1 afterwards and lists the selected members (first 50) for information; it does not assert exact membership. Serialised against this server's other mutations only, not against other operators or clients.

Set one attribute (Dimmer, Pan, Zoom, ColorRGB_R, ...) to an absolute value in the programmer. Sends Attribute "<name>" At Absolute [<unit keyword>] <value> after establishing the target. Target is explicit: fixtures (range/group) OR use_selection: true. With fixtures the tool sends ClearSelection and then SELECTS exactly those fixtures (the selection changes; previously selected fixtures are not affected unless add_to_selection is true). Never clears programmer values. Without unit the number is interpreted by the user profile's readout. Small explicit targets are pre-checked against the fixture type's attribute list (check_attributes), and after setting, the programmer is read back and compared per fixture in the unit sent (verify); a fixture without the attribute is a mismatch, not a success. Serialised against this server's other mutations only.

Set ColorRGB_R, ColorRGB_G and ColorRGB_B (each 0..100 %) in the programmer: three commands Attribute "ColorRGB_R" At Absolute Percent <r> etc., stopping at the first the console rejects (partial result). Target is explicit: fixtures OR use_selection: true. With fixtures the tool sends ClearSelection and then SELECTS exactly those fixtures (the selection changes; previously selected fixtures are not affected unless add_to_selection is true). Never clears programmer values. Only the documented ColorRGB_* attributes are supported. Small explicit targets are pre-checked against the fixture type's attributes (check_attributes); after setting, the programmer is read back and each fixture's R, G and B are compared in percent (verify), so a fixture without RGB is a mismatch, not a success. Serialised against this server's other mutations only.

Set Pan and/or Tilt in the programmer with explicit units: unit "degrees" sends Attribute "Pan" At Absolute Physical <v>, unit "percent" sends ... At Absolute Percent <v> (0..100). Pan first, then Tilt; stops at the first rejected command. Target is explicit: fixtures OR use_selection: true. With fixtures the tool sends ClearSelection and then SELECTS exactly those fixtures (the selection changes; previously selected fixtures are not affected unless add_to_selection is true). Never clears programmer values. Small explicit targets are pre-checked against the fixture type's attributes (check_attributes); after setting, the programmer is read back and Pan/Tilt are compared per fixture in the unit sent, converting degrees through each fixture's physical range (verify). A fixture without Pan/Tilt is a mismatch, not a success. Serialised against this server's other mutations only.

Explicit clear with a required mode: "selection" sends ClearSelection (deselects fixtures, keeps all programmer values); "active" sends ClearActive (deactivates values, keeps selection and values); "all" sends ClearAll (clears the selection AND discards every programmer value). Nothing is implied: one command per call. Verifies Selection.CountTotalSelected == 0 for selection/all; programmer values cannot be read back (unavailable for active). Serialised against this server's other mutations only.

Store the programmer content as a cue of a sequence (create, merge or overwrite), optionally with a name and cue timing (seconds). Sends one Store command (/NoConfirmation; /Merge or /Overwrite for those modes), then one Set() per given name/timing field on the part (part 0 for a cue): Name, CueInFade (fade), CueInDelay (delay), CueOutFade, CueOutDelay. Mode create first checks that the target does not exist and refuses (nothing sent) if it does; that check is a point-in-time read, not a transaction lock. The current fixture selection is not changed; the programmer is not cleared (no Clear is sent). Reads back existence, Name and the timing fields that were given; the store step and the read-back are reported separately. Stored fixture values (attribute data) are NOT verified; that needs gma3_cue_contents (FR-10). The mutation lock orders only this server's own mutations; it does not isolate the operation from another console operator or another client.

Store the programmer content into a part of a cue (Store Sequence n Cue c Part p). Part 0 is the main part that every cue has, so storing to part 0 is the same as storing the cue; parts 1..999 hold values with their own timing. Sends one Store command (/NoConfirmation; /Merge or /Overwrite for those modes), then one Set() per given name/timing field on the part (part 0 for a cue): Name, CueInFade (fade), CueInDelay (delay), CueOutFade, CueOutDelay. Mode create first checks that the target does not exist and refuses (nothing sent) if it does; that check is a point-in-time read, not a transaction lock. The current fixture selection is not changed; the programmer is not cleared (no Clear is sent). Reads back existence, Name and the timing fields that were given; the store step and the read-back are reported separately. Stored fixture values (attribute data) are NOT verified; that needs gma3_cue_contents (FR-10). The mutation lock orders only this server's own mutations; it does not isolate the operation from another console operator or another client.

Edit the timing of an existing cue part (default part 0, the cue's main part) with one Set() per given field: fade (CueInFade), delay (CueInDelay), out_fade (CueOutFade), out_delay (CueOutDelay), snap_delay (SnapDelay), all in seconds; 0 is a value. Only the given fields are changed. Refuses (nothing sent) when the cue part does not exist. No command-line command is sent; selection and programmer are untouched. Reads the changed fields back from the part. Stored fixture values are not touched or verified. The mutation lock orders only this server's own mutations; it does not isolate the operation from another console operator or another client.

Set how an existing cue is triggered: trigger "go" (manual), "time" (after time seconds; time required), "follow" (when the previous cue completes; optional time as extra delay), "sound" or "bpm" (no time). Sets the cue's TrigType and then TrigTime via Set(); no command-line command is sent, selection and programmer are untouched. Refuses (nothing sent) when the cue does not exist. Reads TrigType and TrigTime back. The mutation lock orders only this server's own mutations; it does not isolate the operation from another console operator or another client.

PLAYBACK MUTATION: sends Goto Sequence n Cue c [Fade s], which jumps the sequence to that cue and changes live output. Goto is a playback mutation. A succeeded outcome means the console accepted the command; the crossfade runs asynchronously and its completion is not verified. Refuses (nothing sent) when the cue does not exist. Does not change the selection or the programmer. Verification: not_requested (the current cue is not read back). The mutation lock orders only this server's own mutations; it does not isolate the operation from another console operator or another client.

Delete exactly one explicit cue with Delete Sequence n Cue c /NoConfirmation. Ranges (Thru, +) are rejected. Checks the cue exists first and refuses (nothing sent) when it does not. Verifies by reading existence back: matched when gone, mismatched when it still exists, unavailable when unreadable. Does not change the selection or the programmer. Never retried. The mutation lock orders only this server's own mutations; it does not isolate the operation from another console operator or another client.

Assign a sequence to an executor on an explicit page: sends 'Assign Sequence At Page .' (manual syntax). Before sending anything it checks read-only that the sequence and the page exist and what the executor currently holds; an executor holding a different object is only replaced with replace: true (otherwise the call fails with the previous assignment in the result), and an executor that already holds this sequence is left alone (alreadyAssigned: true, no command sent). Optional label: sends 'Label Page . ""' after assigning. On grandMA3 an executor has no label of its own: it shows its assigned object's name, so this RENAMES THE SEQUENCE itself, everywhere it appears (pools, other executors). If labelling fails after the assignment the outcome is partial. Does not change the fixture selection or the programmer and never sends Go/On/Off/Toggle or any playback keyword; whether the console changes the selected sequence on assignment is not controlled by this tool. verify (default true) reads the executor back and compares the assigned object (by name and class) and, when a label was given, the executor's displayed name and the sequence's own Name; executor configuration, fader/key functions and playback state are NOT verified. Mutations from this server are serialised, but another operator or client can still change the executor between the inspection and the assignment.

Label the object assigned to the executor at Page .: sends 'Label Page . ""'. On grandMA3 2.5.1 an executor has no label of its own and always shows its assigned object's name, so this RENAMES THE ASSIGNED SEQUENCE (or other object) everywhere it appears: in its pool and on every other executor it is assigned to. Fails before sending anything when the page does not exist or the executor is empty (nothing to label). Does not change the selection or the programmer and never sends a playback keyword. verify (default true) reads back the executor's displayed name and assigned object and the assigned object's own Name; nothing else is verified. Mutations from this server are serialised, but not isolated from other operators or clients.

List the attributes of one fixture or subfixture with stable identifiers (attribute name, attributeIndex, uiChannel), pretty name, feature/feature group, activation group, physical unit, natural readout, the channel function's DMX and physical ranges, defaults, optional channel sets, and the DMX address mapping (coarse/fine/ultra as universe.address) from the RT channels. Subfixtures of a compound fixture are listed explicitly (subfixtures[], with their patch index); pass Fixture 501.3 to inspect one. Works with gma3_lua disabled (structured bridge op, plugin >= 0.3.0). Read-only: never changes selection, programmer or playback. The fixture is resolved by fixture ID through the console (patch index is reported separately as subfixtureIndex, never assumed equal). source says whether rows came from the UI channel API ("uiChannels") or the static fixture-type walk ("fixtureTypeWalk", no uiChannel). Null fields were not supplied by the console (explicitly unavailable, never inferred). Results are paginated. Not available: current values (use gma3_programmer / gma3_fixture_output).

Structured view of active programmer values per UI channel (fixture, subfixture patch index, attribute, value, timing, phaser steps). Scope is explicit: all (every patched (sub)fixture, including unselected ones), selection (SelectionTable) or fixtures (an explicit range). Works with gma3_lua disabled (structured bridge op, plugin >= 0.3.0). Read-only: never changes selection, programmer or playback. ROWS ARE PROGRAMMER CONTENT, NOT OUTPUT VALUES (source "programmer"; use gma3_fixture_output/gma3_dmx for output). A row is emitted only when the console's activity masks show programmer data; value: 0 with present: true is a real zero, an absent row means no programmer value. Multi-step phasers keep every step in steps[] (value is null) with phaser-level fade/delay/speed/phase; phaser.supported is false with a reason when the API shape was unusable. coverage reports whether the scan was complete; when it is not (budget reached, API unavailable) the programmer is NOT claimed empty. Paginated. value is percent, valueRaw the 24-bit integer.

Current DMX output of one fixture or subfixture per RT channel: channel name, attribute, universe.address, raw value (8-bit per address, combined to 16/24-bit when fine/ultra addresses exist; bits and unit say which), derived percent, and where the fixture type's channel function is known a physical value (conversion: "linear from channel function") and the active channel set. Works with gma3_lua disabled (structured bridge op, plugin >= 0.3.0). Read-only: never changes selection, programmer or playback. Source is "dmx output": these are output levels, NOT programmer values. Not available: per-attribute cooked output (the API has none), values on a universe that is not granted on this onPC (value null plus a limitation). nonzero_only is an explicit filter (default false). Paginated.

Raw DMX output for an explicit universe and channel range (channels 1..512; universe 1..1024, further bounded by the console's universe count). unit is explicit: "raw8" (0..255 per address) or "percent" (0..100 as the console converts it). Works with gma3_lua disabled (structured bridge op, plugin >= 0.3.0). Read-only: never changes selection, programmer or playback. Source is "dmx output": output levels, NOT programmer values. A universe that is not granted on this onPC returns no values with granted: false and a limitation (never zeros). nonzero_only is an explicit filter. patched: true additionally maps each returned address to its fixture/channel through the RT channels (bounded; stated in limitations when skipped). 16-bit attributes appear as two separate 8-bit addresses.

Read what a cue stores without playing it back or loading it: cue properties (No, Name, TrigType, TrigTime, TrigSound, Release, Assert, Note), per part the timing (CueFade, CueDelay, CueInFade, CueInDelay, CueOutFade, CueOutDelay, SnapDelay), command, MIB settings, OwnDataPresent, and the recipes (selection, preset text plus the resolved preset reference or an explicit unresolved marker, values, FadeX/DelayX/SpeedX/PhaseX, enabled). expand_presets: true adds the referenced presets' data (GetPresetData) keyed by preset address. Works with gma3_lua disabled (structured bridge op, plugin >= 0.3.0). Read-only: never changes selection, programmer or playback. SUPPORTED MODE (onPC 2.5.1): recipe- and preset-based content only. NOT AVAILABLE: hard (non-recipe) fixture values stored in a part (storedValues is always null; a limitation is added when OwnDataPresent is Yes) and tracked/effective values (trackedValues: "not_reconstructed"; a part lists only what it stores). The fixtures filter applies to expanded preset data only (stated in limitations). Never sends Goto, Load or any playback command.

Explicit ownership for console key input across several calls (KB-05). acquire returns a leased interaction id bound to this server's bridge connection; pass it to gma3_hardkey/gma3_keyboard press and release, gma3_type and gma3_input_sequence. While it is open the bridge refuses commands, property changes, playback, faders and Lua from EVERY client with [busy] (reads stay available), so end it as soon as the interaction is done. renew moves the lease deadline (default 15 s, max 120 s; nothing is pressed). end releases every key the interaction holds (newest first), aborts its sequence and reports what stayed unresolved. An interaction is never resumed: after a lease expiry, a bridge reconnect or end, acquire a new one. Needs input enabled on the console (Plugin "gma3_mcp_bridge" "input=keyboard"); end works while input is disabled. Nothing here presses a key.

Press, release or tap a logical MA hardkey (PLEASE, STORE, ESC, CLEAR, OOPS, NUM0-9, EXEC with executor, MA) on the console through the bridge's keyboard backend: REAL console keys are pressed through the operator's shortcut table or a verified native route (MA = LeftShift, PLEASE = Enter redirect); unmapped, ambiguous or colliding routes are refused before dispatch. tap presses and releases with hold_ms (default 50, max 5000) and returns once the release was attempted; exclusive: true is the intended long-press (every other input is refused meanwhile). keys (2-4 logical keys) presses a combination in order and releases newest first (chord tap with action tap; a hold with action press). press holds the key until release or the interaction/lease ends and REQUIRES an interaction id (gma3_input_interaction acquire). While any key is held, an interaction is open or a release stayed unresolved, the bridge refuses commands/property/playback/fader/Lua from every client with [busy]. Input is OFF until the operator runs Plugin "gma3_mcp_bridge" "input=keyboard" (release works while off). Input is not display-scoped. The result never claims a UI effect: verification is unavailable unless an observable (aggregate MASTATE for MA) showed the expected value; a release on this backend is 'dispatched', never 'confirmed'. Nothing is retried or replayed; an uncertain dispatch is reported as unknown.

Press, release or tap a raw PC key (case-sensitive Enums.KeyboardCodes name: Enter, Escape, F1, 5, A, LeftShift ...) with shift/ctrl/alt/numlock passed explicitly on the press AND the release, through the console's Keyboard() emulation. What the key does depends on the operator's user profile, keyboard shortcut enablement and the focused UI element (a mapped key may edit a focused field instead of acting as a hardkey); nothing is substituted or resolved for you, prefer gma3_hardkey for MA keys. tap returns after the release was attempted; press REQUIRES an interaction id; release uses the stored press tuple. Same gate, ownership, busy and verification rules as gma3_hardkey: real keys, input OFF until the operator runs Plugin "gma3_mcp_bridge" "input=keyboard", not display-scoped, commands from every client are [busy] while a key is held, UI effect unverified, nothing retried or replayed.

Type Unicode text as one character event per code point into an EXPLICIT context. Which element receives characters cannot be observed from Lua, so acknowledge_focus: true is always required: you state that the command line (context 'command-line') or a text field (context 'text-field') is focused. 'command-line' is admitted only while the operator has disabled keyboard shortcuts (F10; with shortcuts enabled, characters never reach the command line and nothing is substituted) and is read back from the command line: matched when it shows the text; when it does not within the readback window the step is UNKNOWN and nothing after it runs. 'text-field' cannot be read back (verification unavailable) and must not be followed by PLEASE/Enter in the same sequence. Text is refused while an exclusive long-press is held or a held key's route changed. Text is typed in chunks by the bridge loop with the context rechecked between chunks; it stops with its progress (unknown) when shortcuts are toggled, a route changes or a long-press starts meanwhile. Newlines, tabs and other control characters are refused (up to 256 characters); text NEVER presses Enter, changes focus, opens an editor or toggles shortcuts: commit it with a separate gma3_hardkey PLEASE tap. Same gate and busy rules as gma3_hardkey (input OFF until the operator runs Plugin "gma3_mcp_bridge" "input=keyboard"; commands from every client are [busy] while it types). Nothing is retried or replayed; a character whose dispatch raised is reported as unknown at that position.

Run an ordered, bounded sequence of console input under one interaction owner: taps, presses, releases, combinations, text and waits (at most 16 steps, about 30 s of holds/waits/typing). The bridge validates EVERY step (routes, keys, text policy, context) before the first event; one invalid step means nothing is dispatched. Steps are then serviced one after another by the plugin loop (a tap waits for its release, text goes out in chunks with its context rechecked), and a failure stops the sequence: later steps are reported as skipped, keys the sequence still holds are released newest first, nothing is replayed. Each step ends succeeded, failed (nothing of it dispatched), unknown (a dispatch raised or a release stayed unresolved: the console may have received it) or skipped. A tap is complete only after its release was attempted; completed never means a UI effect was verified (see verification/readback). Pass interaction to run inside an acquired interaction, otherwise one is begun and ended for the sequence. Commands from every client are [busy] while it runs. Input is OFF until the operator runs Plugin "gma3_mcp_bridge" "input=keyboard". Real console keys are pressed.

Read-only: whether console input is enabled and on which backend (keyboard = real keys, fake = nothing reaches the console), the backend's limitations, this server's session, every ownership record (owner, logical key, stored PC tuple, state, lease and deadline, dispatch outcomes, aggregate MASTATE readback, unresolved cleanup failures), open interactions, the running or last sequence, capacity, and the busy descriptor the bridge applies to commands. Ownership records are responsibility for recovery, not physical key state (injected and physical input share one key state). Works while input is disabled; releases nothing.

Release every key held by this server's bridge session, newest first, with the stored press tuples (never re-resolved), and with recover: true also re-attempt the releases that stayed unresolved (a remapped or disabled shortcut, a release that raised). Works while input is disabled: this is the recovery path. A release on the keyboard backend is 'dispatched' (no per-key readback), an unresolved one is reported as unknown and stays as a record until it succeeds or the operator runs Plugin "gma3_mcp_bridge" "input recover". Only this server's keys are affected; another client's or a physical operator's keys are not.

Read-only console state for feedback (KB-06): command-line text, last command feedback, Blind/Highlight/Solo, Preview mode, a display's Preview bar, keyboard-shortcut enablement, aggregate MA state, current executor page, selected sequence, and per executor the assignment and fader level, per sequence its playback activity. Works with gma3_lua disabled, with console input disabled and while another client holds an input interaction; it acquires nothing and changes no console state (selection, command line, programmer, playback, focus). Every item carries available, value (null when unavailable, with a reason or error; false is an observed value), scope, source, observedAt and epoch. Items are read one after another, not as an atomic snapshot. lastCommand and maState are shared observations, not confirmation of a request or key owner; sequenceActive is playback activity, not executor button state; Freeze has no readable state and is always unavailable. With no arguments every parameterless reader is read (previewBar on display 1). Bridge op feedback.read (plugin >= 0.8.0).

Read-only. Lists the fixture types imported into the show with their DMX modes: number, name, manufacturer, short name, source, and per mode the DMX footprint, the number of DMX breaks and the channels per break. Use the type and mode numbers or names with gma3_patch_add. Only the show's own types are listed; importing a type from the library is not supported yet.

Read-only. Lists the show's fixtures from the live patch, every stage, sub-fixtures included, in patch order. Each fixture has FID, CID, ID type, name, fixture type, mode, patch address, DMX breaks, stage, depth, parent FID and sub-fixture count. Filter by FID range (fromFid/toFid; fixtures without a numeric FID are omitted when a range is given); paginated (limit default 200, max 2000).

Add count fixtures of one fixture type and DMX mode at consecutive FIDs from fid, patched consecutively from a DMX address (address, or the first free block found from findFreeFrom), or unpatched when neither is given. Pre-checks (nothing sent on failure): the FIDs are free, the whole block is free and fits inside one universe, the mode has a single DMX break. Fixtures are added at the top level of a stage (default: the first stage). Runs one patch session through the patch edit copy, never a dialog: read-only pre-checks (command line at Root, the copy closed, so nobody is in the Patch menu, no modal open, plus the tool's own checks), then enter the copy, apply the change there, an isolation check, commit, and read back. Requires exclusive: true. Patch changes need exclusive use of the console: the isolation check compares fingerprints of the copy and the live patch, left out the touched FIDs, over several seconds. It is best-effort detection of someone else's changes, not a guarantee, and on a mismatch nothing is committed and the copy is left open for the operator. A committed patch change has NO UNDO (Oops does not revert it). Takes about 10 s (mostly the isolation check). When a session cannot be finished, the copy is closed again only if it provably holds no change; otherwise the result says copyLeftOpen: true and the operator resolves it at the console (Menu > Patch, Save and Exit or Discard and Exit). Needs bridge 0.19.0. verify reads the new FIDs back: present, patch addresses, name (when given) and mode.

Change existing fixtures: per edit, a new DMX address (address), unpatch: true, and/or a new name. Addresses are applied together, so fixtures can swap addresses or move across their own current range. Pre-checks (nothing sent on failure): every FID exists, single-break modes only, and the new ranges overlap no other patched fixture. In the copy the bridge re-checks and restores every change of the call on any problem. Runs one patch session through the patch edit copy, never a dialog: read-only pre-checks (command line at Root, the copy closed, so nobody is in the Patch menu, no modal open, plus the tool's own checks), then enter the copy, apply the change there, an isolation check, commit, and read back. Requires exclusive: true. Patch changes need exclusive use of the console: the isolation check compares fingerprints of the copy and the live patch, left out the touched FIDs, over several seconds. It is best-effort detection of someone else's changes, not a guarantee, and on a mismatch nothing is committed and the copy is left open for the operator. A committed patch change has NO UNDO (Oops does not revert it). Takes about 10 s (mostly the isolation check). When a session cannot be finished, the copy is closed again only if it provably holds no change; otherwise the result says copyLeftOpen: true and the operator resolves it at the console (Menu > Patch, Save and Exit or Discard and Exit). Needs bridge 0.19.0. verify reads each edited fixture back (address and/or name).

Delete fixtures by FID from the patch, removing them from the show (with everything that refers to them, e.g. their values in cues and groups: the console handles references). Fixtures with sub-fixtures are refused. Pre-check (nothing sent on failure): every FID exists and has no sub-fixtures. Runs one patch session through the patch edit copy, never a dialog: read-only pre-checks (command line at Root, the copy closed, so nobody is in the Patch menu, no modal open, plus the tool's own checks), then enter the copy, apply the change there, an isolation check, commit, and read back. Requires exclusive: true. Patch changes need exclusive use of the console: the isolation check compares fingerprints of the copy and the live patch, left out the touched FIDs, over several seconds. It is best-effort detection of someone else's changes, not a guarantee, and on a mismatch nothing is committed and the copy is left open for the operator. A committed patch change has NO UNDO (Oops does not revert it). Takes about 10 s (mostly the isolation check). When a session cannot be finished, the copy is closed again only if it provably holds no change; otherwise the result says copyLeftOpen: true and the operator resolves it at the console (Menu > Patch, Save and Exit or Discard and Exit). Needs bridge 0.19.0. verify reads the FIDs back and checks they are gone.

Read-only. For Page .: the assigned object; the executor's key, MA-key, fader and encoder functions, Fix and Lock; the page lock; for a sequence executor also the allowed function choices, the sequence's playback settings (wrap_around, priority, restart_mode, release_first_cue, auto_start/stop, master_go_mode, protect flags, ...), its Lock, whether it has active playback, which object owns each protection setting, and every executor in the current data pool that references the same sequence (sequence settings apply to all of them). The sequence is read by the address the executor reports, so a sequence from another data pool is reported as such (dataPool: other, ref: null). A value that could not be read is null and listed in unreadable. Sends no command and changes nothing.

Set the key, MA-key, fader and encoder functions and Fix of the sequence executor at Page . by writing its properties (KeyPress, KeyUnpress, MAKeyPress, MAKeyUnpress, Fader, Encoder, EncoderLeft, EncoderRight, Fix; unlike 'Assign At', this never clears the unpress function). The executor must hold a sequence; functions are validated against the sequence lists before anything is sent (keys: Flash, Temp, Swap, Black and Time are key-only). Executor settings belong to this executor only; sequence settings (Wrap Around, priority, ...) are configured with gma3_configure_sequence. lock: true/false sets the executor's own Lock. A page lock also blocks executor changes. Never sends Go, On, Off, Toggle, Flash or any other playback keyword and does not touch the selection, the programmer or fader levels; playback state is read before and after (playback.activeBefore/activeAfter) and configuration alone does not start playback. A locked target is refused before anything is sent (the console silently ignores writes to it) unless unlock: true, which unlocks the owning object, applies the changes and locks it again (relocking is attempted even after a failed change). preview: true performs only the reads and returns the planned changes (from -> to); values already set are reported as unchanged and never sent. Each value is written with one 'set' request whose reply must read back the requested value, because the console silently keeps the previous value for anything it does not accept; the first failure stops the remaining changes. A value that could not be read is unknown, never a default: the call is refused when a value the plan depends on (requested property, Lock, page Lock) is missing, and a set reply without a value is an unknown step. verify (default true) reads every changed property and the lock back. Mutations from this server are serialised, but not isolated from other operators or clients.

Set a sequence's playback settings by writing its properties: wrap_around (a chase loops only with Wrap Around on and a trigger on its first cue), priority, restart_mode, release_first_cue, auto_start, auto_stop, master_go_mode, auto_fix, auto_stomp, tracking, soft_ltp, off_when_overridden, kill_protect, swap_protect (protection from the Kill/Swap playback actions, not from editing), use_executor_time, include_link_last_go, xfade_mode, xfade_reload. lock: true/false sets the sequence's own Lock. Tempo links (SB-06): rate_master (a speed master 1-16 or "none": the cue timing (fades, delays, trigger times) runs at its effective BPM / 60, so 60 BPM is 1:1), speed_master (the phasers in the cues follow it), rate_scale and speed_scale (One, Mul2..Mul256, Div2..Div256), speed_from_rate. Masters are linked by name; a master without a unique name is refused. While a rate master is linked, moving the sequence's rate fader moves the shared master. Settings belong to the sequence, so they apply to EVERY executor that references it: the tool scans all pages and lists them (references) and warns when other executors share the sequence. Cue triggers and timing are set with gma3_set_cue_trigger / gma3_set_cue_timing. Never sends Go, On, Off, Toggle, Flash or any other playback keyword and does not touch the selection, the programmer or fader levels; playback state is read before and after (playback.activeBefore/activeAfter) and configuration alone does not start playback. A locked target is refused before anything is sent (the console silently ignores writes to it) unless unlock: true, which unlocks the owning object, applies the changes and locks it again (relocking is attempted even after a failed change). preview: true performs only the reads and returns the planned changes (from -> to); values already set are reported as unchanged and never sent. Each value is written with one 'set' request whose reply must read back the requested value, because the console silently keeps the previous value for anything it does not accept; the first failure stops the remaining changes. A value that could not be read is unknown, never a default: the call is refused when a value the plan depends on (requested property, Lock, page Lock) is missing, and a set reply without a value is an unknown step. verify (default true) reads every changed property and the lock back. Mutations from this server are serialised, but not isolated from other operators or clients.

Read-only. With group: the stored fixtures of Group (in the console's stored order, which is patch order) with their selection-grid X/Y/Z cells, PreserveGridPositions, lock, shared cells, bounds and gap count, read from the group's stored data (nothing is selected). Without group: the current selection in the order it was selected, with its grid cells (MAtricks-transformed when MAtricks is active). Distributions follow the cells, not the list order. Fixture ids are FIDs or dotted cell ids ("501.1"). Grid cells are the selection grid MAtricks and phasers use, not physical stage positions. Needs bridge 0.21.0.

Create or overwrite Group from a fixture list with explicit selection-grid cells. The cells are the order: the console stores a group in patch order and MAtricks, phasers and At a Thru b distribute along the grid, not along the list. Give either items ([{fixture, x, y, z}]) or an arrangement helper that expands into such a list: row (along one axis), rectangle (row by row, optional serpentine), mirror (left and right halves listed outside-in, right[i] mirrors left[i], optional centre gap). preview: true returns the expanded list, bounds, gaps and shared cells without sending anything. Rules: duplicate fixtures are refused (the console silently ignores a second selection); shared cells are refused unless allow_shared_cells: true; gaps and offsets are kept (preserve_grid_positions, default true; false lets a recall at the origin compact them); a fixture and its own cells (501, 501.1) are separate items; missing fixtures are refused. An existing group needs overwrite: true (its name is kept unless name is given); a locked group is refused. Requires exclusive: true (not for preview): the tool clears the console's fixture selection (programmer values are kept), selects each fixture after its own 'Grid x/y/z' command, checks that the selection is exactly the plan before 'Store Group', sets PreserveGridPositions and the name, then (verify, default true) reads the stored group back and recalls it at Grid 0/0/0 to check order and cells, and finally clears the selection and returns the cursor to 0/0/0. Grid cells are not physical stage positions. Needs bridge 0.21.0.

Read-only. The per-axis settings of MAtricks : wings, blocks, groups, width, shift, shuffle, and the fade/delay (seconds), phase (degrees) and speed (BPM) distributions as {from, to}; null means None. Also lists other settings that differ from a fresh MAtricks. Sends no command.

Set MAtricks per axis (x, y, z): wings, blocks, groups, width, shift, shuffle (null or 0 = None) and fade/delay (seconds), phase (degrees), speed (BPM) distributions as {from, to}. With wings, a distribution runs from the outer edges (from) to the centre (to), so a centre-out delay is wings 2 with delay {from: , to: 0}. create: true creates a missing object with 'Store MAtricks ' and then writes EVERY property (Store copies the programmer's selection MAtricks), so the new object holds exactly the request; reset_unspecified: true does the same for an existing one. Otherwise only the given settings change; values already set are not sent. Each value is one 'set' whose reply must read back the requested value (the console silently ignores values it does not accept); the first failure stops the rest. A locked MAtricks is refused. Does not touch the selection or the programmer; apply it with 'Recall MAtricks '. preview: true reports the planned changes.

Read-only. preset: "." returns what the preset actually stores: per fixture and attribute the mode the value was stored in (selective; global, held by the lowest FID of a fixture type; universal, one holder), value (percent) or steps (each with absolute/relative, width, trans, accel, decel and the preset it integrates; absent layers are the console defaults width/trans 100, accel/decel 0), the phaser layers speedBpm, phase (degrees), measure (beats) and speedMaster (absent: 60 BPM, phase 0), fade/delay, and the source preset of an embedded value; plus PresetMode, StoredData, lock, how many objects reference it, and its dependencies (embedded sources) followed recursively with validity (a deleted source is an invalid dependency) and whether that inspection was complete. pool: returns the pool's default mode and input filter and the operator's store preferences (the defaults a store would otherwise use). Needs bridge 0.22.0.

Store the current programmer content into Preset .. Prepare the programmer first (gma3_select, gma3_set_attribute/color/position, At Preset ... for embedding); this tool only stores. Explicit rules: mode selective | global | universal (never the pool default: a default store resolves a mode conflict silently and can keep one fixture's values), or force global | universal for a forced conversion of an existing preset (removes its selective, or selective and global, data; needs existing: "merge"). existing: refuse (default) | merge | overwrite. fixtures: the scope; every active programmer value must belong to these fixtures (a fixture includes its cells) and each must have one; attributes (optional): exact attribute filter (an activation group, e.g. all ColorRGB_*, is activated as a whole); layers (default [absolute]; also relative, fade, delay, phaser) must cover every value's layers. Anything else in the programmer is refused, because the console stores every active value regardless of the selection. Also refused: universal mode with values that differ between fixtures, embed without a preset reference in the programmer, attributes a feature-group pool's input filter would drop (store into an All pool 21-25 or pass input_filter: false), a locked preset. embed (default false) stores references to the presets active in the programmer; matricks (default false) the selection MAtricks; keep_activation (default false); input_filter overrides the operator default for this store only. The command always carries /Programmer /Active, the mode, /Merge or /Overwrite, /Embed, /MAtricks, /KeepActivation and /NoConfirmation, so the operator's store preferences decide nothing and are not changed (read before and after); Look cannot be overridden per store, so the tool refuses while the operator's StoreLook preference is on. Requires exclusive: true (not for preview). verify (default true) reads the stored rows back and checks each programmer value by mode, value, layers and reference, unexpected content, the preset's mode, dependencies (recursively; incomplete inspection is reported) and that the store preferences are unchanged. Needs bridge 0.22.0.

Build a repeatable effect from structured steps and store it into Preset ., reading every step back. Steps: per attribute an absolute and/or relative value (unit percent, or physical: degrees for Pan/Tilt) or a preset called into the step, plus step timing (width, transition, accel, decel). phaser: fixture distribution (phase {from, to} in degrees over the selection grid; from > to runs the other way; repeat {groups|wings|blocks: n} repeats it along X) and playback speed (speed_bpm, measure in beats, speed_master 1-16). These three are kept apart in the plan and the result. Templates (instead of steps): dimmer_chase {on, off, speed_bpm, spread}, alternating_colors {colors: [{red, green, blue} or {preset}], x2, speed_bpm, snap}, pan_tilt {pan, tilt (degrees), speed_bpm, spread}: a relative circle around the current position. preview: true returns the expanded steps and the console commands. fixtures are selected in list order on grid X (or group: a stored group with its grid). Every attribute is checked against every fixture before anything is sent (the console ignores unsupported attributes silently). The effect is built in the console's Preview environment (its own empty programmer; nothing is output) and the operator's Normal programmer is fingerprinted before and after: it is never touched. The built programmer is checked per fixture, step and layer, including the phase per fixture, then stored with the gma3_store_preset rules (mode selective or global, existing refuse|merge|overwrite, step presets embedded) and verified step by step; the Preview programmer is cleared and Preview left in every case. audition_ms (default 0: no playback) calls the stored preset on the fixtures in the Normal programmer, which must be empty, for that long and releases it with ClearAll. Requires exclusive: true (not for preview). If a build is interrupted, gma3_phaser_release leaves Preview. Needs bridge 0.23.0.

The stop/release path for gma3_build_phaser: when the console is in the Preview environment (an interrupted build), clears the Preview programmer and leaves Preview. clear_normal: true (with exclusive: true) also clears the Normal programmer (ClearAll), which stops an effect called there. Reports the environment and what is left.

Read-only. target: {preset: "N.M"} or {sequence, cue, part?} (part 0 by default). Returns every recipe line (standard and phaser) with its selection (group and its members), values (preset), MAtricks, filter, Enabled, SelectionMode, the console's last cooking state, and problems (missing or empty group, missing preset, disabled), plus the target's coverage: per fixture which attributes are cooked (from recipes) and which are stored directly. Lines whose coverage is not predicted (phaser recipes, filters) are flagged; presets that embed others are noted. Needs bridge 0.24.0.

Edit one standard recipe line of a preset or cue part (the target must exist). action add {selection: group, values: "N.M" preset, matricks?, name?, enabled?, selection_mode?} appends a line; set {line, ...fields} changes it (values: null clears the values); move {line, to} reorders; remove {line} deletes it. References are checked first; the result reads every line back (the edited one and that the others are unchanged or moved as asked). The console re-cooks an edited line by itself (MergeLowPriority) and a removed line's output disappears: the result shows the target's coverage before and after (autoCooked). The console also re-cooks a group or preset change by itself a moment later (in the background); gma3_cook_recipes cooks at once, verifies, and offers Merge, Overwrite and Remove. enabled: false switches a new line off before it gets values, so it never cooks. Phaser lines, filters and timing columns are not edited by this release. preview: true returns the planned commands.

Cook the recipes of a preset, a cue part, a cue (all its parts) or a whole sequence, at once and verified (the console also re-cooks group and preset changes by itself in the background a moment later, with merge low priority). mode is required: merge_low_priority (replaces cooked data, keeps every uncooked value), merge (also replaces uncooked values on the recipes' own fixtures and attributes), overwrite (deletes every uncooked value), remove (removes cooked data). First every affected target is listed with its lines, their problems (missing or empty group, missing preset), the coverage before and the cooked coverage the lines should give; merge and overwrite are refused while they would replace or delete uncooked values unless replace_uncooked: true. preview: true stops there. After Cook <target> /<Option> (verify, default true) each target is read back: every predicted fixture and attribute cooked, no cooked values on fixtures no line selects, uncooked values unchanged (merge_low_priority, remove) or changed only where allowed. Lines that are not predicted (phaser recipes, filters) are named; presets that embed other presets are noted (their recipes are not re-cooked). Needs bridge 0.24.0.

Read-only. The 16 speed masters (Master 3.N): name, fader, base BPM (from the fader: 50 = 60 BPM), speed scale, effective BPM (base x scale, what followers use), the console's own tempo text, learn mode, lock and problems (duplicate names make links ambiguous). usage (default true): per master the sequences that follow it by speed (phasers in their cues) and by rate (cue timing; the rate is effective BPM / 60 x RateScale) and the executors holding it. sound (default true): the onPC audio input device, the available devices, the SoundIn level and master 16 (the BPM master, driven by the input); beat detection and lock are not readable on 2.5.1, so synchronisation is never claimed. observe_seconds (0-10): samples the masters (master 16 when masters is not given) and reports how they moved. Distinct from timing masters (pool 5, fixed seconds) and cue timing.

Sets one speed master (1-16): the tempo as bpm, hz or seconds (one of them; it is the EFFECTIVE tempo under the final speed scale, 0 stops the master, at most 225 x the scale factor), speed_scale (One, Mul2..Mul256, Div2..Div256 or a power-of-two factor) and learn_mode (ignore_scale, respect_scale, auto_increase_scale: how taps treat the scale). Sends set LearnMode, set SpeedScale and Master 3.N At BPM x, in that order. Refuses a locked master. Every sequence linked to the master follows the change (named in warnings). Master 16 follows the sound input and may move again. Reads the fader and scale back (verify, default true); preview: true sends nothing.

action learn: Learn Master 3.N, one tap (the console times the taps itself; taps with interval_ms send several, with the network's jitter); double / half: DoubleSpeed / HalfSpeed (the speed scale one step up or down, the fader stays); reset: Speed1 (60 BPM, scale One). Refuses a locked master. Verifies the scale and tempo afterwards; a single tap cannot be verified (the console needs an interval).

Read-only. Samples the current cue of 1-8 running sequences for seconds (1-30, default 6) every interval_ms (default 40) and reports the observed step interval next to the configured one: the rate (rate master's effective BPM / 60 x RateScale, or the sequence's own rate fader) and, for chases whose cues are all Time-triggered with one trigger time, the predicted step interval. It starts nothing: run the sequences first. The phaser tempo (speed master) is reported as configured only; phaser output is not observable over the bridge.

Read-only. Without macro: the macro pool (number, name, line count; offset/limit, default 100). With macro: its name, note, lock, CLI, the line it is running now (null when idle) and every line exactly as stored (command, wait as seconds / "follow" / "go", enabled, add_to_cmdline, execute, name, note; a name of null is the default). check_references: true also lists the objects each line refers to (Sequence, Cue, Macro, Group, Preset, MAtricks, Page, Master, ...) and whether they exist.

mode (required): create (refuses an existing macro), replace (removes the existing lines first, keeping the macro, its appearance and its executor assignments) or append (adds after the existing lines). lines: [{command, wait (seconds, "follow" or "go" = a manual wait until the next Go+), enabled, add_to_cmdline, execute, name, note, raw}]; name, note, cli of the macro. Before anything is sent the references in each line are checked (single objects named with full keywords; a Store earlier in the macro counts as creating its object); raw: true stores a line unchecked. Refuses a locked or running macro. Sends Store Macro N, Delete/Store Macro N.L and one set per property; NEVER runs the macro. The console rewrites command text outside quotes (trims, collapses spaces, expands abbreviated keywords): every line is read back and compared exactly; a rewritten line is a mismatch unless accept_console_form: true (it is reported in rewritten either way).

action insert (line 1..count+1, needs command), set (any of command, wait, enabled, add_to_cmdline, execute, name, note), move (line -> to; sent as upward moves only, because a downward Move lands one place short), remove. References in a written command are checked unless raw: true. Refuses a locked or running macro. Every line is read back and compared with the expected order and content; accept_console_form as in gma3_store_macro. Never runs the macro.

EXECUTES: action go sends Go+ Macro N (starts it, or continues it after a Go wait); off sends Off Macro N. Then observes the macro's running line for observe_seconds (default 3, max 60): finished, paused_at_go (a manual wait), running, idle. The result separates dispatched (the command was accepted) from observed (the run state seen); it never claims that every line succeeded, because a failing line does not stop a macro. Lines with a (prompt) ask the operator for input.

Read-only. Without timecode: the timecode pool. With timecode: name, playing, cursor and duration (seconds), the source (tc_slot internal / slot N, offset, auto start/stop), playback settings (loop mode and count, switch off, assert previous events), recording settings (the armed state is not readable; these tools never record), and every track group, track (its target) and event: time in seconds and as H:MM:SS.sss (or H:MM:SS:FF with fps 24/25/30/60), exact raw time, action (go, goto, off, flash_press, ...), cue. problems names tracks without a target, Goto events without a cue and unmodelled tokens. slots: true lists the 16 timecode slots (their time only: external reception is not readable). Needs bridge 0.25.0.

mode (required): create (refuses an existing show), replace (removes its track groups, keeps the show) or append (adds a track group). tracks: [{sequence, events: [{at, action, cue?}]}]: at is seconds, "H:MM:SS.sss", "H:MM:SS:FF" (with fps 24, 25, 30 or 60) or {frames, fps}, rounded to the console's 1/16777216 s; action is go (Go+), go_back, goto (needs cue), on, off, toggle, top, pause, kill, flash_press / flash_release, temp_press / temp_release (pairs are checked: allow_unpaired to override). Events are stored in time order; events at the same time keep the order given (the console runs them in storage order). settings: loop_mode (loop, pause, off), loop_count, tc_slot ("internal" or 1-16: configures the source only), switch_off (keep, off), assert_previous_events. Sequences and cues are checked before anything is sent; a playing or locked show is refused. Every event is read back and compared exactly. Never sends Go, Record or anything that plays. Needs bridge 0.25.0.

PLAYS when asked: play sends Go Timecode N (from the cursor, internal time; with a timecode slot the time comes from the slot), stop sends Off (playbacks it started keep running unless switch_off is off), rewind sends Top, seek writes the cursor (to: a time as in gma3_build_timecode). Recording is not offered. Then samples the cursor and the target sequences for observe_seconds (play: default 5) and, for play, checks every event the cursor crossed against the sequences' observed cue changes in order (goto -> that cue, go -> the next cue, off -> off, presses -> running; others are listed as not predictable). The result separates dispatched from observed.