Software Documentation

Software Documentation

Effects OverviewDocumentation

Last updated: June 5, 2022

13 Programmer documentation: Representation of chains in the script

In Finale 3D, chains are represented by one row in the script per device in the chain. It may not look like that, because the “Show chains as one row” setting in the Script window’s gear menu is on by default, but regardless of the display format, each device is a single row behind the scenes. Thus a chain of 10 devices is represented by 10 rows. The rows are bound together by virtue of having the same reference number in the “Chain” column, which is also what determines whether the row is part of a chain at all (see “How can I tell if an effect is a chain?”). If a show had two chains, each with 10 devices, then the show would have 20 rows total, and 10 of those rows would probably have “Chain” values of #1; the other 10 would have “Chain” values of #2.

When you insert a chain or import a show with chains, the chains will be expanded out in the script to one row per device. Imported scripts can represent chains as multiple rows, just like in the script window of Finale 3D, if the script format has a “Chain” column with distinct reference numbers for the chains. The Finale Generic CSV format supports this column. Most script formats don’t have “Chain” column with this meaning, though, so most script formats resort to representing a chain in a single row in the script. As mentioned earlier, the “Quantity” column in the script format may represent number of chains or number of devices.

If a single row in the imported script represents an entire chain, or even multiple chains, then the row will be expanded in the import process to multiple rows in the Finale 3D script, one row per device. Chain reference numbers will be added automatically to group the devices of a chain together. If you are importing shows with chains, please look at the “Chain” column to understand what is going on.

Rows in the script that are part of a chain, i.e., that have a reference number in the “Chain” column, are treated specially. To begin with, you will notice that they appear different on the timeline. You may also notice, perhaps by trial and error, that their “Duration” column is editable, and contains a value that is usually different from the “Duration” value of the corresponding chain effect definition in the Effects window. This is unusual. The “Duration” column in the script is only editable if the row is part of a chain, or if the row’s effect has type other_effect or not_an_effect. Otherwise, the duration is a reference to the effect definition itself. The reason rows that are parts of chains cannot have a reference to the effect definition is that the duration of a chain is the duration from first to last launch, not the duration of an effect in the chain. The chain’s duration would almost certainly be wrong for the effect in the chain. Thus when you import a show with chains, or when you insert chains into the script, the “Duration” field for those rows will be filled in automatically with the specified or default duration of the effect itself.

Similar to the “Duration” column, chain rows in the script have a special column called “Chain Device VDL,” which is usually hidden. This field specifies the VDL for the row’s device, which could be different from other devices in the same chain, and is definitely different from being the entire chain. For example, the chain “Red Peony + Blue Peony + Green Peony Chain of 3” has three shells, all different. The VDL for the chain is that full description (the same for all rows in the chain). The VDLs for the devices in the chain are “Red Peony” “Blue Peony” and “Green Peony” (different for each row).

Figure 1 – The “Used” column depends on “Devices” and the user setting: “Display chain…”


In the effects window, the “Used” column that shows the number of chains used depends on the “File > User settings > Display chain ‘Used’ quantity as per-shell” setting.  If you have this setting checked, then the number displayed in the “Used” column for chains is just the number of devices in the script of that part number.  However, if you have the setting un-checked, then the number displayed in the “Used” column for chains is the number of devices, divided by the “Devices” count in the effect window, unless the Devices count is blank or zero, which is treated the same as the value “1”.   The chain quantity in the “Description” field and the “VDL” field does not affect the Used quantity; only the Devices field does.

Since chains are expanded into their constituent devices when the chains are imported or inserted, it is difficult to edit chain simulations after importing or inserting them. The “Edit simulation” function in the effect window changes the original definition of the chain, but that only affects the expanded devices in the script to the extent they still reference those characteristics from the chain definition. The Duration, Chain Device VDL, and Prefire fields, as well as the number of devices, are all decoupled from the chain definition after insertion, so editing the definition won’t affect those characteristics of chains already inserted into the show.