State¶
A dirac game is one Go value, dirac.State, plus one small buffer it owns. This page shows what is inside
it and why, for readers who want to know what a cheap clone costs and what it rules out.
Sizes were read on 2026-11-08, with Go 1.26.3 on linux/amd64, by a scratch test printing
unsafe.Sizeof of each part. dirac's own TestStateSize logs the total.
Three parts¶
type State struct {
stateCore // the rules state: fixed-size, no pointers
perms [MaxPerm]perm // the battlefield, hot, copied only as far as it is used
cold coldArrays // arrays only some card tables need
pool *ForkPool // the States that rules probes run on
}
| Part | Bytes | What it holds |
|---|---|---|
stateCore |
12,952 | the rules state, below |
perms |
6,272 | 112 battlefield slots at 56 bytes each |
cold headers and pool |
296 | slice headers and a pointer; the arrays themselves are in one buffer |
State, total |
19,528 |
The core and perms hold no pointers, maps, slices, strings or interfaces. Every collection is a fixed array
and a count, so three things follow:
- A clone is one or two memory copies.
dst.CopyFrom(src)assigns the core, copiespermsup topermHi(one past the highest slot this game has used), clears any slots above that in the destination, and copies the cold buffer. It allocates only if the destination's buffer is too small (Performance has the cost). - The garbage collector scans almost nothing. The cold buffer is a
[]uint64, which it doesn't look inside, and the only pointers in aStateare in the cold headers and the fork pool. - Positions compare directly.
SameGamecompares the core,permsand the buffer.Projection, below, compares with==.
An assignment of a State would share the cold buffer, so a noCopy field makes go vet reject one.
What's variable-length about the cards (definitions, filters, op programs) is in the read-only card table
(kop.Table, see Cards). A State names its table by a 16-bit index.
The core¶
| Region | Bytes | Contents |
|---|---|---|
| header | about 16 | turn, step, active player, priority holder, passes, control state, config bits, result |
| RNG | 168 | the PCG state, draw count, chance record (RNG) |
| players | 884 | two records: life, zones, mana pools |
| objects | 1,792 | 224 card instances at 8 bytes: card, zone, slot, version, flags |
| layer stamps | 224 | a layer timestamp per battlefield slot |
| slot masks | about 480 | occupied, by controller, per event kind, static sources |
| stack | 1,920 | 48 entries at 40 bytes (MaxStack) |
| pending triggers | 864 | 48 records at 18 bytes (MaxPending); the trigger-order round's 48 picks follow |
| delayed triggers | 192 | 32 records (MaxDelayed) |
| resolution in progress | 178 | the suspended program and its position |
| change marks | 32 + 224 | one bit per object, one stamp per object (below) |
| generated-table extension | the rest | continuous effects, last known information, per-turn history and other pools |
Hot and cold¶
Moving an array out of the core changes which tables pay for it:
permsstays inline. Reaching it costs no extra load, and most of a battlefield is empty, soCopyFromcopies only the slots in use.- Cold arrays are per table. These are arrays only some tables' cards reach: exiled-with links,
attacker groups, this turn's zone entries and spell pushes, held discards, mechanic masks. A
coldLayout, computed once per table, gives each one its length, and zero when no card in the table can write to it. Each array is a view into one[]uint64, so aStatemakes one allocation for them all. - A cold array is registered by its own feature. The file that owns it declares
var coldX = newCold[T]("x", need), whereneedsizes it from the table's prep, and reads it throughcoldX.of(s). The registry orders the arrays itself, widest alignment first and then by key, so no shared list names them and two features that add one never touch the same lines. A hot path that must not go through the layout binds acoldArraysview (.view), which costsStatea slice header; a per-slot array marks itself.perSlotand is cleared when its slot takes a new permanent.
The mechanic masks show the idea at its smallest. A mask that almost no pool uses (goaded, monstrous, suspected and so on) gets an index only if a card in the table uses it. Any other mechanic's index is past the end of the mask array, so the bounds test is also the off switch and the unused mechanic touches no memory.
A full cold array stalls by name, and an empty one counts as full. A table that can't write to one never gets there, because its size follows the same flags that switch its writers on.
A rules probe (does this option leave a legal play?) runs on a fork from the ForkPool, one State per
nesting depth. NewForkPool makes eight, past the deepest nesting measured in random play, so a warmed search
doesn't allocate for them. All States sharing a pool must run on one goroutine.
Objects and slots¶
An Obj is a uint8 card instance index. Seat 0's deck comes first in deck order, then seat 1's, then tokens
in creation order, the same relative order as gorge's object IDs. An object keeps its index across zones.
A permanent also has a slot, its index into perms. Battlefield loops walk bitmasks (slotMask, two 64-bit
words) rather than scanning 112 records: occ for occupied slots, ctrlM[p] by controller, one mask per
kind of event a trigger can watch, statM for slots with a static ability. Finding the attackers or the
sources that can react to an event is a few word operations.
Each object has a version, bumped on every zone change. A stack target stores the object and its version, so a target that left and came back no longer matches and is illegal (CR 400.7). An ability's source works the same way. An ability that must see a creature as it last existed snapshots it into the last-known-information pool when the trigger is queued or the cost is paid.
Change marks¶
A search copies a position many times, and most objects in a copy match the base. Two readers use that: the network input encoder and the search's evaluation cache.
chgis a bitset of 224 objects (four 64-bit words). A write to an object or its slot marks its bit, bumps a touch counter and stamps the object.SetEpochclears the marks and names the current position as a base. A copy carries the epoch and the marks, so an unmarked object in any copy is field for field the base's.ObjHashis a pure function of an object's fields, so two positions holding the same object hash the same.
Marks may over-report and cost a recomputation, but never miss.
The size bar¶
Every byte of the core is copied on every clone, so its size is a decision rather than a side effect.
Statemust stay under 24 KiB.TestStateSizefails abovemaxStateBytes(dirac/kernel_test.go), and moving the bar is a deliberate decision, measured against the bench cost of the larger copy.- The table holds what's printed and
Stateholds what changes. No field inStatebelongs to one card. - Per-slot bytes are expensive. One byte on
permcosts 112 bytes ofState, one onobject224. Rare state goes in a pool sized for the worst case seen in play, or in a cold array. - A mechanic that's off costs one branch. Each block is gated by a flag computed once per table, and the code behind the gate stays out of line.
The Projection¶
Project writes a dirac.Projection of 41,272 bytes: a comparable view of a whole position, for tools and tests.
| Part | Contents |
|---|---|
per object, in Obj order |
card, owner, controller, zone, position in the zone, token bit, tapped, attacking, blocking and summoning-sick flags, damage, counters, derived power and toughness, attached-to, blocked attacker, attacked defender |
| derived characteristics, per object | types, subtypes, colours and keywords after the layer system |
| per seat | life, lands played, mana pool, zone sizes |
| the stack, bottom to top | kind, source, card, ability index, controller, targets, modes, X |
| the rest | turn, step, active player, priority holder, RNG draw count, game over, winner |
Every field is a fixed array, and equal positions project equal. A position's stack matches gorge's at the points that matter for lockstep: a spell goes on the stack after its X and cost picks and before its modes and targets, an activated ability after its targets and costs, and a triggered ability before its targets. dirac also splits gorge's combat-damage step into a first-strike step and a regular step, which the oracle maps back.
ProjectDelta and ProjectSince update an existing projection from the change marks. The oracle compares its
own canonical projection, built from both engines (Verification).