Skip to main content

Deck Format

Castle CLI projects use a directory for the deck and one directory per card.

my-deck/
  deck.json
  cards/
    <card-id>/
      card.json
      scripts/
        main.lua
      scene/
        actors.yaml
        variables.yaml
        blueprints/
          main.yaml
          main.json
  .castle/

deck.json​

deck.json marks the root directory as a Castle deck project. It stores the deck title, deck ID after saving or getting from Castle, visibility, deck variables, initial card, and card list.

cards/​

Each card has its own directory under cards/. The directory name is the card ID.

card.json​

card.json stores card metadata such as the card ID, title, scene properties, and linked deck IDs.

scripts/​

Lua scripts live in scripts/. Edit these files directly, then run castle restart to reload the preview.

scene/​

scene/ contains materialized scene data:

  • actors.yaml lists actor instances.
  • variables.yaml lists card variables.
  • blueprints/*.yaml exposes blueprint components in a readable format.
  • blueprints/*.json stores generated sidecar data used by the CLI.

Treat the generated scene YAML and blueprint JSON files as inspection files. Use castle edit for structural scene changes.

.castle/​

.castle/ stores local CLI state such as serve metadata, logs, screenshots, and cached data. It is local project state used by the CLI.