Software Documentation

Software Documentation

Visual Descriptive Language (VDL)Documentation

Last updated: September 12, 2023

5 Creating a chain with one or more effects

NOTE: the easiest way to create a chain in Finale 3D is to lay out shells on the timeline, then select them, and then do the menu item, “Effects > Create chain from selected items…”, which will present a dialog showing the VDL that represents the chain.  You can look at the VDL to understand the syntax.

Describing a chain in VDL is not difficult. In fact VDL parsers interpret any effect description containing the word “Chain” as a chain. Universally, the most common problem people have with writing effect descriptions of chains is forgetting to put the word “Chain” in the description. You do need the word “Chain” itself (or its translation in other languages). Other terms like “Finale” or “String” may not be recognized as a chain by the VDL parser, but “Chain” will always work.

An example of a simple chain VDL description is,

3" Salute Chain Of 10

The word “Chain” is all that is required for that description to be interpreted as a chain of 10 shells. The number after the word “Chain” is the number of shells. If that number is missing, a default number will be used, which is usually 10.

You can specify the duration of a chain by adding the duration at the beginning of the VDL description, or in a Duration column if you are importing effect descriptions. For individual shell VDL descriptions, the duration is the duration of the stars. For cakes, the duration is the time from first ignition to last break (Cake duration details). For chains, the duration is the time from first ignition to last ignition (Chain duration details). Thus, the total duration of a chain is the sum of the delays between the shells. If your chain has five shells, then there are four gaps between the shells, and the duration will be the sum of the four delays for the gaps. A 5-shell chain with a duration of 8 seconds will have 2 second delays between the shells. The default duration for a chain is zero.

An example of a more complex chain VDL description is,

3" 8s Red Peony + Blue Peony + Gold Willow + Blue Peony + Red Peony Chain Of 5

This description defines a multi-effect chain. The individual effects are separated by the plus sign (+). If the chain description has any plus signs in it, the number of plus signs must be exactly the number of shells in the chain minus one. In fact, in the absence of a number following the word “Chain” the number of plus signs will imply the number of shells, overriding the default. You could equally well describe this last chain as,

3" 8s Red Peony + Blue Peony + Gold Willow + Blue Peony + Red Peony Chain

You can try out the simulation from the menu item, “Effects > Create effect”.  Type everything into the input box, and look at the green boxes to see if the software is interpreting the information correctly.


Figure 1 – Creating an effect from “File > Create effect” (or control-G)


Figure 1 shows the full description in the input box at the top, and the (read-only) parsed fields that come out that full description, including defaults.  Notice that the number of shells in the chain, and the duration (both circled) are taken from explicit numbers in the input description.  The height and prefire are defaults since they are not specified in the input description.

If you are importing your effects from a CSV, then the size, duration, height, and prefire (but not the number of chain shells) can be split off into separate columns in your CSV.  The software will automatically incorporate these metrics from separate columns into the created simulation, or will pull them out of the VDL or Description columns, or use defaults, if the separate columns for the metrics don’t exist in your CSV.  Thus in a CSV file, if the metrics are in separate columns then the descriptions look a little simpler, like:

Salute Chain Of 10

Table 1 provides guidance for the format of the optional metrics of a chain.

Table 1 – Basic chain metrics

Term Format Example
Size The caliber of the effect, followed by “mm” or double quote or the word “inches” 3″ or 75mm
Number of shells (must be in the VDL or description; not importable as a separate column) A number following the word “Chain” or phrase “Chain Of” Chain Of 5 or Chain 5
Duration For chains, the duration is from first ignition to last ignition, in seconds.  The format is a number, followed by the character “s” or the word “seconds” 10s or 2.5s
Height Meters The lift height in meters, followed by “m” 90m
Prefire For chains beginning with aerial shells, the prefire is both the lift time of the first shell effect type, and also the delay between the chain’s ignition and effect time in the script, which is coincident with the first shell’s break; the format is a number, followed by “s” followed by “PFT” with a space after the “s” 2.3s PFT
CDS The term CDS means “chain delay in seconds“. The term is used in between plus signs (+) separating the shells in a chain description, to specify individual delays between the shells.  A full chain description can contain multiple CDS terms, one for each shell except for the first. Chain Red Peony + 1.0 CDS Blue Peony + 2.0 CDS Green Peony

VDL is not capable of representing chains with multiple size shells.