Software Documentation

Software Documentation

ScriptingDocumentation

Advanced Last updated: November 27, 2023

1 Script window columns

The script window in Finale 3D displays the list of event rows in the script, each row representing a single event or a combination of events in the case of chains or groups .  Each event has a set of properties defined by the columns in the table.   Most of the columns are hidden by default to make the information manageable, so to look at all the columns please select “Hide or unhide columns” from the blue gear menu in the upper right of the window.  The meanings of the columns are defined here in Table 1, along with,

  • The English name is shown in the column header in the script window unless you change the language setting to another language, in which case you’ll see the translation instead.
  • The Finale 3D internal name is the best name to use for column headers if you are importing data from a CSV file into Finale 3D, to avoid translation problems.
  • The Finale 3D internal representation is the data type of the column values.  If the data type is “string” or “symbol” then the column cannot be summed, whereas if it is “number” or “integer” it probably can.
  • The function to combine rows determines how values are combined when groups of rows are collapsed into single rows in the script window or in reports.  You may need to look up these functions, which are described in Table 2, if you are making custom reports.

 

Table 1 – Script row attributes

Finale 3D English name Finale 3D internal name Finale 3D internal representation Function to combine rows in reports Explanation
Address fullAddress string rangifyRowsOptionalStringy A read-only field that displays the full firing system address, combining the Rail and Pin fields.
Alternate alternate symbol mixRows Some firing systems, including Cobra, provide a facility to shoot events manually after a scripted show.  The Alternate field designates that the event is one of the manually triggered events.   The meaning of the Alternate field depends on the firing system.  For Cobra, for example, the value 1 or 2 in the Alternate field will designate the event to be triggered by the buttons associated with Alternate 1 or Alternate 2 in the export options; the export options for Cobra also control whether the event is double listed in the script as part of the pyromusical or only added to the end of the script.

For firing systems that do not make use of the Alternate field (which is most firing systems), you are free to use the field for your own purposes, similar to the Custom Script Field or the Track field.  Please see the firing system documentation page for your firing system, and search for “Alternate” to determine if the field is used for your firing system.

Angles* angleGraphics string angleGraphics A read-only field that displays graphically and numerically the angles of the event or events represented by the row, in the angle format chosen by the user with “Show > Set angle format”.  When a row contains multiple events, such as a chain or group, the Angles* field combines all the angles to display them as a single field, as in: \|/ -45° 0° 45°.
Category category symbol mixRows A read-only field referencing the Category field of the effect in the effects window, which is a user-defined field for your convenience.
CE Number ceNumber symbol mixRows A read-only reference to the effect’s CE number.
Chain Device VDL chainDeviceVdl symbol mixRows The Chain Device VDL field plays a role in rendering chains that are defined in the effects window and that contain multiple types of shells.  An effect defined by the VDL, “Red Peony + White Peony + Blue Peony Chain of 3” in the effects window expands into three script rows when inserted into the show, one for each device (shell) in the chain.  All three script rows thus have the same part number, but each script row is expected to be a different color shell.  The Chain Device VDL field contains the VDL for each row that results from expanding a chain effect from the effects window, which in this example would be “Red Peony” or “White Peony” or “Blue Peony”.

The Chain Device Field is not required for chains created dynamically with “Script > Chains > Combine as chain”, because those effects have their own part numbers, referring to their own effect definitions in the effects window that define their own VDL.

