NOTE: the easiest way to create a cake in Finale 3D is to lay out effects on the timeline, then select them, and then do the menu item, "Effects > Create cake from selected items...", which will present a dialog showing the VDL that represents the cake.  The function automatically figures out the rows and firing patterns of the cake based on the spacing of the effects on the timeline (i.e., the delays between them) and their angles.  You can look at the VDL to understand the syntax. Like all VDL descriptions, cake descriptions can specify a height and duration, as you can see are 100 meters and 10 seconds in the example, 50mm 10s 100 Shot 100m Fan Cake (a) Gold Tail + (b) Red Mine 10 Rows Row 1,2,3,4,5,6,7,8,9,10 (ababababab) For cakes, the duration is the duration of the cake itself (first ignition to last break, see Cake duration details), not the duration of the effects in the cake.  So you may be wondering how you can specify the durations of the individual effects within the cake.  The VDL term "DUR" is the answer.  If you want to specify the duration of the red stars to be 2.3 seconds in the above example, you can use the VDL, 50mm 10s 100 Shot 100m Fan Cake (a) Gold Tail + (b) 2.3 DUR Red Mine 10 Rows Row 1,2,3,4,5,6,7,8,9,10 (ababababab) Unlike the duration specified at the beginning of the effect description (10s), the DUR terms specify the durations of the effects used within the cake.  If a cake contains various effect descriptions separated by plus signs (+), each effect description can contain a DUR expression, which applies only to that specific effect within the cake. A similar approach satisfies the need to specify heights of the individual effects in the cake, which is particularly important for cakes that combine multiple kinds of effects that have vastly different heights, like mines and comets.  Figure 1 shows a picture of a fan cake with mines and comets without any individual height specifications.  The height of the cake, 100m, applies to everything within the cake, which is too high for the mines.   Figure 1 – A cake VDL that doesn't specify individual effect heights has the same height for everything.   The "HTM" term specifies the "height in meters" of an individual effect.  Similar to the DUR term, the cake VDL can contain an HTM specification for each effect description, separated by the plus signs. 50mm 10s 100 Shot 100m Fan Cake (a) Gold Tail + (b) 25 HTM Red Mine 10 Rows Row 1,2,3,4,5,6,7,8,9,10 (ababababab) This cake VDL looks a lot more accurate, as you can see in Figure 2.   Figure 2 – The HTM ("height in meters") term in VDL specifies individual effect heights.   The fan angle of the cake is also controllable, using the term "Degrees" at the beginning of the cake description, as in, 50mm 10s 100 Shot 100m 130 Degrees Fan Cake (a) Gold Tail + (b) Red Mine 10 Rows Row 1,2,3,4,5,6,7,8,9,10 (ababababab) The fan angle applies to any rows in the fake that have angles.

The VDL language supports whatever degree of detail you want to include in your cake descriptions.  Descriptions can be generic, like, 49 Shot Red Pearl Z-Shape Cake or more specific, like, 49 Shot 5s (a) Red Pearl + (b) Blue Pearl Cake Z-Shape, 7 Rows, Row 1,3,5 (aaaaaaa), Row 2,4,6 (bbbbbbb), Row 7 (1.2/abababa/FNT) If you want to specify the firing pattern for each row of a cake, then your VDL cake description will look more like the specific example, above, and it will contain row descriptions for every row in the cake. In this example, rows 1, 3, and 5 have a simple row description, specifying seven shots of effect (a), the Red Pearl. Rows 2, 4, and 6 are similar for effect (b). But row 7 includes more specifications. The three letter "FNT" at the end of the row 7 specifications is the "Firing Pattern Keyword", which specifies the angles of the shots in the row, and whether there are delays between the shots, and which end of the row is ignited to shoot first. In this specific example, the term "Z-Shape" in the body of the cake description defines the default firing pattern for the cake as a whole.  Z-Shape declares the rows will fan shots from left to right and back, alternating with each row.  Since the firing descriptions for rows 1-6 do not specify any changes to that default firing pattern, the Z-Shape firing patterns will apply to rows 1-6.  But row 7 does specify a change, with the firing pattern keyword, FNT.  The term "FNT" stands for Fan-together.  This last row of the cake is thus an all-at-once fan of seven shots of alternating colors based on the letters (a) and (b). If a cake description doesn't include any firing patterns in the body of the description, then the default firing pattern for every row will be the Up-Sequence firing pattern, abbreviated "STR", which means all the tubes are aiming straight up (the “ST” for straight up) and they are fired in left to right order in the row (the “R” for left to right order). A similar firing pattern is Up-Reverse, abbreviated "STL", which is the same except fired in the reverse order, right to left.   The left-to-right or right-to-left order distinction matters when the row contains multiple kinds of effects (the a's and b's, for example) in a non-symmetric pattern. A third straight up example is Up-Together ("STT") which is all tubes firing at the same time.  Two other common fan firing patterns are "FNR", and "FNL", for Fan-Right, and Fan-Left.  The full list of firing patterns is defined in Table 1.   Table 1 – Firing pattern keywords Firing pattern keywords Term Pattern Timing Description Ignited from which end Also called STR ||| Sequential Up-Sequence Left STW STL ||| Sequential Up-Reverse Right STT ||| All-At-Once Up-Together Undefined ALR \ Sequential Left-Sequence Left AGW (and also see Table 2 of Cake descriptions) ALL \ Sequential Left-Reverse Right ALT \ All-At-Once Left-Together Undefined AGT ARR /// Sequential Right-Reverse Left ARL /// Sequential Right-Sequence Right ART /// All-At-Once Right-Together Undefined FNR |/ Sequential Fan-Right Left FNW (and also see Table 2 of Cake descriptions) FNL |/ Sequential Fan-Left Right (see Table 2 of Cake descriptions) FNT |/ All-At-Once Fan Undefined ATF (and also see Table 2 of Cake descriptions) BLR | Sequential Stand-Right Left BKW (and also see Table 2 of Cake descriptions) BLL | Sequential Fall-Left Right (see Table 2 of Cake descriptions) BLT | All-At-Once Left-Bookend Undefined BKT (and also see Table 2 of Cake descriptions) BRR |/ Sequential Fall-Right Left (see Table 2 of Cake descriptions) BRL |/ Sequential Stand-left Right (see Table 2 of Cake descriptions) BRT |/ All-At-Once Right-Bookend Undefined CTO |/ Sequential Center-Out Center CRN (and also see Table 2 of Cake descriptions) OTC |/ Sequential Outside-In Left And Right (see Table 2 of Cake descriptions) TRI |/ All-At-Once W-Shape * Undefined (see Table 2 of Cake descriptions) TRX |/ All-At-Once W-Shape * Undefined TRS |/ Sequence-Of-Ws W-Shape * Right End Of Left Tubes, And Left End Of Center Tubes, And Left End Of Right Tubes (see Table 2 of Cake descriptions) VST / All-At-Once V-Shape Undefined VSS / Sequence-Of-Pairs V-Shape Center (see Table 2 of Cake descriptions)   * TRX is the same as TRI except when the number of tubes in a row is not divisible by 3: TRI adds the remainder as straight tubes; TRX adds the remainder as angle tubes. For example, TRI of 11 tube rows has the pattern 3-5-3, whereas TRX has the pattern 4-3-4. TRS defines a sequence N / 3 Ws, for N = the number of tubes in the row.  If N / 3 has remainder 1, then the extra tube is the left-most center tube; and it is shot along with the tube immediately to its right and the right-most left tube and the left-most right tube, i.e., the first W having 4 tubes shooting simultaneously instead of three.  If N / 3 has remainder 2, then the extra tubes are the right-most left tube, and the left-most right tube; and the extra tubes are shot with their immediate neighbors and the left-most center tube, i.e., the first W having 5 tubes shooting simultaneously.    

