The keystone of the Builder Studio ontology: a mechanic is isolated from an existing game, given a canonical label and trait vocabulary, and recorded as a first-class library entry. Every new game, variant, or reskin then references that record — rather than copying opaque config — so the whole build pipeline knows what kind of game it is working with before a single config value is set.
Mechanics are first-class records that games reference, not inline config blobs that games own. A MechanicRecord can be pointed at by many games simultaneously; changing the record's metadata (label, certification status, trait tags) does not change any game's config. Today's nearest ancestor is the template registry in packages/shared/src/templates.ts, where each GameTemplate carries a manifest with mechanic, sessionMode, and defaultRtp — the library formalises and extends that pattern. In the grown GameSpec data model, a spec points at one or more library entries via mechanicRefs[].
| Field | Type | Description |
|---|---|---|
id |
string |
Stable slug used in mechanicRefs[] on GameSpec and in picker queries. E.g. crash-shared-world. |
label |
string |
Human-readable name shown in the picker and the variant diff UI. E.g. "Crash — shared-world multiplier curve". |
traits[] |
TraitTag[] |
Tagged vocabulary covering: session mode (shared-world / single-player / multi), pacing (real-time / turn-based), decision shape (cashout-timing / n-choice pick / press-your-luck ladder / pure reveal), volatility levers (curve bounds / multiplier ranges / thresholds / prize table), and bonus hooks (earned-through-play / triggered / none). See Labelling vocabulary. |
configSchemaRef |
string |
Points at the engine plugin's config schema (e.g. games/crash/server/src/types.ts#CrashConfig). The Builder renders the mechanic-specific config form from this ref. |
lineage |
string |
Human note on provenance: the game or version from which this record was extracted. E.g. "extracted from crash v1.2" or "extracted from games/trunk-raider". Audit trail; not machine-parsed. |
certificationStatus |
"certified" | "in-review" | "concept" |
Whether the mechanic has been through the certification process. Certified mechanics can be used in production paths; concept entries can be used in prototype and sandbox paths only. |
Every mechanic record carries a set of traits[] drawn from the vocabulary below. The vocabulary is the shared language used across the picker, the variant diff UI, the Math-Sim agent's config validation, and the mechanics library's own filter query. Tags are grouped into five axes — a record carries exactly one tag per axis, except volatility levers (a mechanic may expose more than one lever type).
Five full entries follow — three GROUNDED (values extracted verbatim from packages/shared/src/templates.ts and the engine game sources) and two CONCEPT entries for mechanic types not yet in the library. Every card carries a honesty badge.
games/crash — real-time, shared-world via Durable Object per room; all players see the same multiplier curve tick by tickgames/trunk-raider — bonuses (silentPick, informant, cheatCode) are earned through cumulative play, not externally triggeredgames/silk-road — deliberately minimal config surface; all internal curve and risk parameters are owned by the engine, not exposed as leversstandout-games before a record can graduate from CONCEPT to certifiedWhen a builder chooses the New game path in the Build Path Picker, the second step is selecting a mechanic — or proposing a new one. Rather than presenting a raw list, the picker exposes a filtered view of the library: a builder can describe the kind of game they are making ("something with a shared-world curve", "a pick'em with earned bonuses") and the library returns matching entries ranked by certification status. Only certified records are eligible for production paths; concept entries are offered as starting points for prototype or variant explorations with an explicit warning that a new plugin will be required.
New mechanic records do not enter the library by fiat. The path is engineering-assisted and proceeds in three stages: the engine holds fifteen games today while the template registry covers three — the extraction backlog and the auto-extraction fix are traced in Variant → Live's gap table.
standout-games. A game developer implements the mechanic as a new plugin — a TurnBasedPlugin or RealTimePlugin — in the vhslab/standout-games repository, following the plugin contract and registering it in the engine's static plugin registry. This is the only stage that requires direct engineering engagement; it cannot be agent-automated yet.
configSchemaRef is set to the plugin's config type.
game-rng package. Mechanics never own RNG directly — they consume game-rng via the plugin API. A new mechanic plugin must not introduce its own random-number logic, fork game-rng, or attempt to override its outputs. Any change to game-rng itself requires a full recertification cycle, which is time-consuming and expensive. This constraint is absolute: if a proposed mechanic cannot be expressed using the existing game-rng API, the correct path is to raise an engineering change request — not to work around it in the plugin. See architecture open questions for the related Math-Sim proof compliance question.