VDL Documentation

CakesVDL Documentation

Last updated: August 10, 2019

1 Cake descriptions

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:

  1. The word “Cake”.  Don’t forget to include the word “Cake” either at the beginning or end of the body.
  2. 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”.
  3. 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
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)
Size 3in Integer or float followed by “in” or double quote for inches or “mm” for millimeters
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)
(30mm/aaaaaaaaaa*)
(0.2/30mm/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] [size slash] effect-labels [slash pattern] [slash number] [asterisk]

A complication that programmers implementing VDL programs may need to account for is that if there are 18 different kinds of effects in the cake (which is pretty unusual), then the tube labels could be “mm”, which complicates the parsing because of the ambiguity of whether “mm” is effect labels or a designation of millimeters for the size field.   To resolve the issue, the syntax includes the stipulation that if the effect labels happen to be “in” or “mm”, then either the delay or caliber must also be supplied if the duration is supplied.

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.

 

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 TRI 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.