Creating Effects By Animation Search Phrase


The easiest way to construct simulations for effects is by describing them in text. Often, the effect name itself is a reasonable description, so for many types of effects Finale can construct simulations simply from the effect name. The text description is called an Animation Search Phrase. It is an English language description of the simulation. It may be the same or different from the name of the effect, which could also be in a non-English language.

Finale interprets whatever text description you've written and translates it to a standard description format, called VDL, which you can read to verify that Finale's interpretation is correct. There are many different ways to describe effects in English, so sometimes you need to re-phrase your English description to get the interpretation you want.

Once the VDL interpretation is correct, then Finale constructs a new simulation using the VDL as a recipe for the construction. Every simulation that Finale creates from a description is tailor made based on the VDL. Thus there are an infinite number of possibilities. Whatever you can describe, Finale will build.

In order to get predictable VDL interpretation results from your English descriptions, it is useful to understand the VDL language standard. The closer your English descriptions are to the VDL standard, the easier it is to know what the VDL translation is going to be. If your English descriptions are in the VDL format to begin with, then the translation will be identical to what you originally typed.

This section describes the VDL language so you can create all kinds of effects, from a simple 3" Red Peony to a multi-effect cake in which you've specified the physical construction of the cake including the fusing, the row timing, the firing order, the angles, and all of the individual effects used in the cake.

Basic Effect Name Patterns

The easiest way to explain a language is by example, so the table below gives a set of examples for all the major kinds of effects. You can refer to this list as a guide.



Basic mine

Red Mine

Stars transitions

Red To Swimming Stars Mine

Other stars mixed in

Red Mine w/ Swimming Stars

Shell or bombettes lifted by mine

Blue Peony w/ Red Bouquet



Basic tail attached to aerial effect

Red Peony w/ Gold Tail

Star transitions

Red Peony w/ Red To Blue Tail

Generic rising flowers

Red Peony w/ Rising Flowers

Specific rising flowers

Red Peony w/ Red Falling Leaves Rising




Rising Silver Tourbillions

Star with tip

Red Pearl

Star with trail

Gold Tail


Crackling Comet

(Explicitly “Rising” to avoid ambiguity with aerial shell)

Rising Gold Crossette Comet

Rising Gold Willow Tail



Stars with tips

Red Pearl Cake

Stars with trails

Gold Tail Cake


Rising Silver Tourbillions Cake

(Explicitly “Rising” to avoid ambiguity with aerial shell)

Rising Gold Willow Tail Cake

Rising Red Pearl To Brocade Cake

Different color rising effects

Multi-Color Pearl Slice



Basic cake of aerial shells

Red Peony Cake

Gold Willow Cake

(Explicitly “Aerial” to avoid ambiguity with rising effect)

Aerial Silver Tourbillions Cake

Shells with multi-color stars

Varg Peony Cake

Yellow & Green Peony Cake

Shells with same color stars; each shell different color

Rainbow Peony Cake

Multi-Color Peony Cake

Yellow Peony + Green Peony Cake



Single effect

10 Shot 75’ 10s Red Pearl Roman Candle


10 Shot 2.5s Red Pearl + Green Pearl Plate



Basic aerial shell

Red Peony

(Not in cake, so no need for explicit “Aerial” term)

Silver Tourbillions

With pistil

Blue Peony w/ Red Pistil

With additional petal

Red Peony w/ Blue Ring

Stars or inserts mixed in

Red Peony w/ Blue Stars

Red Peony w/ Tourbillions Inserts

Additional break

Silver Twisters + Purple Peony Peanut

Multi-break cylinder shells

Cylinder Red Peony + White Peony + Blue Peony

Star transitions

Brocade Crown To Crackling

(Left-most flower type, Wave, defining break)

Gold Wave To Blue Diadem

Simple color change; trail only on first phase

Red Chrys To Blue

Simple color change; trail on first and second phase

Red To Blue Chrys



Aerial shell with comet-like stars

Comet Shell

(Explicitly a “Comet Shell” to avoid ambiguity with rising)

Gold Crossette Comet Shell

(“Shell” term not required in “with” phrase)

Gold Kamuro w/ Silver Comet Pistil

(“Shell” term not required when shape of petal specified)

Crossette Comet Ring



Single effect

Ti Salute Chain Of 5


Color Peony Chain of 10

Red Peony + White Peony + Blue Peony Chain of 10

With duration

5s Gold Willow Chain of 5



Fountains, jets, and gerbs

10 Shot 10s 5m Silver Fountain Plate

30’ Silver Jet

15s Crackling Gold Gerb



Fireballs, rockets, girandolas, flame pots, etc.

150’ Red To Blue To Report Girandola

5s Flame Pot

Horse Tail Rocket w/ Strobing Tail

Most standard pyrotechnic effect terms are included in the language of VDL. Finale also recognizes more than 1000 other common words and expressions found in effect names and translates them to the standard terms in VDL. The set of recognized terms is comprehensive enough that you don't have to worry too much about using a word that Finale doesn't recognize, but if you want to look over the list of terms that are actually in VDL, the list is at the end of this section.

Effect Adjustments

Once you've found the way to describe the effect you want, you can adjust the simulation of the effect by adding adjectives like Big or Bright. VDL includes a spectrum of adjectives to adjust the break and the stars, as in 3" Big Red Peony or 3" Small Chrys w/ Bright Even Length Red Ring. The adjectives are listed here: Adjectives.

Auxiliary Specifications

The examples in the table above show just the basic effect description patterns. In addition to the duration and number of shots, you can add specifications for the prefire time, effect height, cone angle, and of course caliber. The full list of auxiliary specifications is,





2.5" or 30mm

