dirac¶
dirac is a second Magic rules engine, written so that tree search and self-play can copy and step a game millions of times. This section is for engine and ML readers, and for bot authors who want to know what a dirac game is, what it supports, how it is checked and where the speed comes from.
The source is in dirac/, and
dirac/README.md is the guide for driving it from Go.
The commands below need the card corpus and make dirac-tables (Install and build).
Why a second engine¶
gorge is built to be right for every card it can play, at up to eight seats, with a hash-chained event log
(Events and replay). That shape costs time: a state.Game is an arena of objects
with slices and maps, so a clone is a deep copy, and every state change goes through an event.
A search wants the opposite trade. Each simulation copies a position, plays a few dozen decisions and throws the copy away. If everything variable-length about the cards lives in a read-only table, the game itself can be one flat value and one buffer sized to that table:
set, _ := cardset.ByName("fdn")
tbl, deckA, deckB, _ := set.Matchup(listA, listB)
s := dirac.NewConfig(tbl, deckA, deckB, seed, dirac.Config{Mulligans: 2})
for {
d := s.Step() // run to the next question
if d.Kind == dirac.DkNone { // the game is over
break
}
s.Apply(d.Options[0]) // answer with any of d.Options[:d.N]
}
over, winner := s.Terminal()
Copying a mid-game FDN position takes about 76 ns and allocates nothing, and a transition takes about 3.1 µs, also allocating nothing, measured 2026-11-11 (Performance).
What it supports¶
A card moves through three states. Only all three together are a claim about play.
| State | Meaning | Where it is recorded |
|---|---|---|
| Lowered | dirac/kgen read every rules parameter of the card's compiled IR and turned it into dirac/kop ops |
the build ratchet, and the lowered column of dirac/docs/support.md |
| Not refused | the card isn't on the short list of cards named as playing wrongly, each with a reason and a game that shows it | dirac/support/refused |
| Evidenced | clean lockstep games of the evidence corpus played the card at least three times and used every ability it has | dirac/support/evidence |
A supported card is all three: lowered, not refused by name, and clean in the lockstep games of the evidence
corpus. dirac/docs/support.md is generated from the
same lists and gives the count corpus-wide and per Standard set, with the games behind each pool, and Card support by set
renders it. kgen -supported <pool> answers for each card of one pool:
A game plays supported cards only. Matchup refuses a deck holding any other card and names the card, so a lowered
card with no evidence, reported as unverified, isn't dealt. Only a run that asks for them plays unverified cards:
the lockstep runs that earn evidence, or a Go caller through cardset.AllowUnverified.
"Supported" says what the evidence games saw, and no more. It doesn't say a card is right, because dirac shares gorge's bugs: lockstep can't see a mistake both engines make (what lockstep proves). It doesn't cover a pair of cards no evidence game put together, so sweeps and census pairs outside the evidence corpus can still find a difference on a supported card.
How far lockstep agrees¶
gorge is the engine dirac is checked against (Verification). The state of that check on
2026-11-08 at fc2be1aabe, with random answers. The rows are make dirac-slices, which any clone
with a corpus can run, and CI runs on every change. A slice is the first 1,500 pairs of a pool at seed 1.
| Run | Games | Clean | Divergent | Unmodelled stalls | Capacity stalls | Refused pairs |
|---|---|---|---|---|---|---|
FDN slice, -surface autopay |
1,494 | 1,492 | 0 | 0 | 2 | 6 |
FDN slice, -surface full |
1,494 | 1,491 | 0 | 0 | 3 | 6 |
BLB slice, -surface autopay |
1,500 | 1,500 | 0 | 0 | 0 | 0 |
BLB slice, -surface full |
1,500 | 1,500 | 0 | 0 | 0 | 0 |
A refused pair holds a card dirac doesn't support, so it never starts a game. A capacity stall is a declared limit, reached with no disagreement up to that point; it counts against the run and isn't clean. Games beyond these slices, on pairs the evidence corpus never put together, can still diverge, and each that does is open work on one engine or the other.
Scope¶
dirac does less than gorge on purpose.
| Limit | Value | Past it |
|---|---|---|
| Players | exactly 2 | not representable |
| Deck size | 100 cards a seat (MaxDeck, a Commander deck's size), and a sideboard of 15 (MaxSide) |
rejected at setup |
| Card instances, both decks plus tokens and copies | 224 | the game stalls (board) |
| Battlefield | 112 permanents | stalls (board) |
| Stack | 48 entries | stalls (stack) |
| Triggered abilities waiting | 48 | stalls (pending) |
| Delayed triggers | 32 | stalls (delayed) |
| Attack or block options in one declaration | 512 | stalls (options) |
| Triggers resolved in one turn | 2,000 | stalls (loop, an endless mandatory loop, CR 104.4b) |
Stalls are named. A game dirac can't continue correctly ends as a draw, Terminal reports (true, -1)
and StallReason gives one of about a hundred named reasons. The names fall into two classes, and every
reason must be in one or a test fails:
- Capacity: a fixed array or budget ran out, and gorge has no such limit. The game was right up to there. These are declared limits, so they count as limits and not as failures.
- Unmodelled: gorge does something at this point that dirac doesn't. These are rule gaps, and a strict lockstep run fails on them.
Nothing is dropped silently: a full pool stalls by name, and an op the interpreter lacks panics by name.
The engine has no event log, no per-seat view, no concede and no manual mana. A cast is offered when
untapped sources and the pool can pay, and it is paid by a planner that mirrors gorge's auto-pay planner. A server
reaches it through dirac/adapter, which derives a game's log and views from its positions
(Serving dirac).
How it relates to gorge¶
dirac is not a second source of rules truth. Its cards are generated from gorge's compiled card IR, its rules code follows gorge's (including gorge's decision grammar and random numbers), and a lockstep harness plays the same game through both engines. When they disagree, the question is which one is wrong under the Comprehensive Rules (CR). If gorge looks wrong, the evidence is checked against XMage and Forge and the fix lands in gorge. Several differences so far were gorge's bugs.
The engine imports nothing from gorge. Only the tools that meet gorge do, and the adapter, which reads gorge's view and decision types and never its rules engine:
flowchart LR
subgraph d["dirac"]
dirac["dirac<br/>State, Step, Apply"] --> kop["dirac/kop<br/>ops, Table"]
cardset["dirac/cardset<br/>loads binary tables"] --> kop
feat["dirac/feat<br/>network inputs"] --> dirac
hbot["dirac/search/hbot<br/>heuristic bot port"] --> dirac
oracle["dirac/oracle<br/>lockstep, kfuzz"] --> dirac
kgen["dirac/kgen<br/>card generator"] -.->|writes tables| cardset
adapter["dirac/adapter<br/>serves a game to a host"] --> dirac
end
subgraph g["gorge"]
engine["engine/...<br/>rules, cards, state"]
end
oracle -->|"runs gorge as the reference"| engine
kgen -->|"reads the compiled IR"| engine
adapter -->|"implements engine/game"| engine
| gorge | dirac | |
|---|---|---|
| State | state.Game: an object arena with slices and maps |
one State of under 24 KiB plus one small table-sized buffer (State) |
| Mutation | events folded by events.Apply into a hash chain |
Apply(action) writes the value directly, with no log |
| Clone | Engine.Clone, tens of µs and hundreds of KB |
CopyFrom, tens of ns and no allocation |
| Players | up to 8 | exactly 2 |
| Cards | every Forge script is compiled; a card is playable when every primitive it names is implemented (Card support) | supported cards only (What it supports) |
| Comparing two games | the chain head: the same head means the same history | its Projection (fixed arrays): equal positions project ==; two States in the same position may differ in bookkeeping |
| Decisions | 13 kinds, multi-select answers | 8 kinds, every answer a single pick (Step and Apply) |
| Checked by | golden replays, census ratchets, XMage, Forge and Oracle-text scenarios | lockstep against gorge at every decision (Verification) |
| Used for | hosting games, every card, the reference | search and self-play; two-seat tables on FDN and BLB limited decks |
dirac can also run as a stdio SpellBench v2 engine: dirac/cmd/sbv2dirac plays the game with dirac as the
authority and a gorge engine following in lockstep, which builds the observations and candidates. A
disagreement ends that game as engine_contract_failure:divergence. See
SpellBench v2.
Pages in this section¶
| Page | What it covers |
|---|---|
| State | the hot, core and cold layout, object identity, change marks, the size bar, the Projection |
| Step and Apply | the control-state machine, Decision and Action, decision kinds against gorge's, the RNG |
| Cards | the op vocabulary, how kgen lowers gorge's IR, refusals, binary tables, evidence, layers |
| Verification | the lockstep oracle, what it proves and what it doesn't |
| Search and bots | what dirac offers a search, the heuristic bot and mulligan ports, the network input encoder |