Skip to content

ByteTerrace/Puck / .claude/skills/puck-dsl

puck-dsl

Verified

Maps the .puck language: grammar, let/template/for, map/range builtins, puck compile/decompile/lint/format, PUCKnnn errors. Use for any .puck edit or JSON-to-.puck conversion. Shapes: sdf-authoring.

FileKindSize
SKILL.mdskill md20.0 KB
evals/p01-json-to-puck-cartridge/graders/arrays-without-colon.mdmarkdown70 B
evals/p01-json-to-puck-cartridge/graders/cursor-row.mdmarkdown114 B
evals/p01-json-to-puck-cartridge/graders/map-range-builtin.mdmarkdown169 B
evals/p01-json-to-puck-cartridge/graders/no-colon-before-a-bracket.mdmarkdown209 B
evals/p01-json-to-puck-cartridge/graders/scalar-colons-kept.mdmarkdown131 B
evals/p01-json-to-puck-cartridge/graders/skill-fired.mdmarkdown36 B
evals/p01-json-to-puck-cartridge/graders/variables-without-colon.mdmarkdown73 B
evals/p01-json-to-puck-cartridge/prompt.mdmarkdown354 B
evals/p02-puck040-and-puck037/graders/colon-refused-at-every-depth.mdmarkdown146 B
evals/p02-puck040-and-puck037/graders/core-parser-accepts-repeat.mdmarkdown144 B
evals/p02-puck040-and-puck037/graders/distinct-fixes.mdmarkdown106 B
evals/p02-puck040-and-puck037/graders/foreach-or-unrolled-effects.mdmarkdown323 B
evals/p02-puck040-and-puck037/graders/if-is-not-refused.mdmarkdown117 B
evals/p02-puck040-and-puck037/graders/puck037-nothing-to-lower-onto.mdmarkdown203 B
evals/p02-puck040-and-puck037/graders/puck040-drop-the-colon.mdmarkdown161 B
evals/p02-puck040-and-puck037/graders/skill-fired.mdmarkdown36 B
evals/p02-puck040-and-puck037/prompt.mdmarkdown474 B
evals/p03-180-zeroes/graders/compile-time-only.mdmarkdown120 B
evals/p03-180-zeroes/graders/compiled-json-keeps-the-values.mdmarkdown104 B
evals/p03-180-zeroes/graders/map-range-builtin.mdmarkdown133 B
evals/p03-180-zeroes/graders/skill-fired.mdmarkdown36 B
evals/p03-180-zeroes/prompt.mdmarkdown312 B
evals/p04-generate-locals-from-kicks/graders/for-in-the-rule-body.mdmarkdown103 B
evals/p04-generate-locals-from-kicks/graders/interpolated-local-name.mdmarkdown68 B
evals/p04-generate-locals-from-kicks/graders/not-five-rules.mdmarkdown141 B
evals/p04-generate-locals-from-kicks/graders/priced-like-hand-written.mdmarkdown120 B
evals/p04-generate-locals-from-kicks/graders/puck114.mdmarkdown64 B
evals/p04-generate-locals-from-kicks/graders/read-by-name.mdmarkdown96 B
evals/p04-generate-locals-from-kicks/graders/rule-when-or-if.mdmarkdown127 B
evals/p04-generate-locals-from-kicks/graders/skill-fired.mdmarkdown36 B
evals/p04-generate-locals-from-kicks/graders/unrolled-locals.mdmarkdown167 B
evals/p04-generate-locals-from-kicks/graders/when-in-for-refused.mdmarkdown118 B
evals/p04-generate-locals-from-kicks/prompt.mdmarkdown425 B
evals/p05-decompile-is-one-way/graders/compile-validate.mdmarkdown82 B
evals/p05-decompile-is-one-way/graders/edit-the-source.mdmarkdown181 B
evals/p05-decompile-is-one-way/graders/lint-strict.mdmarkdown77 B
evals/p05-decompile-is-one-way/graders/one-way.mdmarkdown194 B
evals/p05-decompile-is-one-way/graders/re-author-the-loops.mdmarkdown162 B
evals/p05-decompile-is-one-way/graders/skill-fired.mdmarkdown36 B
evals/p05-decompile-is-one-way/prompt.mdmarkdown486 B
evals/p06-world-rule-minus-equals/graders/long-form.mdmarkdown73 B
evals/p06-world-rule-minus-equals/graders/no-negated-add.mdmarkdown162 B
evals/p06-world-rule-minus-equals/graders/parser-accepts-it.mdmarkdown157 B
evals/p06-world-rule-minus-equals/graders/skill-fired.mdmarkdown36 B
evals/p06-world-rule-minus-equals/graders/two-effects.mdmarkdown190 B
evals/p06-world-rule-minus-equals/prompt.mdmarkdown216 B
evals/shade-runtime-slots/graders/slots-and-structure.mdmarkdown417 B
evals/shade-runtime-slots/prompt.mdmarkdown317 B
references/diagnostics.mdmarkdown8.6 KB
references/grammar.mdmarkdown18.7 KB
---
name: puck-dsl
description: "Maps the .puck language: grammar, let/template/for, map/range builtins, puck compile/decompile/lint/format, PUCKnnn errors. Use for any .puck edit or JSON-to-.puck conversion. Shapes: sdf-authoring."
---

