# Ornamentation — what a game is besides its rules Status: **draft**, normative for new work. Changes go through a decision record in `decisions/`. Companion to [`ArchitectureBlueprint.md`](ArchitectureBlueprint.md) (layers and ports) and [`GameDesign.md`](GameDesign.md) (findings about the game). This document draws **one boundary**: between what the rules can see and everything else a player experiences — and says which repo each belongs to as the simulator grows. > **A good game is not only its rules.** It is materials, flow, timing, > relatability, illustration, typography, and the ceremony around play. > A simulator that models only the rules models a *part* of the game, and > should say which part rather than implying it is the whole. --- ## 1. Two categories, and the test between them **Mechanism** is anything that can change the state the rules can see. **Ornamentation** is everything else the player nonetheless experiences. ### 1.1 The test > **Does it move the state hash?** > > If yes, it is mechanism. If no, it is ornamentation. This reuses an instrument the project already has and already trusts: `state_hash` is what makes a session comparable to its replay, and what a trial note binds to (ADR-0019 D3). **The line is therefore executable, not editorial** — which matters here more than elsewhere, because everything downstream depends on the classification being right. ### 1.2 Ornamentation usually decorates a mechanism rather than replacing it The clearest case, and the one that named this document: | the fact | category | why | |---|---|---| | the deck's permutation | **mechanism** | it decides the deal; in clay-borg it comes from the seed | | **who shuffles**, and the shuffling | **ornamentation** | no rule can see it | | the hands after dealing | **mechanism** | the state contains them | | **who deals**, cards arriving one at a time, entering from the right | **ornamentation** | the same hands either way | So ornamentation is typically **a ceremony around, or a presentation of, a mechanism** — and occasionally a thing with no mechanism under it at all. **"Has a decision in it" is NOT the test.** Choosing who deals is a decision, and it is ornamentation. This was the open question in CB-WP-0036 and the maintainer settled it: these are ornamental *because they are not necessary*, not because nobody chooses. ### 1.3 The unit is a column, not a file **Discovered by doing it** (CB-WP-0037 T03). `Player_Mats.csv` looks like pure ornamentation — a symbol, a colour, a title for each of six seats — and one of its columns is GR-R03 itself: > *"At Stress 0–3 choose any action. At Stress 4–5 choose ATTACK or GROUND > unless you spend a ready Freedom token."* That is the stress gate the engine enforces in `stress_gated` and `allowed_under_stress_gate`. **Classifying the file would have thrown a rule away with the colour swatches.** So a declaration names *what* it ornaments, not *where the bytes live*. A mixed artifact is normal: the mat is a rule printed on a decorated card, which is exactly what a player mat is in the box too. ### 1.4 Why not "ritual" `ritual` reads as ceremony only, and half of this category is not ceremonial — card stock, a typeface, the drift of a discard, how legible a player mat is. **`ornamentation` covers the material and the ceremonial together**, and carries the right implication: it is *applied to* the thing, and it is not structural — and §1.3 is why *applied to* is the right preposition: it sits on something, it is not the something. Ornamentation is **not decoration in the pejorative sense**. This project uses "decoration" for a control that cannot fail (ADR-0006 D3), and that word is spoken for. --- ## 2. Why clay-borg names what it will never render The rendering belongs downstream (§3). The **classification does not**, for one reason: > **Calling something ornamentation is a claim that it does not matter to > the game — and claims that something does not matter are exactly the > claims this project has been wrong about.** The register is the evidence. `quantity` in `Tokens.csv` was measured across 750 games before being declared non-binding (CB-EV-0027 §3), and the argument that settled it was *not* "nothing exceeded it" — it was that no numbered rule mentions a supply, so enforcing one would have been the engine deciding a rules question. F18 stands open because four edition files were assumed not to matter. CB-WP-0023 exists because SOLVE was offered where it could not act. **A classification is a claim about the game.** It therefore belongs where this project keeps claims about the game — with a reproduction and a falsifier (GameDesign §1) — and not in a renderer's stylesheet, where nothing can contradict it. ### 2.1 What a declaration carries 1. **What it ornaments** — the mechanism it accompanies, or `none`. 2. **Why it does not bind** — by rule text where the edition has one, or by measurement, or explicitly *"provisional, nobody has ruled"*. 3. **What would falsify it** — the rule or observation that would make it mechanism. A declaration that cannot be wrong is not a claim. **Provisional is a legitimate state and must be said out loud.** The failure mode this project has already committed once is canonising a provisional default by implementing it quietly. ### 2.2 Ornamentation is sourced, not invented ADR-0015's discipline applies unchanged: **the game's own words, where the game has words.** Card text, mat layout, the vocabulary in `Glossary` and the stage names in `DARVO` are ornamentation-bearing data that exists upstream and is currently **unvendored** (F18). Where the edition says nothing, clay-borg may choose — and must **label the choice as ours**, exactly as the rankings panel labels its one derived superlative *"clay-borg's reading, not a rule"* (CB-EV-0026 §5). --- ## 3. The module boundary ```mermaid flowchart LR CB["clay-borg state - rules - admissibility trials - findings ornamentation DECLARED one simple built-in view"] CA["clay-animate movement - timing - layering the interactive pace's presentation"] CP["clay-physics material simulation cards - table - gravity"] CB -->|"facts + declarations"| CA CA --> CP ``` **clay-borg is the simulation core and stays that way.** Its built-in view is deliberately plain: simple frontend/backend interaction, simple UI concepts, so attention stays on the game and the simulation rather than on a rendering pipeline. **Its native pace is Speed** (§4), and it is tuned for that. **clay-animate** is where movement lives: a card summoned larger beside the acting seat, shrinking toward its target, a discard drifting without resizing. It is a *later, separate repository* and needs a client/server interaction materially more complex than the core should carry. **clay-physics** is further out still: real material behaviour. ### 3.1 The rule that makes the boundary hold > **Downstream may read. Downstream may not decide.** This is [ADR-0007](../decisions/ADR-0007-hot-seat-in-a-browser.md) D5 — *the page reports raw pointer facts and constructs no commands* — restated one level up, at the repository boundary rather than the script boundary. A game played through `clay-animate` must be **indistinguishable, in the record, from the same game played through clay-borg's own view.** If a renderer can change an outcome it is not a renderer. ### 3.2 Why the port is not being built yet **No consumer exists.** This project's own rules say a kind with no instance was invented rather than observed (GameDesign §2) and a gate that cannot go red is decoration (ADR-0006 D3). An interface designed against an imagined client would be both. **What is being fixed now is the vocabulary and the boundary.** The port gets designed when `clay-animate` exists to pull on it, and the first version of it should be *the data clay-borg already emits* — the journal is already the sequence of what happened, and CB-WP-0032 already reads it. --- ## 4. Pace `--pace speed | interactive` (proposed; **not** `--mode`, which is already `ScoringMode`). | pace | what it means | |---|---| | **speed** | ornamentation is skipped; the view jumps to the result. **The default**, and what `sim`, `trials`, benchmarks and bot play always use | | **interactive** | ornamentation is performed | Pace selects **how much ornamentation is performed**. It can never select *different mechanism*, which §5 states as an invariant rather than an intention. `prefers-reduced-motion` behaves as **speed**. --- ## 5. Invariants These are the document's teeth. **I1–I4 are checkable today, cheaply**, which is the point — this project has 62 untagged literals as evidence of what a broad unenforced requirement produces (ADR-0018 D4). | | invariant | |---|---| | **I1** | Ornamentation never moves `state_hash`. | | **I2** | Ornamentation never enters the journal or the recording. | | **I3** | The same seed and the same decisions produce a **byte-identical recording** at any pace, through any renderer. | | **I4** | Speed pace costs the core **nothing** — not "little": `sim`, `trials` and the benchmarks are unaffected. | | **I5** | Every ornamentation declaration states what would falsify it (§2.1). | **I3 is the falsifier for the whole boundary.** If it ever fails, something downstream has become mechanism and the split has stopped being real. ### 5.1 What to do when ornamentation must be preserved I2 keeps the recording canonical, which raises a fair objection: a replay then cannot reproduce **what a player actually saw**. The answer already exists in this repo. A trial keeps *two* files — the recording and a sibling log of what the player said (GameDesign §5). **A session's ornamentation goes in a sibling too**, never in the scenario. One artifact stays replayable; the other stays human. --- ## 6. Where a new capability goes In order. The first match wins. 1. **Can it change a legal move, an outcome, or the state hash?** → clay-borg, as mechanism, under the existing rule budgets. 2. **Is it a claim that something does *not* matter?** → clay-borg, as a declared ornamentation with a falsifier (§2.1). **This is the step that gets skipped**, and skipping it is how a provisional default becomes canon without anyone deciding. 3. **Is it the presentation, timing or movement of either?** → clay-animate. 4. **Does it need materials to behave like materials?** → clay-physics. 5. **None of these?** Then it is not yet understood well enough to place, and the honest move is a finding, not a module. --- ## 7. Falsifier for this document If an ornamentation declaration is ever found to have changed an outcome, §1.1's test is not the right test and this document is wrong at the root — not patchable at the edges. If, after `clay-animate` exists, **§3.2's deferred port turns out to have needed designing here all along**, then the "no consumer, no interface" rule cost more than it saved, and that should be recorded against it.