For cakes or candles, the inside diameter of the tube unless otherwise indicated on a per-row basis of cakes. For shells, the diameter of the shell. For other items, the tube size most representative of the size of the effect.

Number Of Shots

49 Shots

For cakes and candles, the number of tubes or balls.



For cakes, candles and chains, the time delta between the first and last effect ignition. For fountains, flames, or other continuous effects, the visual duration of the effect. For all other effects, including aerial shells, VDL does not ascribe any meaning to the duration term, allowing you to give it your own meaning for these effects, such as the duration of the stars or the duration from break to final dissipation of sparks, etc. Except for cakes, candles, chains and continuous effects, the duration term will not affect simulations based on VDL, so if you want to adjust the duration of the stars or sparks in an aerial shell, for example, use the effect adjustment adjectives like "long" or "long trail".


150' or 30m

The height of the apex break, for aerial shells, or the height of the stars or particles for mines or fountains. With respect to cakes, the cake's height applies to all effects within the cake.


25 Degree

The full spread, in degrees, between the left-most and right-most aiming tubes in a cake.

Prefire Time

2.5s PFT

The script time delta between the firing system's ignition of the effect and the designated visual impact of the effect (often called "display time" or "view time" or "effect time"). Additionally, for cakes and candles the prefire specifies the time between the ignition of the cake or candle itself and the ignition of its first effect (thereby implying that the "display time" of a cake or candle is the ignition of its first effect). For independent aerial shells, the prefire specifies the break time of the shell, but only if the prefire is non-zero. For independent non-aerial effects (comets, mines, fountains, etc.) and for effects inside cakes or candles or chains, the prefire does not specify anything about the break times or durations.


Chain of 10

Indicates a pre-defined chain of N effects, equally spaced over the specified duration if indicated, otherwise firing together as if connected by quickmatch. VDL syntax cannot represent chains that contain cakes, candles, or continuous effects like fountains, though scripting programs may support ad-hoc chains of individual effects connected together by fuse.

Number Of Rising Flowers

Red Peony w/ Four Times Rising Flowers

The spelled out number "N Times" indicates the number of rising flower breaks on an aerial shell.

Multiple Effects

Red Peony + Blue Peony Peanut Shell

Cakes, candles, chains, peanut shells and cylinder shells can all contain multiple effect definitions, separated by the plus sign (+). The plus sign in VDL is not the same thing as ampersand. The plus sign combines multiple effects; the ampersand combines multiple colors in the same effect.

Combining all these elements together, you can write a fully specified effect name like,

50mm 25 Shot 30s 100' Rainbow Mine Cake (0.1s PFT, 25 Degree)

Cake Specifications

The table of patterns covers individual effects and the basic syntax for describing cakes, but it stops short giving examples of detailed cake specifications. The VDL language is capable of representing cakes with a short description of the essential characteristics as you might see in a list of effects, but also with longer descriptions that spell out every detail of the firing pattern, angles, timing, and so forth.

The short descriptions, like "50mm 25 Shot 30s Multi-Color Peony Cake" may be all you need for choreography purposes, but if you want to spell out the details to generate an accurate simulation, the following sections show how.

Cake Example

In Finale, if you type the phrase Red Pearl Fan Cake into the "Effects > Create new simulation" dialog, you'll get a single row, 10 shot fan cake that looks like this,


Finale has set the number of shots to 10 arbitrarily since it wasn't specified in your search phrase. Typing a search phrase that includes two effect components separated by a plus sign, like Red Pearl + Wave Tail Fan Cake, yields this cake,


Since the search phrase didn't specify which effect components belonged in which tube, Finale has filled them into alternating tubes by default. If you want to specify the tubes, you can type a phrase like, 42 Shot (a) Red Pearl + (b) Gold Wave Tail + (c) Popcorn Crackle Cake 7 Rows Row 1,2,3,4,5 (abababa) Row 6 (c).


The more detailed search phrase defines three effect components and gives them labels a-c. Then it defines the tubes in rows 1-5 to use alternating effects between effect "a" and effect "b". Finally, it specifies the last row uses effect "c" for all its tubes.

Multi-Effect Cakes

It takes a lot of information to fully describe a complex cake, but sometimes you just want a simple placeholder. The goal of VDL is to make it possible to specify complex effects while still making it simple to specify simple effects. For example a simple cake description is,

30mm 49 Shot 5s Red Pearl Cake

A more more complex description that includes multiple effect types in multiple firing patterns is,

30mm 49 Shot 5s (a) Red Pearl + (b) Blue Pearl Cake 7 Rows, Z-Shape, Row 1,3,5 (a), Row 2,4,6 (b), Row 7 (1.2/abababa/FNT)

This 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. In VDL you can also define different numbers of tubes per row, and different calibers, as shown in this cake layout for a Dominator cake:

Complex tube layout

To make cake simulations, you can start out with a simple VDL description and add as much information as you need to get the level of detail you want. If you want, you can go all to way to fully specifying the construction of the cake, including its specific fusing and delays.

The syntax for VDL cake descriptions is an Effect Description Body followed by Effect Description Details. The above example breaks down into:

Effect Description Body

Effect Description Details

30mm 49 Shot 5s (a) Red Pearl + (b) Blue Pearl Cake

7 Rows, Z-Shape, Row 1,3,5 (a), Row 2,4,6 (b), Row 7 (abababa/FNT)

