How a deal is decided
Core concepts gives you the words. This page is the mechanics behind deal
and peek. It says exactly which cards are considered, in what order, and why a card that
looks right sometimes doesn’t come up. It’s the page to read when the Board’s Why not? tab
names a reason and you want to know what that reason means.
The stock
Section titled “The stock”At any moment, each box has a stock, every card that could be dealt right now, in ranking
order. It isn’t stored anywhere. The engine works it out whenever you ask, and it changes as
state changes. A peek shows you the top of the stock, and a deal takes cards from it into
a hand.
The checks, in order
Section titled “The checks, in order”When your game deals a hand, the hand’s own condition is checked first, once. If it fails, nothing is dealt and no card is looked at, so the trace for that deal is empty rather than a list of refusals. (A peek has no hand condition.)
Every card in the box then goes through the same checks, in this order, and stops at the first one it fails:
- Deck gate: the card’s deck has a condition and it’s false.
- Cooldown: the card was played recently and its redraw policy says not yet.
- Tags: the card’s tags don’t match what the hand asked for.
- Condition: the card’s own condition is false.
- Claims: every copy of the card is already sitting in some hand.
The order matters when you’re debugging. The trace reports the first check a card
failed, so a card that’s both outside its deck’s gate and on cooldown is reported as
deck-gate, and fixing the cooldown won’t make it appear.
If a condition can’t be evaluated at all (it reads a property that doesn’t exist, say), the card is treated as unavailable and the reason is recorded. It never quietly passes.
Ranking the survivors
Section titled “Ranking the survivors”The cards that pass every check are put in order by:
- Priority comes first. It’s a number you set on the card, or an expression that works one out, and higher goes first.
- Specificity breaks ties. A card whose condition asks for more beats one that asks for less, so the special case wins over the general one. It’s on by default and you can switch it off per box, in which case priority decides outright.
- Chance decides anything still tied, weighted by each card’s
weight(default 1): a card of weight 2 comes up ahead of its equals twice as often as one of weight 1. Weight never lifts a card above a higher priority. The random numbers are seeded, so the same seed gives the same order every time, in every runtime.
A deal makes the hand right. It ranks everything eligible, including what the hand already
holds, and the hand becomes the top of that ranking. So a better card that has just become
eligible takes the place of a worse one, which goes back to the stock (the trace says
outranked). A card the hand holds wins a tie, so an equal card never swaps in for it. Between
deals a hand stays as it is: deal when your game is ready for the cards to change, after a
play or when its clock moves. With no state change between two deals, you get the same
cards.
In one hand, across hands, and claims
Section titled “In one hand, across hands, and claims”A dealt card is claimed by the hand holding it. By default a card sits in one hand at a time and fills one slot of it, exactly as a physical card can’t be in two places at once. Two settings on the card change that:
- In one hand (
inOneHand: N): it may fill up to N slots of one hand, for a pickup or a piece of equipment that can come up three times at once. - Across hands (
acrossHands: "any"): any number of hands may hold it at once, for interchangeable filler. The default,"one", keeps a one-off from being offered in two places.
deal claims, and peek only respects the claims that exist. Playing a card removes it (one
copy) from its hand and releases its claim; the slot fills at the hand’s next deal.
To take a card out of a hand without playing it, because the player turned it down or the game
wants the room, discard(card, hand) it. That’s no play: no outcome, no move of the clock,
nothing in the play log. Its Redraw starts as a play’s would, so the next deal doesn’t hand it
straight back.
This is what makes the “one rumour, offered wherever the player goes first” pattern free. Write one card, and whichever hand deals it first has it.
Claims live on the flow, so “at most one hand at a time” means at most one hand in that playthrough. Run several flows and a one-hand card is on two participants’ boards at once, because each of them is playing their own copy of the deck.
Unless you say otherwise. Mark a deck (or a single card) shared and its claims count
across every flow instead, so there’s one goblin in the whole world, held by whoever was
dealt it first, and nobody else can be dealt it until they play it or it leaves their board.
sharedCopies sets how many may be out anywhere, so sharedCopies: 5 is five golden tickets
with one to a customer. A card refused because
somebody else holds it says so. The trace verdict is claimed-elsewhere, not claimed,
because your own board has room.
A single-flow game never sees any of this, because with one playthrough open a shared claim and a per-flow one are the same thing.
Turns and cooldowns
Section titled “Turns and cooldowns”The clock is the turn, and each box has its own. Your game advances a box’s turns, and in
an ordinary box a play also advances the played card’s box by the project’s configured
amount (one by default, and you can override it per call). A box can instead say the game
moves its clock, so plays advance nothing: see below. Nothing here runs off a frame, and a turn is whatever your
game says it is.
A card’s redraw policy is its cooldown, measured in its own box’s turns: always (no
cooldown), never (a one-shot), or a number N (unavailable for N of that box’s turns after
it’s played). Cooldowns start when a card is played, not when it’s dealt. A peek never
touches any clock, and it draws no random numbers either, so however often you look, the next
deal comes out the same.
Clocks and cooldowns are per flow as well, so advancing a box in one flow moves nothing in another, and a one-shot spent by one participant is still there for the next.
On a shared card, redraw: never is the exception. The first participant to play it takes
it out of the world for everyone, permanently, and the others are told taken rather than
cooldown (they have no cooldown, because it isn’t there any more). A copy already sitting in
someone else’s hand, which a card with sharedCopies above one allows, leaves that hand at its
next deal, evicted as taken. A finite redraw stays
personal even on a shared card. The goblin goes straight back in the pool for whoever is
next, while the participant who just fought it waits their own three turns. For a world-wide
timer, use @world, where your game already keeps the time
(@world.now >= @world.goblin_returns_at).
And never is the one that can outlive the run. Mark a deck or a card durable and
its never spend is still spent tomorrow, for whoever played it, or for everyone if the card
is also shared. See
Durable state. Nothing else can carry,
because a finite cooldown is a turn of a clock that resets with the run, so durable on one
is a compile warning.
A box whose clock the game moves
Section titled “A box whose clock the game moves”A box’s clock moves on each play by default. It can say instead that your game moves it, so plays advance nothing: a calendar, where a turn is a day that ends when the game says so.
{ gameId: "calendar", title: "The Season", turn: {}, // the game ticks it, a day at a time ... }Or that its turns are real time:
{ gameId: "street", title: "The Street", turn: { seconds: 60 }, // one turn a minute of the run ... }That makes it a timed box, and three things follow. Plays in it advance nothing, because
the project’s play-advance setting doesn’t apply, though a play that names advanceTurns
still gets what it asks for. Your game ticks it, once every seconds of real time, for
every open flow, and the engine still has no clock of its own. And redraw: N on its cards
reads as N minutes rather than N plays, which is the point of declaring it. redraw: 30 in
a sixty-second box is half an hour, and the editor, the bundle inspectors, and the coverage
report all say so out loud.
Nothing else changes. The unit is a convention the tools spell out, and the time is still
per flow, so “the goblin comes back for everyone after half an hour” is a job for @world
as above.
Play history
Section titled “Play history”Four functions let a condition ask what has been played. They count plays, not deals, and they’re per flow.
| Function | Answers |
|---|---|
count_played("card") |
how many times that card has been played |
turns_since_played("card") |
how many of the card’s box’s turns since it was last played |
count_played_in("group", "tag") |
how many plays there have been of cards tagged with that tag |
turns_since_played_in("group", "tag") |
how many turns since the last play of a card tagged with that tag |
Cards, groups and tags are named by gameId. The turn counts are 0 straight after the play
and go up by one with each turn of the box’s clock. Before anything has been played they
read 9999, so turns_since_played("ambush") > 5 is true for a card never played, and
turns_since_played_in("zone", "docks") == 9999 asks “has nothing happened in the docks
yet?”.
count_played_in and turns_since_played_in count the card’s tags, not the hand it was
played from. A card with no tag in the group never counts towards it, wherever it was dealt.
They answer for the asking box. The group name is looked up in the box whose card or hand
is being asked about, and only that box’s own plays are counted, on that box’s clock. Two boxes
that each declare a zone group keep separate histories, and so do two boxes on the project
map: a news card read at the docks in one box isn’t an encounter at the docks in another.
A zone property is one value for every box that uses it; zone play history isn’t. A name the asking box
doesn’t know reads as never played: 0 from a count, 9999 from a turns-since.
Hand templates
Section titled “Hand templates”A hand template is a kind of hand you define once: “NPCs you can talk to” fixes some tags,
leaves others for each hand to choose, and carries one condition that’s written once and
evaluated for each hand against that hand’s own @hand. Edit the template and every hand
that uses it follows. A hand can override only its slot count. A hand can also stand alone,
with its own tags, condition, and slots written directly on it.
Your game never names a template. It deals hands.
The @hand scope
Section titled “The @hand scope”@hand is put together fresh for each deal, from three sources, later ones overriding
earlier ones where names collide:
- The properties of every tag the hand binds. These are usually declared on the tag
group, so every tag in it has them, and each tag sets only its own starting value, though
a single tag can also declare its own. Either way, a hand bound to
zone = forestsees@hand.peril. - The hand’s own properties come next, declared on the hand or its template.
- What the deal or peek asked for, by group name.
peek("village", { npc: "elder" })makes@hand.npcreadelder. A hand that pins a group itself reads the same way, and so does a group bound to a@worldor@storyproperty.
Every name remembers where it came from, so a write goes back to the right owner:
@hand.peril = @hand.peril + 1 raises the peril of the zone the card was dealt into. That’s
how state about where things happen works without a scope of its own. A
quality works the same way, so each
zone can sit at its own stage of one shared ladder, and advance(@hand.haunting) moves only
the zone the hand is in.
On the project map, a zone is one tag for the whole project, so its
properties are one value for every box that uses it. A hand in one box and a hand in another,
both in the docks, read and write the same @hand.danger. Each playthrough still has its own
value unless the property is marked shared (see
Shared or per flow). Everything else stays with the
box: a hand still deals only from its own box’s decks.
@hand names are checked when you publish, the same as any other scope, so a misspelt
@hand.perl is an error rather than a card that quietly never comes up, and a comparison
against the wrong type or a stage that isn’t on the ladder is caught too. What can’t be
worked out ahead of time is which hand will be asking, so the
Links window and storyletengine links still leave
@hand relationships out rather than guess. One name is read-only. A group’s own name is
what the hand asked for, so writing @hand.zone is refused.
Reading the trace
Section titled “Reading the trace”Every deal and peek emits a trace event listing each card the engine considered and the
reason it was kept or dropped: dealt, capped (ranked but outside the hand’s slots),
cooldown, deck-gate, tags, condition, priority, claimed,
claimed-elsewhere (another playthrough holds the world’s copies) and taken (a shared
one-shot spent, by anyone, for everyone). The Board’s Not
listed, and why fold shows it. In your game, subscribeTrace streams it and a retained log
keeps it, as Dev tools describes.
Open source under the MIT licence, made by Ian Thomas.