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/composition.md

View on GitHub
# Blends, folds, scopes, and the budget

## Blends

In static emission, `shapes[].blend` selects how a shape composes with
everything accumulated before it. Rigid bodies share that local geometry. In the articulated body path, ungrouped shapes
are emitted with default Union and zero smooth; put interacting shapes in
the same nonzero `group` to carry their authored blends and radii. Groups
also affect ordering and scope ownership; inspect both emission paths.

`shapes[].smooth` carries the radius for every family that takes one,
clamped to [0, 0.5].

| Blend | Formula | Radius lane |
|---|---|---|
| `Union` | `min(a, b)` | — |
| `SmoothUnion` | polynomial smooth min | `smooth` |
| `Subtraction` | `max(a, −b)` | — |
| `Intersection` | `max(a, b)` — **against the whole accumulator**, not the previous shape | — |
| `Xor` | symmetric difference | — |
| `SmoothIntersection` | filleted intersection | `smooth` |
| `SmoothSubtraction` | filleted carve | `smooth` |
| `ChamferUnion` / `ChamferIntersection` / `ChamferSubtraction` | 45° bevel seam | `smooth` |
| `GrooveUnion` | `max(min(a,b), r − √(a²+b²))` — a round seam carved along the intersection curve | `smooth` |
| `PipeUnion` | `min(a, b, √(a²+b²) − r)` — a round bead along that curve | `smooth` |
| `GrooveSubtraction` | `max(a, −b, r − √(a²+b²))` | `smooth` |
| `PipeSubtraction` | `min(max(a,−b), √(a²+b²) − r)` | `smooth` |

`StairsUnion`, `StairsSubtraction` and `Morph` compose only at a field-scope
pop, so a shape carrying one opens a scope of its own, inside its creation's
or group's scope too (`ShapeScope`), and composes at that pop: a stairs blend
climbs `steps` (1 to 64, default 4) over its `smooth` radius, which must be
above zero, and a morph blend takes a `morph { lane, from, to }` facet and
interpolates the field before the shape with the shape as the riding slot's
lane runs from `from` to `to` (a static placement reads the lane as zero). The
VM holds four scope levels, so a grouped shape of a text-bearing animated
creation can nest its shape scope inside the group and creation scopes. The
gallery's `shape-stairs-union`, `shape-stairs-subtraction` and `shape-morph`
show them.

A groove follows the two fields' intersection and can replace a separate cutter.
It does **not** restore panels, trims, or cells: groove and pipe blends require
the same creation-wide scope as subtraction. Both blend families are supported
by deterministic field contact; panel and trim shorthand is presentation only.

An `Intersection` annihilates every earlier non-overlapping shape, including a
ground plane, and its instance can never be culled by a sphere.

## Domain folds

`shapes[].domain` is up to four folds applied in creation space, after the
creation and placement frame and **before** the shape's own transform. A fold is
one shape drawn many times, not many shapes. In `.puck` each fold is a call in
the `domain` array, applied in order:

```puck
domain [
  symmetry(normal: [1, 0, 0])
  repeat(spacing: [0.1, 1, 1], limit: [2, 0, 0], origin: [-0.15, 0, 0])
]
```

`spacing`, `limit` and `origin` are per-axis vectors; a limit of 0 on an axis
leaves that axis unrepeated. `polar(count: 6, axis: Y)` and
`wallpaper(cell: [1, 1], group: P4M, materialStride: 1)` take the same call
form.

| `$type` | Fields | Contact geometry |
|---|---|---|
| `symmetry` | `normal`, `offset` | expands |
| `repeat` | `spacing`, `limit`, `origin` | only when `limit` is a whole number inside the copy budget; an absent limit is unbounded and does not expand |
| `polar` | `count`, `axis`, `mirror`, `materialStride`, `origin` | expands, one rigid copy per sector |
| `wallpaper` | `group` (a mirror group: PMM, P4M, P3M1 or P6M), `cell`, `limit`, `plane`, `materialStride` | **never — render only**; a solid row carrying one is refused by name |
| `jitter` | `spacing`, `amount` (peak-to-peak hashed displacement, under the least spacing), `seed`, `tumble` (0..1 of a half turn), `materialVariants`, `flavor` (White, Blue, Gaussian), `origin` | **never — render only**; a hashed copy per cell. Keep `amount / 2 + the shape's reach` under half the least spacing or the program refuses it at build |
| `logSphere` | `shellRatio` (above 1.05), `twist` (radians per shell about Z), `origin` | **never — render only**; a scaled copy per shell. Author the prototype a radius inside the shell `[1/√ratio, √ratio)` of the origin and clip the lattice with an intersection |