The Effect Description Body contains the VDL information that defines all of the effects used in the cake, and the Effect Description Details include the specifications for constructing the cake, including the layout, timing, and firing pattern of the effects. In addition to the number of rows (7 Rows) and default firing pattern (Z-Shape), the Effect Description Details may include Firing Descriptions applied to specific rows. 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 (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.

Firing Descriptions

Firing Descriptions contain information that specifies the construction of a row. The attributes that you can define are,




Delay before the row


Integer or float (at the beginning)

Duration of the row


Integer or float (not at the beginning)

Effects in the tubes, left to right


Letters referencing labels earlier in description

Firing pattern


Three-letter keyword from table below



Integer or float followed by double quote or "mm" for millimeters

Firing in parallel with previous row


Asterisk at end of description

In a Firing Description, all the attributes other than the asterisk are separated with forward slash, as in these examples:


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). If there is an asterisk, it must be last.

More formally, the syntax of the firing description begins optionally with a number representing the delay followed by a slash, then optionally continues with a caliber followed by a slash, then includes a sequence of letters identifying the effects (required), then optionally continues with a slash followed by a firing pattern name, then optionally continues with a slash followed by the duration number, then optionally continues with an asterisk. Using square brackets to indicate the optional terms, the syntax is:

[number slash] [caliber slash] tubeLabels [slash pattern] [slash number] [asterisk]

There is one extremely minor exception to this syntax: If the letters identifying the effects happen to spell "in" or "mm" (very unusual but technically possible since all individual letters are valid effect labels), then either the delay or caliber must also be supplied if the duration is supplied. The letters identifying effects are usually patterns like "abcde" or "ababa" or "ccccc" so this exception rarely applies.

Parentheses And Punctuation In VDL

In VDL, all parentheses and punctuation (comma and dash) are optional. It is customary to put tube labels and firing descriptions in parentheses, but not required. Ampersand and the plus sign, however, have specific meaning -- ampersand to combine colors, and plus sign to combine multiple effects (see Auxiliary Specifications, above). Ampersand and the plus sign are not interchangeable.

Setting The Number Of Rows, And Tubes Per Row

An effect description optionally specifies the number of rows explicitly as in the following example:

2" 10 Shot 30s Red Strobing Peony Cake (3 Rows)

If the number of rows isn't explicitly specified, then a default of 1 row is used if the effect description 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, if present in the effect description, 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 as in the picture below.

W-shape cake with 9 tubes per row

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 default number of tubes for all rows except the last is the quotient rounded up, and the final row is the remainder, or a single tube if the remainder is negative or zero. For example, by default a 10 shot 3 row cake would have 4, 4, and 2 tubes in its rows. 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 and corresponding tube diagram illustrate:

2" 10 Shot 30s Red Strobing Peony Cake 3 Rows, Row 1 (aaa), Row 2 (aaaa/STL), Row 3 (aaa)

If firing description includes more than one tube label, then the number of tube labels defines the number of tubes in that row, overriding the default (3, 4, 3 in the above example).

This example effect description defines a tube layout and firing order that looks like the picture below (rows shown vertically in the diagram). The description doesn't include a firing pattern for the cake, so the default firing pattern of Up-Sequence (STR), which is ignited on the left end, applies as the default firing pattern for all three rows. In reality, the center row would be ignited on the right so that the fuse runs conveniently zigzag through the rows. The firing keyword STL in the Firing Description for row 2 in the above VDL changes the firing order to right to left. Thus the tubes are ignited in the order of the numbers in the diagram.

Complex tube layout

Setting The Effect In Each Tube

A firing description specifies the effects in the tubes by referring to their lower-case letter effect labels from the body of the effect description. For example, the effect description,

30mm 7 Shot 0s (a) Red Pearl + (b) Blue Pearl Cake 1 Row, Row 1 (abababa)

specifies that the first and only row has tubes with alternating Red Pearl and Blue Pearl effects, beginning with the left-most tube being a Red Pearl. By default, if you don't explicitly specify the effects in the tubes, the tubes will cycle through the effects in order, so in this example there is no difference between the default and the specification.

If you include just a single tube label, then it applies to all the tubes in the row without setting the number of tubes. If you include more than one tube label, then the number of tube labels defines the number of tubes in the row.

30mm 49 Shot 5s (a) Red Pearl + (b) Blue Pearl Cake 7 Rows, Row 1,3,5,7 (a), Row 2,4,6 (b)

The effect specifications are interpreted left-to-right, independent of the firing order. 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. The firing pattern table below defines for each firing pattern which end of the row is ignited first (or center).

Setting The Firing Pattern And Tube Angles For Each Row

The firing pattern is the firing order and angles of the tubes in the row. By default, a cake effect description with no firing pattern specified will have an Up-Sequence firing pattern, abbreviated STR, which means all the tubes are aiming up and they are fired in sequence, left to right. A similar firing pattern is "Up-Reverse", abbreviated STL, which is the same except fired in the reverse sequence, right to left. A third example is Up-Together (STT) which is all tubes firing at the same time.

The three letter firing pattern keywords in VDL are modeled after terms in Vulcan's modular cake specifications. Vulcan and other vendors can use the same term for Up-Sequence and Up-Reverse because they are the same product except for one is rotated around 180 degrees (Vulcan uses STW). However VDL's keywords also have to indicate the orientation of the row in the cake, so distinctions like STL versus STR are required.

In VDL the tube effect specifications are always left-to-right. Firing patterns ending in the letter "R" like STR that fire left-to-right will fire effects in the same order as in your specification. If you don't care about the physical construction of the cake and its fusing, then you could achieve the same visual effect without ever using an Up-Reverse firing pattern by simply using the Up-Sequence firing pattern instead and reversing the order of your effect specifications for the tubes. There is nothing wrong with that approach if all you care about is the visual appearance of the simulation. If you are using VDL for applications that rely on the physical construction of the cake, then your specification obviously should match the physical construction.

The table below is the exhaustive list of the Firing Keywords that can be included in the Firing Description to specify the pattern. They are organized in groups of similar tube arrangements. Notice that the first three rows in the table are sequential left-to-right (ignited on the left), sequential right-to-left (ignited on the right) and all together (ignited either side). The last letter in the keyword, R, L, T is an indication of which end is ignited.

