# cardsKit
A card game kit for multiplayer Zero worlds: classic games like war or crazy eights, simple deckbuilders, tarot-style fortune telling, or whatever you dream up. Cards are described as data, decks are built from them, and every player gets a draw pile, a private hand, a discard pile and a shared table. Drawing, dealing, discarding, playing and shuffling the discard back in never lose or duplicate a card (an audit proves it). The shuffle is fair and repeatable: the same seed gives the same order on every screen and every computer. You drag a card from your hand onto the table to play it (dropped anywhere else it slides back), or tap it and tap the table on a phone. Card effects go into a queue and resolve one after another, so "draw two, then discard one" just works. Six card frame styles, three ways to hold a hand and three starter decks sit behind one interface: change one setting to change the look or the deck. Turn order and seats come from **gridKit**. Two guides ship inside the package.
Version **1.0.4** (`CK.VERSION`).
## Quick start
1. Install `cardsKit.package` into `/source` (search ZeroMind for "cardsKit", or install guid `e9e2f577-f8fa-43e7-85de-bd0684bd52f2` into `/source`). gridKit comes along as a dependency.
2. Make your scene a card table: open `scenes/main.scene/scene.json` and set `"player": "none"` (a walking player's camera would take the mouse the cards need).
3. Replace `scenes/main.scene/build.luau` with:
```lua
local CK = require("cardsKit.api")
function content()
local cam = entity.spawn("TableCamera")
cam.component.add("Camera", {})
cam.localPosition = { 0, 3, 6 }
CK.Table { deck = "standard", style = "classic", layout = "fan", handSize = 5 }
entity.spawn("Gallery").component.add("cardsKit.CardGallery", {}) -- optional: the style/layout/deck browser
end
```
4. Press play. You take seat 1 and are dealt 5 cards. Drag one onto the felt to play it. Every friend who joins takes the next seat and gets their own 5 cards, which only they can see.
Change one word to change the game: `style = "pixel"`, `layout = "grid"`, `deck = "tarot"`.
### A deckbuilder duel in one call
```lua
CK.Table {
name = "Duel", deck = "effects", style = "fantasy", layout = "row",
seats = 2, handSize = 5, actions = 0, -- play as many cards as your energy allows, then End turn
stats = { hp = 30, hpMax = 30, block = 0, energy = 3 }, -- energy refills and block wears off each turn
}
```
### Game rules in a few lines
Rules run on the dealer; register them on every peer, inside `onLoad` in the scene's `entrypoint.luau` (it runs on every machine when play starts, joiners included). A crazy-eights style game:
```lua
local CK = require("cardsKit.api")
function onLoad()
CK.rules("CardTable", {
onStart = function(t) -- turn up a starter card
local g = t.game()
g:move(g.draw[#g.draw], "discard")
end,
canPlay = function(t, seat, card) -- match the suit or the rank; eights are wild
local top = t.game():discardTop()
local topCard = top and t.game():def(top)
if topCard and card.rank ~= 8 and card.suit ~= topCard.suit and card.rank ~= topCard.rank then
return false, "Match the suit or the rank."
end
end,
onPlay = function(t, seat, card, id)
t.game():move(id, "discard") -- the played card becomes the one to match
if #t.game():hand(seat) == 0 then t.setResult(t.seatName(seat) .. " wins!") end
end,
})
end
```
## What you get
| part | what it is |
|---|---|
| `cardsKit.api` | the one interface: `local CK = require("cardsKit.api")` |
| `CardTable` component | one multiplayer table: the dealer's logic and each player's table screen |
| `CardGallery` component | a Gallery button (in the table's top bar, or a screen corner when no table is shown) opening a browser of every style, layout and deck, with "Use on table" |
| `game` module | the pure model: piles, hands, table, turns, stats, audit, save/load, recovery |
| `cards`, `decks` modules | cards as data, decks, the three starter decks |
| `shuffle` module | the seeded Fisher-Yates shuffle |
| `effects` module | the effect queue and its built-in effects |
| `styles`, `layouts` modules | the six frame styles and the three hand layouts |
| `registry` module | this peer's tables, rules, event bus and network channels |
| `art/` | painted card backs (6), tarot illustrations (22) and effect-card illustrations (10), 512 px |
| `cardsKit` test suite | 12 tests of the public features |
| `guides/` | the how-to guide and the higher-card example (see Guides) |
## Catalog
Every entry is also in `CK.CATALOG`; filter it with `CK.variants{ kind = "style" | "layout" | "deck", tag = "retro", search = "words" }`. Names are forgiving: `"sci fi"`, `"8-bit"`, `"Playing Card"` all resolve.
### Frame styles (`style`)
| id | name | looks like | also answers to |
|---|---|---|---|
| `fantasy` | Fantasy | aged parchment in a double gold frame, crimson name banner, sapphire cost gem, EB Garamond; dragon medallion back | medieval, rpg, gold, parchment |
| `scifi` | Sci-fi | gunmetal glass with chamfered corners, cyan glow edge, hexagon cost chip, monospace type; holographic planet back | sci-fi, space, cyber, neon, tech |
| `classic` | Classic playing card | white stock, red and black corner indices, real pip layouts and court frames, Tinos serif; red engraved back | playing card, casino, poker |
| `minimal` | Minimal | warm paper, hairline edge, thin accent bar, lots of air, Arimo; single-line geometric back | clean, flat, modern, simple |
| `pixel` | Pixel art | square corners, chunky light border, hard drop shadow, monospace caps; 16-bit crown back | retro, 8bit, 16bit, arcade |
| `cartoon` | Cartoon | thick ink outlines, bright flat colours, bouncy offset shadow, Comic Neue; sunburst star back | toon, comic, playful, kids |
Every face adapts to its size: under 96 px wide (a phone's hand) it shows the corner index or cost and the art; up to 150 px it adds the name and type line; from 150 px the rules or meaning text and, on number cards, the pips. Tap any card on the table or the discard pile to see it big.
### Hand layouts (`layout`)
| id | name | how it holds the hand |
|---|---|---|
| `fan` | Fan | an overlapping arc like a hand held in front of you; the middle card stands highest |
| `row` | Straight row | one straight line; cards overlap only when the hand outgrows the width |
| `grid` | Grid | wrapping rows with a gap, so every card shows in full (big hands, phones) |
### Starter decks (`deck`)
| id | name | cards | what it is |
|---|---|---|---|
| `standard` | Standard 52 | 52 | four suits, ace to king (`CK.Decks.standard{ jokers = 2 }` adds jokers); ranks compare aces high with `CK.Cards.compare` |
| `effects` | Skirmish | 26 (10 kinds) | Strike (1, deal 6) x5, Heavy Blow (2, deal 12) x2, Fireball (2, deal 8 to every opponent) x2, Guard (1, block 5) x5, Shield Wall (2, block 12) x2, Insight (1, draw 2) x2, Quick Study (0, draw 2 then discard 1) x2, Mend (1, heal 6) x2, Second Wind (2, heal 4 then draw 1) x2, Focus (0, gain 2 energy) x2 |
| `tarot` | Major Arcana | 22 | 0 The Fool to XXI The World, each with an upright and a reversed meaning; `reversals = true` lets a drawn card come up reversed (art upside down, reversed meaning shown) |
## Cards as data
```lua
local strike = CK.card {
id = "strike", name = "Strike", type = "Attack", cost = 1, text = "Deal 6 damage.",
effects = { { kind = "damage", n = 6 } },
art = "myWorld.art.strike", -- a texture asset (name, path or guid), or "glyph:⚔" for a big symbol
color = "#c0392b",
}
CK.registerDeck { id = "myDeck", name = "My Deck", back = "myWorld.art.back",
cards = { { strike, copies = 6 }, { id = "guard", name = "Guard", cost = 1, text = "Gain 5 block.", effects = { { kind = "block", n = 5 } } } } }
CK.Table { deck = "myDeck" }
```
Card fields: `id` (required), `name`, `suit`, `rank` (1 = ace ... 13 = king), `rankLabel`, `cost`, `type`, `text`, `reversed`, `effects`, `art`, `back`, `color`, `number`, `tags`, `data` (anything else). An unknown field warns; a missing `id`, a non-number rank or cost, or an id listed twice is an error that names it. Register your decks everywhere they are named: build the deck in a module of your own that calls `CK.registerDeck`, and require that module at the top of both `build.luau` (before `CK.Table`) and `entrypoint.luau`.
## Table settings (`CK.Table { ... }`, also the `CardTable` fields)
| setting | default | what it does |
|---|---|---|
| `deck` | `"standard"` | `standard`, `effects`, `tarot`, or a registered deck id |
| `style` | `"classic"` | one of the six frame styles |
| `layout` | `"fan"` | `fan`, `row`, `grid` |
| `seats` | 2 | players seat themselves as they join; extra players watch |
| `handSize` | 5 | cards dealt when a player sits down |
| `turns` | `"alternating"` | gridKit turn model: `alternating`, `initiative`, `action_points`, `none` (anyone, any time) |
| `actions` | 1 | plays per turn: 1 passes the turn after a play; n > 1 gives n; 0 = no limit, press End turn |
| `drawRule` | `"any"` | tapping the deck draws: `any` time, only on your `turn`, or `never` (the game deals) |
| `seed` | 0 | 0 = the dealer picks a secret seed each game; any other number deals the same game every time on every screen |
| `tableCols`, `tableRows` | 6, 2 | the table's card slots |
| `stats` | none | starting numbers per seat (`{ hp = 30, energy = 3 }`); cards with a `cost` spend `energy` when the table tracks it |
| `reversals` | false | tarot: drawn cards may come up reversed |
| `autoSeat` | true | seat players automatically |
| `showUi` | true | draw the built-in screen (off for a game that draws its own from `CK.table`) |
| `felt` | `"#1d5a3c"` | the table colour |
| `title` | `"Card Table"` | the heading on every screen |
| `name` | `"CardTable"` | the table's name, used by `CK.table(name)` and `CK.rules(name, ...)` |
`style`, `layout` and `deck` also change live from any player: `CK.table("CardTable").set("style", "cartoon")` (changing the deck starts a new game).
## API
| call | does |
|---|---|
| `CK.Table(opts) -> entity` | spawns a synced table in a scene build |
| `CK.table(name?) -> t` | the live table (by name, entity or id; the only one when left out) |
| `t.draw(n?)`, `t.play(id, q?, r?, faceDown?)`, `t.discard(id)`, `t.endTurn()` | ask the dealer to act for you (refusals come back as a message on your screen) |
| `t.choose(ids)` | answer the effect queue's choice ("discard 1") |
| `t.reshuffle()`, `t.sweep()`, `t.restart(seed?)`, `t.sit(seat?)`, `t.leave()`, `t.set(key, value)` | table actions |
| `t.hand()`, `t.mySeat()`, `t.view()`, `t.state()`, `t.layout()` | your cards (`{ id, def, reversed }`), your seat, the public view, where each of your cards sits on screen |
| `CK.rules(name, hooks)` | game rules the dealer runs: `canPlay(t, seat, card, id) -> false, reason`, `onPlay(t, seat, card, id, q, r)`, `onDraw(t, seat, ids)`, `onTurn(t, seat)`, `onSit(t, seat, peer)`, `onStart(t)`; inside them `t.game()`, `t.log(text)`, `t.setResult(text)`, `t.push(effects, seat, now?)`, `t.nextTurn()`, `t.seatName(seat)` |
| `CK.on(event, fn) -> conn` | `moved`, `played`, `drew`, `shuffled`, `reshuffled`, `swept`, `revealed`, `turn`, `stat`, `recovered`, or `"*"`; each carries `{ table, seq, seat?, id?, def? (when public), from?, to?, count? }`; `conn.Disconnect()` |
| `CK.defineEffect(kind, handler, describe?)` | add an effect kind |
| `CK.card`, `CK.deck`, `CK.registerDeck`, `CK.shuffle(list, seed)`, `CK.face(style, card, w)`, `CK.back(style, w)` | the data and drawing helpers |
| `CK.Game.new{ deck, seats, seed, turns, actions, tableCols, tableRows, stats }` | the pure model: `deal`, `drawCards`, `play`, `discard`, `flip`, `reveal`, `take`, `sweep`, `reshuffle`, `move`, `endTurn`, `stat`/`addStat`, `audit`, `publicView`, `handView`, `save`/`load` |
## The effect queue
A played card's `effects` go to the back of the table's queue and resolve one at a time. An effect that adds effects of its own (`ctx.now(...)` in a handler) puts them at the front, so they finish before the rest carries on. An effect that needs a choice (`discard`) holds the whole queue until that player answers with the cards they tap, and nothing else resolves meanwhile; plays are refused while it waits. A failing effect is logged and skipped. Built in: `draw`, `discard` (`random = true` to discard at random), `damage` (block soaks first; `target = "opponent" | "opponents" | "all" | "self" | seat`), `block`, `heal` (capped by `hpMax`), `gain` (`stat`, `n`), `reshuffle`, `log`.
## How multiplayer works
- **One dealer.** The table lives on a synced entity owned by the room host, who is the dealer. The dealer alone holds the draw order and every hand, applies every request (draw, play, discard, end turn, choices), checks turns, resolves effects, and writes the table's public state.
- **The table is public.** The public state is one synced field: pile counts, the discard pile, every table card (face-down ones without their identity), each seat's hand **count**, stats, whose turn it is and the effect queue. Every player draws the same table from it.
- **Hands are private by delivery.** After each change the dealer sends each player their own cards in a message addressed to them. Other players' screens see only the count and the card backs. Card ids are scrambled by the seed, so an id says nothing about which card it is.
- **Players come and go.** A joiner takes the next free seat and is dealt in. A player who leaves gives their seat back, and their cards are shuffled back into the deck.
- **If the dealer leaves**, the next host becomes the dealer. It rebuilds the table, discard pile and stats from the public state, asks every player for their hand, and shuffles every card nobody holds into a new draw pile with a fresh seed, so no card is lost or doubled.
**How private is a hand, honestly?** Private enough for friends, not for stakes. Zero's `multiplayer.send` reaches every peer in the room and any peer may join any room of the world, so there is no channel only one player can hear. The kit addresses each hand to its owner, and the kit on every other screen drops it unread. It never stores or shows another player's cards, and the shared state carries none. But someone who modifies their own client could read the messages as they pass. The dealer (the host) holds every hand and the draw order by design. A non-zero `seed` makes the deal reproducible by anyone who knows it, so leave `seed = 0` in games with hidden hands.
## Controls
| | mouse | touch |
|---|---|---|
| play a card | drag it onto the felt (it lands in the slot you let go over; on the felt around the slots, in the first free slot) | tap it, then tap a slot, or tap it twice |
| discard | drag it onto the discard pile, or select it and press Discard | select it, press Discard |
| draw | click the deck | tap the deck |
| look at a card closely | select it in your hand (a big preview shows), or click a table card or the discard pile | tap a table card or the discard pile; select a hand card and press Look |
| choose for an effect | click the cards to pick, then Confirm | the same |
A card dropped anywhere that is not the felt or the discard pile slides back into your hand.
## Guides
Two guides come with the package and open in the Docs panel once cardsKit is installed:
- [How to make a card game: deck, shuffle, draw and drag cards to the table](cardsKit.package/guides/how-to-make-a-card-game-deck-shuffle-draw-and-drag-cards-to-the-table) teaches the kit: tables and settings, cards as data, the seeded shuffle, drag and tap to play, the effect queue, rules and events, and how multiplayer privacy works.
- [How to make a two-player higher card game, step by step](cardsKit.package/guides/how-to-make-a-two-player-higher-card-game-step-by-step) builds a small "play the higher card" game from an empty world.
## Tests
`zero tests run cardsKit` (edit mode). 12 tests cover:
- the shuffle against a fixed reference order, plus a fairness count;
- the decks and their art;
- conservation across 600 random operations, audited after each one;
- save and load, turns, and the effect queue's order and choices;
- dealer recovery, and the privacy of the public view;
- every style at three sizes, every layout, the catalog and `CK.Table`.
## Known limits
- **Hand privacy is by delivery, not encryption.** See "How private is a hand, honestly?" above: fine among friends, not for wagers or tournaments.
- **A dealer change drops a pending choice and reshuffles the deck.** If the host leaves while the effect queue waits on a choice, that choice is dropped. The new dealer's draw pile is a fresh shuffle of every unheld card. Hands, table, discard pile and stats carry over.
- **The table is a grid of slots** (`tableCols` x `tableRows`, default 6 x 2). A play onto a full table is refused until someone clears it (the Clear table button, `t.sweep()` or your rules).
- **Editing the kit's code during play restarts the table's game.** The dealer's state lives in the component, and a hot reload starts it fresh.
- **Seat names** use the player's display name where the platform provides one, otherwise "Player 1", "Player 2".
- **One table screen at a time per player.** The built-in screen is full-screen 2D, made for a scene that is the card table (`"player": "none"`). A walking camera that holds the mouse would block dragging.
- **Set the scene's `"player"` before replacing `build.luau`.** Saving both at the same moment can leave `scene.json` saying `"none"` while the loaded scene still expects player spawns, and Play refuses (#23642). Set it to `"spawns"`, save, then back to `"none"` and save again.
- **A drop onto the felt can land on a layer drawn over it** (#11943). The engine hands a drop to the topmost widget under the pointer, and only a canvas can let the pointer through, so a screen drawn over the felt (the kit's own drag ghost included) used to take the drop and a slow mouse drag did nothing. Since 1.0.4 the kit works out where every drag ended from what lies under the pointer, so a drag at any speed plays the card. If a screen of your own covers the felt, tapping the card and then the table always works.
- **Two engines signed in to one account collide as one player** (#14448). The two-player check used two different peers: the editor's client and an agent sub-client.
- **Multiplayer has a frame cost of its own** (#20750). The kit keeps its share small: the table redraws its screen only when the state, your hand or the window size changes, and while you drag only the small drag-ghost screen redraws each frame.
- **The web build is checked separately** (#20946): an agent cannot start a web engine itself, so the kit was verified in the desktop app.
## Versions
- **1.0.4**: a mouse drag at human speed now plays the card: the kit works out where a drag ended from what lies under the pointer instead of waiting for a drop its own drag ghost was taking (#11943), and letting go on the felt around the slots plays into the first free slot. Tall windows lay out cleanly: the top bar sizes itself to the seat tags (the piles no longer sit on them), the log gets a full-width strip under the felt, the fan measures each tilted card so the whole hand stays on screen, and the Gallery button sits in the table's top bar instead of over your cards. Checked at 1280x720, 1024x768, 768x1024, 780x1688, 390x844 and 2560x1440. No long dashes anywhere in the kit or the showcase. The layouts test now checks every card's rotated outline.
- **1.0.3**: documentation pass against the final code: the crazy-eights rules example now turns up a starter card and moves each played card to the discard pile (so the match check works; tested on the game model), and registers its rules in `onLoad`; decks are registered from both `build.luau` and `entrypoint.luau`; the how-to says which settings change live; Known limits drops two issues the kit never hit (#21420, #19258) and adds the scene `"player"` ordering note.
- **1.0.2**: the higher-card example guide was played through on a real table in a fresh install (9 rounds to a win, every round audited): the scene steps now set `"player": "none"` before `build.luau` (the other order can leave the loaded scene expecting player spawns, with a one-line fix if it does), and a dragged card is described as landing where it is dropped, with the round decided as the second card lands.
- **1.0.1**: the quick start names the package's real ZeroMind guid instead of a placeholder (checked by a fresh install that followed it word for word, tests 12/12 twice).
- **1.0.0**: first release. The six styles, three layouts and three starter decks; the CardTable with private hands, drag and tap play, the effect queue, gridKit turns and dealer recovery; the CardGallery; the 12-test suite; the two guides.