My text editor of choice, TextMate, supports large numbers of language grammars to provide syntax coloring. It also allows you to add your own. I threw together this one to get a bit of coloring into .ldr files:

{
   scopeName = 'source.ldr';
   firstLineMatch = '^0 FILE .+\.ldr$';
   fileTypes = ( 'ldr' );
   patterns = (
      {
	name = 'comment.line.ldraw';
        match = '^0 [^!].*$\n?';
      },
      {
	name = 'constant.other.ldraw';
        match = '^0 !.*$\n?';
      },
   );
}

To install this, pick Bundles→Bundle Editor→Edit Languages… from the menu bar. Click the + at the bottom of the window that comes up to create a new item. Then cut and paste the grammar. This should make your LDraw files go from what is shown on the left, to what is on the right:

Upgrading these applications, however, is not just a matter of recompiling them as Intel apps, because DropNuke and DropUnlock were not created in a traditional way. Creation of these applications took less than an hour, most of which was spent designing the icons. The actual “coding” took less time than it took to write this post. This rapid development time isn’t because I’m a fast coder; it’s because the apps are the output of Wilfredo Sánchez’s utility DropScript. What this application did is take Unix shell scripts (as well as Perl, Python, etc.) and wrap a Mac application around them that, when a file was dropped on the application, would execute the script passing the file as a parameter. Here is the complete code for DropNuke (which has been downloadable from the link at the top of this post since the apps were created):

#!/bin/sh
# EXTENSIONS : "*"
# OSTYPES    : "****"

for file; do
  location=$(dirname "$file")
  cd "${location}"
  chflags -R nouchg "${file}"
  rm -Rf "${file}"
done

The DropUnlock code is even simpler, eliminating the last rm call. Looking at the script now, I’m not even sure the first two lines in the loop even need to be there. In any case, you can see there isn’t much to these scripts. The real work is done by DropScript.

Alas, DropScript is a PowerPC application that produces PowerPC applications. Someone hell-bent on building Lion-compatible versions of DropNuke and DropUnlock would need to do the following:

1. Download the source of the scripts.
2. Do one of the following:
   1. Wait for Wilfredo Sánchez to update DropScript to support Intel applications.
   2. Download the source code to DropScript and get it working on Intel machines yourself. This might be a simple matter of just getting it to compile and rebuilding it, but I suspect not. It is likely that creating Intel apps from code is quite different than creating PowerPC apps was, back in the day.
3. Run the resulting Intel-enabled version of DropScript and use it to build DropNuke and DropUnlock.
4. Optionally, extract the icons from the original apps and apply them to the newly created versions.

Since I consider DropNuke too dangerous to release in the wild again (no more email about stray alias resolution accidentally deleting several terabytes of server data, thank you), and DropUnlock no longer really serves a purpose, I won’t be doing any of the above. All this code is available to you though. If you get it working, please drop me a line.

You can grab the file here (might need to right click on the link and “Save URL as…”): Fate d12 definition for Dicenomicon.

How to use this file is not explained that well in the app and not that obvious. And way harder than it should be. I’d love to say “go to the obvious screen in Dicenomicon and type in this URL to download it”, but I can’t, because that inexplicably isn’t an option. There are supposed to be several ways to get the file there, but most of them don’t work (the “import from documents” route fails with a “stream had too few bytes” error).

1. Download the definition file.
2. On your iOS device, launch Dicenomoicon and hit the info button in the top right.
3. Tap “Sharing”.
4. Tap “Web-based Editor”.
5. You are about to turn your device into a web server, briefly. Make up a username and password and tap “Start Server”.
6. At the bottom of the screen, your device will display a URL to use. Open a browser on your computer (assuming it is on the same network as the iOS device) and go to that URL. When asked for a username and password, enter the one you just made up.
7. In the page that comes up, click “Upload File”.
8. Choose the dice definition you downloaded. Select “Numeric Die” in the “Kind of Upload” popup. Click “Submit”.
9. Back in Dicenomicon, stop the server and go back to the main settings screen.
10. Tap “Customize”.
11. Tap “Custom Dice”. You should see the new “Fa12: Fate d12″ in the list.
12. So back to the customize screen. Tap “Dice Bar”.
13. Tap “Edit”.
14. Scroll to the bottom on the list and tap “Add Die…”.
15. A “d6″ will be added to the end of the list. In spite of being in Edit mode, you can’t edit this new die and this point. Tap “Done” instead, even though you are not.
16. Now tap the new “d6″ at the end of the list.
17. In the screen that comes up, you will see a “d6″ in a circle. Double-tap it.
18. In the dialog that comes up, choose “Custom Numeric Die”.
19. In the selector that comes up, choose “Fa12: Fate d12″.
20. Click Done. Go all the way back to the main screen.
21. At the end of your dice bar, you should see “Fa12″, which you can now use like any other die.

