The card format

Status

This is duck-cards/0. Its words come from Studio's plan vocabulary, r001, and a row becomes a duck-intent-plan/0 plan.

The deck file, duck-cards.json, holds the same information as data. Every card on this site is drawn from it.

A card

Reading a row

A row is one line of cards, read left to right like a sentence.

1. Start and End mark the row. Both are optional. When they are on the table, nothing before Start or after End is read.
2. An action card is a step. Walk, Trick and Sound cards each make one step, in the order they lie.
3. Under changes the card above. A Speed or Look card placed directly below a card adds to that card's step. Under a card that cannot take it, a reader ignores it and says so.
4. Repeat makes a bracket. Repeat opens one and End repeat closes the nearest one still open. The count is written on the Repeat card, and a reader that cannot read handwriting asks for it. Brackets can sit inside brackets.
5. When it falls starts a second row. If the duck falls, the first row stops. Once the duck is back on its feet, the second row runs from its first card, and then the program ends.
6. Your cards mean what the deck file says. A reader that has no meaning for one stops at it and says which card it was.

Into a Studio plan

A row becomes the steps of a duck-intent-plan/0 plan, the format Studio's plan editor reads from a router. Each action card is one step, and the card's name is the step's clause. A card under it adds a label to that step. Control cards shape the steps and never become one. A plan has no events, so a When it falls row stays with the reader.

The row on the Duck Cards page becomes this:

{
  "format": "duck-intent-plan/0",
  "request": "Start. Say hello. Walk forward, slowly. Turn left. Kick with the right foot. End.",
  "model": "duck-cards/0",
  "steps": [
    {
      "clause": "Hello",
      "labels": {
        "action": "make_sound",
        "sound": "greet"
      }
    },
    {
      "clause": "Walk forward",
      "labels": {
        "action": "walk_forward",
        "speed": "slow"
      }
    },
    {
      "clause": "Turn left",
      "labels": {
        "action": "turn_left"
      }
    },
    {
      "clause": "Kick, right",
      "labels": {
        "action": "kick_right"
      }
    }
  ]
}

Studio's bench runs a plan with one trick at most, and only as its last step: on the bench a trick is a network that takes over when the walking ends, and it does not hand the duck back. A row with a trick anywhere else still becomes a plan, and Studio says why it will not run it. Sound and Look steps stay in the plan, but the bench plays no sound and sends no head pose.

On a robot

A reader that drives a real Microduck sends robotd's own calls, the way Microduck Studio's source does when it runs a plan on a duck: robot.move for each walking step, robot.do with the skill's name for a trick, and robot.sound with its tag for a sound. On a robot a trick can sit anywhere in a row, and a row can hold more than one, because the robot takes the duck back to walking when a trick ends. A Look card needs a head pose, robot.head, and Studio's source does not send one to a robot yet. Every card names its call.

Wait for each trick to finish before sending the next step: a trick runs to its end once it starts, and stopping the duck does not cancel it. Send intents only, never motor positions. The robot's own software decides what is safe to carry out.

Nobody has run a card on a real Microduck yet, because nobody has a Microduck yet.

The code

Every card carries an AprilTag from the tag36h11 family. The tag's id is the card's number.

• Size. On a full size card the tag's black square is a little over a centimetre across, with a white margin one cell wide around it. Keep that margin on a card of your own.
• Numbers by category. Each category has its own range, so a new card can join it without renumbering anything: Walk 0 to 19, Speed 20 to 39, Look 40 to 59, Trick 60 to 79, Sound 80 to 99, Control 100 to 119, When 120 to 139, and Your card 200 to 299.
• Checked before publishing. The codes are drawn from the family's own table, and this site's checks read every printed code back against that table before a page goes live.

NFC

Optional. Any NFC Forum Type 2 sticker with room for two records will do, and an NTAG213 has room for every card in the deck. Write the records in this order:

Record 1, URI:
https://microduckstudio.com/cards/spec/#card-61

Record 2, MIME type application/vnd.duckcards+json:
{"format":"duck-cards/0","tag":61,"code":"kick_right"}

A phone that taps the card opens its row in the table below. Lock the sticker after writing it, if your app offers to, so a curious tap cannot change a card.

The deck file

duck-cards.json is plain JSON, and a deck of your own starts as a copy of it.

format

duck-cards/0. A reader refuses a format it does not know.

vocabulary and plan_format

The Studio vocabulary the cards' labels come from, and the plan a row becomes.

categories

Each has an id, a name, a line about it, and codes, its range of numbers.

cards

Each card has a tag number, a code word, a name, a category, a kind (action, modifier, control, event or yours), the plan labels it adds to a step, and whether it is printed in the starter deck. A card of your own can add a does sentence that says what it means.

example

The row shown on the Duck Cards page, and how it reads aloud.

license

CC BY 4.0, for the cards, their pictures and the lessons.

Every card

Studio's words and the gamepad's buttons in this table are read out of Microduck Studio's source before every publish, and the site will not publish while a card disagrees with them.

Changing the format

• A number never changes meaning. A new card takes a new number from its category's range.
• Studio's words win. When Studio renames a label, the card is renamed with it.
• The version changes when a reader written for the old format would misread the new one.
• Propose a card by opening an issue on this site's repository.