List, create, rename and remove patch stages
gma3_patch_stagesList, create, rename, or remove venue stages in grandMA3's live patch, applying changes through an exclusive patch-edit session with read-back verification.
Instructions
Stages (areas of the venue, e.g. "Main Floor", "Basement"; gma3_patch_add takes one by name). action "list" (read-only, the live patch): each stage's index (its position), number, name and nameKind ("default": an empty Name or one set to "Stage ", which read alike; "explicit": any other), fixtures (all, sub-fixtures included) and topLevel, whether it has a Spaces list and how many spaces. "create" {name} or {names: [...]}: appends stages (Acquire, then Name; the bridge deletes what it appended on any problem). "rename" {stage, name}. "remove" {stage}: only an empty stage (no fixtures, no spaces) and never the first or the only one; stages after it move up a place, and one with a default name then reads its new number (refused when that is another stage's name; an unreadable Fixtures, Spaces or children list is a refusal too). stage: the index or the name. Names: no characters the console strips (" . , and the like), trimmed, unique among the stages ignoring case (a stage may change the case of its own name). Pre-checks (nothing sent on failure) read the live stages. 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 command line stays inside the edit patch with no Patch window open: the operator keeps the copy by typing ChangeDestination Root at the console (no way to discard it without the Patch menu is known). Needs bridge 0.19.0; a session in a stage with a Name needs bridge 0.45.0. The isolation check leaves out only the stages the change touches (appended or removed ones, and the Name and number of a renamed stage and of those moving up). verify reads the stages back from the live patch: names in order, no two alike, and every stage's fixture count (an unreadable count makes it unavailable, not matched). Removing uses Delete on Stages, not verified on a console yet. Needs bridge 0.48.0; the bridge's own re-check of a removal (unreadable lists, a name clash) needs bridge 0.49.0.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | create: the new stage's name; rename: the new name. | |
| names | No | create: several new stages at once (1-32), in order. | |
| stage | No | rename / remove: the stage's index (position, from list) or its name. | |
| action | Yes | "list" (read-only), "create", "rename" or "remove". | |
| verify | No | Read the patch back after the commit and compare (default true). | |
| exclusive | No | Required, must be true: confirms nobody else uses the console while this runs (see the description). Without it the call is refused and nothing is sent. Not needed for list. |