# The `.puck` authoring language

`.puck` is the one authoring language behind two document vocabularies:
`puck.world.definition.v1` (`Puck.World.Transpiler`) and `puck.cartridge.v1`
(`Puck.GamingBricks.Transpiler`). Both ride one schema-agnostic core,
[`Puck.Transpiler`](../../../src/Puck.Transpiler/README.md): parser, printer,
lowering, diagnostics, module resolver and unit arithmetic. This skill maps that
core and its CLI loop; what a block means is the vocabulary skill's (see the
routing table). When this file and the code disagree, the code wins and this
file is corrected in the same change.

## Where things live

| Thing | Where |
|---|---|
| Parser, printer, lowering, diagnostics | `src/Puck.Transpiler` (`Parsing/PuckParser*.cs`, `Formatting/PuckPrinter*.cs`, `Lowering/DocumentLowering*.cs` and `DocumentBuiltins.cs`, `Diagnostics/PuckDiagnosticCodes.cs`) |
| World vocabulary, its linter and language server | `src/Puck.World.Transpiler` (`Vocabulary/` describes every construct once; `Validation/PuckLinter*.cs`; `Lsp/`) |
| World compile contract | `src/Puck.World.Transpiler/WorldCompileSession.cs`, the one door every host compiles, composes, loads and diagnoses through (it holds library parses by content in `Puck.Transpiler.Modules.PuckSourceTable`, held compiles, and each editor buffer's latest compile), over the internal stage order in `WorldCompiler.cs`; `WorldDocumentMembers.cs` walks the emitted document along `WorldModelShape`: it refuses unconsumed members (naming the nearest declared members through `DocumentNearestNames`), lowers authored pins to canonical document identities, and writes each typed value's canonical form (float spelling, rotation sign, convex profile start, zero-is-absent shape members, a write's `value`/`fromState`, model member order) |
| Cartridge vocabulary | `src/Puck.GamingBricks.Transpiler` |
| Expression vocabulary (operators, named functions) | `Puck.State.ExpressionOperators`, `Puck.State.ExpressionVocabulary` |
| CLI verbs | `src/Puck.Cli.Worlds` (`Transpiler/`: compile, decompile, lint, lsp, migrate, embed; `Test/`; `Vocabulary/`), `src/Puck.Cli.Format` (format) |
| Shipped sources | the world packages, `worlds/<id>/` (the debug world: `worlds/debug/**/*.puck`, cartridges under `worlds/debug/cartridges/`), `src/Puck.World.Transpiler/Samples/`; the quarantined worlds under `experimental/` are prior art |

A document's `schema:` field selects its vocabulary, never the filename.

## Grammar that bites

- **Authored material programs.** A palette's `shade` calls a `shade template`
  or holds `surface`, `light` and `compose` blocks. Parameters are runtime slots
  unless marked `structural`; loop ranges, shape descriptors and indexed lane
  selectors require structural values. `WorldShadeLowering` uses the core's
  expansion and recursion guard. It emits the canonical graph admitted by
  `SdfShadeProgram`, with typed stamp reads, live-read flags and checked cost.
  `lanes.slot[index]` and `lanes.world[index]` lower to the same reads as the
  named lanes. A list (`shade [base.shade, terrain(...)]`) composes programs in
  order into one: an element is a template call, a block, or an admitted program
  read as a value (a row's `shade`; an absent one adds nothing), a later
  element's output replaces an earlier one's, and its surface phase reads what
  the earlier ones wrote as `material.*` and `surface.normal`. A list field is
  spelled without the colon, as every list is. A structural argument reaches the
  template as its expression: a function's scalar parameter works, a member of a
  record parameter does not. A `shade` value lowers to its program's key, and the
  document's root `shades` table holds each distinct program once, so a style on a
  hundred rows costs one program and a hundred keys
  ([one program, one row](../rendering/references/authored-shading.md#one-program-one-row)).
  Refusals are `PUCK126`–`PUCK130`; ordinary
  recursion and invalid compile-time ranges retain the core's codes. See
  [the rendering contract](../rendering/references/authored-shading.md).

- A keyed row layered over a basis may carry `$before: "target-name"` to lead a
  surviving row, including from an imported fragment. `WorldDocumentBasis.MergeList`
  consumes it after drops and appends; missing targets and cyclic positions refuse.
  Ordinary rows keep their order. This is document composition, not a runtime hold option.

- **One spelling per shape, at every depth.** A literal container is always a
  block with no colon (`host { }`, `cameras [ ]`, `variables [ ]`,
  `arrays [ ]`), inside an object literal too
  (`{ name: "lit", pixels ["00000000", "11111111"] }`). A scalar always takes a colon
  (`name: "cursor"`, `initial: 0`). A colon in front of `{` or `[` is
  **PUCK040**, the most common mistake; the fix is to drop the colon. A value
  written as a call or a name keeps its colon even when it produces a
  container: `pixels: map(range(0, 8), row => "00000000")`, `origin: bounds`.
- `let name = expr` is a compile-time constant (admitted at top level, inside
  templates, blocks, `prototypes`/`placements`/`state.world` sections, and `for`
  bodies); `base with overrides` derives a record from an object using either an
  object literal (`{ member: value }`) or any expression evaluating to an object
  (shallow: members replaced or added, a nested override spelled by nesting,
  `speed: kit.speed with { value: 5 }`) and lowers to the object written out;
  `function name(p, q = d) = expr` names a value or a guard, inlined where it is
  called (a document value, a gate, an effect), never recursive;
  `template name(p, q = d) { }` a parametric block (admitting `enum` and
  `export` inside its body); `rule template name(p) { }` a block of rule-body
  statements (locals, `when`, `if`, effects) a rule body calls and splices
  (`worlds/standard/seat.puck`'s `seatPress`); `import "name" [as alias]`,
  `export` (and `exports { … }`, whose repeated blocks merge facet lists), and
  `use m as a(args)` compose modules. An import's export surface is explicit,
  never transitive across nested imports. `table` and `pile` admit
  `capacity(auto)` to lower to their authored entries' count.
- **A template body's block or rule name is a parameter reference only when
  bare.** `shape Box base { }` takes the value bound to `base`; `shape Box "base" { }`
  is the literal name, whatever the template's parameters are called. Only a
  statement directly in the template body is renamed (`DocumentLowering.Rename`).
- **An import names, never spells a file.** `import "skies"`, not
  `import "skies.puck"` (**PUCK121**). The named file decides what comes in: a
  module library (a source emitting no document) hands over its `let`s and
  templates; anything else is a document the importer composes at load, whose
  own `let`s stay its own. A library importing a document is refused (PUCK017).
  A source of imports alone hands over nothing of its own, so it is a document
  fragment that composes what it imports, not a library (`worlds/standard/standard.puck`).
- **Compile-time `for` generates rows and list elements; builtins transform values.**
  `for i in range(0, n) { }` and `for (item, index) in [...] { }` expand at
  compile time — both in statement/section position (emitting rows) and directly
  inside `[ ... ]` (flattening produced elements into the list, with optional
  local `let`s). Collection builtins (`range`, `length`, `concat`, `map`,
  `flatMap`, `filter`, `reduce`, `distinct`, `sort`, `groupBy`) take lambdas
  (`i => 0`); a flatten is `flatMap(rows, r => [..])`, never a `reduce` over `concat`. An array of n zeros is `map(range(0, n), i => 0)` or `[for i in range(0, n) { 0 }]`; it runs once
  at compile time, the compiled JSON still holds every value, and play-time
  behavior is unchanged. A lambda anywhere else is **PUCK042**; an unevaluable
  call **PUCK041**; a `for` over something not known at compile time
  **PUCK044**.
  `range(start, count)` takes a count: `range(16, 16)` emits 16 through 31.
- **A `for` inside a rule body unrolls into the body.** A loop
  over an n-element array that declares `local $"name{i}" = …` compiles to a
  rule carrying n separate locals, `name0` through `name<n-1>`, each with its
  element substituted as a literal; the document holds no loop. Later
  statements read each local by its resolved name, and each is priced like a
  hand-written local. A `for` reads any compile-time array: a `let`, a
  literal, or a builtin's result.
  World locals precede every gate and effect and evaluate in declaration
  order. A late declaration is refused; move it before the first gate or
  effect to make its pre-effect read explicit.
  A rule has one gate and one decision, so a `when`, `decision` or nested
  `rule` inside a rule-body `for` is **PUCK114**; write the condition in the
  rule's own `when`, or in an `if` inside the loop.
- Units (`s ms min h m cm mm hz % pct deg rad`) convert in the core; a unit on
  a field the vocabulary does not dimension is **PUCK024**, an inadmissible
  unit **PUCK025**.
- Strings: plain `"..."`, interpolated `$"...{expr}..."`, raw `"""..."""`, raw
  interpolated `$"""..."""`. An interpolated string computes a name, key,
  number or text, never an expression (**PUCK112**). Backquote a name the bare
  form cannot carry (`` `seat-1` ``).
- **Hashes have one authored spelling.** Write `hash: auto` for automatic
  hashing, or `hash: "sha256/<64 lowercase hex>"` for a digest. Quoted `"auto"`,
  bare digests and `sha256-64/` pins are refused by name during compilation.
  A null document hash carries no pin: decompilation omits that member, rather
  than inventing an empty digest or an automatic hash.
  Font pins cover the font bytes; canonical document rows (creations, patches, tunes,
  music and tables) pin their canonical document, whose compiled identity is
  still the canonicalizer's digest. The printer restores the authored prefix.
- Generated names use `$` inside a document and `~` in file names
  (`Puck.State.GeneratedName`); an author name using them is **PUCK113**.
- **Control flow is core-parsed; each vocabulary decides what its rule shape
  carries.** The parser accepts `if`/`else`, `repeat`/`break`, call-form gates
  and compound assignment for every vocabulary. A world rule lowers `if`/`else`
  to a conditional effect, but its body is straight-line, so `repeat` and
  `break` have nothing to lower onto (**PUCK037**). The refusal names the
  alternative: a rule already runs once per matching subject, so iterate with
  the rule's `forEach`; a fixed count unrolls with a compile-time `for`, or
  folds into one effect (`x += 3`). A world rule carries `=` (`setState`) and
  `+=` and `-=` (`addState`, negating subtraction's operand). Other compound
  operators lower to `setState` over an expression; a computed destination key
  is evaluated once when that effect runs. A cartridge-only `key(...)` gate in a world is
  **PUCK038**. Cartridge rules admit `if`, `repeat`, `break`, `key(...)` gates
  and compound assignment.
- **A `test`'s `expect` reads one world, or names the document it reads.** A line
  reads the booted world; a block named for a sibling document the world
  references (`garden { bodyState(body, 0, size) == 0.25 }`) is judged in the
  instance a crossing starts there, passes on any tick the claim holds, and fails
  when nothing crossed. An absent body reads every register as 0, so a claim of
  `0` there also claims presence
  ([testing a world](../../../docs/authoring/testing-a-world.md#crossing-into-another-document)).
- **`allow CODE "why"` acknowledges a deliberate warning or note** over the
  statement on the next line (a row, a `let`, a template call), never an error.
  It changes nothing in the document; an unknown code, a missing reason or
  nothing to cover is **PUCK124**. A diagnostic is reported against the file and
  line that authored it, an imported library's or a basis's included (with the
  use site attached as related information in the language server), and
  `puck lint <dir>` prints one placed in another file once.
- **Spellings that mean the same compile to one document.** The
  spelling-equivalence corpus
  (`tests/Puck.World.Transpiler.Tests/SpellingEquivalence/`) holds each pair; a
  new spelling lands with its pair, and a pair that fails is a compiler defect.
  Known and closed walls live in the
  [author walls log](../../../docs/authoring/author-walls.md).
  Constants fold before lowering: a name bound to a number, an enum member, an
  exact operator over constants and a ternary on a constant condition become
  their value, in gates and values alike.
- Gates (`when`, `if`, `expect`) accept ordinary expressions. Zero and absence
  are false; nonzero numeric values are true. `and` and `or` short-circuit;
  `not` negates truth. They yield Int 0/1 and bind below comparisons. Bitwise
  `&`/`|` bind above comparisons. `compareState(...)` and `compareValue(...)`
  in a source gate are refused by name; write a comparison such as `left == right`.
- **One bracket rule.** `row.key` names a literal key; `row[expression]`
  evaluates. Names in brackets resolve lexically, so an unknown bare word is
  an error. Use `row["key"]` for a quoted literal key. Read a local as `name`,
  never `local(name)`; use `row[x]`, never `row[(x)]` or `row[slot[$value]]`.
  Functions are recognized only in call position, so a local may be named `sign`.

[references/grammar.md](references/grammar.md) has the full grammar with
examples; [references/diagnostics.md](references/diagnostics.md) the codes
authors hit most. `PuckDiagnosticCodes.cs` declares every code once, with its
meaning as the XML doc comment.

## Authoring a console command

The owner's ruling: a console command composed from existing verbs is authored
in a world document, never as C# work. A `commands` row lowers through the
generic value path (no sugar); its full contract is
[document-authored commands](../../../docs/reference/commands.md#document-authored-commands):

```text
commands [
  {
    name: "gallery.show"                  // namespaced; never an engine verb's name
    help: "Stands a body at the gallery and picks a layout."
    parameters [
      { name: "layout", kind: Choice, values ["play", "front"], default: "play" }
      { name: "body", kind: Body, default: "0" }  // a default is written as typed
    ]
    lines [
      "body.pose spawn:gallery {body}"    // {name} substitutes; {{ and }} are literal braces
      "view.override layout {layout}"
    ]
  }
]
```

- Kinds: `Text` (default), `Number`, `Integer`, `Choice` (`values`), `Body`
  (0..4095), `Spawn` (a `spawnPoints` id). Arguments are positional plain
  tokens; required parameters come first; every parameter appears in a line.
- A line's first token (the verb) is literal; it may be another authored
  command (no loops) or any verb a binding may name. Operator verbs,
  unbindable verbs (`quit`, `world.save`, `storage.*`), engine-verb names and
  verbs no boot shape registers are refused by `puck compile --validate`
  (against the catalog `puck verbs` generates) and again when the World
  validates the document (boot, `world.reload`). A rendered-only verb
  (`world.debug-view`, `world.slice`) is fine in a line: a headless boot
  admits it and refuses only that line when it runs ("not available in this
  host"). Regenerate the catalog with `puck verbs` after adding or changing a
  verb.
- `commands` is keyed by `name`, so each imported document authors its own
  rows. Bind one like any verb (`command: "debug.go", text: "chess"`), or run
  `run <name> [args]`. Verify by booting the world: `help --names <prefix>`
  lists it, and the command answers its lines' output.

## The verbs

```text
puck format <file> --check
puck lint <file> --strict
puck compile <file>                   # writes <source>.world.json (and its .puckb) or <source>.cartridge.json beside the source; all derived, never committed
puck compile <file> --validate        # checks only: writes nothing without --output
puck test <path-or-dir>               # boots each test block headless, one verdict a line
```

- Compilation refuses unknown document members by name, including members
  supplied through templates and bound objects. Converter-owned values retain
  their own shape rules, and reserved document extension keys remain data.
  `puck compile --validate` additionally runs the engine's semantic validation.
  `--output` names the destination; a world source declaring `world` entries
  writes one document per declaration and reads `--output` as a directory.
  A world document also gets its compiled world (`.puckb`) beside it.
  `--tree` mirrors a directory of sources. The edit loop is the World's source watch and the language server; the compile verb has no watch mode.
- `puck decompile` is **one-way**: `let`, `template` and `for` never come back.
  Decompile once to import one hand-written JSON document, then edit the
  `.puck`. A row a `ground`, `test`, `border`, `door` or aliased `use`
  generated is refused by name: those are written in source, never printed
  from a document (decision P1).
- `puck format` prints `.puck` through `PuckPrinter` (two-space indent, lines
  broken past 120 columns, no options). A list of numbers written one to a line
  prints on one line when it fits and in filled rows otherwise; strings and
  rows of several elements keep the author's lines; the language server and `puck
  decompile` print through the same printer. Formatting is a fixed point and
  never moves a compiled document; reformat sources after a printer change.
- `puck lsp` serves completion, hover, go-to-definition, code actions, symbols,
  formatting and diagnostics (grouping findings by the file that authored them
  with the use site as related information).
- `puck migrate <name> <path> [--check]` applies one registered source rewrite
  and proves each rewritten source compiles to the document it did before.
  A syntax migration must also visit retained write-target operands
  (`RowRefNode.Operand`), including keys nested inside them. Compile the
  composed entry document after migrating modules: isolated module checks can
  miss a literal key accidentally resolving to another module's row.
- `puck embed lock <path>` resolves authored `embed(...)` text into committed
  `.embeddings.json` lock files.
- `puck vocabulary [--check]` regenerates the world vocabulary page.

**Source and generated documents.** The owner's ruling treats cartridge JSON
twins as derived caches, never committed or byte-compared against a saved copy.
Compile the authored sources when needed; semantic round trips compare fresh
compilations. Imported modules contribute templates, not standalone documents.
A world source also has no committed document: the build compiles it. `--world foo.puck` boots straight from source,
`world.reload` recompiles it, and `world.save` writes each live edit into the
source that authors it, an import's row in the import and a value read from a
`let` in that `let`, keeping everything else as written; generated rows refuse
by name, and simulation `state` stays as authored.

After editing a world, run it (`dotnet run --project src/Puck.World -c Release
-- --world worlds/debug --devices none --exit-after-seconds 2`); verify a cartridge in a world (`rom-forge`).

## Route adjacent work

| Skill | Route there for |
|---|---|
| `puck-world` | World-document sugar (`rule`/`decision`/effects, `forEach`), section rules, world refusals, booting `--world`. |
| `sdf-authoring` | Creation shapes, materials and rigs in `.puck`. |
| `input` | What `channels`, `inputModes`, `inputHistory`, `inputPatterns` and `bindingOverlays` rows mean. |
| `state` | What `state`, `rules` and `search` compile to: the arena, the rule compiler's refusals, faults and transforms. |
| `dashboard` | World Studio, which edits `.puck` through this language server running in the browser engine. |
| `rom-forge` | The cartridge vocabulary and the compile/`forge.play` loop. |
| `gaming-bricks` | Emulator behavior once a cartridge is compiled. |
| `symbol-analysis`, `content-search` | C# semantics and text search; `.puck` name resolution goes through `puck lint` or the language server. |
slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack."Stars: 198kUpdated Claude CodeCodexVerifiedInstall
ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt.Stars: 194kUpdated Claude CodeCodexVerifiedInstall