The standard syntax for cake descriptions described in Cake descriptions represents not just the visual appearance of the cake but also the physical construction of the cake tubes in rows.  For example, the standard syntax cake description, 49 Shot 5s (a) Red Pearl + (b) Blue Pearl Cake Z-Shape, 7 Rows, Row 1,3,5 (aaaaaaa), Row 2,4,6 (bbbbbbb), Row 7 (1.2/abababa/FNT) has seven rows of seven shots each, and the rows of tubes are angling all left and all right for the first six rows, and then fanned out for the last row.  The standard syntax is capable of representing most physically realistic cakes, but there are cakes that the standard syntax cannot represent, such as cakes with angles or timing that don't match the standard row patterns described in Firing patterns for cake and slice rows.  For all the cakes that cannot be represented in the standard syntax, you can use the exact simulation syntax VDL to produce an exactly matching visual representation without any relationship to the physical construction of the cake. The show import functions and the "Effects > Create cake by combining selected effects..." function fall back upon the exact simulation syntax VDL automatically when the standard syntax is unable to represent the visual appearance of the cake.  If you create cakes without being particularly attentive to the exact angles or timing, you are likely to run into exact simulation syntax a lot.   Exact simulation syntax The equivalent exact simulation syntax VDL for the standard syntax cake description above is, 49 Shot 5s (a) Red Pearl + (b) Blue Pearl Cake, 1 Row (-30a93/-20a/-10a/0a/10a/20a/30a/b/20b/10b/0b/-10b/-20b/-30b/a/-20a/-10a/0a/10a/20a/30a/b/20b/10b/0b/-10b/-20b/-30b/a92/-20a/-10a/0a/10a/20a/30a/b/20b/10b/0b/-10b/-20b/-30b1200/a0/-20b/-10a/0b/10a/20b/30a/CAK)   As you can see, the exact simulation syntax has exactly one row.  The row specifies every shot in the cake individually.  Thus the cake in this example has 49 tube description sections in its exact simulation syntax firing description (the part in parentheses after "Cake, 1 Row"). The tube description sections are separated by slash characters.  Finally, after the last tube description section is the designator "/CAK" which indicates the phrase in an exact simulation syntax firing description.   Tube description sections Each tube description section specifies (1) the left/right angle, (2) the tube label, and (3) the delay after the tube.  The examples in Table 1 represent the first tube in the cake description above.   Table 1 – Components of tube description sections Component Example Explanation Angle -30 Integer angle in degrees with positive numbers to the right; required for the first tube description section, and optional in the following sections Tube label a A single letter referencing a label in the body of the cake description (see Cake descriptions); required for all tube description sections Delay 93 Integer milliseconds; optional for all tube description sections; ignored for the last section if present   Compressing the representation Since the exact simulation syntax represents every tube individually, a cake with a large number of tubes can yield quite a large exact simulation syntax representation.  To minimize the size of the representation, the optional components in the tube description section can be skipped.  When they are not present, the meaning is that they are the same as the previous tube.  In the example cake description above, the first 42 tubes are separated by 93ms delays, yet the number 93 is only required explicitly for the first tube in that sequence. The 42nd tube is followed by a 1.2s delay, or 1200ms, and the remaining tubes are all shot at the same time according to the FNT firing pattern.  Notice the "/-30b1200/a0/" near the end of the cake description, above.  In the exact simulation syntax representation, the 1200ms delay and the first 0ms delay obviously need to be specified, but only once.  Thus the cake description above requires only three delays in the representation in total: 92, 1200, and 0.  That's a lot more compact that 49 delays! The same elision rule applies for the optional angle of the tube, except that the first angle is required in all circumstances. As a matter of convenience, if all of the delays are skipped, then the meaning is that all the delays are the same and that they add up to make the specified duration of the cake match the time from the first shot to the last break.  For effects without breaks, like comets, that is equivalent to saying the delays add up to the duration of the cake, but for shells the duration of the cake includes the lift time of the final shot, so the calculated delays need to take that into account.  

