ByteTerrace/Puck / .claude/skills/sdf-authoring
sdf-authoring
VerifiedAuthors creations: shape rows, primitives, blends, folds, palettes, paints, render lanes, rigs, bake work and bytes, creation stats. Use to sculpt or fix a part. Grammar: puck-dsl; GPU: rendering.
references/loop.md
View on GitHub# The authoring loop
## Naming: `prototypes` on disk, `creations` on the console
A creation lives at `prototypes[].document` in the world file. The console row
door addresses those same rows as section `creations`, keyed by prototype id.
Both names are correct in their own place; neither works in the other's.
## Editing live
```
world.row.set creations <id> document.shapes[name=<shape>].<field> <json>
world.row.add creations <id> document.shapes[name=<shape>].swings <json> [after=<selector>]
world.row.remove creations <id> document.shapes <selector>
world.row.step creations.<id>.document.shapes[name=<shape>].<field> <delta>
world.row creations <id> document.shapes[name=<shape>]
```
Selectors are `[3]`, `[name=…]`, or `[id=…]`. A whole-row payload starts with
`{` or `[`; that is what tells the keyed and keyless forms apart. JSON `null`
clears a nullable field, and a `"state.row.key"` string keeps a binding.
Use `world.row.step <path> <delta>` for numeric scalars such as rounding,
exponent, smooth, or taper. It refuses vectors and nested objects; set the full
`[x,y,z]` for scale/position, or `[x,y,z,w]` quaternion for rotation through
`world.row.set`. A state-bound transform keeps its binding by editing the
underlying state row.
A shape's `parent` carries its animated rigid delta, not its static rest pose
or scale. Changing a parent's base scale does not reposition children; edit
their authored base poses too. A `parent`, `swings` or `slides` edit applies on
the next frame like any other row edit; `body.rig <body> <shape>` reads back
the parent the shape's motion chains under and the delta it composed
([rig](rig.md#attaching-a-shape)).
`world.row.add` creates an omitted list field (a shape with no `swings` yet) when
the member is a list, and refuses a member that is not one.
`world.row creations <id> document.shapes` lists the elements. A creation row
carries no `hash` unless one was authored: the digest is derived from the
document and dropped on every edit.
Mutation verbs return no synchronous echo — the verdict lands at the tick
boundary on stderr. A second edit to the same row inside one tick is refused:
`row '<identity>' already has an edit buffered this tick — fence with world.wait`.
Against a world booted `--world <file>.puck`:
- `world.load <path>` and `world.reload` read `.puck` through
`WorldDefinitionLoader.TryLoadFileForAdmission` with `WorldCompileSession.Shared`
document source, so editing the `.puck` file and running `world.reload`
recompiles it (basis chain included) with no restart. A re-read that no
longer compiles or validates leaves the running world untouched and echoes
why.
- `world.save` prints each changed authored node into the `.puck` source that
authors it (the root or any document it imports), retaining unrelated source
text and proving the recomposed snapshot before writing. Template and compile-time `for` rows refuse by name. Rename a live
duplicate before saving its generated id to source.
`world.row.set`/`world.row` mutations act on the in-memory document. Keep an
authored edit with `world.save`. For an expansion-owned row, edit its generator
or save a JSON target declaring the source as its `basis`. A `world.reload`
discards unsaved row edits, since it rebuilds from what is on disk.
## Looking
```
view.override camera <name> # or: layout <name>, or auto / - to clear
view.isolate <prototype> <shape-name>... # render only those shapes and their descendants; off restores
world.screenshot <abs-path.png>
world.wait <ticks>
```
`world.screenshot` **arms** a capture. stdout carries
`[world.screenshot: pending <path> …]`; the file exists only once stderr carries
`[capture] <instance> -> <path>`. Fence with
`world.wait` and confirm that line before reading bytes. A second arm while one
is pending is refused by name. It is refused headless.
Two windowed captures are never byte-identical. Compare by changed-pixel count
against a threshold, never by bytes.
## Driving the game from a script
```bash
dotnet run --project src/Puck.World -c Release -- \
--world <path> --devices none --exit-after-seconds N --state-dir <tmp> \
< script.txt > out.log 2> err.log
```
`<path>` may be a `.world.json` file or a `.puck` source — `PuckWorldLoader`
transpiles a `.puck` path in memory at this one boot, transparently to
everything below it. There is no separate compile step for a quick look; run
`puck compile <file>.puck --validate` first only when you want the named
diagnostics before spending a boot.
Capture both streams: read-backs on stdout, refusals, mutation verdicts, and
capture confirmations on stderr. Blank lines and `#` lines are skipped.
A look-at-one-part script:
```
view.override layout <layout>
world.row.set creations moth document.shapes[name=torso].scale [0.17,0.30,0.13]
world.wait 4
world.row creations moth document.shapes[name=torso]
world.screenshot out/moth.png
world.wait 4
```
## Offline verbs
Run every verb from your lane's private copy of the head's CLI. The
`creation` and `mesh` verbs read a `.puck` source directly, compiling it in
memory with its relative `basis` resolved from the source's directory; a
compiled `.world.json` written somewhere else loses that basis and fails to
load.
```bash
puck compile <file>.puck --validate
puck lint <file>.puck --strict
```
`compile --validate` runs document-level validation: the panel/trim/cells
creation-scope refusal fires here (it walks every `prototypes[]` row
unconditionally, whether or not a placement uses it). No shape-count ceiling
exists: `CreationDocument.StampShapeCount` only reports bake work. It does **not** run emission or contact construction — `Morph` and
similar PopField-only blends validate here and only fail at the next step;
a Path prism profile under a `solid` placement, and a residual
nonuniform `Scale`, likewise surface only there.
```bash
puck creation stats --world <path> [--prototype <id>]
puck creation shape --world <path> --prototype <id> [--shape <name>...]
```
`creation stats` loads and validates the whole document, then prints
`[<id>] shapes: N, expanded field shapes: M`, histograms by primitive and blend,
counts by facet, and palette slot usage. It then emits text-free prototypes at
unit placement scale through the static path (when applicable) and pooled
rest-pose path, reporting bake groups, field instructions, encoded program and
pose bytes, and global and scoped/shared clamps. There is no shape-count ceiling;
read actual mesh bytes and bake counts from `world.budget` after `world.wait bakes`.
Exit 1 covers
validation refusal **or emission inspection failure**; 2 is a usage error.
Text-bearing prototypes explicitly report that a resolved font atlas is needed
and defer clamp inspection to live `world.budget`.
`Morph`, `StairsUnion`, and `StairsSubtraction` are defined enum values:
raw document validation accepts them, but static shape emission rejects them
as PopField-only composition. Text-free stats catches that failure when the
selected path forwards the blend. Animated ungrouped shapes take pooled Union
defaults, so their unsupported authored blend can still appear in a histogram
with exit 0. Stats proves neither authored-blend preservation across paths,
live motion, nor rendered appearance.
`creation shape --world <path> --prototype <id> [--shape <name>...]` and its
live twin `creation.shape <prototype> [<shape-name>...]` (headless too) read
each shape off its own lowering: `lowered=` (what the renderer emits for it
alone), `distance=exact | bound gain=<g> | uncertified`, `step=` when a warp
clamps the march, `cpu=` (whether the fixed-point evaluator reads the render lowering as the renderer draws it, the reading `mesh audit` measures a bake against) and `contact=`
(admitted with `contact-omits=`, omitted, or refused and why). A `bound` is a
field that underestimates: `|grad d|` lies in `[g, 1]`, from a non-uniform
`Scale` the primitive has no native spelling for (a capsule, cone or torus
scaled apart in X and Z) or the superellipsoid gauge an ellipsoid lowers to.
A bound keeps the authored zero set and its gradient's direction, so the bake
contours the right surface; contact refuses the residual `Scale` and admits the
gauge. To see a field rather than read it,
`world.slice <placement> <x|y|z> <path.png>` writes the distance bands and the
`|grad d|` panel through the running World (see the `Puck.World` README).
The live `creation.sculpts` and `creation.sculpt <name>` console verbs patch the
live document all-or-nothing.
## Authoring in C# instead of JSON — a live but unused path
`src/Puck.World.Authoring/Sculpting/` carries a builder for programmatic
sculpting. It is real infrastructure — `CreationBuilder`'s topological
invariants (parents declared before children, ids unique, `Mirror` always
emitting `Left` before `Right`) are enforced and covered by
`tests/Puck.World.Schema.Tests/CreationBuilderLawTests.cs`, and the live
`creation.sculpts`/`creation.sculpt` console verbs are wired and working. But **no shipped creation is authored
through it today**: `CreationSculptRegistry` ships with zero sculpts
registered (a sculpt is registered by a composition root or a test), and nothing
in the tree calls `new CreationBuilder(...)` outside that law-test suite.
`moth.puck`'s hand-authored `shape` statements are `.puck` DSL source, not
`CreationBuilder` output.
Prefer `.puck` for hand-authoring a character, armor, or prop — it is the
checked-in convention every shipped creation follows, and the loop above
already covers it. Reach for `CreationBuilder` only for programmatic or
parametric generation (mirrored rigs from one authoring expression, a
patch applied by a tool or test) where the DSL's `for`/lambda builtins
would not fit, and register the result through `ICreationSculpt` so
`creation.sculpt` can apply and validate it.
| Type | Use |
|---|---|
| `CreationBuilder` | `Shape(...)`, `Chain(...)`, `Mirror(side => …)` with `Left`/`Right` sides that suffix names `L`/`R`, `Palette`/`PaletteSlot`, `Frame`, `SymmetryX`, `FixedId`, `Find`/`TryFind`, `TryValidateTopology`, `Build()`. Rotations must come from the interned helpers (`AxisAngleDegrees`, `Multiply`, `Identity`); a non-interned quaternion is refused. Auto ids start at 100 |
| `StateHoisting` | lifts literal rotations, scales, joints, and tuning values out into state rows so they become live-editable. Idempotent |
| `SculptPatch` | `UpsertRow`, `RemoveRow`, `SetMember`, `RemoveMember`, `Apply(JsonObject)` — JSON only, no schema dependency |
| `PatchPath` | dotted segments with one `[field=value]` selector each, e.g. `looks.rows[name=moth].motion.poses` |
| `ICreationSculpt` / `CreationSculptRegistry` | `Sculpt(SculptContext) → SculptPatch`; the context exposes the whole world as a `JsonObject` plus `TryGetCreationDocument(prototypeId)` |
The builder refuses a parent that is not yet declared:
`shape '<name>' names parent '<parent>', which is not yet declared — declare parents before children.`
## Verifying a change
1. For a `.puck` source, `puck compile --validate` first — it catches
structure, budget, and scope refusals before spending a `creation stats`
or a boot on them.
2. `creation stats` — distinguish whole-document validation and budget from
the separate static/pooled emission inspection; inspect clamp diagnostics.
3. Run the game and capture. A claim about how something reads is not verified
until you have looked at the image.
4. If the placement carries a `solid` row, distinguish named refusals from
accepted facets omitted by contact emission. Check contact explicitly;
successful validation alone does not prove the picture matches collision.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| 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: 198k | Updated | Claude CodeCodex | Verified | Install |
| 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: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| 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: 194k | Updated | Claude CodeCodex | Verified | Install |