The implementation uses Bricksmith’s “quantized” movement, where bricks move in discrete increments based on a (frequently changing) user setting. While this is a bit unusual for 3d mouse control, it fits better with the way Bricksmith works, and how users typically will want bricks to move. A more typical 3d “full-motion” mode can also be used by holding down the control key while moving the 3d mouse. (This is slightly similar to applications that use “snap to grid” features, but allow the grid to be ignored by holding down the control key.)

I had intended to include a video in this post demonstrating how the mouse worked with Bricksmith; however, since 2.5 was released in April and I haven’t made such a video yet, it’s a good bet that I won’t in the next six months either. So, you’ll just have to trust me that it is totally awesome.

If you are one of the few that both uses a 3dConnexion mouse and Bricksmith, I’d love to hear how it works for you. Heck, I’d love to hear that you even exist.

One of these, DropUnlock, is still available, but today DivNull is officially discontinuing DropNuke. As you would expect with something named “DropNuke”, this version of the utility was pretty much the final option, a scorched earth way of permanently dealing with an undeletable file (using not only chflags calls, but also rm -rf). As you can tell by the warnings on its old download page, you could wreak a lot of havoc with DropNuke if you didn’t know what you are doing.

Since the “undeletable file” problem has been addressed in subsequent versions of OS X, and DropUnlock still exists for people still using the old version, it seems smarter to remove DropNuke, just in case.

I’ll try to keep this updated each year.

Note that the iCalendar format is compatible with most calendaring systems, including iCal, Google Calendar, Lotus Notes, Outlook, and so on.

Please leave a comment if you want to see something added to it.

• Default fonts are too small.
• Using the “larger font” menu choices improves some small fonts, but not others. Two of the main components of this screen are Flash files, so do not respond to this switch.
• Advertisements take up a good portion of the prime real estate of the screen.
• The screen doesn’t scale when you make your window wider, instead using a fixed-width, centered layout.
• Large sections of the screen are essentially useless for tracking the game (such as the header), meaning you need to scroll carefully to optimize viewing of the interesting stuff.

On a 15″ MacBook Pro (1440×900), with a maximized screen (dock on the right), the result looks like this:

Fortunately, the HTML markup of this page is reasonably good for altering (mostly because all the divs have ids), so it is possible to override the CSS for the page to fix most of these problems. Some browsers allow you to override the style of a page out of the box, but the process for doing this is fairly obscure for Firefox. A much more user friendly method for overriding a sites CSS using Firefox is to use a plugin called Stylish. This adds an icon in the lower right of your browser window that allows you to muck with the styles of the page you are viewing.

When you use CSS to alter a page, you are somewhat restricted by how good or bad the HTML of the page you are trying to alter is. While you can get extremely cute with CSS selectors, sometimes there just isn’t anything you can do. Fortunately, most of the things you’d like to do to the Gamecenter site are possible. There are a lot of ways you could hack it, but what follows will alter the game tracking pages to look something like this:

To do this in Firefox, do the following:

1. Install Stylish.
2. Navigate to the NFL Gamecenter page of the game you want to see.
3. Click on the Stylish icon in the lower right of the browser window.
4. In the menu that pops up, select “Write new style → For this URL…”.
5. In the dialog that comes up:
   1. Name the style something like “NFL Gamecenter”.
   2. Add some tags, such as “NFL”.
   3. Replace the script with the code below.
6. Click “Save”.