NOTE: The easiest way to create a cake in Finale 3D is to lay out effects on the timeline, select them, and then go to, "Effects > Combine as cake effect...". This will present a dialog showing the VDL that represents the cake.  The function automatically determines the rows and firing patterns of the cake based on the arrangement of the effects on the timeline (i.e., the delays between them) and their angles.  You can look at the VDL to understand the syntax. Cake and candle descriptions are based on the sub-effects that they contain, so they may require an additional layer of information to define the arrangement of the sub-effects into rows and tubes, and the firing pattern of those tubes.  Cake and candle descriptions thus comprise one or more shots of the other basic effect types (shell, mine, comet, etc.), plus the additional layer of information. VDL supports multiple levels of detail. For example a simple cake description is, 49 Shot 5s Cake A more complex description that includes multiple effect types in multiple firing patterns is, 49 Shot 5s (a) Red Pearl + (b) Blue Pearl Cake Z-Shape, 7 Rows, Row 1,3,5 (aaaaaaa), Row 2,4,6 (bbbbbbb), Row 7 (1.2/abababa/FNT) The longer example describes a zipper cake with 6 rows of alternating colors, and finally a last row with alternating effects in the tubes in an all-at-once fan, preceded by a 1.2 second delay.  The syntax of a cake description breaks down into auxiliary specifications, body, and row specifications.  From the example above, the three parts, in order, are, 30mm 49 Shot 5s ---- auxiliary ------- (a) Red Pearl + (b) Blue Pearl Cake Z-Shape ---------------------- body --------------------- 7 Rows, Row 1,3,5 (aaaaaaa), Row 2,4,6 (bbbbbbb), Row 7 (1.2/abababa/FNT) -------------------------------------- row specifications ---------------------------------------- The body contains one or more effect descriptions of the shots in the cake, separated by plus signs, with single letter labels in parentheses that the row specifications can refer to for the tubes.   The row specifications can optionally specify the number of rows, their tube layout, the timing, and the firing patterns of the effects.  Within the row specifications, the parts in parentheses are called the firing description; they apply to the rows identified immediately before.  In the above example, the firing description (a) applies to rows 1, 3, and 5. The firing description (b) applies to 2, 4, and 6. And the firing description (1.2/abababa/FNT) applies to row 7. Firing descriptions are optional. If not explicitly provided, the default firing descriptions are based on equal timing between firing events, and cycling through the defined effects in each row.   Getting the structure right Human beings are a lot better at understanding improperly formed VDL effect descriptions than software programs, so you might find yourself looking at a VDL cake description that looks perfectly sensible to you but that doesn't produce the correct simulation in a software program.  Cakes are particularly sensitive to the placement of a few of the terms, so to get the structure of cake descriptions right, here's what to remember: The word "Cake".  Don't forget to include the word "Cake" either at the beginning or end of the body. The word "Row".  The word "Row" or "Rows" is a special marker.  Everything before the first occurrence of the word "Row" (except the number immediately preceding it) comprises the auxiliary specifications and body parts of the description;  everything after comprises the row specifications.  The word "Cake" must therefore go before the word "Row". The plus signs ("+").  If the cake contains multiple effects, then the plus sign ("+") separates the effect segments within the body of the description, and a single letter in parentheses in each segment is the segment's label.  The labels can go anywhere within the segments, as long as they are on the correct sides of the plus signs.   Firing descriptions Firing descriptions contain information that specifies the construction of a row. The attributes that you can define are,   Table 1 – Firing description attributes Attribute Example Characters Delay before row 0.2/ Integer or float at the beginning; the delay has no effect on the first row, which always has zero delay no matter what delay is specified in the firing description Duration of row /1.2 Integer or float before the asterisk if present, or otherwise at end Effects in the tubes, left to right abababa Letters referencing labels in the body Firing pattern FNT Three letter firing pattern keyword (See Firing patterns) Firing in parallel with previous row * Asterisk at end of description   All the attributes in a firing description other than the asterisk are separated with forward slash, as in these examples: (0.5/abababa/FNT) (ababababa/FNR) (0.2/ababababa/FNR/0.75) (aaaaaaaaaa*) (0.2/ababababa/FNR/0.75*) The numbers in the firing descriptions refer to the delay prior to the row if they are at the beginning of the phrase (0.5 and 0.2 in the above examples) or to the duration if they are not at the beginning (0.75 in the example).  All the attributes are optional except the effect labels corresponding to the tubes.  Thus the syntax for the row description is, [number slash] effect-labels [slash pattern] [slash number] [asterisk] The three letter firing pattern defines the firing order and angles of the tubes in the row.  "FNT" stands for Fan-Together.   "FNR" stands for Fan-Right.   The full list of firing pattern keywords and their descriptions are here: Firing patterns for cake and slice rows.   Exact simulation syntax The firing descriptions in Table 1 are called "standard syntax firing descriptions" because they represent both the physical arrangement of the cake tubes in rows and the corresponding visual appearance.  The standard syntax is capable of representing most physically realistic cakes, but there are cakes that the standard syntax cannot represent, such as cakes with angles or timing that don't match the standard row patterns.  For those cakes, you will need to use the exact simulation syntax VDL representation instead, as described in Exact simulation syntax.   Setting the number of rows, and number of tubes per row If the number of rows isn't explicitly specified, then a default of 1 row is implied if the effect has 12 or fewer shots; otherwise a default is calculated based on the square root of the number of shots. The exception to this rule is that the firing patterns W-Shape and V-Shape imply a default number of tubes per row of 3 and 2, respectively. If you specify a different number of tubes per row for those two firing patterns, the angles are doubled or tripled up. If the number of rows evenly divides the number of shots, then the default tubes per row is simply the quotient: number of shots / number of rows. Otherwise the individual row lengths are implementation dependent (although they must add up to the correct number of tubes).  If the default isn't right, you can set the tubes per row explicitly in the firing descriptions based on the number of tube labels, as the following example illustrates: 10 Shot Peony Cake 3 Rows, Row 1 (aaa), Row 2 (aaaa), Row 3 (aaa) The number of tube labels defines the number of tubes in that row, overriding the default (3, 4, 3 in the above example).   Setting the tubes’ effects The effect labels in the firing description specify the effects in the row’s tubes, beginning with the left-most tube.  The order of the tube labels in the firing description is unaffected by which end of the row is ignited first.  Thus if the left end of the row is ignited first, then the first effect in the specification is the first to go; if the right end of the row is ignited first, then the first effect in the specification is the last to go.   Setting the firing pattern and tube angles The firing pattern and tube angles are determined by firing pattern terms in the body of the cake description (like "W-Shape" or "Zipper"), which apply to the whole cake, or in the row descriptions (three letter terms like "STR" for Up-Sequence), which apply to the rows individually.  If the firing description doesn't include a firing pattern for the cake as a whole, then the default firing pattern of Up-Sequence (STR) applies to all rows. Returning to the complex description example from the beginning of this section, the firing pattern "Z-Shape" in the body of the description defines the default firing pattern for all the rows, fanning from left to right and back again, alternating each row.  The last row's firing pattern, "FNT", overrides the default Fan-Right implied by the Z-Shape with Fan-Together, which makes all tubes in the last row fire together instead of in sequence. 49 Shot 5s (a) Red Pearl + (b) Blue Pearl Cake Z-Shape, 7 Rows, Row 1,3,5 (aaaaaaa), Row 2,4,6 (bbbbbbb), Row 7 (1.2/abababa/FNT) The firing pattern prescribes the firing order, in addition to the angles of the tubes. The default Up-Sequence firing pattern (STR) prescribes that all the tubes are aiming up and are fired in sequence, left to right.   Other terms like "STL" fire in the opposite order, from right to left.  The three letter firing pattern keywords like STR and STL are modeled after terms in Vulcan's modular cake specifications.  The full list is given in Firing patterns for cake and slice rows. Adding to the firing pattern keywords that can occur in firing descriptions, Table 2 shows the list of  firing terms that can appear in the body of the cake description.   Table 2 – Firing patterns that can occur in the body of the description Firing pattern term Explanation Firing pattern term Explanation 1 X-Shape Alternating CTO and OTC 7 Z-Shape Alternating FNR and FNL 2 C-Shape CTO for all rows 8 W-Shape TRS for all rows 3 V-Shape VST for all rows 9 R-Shape Same as X-Shape 4 Zipper Same as Z-Shape 10 Peacock Same as X-Shape 5 Bookend BLT for all rows 11 Angle ALR for all rows 6 Wipe FNR for all rows 12 Fan FNT for all rows   Adjusting the timing for each row You can specify the delays or durations of the rows explicitly, or you can use the default times based on the overall effect duration. It is often easier to begin with the defaults and adjust the times of specific rows to suit. The default delays are calculated such that all of the non-zero delays between firing events are the same. Thus if all the tubes were aiming up and had the same effect, you couldn't tell from the visual appearance how many rows the cake had. If you want to increase the delay between the rows such that the rows fire in recognizable flights, simply specify the delay times in the fronts of the firing descriptions. The asterisk symbol in a row description indicates the row fires in parallel with the previous row, which applies to cakes constructed with multiple rows firing together.  A V-shaped cake could be constructed with 4 rows of 10 tubes angled in the same direction, as in, 40 Shot 20s (a) Red Pearl + (b) Blue Pearl Cake 4 Rows, Row 1,3 (aaaaaaaaaa/ARL), Row 2,4 (bbbbbbbbbb/ALL*) The same visual appearance would be produced by a cake with 20 rows of 2 tubes per row in opposing angles: 40 Shot 20s Red Pearl + Blue Pearl Cake V-Shape (20 Rows) For this V-shaped cake, the two tubes in each row are the red and blue pearls, obviously, so the default effect assignment suffices. In the absence of firing descriptions, there is no need for the (a) and (b) labels on the components.   No delay in front of the first row Any delay applied to the first row's firing description has no effect.  Consider this VDL describing a cake with five rows of sequenced shots followed by a sixth row of shots all together: 2" 8.57s 30 Shot (a) Red Comet Cake, 6 Rows, Rows 1,2,3,4,5 (0.3/aaaaa/STR/1.2), Row 6 (1.37/aaaaa/STT) The five rows all have the same firing description with a 0.3 delay, but the delay won't apply to the first row because the first row always has a zero delay no matter what its firing description says.  This zero delay characteristic of the first row is convenient -- it means the first row can use the same firing description as the other rows that are same except for their delay, making for shorter a shorter VDL.

