Software Documentation

EffectsDocumentation

Advanced Last updated: September 27, 2019

1 Effects basic instructions

The effect window in Finale 3D and the effect palette in the upper right of the design view are the two ways of viewing your effects.  Both the window and the palette show one specific “Collection” of effects at a time, which you can select from the blue selector of the effect window or from a link at the bottom of the effect palette.  The collections are, “Generic effects”, “Per-show effects”, “My effects”, plus any effect databases that you’ve created as local files, plus any Finale Inventory accounts that you are connected to (see Account setup) .

The Generic effects are the 6,000 or so default effects included with the application as a starting point.  They are read-only effects.  The Per-show effects is the collection of effects that is saved with the current show being edited.  When you insert an effect into a show from any collection, the effect definition is copied into the Per-show effects so that the show is self-contained, without any references to external effects lists.  The My effects is your personal effects collection, saved in the cloud.

Figure 1 – The effect palette and effect window show one collection of effects at a time.

 

To create new effects, use the menu item “Effects > Create new effect…” which brings up the dialog shown in Figure 2.  In this dialog enter a full description of the effect into the Input description field, and then look at the green fields below, which show how Finale 3D interprets your input description.  Your input description should always include the caliber/size of the effect.  Depending on the how much detail you want to provide, you can also provide the duration, height, and prefire, as well as timing and firing pattern information for cakes.  Instructions for typing in the input description are given in the “VDL” section, “finale3d.com > Documentation > VDL documentation”.  VDL, which stands for “Visual Description Language”, is the pyrotechnics language in which you can define arbitrary effects.   Notably, the input description in this dialog is not a search box.  The software will actually construct a new simulation based your description as a recipe.  Try typing something complicated like “50mm red to blue to green chrysanthemum with strobing pink pistil with gold tail” to see how your description is interpreted!

Figure 2 – Enter a full description, including caliber, into the input description field

 

The easiest way to edit effects is to right click on them in the effect window, and then to select “Edit this effect simulation or rack…” in the context menu, as shown in Figure 3.

 

Figure 3 – Right click on an effect row and select “Edit this effect simulation or rack…” to edit effects.

 

The rows in the effect window are effect definitions themselves, comprising about 30 attributes that are shown in the columns.  Most of the columns are hidden by default to make the information manageable.  From the blue gear menu in the upper right of the effects window, select “Hide or unhide columns” to look at the available columns, and unhide any that you are interested in.

 

Figure 4 – From the blue gear menu in the upper right, select “Edit this effect simulation or rack…” to edit effects.

 

There are a few special columns in the effect window that are not attributes — “Line Number”, “Icon”, “Used”, “Quota”, “On Hand”, and “Available”.  The Icon is automatically generated based on the other column values.  The Used, Quota, and other quantity columns are described in Inventory management basic instructions.

All the rest of the columns are the attributes that define the effect itself.   Their meanings are defined here in Table 1, together with the relationship to the corresponding Finale Inventory terms, which you don’t need to care about unless you are using a Finale Inventory or master inventory collection (Finale Inventory is a separate but compatible inventory management service; see finaleinventory.com).

To import effects from a CSV file (see Importing inventory) , you simply need to have the columns in your CSV file that you want to import, and one row per effect.  The only required column is “Part Number” because the part number is the identifier for each effect.  Depending on your language setting (“File > Languages”), the column names may not be in English.  When you import, your CSV file column headers should match what you see in the effect window in your selected language — or, to create a language independent CSV file, you can use the Finale 3D internal column names in your CSV file (column 2 in Table 1, below), which will always work no matter what language you have selected.

 

Table 1 – Effect attributes