Chain Gap chainGap integer milliseconds fancyChainGaps The delay between event times of this item relative to the previous item in the chain.  When multiple rows are combined, the Chain Gap field combines the delays of the individual rows, separated by asterisks.  The first Chain Gap in the combined sequence is therefore always zero.
Chain Reference chainRef integer reference number or undefined mixRows The unique identifier of the chain; all items in the chain have the same Chain Reference.  
Chain Row chainRow integer or undefined mixRows For chain items, the Chain Row counts the contiguous runs of same-effect items in the chain, which maps to the row count for each item of a multi-effect chain that is represented by multiple rows in the standard Chain Specifications report.  See Chain Specifications report for more information.
Cost stdCost number sumRows A read-only field referencing the Cost field of the effect in the effects window.  For chains, you can decide whether the cost means the cost of the full chain or whether it means the cost per device (i.e., per shell). From within the Finale 3D application, select “File > User settings > Chain price, cost, NEQ, and weight are for entire chain” to make the prices and price summaries display correctly for either meaning.  Please also see the related field, Quantity.
Cue Count cueCount integer mixRows Ignoring duplicates, the Effect Times in a show are the cues.  The Cue Count is the chronological order of the cues, beginning with one.
Custom Numeric Field customNumericField number or undefined sumRows A numeric, user-defined field for your convenience.  Unlike text fields, the numeric field will sum if multiple events are combined in the same row, similar to the Devices field.
Custom Part Field customPartField symbol mixRows A read-only field referencing the Custom Part Field of the effect in the effects window, which is a user defined field with a few exceptions (see Effects table columns).
Custom Position Field customPositionField symbol mixRows A read-only field referencing the Custom Position Field of the position identified by the Position field.  The Custom Position Field is useful for sorts in the addressing dialogs and report customization dialogs when you want to define your own priorities based on position.  For example, if you want to sort by position but not exactly alphabetically, you can use the Custom Position Field to store the sortable names.
Custom Script Field customScriptField symbol mixRows A user-defined text field that you can use for anything.  The Custom Script Field is an available option for sorts and constraints in the addressing dialogs, so it is useful if you want to implement your own sorts or constraints based on your own criteria. 
Delay externalDelay integer milliseconds firstRow The Delay field is the time delta from the Event Time to the time at which a device’s internal fuse is ignited.  For pyro, the Delay field is usually zero.  The two exceptions are chains with delays, and delay fuses.

For chains with delays between the devices, each device’s Delay field is the full time delta from the Event Time to the time at which device’s own internal fuse becomes ignited.   For delay fuses (“Fuse Delay”) the Delay field plus the prefire comprise the full delay between the Event Time and Effect Time. When an effect is inserted into the show, the effect’s Fuse Delay field from the effects window is copied as the initial value of Delay field in the script.

Description description symbol firstAndCountOptionalSymbol A read-only field referencing the Description field of the effect in the effects window, which is the proper name of the effect as it should appear in reports and on labels. 
Devices numDevices integer sumRows The number of devices represented by the row — one for a single device like a shell; more than one if the row represents a chain or group of devices; zero if the row represents an effect like a DMX light flash or flame projector shot that is not itself a physical object. 

A device is a physical pyrotechnic object that is not easily broken up into smaller units.  Thus a shell is a single device, and so is a single-shot tube, and so is a cake because a cake is not easily broken up into smaller units; but a chain is multiple devices because its shells are easily separated.

Duration duration integer milliseconds maxRows Either a read-only field referencing the Duration field of the effect in the effects window, which defines the duration globally for the effect, or an editable field representing the duration of this event’s use of the effect, depending on the Type field of the effect.  Please see Why is ‘Type’ so important? What depends on it?.  In general, for pyro the Duration field is a read-only field representing the lifetime of the stars, except for cakes as described in Cake and candle duration (and prefire); and for DMX effects the Duration field is an editable field representing the duration of the effect instance.
Effect Data effectData object firstRow The Effect Data field contains motion and color animation data for animated effects like drones, saxons, wheels, and castiles.  The Effect Data field will be filled programmatically by functions like “File > Import > Import drone show”, but the field is also readable and editable by humans, which enables users to enter manual motion paths for their own creative purposes, like effects on jetskis scooting across a lake.  Please see: Programmer documentation: Effect Data and Motion Data.
Effect Time actionTime integer milliseconds firstRow The Effect Time represents the first visual appearance of the effect.  It is represented on the timeline by the blip on the timeline bar.
Event Time eventTime integer milliseconds firstRow The time at which the firing system or controller triggers the event.  For chains, the Event Time is the same for all script rows that are part of the same chain, since a single trigger time initiates the full chain.
EX Number exNumber symbol mixRows A read-only reference to the effect’s EX number.
First Angle* firstAngleGraphics string firstAngleGraphics First Angle* is like the Angle* field, except that it shows only the first angle even if the script row represents multiple events.  In printed reports, the First Angle* field has a consistent width that is sometimes preferable to the variable width of showing multiple angles — unless you need to see all the angles.
Flight Count flightCount integer mixRows A read-only field representing the number of devices with the same Event Time and same position.  Notably, all devices in a chain have the same Event Time, even if the chain has delay fuses between the devices, so the Flight Count for chains is the length of the chain unless multiple chains are fired at the same time from the same position.