The VDL language includes the list of color terms in Table 1, which can be included in effect descriptions, as in "Red Chrysanthemum w/ Blue Pistil". In addition to specifying the color itself, some of these terms imply the existence of a trail of sparks. For instance, a "Red" comet is just a star with a big red flame envelope, whereas a "Silver" comet is a comet with a silver trail of sparks.   Figure 1 – VDL colors corresponding to Table 1     Table 1 – List of color terms # Color RGB components Hex code Implies trail of sparks Alternative that does not imply trail 14 Aqua 0.20, 0.50, 0.80 337fcc 11 Blue 0.30, 0.40, 1.15 4c66ff - Charcoal N/A N/A Yes Charcoal Tip - Charcoal Tip 0.90, 0.40, 0.10 5a280a 16 Cyan 0.32, 0.64, 0.80 51a3cc - Dark 0.00, 0.00, 0.00 000000 5 Fresh Yellow 0.70, 0.60, 0.35 b29959 20 Fuchsia 0.85, 0.35, 0.90 d859e5 - Gamboge N/A N/A Yes Gamboge Tip - Gamboge Tip 1.0, 0.35, 0.05 ff9959 - Gold N/A N/A Yes Gold Tip - Gold Tip 0.80, 0.70, 0.05 504605 9 Grass Green 0.25, 0.70, 0.05 3fb20c 8 Green 0.15, 0.70, 0.11 26b21c 17 Indigo 0.50, 0.25, 1.15 7f3fff 18 Lavender 0.63, 0.25, 1.15 a03fff 7 Lemon 0.75, 0.60, 0.05 bf990c 10 Lime 0.35, 0.70, 0.11 59b21c 22 Magenta 0.80, 0.10, 1.00 cc19ff 3 Orange 0.90, 0.40, 0.10 e56619 4 Peach 0.80, 0.50, 0.10 cc7f19 19 Pink 0.85, 0.35, 0.75 d859bf 23 Plum 0.70, 0.10, 0.50 b2197f 21 Purple 0.75, 0.25, 1.15 bf3fff 2 Red 0.95, 0.10, 0.10 f21919 1 Ruby 0.95, 0.10, 0.30 f2194c 12 Sea Blue 0.25, 0.50, 1.15 3f7fff - Silver N/A N/A Yes Silver Tip - Silver Tip 0.75, 0.75, 0.85 4b4b55 13 Sky Blue 0.20, 0.50, 0.80 337fcc 15 Turquoise 0.16, 0.64, 0.80 28a3cc 24 Violet 0.80, 0.40, 1.00 cc66ff 25 White 0.75, 0.75, 0.85 bfbfd8 6 Yellow 0.80, 0.70, 0.05 ccb20c In addition to the color terms, other terms in the VDL language also imply the existence of a trail of sparks. For example, some flower types, like Chrysanthemum or Willow, inherently include trail of sparks no matter what color terms are used to describe them. Other flower types, like Peony and Dahlia, do not. It is possible in VDL to declare that star does not leave a trail of sparks despite its flower type by including "No Trail" in the description, such as "Red Chrysanthemum No Trail".