VDL Firing Keywords

Firing Keyword




Which End Ignited

Alternate VDL terms
































































































































Left And Right





W-Shape *






W-Shape *






V-Shape *


* The description TRI in the body of the effect name will also imply three tubes per row as a default. 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. The description VST will imply two tubes per row as a default.

In the table above, the "Firing keywords" and "Alternate VDL terms" can be included inside the Firing Description to define the firing pattern of a specific row, or outside the firing description to define the default firing pattern for all rows. The individual firing descriptions obviously override the defaults.

The table below shows the list of additional firing keywords that specify default firing patterns for all the rows, but that cannot be included within the Firing Description of any single row. Some of these firing keywords like Zipper or X-Shape apply different defaults to the odd and even rows, as explained in the table.

Firing keyword



Alternating CTO and OTC firing patterns for odd and even rows


Alternating FNR and FNL firing patterns for odd and even rows


FNT for all rows


TRI for all rows


VST for all rows


Same as X-shape


Same as Z-shape


Same as X-shape


BLT for all rows


ALR for all rows


FNR for all rows


FNT for all rows

Adjusting The Timing For Each Row

In VDL you can specify the delays or durations of the rows explicitly, or you can use the default times. It is often easier to begin with the defaults and adjust the times of specific rows to suit. Consider the example,

30mm 49 Shot 5s (a) Red Pearl + (b) Blue Pearl Cake 7 Rows, Z-Shape, Row 1,3,5 (a), Row 2,4,6 (b), Row 7 (0.5/abababa/FNT)

you can see that the delay before the last row is set to 0.5 seconds. The FNT firing keyword from the table above is an all-at-once firing pattern, as you can tell by the fact that the last letter in the keyword is "T". Thus the duration of this row is zero. If the pattern were FNR or FNL then the duration would include a delay between each tube.

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.

Cakes are sometimes constructed with multiple rows firing together. For example, you can build a V-shaped cake with pairs of parallel-firing rows having all the tubes in one row firing to the left and all the tubes in the other row firing to the right. In a VDL Firing Description the asterisk symbol indicates the row fires in parallel with the previous row. Thus the V-shaped cake could be constructed with 4 rows of 10 tubes angled in the same direction, as in,

30mm 40 Shot 5s (a) Red Pearl + (b) Blue Pearl Cake 4 Rows, Row 1,3 (a/ARL), Row 2,4 (b/ALL*)

The exact same visual appearance would be produced by a cake with 20 rows of 2 tubes per row in opposing angles:

30mm 40 Shot 5s Red Pearl + Blue Pearl Cake V-Shape

This second description is particularly short because the V-Shape firing pattern description applies to the entire cake and implies by default that rows have two tubes per row. In the absence of Firing Descriptions with effect specifications, the default is that the tubes are assigned effects sequentially in the order in which they are defined, cycling if there are more tubes than defined effects. For this V-shaped cake, the two tubes in each row are the red and blue pearls, obviously, so the default effect assignment suffices. The final contribution to the brevity of this phrase is the fact that in the absence of Firing Descriptions, there is no need for the (a) and (b) labels on the components.

Appendix A: List Of Defined Terms

The following are the basic terms that Finale uses for constructing simulations. When Finale imports an inventory of effect names, it translates the effect names from whatever style they are written in to the patterns described in this paper, using only the terms in this list plus the extra terms for cake specifications. Then Finale builds the simulations from the translated effect names. To read the existing inventories AS IS, Finale recognizes also about 1000 other words and phrases, taking into account common misspellings and alternative descriptions.











Aeolian Bells










Air Burst


Letter-A Pattern





Letter-S Pattern





Letter-U Pattern







Wind Bells

Atomic Rings






Double Rings


Silver Flower


Dragon Eggs


Silver Tipped



Midnight Snow



Falling Leaves









Morning Dew

Small Flowers



Moving Stars

Smiley Face Pattern



Nishiki Kamuro



Flame Projector




Flash Pot



Bowtie Rings

Flash Tray

Olympic Rings

Stained Glass




Star Pattern






Flying Fish


Strobe Pot
















Swimming Stars




Swinging Stars






Ghost Ring

Pixie Dust


Champagne Gerb







Thousand Flowers


Go Getters

Popcorn Crackle

Ti Report




Ti Salute


Gold Tipped


Tiger Tail




Time Rain





Color Changing








Comet Shell


Revolving Dragons


Concentric Rings

Happy Stars


Triple Concentric Rings

Crackle Core

Heart Pattern


Triple Cross Rings


Horse Tail

Rising Flowers

Triple Rings

Crackling Flowers



Twilight Glitter









Cross Rings












Crown Flower




Appendix B: Syntax For Colors, Mixed Colors, Crossettes, And Shell-Of-Shells

Colors are identified by name from a pre-defined list of color names: Red, Green, Blue, etc. To identify multiple color stars in a break, use the ampersand between them, as in,

Red & White & Blue

To indicate color transitions, use the word "To" between the colors, as in,

Red To White To Blue


Putting the two syntaxes for combining colors together, you can specify crossette stars that start out as a single color and split into two colors of children,

Red To White & Blue Crossette

Or crossette stars of multiple colors that split into a single color,

Red & White To Blue Crossette

Or crossette stars of multiple colors that split into multiple colors,

Red & White To Blue & Green Crossette

Or just crossette stars of multiple colors that split into the same colors as the parent,

Red & White & Blue Crossette

The first color in a color transition is interpreted to be before the split. Subsequent transitions are after the split. If no transitions are indicated, then the child stars from the split take on the same color as their parent.


