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.

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 axisPoints
+Yup
+Zthe front the subject faces, toward a front-facing camera
+Xscreen-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). Palette inset.origin and inset.rotation do not convert either: author them in the shader's winning frame (surface). rig 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:

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 wantReach forNotes
A softly swelling mass, squarish or round on demandSuperellipsoid + exponent 2..82 is an ellipsoid, 8 is nearly a box; the sleek middle is 2.5–4
A slab with a shaped outlinePrism + profilerounded rect, chamfered rect, ellipse, regular polygon, or a convex hull
A tapering limb or finPrism + taper0 is a triangle, 1 is a rectangle
A tube, cable, horn, braid, or lock of hairSweep + curvequadratic Bézier, tapered radius, bulge, up to 4 helical strands; uniform scale only
A part that swells or pinches along its lengthflarea scale profile along one axis with a mid-span bulge
A leaning or S-curved massshearpolynomial offset of one axis driven by another
A local dent or swellingbumpsup to 4 gaussian pushes
An organic wobble over the whole formwarpa bounded sine warp of the point, each axis driven by the next
Fine even relief: dimples, corrugation, a hammered skindisplacea sine product added to the field, real geometry
A rounded slab, a stadium, a capsule from any primitiveelongatethe cross-section swept over a box of half-extents, 1-Lipschitz
Scattered, tumbled, recoloured copiesa jitter folda hashed repeat; render only
Self-similar shells, a Droste zooma logSphere foldrender only
Softened edgesrounding (curved) or chamfer (45° bevel)never both on one shape
A hollow shellonion
Repetition: ribs, teeth, plates, spokes, finsa domain foldrepeat, polar, symmetry, wallpaper; one fold, not N shapes. Refuses a panel on the same shape
Cellular or faceted relief: scales, chitin, hammered metalcellsneeds its own scope; see the scope rules
A stripe, ring, panel outline or mouth linea palette paints entrycolour 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).

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

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 scoped clamps 1 (0 shared) and globalStepScale 1, and no other shape marches shorter. Only when that depth is already occupied (the shape sits in a group or creation scope) is its bound shared at the enclosing pop, and only an unscoped chain taxes the program-wide step scale. So a warp does not by itself soften a whole model: read the shared and global clamps creation stats prints 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 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 (refused by group name if exceeded), 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:

ConsumerReads the lane
shapes[].erodein 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.laneat shading time, every frame: chips and scratches, with a static floor
palette[].emissiveLaneat shading time, every frame: emissive × saturate(lane)
palette[].flow.lane, .coverageLaneat shading time, every frame: the flow's speed and its revealed coverage
volumes[].intensityLaneat 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.

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 (up to 8) rotate about a pivot and slides (up to 4) 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.

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 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). 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. 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. 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), 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. The rendering skill 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

WhereRead it for
references/shapes.mdEvery primitive's scale convention, profiles and lifts, which facets each admits, every ceiling and refusal message, contact admission
references/composition.mdBlends with formulas, domain folds, groups, scopes, trims, panels, the budget arithmetic
references/surface.mdPalette fields, weathering, inset, paints, render lanes, volumes, the render fields a look depends on
references/rig.mdparent/joint/swings/slides, frames, chains, drivers, effectors, parts, cameras, text runs
references/loop.mdConsole 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-worldWorld sections around a creation (looks, placements, render, state), console semantics, booting --world
renderingThe SDF VM, ISA, kernels, shaders, the bake's internals, GPU cost and captures
physicsThe contact providers, sweeps and kernels a creation's colliders feed
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