Now, any time you go to the Gamecenter part of the NFL site, you’ll see this hacked version. If you need to turn this off, you can click on the Stylish icon and select “Turn all styles off”. Also, unless you are using the exact screen size mentioned, you may need to tweak the CSS to match your screen. If you know CSS, there is nothing particularly surprising in the code of this alteration. Also, there is nothing in the code that is tied to Stylish itself; the same CSS should work for any other way of overriding the page style that you can come up with.

@namespace url(http://www.w3.org/1999/xhtml);

@-moz-document url-prefix('http://www.nfl.com/gamecenter/') {

/* Hide extra headers and stuff */
#hd-micro-nav-list, #hd-micro-nav-list, #tl, #header-content, div.tab-list-wrapper,
#gc-shop, #gc-discuss, #gc-track-search-ads, #gc-rr, div.w, div.t, #br, #gc-photos {
  display: none !important;
}

#hd {
  width: 1000px !important;
}

div.c {
  background: transparent !important;
}

/* Hide advertisements */
div#dc-header {
  display: none;
}

/* Left justify everything by default */
#com-nfl-doc, #hd {
  text-align: left !important;
}

#doc {
  margin: 0 0 !important;
}

#doc-wrap {
  padding-top: 0px !important;
}

#hd {
  height: 70px !important;
}

/* Scale the Flash file of the game scores, to make the font larger and
    reach across the screen. */
#hd-scorestrip-swf {
  height: 70px !important;
  width: 1380px !important;
}

#gc-team-stats {
  position: fixed !important;
  top: 70px !important;
  left: 990px !important;
  width: 380px !important;
  height: 280px !important;
  overflow: visible !important;
  z-index: 300 !important;
  padding: 5px !important;
  background-color: white !important;
  border: solid 1px #ddd !important;
  font-size: 14px;
}

#gc-last-score{
  position: fixed !important;
  top: 360px !important;
  left: 990px !important;
  width: 380px !important;
  height: 73px !important;
  overflow: visible !important;
  z-index: 300 !important;
  padding: 5px !important;
  background-color: white !important;
  border: solid 1px #ddd !important;
}

#gc-last-score h2 {
  width: 380px;
}

div.widget-inner {
  background-repeat: repeat-x !important;
}

#gc-current-drive {
  position: fixed !important;
  top: 450px !important;
  left: 6px !important;
  width: 760px !important;
  height: 335px !important;
  overflow: visible !important;
  z-index: 300 !important;
  padding: 5px !important;
  background-color: white !important;
  border: solid 1px #ddd !important;
  font-size: 16px !important;
}

#gc-current-drive-window {
  width: 750px !important;
  height: 320px !important;
}

#gc-current-drive-scroll-bar {
  height: 320px !important;
}

#gc-current-drive-scroll-track {
  height: 300px !important;
}

#gc-top-performers {
  position: fixed !important;
  top: 450px !important;
  left: 785px !important;
  width: 575px !important;
  height: 335px !important;
  overflow: visible !important;
  z-index: 300 !important;
  padding: 5px !important;
  background-color: white !important;
  border: solid 1px #ddd !important;
  font-size: 16px !important;
}

div.span-4 {
  width: 280px !important;
}

}

The makers of Stylish allow uploading of scripts like this; however, their “new account” feature is broken as of this writing. Once this is corrected, this page will be updated with a link to the “official” version of this script, which should make installation even easier. It has been posted here: Stylish script for NFL Gamecenter

Introduction

Since the late 1980′s, certain roleplaying games have made use of “dice pool success” mechanics. Such systems roll a handful of similar dice (usually d6 or d10), with the number of dice usually determined by the traits of the character for whom the roll is being made. That is, typically someone with more skill in something will roll more dice, also referred to as having a “larger pool”. Usually, each die rolled is compared individually to some sort of target, and if the die meets or exceeds that number, the die is considered a “success”. The quality of the roll is determined by how many successes are generated (i.e. how many dice meet or exceed the target).

One appeal of this type of mechanic is that it allows many variables to affect the roll, using a number of different mechanisms. A system might allow the situation to alter to number of dice, the target number, the number of successes needed to reach a goal and so on. As a result, many variations on this the basic idea can be found in different games.