A shell-of-shells effect name is just the subshell's effect name, followed by the words "Shell-Of-Shells", as in,

Red Peony Shell-Of-Shells

If the effect name begins with multiple colors, the colors indicate multiple kinds of subshells. Thus,

Red & Blue Peony Shell-Of-Shells

includes two kinds of subshells: red and blue. It does not include a subshell with mixed red and blue stars because in VDL the interpretation with homogeneous star colors in a shell or shot of a multi-shot effect takes precedence over an interpretation with mixed star colors when both interpretations are possible.


If you want mixed stars, you can write,

Red & Blue Mixed Peony Shell-Of-Shells

adding the word "Mixed" to indicate that the colors apply to mixed stars within each subshell or shot instead of applying one color per subshell or shot. The following example illustrates the difference between a cake of nine tubes (shots) with alternating colors or red, white and blue, versus a cake of nine tubes each with red, white and blue stars.

9 Shot Red & White & Blue Mine Cake
9 Shot Red & White & Blue Mixed Mine Cake

Variegated, Rainbow, And Multi-Color

The word "Variegated" or "Varg" for short applies to mixed color stars in a shell or mine. It is similar to writing "Red & Yellow & Green & Orange & Purple" except that the colors are never interpreted to apply to a subshell of a shell-of-shells as a whole or to separate shots of a multi-shot effect; the colors always apply to mixed stars.

The word "Multi-Color" applies to subshells of a shell-of-shells, or to separate shots of a multi-shot effect; never to mixed stars. Thus "Varg" and "Multi-Color" may mean the same set of colors, but they apply to different things. You can imagine the difference between these two shell-of-shells:

Varg Peony Shell-Of-Shells
Multi-Color Peony Shell-Of-Shells

In some effect names, the word "Varg" or "Multi-Color" has no meaning because it doesn't apply. These two effect names make no sense:

10 Shot Varg Rising Pearl Cake
Multi-Color Peony

(The rising pearls are each a single star shot, so each one can be at most one color, not a mixture of variegated colors. The multi-color peony is a single shell, so only one color of the multi-color set can apply.)

The word "Rainbow" is like "Multi-Color", applying to subshells or shots but not mixtures of stars. "New-Color" and "Color" are just like lists of colors; they can apply subshells, shots, or mixed stars.

Complex Combinations

Combining all these syntaxes, you can create specific combinations of colors, crossettes, and shell-of-shells, as in these two very different shells:

Varg Crossette Shell-Of-Shells
Multi-Color Crossette Shell-Of-Shells

the first having identical subshells containing mixtures of star colors; the second having different color subshells with homogeneous colored stars.

If you wanted a shell-of-shells breaking into identical subshells each with red stars that split into multi-colors, you could write,

Red To Varg Crossette Shell-Of-Shells

Appendix C: Syntax For Tip Colors, Trails, And Crackle

Some flower types like "Chrys" imply that the stars have trails of sparks. Others like "Peony" imply that they don't. But these implications are not hard and fast rules. They are defaults that apply in the absence of more specific information. When you describe a shell with more specific information, the rules become complicated.

Tip Colors Versus Trail Colors

To begin with, some colors and adjectives refer to the flame envelopes of stars, whereas others refer to the trails. If an effect description contains a color or adjective that refers to flame envelopes, the presence of those words implies that the stars do indeed have flame envelopes.

The same goes for trails. So if you write,

Crackling Peony

then the stars have trails (that crackle) in addition to flame envelopes. If you write,

Red Chrys

then the stars have red flame envelopes in addition to the trails.

Since the number of trail colors for the most common effects is limited to just gold and silver, and maybe gamboge, these three color names ("Gold" "Silver" and "Gamboge") are used exclusively in VDL to refer to trails, and the presence of these color names implies the stars have trails. All other colors refer to flame envelopes, and their presence implies the stars have flame envelopes.

Thus these effect names all have flame envelopes (two of them also having trails),

Red Chrys
White Kamuro

And these effect names all have trails (three of them also having flame envelopes),

Gold Peony
Silver Dahlia
Red Chrys

If a trail is implied but its color is not specified, its color is taken to match the flame envelope color if it is explicitly identified and an exact match exists, and is gold otherwise. If a flame envelope is implied but its color is not specified, its color is taken to match the effective trail color, whether explicit or default. Thus a "White Crackling Chrys" will have a silver trail (to match the white flame envelope), but "Red Chrys" will have a gold trail.

Gold Tip And Silver Tip

Sometimes the words gold and silver are used in effect names intentionally to refer to the flame envelope, as opposed to a trail. To support this use, while still living within the color rules above, VDL defines the terms "Gold Tip" and "Silver Tip" to mean gold and silver as applying to the flame envelope. Thus, for example, you could describe an Chrysanthemum with silver tips and trails as,

Silver Tip Silver Chrys

although you could equivalently just write,

Silver Tip Chrys

since the chrysanthemum flower type implies the existence of a trail and since the trail color, if not specified, will be taken to match the flame envelope color (silver tip).

Gold tip and silver tip also have a special meaning in addition to indicating the color of a flame envelope. Since gold and silver have a metallic connotation, these tip colors additionally imply a tiny, glittery trail of sparks behind the flame envelope, which distinguishes these tip colors from the pure flame envelope color specifiers yellow and white.

Color Changes And Transitions

If an effect name articulates a transition to the right of the flower type, any trail implied by the flower type does not apply to to the transition unless explicitly mentioned. So,

Red Chrys To Blue

begins as stars with a red flame envelope and gold trail, and transition to a blue flame envelope and no trail. If you want the trail in the blue phase, you must explicitly mention it by indicating a trail color, and optionally the non-significant word "Tip" to make the word sequence more readable:

