Expressions (ƒx) — author values that compute themselves

What this is, in one minute

A ƒx value is stored as a two-key object instead of a number:

{
  "expr":     { "floor_div": [ { "count_cards": { "zones": ["deck", "discard"], "owner": "player" } }, 10 ] },
  "authored": { "level": "formula", "preset": "count_per_n", "params": { "zones": "deck, discard", "n": 10 } }
}

• expr — compiled JSON Logic. The engine and evaluator read only this.
• authored — what the form (or the AI) actually wrote: a preset name plus its parameters. The form repopulates its dropdowns from this, and the server recompiles expr from authored on every save, so the two can never disagree.

Three authoring levels, by design: plain number (~90% of fields), preset formula (~9%), free JSON Logic (~1%, weaker validation, warned in the UI). The AI generator is only ever allowed to emit presets.

Authoring in the forms

Every ƒx-enabled field shows a small mode selector next to the number input:

The Preview button evaluates your formula immediately and shows the result at 2, 3 and 4 players — e.g. 2p: 8 · 3p: 12 · 4p: 12. Preview runs against an empty table, so card-count formulas show 0 there; they count real cards during simulation.

Fields with the widget today: Step 2 · Trackers (Starts at, Min, Max), Anatomy · Setup (Starting hand size), Step 2 · Zones (Refill target count).

The preset catalog

The catalog is deliberately closed: an unknown preset throws at compile time — it is never silently coerced (the lesson from finding A2). Adding a preset is a code change; see Extending it.

Authoring in game-defs JSON (probes, import)

Three accepted spellings — all normalise to the canonical two-key shape on save/import:

/* 1 — canonical: expr + authored (what export writes) */
"copies": {
  "expr":     { "by_player_count": { "map": { "2": 8, "3": 12 }, "default": 12 } },
  "authored": { "level": "formula", "preset": "by_player_count",
                "params": { "2": 8, "3": 12, "default": 12 } }
}

/* 2 — authored only: expr is compiled server-side */
"copies": {
  "authored": { "level": "formula", "preset": "by_player_count",
                "params": { "2": 8, "3": 12, "default": 12 } }
}

/* 3 — bare expr (hand-written JSON Logic): gains authored { level: "free" } */
"copies": { "expr": { "by_player_count": { "map": { "2": 8 }, "default": 12 } } }

Live example: dominion.json — the Estate / Duchy / Province / Curse piles all carry spelling 1. php8.2 game-tool.php import validates every expression and reports problems in the gap report instead of failing the import.

Where expressions work

Evaluator operators available inside expr

Standard JSON Logic (+ - * / if == < > and or var …) plus the DeckCraft custom operators:

The preview endpoint

POST /ajax-expr-preview.php
Content-Type: application/json

{ "value": { "authored": { "level": "formula", "preset": "by_player_count",
                           "params": { "2": 8, "3": 12, "default": 12 } } } }

→ { "success": true,
    "preview": { "2": 8, "3": 12, "4": 12 },
    "compiled": { "by_player_count": { "map": { "2": 8, "3": 12 }, "default": 12 } },
    "note": "Zones are empty in preview: …" }

Also accepts literals (echoed at every player count) and bare-expr values. Invalid formulas return success: false with the compile error — the same error the save endpoint would give.

Extending it (developer how-to)

Adding a preset — four places, in order:

Consuming the union at a new engine read site — the pattern:

$v = $def['some_field'] ?? 0;
if (dcIsExprValue($v)) {
    $v = dcResolveValue($v, $state, ['player' => $me], $fallback);
}

• Guard with dcIsExprValue() first — literals must stay free.
• If the read site is hot (per-action), compute $g->toArray() lazily — see engineApplyZoneRefills() or the cost loop in engineLegalActions() for the pattern.
• dcZoneRefillTarget() shows the callable-state variant for shared helpers.

Adding the widget to another form — three lines:

html += ExprWidget.field('my_field', 'Label', value, { zones: [...], trackers: [...] });
/* after innerHTML: */  ExprWidget.bind(formEl);
/* on save:         */  var v = ExprWidget.read(formEl, 'my_field', 0);
                        var err = ExprWidget.validate(v);   // free-JSON syntax check

Then add the section/field to the compile-on-save block in ajax-step2-save.php ($EXPR_SECTIONS + a $normaliseAt call), and make sure the page loads js/expr-widget.js before the section script.

Invariants & gotchas