Suites of Extractables (All GMs)

# Suites of Extractables

- Basic suites
- Advanced suite usage
- What suites don't do for you

## Basic suites

Suites offer extra (and optional) power for using extractables in charsheets; you should be familiar with \extract, \mention, \secret and their use before reading this.

Many games have occasion to bundle up a bunch of extractables and give them to a number of characters all at once; sometimes they're all the same type, sometimes they're different types. For instance, you might want a bunch of techie characters to each get the Techie greensheet, a hammer, a wrench, a memory packet for the hidden alien spaceship, and the Overtime Pay and Coffee Energy abilities. You could give each of these by hand to each techie, and then edit all their sheets if the list of "stuff to give techies" changes; or you can use suites to abstract that.

The fundamental macro for suites is \augment:
`\augment{Field Name}{code}`
in a character sheet says "store this code and execute it during \begin{extractable}{Field Name} ... \end{extractable}". You can control where inside the list it appears by calling \suitestuff there; this causes all the \augment'ed stuff for this field to appear. If \suitestuff is called again in the same field, it doesn't do anything at all---the list of the field's augments has been wiped. \suitestuff is automatically called at \end{extractable}, so you don't normally bother to call it yourself.

The obvious restrictions apply: you can't \augment a field that's already been done (including one you're in) or a field that doesn't exist, and \suitestuff is only legal in an extractable list. If you \augment a field and then never list that field, the charsheet will have a fatal error at \end{document}.

Of course, the point of \augment is to be used in other macros. You make a suite macro by calling a \augment a bunch of times:

    \newdef\Stechie{
        \augment{Greensheets}{\extract{\Gtechie}}
        \augment{Items}{\extract{\Ihammer}}
        \augment{Items}{\extract{\Iwrench}}
        \augment{Memory Packets}{\extract{%
             \memfold{Location NHT}{Wow, that's... that's... really weird.
    	    Who the hell would build a thing like that?  You'd have to
    	    be some kind of lunatic to come up with that design, and
    	    it wouldn't make sense unless the passengers had three legs.}}}
        \augment{Abilities}{
           \extract{\Aovertime}
           \extract{\Acoffeebuzz}
        }
    }

Now you can call \Stechie in each techie charsheet before any of their extractable lists. As each of the augmented fields comes up, the material added by \Stechie will be put in as if it had been typed directly into the charfile.

Some things the example demonstrates:

- \augment does not replace \extract etc; you still call one of those, since you could use \secret or \mention instead, even though we didn't.
- Multiple \augment's on the same field just stack; we used that to add two Items.
- Whatever you put in \augment's second ("code") arg is what gets done when \suitestuff happens; it doesn't have to be a single entry. We used that to add two Abilities with a single \augment.

The implementation of suites is in charextracts.sty, which is fairly magical (not recommended for the Czar to screw with it).

You can define suite macros wherever and however you want; the \S prefix is a suggested convention to avoid name collisions. For parallelism with other macro sets, the Template comes with a LaTeX/Lists/suites.tex which is read in by character.sty; it is initially empty (well, comments pointing here).

Now you have all the information about what the Template provides; everything else here (suggested ways to leverage suites, limitations of suites) follows from that.

## Advanced suite usage

(The further you go into this section, the more we get into you using TeX code.)

What if all techies are not created equal? Say they each get one hammer, but might have multiple wrenches, or none at all. We can define \Stechie to take an argument the same way we would with any other \newdef:

    \newdef\Stechie[1]{
      ...
      \augment{Items}{\extract[#1]{\Iwrench}}
      ...
    }

\Stechie{1} gives the techie one wrench; \Stechie{13} gives him a lot. \Stechie{0} gives him none, and since this won't even be listed in his sheet, this is a good way to put "might or might not have one at all" entries in a suite. (As per the glossary, zero-multiplicity \mention, \extract, \secret do nothing whatsoever.)

How about having more kinds of techies? They all do the basic stuff (we'll use the always-one-wrench version), but there can be another layer. Since a suite macro can have anything in it, not just \augment calls, this is easy:

    \newdef\Stechiecar{
      \Stechie
      \augment{Items}{\extract{\Icarbattery}}
      \augment{Greensheets}{\extract{\Gcars}}
      \augment{Abilities}{\extract{\Acartech}}
    }

That is, \Stechiecar gets all the \Stechie stuff, plus some more. Our \Stechiecivil could get \Stechie and a different set of civil-engineering extras.

Everyone with \Stechie knows they're a techie---they've got the greensheet and the abilities, it's obvious. But GMs have this habit of making characters who don't know themselves; maybe they got hit on the head and have amnesia, or maybe they've been a latent techie since birth but their inherent skill has never been awakened. (Ok, that's less likely with techies than with psis, but whatever.) These are a lot of why \secret exists along with \extract. For suites, it means we want to be able to make some of \Stechie's components be \extract usually but \secret for these guys, and there might be some normally-\mention'd components that want to drop out.

To have something drop out, we can use the zero-or-one trick above. To switch between \extract and \secret, we can use a nifty feature of their multiplicity arguments: a negative \extract is a \secret, and vice versa. That is, \extract[-1]{whatever} will do the same as \secret[1]{whatever}, and \secret[-2]{whatever} will do the same as \extract[2]{whatever}, etc (try it!). This feature is there specifically to let you do this kind of trick with suites. See the glossary entries.

So for each \Stechie thing, we decide whether the latent techies still get it overtly ("you're very energized by coffee, but you don't know why"), covertly (self-knowledge is required for overtime pay, much less the greensheet), or not at all (no tools).

    \newdef\Stechie[2]{
      \augment{Greensheets}{\extract[#11]{\Gtechie}}
      \augment{Items}{%
          \extract[#2]{\Ihammer}
          \extract[#2]{\Iwrench}
      }
      \augment{Memory Packets}{\extract{\memfold...}}
      \augment{Abilities}{
        \extract[#11]{\Aovertime}
        \extract{\Acoffeebuzz}
      }
    }

Now it takes two arguments. Everyone who gets it at all, latent or not, gets a coffee buzz and is weirded out by the alien ship. The second argument is presumably a 1 for normals, getting them one hammer and one wrench, and a zero for latents, getting them neither; but what the hell is that #11 doing there? You can't reference argument eleven! In fact, you can't even have argument eleven; TeX macros can only take nine. Which means that "#11" is "argument 1 followed by the digit 1." So if we leave it blank, \Stechie{}{0 or 1}, they get \extract[1]{\Gtechie}; if we put a minus sign there, \Stechie{-}{0 or 1}, they get \extract[-1]{\Gtechie}, which does the same as \secret[1]{\Gtechie}. Oddly enough, that's exactly what we want; normal guys get \Stechie{}{1} (or \Stechie{+}{1} to be more explicit), latents get \Stechie{-}{0}.

(Czar) If you're concerned about GMs putting in wrong pairs of args (\Stechie{+}{0}, \Stechie{-}{1}) you could put a wrapper around it:

    \newdef\Stechieduh[1]{
      \ifnum#1>0\relax
        \Stechie{+}{1}
      \else
        \Stechie{-}{0}
      \fi
    }

That uses some TeX you may not have seen before, but \newdef is the only Template thing there (and you could \newcommand instead). Pass \Stechieduh a number greater than zero (\ifnum#1>0) and it does \Stechie{+}{1}; pass it zero or less (\else) and it gets does \Stechie{-}{0}. (The \fi ends the \if; the \relax makes sure TeX knows the boundary of the number 0.) Obviously you don't have to go this far, even if you do the rest. You can get arbitrarily flexible/general/complex suite macros with such techniques.

## What suites don't do for you

Like the advanced usages, this all follows from the basic usage material and is just highlighting issues that teams may care about and that future versions may try to address. Note that none of them are made harder for you by the presence of suite features in the Template; it's just that some things that were hard before are still hard.

- \augment and \suitestuff affect extractable lists. Extractable lists only appear in character sheets. So suites don't help to do something like a Central/misc-foo.tex file with suite-like bundles of abilities/items/whatever.
- If you use suites so much that some chars have more than one, you may find yourself wanting suites Foo and Bar to be mostly independent, to both give ability \Aaaargh, but for the characters who have both Foo and Bar to only get one \Aaaargh. Suites don't offer anything to help deal with this. (Which doesn't mean it's impossible---you just have to throw around some extra TeX.)
- Suites are not particularly good for things like Devices, where you'd want to put \Dfoo and \Dbar in a charsheet somewhere and have it list "Device Foo" and "Device Bar," possibly in a separate Devices list but preferably under Items. You'd then want packet production to automatically create item cards to tape on the manila envelopes for Foo and Bar, and to also create all the contents of those envelopes, including the appropriate RTIs for each and some kind of instructions sheet (maybe a greensheet) for each. But you don't want any of that to show up on the charsheet lists (which you could manage with \secret), and you don't want the char name to appear on the instructions sheet (which you could manage like whitesheets do), and you want something to appear on the RTI and instruction-sheet printouts to clearly indicate whether they go in Foo or in Bar, and you damn well want to be able to have Central/misc-devices.tex DTRT. Well, doing that all automatically was a way serious bitch before the Template, and it's still a serious bitch with the Template, and it's still pretty bitchy even with suites around. Maybe next version.