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.

For purposes of designing a show, you may not need a perfect simulation of a cake that you are planning on using.  That's a good thing because if your cake is a consumer cake with a name like Galactic Gladiator, you may not have much to go on to make a VDL description.  Luckily, VDL makes it easy to create a simple "placeholder" cake simulation using whatever information you do have, which is often enough for designing a show. An example of a simple cake VDL description is, 30mm 49 Shot 10s Time Rain Comet Cake Z-Shape To put a description like this together, start with the size, then number of shots, then the duration, then the primary effect in the cake, then the word "Cake" and then the firing pattern (or leave the firing pattern blank if it is just straight up).  Optionally, you can include the prefire and the height, as in, 30mm 49 Shot 10s 2.1s PFT 90m Multi-Color Peony Cake Z-Shape 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)   If you are using the Hobbyist or Pro version of Finale 3D, you have the option of importing your effects from a CSV file.  In this case, the size, duration, height, and prefire (but not the number of shots) 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: 49 Shot Multi-Color Peony Cake Z-Shape Table 1 provides guidance for the format of the optional metrics of a cake. Table 1 – Basic cake 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 shots The number of shots, followed by the word "Shot"; if the number of shots is 10 or less, then the cake is considered a single row slice cake; optionally you can also specify the number of rows by adding "N Rows" after the word cake, where N is the number of rows 10 Shot Duration For cakes, the duration is from first shot to last break, 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 If prefire < 0.5, it specifies the "delay before simulation"; if prefire >= 0.5, is specifies the lift time for aerial shells; the format is a number, followed by "s" followed by "PFT" with a space after the "s" 2.3s PFT Firing pattern The firing pattern can be left blank for straight up shots, or can be one of these words: Z-Shape, X-Shape, Fan, or FNR; FNR means "fan to the right in sequence", in contrast to "fan" which implies simultaneous shots on each row Fan Some types of effects used in a cake could be single rising effects or shells.  For example, does a 50mm Crossette Cake shoot crossette stars or shells containing crossette stars?  In general, VDL interprets ambiguous effect descriptions in cakes as rising effects instead of shells.  You can explicitly change the description to be a shell by adding the word "Shell" or "Aerial" to the description, as in, 50mm 10 Shot Aerial Time Rain Cake which shoots 10 shells, as opposed to, 50mm 10 Shot Time Rain Cake which shoots 10 comets. VDL is capable of representing complex cake descriptions, including cakes that have multiple types of effects, and rows with different firing patterns and timings.  The basic parameters described in Table 1, though, are usually enough to create a cake simulation that adequate for scripting.