The Flight Count is useful as an addressing sort criterion if you want to assign addresses starting with the longest chains, for example, to utilize racks most efficiently.

Group group array of symbols intersectOptionalSymbolArrayFirstElement The Group field is a list of symbols that define the group to which the event belongs.  Events in the same group are collapsed on the timeline into a single timeline bar and are collapsed by default in the script table into a single row, though the option to show grouped events as individual rows in the script table without collapsing them is available from the blue gear menu.

The Group field can also be used as an addressing pin constraint to control what effects are eligible to share e-matches.

You can create groups of events from the menu item “Script > Groups > Combine as group” or with the keyboard shortcut “G”.  You can also combine groups hierarchically, and you can edit a group or rename it by right-clicking on it on the timeline.

Hazard lockout symbol mixRows The hazard class that show operators may use to prevent groups of 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.

The Hazard field in the script table fills in automatically from the Hazard Default field of the effect definition when the effect is inserted into the show.  After the effect is inserted, the user can edit the Hazard field in the script.

Is Chain isChain boolean mixRows True if the item has a valid Chain Reference, and false otherwise. 
Manufacturer manufacturer symbol mixRows A read-only field referencing the Manufacturer field of the effect in the effects window.
Module Or Slat Type moduleType symbol mixRows A symbol that identifies the type of firing system module or slat that triggers the event.  The Module Or Slat Type field of script rows is filled in automatically by the addressing functions, based on the Module Or Slat Type field of the positions.  It is not possible to have two different Module Or Slat Types in the same position.
NEQ neq number or undefined sumRows A read-only field referencing the NEQ field of the effect in the effects window.  For chains, you can decide whether the NEQ means the NEQ of the full chain or whether it means the NEQ per device (i.e., per shell). From within the Finale 3D application, select “File > User settings > Chain price, cost, NEQ, and weight are for entire chain” to make the prices and price summaries display correctly for either meaning.  Please also see the related field, Quantity.
Next next integer milliseconds mixRowsPermissive A read-only field that displays the time from this event’s Effect Time to the next greater Effect Time.
Notes scriptNotes symbol unionRowsOptionalSymbol A user-defined field for your convenience.  This is not the Notes field in the effects window (internal name partNotes).
Notes 2 scriptNotes2 symbol unionRowsOptionalSymbol Another user-defined field for your convenience.
Notes 3 scriptNotes3 symbol unionRowsOptionalSymbol Another user-defined field for your convenience.
Pair pair boolean mixRows A read-only boolean field that is true if and only if the Flight Count is two.  The Pair field is useful as an addressing sort or constraint to give special treatment to pairs of effects, such as to cause them to share e-matches or fill into rack clusters arranged as “V” shapes.
Pan pan number in degrees or undefined mixRows One of three angles that define the orientation of the effect relative the position: Pan, Tilt, and Spin.  The Pan is a counter-clockwise angle around the Y-axis (up axis), with zero meaning the effect is facing the viewer.  For DMX moving head fixtures, zero means the yolk of the fixture is facing the viewer.

Non-symmetrical pyro effects like fan cakes require that Pan is zero for the effect to face the viewer, but symmetrical pyro effects like shells and mines are unaffected by the Pan unless they are also tilted.  If an effect is tilted, then the Pan controls whether the tilting is forward/back or side-to-side.  Cakes typically have a Pan of zero to face the viewer, whereas shells typically have a Pan of 90 so their Tilt is a side-to-side angle.

