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.

Adding a New Image

1. Create a new YAML file in a subdirectory having the same name as the Markdown page you're putting it on. (You can base it off of an existing YAML file if you want.)

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

import NewChopMove from "./page-name/new-chop-move.yml";

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

<NewChopMove />

See the Markdown file for level 2 as a basic example of how a document is supposed to look with both text and images.

Development

When using npm run start to view 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.

Guidelines

These are general guidelines that should be followed when creating or modifying images. The best way to start is to copy and modifying an existing one.

• Examples should normally use 5 stacks and 3 players. Include more only if needed.
• Stacks can be skipped if they are not at all important to the scenario.
• Only include card identities that are relevant to the scenario. The less details, the clearer and more general.
  • Identify cards with the type: attribute.
    • Make sure to use border: false if they haven't been touched by a clue.
    • Cards that have been touched by a clue are partially identified. (For example type: 2.)
    • Additionally, if a note has been written, put it in the middleNote attribute.
    • Use multiple types sparingly, and only when relevant to the variant (i.e. rainbow/pink).
  • Usually do not identify cards in the clue giver's or the reacting player's hand.
    • Cards that are seen by only some players should have their identities above the card. (For instance: above: Red 2.)
• If a clue is given, always include who gives it using the clueGiver: true attribute.
  • The clue giver is usually Alice.
  • Make sure to include all touched cards with the clue: X attribute.
  • Morph touched cards like the game UI would do, using type: X attribute.
  • Indicate the focus of the clue with a gold message below the card. (For example below: Play or below: Stall.)
  • Retouched cards must have retouched: true to make the arrow grey.
  • Almost always indicate what the receiving player would write on the card using the middleNote attribute.
    • Use shorthand notation, and include all possibilities:
      • Fully identified: b2
      • Partially identified: b23, ryg2
      • Chop Moved: cm. Additionally, Chop Moved cards should have cm: true to draw a white border.
      • Known trash: kt. Additionally, known trash should have trash: true to draw a trash can.
  • Other cards whose identities are inferred from the given clue should have a black message below the card. (For example below: Finesse.)
    • It is not necessary to write notes on those cards, as they will usually blind play right away.
    • Do write their actual identities using above:, as those are known by the clue giver.
• Illegal clues and/or misplays should clearly be marked in red color.
• Mistakes or suboptimal clues should be marked in orange color.
• Alternative actions (discards, plays) should be marked below: in cyan color.
  • The player whose action it is should be marked with clueGiver: true or zeroClues: true.
• Other information about cards should be marked below:.

Each example is different, these are guidelines, use common judgment.

Detailed 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 or space instead of cards. The first on is used to describe something that happens in a game. The second to add some vertical space.

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
  - name: "Space:"
    cards:
      - type: x
      - type: x
      - type: x
  - space: 5
  - name: Small
    cards:
      - type: x
      - type: x
      - type: x
  - space
  - name: Default
    cards:
      - type: x
      - type: x
      - type: x
  - space: 100
  - name: Large
    cards:
      - type: x
      - type: x
      - type: x

Additionally, players can also contain an offset to change player names.

stacks:
  - r: 0
  - b: 5
  - m: 3
players:
  - cards:
      - type: x
      - type: x
      - type: x
  - cards:
      - type: x
      - type: x
      - type: x
        clue: r
  - text: Bob reinterprets his hand
  - offset: -1
    cards:
      - type: x
      - type: x
      - type: r2

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

crossedOut 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 cm attribute can be used to draw a white border around the card.

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

The fix attribute can be used to draw a wrench 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
        middleNote: cm
        cm: true
  - cards:
      - type: 134
      - type: rbm12345
        crossedOut: m35
      - type: xrbm12345
        crossedOut: r4
  - name: F
    cards:
      - type: rb2
        crossedOut: b
      - type: b345
        trash: true
        orange: 34
      - type: x
        fix: true

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 clueGiver 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:
  - y: 0
  - p: 0
players:
  - clueGiver: 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:

• middleNote 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, Bad, Play.
• You can override the color using color attribute. CSS colors are accepted, and additionally rainbow.

stacks:
  - r: 1
  - b: 1
  - m: 1
players:
  - cards:
      - type: 4
        middleNote: (B)
      - type: r
        middleNote: (2)
      - type: x
        middleNote: cm
        below:
          text: Bar
          color: yellow
  - cards:
      - type: x
        above: Red 1
      - type: x
        above:
          text:
            - Multi-
            - line
        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
        below: Bad
      - type: x
        below: Play

Some shortcuts expand to larger text:

stacks:
  - r: 1
  - b: 1
  - m: 1
players:
  - cards:
      - type: r
        below: cm
      - type: 4
        clue: 4
        below: op
      - type: 4
        clue: 4
        below: sp

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
bigText:
  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: xiwguntoks
      - type: iwguntoks5
  - cards:
      - type: t1
      - type: n2
      - type: o1
  - cards:
      - type: k4
      - type: s3
      - type: s12345