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: Saving re-usable script segments as building blocks from which to build new show designs with just a few clicks Saving short script sequences as motifs that can be re-inserted in the same positions or different positions Saving short DMX script sequences that always apply to the same fixtures in a show, no matter what fixtures (positions) are selected 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.   Looping 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.  

If creating effect definitions one at a time using the dialog of Creating fixture definitions and effects for your own fixtures is too slow, programmers can create batches of effects manually by copying effects for existing fixtures and modifying them.   This article lays out instructions for the manual process.   Step 1: Find a similar fixture that is already supported Look over the lists here for lights and here for flames and sparks to find a fixture similar to yours that is already supported.   First narrow the candidates down by general category -- par light, moving head light, sparks machine, moving head flame projector, etc.  Within that category, find the candidates that have similar properties to your own fixture.  For example, does the par light have RGB, or RGBW, or RGBW + Amber + UV, a color wheel, etc. Next, decide whether the effects lists for the candidates match what you are looking for.  Create a new show and right-click a position to configure it as a fixture.  Configure the position as the type of fixture you want to examine, and then right-click the position again to do "Filter effects window to compatible DMX effects".  Look at the effects in the effect window to see if they match what you'd like for your own fixture. If the effects look like a good match, find the documentation for the fixture in the Light fixtures articles or Flame and spark fixtures articles in the documentation here.  Compare the DMX channel specifications (DMX personality) of the fixtures in the documentation to your fixture's user manual.  The more similar they are, the easier the task of creating your fixture definition from an existing starting point.  Choose the similar fixture that looks like the best starting point for making your own fixture.   Step 2: Choose a fixture ID for your fixture Fixture IDs and effect IDs make it possible to convert effects from one fixture to another (Fixture cloning).  The fixture IDs also make it possible for the Finale 3D user interface to filter the effect choices that can be added to a fixture according to their compatibility, and to error check at times of addressing and exporting that the show does not contain any incompatibilities. The Standard Fixture IDs for pre-defined fixtures are integers from 1 to 999,999 excluding 100-199 (see Standard Effect IDs and Standard Fixture IDs).  User-defined fixture IDs are in the range 100-199, so you can simply give your fixture the fixture ID 100.  If you are implementing multiple new fixture types, the next can be 101, and so on, counting up.   Thus all your user-defined fixtures will be distinguished from one another and none of them will conflict with the fixtures already defined in Finale 3D.   Step 3: Copy the effects from the similar fixture and modify the part numbers and fixture IDs Create a new show to work with if haven't already done so in Step 1.  In the effects window, copy the effect rows from the similar fixture, in whatever collection they are in, into the Per-show effects collection of your own show.   You can copy rows by selecting them, and then pressing Control-C, then switching to the Per-Show effects collection and pressing Control-V to paste. Rename all the part numbers of the effects to unique new part numbers, to avoid conflicts.  There's no rule, but it is a good idea to make part numbers all upper case, with no spaces or special characters, and fewer than sixteen characters.  It is also useful to make the part numbers recognizably linked to your fixture or the fixture's manufacturer by starting out with a few characters that are the initials of the manufacturer or brand.  For example, the part number "TS11211" identifies one of the effects for Tomshine light fixtures. To edit the part numbers, you can double click on the part number field of a row and edit it directly in the table, or you can select the entire column of part numbers and copy/paste it into a text editor or into Excel, edit the part numbers there, and then copy them back over the selected column of cells. After editing the part numbers, the next step is to edit the descriptions of the effects to change the fixture ID references to the fixture ID you decided on in Step 2.  The fixture ID is the first number in square brackets in the description.  For example, the Tomshine part number TS11211 in the Generic Effects collection has the description, TSMHG80W [027/1011] Red Flash (lg) In your copied effects, if your fixture ID is 100 then change the description to the following (and change the word "MYFIXTURE" to a short nickname of your fixture): MYFIXTURE [100/1011] Red Flash (lg) You may find it easier to copy the effect descriptions into a text editor or Excel, and then make the changes there and copy them back since you can use find and replace functions to make the substitutions in a text editor.  The second number inside the brackets (1011 in this example) is the effect ID.  Assuming your modified effect is equivalent to the original except applying to a different fixture, the effect IDs should stay the same.  In this example, just leave the 1011 as is.   Step 4: Write a "Fixture Definition" and copy it into the Custom Part Field of all the effects Unhide the Custom Part Field column in the effects window and replace or modify the fixture definitions with a fixture definition for your own fixture.  Fixture definitions for pre-defined fixtures in Finale 3D are incorporated directly into the program, so if you are basing your fixture off a pre-defined fixture it is likely the Custom Part Field will be empty.  The exception is the Explo X2 Wave Flamer and compatible fixtures from other manufacturers, which use the Custom Part Field for a different purpose (see Explo X2 Wave Flamer).  If you are basing your fixture on the Explo X2 Wave Flamer, please contact Finale for assistance. For user-defined fixtures, the fixture definition will be stored in the Custom Part Field of every effect for the fixture.  A show with multiple effects for the same user-defined fixture may therefore contain multiple copies of the same fixture definition in its effects.  The redundancy serves to ensure that even if a show contains just one of the effects for your fixture, it is sure to have a fixture definition stored in the effect itself. Please see User-defined fixture definitions for instructions to create your fixture definition.  It is just a single line of text that you can copy into the Custom Part Field cells of your effects, along side the modified part numbers and descriptions.  An example Custom Part Field for the Tomshine fixture is: {[name "Tomshine [] Moving Head Gobo 9CH"][fixtureId 100][numChannels 9][defaultEffectPartNumber TS11301][channelLabels {[0 "Pan"][1 "Tilt"][2 "Motor Speed"][3 "Dimmer"][4 "Strobe"][5 "Color"][6 "Gobo"][7 "Set To Zero"][8 "Set To Zero"]}]} Fixture definitions in the Custom Part Field are case-sensitive and unforgiving with respect to missing punctuation, so please ensure you have matching brackets, double quotes, etc.   Step 5: Write DMX Patches for your fixture's effects Unhide the DMX Patch column of the effects window.  The effects you are working on will already have DMX Patches for their original fixture.  You'll need to replace the DMX Patches with the equivalents that work with your fixture.  DMX Patches are small computer programs that calculate the DMX channel values that implement the effect for your fixture, taking into consideration (for certain types of effects) the angle of the dotted line effect trajectory in the user interface and the duration of the effect if the user has modified it in the timeline or script window.  An example DMX Patch for the Tomshine fixture is, [setupBeginEndPatch 1000 0 :pan540 :pan540 :pan540 1 :rTilt230 :rTilt230 :rTilt230 2 0 0 0 3 0 255 0 5 12 12 12] The terms and numbers in the DMX Patches are explained in The DMX Patch field, which provides the instructions you'll need to implement your own DMX Patches.   Step 6: Modify the VDL of your fixture's effects if necessary If the effects you are creating for your own fixture have the same visual appearance as they do for the fixture you are copying, then you don't need to modify the VDL at all.  Just leave it as is.  If the effects are different -- taller, bushier, etc. -- then you can edit the VDL to customize the appearance, just as you can edit any of the pyro effects.  If the effects are modifier effects or relate to Move-To effects, please add the keywords described in VDL for special DMX effects like “Move-To” and “With Strobing’.   Step 7: Save your effects Once you've defined all your new effects, copy them out of the test show into their own FDB file ("File > Effects files > New effects file" to create the effects file) or into your My Effects, so you have them available for scripting.  After you have defined your effects in Steps 1-7, the next time you right-click on a position and choose "Configure position as DMX fixture" you'll have the option of picking the fixture that you defined in your effects.  Here's an example of a user-defined fixture I created for an imaginary fixture manufacturer, WillCo:   Figure 1 – The "Configure position as DMX fixture" menu item will include your user-defined fixtures as options