# Lonelog: Card Notation Add-on
Roberto Bisceglie

## Overview

Core Lonelog already acknowledges card draws as a valid way to resolve uncertainty or generate content. What it doesn’t define is a compact, unambiguous shorthand for card identities.

Without a standard, logs fill with inconsistent spellings: “Q of spades”, “queen♠”, “Queen Spades”, “QS”. Tarot draws fare worse — “reversed Tower” and “The Tower (rev.)” and “XVI r” are all the same card. For tools that parse logs, and for players who share them, the inconsistency creates friction.

This add-on defines a compact notation for three types of card draws:

- **Standard playing cards** — the 52-card deck plus jokers
- **Tarot** — Major Arcana, Minor Arcana, and upright/reversed orientation
- **Oracle decks** — a lightweight convention for named-card systems

**When not to use this add-on:** If you play a single system with a single card type and never share logs, your current spelling probably works fine. Adopt this notation when consistency matters — for shared logs, tool support, or crossing between multiple card systems in one campaign.

------------------------------------------------------------------------

### What This Add-on Adds

| Element | Purpose | Example in a log |
|----|----|----|
| `{rank}{suit}` | Compact standard card identity | `tbl: draw=Qs -> Dark omen` |
| `M{n}` | Major Arcana by number | `tbl: draw=M12r -> Blocked` |
| `{rank}{suit}` with tarot suits | Minor Arcana | `tbl: draw=KnCu` |
| `r` suffix | Reversed orientation (Tarot) | `tbl: draw=M16r` |
| Position labels in spreads | Named positions in a multi-card spread | `tbl: Past=5s, Present=Ks` |

The add-on also uses two ordinary core tags for what a deck and a hand hold: a `[Deck:]` tag counts the cards left and lists the ones out of play, and a `hand:` category on the character lists the cards held (see *Deck State and Hands*).

**No new core symbols.** Card draws use `tbl:`, `d:` and `->` exactly as defined in core Lonelog. The card identity uses `=` as the drawn result; `->` carries the interpreted outcome.

### Design Principles

**Cards follow the same pattern as dice.** `=` records the drawn card, `->` carries the interpreted outcome, `=>` carries the narrative consequence. `tbl: draw=Qs -> Dark omen` is the same structure as `tbl: Loot d100=42 -> A broken sword`.

**Content or verdict decides the prefix** (core Lonelog §3.2.2). Most draws give content — an image, an omen, a place, an encounter — and use `tbl:`. A draw that gives a verdict — a fate card answering yes or no, a card played against a target — uses `d:`.

**Compact but readable.** `Qs` over “Queen of Spades”. Abbreviations should be recoverable without a lookup table by anyone who knows the card system.

**No orientation assumption.** Upright is the default and unmarked. Reversed is the exception and is always marked with `r`. A card with no suffix is always upright.

------------------------------------------------------------------------

## Part I: Practical Reference

### How card draws fit into a log entry

Card draws follow the same structure as dice rolls. The card drawn is the raw result and uses `=`; the interpreted outcome uses `->`. Draws that give content use `tbl:`:

    tbl: draw=Qs
    tbl: draw=M12r -> The obstacle is myself.
    => The Hanged Man reversed. I've been the obstacle all along.

For oracle reads that answer a question, pair with `?`. When the card gives an image to interpret, it’s still `tbl:`; when your deck or method turns it into a yes or no, it’s `d:`:

    ? Can I trust the merchant?
    tbl: draw=Jc -> Scheming youth
    => No.

    ? Is the bridge still standing?
    d: draw=Qh vs red -> Yes

For spreads, label each position with `=`:

    tbl: Past=5s, Present=Ks, Future=ACu

------------------------------------------------------------------------

Or split across lines when each card needs its own consequence:

    tbl: Past=5s
    tbl: Present=Ks
    tbl: Future=ACu
    => Conflict led here. Authority holds the present. Something new waits at the end.

------------------------------------------------------------------------

### Standard Playing Cards

Ranks: `A`, `2`–`10`, `J`, `Q`, `K`  
Suits: `h` (hearts ♥), `d` (diamonds ♦), `c` (clubs ♣), `s` (spades ♠)  
Format: `{rank}{suit}`

    Ah    Ace of Hearts
    7c    Seven of Clubs
    Ks    King of Spades
    10d   Ten of Diamonds
    Jh    Jack of Hearts

