Software Documentation

Software Documentation


Hobbyist Pro Last updated: May 8, 2022

12 Programmer documentation: Creating fixture definitions and effects manually

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