The VDL language includes terms to affect the timing of the simulation.   Table 1 – VDL terms that affect timing Term Meaning Explanation Example Scope PFT Prefire PFT < 0.5 defines delay before simulation; PFT >= 0.5 defines aerial shell lift time 50mm 1.5 PFT Red Peony Effect LFT Lift delay Aerial shell lift time (overrides prefire) 50mm 1.5 PFT 1.75 LFT Red Peony Shot DLY Delay before simulation A delay from ignition to when the simulation begins 50mm 10 Shot 10s Cake 2.0 DLY Red Comet Effect DUR Duration For aerial shells in cakes, the duration of the stars; For mines and comets in cakes, the duration of the rising effect; 50mm 10 Shot 10s Cake .75 DUR Red Peony Shot part (applies only in cakes, multi-shot candles, and chains) CDS Chain delay seconds The delay  between the previous shell and this shell in a chain 3" 7s Chain of 3 Red Peony + 3.0 CDS White Peony + 4.0 CDS Blue Peony Shot (applies only in chains)   Prefire/PFT The term "prefire" means the time from firing system ignition to the effect time that is synchronized to the music.  For aerial shells, the prefire is usually associated with the lift time.  In fact, the association is so close that people often use the terms interchangeably.  VDL supports this common usage with the special rules, PFT < 0.5 defines delay before simulation; PFT >= 0.5 defines aerial shell lift time In other words, if the PFT is a small fraction of a second, then it refers to the latency introduced by the firing system or the time it takes for the effect to get started.  If the PFT is in the range that could be a lift time, then that's what it is.  These rules work almost all the time, so you usually don't need to give much thought to it. The rules even work for combination effects like RED PEONY w/ BLUE MINE, or BLUE MINE w/ RED BOMBETTES.  If you want to synchronize the launch of the mine to the music, specify a small prefire < 0.5.  If you want to specify the break of the shell to the music, specify a larger prefire, being the lift time of the shell.   LFT and DLY In circumstances for which the prefire rules are insufficient, the LFT and DLY terms in VDL specify the lift time and delay before simulation, taking precedence over whatever the default lift time would be or whatever the prefire implies.  Consider the case of a bombette roman candle with a 1.0 second fuse prior to the first launch, and then 2.0 seconds between the shots, and finally 3.0 seconds lift time in each of the bombettes.  You can define this effect in VDL as, 50mm 21.0s 4.0 PFT 10 Shot RC 1.0 DLY Pink Peony w/ Green Mine 3.0 LFT Breaking this phrase apart, you can see the 3.0 LFT time at the end, defining the lift time.  The 1.0 DLY is the delay before simulation, representing the delay before the first launch as the visco fuse works its way down into the roman candle tube to the first shell.  The 4.0 PFT aligns the prefire with the first break, which occurs at 1.0 seconds + 3.0 seconds = 4.0 seconds after the firing system ignition.  What would the choreographer write instead if he wanted to synchronize the music to the launch of the green mine instead of the shell break? (answer: write 1.0 PFT)   DUR The roman candle example illustrates the need for another duration term.   For cakes and multi-shot candles, the duration term in the VDL (21.0s in the roman candle example, above) or in the Duration column in the effect window in Finale 3D defines the shot timing, not the duration of the stars in the shot.  For example, you can specify a RED PEONY with 1.25 second duration stars simply by typing, 1.25s Red Peony But if you want to include that shell in a cake or candle, you would have no place to put the 1.25s duration specification because the duration in a cake or multi-shot candle VDL would be interpreted as the shot timing specification, namely the time from the first launch to the last break (more details here).  The DUR term in VDL fills the need, as you can see in, 50mm 21.0s 4.0 PFT 10 Shot RC 1.0 DLY Red Peony 1.25 DUR 3.0 LFT   CDS The duration of chains is the first to last shot, so it is easy to write VDL for chains with the same delay between shells.   If a chain has 10 shells, then there are nine delay gaps between the shells (no delay in front of the first), so the overall duration of the chain is 9 times whatever the delay is between the shells.  If the delay is 3 seconds, the chain is 27 seconds long, 100m 27s Chain of 10 Gold Willow If you want to specify delays individually between the shells so they don't all have to be the same, you can use the CDS term, as in, 100m 27s Chain of 10 Gold Willow + 4 CDS Green To Blue Ghost Shell + 4 CDS Red Chrysanthemum w/ Green Pistil + 2 CDS Purple Dhalia w/ Crackle Core + 2 CDS Silver Kamuro + 3 CDS Green To Blue Chrysanthemum + 3 CDS Red &amp; Green Atomic Rings + 2 CDS Pink Crossette + 3 CDS Variegated Shell-Of-Shells + 4 CDS Pink Yellow Half-And-Half Shell   Figure 1 – Irregularly spaced shells in a chain, as shown on the timeline in Finale 3D.   Scope The scope of the VDL term means how much of the VDL phrase it applies to.  The PFT and DLY apply to the entire effect, even if the effect is a cake or chain, because the entire effect can have only one prefire time and it has only one "delay before simulation".  Thus you can put the PFT and DLY terms anywhere in a VDL phrase and it doesn't make any difference. CDS obviously applies to a single one of the chain shells.  Chains in VDL that are not all the same effect use the plus sign to separate the shots of the chain.  The CDS term applies to the shot that it is in, between the plus signs. DUR applies only to shots within cakes and candles.  It is not needed for individual effects because the standard duration terminology applies (a number followed by the letter 's').  Within cakes and candles, the DUR applies to the shot part.   The shot part is usually just the shot itself, except for the case of shots that combine mines with comets or shells, in which case the shot part is either the mine or the comet or the shell, not all three together.  Thus you can specify RED PEONY w/ BLUE MINE 1.5 DUR, and the indicated duration applies just to the blue stars of the mine. You might guess that LFT also applies to the shot part, but it actually applies to the entire shot, because LFT only applies to aerial shells and even shots with multiple parts have only one aerial shell part, so it suffices to put LFT anywhere in the shot.   Using LFT to override the prefire on the first shell of shell cake The prefire of a cake, if at least a half second long, defines the default lift time of the first effect in the cake if that effect is a shell, and does not affect the default lift time of the subsequent effects if they are different (details here).  These mechanics produce the desired result most of the time, but not all the time.  The 11 shot Dahlia cake shown in Figure 2 has a prefire that is not intended to be the lift time of any of the shells, but according to the mechanics of VDL the prefire affects the default lift time of the first shell, making the first shell break on the way up, differently from the other shells.   Figure 2 – The prefire of a shell cake affects the lift time of the first shell.   The VDL of the cake with the first shell breaking on the way up, shown in Figure 2, is, 30mm 0.6 PFT 11 Shot Cake (a) Red Dahlia w/ Red Tail + (b) Green Dahlia w/ Green Tail + (c) Blue Dahlia w/ Blue Tail + (d) Yellow Dahlia w/ Yellow Tail + (e) Orange Dahlia w/ Orange Tail + (f) Purple Dahlia w/ Purple Tail + (g) Peach Dahlia w/ Peach Tail + (h) Lemon Dahlia w/ Lemon Tail + (i) Aqua Dahlia w/ Aqua Tail + (j) Violet Dahlia w/ Violet Tail + (k) Fuchsia Dahlia w/ Fuchsia Tail, 1 Row (abcdefghijk/FNT) To fix the lift time of the first shell, simply insert an LFT term for the first shell, as in, 30mm 0.6 PFT 11 Shot Cake (a) 1.6 LFT Red Dahlia w/ Red Tail + (b) Green Dahlia w/ Green Tail + (c) Blue Dahlia w/ Blue Tail + (d) Yellow Dahlia w/ Yellow Tail + (e) Orange Dahlia w/ Orange Tail + (f) Purple Dahlia w/ Purple Tail + (g) Peach Dahlia w/ Peach Tail + (h) Lemon Dahlia w/ Lemon Tail + (i) Aqua Dahlia w/ Aqua Tail + (j) Violet Dahlia w/ Violet Tail + (k) Fuchsia Dahlia w/ Fuchsia Tail, 1 Row (abcdefghijk/FNT) The adjusted VDL fixes the lift time, as shown in Figure 3.   Figure 3 – Use LFT to fix the lift time if the prefire sets an undesired default lift time.      