Jokers: `Jkr` (generic), `RJkr` (red joker), `BJkr` (black joker).

When the game cares about color but not suit: `R` (red — hearts or diamonds), `B` (black — clubs or spades).

**Card identities always follow `=`.** Write `draw=4d` or `Past=4d`, never a bare `4d`. That keeps a card apart from a dice expression: `4d` after `=` is the four of diamonds, while `4d6` on its own is four six-sided dice. The rule holds in compact form too.

In a log:

    @ Search the body
    tbl: draw=3h -> Minor find
    => A folded note, damp and illegible.

    @ Fate check
    tbl: draw=Jkr -> Chaos surge
    => Everything changes.

------------------------------------------------------------------------

### Tarot

#### Major Arcana

Format: `M{n}` where `n` is the card’s number (0–21).

| n   | Card               | n   | Card           |
|-----|--------------------|-----|----------------|
| 0   | The Fool           | 11  | Justice        |
| 1   | The Magician       | 12  | The Hanged Man |
| 2   | The High Priestess | 13  | Death          |
| 3   | The Empress        | 14  | Temperance     |
| 4   | The Emperor        | 15  | The Devil      |
| 5   | The Hierophant     | 16  | The Tower      |
| 6   | The Lovers         | 17  | The Star       |
| 7   | The Chariot        | 18  | The Moon       |
| 8   | Strength           | 19  | The Sun        |
| 9   | The Hermit         | 20  | Judgement      |
| 10  | Wheel of Fortune   | 21  | The World      |

Reversed: append `r`.

- `tbl: draw=M0` — The Fool, upright
- `tbl: draw=M16r` — The Tower, reversed

When space allows, add the name as an inline description:

    tbl: draw=M12 // The Hanged Man
    tbl: draw=M16r // The Tower reversed

#### Minor Arcana

Suits: `Wa` (Wands), `Cu` (Cups), `Sw` (Swords), `Pe` (Pentacles)  
Ranks: `A`, `2`–`10`, `Pg` (Page), `Kn` (Knight), `Q`, `K`  
Format: `{rank}{suit}`

    ACu     Ace of Cups
    7Wa     Seven of Wands
    PgSw    Page of Swords
    KnPe    Knight of Pentacles
    QCu     Queen of Cups
    KWa     King of Wands

Reversed: append `r`.

- `tbl: draw=5Swr` — Five of Swords, reversed
- `tbl: draw=KnCu` — Knight of Cups, upright

In a log:

    ? What force opposes me here?
    tbl: draw=KSw -> Adversary: principle, not malice
    => The King of Swords — cold logic. He acts on conviction, not cruelty.

------------------------------------------------------------------------

### Oracle Decks

Oracle decks use proprietary card names that cannot be standardized. Use the card’s name as free text with `=`, optionally with an inline description naming the deck. A deck that answers yes/no questions, like Mythic’s fate cards, gives a verdict and uses `d:`.

    tbl: draw // Ironsworn Oracle=Darkness and Shadow
    d: draw // Mythic Fate=Exceptional Yes -> Yes, and...
    tbl: draw // Crow's Eye Oracle=The Lantern -> Safe passage

For decks you use repeatedly, a short deck tag in the label keeps things scannable:

    tbl: Crow=The Lantern -> Safe passage
    tbl: Crow=The Abyss -> Something follows

------------------------------------------------------------------------

### Spreads

A spread is a multi-card draw where each card occupies a named position. Write position labels with `=` for each card.

**Single-line (compact, for short spreads):**

    tbl: Past=5s, Present=Ks, Future=ACu

**Multi-line (when each card needs interpretation space):**

    tbl: Past=M16r -> Collapse that was delayed, not avoided.
    => The Tower reversed. I should have fallen sooner.

    tbl: Present=KWa -> I am the force at work here.
    => The King of Wands. The fire is mine to wield or waste.

    tbl: Future=ACu -> Something new if I let go.
    => The Ace of Cups. Grief first, then an opening.