One type of variation is known as a “roll and keep” system. The idea here is that you roll your pool, but only get to keep some subset of the dice. For example, you might roll seven dice but only be able to keep three, selected after the roll is made. Obviously, players will typically pick the best three results.

While not many games use roll and keep systems, the appeal of them is twofold. First, it adds yet another variable into how the roll can be manipulated (i.e. changes to how many dice you keep). Second, and more importantly, it allows a game designer to exert some control over the maximum number of successes generated by a roll. That is, some pool-based systems can get intro trouble with “runaway successes”, where various imbalances between characters can get magnified, with some characters scoring ungodly numbers of successes. Using a roll and keep system allows a designer to focus on a “sweet spot” for the number of generate successes. This post aims to investigate what various rules variations do to a roll and keep system.

One caveat: this analysis starts with a very “crunchy” (rules-heavy) system, and mutates it into an even more crunchy system in some ways. The point is really to see what happens within the roll and keep system, rather than try to convince you that the result is somehow “good”. The system does what it does; it’s up to you to decide if that is useful to you.

Start with an existing system

To keep things slightly more focused, the starting point for this investigation will be a popular pool-based system from a game called Exalted. As written, this game does not use a roll and keep system, but it has a number of features that might be usefully implemented by changing it to a roll and keep system. Some of what follows might make a bit more sense if you know a bit about the world of Exalted, but you don’t really need to know the game to follow along. Some important ideas of the system, as written:

• It uses pools of d10s.
• It uses a large number of “traits” rated (mostly) one through five. Some of these are called “Attributes”, some “Abilities”, but there are other kinds as well.
• Pool size for any given test is based on one Attribute, one Ability and, optionally, one “specialty” (rated zero through three).
• Dice that roll a seven or higher generate a “success”.
• Dice that roll a ten count as two successes.
• One important trait is called Essence and is a very rough measure of “power level” in the game. Mortals have an Essence of one. Very powerful gods have an Essence of ten.
• Player characters in the game are superhuman, typically with an Essence of two to five.
• Players have access to magic that allows them to (among other things) manipulate dice in various ways. For example, they might spend “points” of this magic (called motes) to buy extra dice for a roll, etc.
• Player characters can be different kinds of superhuman, each kind having their own “style” of magic. These different kinds are explicitly not equal in the game, with some being “more powerful” than others.
• Everything in the game that can use dice pools can gain a few additional dice for a roll just by giving a cool description of what they are doing. This is called “stunting”, and can provide from one to three dice.
• Everything in the game that can use dice pools also has a set a traits called Virtues. If they are really desperate, anyone can “channel” a Virtue to gain dice for a roll. This is costly, and can only be done a limited number of times.

Mutating into the roll and keep

Changing this system to a roll and keep system requires answering two questions. First, what determines the basic limit on how many dice are kept? Second, how is this limit manipulated? The way the world of Exalted works suggests some choices here. After some experimentation, the key really comes back to the notion of the different “kinds” of character mentioned above and how these are intentionally not equal. Also important is that most rolling will be using magic, so what happens to the rolls when they are augmented matters more often than how rolls without magic work. While there are number of possibilities here, the following accentuates the differences of the kinds of characters. What seems to work is:

• As with the standard system, characters roll Attribute + Ability + Specialty.
• Characters keep a number of dice equal to their Essence + 1. Note that this limit is intentionally on the low side, compared to the size of the pool. This has several ramifications but generally means that adjustments to the keep limit are more formidable than adjustments to pool size.
• Stunting works as in the standard system, adding dice to the roll.
• Virtue channeling adds to the number of dice you keep. (Also, for those who really know Exalted, in this system it does not cost Willpower.)
• The different kinds of characters each have their own basic mechanism for manipulating a roll. (In Exalted terms, the following replace excellencies.) The names for the different types don’t matter so much, but are arranged by “power level”, from strongest to weakest:
  • Solars (and their offshoots) can spend 2m to buy one success, with a maximum of Ability successes added to a given roll.
  • Lunars, prior to rolling, can spend 1m to convert a pool die into a single success instead of rolling it, with a maximum of Attribute die so altered for a given roll.
  • Sidereals can pay a flat 3m to add one to the number of dice they roll, but count two successes for rolling 8 or 9 as well as 10.
  • Alchemicals can pay a flat 1m to raise the number of dice they keep by two. This can only be done once per test.
  • Terrestrials can pay 1m to add two dice to their pool. They may add up to Ability + Specialty dice to a given test.
  • Spirits, Fair Folk, Ghosts and other essence users can pay 1m to add one die to their pool, adding a maximum of Ability dice to a given test