The VDL language includes a set of adjectives to adjust certain characteristics of the effect description, such as the size of a shell’s break or the number of stars in the break.  Here is the list of adjectives and their meaning. Meaning Small adjustment Medium adjustment Large adjustment Expand the size of the shell break or mine spread Slightly big Big Very big Reduce the size of the shell break or mine spread Slightly small Small Very small Brighten the stars and their trails of sparks Slightly bright Bright Very bright Darken the stars and their trails of sparks Slightly dim Dim Very dim Brighten the trails of sparks Slightly bright trail Bright trail Very bright trail Darken the trails of sparks Slightly dim trail Dim trail Very dim trail Brighten the stars Slightly bright tip Bright tip Very bright tip Darken the stars Slightly dim tip Dim tip Very dim tip Increase the number of stars Slightly dense Dense Very dense Reduce the number of stars Slightly sparse Sparse Very sparse Thicken the trail of sparks from the stars Slightly thick Thick Very thick Thin out the trail of sparks from the stars Slightly thin Thin Very thin Lengthen trail spark duration Slightly long trail Long trail ("trail" not "tail") Very long trail Shorten trail spark duration Slightly short trail Short trail Very short trail Lengthen star duration Slightly long Long Very long Shorten star duration Slightly short Short Very short Make gerb/fountain sparks last longer Slightly droopy Droopy Very droopy Make shell break pattern more ragged Slightly ragged Ragged Very ragged Make shell break pattern more uniform Slightly uniform Uniform Very uniform Even more pronounced alterations are possible by repeating adjustment adjectives in a VDL effect description. For example, to very significantly reduce the number of stars in a mine you would type, "Very Big Very Big". In this way, each repetition of the VDL large adjustment adjective will further compound the changes to the effect. In a VDL effect description, the position of the adjectives determines what part of the description they apply to.  For example, if you type, Red Peony w/ Big Blue Pistil That is obviously going to be different from, Big Red Peony w/ Blue Pistil Similarly, if you type, Bright Red To Green Chrysanthemum That will be different from, Red To Bright Green Chrysanthemum A good rule of thumb is that prepositions like “To” and “With” divide the effect description up into parts, and you need to make sure that your adjectives are in the right parts of the description.  Within a part of the description, however, the position of adjectives doesn’t matter, so, Red Peony w/ Big Blue Pistil Is the same as: Red Peony w/ Blue Pistil Big The ability to locate adjectives before or after the noun or pronoun that they modify makes VDL easier for non-English users, because unlike English, many languages have a “post-nominal” grammar in which adjectives follow the noun or pronoun they modify.   Angles VDL also includes a set of adjectives to set the angle of the effect: R15, R30, R45, R60, R75, R90, R105, R120, R135, R150, R165, R180, and the same for L15, L30, etc.  These adjectives tilt the trajectory left or right by the indicated number of degrees.  For example, the VDL, Flame Projector L105 is the VDL for the Explo X2 Wave Flamer pre-programmed Macro #16, which fires a column of flames at 105 degrees to the left.

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.