The Pan, Tilt, and Spin fields’ angle convention is unaffected by the setting “Show > Set angle format”, which applies only to the Angles* and First Angle* and Pitch and Roll fields.

Part Number partNumber symbol firstRow The symbol that identifies the effect to which the event refers in the Per-show effects collection of the effects window .
Pin pinAddress string rangifyRowsStringy For pyro effects, the Pin identifies the electrical terminal on the firing system module or slat that ignites the e-match.  For DMX effects, the Pin is just the word “dmx”. 

For some special effects fixtures triggered by some non-DMX firing systems, such as the Explo Wave Flamer triggered by the Explo Ignition System and the Galaxis G-Flame triggered by the Galaxis controller, the Pin field has a specialized meaning defined by the firing system.  In the case of the Explo Wave Flamer, the Pin identifies the macro pattern of flames to be fired.

Like the Rail field, the Pin field is formatted according to the standard of the firing system, which may be numbers or letters.

Pitch pitch number in degrees or undefined mixRows A read-only field indicating the forward/back angle around the X-axis, relative to the position and displayed according to the user’s chosen angle convention in the setting “Show > Set angle format”.  The Pitch field is fully determined by the Pan and Tilt field values.  Whereas Tilt may be forward/back or may be side-to-side, depending on the Pan field, the Pitch field is always forward/back.
Position position symbol groupifyRowsOptionalSymbol The launch position at which the effect is located of DMX fixture that produces the effect.
Position Safety Distance positionSafetyDistance number in meters or undefined minRows A read-only field referencing the position’s Safety Distance Meters; useful to compare to Effect Safety Distance.
Prefire internalDelay integer milliseconds firstRow A read-only field referencing the Prefire field of the effect in the effects window, which is the time delta between the Event Time and the Effect Time.  On the timeline, the prefire determines the length of the line segment to the left of an effect’s timeline blip.  The prefire is typically the lift time for shells and zero for ground effects like comets or mines, but may be enlarged to take into account the tiny firing system and e-match delays as well as the fraction of a second it may take an effect to develop to the point to which you  synchronize the music.  For further explanation see Cake and candle duration (and prefire).
Price stdPrice number or undefined sumRows A read-only field referencing the Price field of the effect in the effects window.  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 > Chain price, cost, NEQ, and weight are for entire chain” to make the prices and price summaries display correctly for either meaning.  Please also see the related field, Quantity.
Quantity quantity number or undefined sumRows A read-only field that is the same as Devices except with special handling for chains if the user setting “Chains count as one in ‘used’ and ‘quantity’ columns” is true.  If so, then the quantity is the number of devices in the row divided by the number of shells in the chain’s definition in the effects window.  For example, if the row represents a single shell from a chain of 5, then the quantity is 0.2.  The quantities for chains constructed manually with the command “Combine as chain” are just the number of devices, unaffected by the user setting, since the shells do not come from chains defined in the effects window.
Rack rack integer reference number or undefined mixRows A numeric reference identifying the rack that holds the device.  The Rack field is filled in by the addressing functions or by the user’s dragging and dropping of effects into racks in the rack layout view.
Rack Type rackType symbol mixRows An optional text field that gives the user control over what kinds of racks are compatible with the effect, as described in Using “Rack Type” to control what types of racks are used for what effects.  If an effect in the effects window has a Rack Type Default field value, it will be copied into the Rack Type field of the event when inserted into the show.  Thus if you have a particular kind of effect that always goes into a particular kind of rack, like chain of certain length or long tube single-shot effect specialized for sky letters, the Rack Type Default field is a convenient way to enforce the matching condition.
Rail railAddress string rangifyRowsStringy The Rail identifies the module or slat that triggers the event.  The rail address may be a single number or letter for a module alone, or it may be a combination of two numbers or letters to identify a module and slat, depending on the requirements of the firing system.  The Rail field in the script table is formatted according to the standard of the firing system.
Roll roll number in degrees or undefined mixRows A read-only field indicating a side-to-side angle around the Z-axis (forward axis) prior to the pitch rotation.  If an event is not pitched forward/back, the Roll field is simply the side-to-side angle.  If an event is pitched forward/back, the Roll field is affected by the pitch and is thus harder to interpret.  Like the Pitch field, the Roll field is fully determined by the Pan and Tilt field values.  
Effect Safety Distance safetyDistance number in meters or undefined maxRows A read-only field referencing the Safety Distance Meters of the effect in the effects window.
Section section symbol mixRows An optional identifier of letters or numbers that divides the show into different parts within the same universe.  The firing system addresses for different sections within the same universe are not independent of each other.