**Labeled spread with deck name:**

    tbl: Celtic Past=7Wa, Celtic Present=M12, Celtic Future=3Cu

------------------------------------------------------------------------

### Deck State and Hands

Many card-driven games care about what is left in the deck. Track it with a `[Deck:]` tag, using core Lonelog’s update rules: the count of cards left is `×N`, and the cards out of play are an `out:` category.

    [Deck:Main|×52]
    tbl: draw=Qs -> Dark omen
    [Deck:Main|×-1|out:+Qs]
    tbl: draw=M16 -> Collapse
    [Deck:Main|×-1|out:+M16]

When you reshuffle, reset both:

    => I shuffle the discards back in.
    [Deck:Main|×52|out:none]

A **hand** is a category on whoever holds it. Add cards as you draw them and remove them as you play them:

    [PC:Kael|hand:Ah, Kd, 7c]
    [PC:Kael|hand:+Qs]
    @ Play the Ace against the guard
    [PC:Kael|hand:-Ah]

Use several `[Deck:]` tags when a game uses several decks: `[Deck:Encounters|×20]`, `[Deck:Fate|×22]`.

### Common Patterns by System

**Standard deck as oracle (e.g. *Carta*, *For the Queen*):**

    @ Explore the next hex
    tbl: draw=7d -> Forest path
    => Tall pines, no trail. I mark it as unmapped.

**Tarot for scene framing:**

    ? What is the mood of this place?
    tbl: draw=M18 // The Moon -> Illusion, hidden things
    => Nothing here is what it seems.

**Oracle roll plus a complication card:**

    ? Is the bridge still standing? (Likely)
    d: d100=47 vs 75 -> Yes
    tbl: draw=Ks -> Complication: authority figure
    => The bridge is there, but a city guard holds the crossing.

**Reversed card as obstacle:**

    ? Does my contact show up?
    tbl: draw=M6r // The Lovers reversed -> Divided loyalties
    => He's here, but he brought someone I didn't expect.

**Horror game — Joker as catastrophe trigger:**

    tbl: draw=RJkr -> The Worst Thing
    => The lights go out across the whole building. Something found the generator.

------------------------------------------------------------------------

## Part II: Complete Reference

------------------------------------------------------------------------

## 1. Standard Deck Notation

### Ranks

| Symbol   | Card         |
|----------|--------------|
| `A`      | Ace          |
| `2`–`10` | Number cards |
| `J`      | Jack         |
| `Q`      | Queen        |
| `K`      | King         |

### Suits

| Symbol | Suit       | Color |
|--------|------------|-------|
| `h`    | Hearts ♥   | Red   |
| `d`    | Diamonds ♦ | Red   |
| `c`    | Clubs ♣    | Black |
| `s`    | Spades ♠   | Black |

### Jokers

| Symbol | Card                                       |
|--------|--------------------------------------------|
| `Jkr`  | Joker (generic, when color doesn’t matter) |
| `RJkr` | Red Joker                                  |
| `BJkr` | Black Joker                                |

### Color Shorthand

When a system cares about red/black but not the specific suit:

| Symbol | Meaning                       |
|--------|-------------------------------|
| `R`    | Red card (hearts or diamonds) |
| `B`    | Black card (clubs or spades)  |

### Full Card Examples

    Ah    Ace of Hearts
    2c    Two of Clubs
    10d   Ten of Diamonds
    Jh    Jack of Hearts
    Qs    Queen of Spades
    Kd    King of Diamonds
    Jkr   Joker

**Note:** `10d` (Ten of Diamonds) is two characters before the suit. All other ranks are one character. Parsers should treat `10` as a complete rank token.

## 2. Tarot Notation

### Major Arcana

**Format:** `M{n}` where `n` is 0–21.

**Reversed:** append `r` — `M0r`, `M16r`.