Red Chrys To Blue Tip Gold

Transitions to the left are the same, with one exception: if the flower type is not adorned by any adjectives applying to flame envelopes or trails other than a single flame envelope color, and if all the transition phases to the left of the flower type also consist of only a single flame envelope color, then the transition is a special type of transition called a "simple color change," the significance of which is that flame envelope and trail properties implied by the flower type do apply to transitions on the left for simple color changes. Thus in the effect name,

Red To Blue Chrys

both the red phase and the blue phase of the stars have a gold trail.

Tail (No "R")

The word "Tail" (as opposed to "Trail") describes rising effects. As discussed in the section below on tails and pearls, if the word "Tail" is used in the context of an independent rising effect, it implies all phases of the effect leave a trail of sparks.

No Trail (Trail with an "R")

You can cancel the trail property of a star that would otherwise impute a trail from its flower type by adding the adjective phrase "No Trail" to that phase of the star. For instance:

Red No Trail To Blue Chrys

will have no trail in the red phase, and will have a gold trail in the blue phase. The "No Trail" designation also applies to rising effects.

No Tip / Dark

Analogous to "No Trail" you can cancel the tip property of a star that would otherwise impute a tip from its flower type by adding the adjective phrase "No Tip" to that phase of the star. The term "Dark" is a synonym. For example:

Red To No Tip To Blue Peony
Red To Dark To Blue Peony

both mean the same thing, a color changing star with a dark phase between the red and blue.

Crackle Colors

Crackling star trails include energetic sparks that pop. Simply adding the word "Crackling" to an effect description implies the star has trails and that the trail has crackling sparks.

By default, the sparks are the same color as the trail, but VDL defines a special set of colors that apply specifically to the crackling sparks, without applying to the non-crackling sparks of the same star trails. Using these crackle colors, you can introduce a second color into a trail, and you can make the standard trail colors -- gold, silver, and gamboge -- more chromatic.

The crackle colors are easy to recognize. They are just standard color names, but ending in "-ish", as in, "Green-ish" or "Red-ish". Since these "ish" color names are all distinct, there's never any question as to whether they refer to crackle or trails or tips. They always refer to crackle. Here are some examples,

Red-ish Gold Comet
Silver Tip Blue-ish Silver Chrys

This second example explicitly specifies the tip color, the crackle color, and the trail color of the chrysanthemum, all three types of colors.

Like trail colors, crackle colors even by themselves in an effect name imply the star has a trail. If unspecified, the color of an implied trail is the default color. So in the example,

Green-ish Peony

the "Green-ish" color implies the peony stars have trails of a default color (gold), and the trails additionally have mixed in crackle sparks of the specified color, green-ish.

Appendix D: List Of Colors

The full list of colors is shown in this table, grouped by what they apply to.

Tip Colors

Trail Colors

Crackle Colors
















Appendix E: Syntax For Tails And Pearls

The words "tail" and "trail" are often confused, because they mean almost the same thing, and they differ by a single letter. The difference matters subtly in syntax: a "trail" is a path of sparks. A "tail" is either (a) a rising effect attached to a shell that may or may not not include a trail of sparks (it could be just a flame), or (b) an independent rising effect that necessarily does include a trail of sparks (otherwise it would be called a "pearl").

Examples illustrate the difference. In VDL, if you write,

Red Peony w/ Blue Tail

the rising effect attached to the shell has a blue flame envelope and no trail of sparks because none is indicated or implied by the word "tail" in the context of an effect attached to a shell.

However, if you write,

Rising Blue Tail

the independent rising effect has both a blue flame envelope, because it is indicated by the tip color "blue", and a trail of sparks implied by the term "tail" in the context of the independent rising effect.

The word "pearl" means an independent rising effect with a flame envelope. Since "pearl" only applies to independent rising effects, it has no ambiguity. It always implies a flame envelope, and could additionally have a trail of sparks if implied by a trail color or effect:

Red Pearl (red flame envelope)
Gold Pearl (gold tip flame envelope and gold trail of sparks)

Appendix F: Rising Effects

Rising effects come in three types: individual comets, or stars or inserts shot from cake and candle tubes (independent rising effects), continuous effects attached to shells that trace a path along the shell's trajectory (attached rising effects), and small shells attached to a launched shell that break at intermediate points in the launched shell's trajectory (rising flowers). VDL supports all three types of rising effects.

Independent Rising Effects

Independent rising effects encompass the entire physical body of the projectile, for if they did not they would be attached rising effects. Simply writing,

Brocade Tail
Brocade Tail To Report

or substituting "Pearl" or "Comet" for "Tail" in VDL will define an independent rising effect. The term "Report" in VDL refers to an explosive charge inside a star or insert. The term "Salute" in VDL refers to an explosive charge in an aerial shell. Thus "Brocade Tail To Report" is an independent rising effect, whereas "Brocade Tail To Salute" is an aerial shell with an attached rising effect.

In the context of cakes and candles, the terms "Crossette" (a splitting star) and "Tourbillions" (an insert) will refer by default to independent rising effects, though they can also refer to aerial shells by the same name if so indicated (see below to differentiate).

An alternate way of writing an independent rising effect uses the term "Rising" instead of the term "Tail", e.g,

Rising Brocade
Rising Brocade To Report

Effect names that begin with "Rising XXX To YYY" or "XXX Tail To YYY" describe an independent rising effect unless YYY implies a default petal shape or payload of a shell. Thus,

Red Tail To Blue
Red Tail To Crackling
Red Tail To Report

are all independent rising effects, whereas,

Red Tail To Brocade
Red Tail To Ring
Red Tail To Salute

are all aerial shells with attached rising effects (red tails).

Attached Rising Effects