The addressing functions have an implicit constraint that prevents modules from being shared across different sections in the show, which makes the Section field useful for partitioning the show into groups of positions that can share modules only within the groups.  Addressing techniques for firing systems with slats often employ the Section field, as described in Using the Section field in position properties and Slats, virtual slats, and splitter boxes.

The Section field of script rows is filled in automatically by the addressing functions, based on the Section field of the positions.  It is not possible to have two different sections in the same position.  The site layout diagrams designate sections with bounding boxes around the positions having the same Section field.

Size size floating point number representation of typed microns or undefined maxRows A read-only field referencing the Size field of the effect in the effects window, which represents 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.
Sleeve sleeve floating point number representation of typed microns or undefined mixRows If provided, the optional Sleeve field replaces the Size and Type fields for determining what racks are compatible with the effect.  The term “sleeve” refers to the practice of placing a smaller size tube or a candle or single-shot inside a larger size mortar for the purpose of firing the smaller effect.  If an effect has a Sleeve, then it will be compatible with mortar racks of matching size, independent of the effect’s Type, as described in Sleeving effects into different size mortars.
Spin spin number in degrees or undefined mixRows One of three angles that define the orientation of the effect relative the position: Pan, Tilt, and Spin.  Spin is the counter-clockwise angle around the Y-axis (up axis) after the Y-axis has been rotated first by Pan and then by Tilt.  The Spin is the rotation around the trajectory of a pyro effect or beam of a DMX effect, which in most cases doesn’t matter since most effects are symmetric about their trajectory or beam.  Thus the spin is usually zero for both pyro and DMX effects, but it may be non-zero for gobos of DMX light effects or for tilting a pyro fan cake sideways while still facing forward.

The Pan, Tilt, and Spin fields’ angle convention is unaffected by the setting “Show > Set angle format”, which applies only to the Angles* and First Angle* and Pitch and Roll fields.

Storage Location stdLocation symbol mixRows A read-only field referencing the Storage Location field of the effect in the effects window, 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.  Storage Location corresponds to Std Bin ID in Finale Inventory.
Straight Up straightUp boolean mixRows A read-only boolean field that is true if and only if the effect is aiming straight up.  The Straight Up field is useful as an addressing sort or constraint criterion. 
Subtype subtype symbol mixRows A read-only field referencing the Subtype field of the effect in the effects window.
Tilt tilt number in degrees or undefined mixRows One of three angles that define the orientation of the effect relative the position: Pan, Tilt, and Spin.  The Tilt is a counter-clockwise angle around the X-axis (the axis aiming right) after the X-axis has been rotated by Pan.  When Pan is zero, a positive Tilt rotates the effect forward toward the viewer.  When Pan is 90, a positive Tilt rotates the effect to the right.

The Pan, Tilt, and Spin fields’ angle convention is unaffected by the setting “Show > Set angle format”, which applies only to the Angles* and First Angle* and Pitch and Roll fields.

Track track symbol mixRows The meaning of the Track field varies depending on the firing system.  For many firing systems, the Track field groups together a sequence of events that the user triggers manually (“Semi-automatic mode”).  The Track field may have a specific format to identify a button that triggers the sequence.   For some wireless firing systems like Galaxis, the Track field also provides the user some control over the system’s automatic grouping of events for fast firing sequences within a pyromusical (“steppers”).  For a number of firing systems, the Track has no meaning at all, in which case you are free to use the field for your own purposes.