| n   | Card               | Symbol | Reversed |
|-----|--------------------|--------|----------|
| 0   | The Fool           | `M0`   | `M0r`    |
| 1   | The Magician       | `M1`   | `M1r`    |
| 2   | The High Priestess | `M2`   | `M2r`    |
| 3   | The Empress        | `M3`   | `M3r`    |
| 4   | The Emperor        | `M4`   | `M4r`    |
| 5   | The Hierophant     | `M5`   | `M5r`    |
| 6   | The Lovers         | `M6`   | `M6r`    |
| 7   | The Chariot        | `M7`   | `M7r`    |
| 8   | Strength           | `M8`   | `M8r`    |
| 9   | The Hermit         | `M9`   | `M9r`    |
| 10  | Wheel of Fortune   | `M10`  | `M10r`   |
| 11  | Justice            | `M11`  | `M11r`   |
| 12  | The Hanged Man     | `M12`  | `M12r`   |
| 13  | Death              | `M13`  | `M13r`   |
| 14  | Temperance         | `M14`  | `M14r`   |
| 15  | The Devil          | `M15`  | `M15r`   |
| 16  | The Tower          | `M16`  | `M16r`   |
| 17  | The Star           | `M17`  | `M17r`   |
| 18  | The Moon           | `M18`  | `M18r`   |
| 19  | The Sun            | `M19`  | `M19r`   |
| 20  | Judgement          | `M20`  | `M20r`   |
| 21  | The World          | `M21`  | `M21r`   |

**Note:** The Thoth Tarot and some other decks swap the positions of Strength (VIII) and Justice (XI). The `M{n}` notation follows the Rider-Waite-Smith standard (Strength = 8, Justice = 11). If you use a different numbering, note it in your session header.

### Minor Arcana

**Suits:**

| Symbol | Suit              | Element |
|--------|-------------------|---------|
| `Wa`   | Wands             | Fire    |
| `Cu`   | Cups              | Water   |
| `Sw`   | Swords            | Air     |
| `Pe`   | Pentacles / Coins | Earth   |

**Ranks:**

| Symbol   | Card         |
|----------|--------------|
| `A`      | Ace          |
| `2`–`10` | Number cards |
| `Pg`     | Page         |
| `Kn`     | Knight       |
| `Q`      | Queen        |
| `K`      | King         |

**Format:** `{rank}{suit}` — `ACu`, `7Wa`, `PgSw`, `KnPe`, `QCu`, `KWa`

**Reversed:** append `r` — `7War`, `PgSwr`

### Orientation

| Suffix   | Meaning           |
|----------|-------------------|
| *(none)* | Upright (default) |
| `r`      | Reversed          |

## 3. Oracle Decks

Oracle decks use proprietary card names. No compact symbol system can cover them all. Use the card’s name as free text with `=`.