Example

For a particular test, a character uses an Attribute rated at 2, an Ability rated at 4 and a specialty rated at 1. This provides a dice pool of seven dice. The character has an essence of 3, which means, after the roll, she will keep four of those dice.

Her roll is an extremely good one: 2, 5, 8, 9, 9, 10, 10. She obviously elects to keep the best four dice, which are 9, 9, 10, 10. Each 9 gives one success. The 10s give two successes each. Her total is six success.

Later she needs to make a very similar test (based on the same traits). This time, though, she describes her action in a really neat way, and is awarded two stunt die. While this makes the pool larger, it doesn’t change how many dice she can keep. This roll happens to turn out worse: 1, 2, 4, 5, 5, 5, 6, 8, 10. She still keeps four (5, 6, 8, 10), gaining three successes (one for the 8, two for the 10).

Even later, she has to make the same kind of test again. This time she is in real trouble. She describes well again, gaining two stunt dice. She also channels one of her virtues (rated 3), which allows her to keep three additional dice. She rolls well again: 3, 5, 6, 7, 7, 7, 8, 9, 10. Thanks to the channel, she keeps seven dice (6, 7, 7, 7, 8, 9, 10) giving seven successes.

Running the numbers

The various choices were analyzed using software simulation, written in Python (source). The simulation makes a million rolls using 30 dice each. For each roll, the stream of dice is used by a bunch of different “strategies”. Each strategy represents a type of character, adjusting its traits and, importantly, kind. The strategies are set up such that they cover all relevant combinations. Each of these is fed the 30 dice results, but how many they actually use depends on the strategy. If a strategy is supposed to have a pool size of 12 dice, it only takes the first 12 dice for its pool and ignores the rest. By working in this way, all of the strategies use roughly the “same” results for their million rolls. This is not exact, of course, as some strategies use more dice than others, but it provides a more “fair” comparison of the strategies (and is much faster than rolling pools independently for each strategy a million times each).

What turns out to be interesting here are graphs where the traits are kept constant, but the various magical effects are used to the full extent allowed (that is, solars always buy Ability successes, etc.). You can see from these how the magic works at each sort of “skill level”. (It is also illustrative to show how the “canon” system works. That is, the system that doesn’t use a roll and keep mechanism, but rather always keeps all dice.)

Consider characters at Essence 3, but with minimal traits. At this level, the results are fairly homogeneous, and the magic doesn’t change much:

One thing to notice, though it doesn’t show on the graph very well, is that with their additional dice, terrestrials and spirits can occasionally get lucky enough to exceed the maximum achievable by a solar (about an 0.1% chance of getting six successes, while solars can only hit five), even though they do worse on average. This result will hold in any situation where the keep cap exceeds the standard pool size, which doesn’t happen that often. With traits this low, however, it still happens with virtue channeling/stunts:

One oddity you see emerge here is that the because of the way sidereal magic works, they are more likely to get even numbers of successes than odd.

When traits move to 3 dots each, you can see another emergent behavior: when the base pool and the cap become close, without magic the basic “roll and keep” behaves very similarly to canon, but magic causes the various types of exalts to have much different expectations of success:

Also note the “canon” line in the graphs above. Bear in mind this is just a standard roll in the original system, without any magical augmentation. Since each die can possibly generate two successes (by rolling a 10), Exalted has a bigger issue with “runaway successes” than most other pool based games do. The “roll and keep” tends to keep runaway successes under the original system more constrained, with magic use having a bigger impact than luck.

Things get more interesting when you ignore the virtue channeling and add only some additional dice, say from a stunt or specialty. Since these two cases are mostly the same (the only difference being that three dice from a specialty help terrestrials more than three dice from a stunt would), we’ll look at the specialty case:

Here, you can really see how the excellency differences play out:

• Solars are simply “more excellent” than the others, but since they are limited in how many successes they can buy, not overwhelmingly so. This is a departure from the canon rules, were the gap between solars and others can be severe.
• Lunars have the same minimum and maximum successes as solars, but average one fewer success. Still they outshine other types.
• Sidereals leave much more up to luck, but still regularly hit celestial levels of success. Their minimum is much lower than solar and lunars (they can still actually get zero successes), and their max is slightly lower, but they have a much flatter curve, that favors the high end.
• Terrestrials, unlike celestials, can’t gain more with magic than without, but are much more likely to hit the high end of their range.
• Alchemicals most closely match the canonical curve. They can do better than even solars, but not very often.
• Spirits are similar to, but outmatched by, terrestrials.

As the traits climb to five, all of these trends become more accentuated, and the higher powered exalts make better use of their increased skill:

When you add stunts and channeling to mix, however, the odds tend to even out a bit, particularly for those in the mid power range:

Higher Essence

As Essence increase to five (the realistic upper limit for PCs in most games), the keep limit becomes less relevant, particularly at average skill levels, because you are keeping nearly all of the dice you roll. You start to see a more canonical behavior of the magic:

Once traits are maximized, however, the disparity between pool size and limit cap returns, and the difference between the types of characters become more pronounced:

The low end

One thing that turns out to matter a lot in this analysis (and the reason Exalted is being used as a base) is the notion that rolling a 10 generates two successes. This mixes in interesting ways with the keep limit. Obviously, 10s are much more worth keeping but, more importantly, they allow the success count to exceed the keep limit. That is, even if you can only keep two dice, it’s possible to get four successes. Further, the more dice you roll, the more likely that outcome is.

For example, if you roll only two dice and keep both, the chance of getting four successes is only 1% (with a 34% chance of failure). If, however, you roll 12 dice and keep two, the chances of four successes is closer to 35% (with the chance of failure dropping to around 0.2%). So, the limit and the 10s rule combine to reign in the number of total possible successes, but yet still let skill matter.

This is easier to see when looking at the results for the low end of the power scale: Essence 1 characters. Since mortals can’t use magic (and everyone that can use magic has Essence 2 or more), graphs at this level are more simple. At this level, it is a bit more useful to look at how the roll and keep results change the dynamics of the game compared to the canonical system.

One twist here is that Exalted divides mortals into two groups: standard mortals and heroic mortals. The difference is that, for standard mortals, rolling a 10 only generates one success. This changes things a lot for them. (If you suspect that mortals are a bit screwed in the world of Exalted, you’d be totally right.)

Let’s look at a minimal mortal, with all traits at one. Since the keep limit equals the number of dice, this works just like canon, so is not particularly interesting, but consider when this character stunts:

Heroic mortals cannot do better than four successes here, even with the stunt, because stunting doesn’t change the cap. The standard mortal can only get two successes in this situation. Compared to not stunting, the difference for the standard mortal is a drastic increases the likelihood of getting two successes (from around 16% to 53%), and decrease the chance of failure (from 36% to 13%).

You can also see how, compared to canon, the 2+ success results are “compressed” into a lower range.

But what if, instead of stunting, they channel a virtue (rating 3)? Looks like this:

Under r&k, the mortals still can’t crack four and two successes, respectively. In this case, the culprit is the size of their dice pool. Their keep limit is over twice the size of how many dice they actually can roll. The canon case has much different behavior here, as it is rolling five dice instead of just two.

Channeling a virtue in this situation is much worse for the mortal than a stunt. This turns out to be more of a fringe case, but it has an interesting effect: mortals simply cannot do “legendary” things, unless they both stunt and channel. Or, put another way, it is possible for even the weakest mortals to do awesome things if they stunt like hell and pour their heart into it:

You can really see the divergence from canon here. Compare standard mortals in canon to heroes in r&k, for example. In this case, canon mortals gain 7 successes 3 times out of every two thousand rolls. Heroes in r&k don’t do this as often, though they can get 8 successes while standard canon mortals can’t (meanwhile, canonical heroes can get as many as 14). Note that standard r&k mortals still cannot achieve “legendary” successes, though they could with a higher virtue.

As mortal traits increase, the result of raising their attributes doesn’t affect their success caps, but moves their results more reliably to the higher end of that cap:

So, on the low end, this system seems to at least function, and does a fairly good job of “keeping the man down”. Can’t have mortals get too uppity. With enough stunting and heart, they can still do “legendary” things.

Conclusions

While initially intended to be a somewhat generic look at how you might manipulate a roll and keep system, the results actually turn out to depend heavily on the specifics of the original system used, particularly the rule that awards two successes on a 10.

On the other hand, if you consider the specific flavor of the game in question, you actually can use roll and keep to make the game work a bit more like it is described. That is, with some minor mechanical changes, the success rate of the various kinds of exalted can be tinkered with until they match the relative power levels implied by the game’s descriptions, all in a way that minimizes the huge success disparity of the original system.

This post acts as a how-to describing how you can build such cards yourself, should the muse strike you. More generally, it demonstrates how you can use two different but complementary XML-based technologies (XSLT and FOP) to format output for Avery business cards, mailing labels, etc. from an XML data source. An assumption is made that you know what XML is and have enough technical chops to install and setup the various technologies involved.

Formatting Objects Processor

The Formatting Objects Processor (FOP) is a free, cross-platform technology from Apache. It claims to be “driven by XSL formatting objects (XSL-FO)”. All this really means is that it makes use of a specific XML format called XSL-FO, which is built to represent printed page layout. FOP can read in this format and render it into a wide variety of output, including text, PostScript and the format we’ll be using here, PDF. The XSL-FO standard has enough in common with HTML that its basics are fairly simple to pickup if you know that language; however, it is more complicated and much more accurate, capable of millimeter-level control over the output.

In principle, all you need to to use FOP is a source file written in XSL-FO markup. Nearly every demo you’ll find on the web uses the same mechanism of generating this source that we will (XSLT, see below); however, FOP really doesn’t care where it comes from. Keep in mind that it’s just an XML file, so you could just as easily, say, build the XSL-FO with a Perl script or even by hand. Typically, you will also have some source of data in hand, such as a database or text file. In our case, we have some XML data in a totally different format.

The d20 Standard Reference Document in XML

The d20 game uses a (mostly) open standard, based around the d20 Standard Reference Document. Fortunately for us, an enterprising soul named Andargor has gone through the trouble of translating this SRD into XML and some other data-based formats. His XML files use a fairly straight-forward format of his invention. This format, of course, is pure data and nothing like the XSL-FO layout format. Nor should it be. So, what we need is something to translate the d20 XML into the XSL-FO markup describing the page layout we want.

Extensible Stylesheet Language Transformations

Many paths exist to convert the d20 XML into XSL-FO. Python scripts, Java, heck even sed. We’re using a technology meant to transform XML input into some other kind of output (usually XML, HTML or text) called the Extensible Stylesheet Language (XSL). XSL is yet another special XML format geared towards matching XML data and transforming it. (It is, believe it or not, turing complete.) It makes heavy use of a standard called XPath, which is a funky query language for specifying exact subsets of nodes within an XML document. Though XPath looks nothing like SQL, it is similar in purpose, except querying a hierarchy tree instead of relational tables.

An XSL transformation (XSLT) is specified in an .xsl file. Typically, such files are very specific, written exactly for the combination of data type being transformed and output format being written. That is, the XSL file we use here is specifically for turning the d20 SRD XML format into XSL-FO formatted for Avery business cards. If you need to change either end of this, you should make a copy of the file and mutate it into a new transformation that does what you need.

Tools

We need some kind of tool that allows a two-step workflow (or knows how to combine the two steps into one). First, we convert the d20 SRD XML data into XSL-FO using XSLT. (That’s a lot of acronyms.) Second, we take the result of that and feed it into FOP to build our PDF. The four files are involved are:

1. spells.xml – The d20 XML data containing all the spells in the SRD.
2. spellcards.xsl – The XSLT to do the translation into XSL-FO.
3. temp.fo – The XSL-FO generated by the transformation.
4. spellcards.pdf – The final PDF file.

