yalotrp

Chapter 8

Packs

Logic as JSON: the pack format, names and ids, and sharing your versions.

The format

A pack is a JSON file: { "version": 1, "name": "My pack", "cards": { ... } }, with one entry per card. An entry is a list of abilities, as the Logic window shows them: each has a when and its steps under do.

`json "Ever Vigilant": { "abilities": [ { "when": "played", "do": [ { "targetZone": "slots", "zone": { "action": "search", "types": ["Ally"], "states": ["exhausted"] } }, { "targets": ["@picked"], "state": { "action": "ready" } }, { "state": { "moveTo": "pdiscard" } } ] } ] } `

when is a named moment (revealed, played, drawn, engaged, travelled, discarded, shadow, stage-revealed: "when": "played" is a change from anywhere to the play area), change (with from, to, whenTokens, for any other change), event (with on, of, while, and response for a Response), step (with step: "Phase/step", such as "Refresh/end" or "Setup/start"), action (with tooltip, requires, limit, and on for a Response), rule (one step, the rule) or routine. The steps have no ids in a pack. Fields the site does not know are dropped when a pack is read; an item it cannot read (an unknown step, or an ability with no when it knows) is skipped with a warning.

The older form, with steps, triggers, manual groups and rules lists, is still read (the packs that ship with the site use it); Copy and Export write abilities.

Names and ids

A card is keyed by its name when every printing of that name has the same text, and by its id otherwise. An id entry wins over a name entry, so give a printing with other text an entry of its own (an empty one when it should have no logic).

Importing and exporting

The Account menu's Logic settings dialog imports a pack (its cards become your versions) and exports yours. Under Engine logic it also has the engine's own logic for every card (Pay for cards played, Ask to flip the stage, Victory display, Surge, Doomed, Time, Guarded, Ambush, Peril, Enters play exhausted, Indestructible, Toughness, Secrecy, Refill the encounter deck, Boarding, Uncharted, Loot, Deep, Aflame, Burn, Hinder, Spectral, Attachment limits), to switch on or off, the same switches as in Gameplay settings. Save as default in a Logic window writes one card's version. To get back to the logic that ships with the site, remove your version in the dialog.

The engine's routines

The questions the engine logic asks, what it does for the keywords, and four of the phases' auto actions are routines in a pack that ships with the site (engine.json): @Pay for cards played (the pay window), @Play cards (the plain Play / Cancel, with Pay for cards played off and the confirmation Play cards on), @Flip stage (the question and, on Yes, the flip to side B), @Surge (reveal the top card of the encounter deck, with no question: the card it reveals asks "Surge reveals {self}, resolve?"), @Doomed (raise each player's threat by the card's printed Doomed, "game": { "threatFrom": "doomed" } with "player": 0), @Time (put the card's printed Time X on it in time counters as it enters play, "tokens": { "mode": "add", "kind": "time", "amountFrom": "time" }), @Time refresh (at the end of each Refresh phase, take one off each card with Time that has any) and @Guarded (discard from the top of the encounter deck until a card of the guarded kind, which goes to the staging area unrevealed, "zone": { "action": "move", "moveTo": "discard", "until": { ... }, "matchTo": "staging" }, then attach the objective to it, "ifFound": true, "targets": ["@picked"], "state": { "attach": true }), @Ambush (an engagement check against the enemy, "state": { "engageCheck": true }: it engages the first player in turn order whose threat is at least its engagement cost), @Peril (a notice on the card, with more than one player) and @Enters play exhausted ("state": { "action": "exhaust" }). A pack of yours with an entry of the same name changes the question for every card, as an entry for a card does:

`json "@Flip stage": { "routine": [ { "prompt": { "title": "Turn {self} over?", "showCard": true, "choices": ["Flip", "Not yet"] } }, { "ifChoice": 1, "state": { "action": "side-b" } } ] } `

The auto actions are @Gain resources (a resource token on each hero: a headless search of the heroes, then "tokens": { "mode": "add", "kind": "resource" } on @picked), @Draw cards (draw from the player deck), @Raise threat ("game": { "threat": 1 }) and @Discard shadow cards (a headless search of the engaged enemies, then "state": { "discardShadow": "all" }). Each runs at its step for every player in turn, with that player's cards in view, so write it for one player. Its log lines start with the phase ("Resource phase: drew Gandalf."). The switch in Gameplay settings' Auto actions still turns the step off. An entry of your own is a house rule, such as drawing 2 cards each round:

`json "@Draw cards": { "routine": [ { "targetZone": "pdeck", "zone": { "action": "draw", "n": 2 } } ] } `

An extra resource is "amount": 2 on @Gain resources's tokens step, and an empty @Raise threat leaves the threat alone. A routine that asks something (a prompt first) opens its window as the step is reached. The Sailing test runs @Sailing test, which a pack can replace. Ready all cards, Archery, passing the first player token and switching to the first player have no routine: they are only switched on or off.

The board still fills in what only the game knows: the card's printed cost on the pay window, Play for a card that costs 0, X, the card's play only if, and the kinds of card that guard an objective (the types of @Guarded's until: an enemy or a location, or the one its "Guarded (enemy)" names). An empty routine asks nothing (an empty @Surge or @Doomed does nothing). @Doomed, @Guarded, @Time, @Enters play exhausted and @Peril run before the card's own triggers, @Ambush and then @Surge after them; none is dropped when the player answers No to the card's "Resolve {self}?", since they are keywords and not its When Revealed.

Printed Surge, Doomed X, Guarded and Time X are not written in a card's logic: the engine does them for every card that has them printed (Time: placing the counters and taking one off each round; what the card does when the last one is removed is its own logic, often an Action for the player to click). A card's logic writes only what its text gives it ("this gains surge if ...", "Followed by Night gains surge"): a reveal after its "Resolve {self}?" question. A card whose own logic still reveals from the encounter deck as it is revealed (a trigger From the encounter deck that reveals, the way packs once wrote surge), or raises the threat as it is revealed, or places time counters on itself (in a trigger), or takes one off at the end of the Refresh phase, or attaches itself to a guard of its own, does it itself, and the engine leaves that card alone, so it never surges twice. A card with Time X ("X is 5 times the number of players") places its own counters. The shipped packs had Surge, Doomed and Time written out by hand; scripts/strip-keyword-logic.mts took those copies out (no pack had written out Guarded). The victory display question is the board's own window, so it has no routine: it is only switched on or off. So are Indestructible (no Destroy), Toughness (less damage, a line of the Combat panel), Secrecy (a lower cost in the pay window) and Attachment limits ("cannot have attachments" refuses an attach; a third Restricted attachment gets a log line): they are checks of the engine's own moves, not routines. Some scenario keywords are routines in packs of their own that the engine calls the same way: @Boarding, @Uncharted, @Loot, @Deep and @Aflame, and @Burn, which a card calls ("resolve all burn damage") and the engine fills in with the total Burn of the locations in play (Hinder and Spectral are checks, with no routine). @Assign damage is a shared routine of the same kind for "assign X damage among characters": set the counter assign to X, then call it with callArgs assignQuesting (1: only characters committed to the quest) and assignExhaust (1: exhaust each damaged character); the player picks a character for each point of damage in turn. Printed Enters play exhausted is not written in a card's logic either; the copies the player-card packs had were taken out the same way.

Checking a pack

The headless harnesses in scripts/harness/ run a pack's cards through the engine with no browser (see its README): every trigger, search, question and manual action, answered by the script, with a transcript of what happened.