Add fixtures to the patch
gma3_patch_addAdds one or more fixtures of one type and DMX mode at consecutive FIDs, patching them to a DMX address, the first free block, or unpatched, with pre-checks and read-back verification.
Instructions
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 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. verify reads the new FIDs back: present, patch addresses, name (when given) and mode. With count above 1 a clean success lists each new fixture as {fid, name, address} in items (detail: true for the full rows).
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| fid | Yes | First fixture ID; the block uses fid .. fid+count-1, all of which must be free. | |
| mode | Yes | DMX mode number or name within that type. | |
| name | No | Optional name for the new fixtures (default: the console's naming). | |
| type | Yes | Fixture type number or name, as gma3_patch_types lists it. | |
| count | No | Number of fixtures (1-256, default 1). | |
| stage | No | Stage name (default: the first stage). A stage with a Name needs bridge 0.45.0. | |
| detail | No | Return the full result on a success too: every step's detail and each fixture's state before and after (default false: a clean success, committed and read back matched or not requested, lists one entry per fixture in items; anything else is always returned in full). | |
| verify | No | Read the patch back after the commit and compare (default true). | |
| address | No | DMX start address "U.AAA" (e.g. "2.001"); the block must be free and inside one universe. | |
| 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. | |
| findFreeFrom | No | Instead of address: use the first free block from this "U.AAA". |