Skip to content

ByteTerrace/Puck / .claude/skills/sdf-authoring

sdf-authoring

Verified

Authors 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.

FileKindSize
SKILL.mdskill md28.6 KB
evals/s01-blocky-pauldron/graders/author-frame-kept.mdmarkdown250 B
evals/s01-blocky-pauldron/graders/curvature-from-curved-primitives.mdmarkdown180 B
evals/s01-blocky-pauldron/graders/edge-operation.mdmarkdown124 B
evals/s01-blocky-pauldron/graders/names-the-checks.mdmarkdown74 B
evals/s01-blocky-pauldron/graders/shape-count.mdmarkdown188 B
evals/s01-blocky-pauldron/graders/skill-fired.mdmarkdown36 B
evals/s01-blocky-pauldron/graders/sleek-exponent-band.mdmarkdown300 B
evals/s01-blocky-pauldron/prompt.mdmarkdown1.2 KB
evals/s02-damage-plates/graders/bottom-to-top-erosion.mdmarkdown157 B
evals/s02-damage-plates/graders/erosion-is-baked.mdmarkdown205 B
evals/s02-damage-plates/graders/lane-reads-bare-hp.mdmarkdown168 B
evals/s02-damage-plates/graders/no-engine-health.mdmarkdown164 B
evals/s02-damage-plates/graders/skill-fired.mdmarkdown36 B
evals/s02-damage-plates/graders/undersuit-remains.mdmarkdown72 B
evals/s02-damage-plates/graders/weathering-before-erosion.mdmarkdown152 B
evals/s02-damage-plates/graders/weathering-reads-live.mdmarkdown145 B
evals/s02-damage-plates/graders/weathering-with-under.mdmarkdown93 B
evals/s02-damage-plates/prompt.mdmarkdown1.6 KB
evals/s03-wrong-shoulder-and-soft-model/graders/author-frame-yaw.mdmarkdown127 B
evals/s03-wrong-shoulder-and-soft-model/graders/clamps-versus-global-scale.mdmarkdown131 B
evals/s03-wrong-shoulder-and-soft-model/graders/inspect-clamp-diagnostics.mdmarkdown115 B
evals/s03-wrong-shoulder-and-soft-model/graders/no-flare-always-softens.mdmarkdown112 B
evals/s03-wrong-shoulder-and-soft-model/graders/plus-x-is-the-subjects-left.mdmarkdown98 B
evals/s03-wrong-shoulder-and-soft-model/graders/skill-fired.mdmarkdown36 B
evals/s03-wrong-shoulder-and-soft-model/graders/two-diagnoses.mdmarkdown89 B
evals/s03-wrong-shoulder-and-soft-model/prompt.mdmarkdown368 B
evals/s04-flat-plastic/graders/eye-stops.mdmarkdown113 B
evals/s04-flat-plastic/graders/inset-eye.mdmarkdown155 B
evals/s04-flat-plastic/graders/painted-metal-armor.mdmarkdown135 B
evals/s04-flat-plastic/graders/skill-fired.mdmarkdown36 B
evals/s04-flat-plastic/graders/sky-panels.mdmarkdown147 B
evals/s04-flat-plastic/graders/unit-range-fields.mdmarkdown135 B
evals/s04-flat-plastic/prompt.mdmarkdown1.1 KB
evals/s05-hull-seam/graders/cutter-removed.mdmarkdown109 B
evals/s05-hull-seam/graders/groove-blend.mdmarkdown82 B
evals/s05-hull-seam/graders/groove-does-not-restore-panels.mdmarkdown207 B
evals/s05-hull-seam/graders/panel-remedy.mdmarkdown156 B
evals/s05-hull-seam/graders/separates-the-problems.mdmarkdown111 B
evals/s05-hull-seam/graders/skill-fired.mdmarkdown36 B
evals/s05-hull-seam/prompt.mdmarkdown1.1 KB
evals/s06-fin-stack/graders/domain-fold.mdmarkdown194 B
evals/s06-fin-stack/graders/fin-count-preserved.mdmarkdown96 B
evals/s06-fin-stack/graders/not-limit-twelve.mdmarkdown102 B
evals/s06-fin-stack/graders/shape-count-drops.mdmarkdown139 B
evals/s06-fin-stack/graders/skill-fired.mdmarkdown36 B
evals/s06-fin-stack/prompt.mdmarkdown2.1 KB
evals/s07-over-budget/graders/already-refuses-with-puck030.mdmarkdown189 B
evals/s07-over-budget/graders/budget-arithmetic.mdmarkdown194 B
evals/s07-over-budget/graders/creation-stats-under-budget.mdmarkdown227 B
evals/s07-over-budget/graders/detail-flags-do-not-save.mdmarkdown159 B
evals/s07-over-budget/graders/shape-count-levers.mdmarkdown217 B
evals/s07-over-budget/graders/skill-fired.mdmarkdown36 B
evals/s07-over-budget/prompt.mdmarkdown1.0 KB
evals/s08-subtraction-trap/graders/bore-is-the-cause.mdmarkdown118 B
evals/s08-subtraction-trap/graders/creation-scope-rule.mdmarkdown199 B
evals/s08-subtraction-trap/graders/fixture-already-refuses.mdmarkdown165 B
evals/s08-subtraction-trap/graders/no-scope-bypass.mdmarkdown113 B
evals/s08-subtraction-trap/graders/offers-a-remedy.mdmarkdown149 B
evals/s08-subtraction-trap/graders/skill-fired.mdmarkdown36 B
evals/s08-subtraction-trap/prompt.mdmarkdown1.4 KB
evals/s09-contact-mismatch/graders/admitted-near-outline.mdmarkdown252 B
evals/s09-contact-mismatch/graders/creation-stats-builds-contact.mdmarkdown196 B
evals/s09-contact-mismatch/graders/keeps-the-solid-placement.mdmarkdown69 B
evals/s09-contact-mismatch/graders/path-cause.mdmarkdown219 B
evals/s09-contact-mismatch/graders/renderer-not-at-fault.mdmarkdown85 B
evals/s09-contact-mismatch/graders/skill-fired.mdmarkdown36 B
evals/s09-contact-mismatch/prompt.mdmarkdown1.5 KB
evals/s10-morph-blend/graders/accepted-then-emission-fails.mdmarkdown154 B
evals/s10-morph-blend/graders/creation-stats-catches-it.mdmarkdown133 B
evals/s10-morph-blend/graders/morph-exists.mdmarkdown83 B
evals/s10-morph-blend/graders/pop-only-compose.mdmarkdown152 B
evals/s10-morph-blend/graders/shape-level-blend.mdmarkdown180 B
evals/s10-morph-blend/graders/skill-fired.mdmarkdown36 B
evals/s10-morph-blend/graders/validate-alone-misses-it.mdmarkdown149 B
evals/s10-morph-blend/prompt.mdmarkdown270 B
evals/s11-sweep-cable/graders/bezier-between-brackets.mdmarkdown98 B
evals/s11-sweep-cable/graders/curve-limits.mdmarkdown150 B
evals/s11-sweep-cable/graders/names-the-checks.mdmarkdown74 B
evals/s11-sweep-cable/graders/skill-fired.mdmarkdown36 B
evals/s11-sweep-cable/graders/sweep-with-a-curve.mdmarkdown113 B
evals/s11-sweep-cable/graders/uniform-scale.mdmarkdown132 B
evals/s11-sweep-cable/prompt.mdmarkdown976 B
evals/s12-live-tweak-and-capture/graders/reads-the-row-back.mdmarkdown84 B
evals/s12-live-tweak-and-capture/graders/row-set-on-creations.mdmarkdown162 B
evals/s12-live-tweak-and-capture/graders/save-to-a-json-path.mdmarkdown214 B
evals/s12-live-tweak-and-capture/graders/screenshot-fenced-by-wait.mdmarkdown162 B
evals/s12-live-tweak-and-capture/graders/skill-fired.mdmarkdown36 B
evals/s12-live-tweak-and-capture/graders/structural-check.mdmarkdown101 B
evals/s12-live-tweak-and-capture/graders/verbs-exist.mdmarkdown67 B
evals/s12-live-tweak-and-capture/graders/whole-array-row-set.mdmarkdown174 B
evals/s12-live-tweak-and-capture/prompt.mdmarkdown300 B
evals/s13-stripe-and-mouth-paints/graders/mouth-sweep.mdmarkdown149 B
evals/s13-stripe-and-mouth-paints/graders/paints-block.mdmarkdown68 B
evals/s13-stripe-and-mouth-paints/graders/parented-to-helmet.mdmarkdown105 B
evals/s13-stripe-and-mouth-paints/graders/relief-frays.mdmarkdown211 B
evals/s13-stripe-and-mouth-paints/graders/skill-fired.mdmarkdown36 B
evals/s13-stripe-and-mouth-paints/graders/stripe-stroked-plane.mdmarkdown141 B
evals/s13-stripe-and-mouth-paints/graders/uses-paints.mdmarkdown128 B
evals/s13-stripe-and-mouth-paints/prompt.mdmarkdown804 B
references/composition.mdmarkdown13.5 KB
references/loop.mdmarkdown11.5 KB
references/rig.mdmarkdown31.5 KB
references/shapes.mdmarkdown18.4 KB
references/surface.mdmarkdown26.8 KB

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