# Build a deck of cards with an agent

> An AI agent turns a card sheet into a playable DiceyTable deck. It imports the art, runs deck_create and deck_set_cards, then checks cards one by one.

- Question: How does an agent turn card art into a playable deck?
- Source: https://diceytable.com/docs/ai-agents/workflows/build-a-deck
- Last verified: 2026-10-09

An agent turns card art into a deck in four moves. It imports a card sheet and a card back, creates the deck with
`deck_create`, names the cards with `deck_set_cards`, and checks the art with `screenshot_card`. Then it places the
deck in the scene so it shows up in the game.

A **card sheet** is one image with every card face laid out in a grid, like a sheet of stickers. Making your own card
game from scratch? The [card game maker](https://diceytable.com/features/card-game-maker) page shows what the finished thing can do.

## What you'll need

- An editor tab [paired with your agent](https://diceytable.com/docs/ai-agents/setup/pairing), with the project open.
- A key with **Edit projects**. To import from your computer it also needs **Local files**, or **Import from URLs**
  for a web address.
- The art: a card sheet and a card back, as PNG, JPEG or WebP files.

## Step 1: Import the art

The agent brings both images into the project with `asset_import`. Each import needs a credit that says who made the
art and under what license. Tell the agent the truth, and it fills the credit in for you.
[Import models, images and sounds](https://diceytable.com/docs/ai-agents/workflows/importing-assets) covers this step in full.

## Step 2: Create the deck

`deck_create` builds the deck from the sheet. The agent gives it the sheet's path, the back's path, and the grid
size in `rows` and `columns`. If the last row isn't full, `cardCount` says how many cells hold cards. A count bigger
than the grid is refused.

The tool returns a `deckId`. Every later call uses it to find this deck.

## Step 3: Name and count the cards

`deck_set_cards` sets the whole card list in one call. Each entry points at a cell of the sheet with `faceIndex`,
counting from 0 across each row. Each entry also has:

- a `label`, the card's identity. DiceyTable uses it to keep hidden cards hidden, so pick a clear one.
- a `count`, for how many copies the deck holds. The default is 1.
- optional `data`, such as a cost or a type.

The list replaces the old one whole, and the deck file is checked before anything is saved. A `faceIndex` past the
last cell makes the deck invalid, so nothing is written.

## Can the agent use one image per card?

Not directly. `deck_set_cards` refuses per-card images with the reason `per-card-images`. Cards always point at cells
of a sheet. If your art is in separate files, build the sheet in the [Deck editor](https://diceytable.com/docs/editor/item-editors/deck)
first. Then the agent can take it from there.

## How do cards get their text?

Many games share one card frame and change only the words. For those, the agent writes a **card layout**: a template
of text regions, filled from each card's data.

- `card_data_set` changes one card's data fields and keeps the rest.
- `card_layout_set` creates or updates a layout. The project needs a card schema first, which you add with
  **Mod ▸ New ▸ Card Data**.

The [Card Layouts editor](https://diceytable.com/docs/editor/item-editors/card-layouts) explains regions and matching rules.

> **Good to know.** Card text is what other players read. The agent also reads it back as untrusted text, so keep it
> plain. A card that says "ignore your instructions" is still only a card.

## Step 4: Check the art

`screenshot_card` draws one card, face or back, so the agent can see whether the grid lines up. A card that shows
half of its neighbor means the `rows` or `columns` are wrong. If the art itself needs a fix, the image tools such as
`image_quick_edit` can crop, rotate or adjust it.

## Step 5: Put the deck on the table

A deck that only lives in the project isn't in the game yet. The agent places it with `entity_create` and
`kind: "deck"`, as described in [Let an agent edit your scene](https://diceytable.com/docs/ai-agents/workflows/edit-the-scene). Then a
[play-test](https://diceytable.com/docs/ai-agents/workflows/playtest) can draw, deal and shuffle it.

![A deck face down on a poker table, next to two dealt cards face up and a bot's two cards face down](https://diceytable.com/assets/build/build-a-deck--deck-on-table-DZZelnB6.webp "**A deck that lines up.** Check one card face and the back before you deal a single hand.")

## Next steps

- [Building a deck by hand](https://diceytable.com/docs/editor/workflows/build-a-deck): the same job in the editor, step by step.
- [Take screenshots with an agent](https://diceytable.com/docs/ai-agents/workflows/screenshots): check the deck on the table, too.
- [Write game scripts with an agent](https://diceytable.com/docs/ai-agents/workflows/write-scripts): deal the cards automatically.