The setting, “Show > Set cue flag color mapping” makes the color of the cue flags on the timeline a function of the Track field.

Tube tube integer or undefined mixRows The tube number in the rack that holds the device, beginning with the first tube in the rack = 0.  Tube assignment order can be controlled by the user as described in Tube loading order.
Tubes numTubes integer or undefined sumRows A read only reference to the effect’s or rack’s Tubes field, counting the number of tubes or shots.

This field can be used in reports based on the script window to count the total number of shots in the show, taking into account that cakes and other multi-shot devices may comprise multiple shots.  In Finale 3D‘s terminology a cake is a single device with multiple shots; thus the Devices column always counts cakes as one.  Please see the Tubes row of Table 1 of Effects table columns for more information.

Type partType symbol mixRows A read-only field referencing the Type field of the effect in the effects window.  The value is 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, as explained in Why is ‘Type’ so important? What depends on it?
UN Number unNumber symbol mixRows A read-only reference to the effect’s UN number.
Universe universe symbol mixRows An optional identifier of letters or numbers used to divide the show into different parts — universes — each universe corresponding to a separate exported firing system script.  The firing system addresses for scripts of different universes are independent of each other.  For more information, see Multiple firing systems in the same show.

The Universe field of script rows is filled in automatically by the addressing functions, based on the Universe field of the positions.  It is not possible to have two different universes in the same position.

Weight weight number or undefined sumRows A read-only field referencing the Weight field of the effect in the effects window.  For chains, you can decide whether the weight means the weight of the full chain or whether it means the weight per device (i.e., per shell). From within the Finale 3D application, select “File > User settings > Chain price, cost, NEQ, and weight are for entire chain” to make the prices and price summaries display correctly for either meaning.  Please also see the related field, Quantity.

 

Columns in printed reports

Most printed reports are based on the rows of the script window.  Based on the report template, script rows are partitioned into groups, and each group of rows is combined into a single row that is displayed in the report.   When a group of rows is combined, each column of values in the group is combined into a single summary value using an appropriate “combine” function.

Most numerical columns like Devices (the device count) or Weight or Price summarize by adding the numbers together.   If the script window has 1000 rows that the report template combines into a single row, the Devices column in the single row would contain the number “1000” if each of the 1000 individual rows had a Devices count of “1”.  Most symbolic columns summarize as the consensus if all the values agree, or blank if there is any disagreement.  Other columns like Address or Angles have special combination functions that combine the addresses or angles together in a special format.

If you have need of an extra column in the script window for a data value that isn’t one of the predefined columns, you may chose to re-purpose a predefined column that you aren’t using.  If you are going to include your re-purposed column n printed reports that combine rows, then you need to make sure that the combine function works for the kind of data you put into the row.  For example, if your data is numbers and if you want them to sum when rows are combined, then you’ll need to choose a predefined column that uses the sumRows combine function, like Weight or Cost or NEQ.

 

Table 2 – Combine functions

Function Explanation
angleGraphics Combine the angles as a string with ASCII art angles like \\\|||///
fancyChainGaps Special formatting for chains
fancyDelays Special formatting for delays
firstAndCountOptionalSymbol Take the first value and add a count to it
firstAngleGraphics Take the first angle value and format with ASCII art angle
firstRow Take the first value
groupifyRowsOptionalSymbol Combine the symbol values as a group of values
intersectOptionalBits Combine the integer values with logical AND of the bits
intersectOptionalSymbolArrayFirstElement Combine the first elements of array values
maxRows Return maximum value
minRows Return minimum value
mixRows Return consensus if values agree, blank otherwise
mixRowsPermissive Return consensus if values agree ignoring blank values, blank otherwise
rangifyRowsOptionalStringy Combine numbers into a non-lossy string representation that efficiently encodes ranges of numbers, ignoring blank values
rangifyRowsStringy Combine numbers into a non-lossy string representation that efficiently encodes ranges of numbers
sumRows Sum the values
unionRowsOptionalSymbol Union the symbol values, returning a symbol, ignoring blank values