For logs that use a single oracle deck throughout, establish a short deck prefix in your session header or as a note, then use it consistently:

    [Session: ...] [Oracle: Crow's Eye]

    tbl: draw=The Lantern -> Safe passage
    tbl: draw=The Abyss -> Something follows

For mixed-deck sessions, name the deck inline:

    tbl: draw // Crow's Eye=The Lantern
    tbl: draw // Ironsworn Oracle=Darkness and Shadow

------------------------------------------------------------------------

## 4. Spread Notation

A spread assigns each drawn card to a named position. The position label appears in the `tbl:` field with `=` for each card.

### Single-line format

    tbl: {Position1}={card1}, {Position2}={card2}, ...

Example:

    tbl: Past=5Sw, Present=KWa, Future=ACu

### Multi-line format

Use when each card warrants its own `->` or `=>`:

    tbl: {Position}={card} -> [outcome]
    => [Narrative consequence]

------------------------------------------------------------------------

### Common spread names

These are conventions, not requirements. Any position label is valid.

| Spread | Positions |
|----|----|
| Three-card | `Past`, `Present`, `Future` |
| Three-card (alt) | `Situation`, `Action`, `Outcome` |
| Three-card (alt) | `Mind`, `Body`, `Spirit` |
| Celtic Cross | `Self`, `Cross`, `Foundation`, `Past`, `Crown`, `Future`, `Self2`, `Environment`, `Hopes`, `Outcome` |
| Single draw | `draw` (no position label needed) |

------------------------------------------------------------------------

## Quick Reference

### Standard Deck

    Ah  Ac  Ad  As    Aces
    Kh  Kc  Kd  Ks    Kings
    Qh  Qc  Qd  Qs    Queens
    Jh  Jc  Jd  Js    Jacks
    10h … 2h          Number cards (any suit)
    Jkr  RJkr  BJkr   Jokers
    R  B                Color only

### Tarot

    M0 – M21            Major Arcana (M0 = The Fool, M21 = The World)
    M0r                 Reversed Major Arcana

    ACu  7Wa  PgSw  KnPe  QCu  KWa   Minor Arcana
    7War                              Reversed Minor Arcana

    Suits: Wa (Wands)  Cu (Cups)  Sw (Swords)  Pe (Pentacles)
    Ranks: A  2–10  Pg  Kn  Q  K

### In a Log

| Log line | Meaning |
|----|----|
| `tbl: draw=Qs` | Single draw, no interpretation needed |
| `tbl: draw=Qs -> Dark omen` | Single draw with outcome |
| `tbl: draw=M16r -> Everything breaks` | Tarot, reversed, with outcome |
| `tbl: draw=M12 // The Hanged Man` | Draw with the card’s name as a description |
| `tbl: Past=5Sw, Present=KWa` | Spread on a single line |
| `d: draw=M17 -> Yes` | A card answering a yes/no question: a verdict |

------------------------------------------------------------------------

## FAQ

**Q: Why does the card use `=` rather than `->` — isn’t the card itself the outcome?**  
A: The card drawn is the raw result of the mechanic, just as `9` is the raw result of `2d6+2`. What the card *means* in context — the interpreted state — is the outcome, and that goes in `->`. `tbl: draw=Qs -> Dark omen` mirrors `tbl: Loot d100=42 -> A broken sword` exactly.

**Q: What about card games that use multiple decks, or partial decks?**  
A: Give each deck its own `[Deck:]` tag, with a count of the cards left and an `out:` list of the cards out of play. See *Deck State and Hands*.

**Q: My system uses pip value (Ace = 1, King = 13) rather than card identity. Should I write the card or the number?**  
A: Write the card: `d: draw=Ah -> 1`. The card identity is the raw result; the pip value is the interpreted outcome. Both are preserved.

**Q: How do I note a hand of cards (drawn but not played)?**  
A: As a `hand:` category on the character: `[PC:Kael|hand:Ah, Kd, 7c, Qs, 3h]`. Remove a card with `hand:-Ah` when it is played. See *Deck State and Hands*.

**Q: Tarot decks vary — some have different names or art. Does `M12` always mean The Hanged Man?**  
A: This spec follows the Rider-Waite-Smith numbering, which is the most common standard. If your deck diverges (e.g. Thoth swaps Strength and Justice), note it once in your session header: `[Deck: Thoth — Strength=M11, Justice=M8]`.

------------------------------------------------------------------------

**Q: Can I use `?` with a card draw instead of `tbl:` or `d:`?**  
A: Use `?` for the question, then `tbl:` or `d:` for the draw that answers it. They are separate events — the question is asked, then the card is drawn as the mechanical resolution.

    ? What does fate hold for this meeting?
    tbl: draw=M10 // Wheel of Fortune -> Chance rules all
    => Anything could happen. I prepare for nothing and everything.

**Q: What about digital tools that render suit symbols (♥ ♦ ♣ ♠)?**  
A: The letter abbreviations (`h d c s`) are the canonical form for logs. Tools that render logs may substitute suit symbols for display, but the stored notation should use letters to stay plain-text safe.

------------------------------------------------------------------------

## Credits & License

© 2026 Roberto Bisceglie

This add-on extends [Lonelog](https://zeruhur.itch.io/lonelog) by Roberto Bisceglie.

**Version History:**

- v1.1.0: Added deck state (`[Deck:]` with `×N` and `out:`) and hands (`hand:` category); card identities always follow `=`; the oracle example no longer claims to be Ironsworn’s. Aligned with Lonelog v1.7: draws that give content use `tbl:`, draws that give a verdict use `d:`. Explanations moved out of code blocks.
- v1.0.0: Initial release

This work is licensed under the **Creative Commons Attribution-ShareAlike 4.0 International License**.

You are free to share and adapt this material, provided you give appropriate credit and distribute adaptations under the same license. Session logs and play records created using this add-on’s notation are your own work and are not subject to this license.