Rotors: Automatically Vary Cards in a Series

What is a Rotor?

A series expands a single row of content into multiple rows, each with a different value in the series field. A Rotor does not expand a row into multiple rows. Instead, use a rotor in a row that also has a series, or that has a #repeat value greater than one. When the row is expanded into multiple rows by the series or the #repeat field, the rotor will vary the values in its own field on each expanded row.

Learn more about Series.
Learn more about the #repeat feature.

The rest of this page describes the Rotor feature in detail.

A Rotor is Multiple Values in One Field

Normally, a single field in your content specifies the value for one item on one card. But if the value is in Series or Rotor format, it is treated as a list of several values. Use a rotor when you have a row that generates multiple cards, and you want to vary the values of a field without generating even more cards (as would happen if you used a series instead).

Important: Normally, a rotor is only useful on a row that will be expanded into multiple rows. If a row does not have a #repeat column with a value greater than 1, or at least one series in another column, a simple rotor is useless. (However, there is an exception if you use a tagged rotor, as these can be continued on subsequent rows; see below.)

How to Write a Rotor

A rotor is always defined in a single field on a single row. Here are a few sample rotors:

The value of a field is recognized as a rotor only if the value begins with a circumflex character ^ and ends with a list of elements separated by pipe | characters.

Learn more about Series.

In between the circumflex and the first pipe character, a rotor may have optional modifiers. In the example rotors above, the "stagger" and "tag=bonus" parts of the second and third examples are modifiers and are not part of the list of elements. See below for more about modifiers. A simple rotor that has no modifiers will begin with ^| followed by its elements separated by more | characters, and ending with a final |. If the entire value is not recognized as a valid rotor specification, the value will not be interpreted as a rotor.

Within the value, pipe characters separate elements. (This is the same as for a series.) When the deck is printed, previewed, or exported, and the row is expanded into multiple rows because of a series or #repeat in another column, each of the expanded rows will have a different one of the elements from the rotor as the value of the rotor field.

If there are more expanded rows than there are rotor elements, the rotor will simply repeat its list of elements, as many times as needed.

Example: Multideck will treat the row

...as if it were five rows:

Farmer Wheat Rancher Grapes Merchant Beans Mayor Wheat Vintner Grapes

An element may be empty, in which case it is treated the same as a normal empty value. In this example, the third element is empty:

^|Wood|Grain||Stone|

Using Ranges

Rotors will accept the same range syntax as a series, to shorten the list of elements when they form a predictable progression.

For example, this rotor: ^|1~5| will expand to: ^|1|2|3|4|5|.

Learn more about Using Ranges in Series.

Embedding a Rotor in Another Field

A rotor won't be recognized by Multideck unless it's the entire value of its field. That means you can't include a rotor as just part of a field's value. For example, you can't have a field whose value is:

Gain one ^|Wheat|Brick|Stone|. <== This won't work!

But remember that it's possible to include the value of one field in the value of another, by using markup to refer to the other field. Here's a content excerpt that will work:

Goods	Effect	#repeat
^\|Wheat\|Brick\|Stone\|	Gain one {..Goods}.	5

In the above example, the value of the Effect field (which must be a rich text field) refers to the values of the Goods field by including a reference to it: that's the {..Goods} part. The value 5 in the #repeat field expands this row to five rows. In the Effect field, the markup {..Goods} is replaced by the value of the Goods field; since that is a rotor, each row will contain the next element from the rotor. So the whole thing expands to:

Goods	Effect
Wheat	Gain one Wheat.
Brick	Gain one Brick.
Stone	Gain one Stone.
Wheat	Gain one Wheat.
Brick	Gain one Brick.

Learn more about Embedded References to Other Fields in Rich Text Markup.

Modifiers

An unmodified rotor behaves as described above. You can get different behaviors by applying modifiers.

Modifiers are placed between the leading circumflex character ^ and the first pipe character | that introduces the list of elements. There can be more than one modifier; if there is more than one, the modifiers are separated by semicolons. Remember that modifiers are not elements: the list of elements begins after the first pipe character.