In Finale 3D, the angles of effects are represented as three numbers: pan, tilt, and spin.  Of the many possible ways to represent angles, Finale 3D chooses this representation because the three numbers, pan, tilt, and spin, correspond directly to the three degrees of freedom of a moving head light fixture.  If you ever forget what pan, tilt, and spin mean, you can just imagine a moving head light fixture in the orientation of Figure 1, and the meanings of the angles will pop out as the only possibilities. It bears mentioning here that positions in the scene (pyro launch positions and DMX fixtures) use a different representation for their angles that is more natural for their orientations (heading, pitch, and roll).  The positions' angle representation is described in Positions coordinate system. For fireworks effects, the three angles of a moving head light fixture may seem excessive.  A fireworks show whose effects are either aiming straight up or tilting left and right would only need one angle.  But if effects can also tilt forward toward the audience then a second angle is required.  If the show contains cakes that can be flipped around to face the opposite direction then a third angle is required.  So while one angle is enough for many kinds of fireworks shows, it takes three angles to cover all the possibilities, even for fireworks. Figure 1 – To understand pan, tilt and spin, imagine a moving head light fixture.   Pan, tilt, and spin The picture in Figure 1 is the image to have in mind for the definitions of pan, tilt, and spin, even if what you care about is fireworks.  The moving head light fixture has three degrees of freedom, which correspond to the pan, tilt and spin. With pan, tilt, and spin all being zero, the head of fixture and thus its beam direction aim straight up, as in Figure 1.  The head is mounted in a U-shaped yoke on an axis that enables the head to rotate forward toward the viewer by the tilt.  With angles being zero the U-shaped yoke is facing the viewer.  The yoke itself is mounted on a base plate in a fashion that enables it to rotate on the plate by the pan to face different directions, toward the viewer, to the side, etc. Although it isn't visible in Figure 1, the head may contain a stencil pattern internally, through which the light beam shines to make a pattern like the Batman logo that is projected into the clouds on television.  The stencil, which is called a "gobo", can rotate by the spin.   You can easily imagine the projected Batman logo spinning in the clouds, and you connect that image to the rotating gobo in the light head. With the mechanical model of Figure 1 firmly in mind, you can relate the definitions of pan, tilt, and spin to the three possible rotations of the moving head fixture: Pan is the rotation on the base. Tilt is the rotation in the yoke. Spin is the rotation around beam axis.   "Right Hand Rule" All three of these rotations follow the "Right Hand Rule" to resolve whether positive angle rotations are clockwise or counter-clockwise.  The Right Hand Rule states that if you hold your right hand out with your thumb aiming in the direction of the axis of rotation, then your fingers will curl in the direction corresponding to a positive angle.  Following this convention, pan rotates the yoke around to the right, counter-clockwise as seen from above.  Tilt rotates the head toward the viewer.   Spin rotates Batman logo on the beam to the right, counter clockwise.   Table 1 – Order of Euler Angle rotations producing a rotated vector v' from vector v v' = v * R1 * R2 * R3 Rotation First rotation (R1) Rotate around global Y-axis by spin Second rotation (R2) Rotate around global X-axis by tilt Third rotation (R3) Rotate around global Y-axis by pan   As you can see, the order of the three rotations matters to their definition.  Spin and pan are actually rotations around the same global Y-axis, differing only by which one is the first rotation and which one is the last rotation.  Referring back to the moving head light fixture of Figure 1, the order of rotations of Table 1 is the only possible choice that matches the physical constraints of the fixture.  If pan were the first rotation, for example, then tilting around the global X-axis wouldn't be possible because the yoke wouldn't necessarily be facing forward.   Table 2 – Range of angles in conversions from orientations Angle Range Pan (-180°, +180°] Tilt [0°, +180°] Spin (-180°, +180°]   Any orientation can be represented by pan, tilt, and spin angles in the ranges of Table 2.   Some orientations have multiple representations within these ranges that are equivalent.  If tilt is 0° then pan and spin do exactly the same thing!  Mathematically, in this Euler Angle representation all rotation sequences with tilt = 0° or 180° are equivalent to a rotation sequence in which +/- pan and spin sum to a constant value.  In circumstances in which an orientation is converted to a rotation sequence that is not uniquely defined, Finale 3D will choose the rotation sequence with spin = 0°, which creates a 1-to-1 relationship between orientations and Euler Angles in the ranges of Table 2.  These ranges are not limits, though, in Finale 3D's user interface and tables.  You can enter any pan, tilt and spin value into the script table columns, including numbers outside these ranges.   Orientations of pyro effects The firework example in Figure 2 is as simple as can be -- a comet effect is tilted 45 degrees to the right.  You might expect that an example like this would have pan = 0, tilt = 45, and spin = 0 since the tilt seems like the only rotation, but if you look again at Figure 1 you will remind yourself that when pan = 0 the tilt rotates toward the audience.  Thus, tilting an effect to the right requires pan = 90 to rotate the yoke shown in Figure 1 to face to the right, enabling the tilt to rotate the effect 45 degrees to the right instead of toward the audience.  Thus Figure 2 shows pan = 90, tilt = 45.  If you want to confirm the pan = 90 you can try this simple example yourself and then unhide the Pan column in the script window from the blue gear menu in the upper right.   Figure 2 – A comet or shell tilted 45 degrees to the right has pan = 90, tilt = 45, spin = anything.   Unlike the Batman logo in the moving head light example, the comet in Figure 2 is rotationally symmetric.  Spinning a comet around its beam axis doesn't make any difference, so the spin in Figure 2 can be anything.  That's not true for cakes with angles though, such as the fan cake shown in Figure 3.   Figure 3 – A tilted fan cake requires spin = -pan to face the audience while tilted, e.g.,  pan = 90, tilt = 45, spin -90.   Tilting a fan cake to the right requires all three angles -- pan, tilt, and spin.  The pan = 90 makes the yoke face the right, which is required for tilting it to the right.  Tilt = 45 tilts the cake to the right, same as in Figure 2.  But if spin is 0, the fan cake will still face the right, on account of the pan = 90.  Instead of the image of Figure 3, we'd be looking at the fan from the side, and the image would look more like Figure 2!  Setting spin = -pan returns the effect to face the audience while tilted.  The tutorial of Video 1 includes an example of a tilted cake.   Video 1 – Tutorial for pan, tilt, and spin