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.

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: 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

ThingWhere
Parser, printer, lowering, diagnosticssrc/Puck.Transpiler (Parsing/PuckParser*.cs, Formatting/PuckPrinter*.cs, Lowering/DocumentLowering*.cs and DocumentBuiltins.cs, Diagnostics/PuckDiagnosticCodes.cs)
World vocabulary, its linter and language serversrc/Puck.World.Transpiler (Vocabulary/ describes every construct once; Validation/PuckLinter*.cs; Lsp/)
World compile contractsrc/Puck.World.Transpiler/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 vocabularysrc/Puck.GamingBricks.Transpiler
Expression vocabulary (operators, named functions)Puck.State.ExpressionOperators, Puck.State.ExpressionVocabulary
CLI verbssrc/Puck.Cli.Worlds (Transpiler/: compile, decompile, lint, lsp, migrate, embed; Test/; Vocabulary/), src/Puck.Cli.Format (format)
Shipped sourcesthe 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. Refusals are PUCK126–PUCK130; ordinary recursion and invalid compile-time ranges retain the core's codes. See the rendering contract.

  • 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; base with { member: value } derives a record from 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; 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 use m as a(args) compose modules.

  • 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 lets and templates; anything else is a document the importer composes at load, whose own lets 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; builtins generate values. for i in range(0, n) { } and for (item, index) in [...] { } expand at compile time, and the document carries the rows they produce. Inside one value, use the collection builtins: range, length, concat, map, flatMap, filter, reduce, distinct, sort, groupBy, each taking a lambda (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); 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).

  • 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, 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. 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 has the full grammar with examples; 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:

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

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. --watch recompiles on change; --tree mirrors a directory of sources.
  • 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, symbols, formatting and diagnostics.
  • 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

SkillRoute there for
puck-worldWorld-document sugar (rule/decision/effects, forEach), section rules, world refusals, booting --world.
sdf-authoringCreation shapes, materials and rigs in .puck.
inputWhat channels, inputModes, inputHistory, inputPatterns and bindingOverlays rows mean.
stateWhat state, rules and search compile to: the arena, the rule compiler's refusals, faults and transforms.
dashboardWorld Studio, which edits .puck through this language server running in the browser engine.
rom-forgeThe cartridge vocabulary and the compile/forge.play loop.
gaming-bricksEmulator behavior once a cartridge is compiled.
symbol-analysis, content-searchC# 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: 197kUpdated 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