Store a group with an explicit selection grid
gma3_store_groupCreates or overwrites a fixture group with explicit grid-cell order, expanding row, rectangle, mirror, or rows arrangements; previews and verifies the stored selection before use.
Instructions
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), rows (one row per list, each spread over width cells). 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. A name another group already has is refused before anything is sent, naming the holder (the pool's names are read once per call, compared case-insensitively; a duplicate makes lookups by name ambiguous, and whether the console would store "#2" is not verified for groups); on_name_taken: refuse (default) | allow_suffix (store anyway; a "#" read-back is a warning, not a mismatch). In the batch form a name an earlier group of the call was stored under counts as taken. 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 (a one-fixture group is recalled at the cursor, so its recall checks the fixture and the read-back its cell), 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. rows: rows of different lengths spread over one width (align spread, start or center); ranges run in their own direction ("402.36 Thru 402.1"). Batch form: give the list instead of the single object's fields; the other arguments are defaults for every item (an item's own fields win). Each item gets the single form's checks and read-back, and its own outcome; items run in order, nothing is retried, an unknown outcome stops the rest, and the result has one line per item (detail: true for every step).
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | Group name (a new group is otherwise named by the console). | |
| group | No | Group number (1-9999). Required unless groups is given. | |
| items | No | Explicit list; each fixture once. The cells define the order distributions follow (the console stores the group in patch order). | |
| detail | No | Return every item's full result with its steps (default false: one line per item). | |
| groups | No | Batch form: several groups, each {group, name, items | arrangement, overwrite, ...}, stored one after the other. | |
| verify | No | Read back and recall-check the stored group (default true). | |
| preview | No | Only expand, analyse and check; send nothing (default false). | |
| data_pool | No | Data pool number (DataPool n). Default: the current data pool, as without this parameter. | |
| exclusive | No | Required (true) unless preview: nobody else uses the console's selection while the tool runs. | |
| overwrite | No | Replace an existing group (default false: refuse). | |
| arrangement | No | Helper that expands into the explicit list (see preview). | |
| on_name_taken | No | When another group has the name: refuse (default, nothing is sent) or allow_suffix (store anyway). | |
| stop_on_failure | No | Batch form: stop at the first item that does not succeed (default false: independent items go on; an item on an object an earlier item failed on is skipped either way). | |
| allow_shared_cells | No | Allow two fixtures in one cell (default false: refuse). | |
| preserve_grid_positions | No | Store with PreserveGridPositions (default true). |