Software Documentation

Software Documentation

Visual Descriptive Language (VDL)Documentation

Last updated: September 12, 2023

12 The difference between AND, PLUS, and AMPERSAND

Effect descriptions in English and other languages often employ the terms And, + and & to mean the same thing, as in “Red And Blue Peony” and “Red & Blue Peony” and “Red + Blue Peony”. Making matters more complicated, in some languages With means the the same thing as And, as in “Red Peony And Tail” in comparison to “Red Peony With Tail”. In VDL, however, these terms have different meanings, making it possible to interpret complex effect descriptions that use multiple colors and multiple effects unambiguously.

 

Table 1 – Conjunctions that sound alike, but are different in VDL

Term Meaning Example
And Not a VDL term
+ Combines shots of a cake, candle or chain Red Comet + Gold Comet Cake
& Combines colors that are part of the same multi-color effect Red & Blue Peony
With Combines an effect with a mine, petal, tail, or other stars mixed in Gold Comet With Red Mine

 

The first question people ask is: Why is And not a VDL term? The second question they ask is: If effect descriptions in my inventory use the term And anyway, what happens? Ironically, the reason And is not in VDL is precisely to make sure the right thing happens if you use the term in your inventory.

VDL is designed to encompass existing effect inventories, to make their meanings explicit, and to enable people to adjust their descriptions when necessary to get the exact meaning they want. The problem with And is that it is used pervasively in existing effect inventories, with different meanings. Thus, if VDL chose any specific meaning for And, that meaning would be the wrong interpretation for a lot of effects in people’s inventories.

By leaving And out of VDL, the designers of VDL sought to give more latitude to software programs that interpret effect descriptions to create simulations automatically. If And had a defined meaning in VDL, then software programs would be forced to create simulations according to that specific meaning (even if it is obviously wrong). If And is not part of VDL, then software programs are free to determine the best interpretation for it based on the other terms in the effect description. Software programs can usually guess right, which is a better outcome than necessarily being wrong for one set of effects or another.

So, if your effect descriptions use the word And, that’s probably just fine. Software programs will interpret And as + or & or With, as smartly as possible. If you don’t like the result, then change the word And to one of the other three, which all have defined meanings.

The two symbols + and & are easy to differentiate.  The + symbol combines effect descriptions for shots of a cake, candle, or chain in circumstances in which the item’s shots are not all the same.  Here are some examples,

20 Shot Red Peony + Blue Peony Cake
Red + White + Blue Chain Of 6
8 Shot Red Comet + Blue Comet Roman Candle

All three of these examples have multiple shots that are not all the same.  The cake in the first example has two kinds of shots: Red Peony, and Blue Peony.  This cake description doesn’t specify how many of the 20 shots are red peonies versus how many are blue, nor does it specify the firing order, but it does make clear: The cake shots are one color or the other.  (See articles on cake effect descriptions for instructions to specify the firing order, timing, etc., in effect descriptions).

The ampersand symbol & in VDL combines the colors of a multi-color effect.  Compare the chain example above with this chain:

Red & White & Blue Chain Of 6

Can you see the difference?  In this effect description that uses ampersands, the chain has six identical shells, each one of them a multi-color shell with stars of three colors.

The term With in VDL combines an effect with an additional mine, petal, tail, or other stars mixed in, as in these examples:

Gold Comet With Blue Mine
Gold Palm With Red Ring
Gold Kamuro With Tail
Gold Chrysanthemum With Blue

If the With-phrase includes the term Mine or Bouquet, then it adds a mine to the original effect, usually representing a shot consisting of lose mine stars underneath one or more shells or bombettes that are lifted together. If the With-phrase includes a term that defines a flower or shape (e.g., Palm, Ring, etc.), then the phrase adds a petal to the original effect. If the With-phrase just describes characteristics of a star, then it indicates the original effect includes stars of that description, mixed in with the other stars.