Finale 3D English name Finale 3D internal name Finale Inventory name Explanation
Part Number partNumber Product ID The unique identifier for the effect, like DOM10001 or LD3CK253. This field is called the “Product ID” in Finale Inventory.  If you are creating new part numbers from scratch, the best practices we recommend are: 1) all upper-case, 2) A-Z letters and digits only, 3) no spaces or special characters other than dash or underscore, 4) not longer than 16 characters.
Used used The number of devices currently used in the active show. This field is not an attribute, so it cannot be edited. See Inventory management basic instructions for further instructions.  Most of the quantity filters in the effect palette and the effect window blueprints compare the Used quantity with other quantities like Quota, On Hand, and Available.
Quota quota The number of devices that you intend to use in the active show. This field is saved in the show’s Per-show effects but “shows through” into any displayed collection of effects, matching by cross-referencing the Part Number. Please edit this field in the Per-show effects collection or import it with “Effects > Import quotas…” or “Effects > Finale Inventory > Import quotas from sale order…”. See Inventory management basic instructions for further instructions).
On Hand qoh The number of devices physically present in your inventory, disregarding reservations, unreceived purchases and unshipped sales. This field can be edited in place in the My effects collection and the effect database files, but cannot be edited in place in Finale Inventory collections or Generic effects. Finale Inventory collections provide an up-to-date On Hand quantity based on your inventory management operations like stock takes and received or shipped shipments. See Inventory management basic instructions for further instructions).
Available available The number of devices in your inventory that are available to use, taking into account reservations, (optionally) unreceived purchases and unshipped sales. See paragraph 5 of Account setup for options pertaining to unreceived shipments. This field can be edited in place in the My effects collection and the effect database files, but cannot be edited in place in Finale Inventory collections or Generic effects. Finale Inventory collections provide an up-to-date Available quantity based on your inventory management operations like stock takes and sale or purchase orders. See Inventory management basic instructions for further instructions).
Description description Description The proper name of the effect as it should appear in reports and on labels, like “Galactic Gladiator” or “Red Peony 75m” or “Bomba Roja Con Aro Azul” or “Синяя в красную хризантему”.  Since the simulation is specified by the VDL column and other numerical columns like Height Meters and Duration, the description can be anything.  It does not affect the simulation.
Size size Caliber The caliber of the effect, in inches or millimeters, e.g., 3” or 75mm.  This field determines the size of the visual simulation. If the field is blank, the default value of 3″ will apply.
Prefire internalDelay Prefire Time The lift time, for shells, or the lift time of the first effect of a cake if it is a shell. This field is not the visco fuse delay on a cake. This field does apply to the visual simulation.  The value of this field can be zero or blank for cakes and candles, which is generally easiest and safest because the automatic default values are good for both for shell and non-shell components of a cake.   As a reminder and point of emphasis, for shells this is the lift time, so if you have a prefire of 0.1 seconds on a shell, for example, that shell will explode on the way up (see Inventory compatibility with Finale Business (and how to fix cakes)). For further explanation see Cake and candle duration (and prefire).
Duration duration Duration The lifetime of the stars, for aerial shells, or the duration of the continuous effect for gerbs or flares, or the duration from first launch to last break for cakes.   For more explanation of cake durations, see Cake and candle duration (and prefire).
Height Meters height Effect Height The height in meters of the trajectory apex of an aerial shell, or of the spark plume for fountains and gerbs. This field determines the height of the visual simulation. In Finale 3D, this field is always meters.  In Finale Inventory, you can set the Distance Unit Of Measure to feet if you want, which applies to all distances including height and safety distance. Finale 3D will convert between feet and meters automatically if necessary when it connects to Finale Inventory, but we recommend you use meters, for simplicity.
Devices Devices Chain Number Of Devices The number of devices in the chain, or 1 if the item is not a chain.
Color color Effect Color A single color, which you can use as a search term. It may contain spaces but not commas. If the effect has multiple colors, this field should contain the most prominent single color that you are likely to search for.
Subtype subtype Effect Subtype A user defined field, such as “500g Cakes”, or “Special Shells”.  This field does not affect any application functions, so you can use it for whatever you want.
VDL vdl VDL Description The description of the effect in standard pyrotechnics terminology (See “finale3d.com > Documentation > VDL documentation”).  This field defines the visual simulation of the effect, along with a few other specifications like Size, Height Meters, and Duration.   There are some differences between Finale Business and Finale 3D with respect to VDL, particularly with respect to cake durations.   If you are importing or connecting your Finale 3D inventory from Finale Business cakes, please see Inventory compatibility with Finale Business (and how to fix cakes) for instructions to fix the prefires and durations.
Manufacturer Part Number manufacturerPartNumber Mfg Product Id The manufacturer or supplier part number.  This field may be useful for your own purposes.  Additionally, the Manufacturer Part Number field enables you to update simulations in your own effect catalog with the current, up-to-date simulation managed by the supplier, by cross-referencing.
Manufacturer manufacturer Manufacturer This is the name of the manufacturer or supplier.
Type partType Choreography Tab One of these predefined English terms (exactly): shell, comet, mine, cake, candle, other_effect, single_shot, ground, rocket, flame, not_an_effect, rack.  The Type field is important, because a number of the application functions behave differently depending on the Type.  For example, the rack layout functions will allocate mortar rack tubes for effects of type “shell” but not effects of type “cake”; the e-match count functions will not allocate e-matches for effects of type “flame”; effects of type “other_effects” have editable durations in the script window, whereas other effects have constant durations defined by the effect definition; etc.  The full list of differences based on Type is given in Why is ‘Type’ so important? What depends on it? Please note that these values are slightly different from the corresponding values in Finale Inventory.  
Price stdPrice Item Price The price of the item. Finale 3D will display the price of a show based on these values.  For chains, you can decide whether the price means the price of the full chain or whether it means the price per device (i.e., per shell). From within the Finale 3D application, select “File > User settings > Interpret chain prices as per-shell” to make the prices and price summaries display correctly for either meaning.
Storage Location stdLocation Std Bin ID The standard storage location for the item, for simple inventory management of items stored in fixed locations, and for picking instructions.  Item quantities from Finale Inventory are based on Sublocations and Locations, which are not directly visible in Finale 3D.
Hazard Default lockoutDefault Hazard Default A default value for the hazard class or caliber group that show operators may use to selectively prevent effects from firing based on real time conditions.  For many firing systems, this field is exported directly to the firing system script, though sometimes it goes by a different name in the firing system nomenclature, such as CGHZ or Lockout.
Tubes numTubes Rack Tubes For racks, the number of tubes in the rack. Leave blank for anything other than racks.
Category category A user-defined field for your convenience.  Unrelated to the Finale Inventory field by the same name.
Custom Part Field customPartField Custom Part Field A user-defined field that you can use for anything, except in this circumstance: if you are using the Explo X2 Wave Flamer flame units, then the Custom Part Field may contain the macro number for the 66 pre-defined X2 Wave Flamer effects (see Explo X2 Wave Flamer for details).
Rack Type Default rackType Rack Type Default A field that you can employ to set matching conditions between racks and effects (See Using the “Rack Type” field to make effects go into fan racks).
Notes partNotes Notes A user-defined field for your convenience.  
DMX Patch dmxPatch DMX Patch A tiny program that defines the DMX signals corresponding to the effect.  This field only matters when exporting DMX-based scripts.
EX Number exNumber EX Number A field that is useful to include for US users.  This field can contain single EX numbers or a comma separated list, like 2008040132, 2004110899.
CE Number ceNumber CE Number A field that is useful to include for European users.
UN Number unNumber Hazardous Material A field that is useful to include for all users.  This number must be in the format: UNXXXX, where XXXX is a four digit number like 0336 or 0337.  Example: UN0337.
Cost stdCost Standard Accounting Cost The cost of the item.
Safety Distance Meters safetyDistance Safety Distance The safety distance for the item, in meters.
Fuse Delay fuseDelay Fuse Delay The visco fuse delay between the ignition of the device’s fuse and the first launch.  In contrast with other attributes that are referenced by effects the script, when you insert an effect in the show, the Fuse Delay field is copied into (not referenced by) the “Delay” field of the script row, and can be edited directly in the script row.
Remaining Quota remainingQuota The Quota minus the Used of the item in the active show. This non-editable field is used for quantity filters and for reports.
Remaining On Hand remainingQoh The On Hand minus the Used of the item in the active show. This non-editable field is used for quantity filters and for reports.
Remaining Available remainingAvailable The Available minus the Used of the item in the active show. This non-editable field is used for quantity filters and for reports.