Software Documentation

Software Documentation

Visual Descriptive Language (VDL)Documentation

Last updated: September 12, 2023

8 Exact simulation syntax

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.