ByteTerrace/Puck / .claude/skills/puck-world
puck-world
VerifiedMaps Puck.World: .puck worlds, rules, grants, console verbs, extensions, the live MCP World. Use to run or verify a World change (stdin script, stale binary, headless run) or debug a refusal.
references/documents-render.md
View on GitHub# `render`, `dynamics`, `curves`, graph instances, flock, crowd-scale, render validation, `rigid`/`carry`/`tether`
Part of [`puck.world.definition.v1`](documents.md). Field names, defaults, and ranges
are generated (`puck schema`, or `src/Puck.World.Schema/Schemas/schema/*.schema.json`); this
file is the decision/derivation prose the schema cannot state.
### `render` — the render defaults
`render.indirect.tier` boots Medium when absent and accepts Off, Medium or High.
The existing `world.indirect` session lever overrides it and `world.save` folds it
back without changing source gains. Quality presets carry an optional `indirect`
override; absent uses Off for Low, Medium for Medium and High for High. The one
shipped `quality.puck` table authors all three explicitly.
`render.indirect.sources` carries bindable `lights`, `emission`, `screens`, `sky`
and `feedback` gains in [0, 1], each default one. Explicit screens=0 stays off
even when an emitting image is bound. Structural `bounces` requests zero through
four bounces after direct, capped by the active tier. `apply` holds bindable
unit `intensity`, `tint` and `contact`; those receiver-only controls do not retrace
the irradiance volume. The ordinary generated document shape, scalar domains and
environment binding path own validation, keys and state reads; add no separate
indirect binding walker. The [lighting handbook](../../../../docs/rendering/sdf/handbook/lighting-and-shading.md#indirect-light-controls)
owns source and receiver semantics.
`WorldRenderDefaults` (`WorldRenderDefaults.cs`), optional; `Absent` carries the
engine defaults, including Medium indirect. The boot levers (`shadows`, `shadowLights`,
`shadowFadeSlots`, `shadowFadeTicks`, `shadowOverflow`,
`ambientOcclusion`, `renderScale`, `upscaleSharpness`, `temporal`,
`dynamicResolution`, the `low`/`medium`/`high` presets, each also carrying a
`renderScaleFloor` tier) seed `WorldRenderSettings` once at boot and move only
through their verbs afterwards; `views.quality` rows (`WorldViewQuality`; [views.md](views.md) owns them) hold a
render view's durable quality, each by instance `name` (or `*` for the player
views' defaults): `renderScale` (a scalar ceiling), `renderScaleFloor` (the lowest
dynamic-resolution tier) and `tier` (a quality preset), and a camera or session
view takes only a row that names it. They override these boot levers for that
view; session pins have no document member. `world.save` folds a moved lever back into the
section when the world authors one (`WorldSessionLevers.Fold`), creates the
section when the world omits it and the render-scale ceiling moved, and
otherwise leaves an absent `render` section absent. Presentation fields are read off the LIVE definition every frame instead,
so `world.row.set render {…}` lands on the next frame with no rebuild:
`lighting`/`sky`/`indirect` (`WorldEnvironmentResolve`, every keyed value at its clock's presented phase) and `farDistance`
(`WorldRenderFarDistance.Resolve`). `farDistance` is the depth every view's
geometry ends at (the mesh raster's far plane, the bake's and the irradiance
volume's reach, the fog and depth ramps' reach): nullable, absent resolves to
the engine's pinned 40 (`SdfFrame.DefaultFarDistance`);
an authored value must lie in
[`WorldRenderDefaults.MinFarDistance` 1, `MaxFarDistance` 8192], refused by
`ValidateRenderFarDistance` as `render.farDistance <v> must be finite and
within [1, 8192].` Geometry past it is never drawn, so an infinite plane
ends on a horizon curve at that depth unless `render.atmosphere.fog.density` has absorbed it
first. Read back with `world.row.set render` (the section's read arm) and
`world.budget`, which quotes the far distance with its derived costs: the
reach multiplier over the default and the fog
remnant `exp(−fogDensity·far)` at the far plane. Renderer contract:
`rendering` skill sync pairs, the pass block (`farDistance`).
`lanes` (up to four `BindableScalar`s, optional) are the world render lanes 4
to 7 every material and volume reads alike (`SdfLanes`), resolved off the LIVE
definition with `lighting` by `WorldEnvironmentResolve` at the presented tick
into `SdfFrame.WorldLanes`; a fifth is refused by `ValidateRenderLanes`, and
each judges as the `RenderLane` value field (finite). `world.lighting` echoes
them. Their meaning and consumers:
[sdf-authoring surface](../../sdf-authoring/references/surface.md#render-lanes).
`environment` (`WorldRenderEnvironment`, optional) and `tone`
(`WorldToneCurve`, optional: `peak`, `contrast`, `linearStart`, `linearLength`,
`toe`, all required when present; `worlds/standard/tones.puck` names
`filmicTone`) are also read off the LIVE definition every frame, alongside
`lighting`/`sky`; a `tone` change reaches each view's display pass on the next
frame with no graph rebuild. `environment`
carries nonnegative bindable `ambient` and `reflection` gains, each defaulting
to one. Zero skips the corresponding shading work. Ambient is the sky's
second-order harmonic irradiance, multiplied by the existing AO; reflections
read the shared map with analytic `panel` highlights. A panel is a repeatable
sky layer with `direction`, `size` (angular half-width and half-height in
radians), `color`, `intensity` and `blur`; its defaults are lighting
visibility and add blending. Its colour, intensity and blur can be keyed;
direction and size are structure. `tone` absent applies no curve: exposed light
of one is SDR white and brighter light clips on an SDR display. Present, it is
Uchimura's toe, linear section and shoulder, which each view's display pass applies
to its exposed scene light before the sRGB encode, so the letterbox color, a pane
and the HUD are never toned, and a debug view whose picture is not scene light
passes unencoded. Authored hex colours are display colours, decoded to linear
light where they enter shading (surface, light, sky, fog and medium colours).
Read back with `world.lighting`.
Renderer contract: `rendering` skill sync pairs, the sky block and layer table; the tone curve is the view's display pass, not a sky
record.
`lighting` (`WorldRenderLighting`, optional) carries `lights[]` (at most
`SdfLights.MaxLights` 128, in slot order, each optionally `name`d) and
`curvature`. Each light also carries a nonnegative bindable `bounce`, default
one, which scales its diffuse contribution to indirect transport independently
of direct shading. Rim and attenuation-only lights have no diffuse term.
Every value may be keyed on a `timeline` clock, and the section may
be keyed whole (`clock`, `keys`): each key a partial record addressing a light
by its `name`, of its own kind, stating values only (a light's `name` and
`shadow` are structure and refused). The sky keys the same way, addressing a
layer by `name`. `WorldRenderKeys.Expand` turns section keys into value keys
and `WorldKeyResolver` resolves them, for the validator with no live source and
for the client through its state mirror. Ordered values (gradient stop
elevations, the ink band) are judged by `JudgeAscending` over every phase of
their one clock, between keys as well as at them. A projection carries the tick
clocks, and each state clock a value keys on as an anchored clock
(`WorldClock.Anchor`, refused in an authored document) whose phase the
recipient predicts with `WorldClockAnchor.Predict`, the authority's own
prediction; `WorldClockAnchorLedger` sends a new anchor at exactly the ticks
that prediction misses, and a clock whose row the recipient may not read
refuses the composition. See [the worlds manual](../../../../docs/architecture/worlds.md#observation-and-display).
Every bindable presentation scalar's domain is one row of `WorldValueFields`
(`WorldValueDomain.cs`), keyed by its model member: `JudgeScalar` judges a
literal and each key against it, `ValidateBoundStarts` judges a bound row's
starting value at a load only (`TryValidate`; `TryValidateLocally` never reads
rows, so a stray live value never refuses a mutation, a replay or a snapshot).
The starting value is the one the binding presents: its row's eased follower, or
the stored value for a `.$target` binding. The presentation
(`WorldEnvironmentResolve`, `WorldThemeResolve`, `WorldMarkerAlphas`, and every
camera rig through `WorldCameraRigCompiler`) maps each resolved value through
`WorldValueDomainGuard.Resolve` over `WorldValueDomain.Map`: a finite value
beyond a closed end clamps to it, and a value that is not finite or lies at or
beyond an open end holds the binding's last valid value (the field's engine
default before it has presented one). The guard keeps that value per binding in
its world (one entry per field, site and state binding of a `WorldStateMirror`).
An entry lives while the installed document authors its binding, resolved or
not: a document install that no longer binds the field to that state binding
(`WorldPresentationManifest.Authors`, by document path and binding) releases it,
so a removed binding that is added again starts fresh whatever else reads its
row, and a hidden camera keeps its history. A different world in the mirror
(`WorldStateMirror.BeginLifetime`; a session mirror publishes the lifetime in the
same `WorldDeliveredDocument` snapshot as the document) and a restored timeline
(`WorldValueDomainGuard.Restart(mirror)`, for that world only) start its bindings
fresh, and so does the mirror's own disposal. The guard reports a binding when it leaves its domain and when it returns, never once per
frame (`[world.value: …]`, wired in `WorldPostBuildWiring`), and does no counted
work (`Checks`) while a binding's input is unchanged. A coupled threshold (a
gradient's stop elevations, the curvature ink band) may not bind a row, so no end
is ever clamped alone. The guard is a required, non-null parameter of every
type that resolves a bound value, so a site cannot omit it. A new bindable scalar member needs its
row, or `WorldValueDomainLawTests` fails. A domain a kernel depends on is closed
at a floor the kernel is proved against, never open at zero (an open end holds,
and a closed end's clamp target must survive a GPU's flush to zero): cloud
softness, a sky layer's and a creation volume's (`VolumeDocument.SoftnessDomain`,
judged by `CreationCanonicalizer`), is `[SdfSky.MinCloudSoftness, 1]`, and a
camera's field of view is `[CameraSnapshot.MinFieldOfViewRadians, π)`.
Each light's `$type` union:
| `$type` | Carries |
|---|---|
| `directional` | `direction`, `color`, `weight`, `angularRadius`, `shadow` (`always`, `auto`, or `never`); `always` and `auto` require a unique `name` |
| `rim` | `color`, `weight`, `power` — a view-dependent silhouette brighten added after the material shade |
| `point` | `position`, `radius`, `color`, `weight`, optional `anchor` — inverse-square falloff with a soft core (`intensity = weight / (1 + (distance / radius)^2)`); lambert diffuse plus the material's GGX specular from the light's own direction, both scaled by ambient occlusion like every non-shadow light; no shadow march |
A point light's `anchor` is a `WorldAnchor.Placement` only (every other anchor
kind is refused by name): its position then rides that placement's — or, with
`shapeId`, one of the placement's creation shapes' — dynamic transform every
frame instead of the authored `position`, so the light follows the placement.
Resolved in `WorldFramePresenter` (`WorldCreationInstances.TryShapeTransformSlot`),
fresh every produced frame. Renderer contract: `rendering` skill sync pairs, the
lights table.
`WorldRenderLight.Occluder` uses ordinary light rows to attenuate nearby
surface illumination. It declares `position`, positive `radius`,
`weight`, and an optional entity, entity-part, or placement `anchor`.
Anchors resolve each frame; unavailable anchors give weight zero.
Point and Occluder positions are `BindableVector3`: keyed, they blend linearly, never along an arc.
`world.lighting` reads back the authored light definitions and the allocator's
slots at this tick, naming each light and its selection reason (`always`, or
`auto` with its rank). A shadow candidate is identified by its `name`, never
its light-table index. `always` candidates rank first, then `auto` candidates
by tick-state luminance. At equal priority, current holders precede non-holders;
authored order breaks ties among non-holders and on a fresh selection. Selected
names retain their slots when ranking or authored order changes. Reusing a
table index for a different name produces an ordinary crossing.
`WorldShadowSelection` reduces each complete delivered state into those bounded
slots; it reads the mirror's current samples and delivered clock, not the
frame's interpolation. On the boot client the ordinary tick notification follows
the snapshot's field cells. `DeliverDefinition` supplies the new definition and
revision with its notification, so a pure reorder is detected before the reset
decision; its next snapshot installs the completed field samples with
`completingDelivery: true`, resampling the same tick without another identity
reset. A followed session observes structural reseeds and every completed
delivery through a `WorldSessionMirror.ObserveDeliveredState` lease, even when no frame
reads it, and the lease's `Work` source counts the shared observer samples.
The callback mirror is borrowed only for that callback; the selection retains
only bounded candidates and assignments. Disposing the lease ends callbacks
synchronously, and the last observer retires its optional sample store.
The boot render settings and each `WorldQualityPreset` carry `shadowLights`
(K, 0..4), `shadowFadeSlots` (F, 0..2), `shadowFadeTicks` (nonnegative engine
ticks), and `shadowOverflow` (`queue` or `instant`). The boot default is 1/0/0
with `instant`, and the named pinned sun is an `always` candidate. A preset
applies all four fields as one settings change. Validation checks the boot
policy and every reachable preset,
including `auto`: K > 0 with F = 0 and positive fade ticks, positive F with
zero fade ticks, and a queue that cannot progress are refused by name. The
shipped presets currently use K = 0/1/2 and F = 0 with zero fade ticks and
`instant`; the final sky defaults remain the P18-14 decision.
A candidate competes for a slot only while its delivered illuminance is above
zero, whatever its mode. The slots keep identities; the shadow roles go to the
slotted lights by what each emits in the frame (`SdfLights.RoleSlot`): the
brightest holds the primary role (the near and far cascades, and the frame's
key light, `SdfLights.Key`), the next the secondary (one cascade), and any other
slotted light takes the probes' answer. The `shadowSlots` report
`world.lighting` prints names each slot's `role=`. A directional with no `angularRadius` is a point source;
the standard package authors its own lights' soft edges.
`render.nested` (`WorldNestedViewQuality` rows, ascending `share` of the
display's height) says what a nested view gives up at each presented size:
`shadows` (the finest tier it keeps, `Off` drops its cascades) and
`ambientOcclusion`. No table gives up nothing; the standard authors one in
`worlds/standard/quality.puck`.
`WorldShadowAllocator` detects crossings on delivered ticks and derives fade
progress only from the presented tick. Fixed current and prior handoff records
hold integer crossing ticks and durations, 32 bytes each per fade slot for
F <= 2. Active readouts give outgoing and incoming light indices, stable slot
and progress; steady reads neither advance a handoff nor allocate. The full
report includes active handoffs and queue targets. `queue` waits for a target
slot's active handoff (`SlotInHandoff`), a desired identity participating in
another handoff (`IdentityInUse`), or busy fade capacity (`FadeCapacity`).
Only delivered boundaries recompute current targets; a still-needed crossing
starts at the first delivered tick its blocker clears. Matching queued targets
take free fade capacity before fresh crossings, oldest first, with slot index
breaking equal-age ties. `instant` swaps
atomically for overlap or exhausted capacity, releasing all old participants.
F = 0 or zero fade duration also chooses instant behavior. Seek, reload,
structural revision, backward delivery and policy changes install without fades,
preserving the held slots of names still selected and filling freed slots in
rank order.
`MarchSlots` is stable count plus active handoff count, bounded by K + F.
`SdfLights.ShadowSlots` carries that full selection to the counted GPU march.
The K word holds four 8-bit stable visibilities. Active incoming marches use
retained R8G8 storage at every nonzero F, absent at F = 0.
Each light's own occlusion deficit fades out or in with progress, leaving its
radiance unchanged; a light outside the slots shades unshadowed. The per-slot
march counters and counted 16-byte handoff uploads follow the
[P18-7 binding contract](../../../../docs/plans/rendering.md#p18--sky-and-atmosphere).
`CreationDocument.PaletteSize = 32` bounds `puck.creation.v1`'s `palette`
array. Each `PaletteEntryDocument` entry: `color` (`#RRGGBB` or a
`state.<row>[.<key>]` binding), `emissive` (null = 0), `specular` (null =
the `SdfMaterial` default 0; the GGX dielectric reflectance at normal
incidence before the `metal` mix), `roughness` (null =
`SdfMaterial.DefaultRoughness`; [0, 1], the GGX roughness-floor curve
parameter — see the `rendering` skill sync pairs, `SdfMaterial` packing), `sheen` (null = 0;
[0, 1], a fresnel edge-lift strength), `metal` (null = 0; [0, 1], mixes the
reflectance toward `color` and scales the diffuse term by `1 - metal`),
`coat` (null = 0; [0, 1], a fixed-roughness clearcoat GGX lobe). Each of
those four unit-range lanes is refused BY NAME at the canonicalizer when
non-finite or outside [0, 1] (`PaletteAdmissionLawTests`) — `SdfMaterial`'s
own `RequireUnitRange` would otherwise throw at stamp emission. A document
still spelling `shininess` is an unmapped member and is refused. A palette
entry's `weathering` declares `edge`, `lines`, `settle`, `reach`,
`seed`, `scale`, `floor`, `lane`, `noise`, `patternScale`, `softness`, the pattern's
character (`octaves`, `octaveRatio`, `octaveGain`, `turn`), up to two ascending
`under` threshold/surface entries, and an optional `deposit` surface.
Each surface supplies `color`, `roughness`, and `metal`.
`inset` declares `origin`, `rotation`, `depth`, `ior`, and
`paint`: 1..4 ascending radial `{radius,color}` stops with `softness`,
`modulationAmplitude`, `modulationFrequency`, and `seed`.
Inset coordinates use the winning dynamic frame, or world space for a
static hit. `wrap`, `soften`, and `fill` retain their shading roles.
### `dynamics` — the personality table
`DynamicsRow` (`Puck.State/DynamicsRow.cs`): named rows of `{name, f, zeta, r}` —
a t3ssel8r-style pole-matched second-order response every follower consumer
names by `name` rather than authoring inline, so one row can drive a look's
root/part followers, a camera boom, a kit's planar shaping, and a state cell's
eased read at once. `f` (Hz, positive, finite, ≤ `DynamicsLimits.MaxFrequencyHz`
100) is the natural frequency; `zeta` (≥ 0, ≤ `DynamicsLimits.MaxDamping` 16) is
the damping ratio — `0` rings forever, `<1` overshoots and rings down, `1` is
critically damped, `>1` is overdamped; `r` (`DynamicsLimits.MinResponse`..
`DynamicsLimits.MaxResponse`, ∓4) is the initial response — `0` eases in from
rest, `>0` reacts immediately to the target's own motion, `>1` overshoots the
target's motion before settling, `<0` anticipates. The section is OPTIONAL and
every reference to a row is nullable, so an unauthored world is unchanged.
Every consumer resolves a name through `StateRows.FindDynamics` and
refuses a dangling one by name (`'{name}' names no dynamics row.`); removing a
still-referenced row is refused the same way, naming the referrer. Authored
with `world.row.set dynamics {"name":"chase","f":0.9549,"zeta":1,"r":1}` /
`world.row.remove dynamics <name>`; read back with `world.dynamics`, which
reports every row's authored triple, the derived decay/oscillation/k3
constants through the SAME fixed-point derivation
(`Puck.Maths.SecondOrderDynamics.Create`) the simulation compiles from, and a
live reference count across cameras, looks, look parts, kits, and state.
Consumers: a look's `motion.dynamics`/`motion.partDynamics` (root and per-part
followers), a camera program's `dynamics` op (the boom ease), a kit shaping
row's `dynamics` facet (planar velocity shaping — exactly one of `dynamics`
or `along` on that row, never both, never neither — see
[documents-motion.md](documents-motion.md)), and a
`state` row/cell's `dynamics` trait (the eased read — see
[documents-state.md](documents-state.md)).
### `curves` — the curvature-first spline table
`WorldCurveRow` (`WorldCurves.cs`): named rows of `{name, closed, knots}`. An
author declares intent per knot — position, tangent direction, signed
curvature — and `Compiled` derives the machinery (the cubic-Bézier tangent
lengths that reproduce it exactly, Steven Wittens' curvature-continuous
construction; see the `maths-usage` skill for `Puck.Maths.CurvatureSpline`)
rather than authoring control points directly — no control-point document
shape ever ships. A knot's `position` is a `DocumentVector3` — X/Z the planar
curvature-solve inputs, Y an elevation lift carried outside the curvature/
arc-length solve as a linear grade; `tangentYaw` (radians, unit tangent
`(cos, sin)` in XZ) and `curvature` (signed, within
±`CurvatureSpline.MaxCurvature`, under the `cross2(a, b) = a.X·b.Z − a.Z·b.X`
convention) complete it — the SAME facing convention the engine's own facing
path uses, pinned once here so the camera `path` op and the sim curve-follow
target both read it rather than re-deriving one. An open curve needs at least
two knots, a closed one at least three, and at most `WorldCurves.MaxKnots`
(64); the section holds at most `WorldCurves.MaxRows` (64) rows. The section
is OPTIONAL and every reference to a row is nullable, so an unauthored world
is unchanged. The validator's per-field checks (coordinate/curvature range,
knot counts) catch authoring mistakes; the exact solve itself — chord length,
tangent/curvature consistency, an unreachable curvature, an interior cusp, Q32
carrier overflow — is the LAST gate, run once by compiling the row
(`WorldCurveRow.Compiled`, cached per row instance, the
`DynamicsRow.Compiled` precedent) rather than duplicated in the
validator. Every reference resolves through `WorldDefinitionRows.FindCurve`
and refuses a dangling name; removing a still-referenced row is refused naming
the referrer (`WorldDefinitionRows.EnumerateCurveReferences`). Authored with
`world.row.set curves {"name":"dolly","knots":[…]}` /
`world.row.remove curves <name>`; read back with `world.curves`, which reports
every row's authored shape, its compiled segment count and total arc length
through the SAME derivation the consumers read, and a live reference count
split by `cameras`/`follows`. Consumers: a camera program's `path` op (dollies
the eye/pivot along the curve by arc-length fraction; see views.md) and a
body-motion program's `curve` target source
(`Puck.Physics.Motion.BodyTargetSource.CurveFollow`) — a fixed-point, per-tick
arc-length follower feeding the SAME planar target-consuming op vocabulary a
`designated`/`sensed` target does.
### `views.graphs` — render-graph instances
`WorldViewGraph` (`WorldViews.cs`) carries `{name, source | package, camera,
refresh, inputs, timeScale, output, overrides}`. A row names exactly one of
`source` and `package`: a `package` row is an engine package's producer (such
as `sdf.world`) and takes no input, time scale, output or override. The
`.puck` spelling is a `graph "name" { … }` block inside `views`.
[views.md](views.md) owns `refresh`, `inputs`, `views.root` and the graph
budget. `overrides` maps a pass name to that pass's
config object and `output` names the shown image version; both are bound
through the source's config schema at the mutation door, at boot, and at
`world.load`/`world.reload`, and the shared source keeps its defaults (see
[mutations.md](mutations.md) and the
[per-instance overrides contract](../../../../docs/reference/shaders.md#per-instance-overrides)).
`pipeline.commit` is the one door that turns a session preview into these
members. Source is a `puck.render.graph.v1` graph document, a one-off `.hlsl`
shader read as a one-pass graph, or a `puck.shader.package.v1` package
directory (a directory is a package; there is no second member for it), and
resolves relative to the world document. A source row loads through
`ShaderPackager.LoadSource`, and its `SHADERPKG_*` or `SHADERSRC_*` refusal is
the instance's failed compilation, by code. The graph's own shader paths
resolve relative to its document. `WorldViewSlot.Instance` (`instance: "name"`
in `.puck`) names the row; a slot cannot name both a camera and an instance.
`timeScale` seeds presentation time. `views.shaderToolchain` optionally names
the compiler directory; otherwise executable lookup uses the process path.
Rows use `world.row.set views.graphs` and `world.row.remove views.graphs <name>`
through the same closed mutation vocabulary as `pipeline.load`. The host
(`WorldViewGraphHost`) reconciles only accepted document state into the render
graph runtime's instance set. The runtime owns resources, history, background
compilation and frame-boundary installation; none belongs in the schema. Use
[the pipeline world](../../../../experimental/src/Puck.World/Assets/worlds/pipeline.puck)
for the live three-pass editing workflow. The
[shader reference](../../../../docs/reference/shaders.md#shader-pipelines-and-live-development)
owns the `puck.render.graph.v1` document contract a row's source is written in.
### Kit producer `flock` — bounded local perception
`ProduceFlockIntent` requires `producers.<name>.flock` on the assigned kit:
range, separation radius, candidate budget, maximum retained neighbors,
perception interval in seconds, tangent/volume space, cone/line-of-sight policy,
and separation/alignment/cohesion/goal/inertia weights. It is mutually exclusive
with `ProduceSteeringIntent`/`FaceSensorTarget`. Target sources remain optional; when
present they use the ordinary sensing/target-register vocabulary.
The population freezes position/orientation/travel before any body advances.
Cadence limits neighbor and sensed-target updates, not designation/route/frame
blending. A sensed target shares the neighbor candidate budget over the larger
range and retains its last observed position between updates. Sampling is bounded
even in a coincident crowd; results are nearest within the inspected sample,
not globally nearest.
Use range-scaled grids independent of unrelated profiles; rebuild only levels
needed by this step's samples. Preserve caches across unchanged bindings and
invalidate them when the profile or target source changes. Checkpoint/hash the
unclamped neighbor contribution, timing residue, local sample ordinal, observed
target position/generation, and occupant generation. An optional `movementDomain` names a volume/medium domain
whose root-centered agentRadius encloses the kit's offset collider volumes.
Integrated locomotion is continuously checked; refused steps stop momentum.
This ends with the producer and does not cancel later impulse/contact/tether or
teleport operations, find an escape route, or implement a surface constraint.
The steering kernel itself confers no friendship or collision safety. Read it back
with `world.flock`; `world.budget` repeats the structural cost. Author changes
still use the one document door, not a separate flock mutation API.
Optional `cohesionAffinity`/`alignmentAffinity` use the ordinary Fixed postfix
expression evaluator. Left is the observer, right the retained neighbor; only
state-backed operands are admitted because body/channel/navigation reads
change during the movement pass. A belief row keyed by observer (`$left`) is
the ordinary way to feed one — see "Keyed belief rows and evidence dedup"
in [documents-rules.md](documents-rules.md). Missing expressions read one, results clamp
to [0,1], arithmetic failure reads zero with a counter. These are relative
weighted-mean inputs, not separation filters or absolute term strength. They
refresh with perception cadence, not on every belief-row update. Rebind compiled
state handles on every declaration installation; key
bindings by authored kit/producer names, not object identity (wire restore
deserializes fresh objects). Cached neighbor contributions already carry the
result through checkpoint/hash. Charge both programs and all indirect scans for
every retained neighbor in the worst-case simultaneous population refresh,
under the shared rule work ceiling — an O(population²) Distance interaction
firing an ordinary state-write effect on every pair is priced at the engine's
real per-write cost, not a bespoke cheap one; keep that shape to a linear
forEach/flock-affinity reach instead. See the
[authoring example](../../../../src/Puck.World.Schema/README.md#keyed-belief-rows-and-flock-affinities).
### Crowd scale policies
`WorldBodiesLimits.CapacityCeiling` is 4096. `kits.rows[].autonomy` independently
batches non-human `motionSeconds` and producer `steeringSeconds` (0..1; zero is
full authority rate), with deterministic per-body phasing and exact elapsed
engine-tick batches. Live/human/tape/pending-input bodies stay full-rate. Refuse
positive motion cadence with `bodyContact: solid`; deferred bodies cannot claim
per-tick dynamic contact. Large flocks use overlap contact.
`collision.events` bounds body-pair proximity events separately:
`candidateBudget` per body, `maxPairsPerBody` retained degree, and `beginBudget`
per tick. Existing pairs win continuity priority. `maxPairsPerBody: 0` disables
pair events while ordinary world contact remains live. Preserve these policies,
cadence phase, cached steering, and overlap latches through checkpoint/hash.
`collision.bodyContacts` separately bounds physical depenetration between
`solid` kits: at most 256 inspected box-overlapping candidates and 16 resolved pairs per body
(defaults 32/8). Dense saturation omits later stable-index pairs. Do not couple
these budgets to `collision.events`; sensing and physical correction are
independent authored costs. `rigidSubstepCeiling` (default 8, maximum 32)
is the rigid solver's substeps a tick. `contactHertz`/`contactDampingRatio`/`contactSpeed`
author spring frequency (Hz), damping ratio and maximum push-out speed (m/s),
all non-negative with zero defaults. The standard package chooses 30/10/3.
Frequency is clamped to one eighth of the substep rate.
`rigidSubstepTravelFraction`/`rigidSubstepMinimumTravel`
(defaults 0.5/0.001) bound how far a body's solved motion may depart from its
predicted motion before a guard sweep re-certifies it. `rigidRestSpeed`/`rigidRestHoldSeconds`
(defaults 0.05/0.25) are the threshold on the fastest point's speed (linear plus
angular times bounding radius) and the hold window a supported rigid body's
`Resting` fact latches against. `rigidPairRestitutionSpeed` (default 0.05) floors
a rigid contact's restitution at zero below that closing speed, so two resting
bodies do not micro-bounce. `maxPairsPerBody` also sizes the rigid contact
registry: a rigid body owns at most that many body contacts plus its surface
contact.
### Text-screen bindings
`WorldScreenText` owns text-screen parsing and the bounded grid policy shared
by validation and baking. Lines use HUD brace escaping (`{{`, `}}`) but accept
only `{state.<row>[.<key>][.$target]}` placeholders over declared Int, Fixed,
Bool or Text rows, with no `$body` context. Missing live cells display empty.
Literal widths count unescaped Unicode scalars; dynamic expansions clip to
explicit columns or inferred columns bounded by the per-screen cell budget,
even when a later write grows a value. Never size a bake from unrestricted
expanded width while validating template syntax length.
`WorldKeyedValues.BoundOf` includes text placeholders wherever a source sits
(screen, magazine or placement face), so projection's existing disclosure
checks and observations see their dependencies. The protocol manifest and
`WorldBakedColors` read the same parsed grammar through the mirror; the
manifest and `WorldKeyedValues` both take placeholders from
`WorldScreenText.Placeholders`.
Both, and `WorldStateDocumentValues` (which fills, flattens, finds and collects
`IDocumentStateValue` holders), are visitors of one walk of the document model,
`WorldDocumentWalker` (`Puck.World.Schema`): a walker is built over a consumer's
surface types (or a predicate over types) and enters only members that can reach
one, with readers, fields and member lists cached per type and `CodeRevision`
(a hot reload derives them again). A value the generated model table does not
describe (a mutation, a projection, a list at the root) is followed through its
public properties; a value shared by two owners is walked under each (only a
cycle is cut); a visitor ends the walk early through `Stopped`. A walk that
finds state a document reads is a new visitor of it, never a new walker. `BindableDirection`,
`BindableVector2` and `BindableVector3` bind no state cell (literal or keys
only), so the manifest does not list them; a keyed one reads its clock, whose
state row the manifest records with the timeline. A local
mirror test alone cannot prove a presentation observer receives the row: test
compose, hydrate, and resolve too, including a restricted recipient.
### Render validation and stamp capacity
For multi-body render validation, inhabited placements belong only to the body
stamp census, even when their creation is animated or attached. A simultaneous
animated-placement registration doubles the character. Verify body count and
`world.budget` together. Bounded flow/cloud media share 64 frame slots; disabled
volumes emit nothing, and the budget readback includes their submitted count.
The [Moth courtyard](../../../../experimental/src/Puck.World/Assets/worlds/moth-courtyard.md)
provides eight held poses and independent sky/cloud switches for repeatable GPU
captures. Density controls live in the World.Authoring README.
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.
### A kit's `rigid` facet
`mass`, `restitution`, `friction`, `rollingResistance`,
`linearDamping`, `angularDamping` hand its bodies to the rigid solver
instead of a locomotion program — see
[the server reference](../../../../src/Puck.World.Server/README.md#rigid-dynamics-worldbodyrigidcs-worldpopulationrigidcs).
`mass` is required and positive; `restitution` is in `[0, 1]`, `friction` a
non-negative coefficient, `rollingResistance` a non-negative lever in metres,
and the two dampings non-negative per-second decay rates, never per-tick
fractions. Requires `collider` with exactly one
sphere, capsule, box or ellipsoid volume and `bodyContact: solid`. A
`fromCreation` collider admits a creation's single primitive too; a nonuniform
Sphere or Ellipsoid retains its actual radii and curved support, rather than
its bounding box. Compound creations still refuse rigid inertia derivation.
An ellipsoid's creation-local rotation must keep its principal inertia axes
aligned with the body (axis permutations and equal-radius-plane rotations
are admitted); rotate the body itself to give it an arbitrary orientation.
The older Box mass path still reads its original half-extents without rotating
the tensor for a collider-local rotation; keep an anisotropic box primitive
unrotated until that path has the same principal-axis admission check.
A kit's `rigid` facet (`Puck.World.Schema.WorldRigid`) is a passive
physical entity — mass/restitution/friction/damping derived to
mass/inertia from the kit's own primitive collider, never a free
density or tensor. Every rigid contact, against the static field or another
body, is solved by one `Puck.Physics.FixedRigidWorld` step over every awake rigid
body (`WorldPopulation.SolveRigidContacts`, `WorldPopulation.Rigid.cs`), from
manifolds each body owns and carries in its continuation. The geometry runs once
a step: each body's contact generation asks the contact field for every static
surface within its reach (one exact query per collider, or one certified sweep
where the field cannot answer per surface), and `ResolveDynamicContacts` runs one
overlap query per broadphase pair; `Puck.Physics.FixedRigidContacts` spreads each
contact over the shapes' support features (`FixedRigidWitness.SupportManifold`:
four box corners, two capsule caps, an ellipsoid's support point and a tilted
ring), each with its own separation, which is what keeps an upright body's centre
of mass over its support polygon and lets a tilted one tip. A box-vs-box pair's
overlap is the complete fifteen-axis separating-axis test
(`Puck.Physics.FixedOrientedBox.TrySeparation`), not the
coarser world-bounds approximation a capsule-vs-box pair still uses. Once the resting latch
closes over a complete rigid contact island, the population parks every member until something
wakes it (an impulse, a broadphase overlap with an awake body, a hard
teleport, glide, reconciliation, changed scale/collider/rigid facet, or a live solid edit replacing the contact field it rested
against) — this is what makes `Resting`/`$physics:quiescent` mean the body
is not moving. `body.impulse`, `world.rigid`, `world.budget`, and the
`physics(quiescent)` rule operand are the console/rule surface. A carried rigid
body is never quiescent. `physics(quiescent, roster)` limits the check to the
authored keys of a keyed state row, each naming one count-1 inhabited placement;
the compiler resolves those names to placement ordinals, so each read costs one
lookup per listed placement rather than a population scan per member. Cell
values do not filter membership, and uninhabited or inactive bodies contribute
no motion. Dynamic-pair support counts toward the hold after the pair solve. A stack sleeps as one island;
touching or changing any member wakes the component, so moving a lower body releases the stack.
Sleeping bodies retain a spatial index and leave the integration, broadphase construction and event work sets.
An awake neighbour queries that index before its sweep, and a bounded contact-field change takes its candidates from
the same index over the change box. The island graph is the bodies' own persistent contacts, carried in each body's
checkpoint entry; a contact with a non-rigid support is a wake dependency of the sleeping load. Solved gravity changes wake affected components before integration, even without a contact-field
revision. Checkpoints also retain pending event discovery and its last policy: clearing that history would change
which edges consume a bounded candidate budget. Reconstruct captured scale and effective kit before restoring
rest latches, so register catch-up does not spuriously wake an unchanged body. `puck bench world` reports sleeping bodies and integration,
broadphase and event work counts. See
[Crowd scale policies](#crowd-scale-policies)
for the authored `collision.bodyContacts` rigid fields, and the
[server](../../../../src/Puck.World.Server/README.md#rigid-dynamics-worldbodyrigidcs-worldpopulationrigidcs)/[schema](../../../../src/Puck.World.Schema/README.md#rigid-dynamics-worldrigidcs)
references for the mechanics. The shipped garden's `billiardsTray`/
`bowlingLane`/`dominoRun` placements are the worked example.
### `carry` and `tether` facets
A DISTINCT kit
facet, `carry` (`Puck.World.Schema.WorldCarry`), lets a body pick up another
rigid one — `body.carry <carrier> <target>`/`body.release [carrier]`,
`WorldBody.Carry.cs`/`WorldPopulation.Carry.cs`; a carried body's own
integration is suspended and its pose is derived from the carrier's frame
every tick, but TANGIBLY: its own collider sweeps from its previous pose to
that frame-derived one against static geometry (`WorldBody.FollowCarrier`)
and against every other active solid body (`WorldPopulation.ResolveCarriedBodyPush`),
so it pushes and is blocked rather than passing through — whatever
correction either sweep applies is handed back to the carrier too, so the
carrier itself is stopped, not just the object it holds. `body.release`
refuses by name when the carried body's CURRENT pose still overlaps static
geometry or another body. The garden's `walker` kit (Wren) carries this
facet.
A THIRD distinct facet, `tether` (`Puck.World.Schema.WorldTether`),
is an aimed distance-cap rope a body throws along its own facing and reels —
`body.attach`/`body.detach`/`body.reel`, `WorldBody.Tether.cs`; presence is
the switch, the same convention `rigid`/`carry` carry. A body's attach
state is `m_tether is not null` — there is no separate mode field. Read
back per body with `body.tether`, per kit with `world.kits`. The garden's
`walker` kit (Wren) carries this facet too.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the work | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixes | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation code | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |