Table of Contents:

• Example Cards
• Card DOM Structure
• Card JSON Structure
• Markup Text
• Creating Your Own Cards
• Printing Cards
  • SVG-format Conversions

This page describes, more or less, how to use the Dark Venture card tools. In short, these tools exist to allow creation of custom content for the Dark Venture line of tabletop games. As of this writing, it is limited to Heroic Quest and Side Quest cards.

This document assumes some knowledge of HTML, CSS, JSON, and a little bit of JavaScript. HTML and CSS are the core-most aspects of these tools, with JSON and JavaScript being used to simplify creation of HTML/CSS-based cards.

The source code for this page and its tools can be found at fossil.wanderinghorse.net/r/darkventure.

Example Cards

A picture is worth a thousand words, so...

It is important to keep the following in mind:

• These cards are not image files. They are rendered by your browser dynamically using HTML, CSS, and a few graphics made available by Dark Venture creator Rob Lemon. e.g. the card background and borders are bitmap graphics, but the various glyphs are vector graphics and the text is rendered exactly as all other web-page text is.
• Every browser has its own little rendering quirks and no browser is perfect in that regard. Even apparent sizes of the exact same font may differ slightly from browser to browser. Thus these cards may or may not appear 100% as intended in your browser.
• Development and testing are done using only Firefox and Chromium on Linux platforms, and every reasonable effort is made to get them looking more or less the same in both of those browsers, but getting a perfect match has proven to be an impossiblity (see the previous point).

Card DOM Structure

Both Heroic Quests and Side Quests have identical DOM structures. They differ mainly in their CSS classes and how CSS lays out those structures. This section describes that layout and the corresponding CSS classes.

• DIV.dv-card-wrapper-SIZE, where SIZE is one of "mini" (for small-format cards) or "standard" (for standard-sized cards). This element is not strictly part of the card, but is useful for layout purposes, in particular applying (or removing) a border to provide cutting lines.
  • DIV.dv-card.dv-card-size-SIZE.dv-card-TYPE, where SIZE is the same as described above and TYPE is either "sidequest" or "heroicquest". If this element has the class dv-official then the card is assumed to be a clone of an "official" card (one which comes with the physical version of the game) and its layout may be restricted a small bit to conform to the layout of the game's official cards.
    • SECTION.card-qp contains the Quest Point value for the card. It must be a very short string, no longer than 3 characters (e.g. 1-3).
    • SECTION.card-name contains the name of the card.
    • SECTION.card-id contains a very short identifier for the card. Official cards have no more than 2 numeric digits and on cards with the dv-official CSS class this element has a fixed size. On non-official cards it will expand to the left to fit the text, but should only contain a few characters, e.g. ex-01. The text will be automatically uppercased by CSS.
    • SECTION.card-body contains one sub-element...
      • DIV contains the full text of the card's body, possibly including DV markup.
        This extra DIV is unfortuantely required in order to get vertical centering of the body text to work (for style conformance with the official cards). If a workaround can be found for vertical centering which does not require this element, it will be removed from the DOM structure.

General notes:

• The order of the SECTION.card-XYZ elements in the DOM is not important, as their positions are set via CSS.
• Some of the CSS classes may seem redundant or superfluous, but experience with this code's predecessor has shown them to be useful internally in the programmatic generation and modification of cards.
• The intent is really that users define cards via a simple JSON structure which JavaScript converts to the appropriate DOM elements. Thus users, unless they want to, generally need not bother with the DOM at all.

Card JSON Structure

Quest cards can be (and are intended to be) implemented using a simple JSON-format data structure, which is much simpler for users to deal with than hand-writing their DOM-based counterparts. Each card, whether it's a Side Quest or Heroic Quest, can be represented as a JSON object with the following properties:

• id: a very brief number or letter/number combination which uniquely identifies the card. The official cards use 1- or 2-digit numbers. This value gets automatically uppercased when rendered on the cards, and the back-end may restrict its length (currently to 6 lower-case ASCII characters, digits, dashes, and/or underscores).
• isOfficial: an optional boolean which indicates (if true) that the card is a facsimile of an "official" card. This may modify the rendered layout of a card in order to easily distinguish between official and fan-created cards.
• name: a brief name for the card. Conventionally these normally end with a "!". This gets automatically uppercased when rendered and is considered case-insensitive for purposes of the back-end database.
• qp: the number of Quest Points or a range of numbers. Should not be longer than 3 characters, else the layout may break. e.g. "1-3" is fine. If the range is variable, use an asterisk and explain it in the card body.
• contributor: optional (and currently unused!) string describing the card's contributor, e.g. their name, their URL (e.g. home page or BoardGameGeek profile), or similar. This information is not shown on the card, and is reserved for potential future use if an editor application ever gets created for these cards. Cards for which isOfficial is true have an implicit contributor of Rob Lemon, the game's creator.
• body: holds the entire body text of the card, including markup. The body may be in any of the following forms:
  • A single string.
  • An array of strings. The array entries are simply concatenated together to form the body text. This form is often easier to work with than a plain string when hand-writing JSON text, especially longer card text.
  • An OBJECT in the form:
    • fontSize: an optional framework-defined integer value. 100 means a 10-point font size (of Futura Medium). Each increment of 1 point is equivalent to 0.1pt font size. Thus 110 means 11pt and 95 means 9.5pt. The legal range is 50 (5pt) to 250 (25pt), inclusive, noting that anything less than about 6pt is illegible (and 6pt is only really legible if it's uppercased). Official cards included with the game all have the same font size, but this toolkit allows the font size to to be varied in order to allow more freedom in the amount of text and to account for different browsers sizing text slightly differently.
    • text: body text in one of the string/array forms described above.
• meta: the "meta" property is an object which contains state which is relevant for the long-term storage, retrieval, and editing of cards. i.e. it's information for use by a back-end database and related software. This property is not relevant for those creating cards solely for use in a single page, e.g. a collection of custom quest cards. As of this writing, the following sub-properties are used by the back-end system:
  • uid: the card's unique identifier. Unlike the card's "id" field, which may change over time, this value is constant. Changing it effectively creates a different card. This value is constrained to a string starting with a lower-case ASCII alphanumeric character or underscore followed by up to 39 additional dashes, underscores, and/or lower-case ASCII alphanumeric characters. When a card is submitted for saving but lacks a UID, the back-end assigns a random one.
  • deck: the ID of the deck this card belongs to. A deck is a higher-level construct for grouping cards and specifies the size of the cards which it holds. Because Side Quests and Heroic Quests have identical structures, and can hypothetically be used in both contexts, the size of the quest card is not part of the card's state, but is instead part of the deck's state. Deck IDs follow the same syntax as card uid values. This ID must refer to a deck which exists in the database or saving will fail. It is illegal for two cards to share the same meta.deck and id values, as that ID is rendered on the cards and it "just wouldn't do" to have two cards in the same deck with the same unique (per deck) identifier. For the same reason, it is illegal for two different cards to have the same meta.deck and case-insensitive name values.
  • mtime: the timestamp of the last time the card was saved, an integer in Unix Epoch format (implied UTC time zone) with seconds precision. This is only set by the back-end, and is ignored (overwritten) by the backend when saving cards.
  • contributor is part of the top-level card object, not the meta property, because it is potentially relevant for cards even when they are not part of a database.

Future versions of these tools may add additional fields, e.g. metadata required by an editor application. No such hypothetical fields are expected to be visible to end users of the cards, so they will not affect the layout.

Examples, with their JSON on the right and rendered forms on the left:

Note that the boxed areas in the cards are baked in to the background graphics and will not resize to fit larger text. Side Quests, in particular, must be kept brief.

The Side Quest box layout is defined by the game's designer. These tools "could" (and initially did) draw the boxes dynamically, to allow them to fit their text and shift to allow more body text, but doing so would require using modified card backgrounds and would violate the uniformity of the graphic design.

Card Text Markup

In order to prevent that game card text can contain arbitrary HTML (which would pose a potential security risk for those who view the cards), these tools offer a custom markup format, processed by JavaScript, which provides "most of what one needs" to decorate card text with things like *italics*, **bold**, {{u}}underlining{{/u}}, and various game-specific glyphs (namely attribute and faction icons like {::MIND::} and {::F_CONSTRUCT::}).

This markup was originally implemented for a similar set of tools for use with the Dungeon Degerates board game, and thus its syntax has some oddities which make more sense in that context.

General notes and limitations include:

• Only card body text, not the card name, ID, or QP value sections, may contain markup.
• All tags are case-sensitive.
• Markup processing errors will generally only be visible in the browser's developer tools console (in the form of exceptions). The markup processor is relatively strict.
• Marked-up text may not contain any raw HTML - the processor will not treat it as such.
• The rigid format of the game's cards precludes colorizing text and glyphs. It "can be done" but would not be in the spirit of the game's graphic design, so those features are not described in this document.

Generic Markup

Keywords and Glyphs

"For historical reasons," the markup has two general styles of markup for keywords and game-specific glyphs (icons). Tags in the form {:XYZ:} and {::XYZ::} represent game-specific glyphs and keywords. The form with a single colon on either side resolves to a glyph with (if available) its capitalized keyword to the left. The form with two colons resolves to only a glyph. (Again, this distinction is historical: the game for which this was originally written always writes keywords with their associated icon.) The following table demonstrates the available keyword/glyph tags and how they appear when resolved...

Note that the images are sized (via CSS) to fit their surrounding text, so a larger font size will result in correspondingly larger glyphs.

Creating Your Own Cards

To create your own cards, edit these files, included in the same distribution as this file:

• scratchpad.html - Scratchpad and sandbox.
• sidequests.html - Side Quests only.
• heroicquests.html - Heroic Quests only.

Add, edit, and/or remove cards to suit, then print out the page, being sure to note the caveats and limitations of card printing.

To create several independent sets of cards: copy one of those HTML files, and optionally its like-named JavaScript file, to a new file and rename, if needed, the JavaScript file reference at the bottom of the new HTML file to point to the renamed JavaScript file. It is possible to mix card types within a single file, as scratchpad.* demonstrates, but print results are generally better if each file contains only a single type of card (as sidequest.* and heroicquest.* do).

Note that the above files, as well as any copies made of them, need to live in the same directory as this file so that they can find the various resources (images, fonts, and CSS) used by the card tools.

Printing Cards

Cards created with these tools can be printed directly from one's browser, either to a printer or to a PDF. There are, however, caveats and things to be aware of...

Multi-page printing: When printing cards from any pages in this collection, the only reliable way to get major browsers to wrap cards at page boundaries, rather than truncate them when spanning pages, is to ensure that all cards being printed are placed directly in the page's BODY element, not wrapped in a sub-element. For example, using a table to line them up or a DIV to group them will lead to truncation. That's an unfortate quirk which affects all known browsers and for which there is no known workaround. Thus, when creating HTML files of cards, make sure the cards are all direct children of the page's BODY element. When using the provided page templates for creating cards, that's already taken care of.

Background colors and images: Browsers may choose not to print background images and colors, and might (depending on the environment) need to be explicitly told to do so. The included CSS provides a hint to the browser that it should print such things, but if your printouts do not include background colors or images (e.g. the card backgrounds), make sure they're enabled in your platform's print job configuration dialog.

Resolution and Scaling: Modern browsers, when printing or generating a PDF, will transform the cards to vector-format graphics suitable for printing at effectively any resolution (with the limitation that the card background graphics are bitmaps, so have a limited resolution). Printing them at 100% scale will produce cards size-compatible with those which come with the game. Note, however, that there may be slight color differences from printer to printer, so do not expect a 100% perfect match against the originals!

Inconsistencies across browsers: Each browser has its own quirks with regards to the finer details of HTML and CSS layout. Two different browsers might even understand "use this font in 12pt size" to mean two slightly different things for "12pt". These tools are tested solely with some version of Chromium and Firefox, and it has been my not inconsiderable experience that Firefox, more often than not, does a slightlly better job of it. (Chromium, however, is the only one which can be fully automated to batch-print cards.) Thus if the cards don't look right to you on one browser, try another (noting that many browsers nowadays are internally based on Chromium's rendering engine).

Inconsistencies, part 2: Similarly to the above point, any given browser may lay out cards inconsistently. e.g. it may choose to print X cards on page 1 of a printout and X-3 or X+3 cards on every other page. They may also ignore explicit margin and similar layout fine-tuning, or may apply them inconsistently across pages or rows within a page, and there's nothing we can do about that. Though HTML and CSS give us a fairly good level of control over the layout, it does not provide the pixel-level precision of Postscript or PDF. (That's normally a good thing, as it allows us to delegate all layout to the browser, but it occasionally bites us.)

SVG-format Conversions

When the cards are printed to PDF, that PDF can then be imported into a vector graphics editor (e.g. Inkscape) to create SVG-format copies of the cards (noting that the card border/background images are bitmaps, not vector graphics). When importing to Inkscape, make sure to use the "poppler" import/conversion option (which is not the default!), as it will not only produce far better results than the default option, but will convert all text to "paths," which means that they are no longer editable as text but are 100% faithful conversions. Without that, the text will only look correct in Inkscape if Inkscape has the exact same font installed. It's been my experience that the default (non-poppler) import process produces fairly horrid results on just about any inputs, and should never be used when fidelity with the original is desired. Poppler conversion is relatively slow, but its results are unbeatable.

After importing a page of the PDF into Inkscape, one needs to "ungroup" (Ctrl-Shift-G) the cards, perhaps several times, to break them down into smaller parts (by default the whole page is one group). After doing so, the components can be re-grouped (Ctrl-G) into individual cards.

Why might one want to convert them to SVG? They can easily be laid out in one's graphical or desktop publishing software of choice for more precise printing than is possible with HTML. e.g. to include cut lines or place them side-by-side or front-to-back with card backs.