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.
SKILL.md
View on GitHub---
name: sdf-authoring
description: "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."
---
# Authoring a Puck creation
A creation is a `puck.creation.v1` document: a palette, a list of shapes, and
optional rig, motion, text, volume, and noise sections. Shapes are signed
distance fields composed by blends, not meshes: a cut is a subtraction, a
fillet is a blend radius, and repetition is a fold rather than copies.
**Where it lives.** On disk in a world document at `prototypes[].document`. The
console addresses those same rows as section **`creations`**, keyed by prototype
id: `world.row.set creations moth …` edits what the file spells
`prototypes[id=moth].document`. Read `references/loop.md` before driving it
live.
## The author frame
Every creation position, rotation, joint, pivot, axis, and camera offset is
authored in one frame that is a **180° yaw about +Y away from the engine's**:
| Author axis | Points |
|---|---|
| +Y | up |
| +Z | the front the subject faces, toward a front-facing camera |
| +X | screen-right as you look at that front, which is the subject's own **left** |
So a shape authored at +X appears on the viewer's right, on the character's left
side. Getting this backwards is the most expensive mistake in this surface, and
it looks like a correct sculpt mirrored rather than like a bug. The conversion
is exact axis negation, `(x, y, z) → (−x, y, −z)`, and it is its own inverse
(`src/Puck.World.Authoring/Authoring/CreationFrame.cs`). The frame is a document
fact: it applies identically in raw JSON and in a `.puck` shape row.
Scalars, camera yaw and pitch, and chain goal and pole do **not** convert.
Shape position, rotation, and joint convert; `curve.a/b/c` remain shape-local
and ride that converted pose. Repeat and polar fold origins do not convert, so
an author-space position `[x, y, z]` needs origin `[-x, y, -z]`
([composition](references/composition.md#domain-folds)). Palette
`inset.origin` and `inset.rotation` do not convert either: author them in the
shader's winning frame ([surface](references/surface.md#inset)).
[rig](references/rig.md#what-crosses-the-author-frame) lists every field.
## Authoring in `.puck`
`.puck` is the checked-in source for shipped creations:
`worlds/debug/avatars/moth.puck` sculpts the whole Moth as
`shape` rows inside `prototypes { prototype "moth" { document { } } }`. A shape
row is `shape Type "name" { field: value ... }`: array-valued fields take
brackets with no colon (`position [0, 1.02, 0]`, `scale [x, y, z]`), scalar
fields take a colon (`material: charcoal`, `exponent: softness`), and
`let name = value` binds a reusable constant; the Moth names its palette slots
this way (`let charcoal = 2`, then `material: charcoal`). `profile`, `domain`,
`swings`, `slides`, `panel`, `curve` and every other per-shape facet are
ordinary nested blocks with the same field names the JSON form uses. The
grammar, `let`/`template`/`for` and the CLI verbs belong to `puck-dsl`; load it
before writing `.puck` source beyond shape rows.
Check an edit offline before booting it, straight from the source:
```bash
puck compile <file>.puck --validate
puck creation stats --world <file>.puck --prototype <id>
```
`compile --validate` runs document validation: representation guards and the
panel/trim/cells creation-scope refusal fire here (PUCK030), over every
`prototypes[]` document whether or not a placement uses it. It does **not** run
emission or contact construction, so the Path contact refusal and a residual
nonuniform `Scale` on a solid placement pass it and fail only under
`creation stats`.
`creation stats`, `creation shape` and `mesh audit` read a `.puck` source
directly, compiling it in memory with its relative `basis` resolved from the
source's own directory; a compiled JSON copied elsewhere loses that basis.
`puck decompile` is one-way: it discards every `let`, `template`, and `for`.
Decompile once to import a hand-authored JSON document, then edit the `.puck`.
## The loop
A world booted with `--world <file>.puck` transpiles in memory
(`PuckWorldLoader`), and authoring against that live process needs no restart:
```
world.row.set creations <id> document.shapes[name=<shape>].<field> <json>
world.row creations <id> document.shapes[name=<shape>]
world.wait <ticks>
world.screenshot <abs-path.png>
```
`world.row.set` replaces a whole field: a vector such as `scale` or `position`
takes the full `[x, y, z]`, a rotation the full quaternion.
`world.row.step creations.<id>.document.shapes[name=<shape>].<field> <delta>`
steps a numeric scalar and refuses a vector. `world.row` reads the field back,
so confirm each edit with it. Edits land at the tick boundary, one per row per
tick. A `parent` carries only its animated delta, never its rest pose or
scale, so rescaling a parent moves no child: edit the children's base poses
too.
`world.reload` recompiles the `.puck` from disk (basis chain included) and
discards unsaved row edits; `world.save` writes each live edit into the source
that authors it (an imported file included), retaining unrelated text. A row
generated by a template or
a `for` can be edited live, but `world.save` refuses it by name: edit the
template or loop, or save to a JSON target whose `basis` names the source.
`world.screenshot` only **arms** a capture. Fence it with `world.wait` and
confirm the `[capture] … -> <path>` line on **stderr** before reading the file.
Read-backs land on stdout, refusals and capture confirmations on stderr, so
capture both streams. The verb surface, the offscreen recipe, and the sculpting
library are in `references/loop.md`.
## Choosing geometry
The vocabulary is much wider than sphere-box-cylinder, and reaching for boxes
when a profile or a warp would do is what makes a sculpt read as blocky. Start
from what you want the surface to *do*:
| You want | Reach for | Notes |
|---|---|---|
| A softly swelling mass, squarish or round on demand | `Superellipsoid` + `exponent` 2..8 | 2 is an ellipsoid, 8 is nearly a box; the sleek middle is 2.5–4 |
| A slab with a shaped outline | `Prism` + `profile` | rounded rect, chamfered rect, ellipse, regular polygon, or a convex hull |
| A tapering limb or fin | `Prism` + `taper` | 0 is a triangle, 1 is a rectangle |
| A tube, cable, horn, braid, or lock of hair | `Sweep` + `curve` | quadratic Bézier, tapered radius, bulge, up to 4 helical strands; uniform scale only |
| A part that swells or pinches along its length | `flare` | a scale profile along one axis with a mid-span bulge |
| A leaning or S-curved mass | `shear` | polynomial offset of one axis driven by another |
| A local dent or swelling | `bumps` | up to 4 gaussian pushes |
| An organic wobble over the whole form | `warp` | a bounded sine warp of the point, each axis driven by the next |
| Fine even relief: dimples, corrugation, a hammered skin | `displace` | a sine product added to the field, real geometry |
| A rounded slab, a stadium, a capsule from any primitive | `elongate` | the cross-section swept over a box of half-extents, 1-Lipschitz |
| Scattered, tumbled, recoloured copies | a `jitter` fold | a hashed repeat; render only |
| Self-similar shells, a Droste zoom | a `logSphere` fold | render only |
| Softened edges | `rounding` (curved) or `chamfer` (45° bevel) | never both on one shape |
| A hollow shell | `onion` | |
| Repetition: ribs, teeth, plates, spokes, fins | a `domain` fold | repeat, polar, symmetry, wallpaper; one fold, not N shapes. Refuses a `panel` on the same shape |
| Cellular or faceted relief: scales, chitin, hammered metal | `cells` | needs its own scope; see the scope rules |
| A stripe, ring, panel outline or mouth line | a palette `paints` entry | colour drawn at the hit, never sculpted relief; see "Surface and look" |
Exact scale conventions per primitive (a torus is not what you would guess), the
facet-admission matrix, every ceiling, and every refusal message are in
`references/shapes.md`. Check it before authoring a primitive you have not used
here: `scale` means something different for a torus, a capsule, and a revolved
prism.
In `.puck` a fold is a call in the shape's `domain` array, such as
`domain [ repeat(spacing: [0.1, 1, 1], limit: [2, 0, 0]) ]`, with per-axis
vectors. A bounded repeat spans `-limit..+limit`, so a limit of n draws `2n+1`
copies; an even count needs a composition such as a symmetry fold over an odd
repeat ([composition](references/composition.md#domain-folds)).
## Composition, and the two scope rules that bite
Blends run from `Union` through the smooth and chamfer families to the round
seams: `GrooveUnion` carves a recessed seam along the intersection curve of two
solids, `PipeUnion` lays a bead along it, and both have subtraction twins. Reach
for a groove when the seam should follow that intersection; it removes a
separate cutter shape, but it still forces the creation-wide scope.
`StairsUnion`, `StairsSubtraction` (`steps`) and `Morph` (`morph { lane, from,
to }`) compose at the pop of a scope the shape opens for itself
([composition](references/composition.md#blends)).
Two rules decide whether facets are available at all:
1. **Per-shape scope.** `dilate`, `onion`, `panel`, `twist`, `bend`, `flare`, `shear`, `bumps`,
`warp`, `displace`, `erode`, and `cells` each make the shape request its
own field scope, as does a stairs or morph blend. A
non-uniformly scaled sphere or ellipsoid does not: it bakes into the
1-Lipschitz exponent-2 superellipsoid gauge. A warped shape whose scope is
free clamps only itself at its own pop: `creation stats` shows
its shape clamp, and independent shapes keep their own bounds. A blend or
relief that reads field magnitudes keeps the original candidate distances
inside its scope. The scope clamps its completed field at the pop. Read
the shape and scope counts in `creation stats` before naming the cause of
a soft image.
`ShapePointOps` derives the warp predicate from the point chain's emission
mask; static and pooled scopes, bake partitioning, bounds and detail share it.
2. **The creation-wide scope.** If a creation has a `noise` facet, an engraved
text run, **or any shape blend outside `Union` and `SmoothUnion`**, the whole
static creation emits inside one scope, and `panel`, `trims`, and `cells`
are refused on **every** shape in it, whatever the placement kind.
The second rule surprises people: one `Subtraction` anywhere costs panels,
trims, and cellular relief everywhere, and so does a groove or a pipe. Keep the
creation all-union and use `panel`, or split prototypes. In an already scoped
creation, explicit cutter shapes can replace panel shorthand; each costs shape
budget but no extra scope depth. Groove and pipe blends reach deterministic
field contact; panels and trims do not.
In pooled emission, `group` collects interacting shapes into one instance and
forwards their authored blends; ungrouped shapes use Union defaults, and PUCK131
warns on an ungrouped shape whose authored blend is not `Union`. A group
opens a shared scope when needed, and grouped shapes cannot carry panel, trims,
or cells. Static emission ignores `group` and walks the list in order, so a
group cannot keep a subtraction off its siblings on a static placement. The VM
admits four scope levels. [composition](references/composition.md) has the
formulas, folds, groups, panels, trims and shared-clamp diagnostics.
## Bake work and residency
There is no per-creation shape cap or fixed registration pool. A rigid creation
bakes once in its own space; its bodies share that geometry and palette, with one
root transform and draw each. Independently moving parts add transform slots;
static shapes in a part share its slot. Spawning rigid copies does not rebuild
the field program. Catalog looks emit only for bodies wearing them, at detail
chosen by projected size.
Panels expand to two field operands, trims to two more each, and glyphs to one
per non-whitespace glyph. These increase bake work rather than consume a stamp
budget. `puck creation stats` reports field instructions, bake groups and encoded
bytes. Read actual mesh vertices, draws, baked groups and resident bytes from
`world.counters gpu` and `world.budget` after the bake settles. `detail: true`
saves contact work; its render field still bakes normally. Edit-to-running stays
under 30 seconds, checked on a quiet machine by the lead.
The limits retained protect representations or per-pixel work: 255 skin members
per bake group (`SdfSkinLimits.MaxMembers`; validation refuses a group whose
skinned seams ride more, naming the group, before any bake), 24-bit GPU indices, the material sentinel, 64 bounded volumes and 32
screen bindings. Scopes nest to 4.
Derived faces follow the world's highest authored screen index.
## Surface and look
The palette (up to 32 slots) carries far more than a colour: `specular`,
`roughness`, `metal`, `coat`, `sheen`, `emissive` (switched by a render lane
with `emissiveLane`), `wrap` and `soften` for skin, `fill` for a warm interior
fill, `weathering` for chips and scratches over a revealed `under` substrate,
`inset` for a refracted layer beneath the surface (how an eye is authored: a
radial paint ramp of pupil, iris, limbus and sclera stops under a cornea, not a
dark sphere), and `paints` for detail that is colour rather than form: stripes,
trims, panel outlines, a mouth line. A paint is drawn crisp at the hit; relief
finer than the bake's cell (15 mm on flat faces, refined toward each shape's own
round sections, roundings and thickness, down to 2 mm) frays into
jagged steps, so never sculpt a millimetre-proud stripe. Painted metal and
clearcoat read only against something to reflect: the world's sky `panel`
highlights. Ranges, defaults and examples are in `references/surface.md`.
## Binding to state
Nothing in the renderer knows what health, charge, or speed are. A surface
reads eight anonymous **render lanes** by index. Lanes 0 to 3 are body lanes: a
look row's up to four expressions over world state, supplied only by body
registration (an inhabited placement needs a look, kit, and body capacity);
static, animated, and attached placements read them as zero. Use bare `hp` or
`airPose[$body]` in a lane, and `bodyState($body, flightFuel)` for one of the
body's own action-state slots; `state.hp` is driver/binding spelling and reads
the wrong row here. Lanes 4 to 7 are world lanes: `render.lanes`, up to four
bindable scalars (`"state.fallsFlow"`), which every surface reads alike,
static copies included. Shapes and materials read a lane by index:
| Consumer | Reads the lane |
|---|---|
| `shapes[].erode` | in the bake, body lanes only: erodes a shape away over a lane range with a ragged front, frozen at the value the bake read |
| `palette[].weathering.lane` | at shading time, every frame: chips and scratches, with a static floor |
| `palette[].emissiveLane` | at shading time, every frame: `emissive × saturate(lane)` |
| `palette[].flow.region` | at shading time: vary the built-in flow velocity near an authored world-space centre |
| `palette[].flow.lane`, `.coverageLane` | at shading time, every frame: the flow's speed and its revealed coverage |
| `volumes[].intensityLane` | at shading time, every frame |
Erosion is geometry, and every view draws baked meshes. A bake reads the lanes
when a new program arrives (at boot, usually 0), and the mesh keeps that
erosion until the program next changes; a lane change alone never rebakes. So
**erode cannot show or hide a part live**, and a part that only appears as its
lane rises bakes empty. Show live state with weathering, `emissiveLane` and
volume intensity, or move a part away with rig motion driven by a state row.
See [surface](references/surface.md#render-lanes).
Author the meaning in the document's own cell names and the lane expression; the
engine only ever sees a number. A reversed `from`/`to` range runs the fold
backwards.
## Making it move
`parent` is the skeleton: it names an **earlier** shape whose animated motion
carries this one, so chains resolve in one pass and can never cycle. On top of
that, `swings` rotate about a pivot and `slides` translate,
both driven by a named `driver` reading a signal or a state row (`state.hp`).
Directional locomotion reads `travelDirection` and the planar accelerations,
and a driver naming a world `dynamics` row trails and settles instead of
tracking. A driver can ride an earlier driver's cycle (`driver.<name>`) and
scale its cadence or weight by a world `curves` row (`cadenceBy`, `weightBy`).
`chains` plus `effectors` give CCD inverse kinematics with plant windows for
feet, a `replant` latch, and `align`. `frames` snapshot base poses. A behaviour
the vocabulary cannot express is a new signal, member or op, never a client
special case. A shape carrying `domain` folds may not also carry a swing or
slide. Details, caps, every refusal, and the Moth's driver map are in
`references/rig.md`.
A relief takes `masks`, regions drawn with shapes that scale its displacement down
(`CreationReliefMaskDocument`: `fade`, `start`, `inside`, `outside`, `shapes`): with `inside: 0` the relief is exactly
zero on and inside a region, so a carve or pad that is also its own region keeps its authored surface, in the bake and
in contact alike. A region shape is a box (unchamfered), a sphere, an ellipsoid, a superellipsoid, a capsule scaled
alike in X and Z or a plane, at a pose, carrying geometry only (no material, blend, group, warp, elongation, profile or
other facet); entries' weights multiply, and a relief takes at most 8 masks and 32 region shapes. The band snaps to a
2⁻¹² grid and the weights to 2⁻¹⁶, and the canonical document stores the snapped values (`SdfReliefBand`). Every
sample of a masked creation evaluates each region, so keep the regions few. They are written through the generic value path (`masks [ { fade: 8, shapes [ { type: "Sphere", … } ] } ]`);
`worlds/standard/terrain.puck`'s `terrainCarveMask` builds one from the rows `terrainBasin` and `terrainCut` carve.
Creation `noise` can ride whole-creation motion, including `sizeBy`, attached roots and body looks.
The relief bakes once over the composed field in the root's units and keeps its amplitude and wavelength
under root scaling. Parts that move within that frame refuse it (`CreationMotionPlan`, PUCK030): per-part
relief would change the composed surface at their seams. A moving cutter counts as such a part today. `sizeBy` reads a numeric state binding in authority fixed point; solid contact and the drawn root share the tick's sampled size, and zero removes contact.
**Blends between shapes that move apart (owner's ruling).** A pooled `group`
whose blend joins shapes with different motion owners (a swing, slide, effector
chain or frame not shared through `parent`) bakes once at the authored rest. A
smooth blend whose motion stays inside its admitted envelope skins: each vertex
near the seam blends its two owners' motions, so the seam holds while they
move. Any other such blend splits the group by owner, and it draws as a crease.
A carve (a subtraction or intersection) of one owner on another owner's
surface keeps the cut it makes at rest, wherever the cutter moves
([moving blends' gap 8](../../../docs/plans/moving-blends.md#gap-8-a-cutter-that-moves-against-the-surface-it-cuts)
designs the fix). It is a warning, not an error: PUCK122 in
`puck compile --validate`, `puck lint` and `puck creation stats` names the
creation, the two shapes, what moves each, the blend and the outcome
(`CreationMotion.MovingBlends`, `CreationMotion.Describe`). When a seam outside
the envelope must hold, give the shapes one owner: put the swing or slide on a
shape both parent under, or widen `smooth` as PUCK122 says.
## Render-only versus deterministic
A solid placement requiring deterministic field contact refuses `Revolve` and
domain folds that cannot expand; a `Path` prism profile (extruded, a fill or a
stroke) is admitted, since the fixed-point evaluator reads its edge table as
the kernel does. `flare`, `shear`, `bumps`, `erode`, panels,
trims, cells and sweeps validate but are omitted from contact geometry (cells
keep the base primitive). Creation `noise` is not omitted: a relieved creation
collides as the surface its bake draws, one field collider per stamped copy
whose field is the creation's own fixed-point program (its contact shapes and
the relief over their union), so a body stands on the drawn rock
([shapes](references/shapes.md#contact-admission)). For an arched or otherwise convex
outline that must collide, a clockwise `Convex` profile (at most 32 vertices)
or a union of admitted primitives keeps the shape. See
[shapes](references/shapes.md#contact-admission). Every view still renders a
shape contact omits.
CPU cull certificates live in `SdfFieldEvaluator.Cull.cs`. A scoped instance's
lowering candidates include its finite `FarDistance` seed after slack and pop
scaling, not just its shapes. Slack accumulation must fit independently of the
point carrier. `SdfProgram.RequireSegmentsStartAtTheWorldPoint` rejects inherited
moved points across segment and instance boundaries; `ClosesAtScopeEdge` checks
reads within the segment. `SdfCullAdversarialLawTests` compares cull certificates
with the cull-off walk.
## Making it read
A creation is held to [the visual bar](../../../docs/game/art/README.md#the-visual-bar).
What a first swallow taught, in the order it went wrong:
- **References before shapes.** Name the references and the traits to hit
(silhouette, proportion, the two or three marks that say what it is) in the
place's guide first. Guessing numbers from memory took ten passes to reach a
bird that still failed.
- **Sculpt with the shaping vocabulary, not primitive soup.** A body is one
shaped mass (`Superellipsoid` with `flare` and `shear` for a teardrop), not
stacked ellipsoids; an eye is a palette `inset` under a cornea
([surface](references/surface.md#inset)), never a dark sphere, which reads
as a chrome or faceted bead; markings are `paints`, not proud ellipsoids,
which read as stickers or an open mouth from the front.
- **Every shape declares its detail by one rule** (`WorldShapeDetail.Of`), on
a static stamp, in a pooled blend group or alone: its round sections (a
cylinder's and a cone's included), its rounding, its thickness when it is a
plate or folded, and its warps and sine relief (their crests' bend). A blend group's shapes each refine their own
box at their own factor, and only where the surface turns, so grouping a part
to borrow a neighbour's detail is never needed (`puck mesh audit --prototype
<id> --cpu` prints each group's cell and triangles). A section thinner than
the 2 mm floor declares the floor, and a `smooth` blend declares its seam's
radius. Each declaration costs triangles: a rounding of 5 mm or more refines
its shape's turning cells to its radius, so round edges where they read. What
a declaration costs in a running World is bounded by what its views resolve
(`SdfMeshTier`: a group bakes at the coarsest cell under half a display pixel
at the nearest camera, so a 2 mm declaration is paid within about 4 m and
halves each doubling of distance); `puck mesh audit --cpu --eye x,y,z`
prints what one eye there would bake.
- **Animating a creation changes its bake.** Drivers make the creation
animated and its shapes pooled: `group: 0` is ungrouped there, and each
ungrouped shape bakes alone, so a `SmoothUnion` on it draws as a hard union
and the head reads as a ball on the body. PUCK131 names each such shape. Give
every blended shape a group of 1 or more.
- **A blend across parts that move apart tears.** PUCK122 names it: a glancing
head blended into the body in one group tore the throat into spikes
mid-motion. Give each moving part its own group (a crease, no tear) or one
motion owner, and check the extreme poses frame by frame.
- **Judge every side.** A side view read right while the front showed a
screaming face. Capture front, side, three-quarter, back and close, plus a
presented burst for motion, and keep going while any of them shows a
defect your authoring can fix. Work you can see fails is not shown as
progress.
- **A creation that pushes the engine is a probe (AGENTS.md, "Puck's
purpose").** When a defect is an engine limit (a tear the bake cannot close,
detail the animated bake cannot hold), stop sculpting around it: name the
limit with its evidence and hand it back, so the gap goes to the front of its
owning plan. A creation gets at most two look-critic rounds per wave. One
that still misses the bar may land when it is a material improvement on what
the tree holds, with its failures and the gaps behind them stated in the
commit.
- **Push a live edit as a row when `world.reload` is refused.** The debug
world's rebuild exceeds the transport cap (open items), so compile the
`.puck` and send the creation's document with
`world.row.set creations <id> document <json>`; a rebake shows in about 20 s.
## Verifying
Source first, then structure, then pixels:
1. `puck compile <file>.puck --validate` catches structure, budget and scope
refusals.
2. `puck creation stats --world <file>.puck --prototype <id>` validates the
whole world, emits text-free prototypes at unit scale to report static and
pooled rest-pose clamps, and builds the world's deterministic contact field,
solid placements included, even with a prototype filter. Exit 1 means
validation, emission, or contact failed; read the diagnostic. A pass does not
prove live motion or appearance.
3. `puck creation shape --world <file> --prototype <id> [--shape <name>]` (live:
`creation.shape`) says whether each shape's distance is exact, a bound or
uncertified, whether the fixed-point evaluator takes it, and what contact
makes of it. `world.slice <placement> <x|y|z> <path.png>` draws the field's
distance bands live.
4. Preview on the CPU before a windowed batch:
`puck mesh preview --world <file>.puck --prototype <id> --output <dir>` bakes
the creation with the engine's own CPU bake (no GPU lease, no World boot) and draws front, back, both sides, four three-quarter views, top and
below as palette-coloured PNGs and one contact sheet. Look at the sheet from
every side, as a missing part, a torn seam or a mirrored limb shows there
(magenta is a surface seen from behind, red a triangle on an open edge), and
name a close window (`head=30,10,0,0.07,0.05,0.04`) for a detail. It omits
paints, insets and wear, so it cannot judge a look, only form.
5. Run the game and look: a claim about how something reads is not verified
until you have looked at a capture (`references/loop.md`).
6. Audit what the boot baked:
`puck mesh audit --world <file>.puck --prototype <id> --group <shape> --images <dir>`
names the shapes at each group's worst clusters, in the author frame, and
says which way the mesh faces against the field's gradient at the worst
sample: opposed directions with both shapes at 0 mm is a sliver between
two surfaces, not a bake fault.
Frayed edges show as face normals off the gradient; a cutter whose field is
only a lower bound (a stretched ellipsoid, a non-uniform scale) shows as a
loose field; give that cutter an exact primitive instead. A smooth cut by
such a cutter spreads its fillet to several times the authored radius, and
unevenly round the rim (the gallery's `shape-stretch-smooth`; the
[rendering plan](../../../docs/plans/rendering.md#a-true-distance-under-a-non-uniform-scale)
designs the true distance). The
[rendering skill](../rendering/references/mesh-bake.md#auditing-a-bake) owns how the audit
reads a store.
Run every `puck` verb from your lane's private copy of the head's CLI
(`verification`).
## References and routing
| Where | Read it for |
|---|---|
| `references/shapes.md` | Every primitive's scale convention, profiles and lifts, which facets each admits, every ceiling and refusal message, contact admission |
| `references/composition.md` | Blends with formulas, domain folds, groups, scopes, trims, panels, the budget arithmetic |
| `references/surface.md` | Palette fields, weathering, inset, paints, render lanes, volumes, the render fields a look depends on |
| `references/rig.md` | parent/joint/swings/slides, frames, chains, drivers, effectors, parts, cameras, text runs |
| `references/loop.md` | Console verbs, capture recipes, the offline `puck creation` verbs, the sculpting library for C# authoring |
| `puck-dsl` | `.puck` grammar (`let`/`template`/`for`, the one-spelling rule), CLI flags, PUCKnnn diagnostics not specific to a creation field |
| `puck-world` | World sections around a creation (`looks`, `placements`, `render`, `state`), console semantics, booting `--world` |
| `rendering` | The SDF VM, ISA, kernels, shaders, the bake's internals, GPU cost and captures |
| `physics` | The contact providers, sweeps and kernels a creation's colliders feed |
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 |