Attached rising effects are expressed in VDL in combination with an aerial shell as a "with XXX tail" clause after an aerial shell description, e.g.,

Red Peony w/ Tail
Red Peony w/ Silver Tail
Red Peony w/ Red To Blue Tail

The first example describes a gold trail of sparks, which is the default tail. The second describes a silver trail of sparks. The third describes a flame the starts out red and transitions to blue on the way up. You can also write these descriptions in the reverse order with the tail first,

Tail To Red Peony
Silver Tail To Red Peony
Red To Blue Tail To Red Peony

As discussed above, the reverse order can also describe an independent rising effect if the phrase to the right of "Tail" does not imply a shell or default petal shape. You can use the term "To Aerial" to remove any possible misinterpretation, as in "Tiger Tail To Aerial Red Peony".

Rising Flowers, And N-Times

Rising flowers are themselves shells, so their syntax is the same as the syntax for the shell they are attached to, inside a clause of the form "With XXX Rising Flowers":

Green Peony w/ Falling Leaves Rising Flowers
Yellow Peony w/ Red To Blue Rising Flowers
Gamboge Tip Peony w/ Four Times Blue Rising Flowers w/ Green

The third example indicates the number of rising flower breaks ("Four Times"). VDL supports up to ten rising flowers on an aerial shell, with the number spelled out as in this example. By default the number of rising flowers is 3 if not otherwise indicated.

The third example also illustrates a limitation on the syntax for rising flowers: They cannot themselves include "with" clauses. The green pistil in the end of the effect description applies to the aerial peony, not the blue rising flowers.

Differentiating Rising Effects From Aerial Effects

The difference between "Tail To Red Peony" (an aerial shell with an attached rising effect), and "Tail To Red" (an independent rising effect that transitions to red) is subtle. Effect names that begin with "XXX Tail To YYY" describe an independent rising effect unless YYY implies a default petal shape or payload of a shell. "Red Peony" implies a default petal shape, whereas "Red" by itself does not.

To remove any possible ambiguity for describing an aerial shell, you can use the term "To Aerial" for the transition, as in the aerial shell:

Gold Tail To Aerial Red

To remove any possible ambiguity for describing a rising effect, you can put the "Tail" term (or similar term "Comet" or "Pearl" or "Rising") last, as in the rising effect:

Gold To Red Tail

In cakes and candles, some effect names like "Crossette" and "Tourbillions" can represent individual rising stars and inserts, or aerial shells consisting of stars and inserts, depending on the context. VDL differentiates whether these terms refer to independent rising effects or aerial shells with the following rules: (1) if the terms are preceded by the term "rising", then they mean rising effects; (2) if the terms are preceded by the term "aerial", then they mean aerial shells; (3) otherwise they mean aerial shells unless they are part of a cake or candle, in which case they mean rising effects.

The third rule covers the most common cases so usually you don't have to worry about the terms "rising" or "aerial", but if you wanted to represent a cake that contains crossette shells (as opposed to individual crossette stars), you have a way to do it.

Crossette (aerial shell)
Crossette Cake (cake of rising stars)
Aerial Crossette Cake (cake of crossette shells)

Appendix G: Syntax of Bouquets, Bombettes, And Mines That Lift Shells

Some effects combine a mine with one or more shells that are lifted by the force of the mine. VDL provides two ways to describe the combined effects, either starting with the mine or starting with the shells. Examples:

Red Mine To Aerial Willow
Willow w/ Red Mine

The two examples describe the same thing, but with a different emphasis. The word "bouquet" can also be substituted for "mine". Combined mine/aerial effect descriptions that begin with the mine prior to "To", as in the first example, must include to the right of "To" a term that implies a default petal shape or salute, or in the absence of that must include the word "Aerial" immediately following "To" to disambiguate the description of the aerial effect from the description of the mine's stars. The following three examples combine mines and aerial shells:

Red Mine To Willow
Mine To Salute
Blue Mine To Aerial Red

whereas these three examples are mines with color changing stars or report:

Red Mine To Gold
Mine To Report
Blue Mine To Red

To represent a mine with stars that transition from red to Willow-like stars (no aerial shells involved), you can write,

Red To Willow Mine

which is the same as the combined mine/aerial description above except that the word "Mine" is moved to the end. The syntax "XXX To YYY Mine" is preferable to "XXX Mine To YYY" if you are describing a mine with transitioning stars because it cannot be confused with a mine/aerial description.

When effect names combine mines and shells, any "with" clauses in the name refer to the part of the effect to their immediate left. The following more complex examples illustrate these concepts:

Red To Yellow Peony w/ Gold Tail w/ Blue To Green Bouquet
Blue To Green Bouquet To Aerial Red To Yellow Peony w/ Gold Tail

Appendix H: Salutes and Report

The term "Salute" in VDL refers to an explosive charge in an aerial shell, whereas the term "Report" refers to an explosive charge culminating the life of a star or insert. Thus "Brocade Tail To Report" is a single rising star, whereas "Brocade Tail To Salute" is an aerial salute shell with an attached rising effect.

The subtle difference in words is very large difference in meaning, so care must be taken with VDL descriptions including these terms. See the earlier section on rising effects for more examples.

Addendum I: Adjusting Rendering Parameters

When Finale 3D renders a VDL effect, it first translates the VDL into a parse tree, and then translates the parse tree into a set of lower level rendering parameters and instructions. If you are designing an effect in VDL and you can't get exactly the look you want with the adjectives in the VDL language, you can set the lower level rendering parameters directly by adding them as annotations to the VDL to be injected into the renderer. Here is an example that shows the phases of translation for "Red To Blue Peony".


Red To Blue Peony

Parse tree (simplified):

