Software Documentation

Software Documentation


Hobbyist Pro Last updated: May 9, 2022

5 Effect macros

Effect macros are snippets of a show that you can re-insert as easily as inserting an individual effect.  Effect macros have a variety of uses, including:

  1. Saving re-usable script segments as building blocks from which to build new show designs with just a few clicks
  2. Saving short script sequences as motifs that can be re-inserted in the same positions or different positions
  3. Saving short DMX script sequences that always apply to the same fixtures in a show, no matter what fixtures (positions) are selected
  4. Saving effects or sequences that have keyboard shorts that you trigger in real time while playing or looping the show simulation to build a show on the fly

Technically, effect macros are just effects in the effects window.  Like other effects, effect macros have part numbers that identify them; and they can be inserted into the show by clicking on their effect icon in the effect window.  Unlike other effects, inserting an effect macro doesn’t add an instance of the effect macro’s part number to the script; instead it adds instances of all the effects that the effect macro represents.


Effect macros are like copy/paste

In a sense, effect macros are a lot like copy and paste.   Creating an effect macro is a lot like copying a sequence of effects from the script.  Inserting an effect macro is a lot like pasting the copied effects into the show.  In fact, effect macros are implemented by way of storing a compressed copy buffer in the VDL field, so it is no accident that effect macros and copy/paste are such similar operations.


Figure 1 – The “Script > Effect macros > Create effect macro from selection in script…” dialog


The effect macro functions in the Script menu include “Script > Effect macros > Create effect macro from selection in script…” which creates an effect macro from the selected effects and your choices in the dialog shown in Figure 1.  Like the copy/paste operation, effect macros contain within them not just the copied effects but also references to the positions from which the effects were copied.

Copy/paste has some complicated rules about what happens you paste, as fully explained in Copy/paste.  In brief, if the copied effects all stem from a single position, then they will be pasted in whatever positions are selected at the time of pasting, yielding duplicates if more than one position is selected.  If copied effects stem from multiple positions, then they will be pasted into the selected positions if exactly the same number of positions are selected as are referenced by the copied effects; otherwise the copied effects will be pasted into their original referenced positions no matter what.


Inserting at the recorded positions versus the currently selected positions

Effect macros work exactly like the paste operation if the checkbox “Applies to recorded positions no matter what positions are selected” is not checked.  If the checkbox is checked, then the effect macros always insert into the original positions.  The checkbox is generally ON for use cases like (1) and (3) and (4) as described above.  However use case (2) requires the checkbox OFF.  A common example of case (2) is a fanned flight or chain of shells.  Finale 3D has many features for inserting effects and creating fans, but if you create an effect macro from effects that are already in a fan, then inserting the fan is as easy as a single click.

Since effect macros created with the checkbox ON are bound to their original positions, the positions themselves play a role in the meaning of the macro.  Instead of calling such a macro “My Sequence 1” it would make more sense to call the macro “My Sequence 1 at front left ceiling fixtures” or something like that in order to make the positions explicit in the name of the macro.  Otherwise you would never know by looking at the macro what it applies to.  Since including the positions in the name of the macro makes so much sense, the create macro dialog automatically adds the positions to the macro name if the “Applies to recorded positions” checkbox is ON.   The name “My sequence 1” entered into the dialog becomes “My Sequence 1 [P01 P02 P03]” if it applies to those three positions.



Since effect macros can be bound to their original positions, you can build a show on the fly by clicking on effect macros or pressing their keyboard shortcuts while the show simulation is playing.  Each effect macro is like an instrument in music composition software, and clicking on the effect macro is like playing a note with the instrument.  Since it is nearly impossible to click on positions while a show simulation is playing, the only way the “on the fly” method works is if triggering an effect macro indicates not just the effects, but where they go — which is exactly what the “Applies to recorded positions” checkbox guarantees.

If you decide to try the “on the fly” scripting method, consider the “Looping” options in the show menu.  You can add loop start/stop markers to the show, and then play a section over and over again, layering in the effects by pressing the effect macro keyboard shortcuts while the show simulation is playing.


Changing the effects or position references contained within effect macros

Especially with DMX scripting but also possible with pyro, you may find yourself defining a set of effect macros for one group of effects or positions, and then wanting to create an entire duplicate set of the effect macros for a different set of effects or positions.   (If, for example, you want to create a set of 20 effect macros for various color par light effects — red, blue, yellow, etc. — then creating 20 effects for every single color would be tedious.  The “Find and replace inside macros” function provides another way.

Using the replace function, you can replace the effects or positions in a single effect macro or an entire batch of effect macros all at once, which can significantly cut down on the work required.  I find it useful to save my effect macro collections for different position sets as separate FDB effect files.  With that approach, I can duplicate the file, select all the effects in it, and use the replace function to create the variations of the entire file.


Figure 2 – The “Find and replace inside macros…” function changes the positions or effects contained in the macro.


The macro payload

Effect macros store their payload of information as a compressed copy buffer in their VDL field.  If you need to see the payload information of a macro in human readable form, for programmer-like purposes, you can do the menu item, “File > Admin > Decompress macros” to decompress the macro payloads in all selected effect macros in the effect window.  The maximum payload size is 10KB, so if decompressing would result in a larger size (for very large macros), the decompression operation will not work.