Step by step instructions for defining your own fixture definitions and effects in Finale 3D manually are in the article, Creating fixture definitions and effects for your own fixtures. One step in that process involves writing a line of code called a “Fixture Definition” and storing it in the user-defined effects for your fixture. This article provides the specifications for that line of code.
The line of code specifies,
- The name of the fixture
- The fixture ID
- Number of channels
- Part Number of the default effect
- Labels of DMX channels in the DMX personality
- Part Number of “initialize fixture” effect, if required
- Part Number of safety channel effect, if required
- A short nickname for the fixture (optional)
- Boolean flag indicating whether the safety channel’s address is independent of the DMX Channel Base (optional)
All of this information is easy to find in the user manual of your fixture.
Syntax
An example fixture definition for a Tomshine moving head light fixture is:
{[name "Tomshine [] Moving Head Gobo 9CH"][fixtureId 100][numChannels 9][defaultEffectPartNumber TS11301][nickname "TSGOBO"][channelLabels {[0 "Pan"][1 "Tilt"][2 "Motor Speed"][3 "Dimmer"][4 "Strobe"][5 "Color"][6 "Gobo"][7 "Set To Zero"][8 "Set To Zero"]}]}The fixture definition is written in a programming language in which curly brackets define set of attributes and their values. Each attribute/value pair is in square brackets. Thus in this example, the first attribute is,
nameand its value is,
"Tomshine [] Moving Head Gobo 9CH"(double quotes included). The square brackets inside the double quotes are just part of the string. If the string contains any embedded double quotes, they are preceded by backslash, as in “2\” Red Peony”. The attributes are case-sensitive, so be careful to type fixtureId, not FixtureId.
Attributes
The name attribute should begin with a short, upper case abbreviation or nickname of the fixture brand or manufacturer with no spaces or special characters, followed by square brackets with nothing in them, followed by the fixture description itself.
The fixtureId attribute is the fixture ID number. User-defined fixture IDs are in the range 100-199.
The numChannels attribute is the number of channels of your fixture’s DMX channel map, which is called its “DMX personality”. Fixtures often have multiple DMX personalities that you can choose from. When you make a fixture definition and set of effects for that fixture definition in Finale 3D, it is specific to a single DMX personality, and thus has a specific number of channels. If you notice in the syntax example above, the name of the fixture is “Moving Head Gobo 9CH”, which indicates that it represents the 9 channel DMX personality of the fixture. If you use effects in Finale 3D that are made for one DMX personality of your fixture, and yet you configure your fixture to a different DMX personality, then the exported DMX script will be incorrect.
The defaultEffectPartNumber attribute is the part number of the effect that Finale 3D will use when it cannot find an effect for your fixture to match a need of the “Change DMX fixture and convert effects” function. If you use that function to convert a show from some other fixture to your fixture, and the show contains effects for the other fixture that you have not defined for your fixture, the defaultEffectPartNumber is what will be used as a placeholder. The part number is a symbol, not a string, so it is not surrounded by double quotes. If the part number contains spaces or double quotes within it, then it can be written in an alternate syntax: #<"TS11301">. The alternate syntax allows for spaces and double quotes as part of the part number. Contained double quotes should be preceded by backslash, as in #<"2\" RED PEONY">. Although Finale 3D supports all characters in part numbers, it is generally a bad idea to have double quotes or spaces in part numbers since they can cause trouble if you export to Excel or use barcodes or other systems.
The channelLabels attribute is an object (curly brackets!) that contains as its attribute/value pairs the list of DMX channel offsets beginning with zero, and their meaning as a short description of just a few words. The description needs to be short because it is included in the exported DMX scripts to make the scripts more readable, and many firing systems have character limits of the description fields. The DMX channel offsets begin with zero. Your fixture’s user manual may have a DMX channel specification that begins with channel 1 and counts up. Please renumber them when you add them to the channelLabels field of your fixture definition, so the first channel is 0, the second is 1, and so on.
The requiredInitializeFixturePartNumber (only if required!) attribute is a part number symbol, similar to the defaultEffectPartNumber (i.e., not in quotes). Most fixtures do not require an effect to initialize the fixture, so most fixture definitions do not include this attribute. Some fixtures have a DMX personality that requires an initial configuration for some of the DMX channels. For these fixtures, the user needs to add an effect at the beginning of the show to reset/initialize the fixture by setting those channel values. On the basis of this attribute in the fixture definition, Finale 3D will warn the user if the user has forgotten to add any required reset/initialize fixture effects before attempting to export a DMX script. An example attribute value for the 30W Tomshine moving head fixture is, [requiredInitializeFixturePartNumber TS12295].
The requiredSafetyChannelPartNumber (only if required!) attribute is a part number symbol, similar to the defaultEffectPartNumber (i.e., not in quotes). Most flame projector fixtures require a safety channel effect to enable the fixture. On the basis of this attribute in the fixture definition, Finale 3D will warn the user if the user has forgotten to add the required safety channel before addressing or export a DMX script. An example attribute value for the Galaxis G-Flame flame projector is, [requiredSafetyChannelPartNumber GFX9899].
The safetyChannelConfiguredSeparately (only if safety channel is required!) attribute is a boolean flag with value true or false that is true if the fixture’s safety channel number can be set independently of the fixture’s DMX Channel Base that is the base address for the channels in the DMX personality. An example attribute value for the Galaxis G-Flame flame projector is, [safetyChannelConfiguredSeparately true].
The optional nickname attribute should be a short, upper case string 3-8 characters long, which will be appended to the beginning of effect names for the fixture so the effect names contain within themselves an indication of what fixture they are meant for, as a convenience for the designer when looking through rows in the script window or exported script.