A wallpaper fold builds only through a group whose every cell wall and in-cell
seam is a mirror, so its field never reads past the nearest copy; the program
refuses the other thirteen groups by name. Content may cross the mirrors: the
field then reads short, which costs march steps but skips nothing. A square
group's `limit` is a whole number of cells; a hex group (P3M1, P6M) takes none,
since a hex lattice has no continuous clamp, so bound a hex wallpaper by
intersecting it with a bounding shape inside a field scope (`PushField`); the
instance's cull bound then composes through the blends (`SdfBoundAlgebra`), so
the clipped lattice is as cullable as its clipper, while the same lattice with a
shape unioned in has no bound and is never culled by radius. An absent repeat
limit is unbounded the same way. A `cell` is refused when its reciprocal exceeds 1e18.
Clip a kaleidoscope, a repeat or a jitter along its mirror planes or cell
walls (a box or a hexagonal prism whose faces are mirrors), never with a round
clip: a round wall meets some copy's face within a millimetre or two, and the
sliver between them is thinner than any bake cell, so the contour folds it into
a crease the audit reports as hundreds of turned triangles on the wall (the
gallery's hex wallpapers and clipped beads).

Mirror a part with a `symmetry` fold, never with a negative scale — negative
scale components are refused by name because emission reads magnitudes.

A symmetry plane satisfies `dot(p, normal) = -offset`: the shader tests
`dot(p, normal) + offset < 0`. For a +Y normal and author y = 0.99, use
`offset: -0.99`.

A bounded integer repeat spans `-limit..+limit`, giving `2*limit+1`
cells per repeated axis. A limit of 12 gives 25, not 12. Even counts need a
composition, such as two disjoint odd repeats, an odd repeat plus one endpoint,
or symmetry over a correctly positioned half-pattern. Preserve positions as
well as the count.

A polar fold centres its first sector on the folded shape's own position
about the axis (`SdfDomainOp.Polar.Subject`), so a shape authored at any angle
draws one copy per sector, as contact expands it; content wider than a sector
is still cut at the sector walls. A mirrored polar fold reflects across the
plane through the axis and the shape.

Cell centres lie at multiples of spacing from `origin`; a primitive displaced
half a cell from that lattice can be sliced. Centre the fold on the primitive
in the fold's coordinate frame and leave enough cell width for its extent.
The current `CreationFrame` converts symmetry normals but leaves repeat/polar
origins unchanged, so for an unrotated placement an author-space position
`[x,y,z]` needs origin `[-x,y,-z]` to coincide with its engine-space centre.
Do not blindly copy a nonzero author X/Z position into `origin`.

A shape carrying folds may not also carry a swing or a slide, may not carry a
`panel`, may not be the reference of a trim, and may not be a chain bone: a fold
rides its parent's frame, never a solve or a swing of its own, and its fold
already owns the point, so a panel has no scope left to nest into.

That panel exclusion decides most budget questions, because folding repetition
and dropping panel copies are the two cheapest levers and they do not compose:
a panelled shape cannot be folded, so fold the unpanelled copies and leave the
panelled ones hand-placed.

## Panels and trims

Both are render-only detail that reuses a shape's own geometry.

`panel` is `{ inset, depth, material, face }`. It erodes a copy of the plate by
`inset`, then recesses it (positive `depth`, a subtraction) or raises it
(negative, a union) along `face`, which defaults to local +Z. `inset` may not
exceed the shape's smallest local half-extent; `|depth|` may not exceed the
eroded copy's full extent along the face.

`face` is normalized; null means +Z, and a zero-length face is refused by name.
`inset` and `depth` are creation units that the animated pool scales by the
placement. `ShapePanelDocument.Resolve` is the one derivation both emission paths
read, and the static probe reserves two chains per panelled shape
(`CreationStampEmitter.PerCopyInstanceCount`). The contact field never reads a
panel, so a panelled solid placement's collider is unchanged. A panel is refused
by name on a `Plane`. Verify with `ShapePanelLawTests`.

`trims` is up to four `{ shape, width, material, inset }`. Each re-reads an
**earlier** shape's primitive geometry and pose and lays a band of `width` along
it. The referenced shape may carry neither domain folds nor a group, because a
trim's copy could not follow either. Both the host copy and reference copy
rebuild fresh primitive/pose chains without warp operations. On a warped host
or reference, the trim can paint an unwarped ghost shell. Use unwarped shapes
for both sides when the band must follow the rendered surface.

## The three scope rules

The builder allows four levels of field scope. Creation shape and group emission
uses its shared-scope rules below; nested text, group and shape scopes fit without
flattening independent groups.

**1. A shape takes its own scope** when it carries any of `dilate`, `onion`,
`panel`, `flare`, `shear`, `bumps`, `erode`, or `cells`. Squashing a sphere or
ellipsoid never does: every ellipsoid is the 1-Lipschitz exponent-2
superellipsoid gauge, whatever its scale, a bound that never oversteps. The scope clamps that shape's Lipschitz factor onto
its own candidate. A hard field can clamp each shape at the blend. When a
smooth blend or relief reads the candidate's magnitude, its enclosing pop
owns the bound and all of the scope's members share the clamp. An unscoped
magnitude-reading field keeps a residual CPU query bound. Shorter steps can
affect convergence and the apparent hit threshold.

**2. A group takes one scope for all its members** when any member wants one.
The creation emitter does not lower `panel`, `trims`, or `cells` as grouped
members, so those combinations remain refused by name.

Only the articulated body path reads `group` at all. Static and rigid template emission walk the shape
list in declaration order and never looks at it, so on a static placement a group
isolates nothing and every `Subtraction` composes against the whole creation
accumulator — order each cut to be spatially local instead. `creation stats`
shows the difference directly: its `static:` line reports one scope over all
shapes where `pooled:` reports one per group.
Text-bearing pooled creations wrap those groups and their text in one outer
scope and one dynamic instance. Engraving therefore cuts the creation, never
another placement, and a group's cutter still affects only that group.

**3. Static emission takes a creation scope** when it has a `noise` facet, an
engraved text run, **or any shape blend outside `Union` and `SmoothUnion`**.
The document admission rule uses that same predicate for all placements:
`panel`,
`trims`, and `cells` are refused on **every** shape in the creation.

A single `Subtraction`, groove, or pipe blend costs panels, trims, and cellular
relief throughout that creation. Keep `Union`/`SmoothUnion` and use `panel`,
use trims where admitted, or split prototypes. If already scoped, replace panel
shorthand with explicit cutters: they charge shapes, but require no extra depth.
Removing panel shorthand does not restore trims or cells while the outer
scope remains.

Warps (`flare`, `shear`, `bumps`, `erode`) accept the enclosing clamp;
`panel`, `trims`, and `cells` refuse by name when isolation is unavailable.
The silent part is admission, not inspection: `creation stats` reports
text-free static/pooled rest-pose scoped clamps, shared shape counts, and the
global step scale. `world.budget` reports the live program's scoped/shared
summary and worst clamp. Global scale 1 does not mean every scope is unit.
These are field bounds, not measured GPU timings; capture the running game to
judge appearance.

Erosion emits on both branches — the shape's own scope and the enclosing one —
so a shape inside a group or creation scope shares that pop's clamp rather than
losing the facet. What a static placement lacks is a lane to drive it: static,
animated, and attached registrations supply zero-valued lanes, so a static
erosion resolves at zero. Even on an inhabited placement erosion is baked: it
holds the lanes the bake read when the program last changed, so it cannot
follow live state ([render lanes](surface.md#render-lanes)).

## Bake work and bytes

Rigid creation copies share one local bake and palette. Each live copy owns one root transform and one draw; articulated creations add only independently moving part slots. Storage grows from the live world, without a fixed registration or per-creation shape budget. Catalog geometry emits only for looks in use, with detail chosen by projected size. The actual render envelope, GPU draw/vertex counters, baked groups and resident bytes describe the cost. Scope depth is 4, screen bindings 32 and bounded volumes 64; representation overflow refuses explicitly.

Panels expand to two field shapes, trims add two operands each, and glyphs add one per visible character. These are bake work, reported by creation stats alongside program bytes. Actual mesh bytes are read from the running bake, never guessed from shape count.
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