Technical Documentation for the Example Images

Intro

Throughout this website, we have example images that show game states. This page describes how to edit them or how to create new ones.

Each example image is created from a YAML file, which is a simple textual description that you can easily edit. The YAML files are located in the image-generator/yml directory.

Steps

1. Put a new YAML file or edit an existing YAML file in the image-generator/yml directory.

2. On the respective Markdown page, import it as a React component at the top of the file, like so:

import NewChopMove from "@site/image-generator/yml/level-123/new-chop-move.yml";

(For an example of this, look at the Markdown page for Level 1.)

3. Insert the React component at the appropriate place in the Markdown file:

<NewChopMove />

(For an example of this, look at the Markdown page for Level 1.)

Development

When using the run.sh script and viewing the page locally, any changes that you make to the website will be automatically updated without having to refresh the page. This includes any changes to YAML files - they will be automatically re-converted into SVG files on the fly and updated in the browser.

YML File Format

There are 2 main sections: stacks and players.

• stacks is an array of cards which have been played on the stacks already. The following suits are supported by default:
  • r: red,
  • g: green,
  • b: blue,
  • y: yellow,
  • p: purple,
  • m: rainbow (multicolor).
• players contains an entry for each player. Each entry contains the cards that they have in their hand.

stacks:
  - r: 1
  - g: 0
  - b: 3
players:
  - cards:
      - type: x
      - type: x
      - type: x
  - cards:
      - type: x
      - type: x
      - type: x

Players are assigned the following names automatically: Alice, Bob, Cathy, Donald, and Emily. It is possible to override this with the name attribute. For example, this could be useful if Bob's hand is shown twice, before and after something happens.

players can also contain a text instead of cards. This is used to describe something that happens in a game.

stacks:
  - r: 0
  - b: 5
  - m: 3
players:
  - cards:
      - type: x
      - type: x
      - type: x
  - text: Aliens replaced Bob with Zoe.
  - name: Zoe
    cards:
      - type: x
      - type: x
      - type: x

Cards

Cards in hand can be of various types:

• clued with known exact identity, e.g. g2
• clued with known suit, e.g. b
• clued with known rank, e.g. 4
• clued with multiple possibilities, e.g. b234, rm4, ym45
• unclued card without any pips displayed, e.g. x
• unclued card with pips displayed, e.g. xrg23

crossed_out attribute can be used to mark some pips with X (when all other copies of that card are seen elsewhere).

The orange attribute can be used to draw some rank pips with orange. This is useful for pink cards.

By default, clued cards have an orange border, but this can be overridden with the border attribute.

The trash attribute can be used to draw a trash icon on top of the card.

stacks:
  - r: 1
  - b: 1
  - m: 1
players:
  - cards:
      - type: x
      - type: xrbm125
      - type: r4
  - cards:
      - type: m
      - type: b124
      - type: 5
  - cards:
      - type: rm24
      - type: bm3
      - type: rm
  - cards:
      - type: x
        border: true
      - type: m4
        border: false
      - type: xr3
  - cards:
      - type: 134
      - type: rbm12345
        crossed_out: m35
      - type: xrbm12345
        crossed_out: r4
  - name: F
    cards:
      - type: rb2
        crossed_out: b
      - type: b345
        trash: true
        orange: 34
      - type: x

Clues

You can use the clue attribute to show that a card is in the process of being clued.

By default, there is no clue giver, but this can be specified with the clue_giver attribute.

You can also use the retouched attribute to signify that the clue is re-touching a card, which will result in a darker arrow than normal. (This matches the behavior of Hanab Live.)

stacks:
  - p: 0
  - y: 0
players:
  - clue_giver: true
    cards:
      - type: p
        clue: p
      - type: x
  - cards:
      - type: x
      - type: yp5
        clue: 5
  - cards:
      - type: p1
        clue: 1
        retouched: true
      - type: x

Text on Cards

Text can be placed on a card:

• middle_note to put a text label in the middle of the card
  • the string is automatically colored if it is a letter of one of the 5 suits
• above to put a note above the card
• below to put a note below the card

above and below have the same syntax:

• above: Green 3 or above: Rainbow 5 will draw the box with the specified color and text.
• Several more keywords have a specific color assigned to them: Focus, Chop.
• You can override the color using color attribute. CSS colors are accepted, and additionally rainbow.
• You can make it a multi-line note by using an array.
• It can be a list of such text boxes, potentially with different colors.

stacks:
  - r: 1
  - b: 1
  - m: 1
players:
  - cards:
      - type: 4
        middle_note: (B)
      - type: r
        middle_note: (2)
      - type: x
        middle_note: (CM)
        below:
          - Green
          - text: Bar
            color: yellow
  - cards:
      - type: x
        above: Red 1
      - type: x
        below: Focus
      - type: x
        above: Rainbow 4
        below: Chop
  - cards:
      - type: x
        above:
          text:
            - Foo
            - Bar
          color: rainbow
      - type: x
        above:
          text: Foo
          color: indigo
      - type: x
        above: Save

Discard Pile

For some examples, some cards in the discard pile need to be shown. This is performed with the discarded array on the top level.

stacks:
  - r: 1
  - g: 1
  - b: 2
discarded:
  - r3
  - b5
players:
  - cards:
      - type: x
      - type: x
      - type: x
  - cards:
      - type: x
      - type: x
      - type: x
  - cards:
      - type: x
      - type: x
      - type: x

Big Text

For keywords "Bluff", "Finesse" and "Illegal!", color is ignored.

stacks:
  - r: 1
  - g: 1
  - b: 1
big_text:
  text: Blah
  color: green
players:
  - cards:
      - type: x
      - type: x
      - type: x
      - type: x
  - cards:
      - type: x
      - type: x
      - type: x
      - type: x

Variants

Some variant-specific suits can be added via suits, which contains the mapping from the letter indicating the suit to the part of the filenames of card images and pips. Currently these variant suits are supported:

• black
• brown
• null (needs to be in quotes because normally null is a YAML keyword)
• omni
• pink
• prism-rygbp
• teal
• white

Standard suits don't need to be repeated in suits.

This is done to be able to differentiate between suits which commonly use the same letter, e.g. or "i" for both prism and pink.

suits:
  t: teal
  k: black
  i: pink
  w: white
  n: brown
  o: omni
  u: "null"
  s: prism-rygbp
stacks:
  - i: 1
  - w: 0
  - g: 2
  - u: 4
  - n: 5
  - t: 0
  - o: 3
  - k: 4
  - s: 2
players:
  - cards:
      - type: i4
        border: false
      - type: u2
        border: false
      - type: w4
  - cards:
      - type: i12345
      - type: xgtkiwnous
      - type: gtkiwnous5
  - cards:
      - type: t1
      - type: n2
      - type: o1
  - cards:
      - type: k4
      - type: s3
      - type: s12345