Step and Apply¶
dirac has no event loop and no host. A game is driven by two methods on the State value: Step runs the game
forward to its next question, and Apply answers it. This page is for anyone who wants to know what a driver, a
bot or a search would write against dirac, and how its decisions compare with gorge's
Game loop and decisions.
The loop¶
var d dirac.Decision
s := dirac.NewConfig(tbl, deckA, deckB, seed, dirac.Config{Mulligans: 2})
for {
s.StepInto(&d) // Step() returns a copy; StepInto fills d in place
if d.Kind == dirac.DkNone {
break // game over
}
s.Apply(d.Options[pick(&d)]) // must be one of d.Options[:d.N]
}
over, winner := s.Terminal() // winner -1 is a draw
| gorge | dirac | |
|---|---|---|
| Run to the next question | Advance() emits events until a decision is pending |
Step() or StepInto(&d) writes the value until a decision has options |
| The question | decision.Decision: kind, player, labelled options, Min/Max |
Decision: kind, sub-kind, player, N options, each a 32-bit Action |
| The answer | an Intent of option indices, validated against the decision |
one Action, not re-validated: the caller is trusted |
| Answers per decision | a subset | exactly one pick; a multi-select becomes a sequence of picks |
| Recorded | the intent is appended to the log | nothing; Decisions counts the answers |
StepInto does two things to each decision before returning it. It sorts the options into a canonical order,
so a policy's choice doesn't depend on storage order. By default it also answers a decision with one option in
place and counts it in State.Skipped, chiefly the priority rounds where passing is the only legal action.
Config.NoElide turns that off, as the oracle does.
The control-state machine¶
Step and Apply both dispatch on one byte, State.ctl, which says where the game is waiting. Step does the
rules work for the current state (turn-based actions, state-based actions, triggers, resolving the top of the
stack) until a state produces a decision. Apply performs the answer and moves on. Everything needed to resume is
in the value (the entry being built, a suspended program's position), so a game can stop in the middle of a cast
or a resolution with no Go stack to save.
stateDiagram-v2
[*] --> MullDeclare: Config.Mulligans > 0
[*] --> StepBegin: no mulligan round
MullDeclare --> MullBottom: every seat kept
MullBottom --> StepBegin: bottoming done, turn 1
StepBegin --> Priority: turn-based actions of the step
Priority --> PlaceTriggers: triggers pending
PlaceTriggers --> Build: trigger needs modes or targets
PlaceTriggers --> Priority: all pushed
Priority --> Build: cast or activate
Build --> Priority: on the stack, costs paid
Priority --> Resolve: both passed, stack not empty
Resolve --> Priority: resolved
Priority --> StepBegin: both passed, stack empty
StepBegin --> Attackers: declare attackers
Attackers --> Priority: AkDone
StepBegin --> Blockers: declare blockers
Blockers --> Priority: AkDone
StepBegin --> Divide: combat damage, a division is asked
Divide --> Priority: damage dealt
Priority --> Legend: legend rule
Legend --> Priority: kept one
StepBegin --> CleanupDiscard: cleanup, hand too big
CleanupDiscard --> StepBegin: next turn
Priority --> [*]: game over
The turn structure follows gorge's engine/rules exactly, because lockstep compares every priority decision. Untap
and cleanup pose no priority. Every other step runs a full priority round even when nothing can happen. The starting
player skips the turn-1 draw. With no attackers declared the game jumps from declare attackers to end of combat.
State-based actions run after each combat-damage pass.
Decision and Action¶
A Decision is a kind, a sub-kind, a player and up to 512 options (MaxOptions), 2,056 bytes in all, which is why
StepInto exists. An Action is one packed uint32:
source and target are Obj indices. Bytes 0xF0 and up in a target are the two players and "none", which is why
MaxObj can't pass 240. MakeAction, Kind(), Source(), Target() and Mode() encode and decode it. Each action
kind says which fields it uses: AkCast's mode bits name the cast route, for example kicked, flashback or
a play permission. A granted activated ability is AkActivate with the creature as source, the granting permanent
as target and 0x80 | index as mode.
Decision kinds against gorge's¶
gorge has 13 decision kinds (The 13 decision kinds), and dirac has 8
plus DkNone. gorge's multi-selects and several small kinds become DkChoose with a Sub, and every answer is one
pick.
| gorge kind | dirac | How it is posed |
|---|---|---|
priority |
DkPriority |
pass, land plays, casts, activations, special actions. No mana abilities (costs are paid by the planner) and no concede |
target |
DkTarget |
one pick per target; a multi-object slot is one pick per object, closed by AkDone once its minimum is met |
attackers |
DkAttackers |
one AkAttack per attacker and defender, closed by AkDone; only picks that leave the declaration completable are offered |
blockers |
DkBlockers |
one AkBlock per blocker and attacker, closed by AkDone; a menace attacker that fewer than two creatures could block is never offered |
modes |
DkModes |
the mode pick; gorge's effect discards, posed as modes, become DkChoose/ChDiscard |
choose |
DkChoose + Sub |
X, cost picks, the legend rule, combat damage division and the other generic asks |
trigger_order |
DkTriggerOrder |
one AkOrder per trigger, every one posed; the group is pushed in pick order |
trigger_optional |
DkChoose/ChOptional |
mode 1 yes, 0 no |
mulligan |
DkMulligan, then DkChoose/ChBottom |
keep or mulligan, then one bottoming pick per card |
arrange |
DkChoose/ChArrange |
scry and surveil: each pick is the next card from the top, closed by AkDone |
replacement |
DkChoose/ChGenReplOrder |
the CR 616.1 order among competing replacement effects |
starting_player |
not posed | the toss winner takes the first turn, as with gorge's plain rules.New |
commander_zone |
not applicable | no Commander |
Generated card tables raise further Sub values (a hybrid pip's colour, a pile split, a card to cast free). A bot
that only understands the common ones can still answer the rest, because every option is a complete Action.
RNG¶
gorge's engine RNG is math/rand/v2's PCG seeded with (seed, seed ^ 0x9e3779b97f4a7c15), drawn through
rand.Rand.IntN, with a counter of every draw. A rand.Rand holds an interface, which the core of State may not
contain, so dirac keeps the bare PCG in the value and reimplements IntN with the same reduction. The draw order
also matches: the coin toss first, then each seat's Fisher-Yates shuffle of its whole library in seat order, then seven
cards. A London mulligan puts the hand on the library, shuffles and draws seven, then bottoms one pick per card.
That is what makes lockstep possible:
- Same seed, same game. With the same decks, seed and answers, both engines deal the same hands and resolve every random effect alike, so they can be compared position by position.
- An early alarm. The draw count is in both projections. If one engine draws a random number the other doesn't, the next comparison fails on that field instead of many turns later when a different card shows up.
- Replay across engines. With
Config.RecordChance, dirac records the bound of every draw andChanceTranscriptrecomputes the values. The oracle forces those outcomes on gorge, so a game dirac played alone can be re-executed in gorge and checked (Verification).
A search re-seeds a simulated world with ReseedChance and re-deals what the searching seat can't see. Those are
deliberate departures from the real game's stream, made only on copies.
Configuration that changes behaviour¶
The defaults are what a search wants. The Gorge* switches exist so that the oracle can match gorge's option surface.
| Switch | Off (default) | On |
|---|---|---|
Mulligans |
0: no round | the London mulligan limit |
NoElide |
a single option is answered in place | every decision is posed |
AutoDivide |
damage division among blockers is asked | divided automatically (lethal in block order, the rest to the last), which cuts branching |
ArrangeRestOrder |
the rest of a scry or surveil goes in library order | the answerer orders them too, for a host whose wire carries that order |
GorgeAutopaySurface, GorgeUnpriced, GorgeLowering |
every castable spell is offered and paid | casts gorge's payment planner doesn't price are offered only the way gorge reaches them |
GorgeAltAdd, GorgeMustAttack |
payable parts only; must-attack creatures are declared up front | posed the way gorge poses them |
RecordChance |
no record | every random draw is recorded for cross-engine replay |