[[particle [break 95 [particle red [break 1 [particle blue]]]]]]

Rendering parameters and instructions:

(define-particle :t0 0.0 :dt 2.51 :pos (0.0 0.0 0.0) :vel (0.0 133.6719 0.0) :windFriction 0.011 :randomSeed 1 :particleDef ((break :breakNumParticles 95 :breakVelGaussian (200.0 0.0) :breakWindFrictionGaussian (0.012 0.0) :breakLifetimeGaussian (0.3875 0.0) :particleDef ((break :breakNumParticles 1 :breakVelGaussian (0.0 0.0) :breakWindFrictionGaussian (0.012 0.0) :breakLifetimeGaussian (0.3875 0.0) :particleDef ((spark :sparkColor (0.5 0.5 1.0) :sparkRadiusGaussian (0.00470.0) :sparkIntensity 100.0 :sparkAnimation constant))) (spark :sparkColor (1.0 0.5 0.5) :sparkRadiusGaussian (0.0047 0.0) :sparkIntensity 100.0 :sparkAnimation constant)))))

Syntax Of Injected Parameter

If you notice in the rendering parameters above, near the end, there are two instances of ":sparkIntensity 100.0". These control the intensity of the star in its red phase and blue phase. If you want to change the second occurrence to 50.0 instead of 100.0, you can add the annotation to VDL:

red to blue peony {2 :sparkIntensity 50.0}

Which means simply, the value of the 2nd ":sparkIntensity" parameter in the define-particle representation is changed to 0.5.

If you want multiple edits, just concatenate them,

red to blue peony {1 :sparkIntensity 50.0} {2 :sparkIntensity 25.0}

Unless the effect name has multiple clauses separated by the plus sign (+) or the preposition "with", the location of the annotation makes no difference, so you could also equally well say,

{1 :sparkIntensity 50.0} red {2 :sparkIntensity 25.0} peony

For gaussians, you can optionally include two numbers as the data payload of the curly braces (the first number being the mean and the second number being the standard deviation), e.g.,

red to blue peony {1 :breakVelGaussian 100.0 10.0}

Or just the first,

red to blue peony {1 :breakVelGaussian 100.0}

Colors require three numbers in the data payload of the curly braces to represent RGB channels in the range 0.0 to 1.0:

red to blue peony {1 :sparkColor 1.0 5.0 1.0}

Example Injected Parameter

Here is an example of a before and after, showing the original VDL and its rendering parameters, followed by the annotated VDL and its resulting rendering parameters.

Original VDL:

Red To Blue Peony

Original rendering parameters and instructions:

(define-particle :t0 0.0 :dt 2.51 :pos (0.0 0.0 0.0) :vel (0.0 133.6719 0.0) :windFriction 0.011 :randomSeed 1 :particleDef ((break :breakNumParticles 95 :breakVelGaussian (200.0 0.0) :breakWindFrictionGaussian (0.012 0.0) :breakLifetimeGaussian (0.3875 0.0) :particleDef ((break :breakNumParticles 1 :breakVelGaussian (0.0 0.0) :breakWindFrictionGaussian (0.012 0.0) :breakLifetimeGaussian (0.3875 0.0) :particleDef ((spark :sparkColor (0.5 0.5 1.0) :sparkRadiusGaussian (0.00470.0) :sparkIntensity 100.0 :sparkAnimation constant))) (spark :sparkColor (1.0 0.5 0.5) :sparkRadiusGaussian (0.0047 0.0) :sparkIntensity 100.0 :sparkAnimation constant)))))

Annotated VDL:

red to blue peony {1 :sparkIntensity 50.0} {2 :sparkIntensity 25.0} {1 :breakVelGaussian 100.0 10.0}

Resulting rendering parameters and instructions:

(define-particle :t0 0.0 :dt 2.51 :pos (0.0 0.0 0.0) :vel (0.0 133.6719 0.0) :windFriction 0.011 :randomSeed 1 :particleDef ((break :breakNumParticles 95 :breakVelGaussian (100.0 10.0) :breakWindFrictionGaussian (0.012 0.0) :breakLifetimeGaussian (0.3875 0.0) :particleDef ((break :breakNumParticles 1 :breakVelGaussian (0.0 0.0) :breakWindFrictionGaussian (0.012 0.0) :breakLifetimeGaussian (0.3875 0.0) :particleDef ((spark :sparkColor (0.5 0.5 1.0) :sparkRadiusGaussian (0.0047 0.0) :sparkIntensity 50.0 :sparkAnimation constant))) (spark :sparkColor (1.0 0.5 0.5) :sparkRadiusGaussian (0.0047 0.0) :sparkIntensity 25.0 :sparkAnimation constant)))))

List Of Rendering Parameters

The full list of rendering parameters is shown in this table.




Applies to break parameters


Meters/sec and standard deviation


Velocity reduction per 100Hz simulation step


Duration of child particles in seconds


Flame envelope of star or spark in trail, 0.0 to 1.0 RGB channels


Physical size of particle in meters


Brightness, 100.0 = the brightness of a sparkler (as a reference)


Constant, fadeOut, or popper (for crackle)


Applies to trail or fountain emission parameters, emissions/sec


Relu, hill, or constant


Meters/sec and standard deviation


Velocity reduction per 100Hz simulation step


Duration of child particles in seconds


Fraction of parent's velocity added to child's initial velocity (1.0 = all of it)


Emission origin range from parent position, to give fountain nozzles a radius (0.0 default)


Width of fountain cone, 0.25 * coneAngleFullSpread for fountains or 720.0 for approximately spherical distribution


0.0 = no smoke; 1.0 = maximum density.


Initial diameter of smoke puffs.


Diameter of smoke puffs at expiration.

Categories: Category_Creating_Effects