Battle Rules
Nine fields on the encounter decide the battle's rhythm: how many cards flow, where energy comes from, what survives the turn boundary, and how fast resolution plays out.
For encounter authors tuning pacing and difficulty. Every field lives in Workbench > Encounter, inside the Battle Rules foldout.Battle rules live on the encounter, not on the player unit and not in a global config. Two encounters can share the same player and the same enemy roster yet play completely differently, because one draws five cards and resets armor every turn while the other draws three and lets armor stack.
Edit them in Workbench > Encounter, in the Battle Rules foldout. The preview column repeats the full ruleset as chips, so a reviewer can read an encounter's rhythm without opening a single field:
The nine rules
| Rule | Default | Meaning |
|---|---|---|
| Starting Hand Size | 5 | Cards drawn at battle start. Minimum 0. |
| Draw Per Turn | 5 | Cards drawn at the start of every turn from turn two onward. Minimum 0. |
| Max Hand Size | 10 | Hand cap. The turn draw discards what it cannot fit; draw effects stop early instead. Minimum 1. |
| Starting Energy | 0 | Per-turn energy refill override. 0 means the player unit's Base Energy applies. |
| Card Reward Count | 3 | Card candidates offered on victory. The runtime treats values below 1 as 1; removing the Reward Deck is what disables the offer. |
| Armor Decay | ResetOnTurnStart | ResetOnTurnStart clears each unit's armor at its own turn start; Persist keeps it. |
| Hand Discard | DiscardOnTurnEnd | DiscardOnTurnEnd discards the hand at the player's turn end (cards with Retain stay); Persist carries the hand over. |
| Enemy Intent Display | Full | How much of the enemy's next move the player sees: Hidden, IconOnly, or Full. |
| Animation Gap | 0.28 | Pause between resolution steps, in seconds. Minimum 0. |
These are gameplay rules, not cosmetic preferences. Anyone opening the encounter should be able to scan the chips and predict the basic feel of the fight. All twelve demo encounters, from The Threshing Field to Pyre of the Ash-King, run this exact default set; their difficulty comes from lineups and behavior graphs, not rule tweaks.
Draw and hand
Three fields work as one system:
| Field | Design question it answers |
|---|---|
| Starting Hand Size | How many choices does the player have on turn one? |
| Draw Per Turn | How many fresh choices arrive each turn after that? |
| Max Hand Size | How much can the player hoard before draws stop landing? |
At runtime the numbers behave like this:
- Turn one deals Starting Hand Size cards and nothing else; Draw Per Turn starts on turn two.
- Cards with the
Innatekeyword jump to the front of the opening draw. - When the draw pile runs dry mid-draw, the discard pile reshuffles into it automatically.
- A draw past Max Hand Size never lands in the hand, but the two draw paths overflow differently. The turn draw (Starting Hand Size and Draw Per Turn) flips the cards it cannot fit from the draw pile straight into the discard pile, firing each card's discard trigger on the way. A Draw Cards effect stops early instead, and the leftover cards stay in the draw pile, which looks exactly like a broken draw node until you count the hand.
- Cards added to the hand by an effect (an Add Cards node, for example) also respect the cap: past it they land in the discard pile.
A status behavior can modify the per-draw count through the Draw Count Hook entry and the hand cap through the Hand Size Hook entry. When live numbers disagree with the rules, check the unit's statuses in the Monitor before doubting the encounter.
Energy
Starting Energy exists for encounters that intentionally bend a class's energy budget.
| Value | Result |
|---|---|
0 | The player unit's Base Energy is the per-turn refill. Pyre of the Ash-King does this, so the Archmage plays with his native 4. |
| Positive number | This encounter refills to the override instead. |
Energy is a refill, not income. At every player turn start the pool is set to the resolved value; whatever went unspent last turn is gone. A status can adjust the refill through the Energy Per Turn Hook entry.
Leave the field at 0 while testing a class so the player unit stays the single source of truth. Reach for the override in tutorial fights, gimmick battles, or difficulty variants of the same encounter.
What survives the turn boundary
Armor Decay and Hand Discard together define the turn rhythm:
Armor decay applies to everyone, each at their own moment: the player's armor resets when the player turn starts, and each enemy's armor resets just before that enemy acts in the enemy phase. ResetOnTurnStart gives you the familiar roguelike block loop where defense is a per-turn decision; Persist suits shield-stacking designs. A status can also intercept the reset through the Armor Reset Hook entry and keep some or all of the block.
Hand Discard applies at the player's turn end. Under DiscardOnTurnEnd, every card goes to the discard pile except cards carrying the Retain keyword. Under Persist, the whole hand carries over and becomes a resource the player manages across turns. Cards with the Ethereal keyword exhaust at turn end no matter which rule is active.
A card that says "keep this for next turn" reads as broken in an encounter that discards the whole hand at turn end. Whichever persistence rules you pick, make sure the card wording in that encounter agrees with them.
Enemy intent
Enemy Intent Display decides how much of an enemy's next move the player sees. Enemies pick their next actions at battle start and again at the end of every enemy phase; this rule shapes what that broadcast contains.
| Value | What the player sees |
|---|---|
Hidden | Nothing. No intent is broadcast at all. |
IconOnly | The intent icon without numbers. |
Full | Icon plus numbers. |
Full numbers are a live preview, not the raw graph value: an attack runs through the attacker's damage modifiers and the player's own defensive modifiers before it is shown, so an Ashen Hierarch attack lowered by Weak displays the reduced value.
Keep the rule on Full while building enemies. You need to see what the enemy plans in order to verify its behavior graph. Reduce the information only when the game design deliberately withholds it.
Rewards
Card Reward Count and the encounter's Reward Deck work as one system, and the deck holds the on/off switch:
| Setup | What victory offers |
|---|---|
Deck with cards, count 3 | Three card candidates. |
Deck with cards, count 0 | One candidate anyway. The runtime treats any count below 1 as 1. |
| No deck, or an empty one | No card candidates. |
Two details matter before you stock the deck. Copies on a deck entry weights the roll, so an entry with three copies is three times as likely to be offered. And the same entry is never offered twice in one victory, which also caps the candidate count at the number of entries in the deck.
The deck itself is configured in the encounter's Reward Deck section, covered on Encounter Authoring.
Animation gap
Animation Gap is the encounter's pacing value for the battle presentation: the pause left between resolution steps, measured in seconds. The default 0.28 keeps resolution feeling responsive while letting damage, status, and effect beats read as separate moments, and every demo encounter ships with it unchanged.
Treat it as a dial for the whole fight. A large value slows every resolution in the encounter, so when only one effect feels off, tune that effect's presentation instead.
Common mistakes
| Symptom | Likely cause |
|---|---|
| First hand is too small | Starting Hand Size is lower than expected. Turn one does not add Draw Per Turn on top. |
| Draw effects seem to do nothing | The hand sits at Max Hand Size, so the Draw Cards effect stops early and the cards stay in the draw pile. |
| Cards jump straight to the discard pile at turn start | The hand was full; the turn draw discards what it cannot fit. |
| A created card landed in the discard pile | The hand was full when an effect added the card directly. |
| Energy ignores the player unit | Starting Energy is set to a positive override. |
| Armor disappears every turn | Armor Decay is ResetOnTurnStart. |
| Hand empties at end of turn | Hand Discard is DiscardOnTurnEnd and the cards lack the Retain keyword. |
Victory offers a card despite a count of 0 | The runtime minimum is one candidate. Clear the Reward Deck to offer none. |
| No rewards after victory | The Reward Deck is missing or empty. |
Battle rules are part of encounter design, and the chips in the preview keep them visible. Resist the urge to hide core battle rhythm inside custom code where no reviewer will find it.