Currently there are two modifiers: stagger and tag. These are described below.

The "Stagger" Modifier

Normally, each time a rotor repeats, it starts over again with its first element, and substitutes the elements in the same order every time. For example, if the rotor ^|Able|Baker|Charlie| is used over nine cards, you will get:

Able, Baker, Charlie, Able, Baker, Charlie, Able, Baker, Charlie

But sometimes you don't want a straight rotation of the elements of a rotor.

A staggered rotor is a rotor that will change the order of its elements each time it repeats. It does this by effectively taking the first element of the list and moving it to the end of the list after each repetition.

To create a staggered rotor, add the modifier stagger, like this:

^stagger|Able|Baker|Charlie|

So in the above example, the staggered rotor would produce:

Able, Baker, Charlie, Baker, Charlie, Able, Charlie, Able, Baker

The "Tag" Modifier: Spanning Multiple Rows

An unmodified rotor only affects the cards that are created by expanding the row in which the rotor occurs. But sometimes, even with series to help, you may want to apply a rotor across multiple rows of your input source. This is called spanning.

Creating a Tagged Rotor

You can create a rotor that will span multiple rows by giving it a tag modifier. A tag is a name that you create, and that identifies that rotor. In other rows in your content, you can refer to that rotor by its tag, and continue that rotor's use on those other rows (that is, on any and all cards created by expanding those rows).

Careful: Do not confuse these rotor tags, which apply only to the rotor, with Item Tags.

In any one appearance of the rotor in your content, define it as described above, but give it a tag modifier with a name that you choose. The syntax of the modifier is:

tag=tagname

Tag names may contain alphanumeric characters, dash, and underscore. Spaces and other punctuation are not allowed.

Here's an example that creates a rotor with a tag of "occupation":

Using a Tagged Rotor: the span Directive

For those cards expanded from a row with a tagged rotor, the rotor behaves as usual. But now that we have a tagged rotor, we can refer to that same rotor in later rows, to continue its use in those rows without creating a new rotor.

To do this, we use a span reference that includes the name of a tagged rotor, like this:

^span=tagname

For the example rotor above that was tagged "occupation", you would use exactly this value in the rotor fields on later rows:

^span=occupation

Note that there is no list of elements here, and no other modifiers are allowed. This value specifies that we are going to continue using the tagged rotor defined earlier, so we don't need to say anything else (and we are not allowed to say anything else) about it.

Here's a more complete example:

Status	Weapon	Ransom
\|Duke\|Marquis\|Lord\|Earl\|Baron\|	^tag=weapon\|Longsword\|Bow\|Crossbow\|	£100
\|Peasant\|Ostler\|Shopkeeper\|	^span=weapon	(none)

The above would expand to eight cards, like this:

Status	Weapon	Ransom
Duke	Longsword	£100
Marquis	Bow	£100
Lord	Crossbow	£100
Earl	Longsword	£100
Baron	Bow	£100
Peasant	Crossbow	(none)
Ostler	Longsword	(none)
Shopkeeper	Bow	(none)

Note how the original "weapon" rotor continues its rotation of "Longsword,Bow,CrossBow" over all of the expanded cards.

Combining Modifiers

A rotor may have multiple modifiers. To do this, separate the modifiers with semicolon characters. Here's an example of a tagged, staggered rotor:

Escapes

In the rare case that you need to use literal circumflex, tilde, or pipe characters in your rotor elements, you can do so by preceding them with a backslash character. The value \^|1|3|5| will not be treated as a rotor series, because it does not start with a simple circumflex character; but the backslash will be removed and will not be part of the value.

Similarly, the value ^|1|3\~5|7| will produce the progression

1 3~5 7

because the \~ combination will be treated as a literal ~ character, and will not be interpreted as a range.

Quick Clicks

The Basics

Creating Card Layouts

Specifying Content

Content in CSV Files

Effects

Previewing and Finding Errors

Printing

Exporting for Documentation, Print-on-Demand, and Online Gaming

Text Layout

Item Tags and Hiding Card Items

Styles, Series, and Rotors

Appendices