A number of tools exist to do this. I happen to use oXygen, as it combines everything needed to run this process into a single step, and also functions as a very good XML and XSLT editor. It’s a powerful tool, but pricey. Stylus Studio costs even more. Some less feature-rich alternatives might be TestXSLT. If you want to go the Java route, your best bet is to download the recent FOP package, which contains the Xalan XSLT engine and a command line to use it. If you know of other tools, leave a comment with a URL.

Steps

Once you have the tools picked out, download the XML d20 SRD and find the spells.xml file. Now, take a look at the transformation file. It is fairly well commented. Save a copy of it to your local drive as your spellcards.xsl file. Now tell your tools to use spellcards.xsl to transform spells.xml into temp.fo, then channel it into FOP.

If using oXygen, do the following (note, there may be some changes between versions of oXygen, so this may not be exact):

1. Open the two files.
2. Make spellcards.xsl the active document and select the menu “Document → XML Document → Configure Transformation Scenario”.
3. In the dialog that comes up, click “New”.
4. Name the scenario “spellcards” or something similar
5. In the dialog’s “XSLT” tab, set the “XML URL” to your local copy of spells.xml. You should be able to leave the other settings alone on this tab.
6. In the dialog’s “FO Processor” tab, check “Perform FO Processing” and make sure the “XSLT result as input” is selected. You want to use the “pdf” method and the built-in FOP.
7. In the dialog’s “Output” tab, click the “Save As” radio button and provide a place to save the spellcards.pdf file. Click the “Open in browser” checkbox and the “Saved file” radio button.
8. Click OK to close the dialog.
9. Back in the “Configure Transformation Scenario” dialog, you can click “Transform Now” to test out your settings.
10. Hopefully, you should be looking at a PDF now. If you need to run the transformation again, you can hit the big red “play button” toolbar icon (which is called “Apply Transformation Scenario”).

If you are using the command line tool that comes with FOP instead of oXygen, the command you need should be something like this:

fop -xml spells.xml -xsl spellcards.xsl -pdf spellcards.pdf

Printing

Once you have the PDF created, make a test print of one of the pages. Put this page behind one of the Avery business card pages and hold it up to the light to see how it lines up. Every printer feeds slightly differently, so you may need to tweak the measurements slightly to align the cards just right. You do this by altering the spellcards.xsl file.

Search this file for the word “tweak”. You’ll find a couple, which identify spots in the file that measurements can be altered. One place is the margins for the whole page. The other is the padding within a table cell. Adjust these until your test page lines up with the Avery labels. Once this all works, print out a test page on the Avery label paper. Hopefully it will still match up. If not, tweak again. Once it works, print them all.

Note, the measurement tweaking locations (as well as some nearby tags) within spellcards.xsl can be altered more radically to support other types of Avery pages, such as index cards or mailing labels.

Filtering

You may not want to make cards of every single thing in the spells.xml file. You can use different XPath statements within the spellcards.xsl file to select subsets of the data. There are two logical places to do this in the file, both of which can be found by searching for “filter” in the text.

The primary location is the select of the main apply-templates tag. In the file, there are a half-dozen or so alternate examples for this statement that you can use. Just comment out the first one and uncomment the one you want. You should be able to find a statement close to what you want and alter it to taste.

For more exotic filtering, there is a very slim chance that you what you want can’t be done in the main select. You can, instead, examine each spell as it comes through and make more complicated tests. The transformation file contains a skeleton to do such filtering, but always lets everything through. You’d need to change this to set include to true.

Filtering this data is harder than it could be, because the level tag in the spells.xml file is a string that combines all of the level information into a single field, rather than more structured data. For example, if a line like:

<level>Cleric 6, Druid 6, Sorcerer/Wizard 6</level>

…was instead…

<level>
 <class>Cleric</class>
 <classlevel>6</classlevel>
</level>
<level>
 <class>Druid</class>
 <classlevel>6</classlevel>
</level>
<level>
 <class>Sorcerer/Wizard</class>
 <classlevel>6</classlevel>
</level>

…it would be a lot easier to do more powerful XSLT filtering and sorting.