Skip to content

ByteTerrace/Puck / .claude/skills/puck-world

puck-world

Verified

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

FileKindSize
SKILL.mdskill md72.0 KB
evals/w01-seat-mouse-look-sensitivity/graders/behavior-preserving-default.mdmarkdown191 B
evals/w01-seat-mouse-look-sensitivity/graders/names-the-existing-record.mdmarkdown71 B
evals/w01-seat-mouse-look-sensitivity/graders/no-flag-or-constant.mdmarkdown89 B
evals/w01-seat-mouse-look-sensitivity/graders/one-seat-through-identity.mdmarkdown186 B
evals/w01-seat-mouse-look-sensitivity/graders/pointer-sensitivity-members.mdmarkdown88 B
evals/w01-seat-mouse-look-sensitivity/graders/read-back-verb.mdmarkdown76 B
evals/w01-seat-mouse-look-sensitivity/graders/reuses-existing-vocabulary.mdmarkdown155 B
evals/w01-seat-mouse-look-sensitivity/graders/skill-fired.mdmarkdown36 B
evals/w01-seat-mouse-look-sensitivity/graders/value-in-the-document-model.mdmarkdown125 B
evals/w01-seat-mouse-look-sensitivity/prompt.mdmarkdown268 B
evals/w02-row-set-refusal/graders/actor-differs-from-target.mdmarkdown158 B
evals/w02-row-set-refusal/graders/captures-both-streams.mdmarkdown122 B
evals/w02-row-set-refusal/graders/grant-versus-subject.mdmarkdown283 B
evals/w02-row-set-refusal/graders/skill-fired.mdmarkdown36 B
evals/w02-row-set-refusal/graders/stamped-principal.mdmarkdown252 B
evals/w02-row-set-refusal/graders/success-control.mdmarkdown70 B
evals/w02-row-set-refusal/prompt.mdmarkdown251 B
evals/w03-hermetic-hud-script/graders/announcement-on-stderr.mdmarkdown84 B
evals/w03-hermetic-hud-script/graders/bom-less-utf8.mdmarkdown75 B
evals/w03-hermetic-hud-script/graders/captures-both-streams.mdmarkdown75 B
evals/w03-hermetic-hud-script/graders/drain-barrier-or-wait.mdmarkdown96 B
evals/w03-hermetic-hud-script/graders/frame-after-pending.mdmarkdown204 B
evals/w03-hermetic-hud-script/graders/isolated-state-directory.mdmarkdown76 B
evals/w03-hermetic-hud-script/graders/pixel-versus-replay-proof.mdmarkdown108 B
evals/w03-hermetic-hud-script/graders/skill-fired.mdmarkdown36 B
evals/w03-hermetic-hud-script/prompt.mdmarkdown224 B
evals/w04-cooldown-rule/graders/authored-as-puck.mdmarkdown138 B
evals/w04-cooldown-rule/graders/boots-the-source.mdmarkdown76 B
evals/w04-cooldown-rule/graders/compiled-in-memory.mdmarkdown143 B
evals/w04-cooldown-rule/graders/folds-through-the-rule-frame.mdmarkdown170 B
evals/w04-cooldown-rule/graders/gate-on-tick.mdmarkdown68 B
evals/w04-cooldown-rule/graders/names-the-mutation-kinds.mdmarkdown140 B
evals/w04-cooldown-rule/graders/no-decrementing-remainder.mdmarkdown97 B
evals/w04-cooldown-rule/graders/remove-sugar.mdmarkdown71 B
evals/w04-cooldown-rule/graders/row-set-is-not-authoring.mdmarkdown109 B
evals/w04-cooldown-rule/graders/schedule-sugar.mdmarkdown73 B
evals/w04-cooldown-rule/graders/skill-fired.mdmarkdown36 B
evals/w04-cooldown-rule/graders/targets-the-debug-world.mdmarkdown215 B
evals/w04-cooldown-rule/prompt.mdmarkdown239 B
evals/w05-gcp-storage-provider/graders/assembly-attribute.mdmarkdown82 B
evals/w05-gcp-storage-provider/graders/catalog-in-a-running-host.mdmarkdown83 B
evals/w05-gcp-storage-provider/graders/duplicates-refused-by-name.mdmarkdown149 B
evals/w05-gcp-storage-provider/graders/extension-model-laws.mdmarkdown79 B
evals/w05-gcp-storage-provider/graders/installed-not-referenced.mdmarkdown171 B
evals/w05-gcp-storage-provider/graders/mcp-services-provider.mdmarkdown188 B
evals/w05-gcp-storage-provider/graders/no-own-directory-scan.mdmarkdown84 B
evals/w05-gcp-storage-provider/graders/no-per-kind-interface.mdmarkdown87 B
evals/w05-gcp-storage-provider/graders/no-static-registry.mdmarkdown74 B
evals/w05-gcp-storage-provider/graders/one-extension-project.mdmarkdown105 B
evals/w05-gcp-storage-provider/graders/one-hosted-control.mdmarkdown85 B
evals/w05-gcp-storage-provider/graders/registers-through-add-storage.mdmarkdown141 B
evals/w05-gcp-storage-provider/graders/skill-fired.mdmarkdown36 B
evals/w05-gcp-storage-provider/prompt.mdmarkdown246 B
evals/w06-agent-harness-on-azure/graders/agent-harness-participant.mdmarkdown71 B
evals/w06-agent-harness-on-azure/graders/body-five.mdmarkdown81 B
evals/w06-agent-harness-on-azure/graders/default-azure-credential.mdmarkdown79 B
evals/w06-agent-harness-on-azure/graders/deliberate-approval.mdmarkdown89 B
evals/w06-agent-harness-on-azure/graders/extensions-document.mdmarkdown84 B
evals/w06-agent-harness-on-azure/graders/grants-in-the-world.mdmarkdown162 B
evals/w06-agent-harness-on-azure/graders/installs-beside-each-host.mdmarkdown156 B
evals/w06-agent-harness-on-azure/graders/local-config-flag.mdmarkdown81 B
evals/w06-agent-harness-on-azure/graders/no-key.mdmarkdown60 B
evals/w06-agent-harness-on-azure/graders/participant-laws.mdmarkdown86 B
evals/w06-agent-harness-on-azure/graders/participant-settings.mdmarkdown175 B
evals/w06-agent-harness-on-azure/graders/principal-not-console.mdmarkdown114 B
evals/w06-agent-harness-on-azure/graders/silo-extension-laws.mdmarkdown83 B
evals/w06-agent-harness-on-azure/graders/silo-row-extensions-member.mdmarkdown125 B
evals/w06-agent-harness-on-azure/graders/skill-fired.mdmarkdown36 B
evals/w06-agent-harness-on-azure/graders/status-line.mdmarkdown103 B
evals/w06-agent-harness-on-azure/prompt.mdmarkdown202 B
evals/w07-failed-build-stale-binary/graders/build-exits-zero.mdmarkdown104 B
evals/w07-failed-build-stale-binary/graders/documented-recipe.mdmarkdown114 B
evals/w07-failed-build-stale-binary/graders/hermetic-state-dir.mdmarkdown68 B
evals/w07-failed-build-stale-binary/graders/old-binaries-ran.mdmarkdown170 B
evals/w07-failed-build-stale-binary/graders/reports-the-run.mdmarkdown76 B
evals/w07-failed-build-stale-binary/graders/same-script.mdmarkdown72 B
evals/w07-failed-build-stale-binary/graders/says-no.mdmarkdown91 B
evals/w07-failed-build-stale-binary/graders/skill-fired.mdmarkdown36 B
evals/w07-failed-build-stale-binary/prompt.mdmarkdown261 B
evals/w08-gpu-grant-held-by-parity/graders/build-exit-zero-first.mdmarkdown129 B
evals/w08-gpu-grant-held-by-parity/graders/build-runs-beside-the-leg.mdmarkdown153 B
evals/w08-gpu-grant-held-by-parity/graders/effective-presentation-modes.mdmarkdown118 B
evals/w08-gpu-grant-held-by-parity/graders/headless-runs-now.mdmarkdown171 B
evals/w08-gpu-grant-held-by-parity/graders/headless-world-is-not-gpu-work.mdmarkdown142 B
evals/w08-gpu-grant-held-by-parity/graders/self-excluding-search.mdmarkdown166 B
evals/w08-gpu-grant-held-by-parity/graders/skill-fired.mdmarkdown36 B
evals/w08-gpu-grant-held-by-parity/graders/windowed-waits-for-a-grant.mdmarkdown121 B
evals/w08-gpu-grant-held-by-parity/prompt.mdmarkdown279 B
evals/w09-live-world-mcp/graders/camera-read-back.mdmarkdown76 B
evals/w09-live-world-mcp/graders/lists-the-worlds.mdmarkdown68 B
evals/w09-live-world-mcp/graders/names-the-world.mdmarkdown178 B
evals/w09-live-world-mcp/graders/own-world-for-worktree-edits.mdmarkdown222 B
evals/w09-live-world-mcp/graders/restores-the-mutation.mdmarkdown174 B
evals/w09-live-world-mcp/graders/skill-fired.mdmarkdown36 B
evals/w09-live-world-mcp/prompt.mdmarkdown360 B
evals/w10-bounded-diagnostic-report/graders/bounds-and-running.mdmarkdown542 B
evals/w10-bounded-diagnostic-report/graders/snapshot-and-hold.mdmarkdown453 B
evals/w10-bounded-diagnostic-report/prompt.mdmarkdown547 B
evals/w11-reload-delta/graders/delta-and-drain.mdmarkdown1.1 KB
evals/w11-reload-delta/prompt.mdmarkdown735 B
references/addons.mdmarkdown32.7 KB
references/adjacency-and-federation.mdmarkdown55.7 KB
references/authority.mdmarkdown40.0 KB
references/console.mdmarkdown58.5 KB
references/documents-composition.mdmarkdown34.4 KB
references/documents-identity.mdmarkdown19.4 KB
references/documents-motion.mdmarkdown37.2 KB
references/documents-render.mdmarkdown40.5 KB
references/documents-rules.mdmarkdown27.4 KB
references/documents-state.mdmarkdown59.2 KB
references/documents.mdmarkdown21.1 KB
references/engagement.mdmarkdown50.6 KB
references/hosting-and-release.mdmarkdown31.1 KB
references/hud.mdmarkdown33.4 KB
references/mutations.mdmarkdown36.4 KB
references/ordered-domain.mdmarkdown14.6 KB
references/replay.mdmarkdown69.7 KB
references/schedules-and-tests.mdmarkdown26.4 KB
references/session-lifecycle.mdmarkdown15.0 KB
references/views.mdmarkdown54.8 KB

references/documents.md

View on GitHub
# The document families

Three versioned JSON families, all owned by `src/Puck.World.Schema`.
`puck.world.definition.v1` (`WorldDefinition.cs`) describes a world. An identity is not
a separate schema — it is an ordinary `WorldDefinition` document carrying an
`identity` section, one file per owned world (see "Owned-world identities"
below). The other two are EGRESS documents, never authored by hand and never
loaded as a world: `puck.world.projection.v1` (`WorldProjection.cs`) and
`puck.world.counterpart.v1` (`WorldCounterpartAttestation.cs`) — see
"Disclosure" below. All three carry a root `Extensions` bag under
`Puck.World.DocumentExtensionsPolicy`.

**Field names, enums, defaults, and validation ranges are generated, not
restated here.** `puck schema` derives `puck.world.definition.v1.schema.json` (root),
`puck.world.projection.v1.schema.json`, and one file per document section
under `src/Puck.World.Schema/Schemas/schema/*.schema.json` directly from `WorldDefinition.cs`
over the same source-generated `WorldJsonContext` the engine parses a world
through (`System.Text.Json`'s `JsonSchemaExporter` — never hand-maintained);
the same run writes the dashboard portal's `worldDefinition.generated.ts`
from the bundled schema (`WorldSchema.ToTypeScript`), so a schema change is
regenerated by `puck schema` and never by hand or through npm. The same run
writes `src/Puck.World.Schema/WorldModelShape.generated.cs`, the model shape
the engine's model walks read (`WorldModelShape`).
If a renamed model type prevents the lane's first CLI build, build it with
`-p:PuckSchemaBootstrap=true`, run that copy's `schema`, then rebuild and refresh
the normal CLI copy. The bootstrap CLI exposes only `schema`, not `lease` or
other verbs; never use its assemblies to verify runtime behavior.
`puck schema --check` fails the build the moment a checked-in schema file,
that TypeScript or the model shape drifts from the code, and `puck schema --bundle` emits the
single-file, fully-`$ref`-resolved form for a quick read. When this reference states a
field name, an enum member list, or a numeric default with no accompanying
reason, treat it as a drift hazard and read the schema instead. This file's job is what the schema cannot say: why a
shape is what it is, an ordering rule, a refusal condition, a worked trap.

**Canonical static occurrences.** `WorldPlacementStamp.Resolve` compiles the fixed-point
occurrences every static geometry consumer reads, including a placement's optional
`Surface` projection. Do not add terrain offsets to a renderer or collider separately.
`CompiledPlacementStamp.OccurrenceAt` retains candidate identity after rejected roots;
a compact array index is not that identity. Source restrictions and miss policy belong
to `WorldPlacementStamp.TryValidateSurface`/`WorldPlacementSurface`, not world-specific
C# code. `scatterPoints` in the world vocabulary exposes the existing PCG sampler before
authored `map`/`filter`; projection against named contact geometry follows once at
admission. Read `world.boot` surface work and created payload beside query instructions
and normal-play memory. An unchanged moving world must issue no new grounding rays.
The surface descriptor checks cache both valid and refused parent chains. Keep the
cache-miss `out` value separate from the empty success reason: `TryGetValue` assigns
null on a miss, including an ordinary unparented root's first validation.

**`.puck` is the authoring surface; JSON is the compiled wire form.** Every
JSON block in this reference and its split files is what a `.puck` source
compiles to, not the recommended way to type it; every live world under
`worlds/` is `.puck` source. The `.puck`
language itself — grammar, `let`/`template`/`import`/`export`, units, the
compile-time collection builtins, string/indexing forms, and the
`compile`/`decompile`/`lint`/`format`/`lsp` CLI verbs and `PUCKnnn` diagnostics —
is [`puck-dsl`](../../puck-dsl/SKILL.md)'s to teach; this file only states what
the WORLD vocabulary's own blocks mean (`rule`/`decision`/`shape`/`placements`/
`prototypes` sugar, section semantics, refusals) and shows worked examples in
`.puck` with their compiled JSON alongside. See "Verifying a change here"
below for the loop: `lint` → `compile --validate` → run `Puck.World`.

## Disclosure — what leaves an authority

`WorldDisclosureTier` (`src/Puck.World.Schema/WorldAdmission.cs`) is the whole vocabulary:
`frames` (no document), `presentation` (a `puck.world.projection.v1`
document), `replica` (the `puck.world.definition.v1` document verbatim, hash-identical
— the sanctioned download). The tier is authored per `admission` row as
`disclosure` and decided ONCE at the admission door; `WorldAdmissionVerdict.Tier`
carries it, and every remote egress reads it and nothing else. An absent
`disclosure` resolves to `presentation`
(`WorldAdmissionEntry.Tier`), so no world already checked in hands out a
replica. A `frames` row that also mints grants refuses by name.

`WorldProjection.Compose(definition, tier, authority, revision)` is the one
egress composer, answering `null` at `replica`/`frames` so the caller sends the
definition verbatim or nothing. `WorldProjectionDocument`'s MEMBER LIST is the
disclosure decision: it has no member for `rules`, `grants`, `state`,
`admission`, `generation`, `generators`, `groups`, `properties`, `addons`,
`storage`, `host`, `authoring`, `identity`, `inputHold`, `targetRegisters`,
`bodyMotionPrograms`, or `portals`, and its `WorldProjectedKit` row has none for
a kit's `producers`/`actions`. `adjacencies`/`destinations`/`references`/
`interactions` DO cross: `WorldAdjacencyPolicy.TryDeriveOverlap` reads them from
both sides of a seam and must derive the same depth on each. `metadata` crosses
in reduced form — `WorldProjectedMetadata` carries `title`/`description` only;
`authors`, `tags`, and `custom` never cross (`custom` is an unbounded author
scratch bag that may hold notes never meant to leave the authority).
`WorldProjection.TryToDefinition` hydrates a received projection back into a
`WorldDefinition` (undisclosed sections take their neutral built-in defaults) so
no downstream consumer changed type; a hydrated document is never saved,
journaled, or an authority. Its `observations` (composed for this recipient)
arrive as plain `state.world` rows of the disclosed cells; a disclosed vector row
names its space (`WorldObservedRow.Space`) and the projection's `spaces` carries
exactly the spaces those rows name, so it hydrates as a vector row. A projection is FLAT:
because it discloses no `state` section, `Compose` answers every
`state.<row>[.<key>]` document identifier or spatial value from the composing
authority's own state and sends the literal (`WorldStateDocumentValues.TryFlatten`,
on a rehydrated copy so the live document keeps the authored reference canonical
write-back preserves), and `TryToDefinition` refuses BY NAME a peer that still
names a cell no observed row carries. Its `timeline` carries the tick clocks and,
for each state clock a carried value keys on, an anchored clock holding a
`WorldClockAnchor` instead of the row; `Compose` takes the recipient's
`WorldClockAnchorLedger` and refuses a clock whose row's slot, or a bindable
whose bound cell (every cell for a per-body read), the recipient may not read,
while a row a bindable binds that it may read crosses in `observations` whether
or not it declares a policy, and `TryToDefinition` refuses a carried row, a malformed anchor, or a
keyed clock the timeline does not carry.

A presentation-tier recipient is fed by one `WorldProjectionFeed` (the session
sink and the federation projection sink each hold one): a whole projection first,
then member deltas (`WorldDocumentBasis.Diff`) only when a member changed, all as
compact canonical JSON (`WorldProjection.SerializeCompact`), and a
timeline delta at the authoritative ticks a held anchor's prediction misses.
A held anchor ahead of the authority's engine tick (a restore or a history seek
moved the authority behind it) is stale: `WorldClockAnchorLedger.Carry` and
`Step` drop it first, counted as a released anchor row, and carry what a fresh
recipient composed at that tick holds (the row's anchor, the clock's seed, or no
anchor), and the step's timeline delta clears it on the recipient
(`ProjectionAnchorLawTests`).
`WorldProjectionHold` is the receiving half. The feed counts under
`WorldProjectionWork` (`world.projection`), whose anchor rows retained and
released are the per-recipient anchor memory.

On the wire a document leaf is `[tier byte][version][document bytes]`
(`WorldFederationCodec.EncodeDocument`/`TryDecodeDocument`), and a
presentation-tier delta a `ProjectionDelta` leaf that adds the authoritative tick
and engine tick before the delta (`EncodeProjectionDelta`/
`TryDecodeProjectionDelta`), so a receiver names
what it was handed rather than sniffing it — the observation lane narrates it
once per tier change on stderr. A traveler's reservation carries a
`WorldIdentityProjection` (id, name, colour, move/turn rate), never its owned
document. `bodies.disclosure` (`WorldObserverDisclosure` — `all` (the
unauthored default), `radius`, `selfOnly`) redacts snapshot ENTRIES per sink at
`WorldOutputHub`, never inside the tick. `updateSeconds` samples remote QUIC
projections (default 0.03 s; zero means every authority tick) while coalescing
skipped field writes and pose-discontinuity hints. Local sinks remain full-rate.
Read back with `world.projection`,
`world.peers`' tier column, and `world.admission`'s disclosure column.

## Contents

This file is the entry point. It states the document families, the schema/DSL
framing above, the top-level `puck.world.definition.v1` member and section-grant
catalogs (with a pointer to the generated schema for everything derivable), the
capacity constants, and the routing map — then hands off to the split files
below, each covering one coherent slice of decision/gotcha prose that the
schema cannot state on its own:

| File | Read it for |
|---|---|
| [documents-rules.md](documents-rules.md) | The `rules` section: predicates, effects, zones, tables, the expression/function vocabulary a rule's operands and `score` can call, transactions, decisions. |
| [documents-state.md](documents-state.md) | The `state` section: rows/cells, kinds, envelopes, the `advance`/`dynamics`/`cycle` traits, keyed-row eviction, reserved `$` names, `state.lattices` + the `lattice` trait, authored randomness (source/site/moment), `search`, `navigation`, the tabletop primitive, discrete-board patterns, records, pools, and retained turns. |
| [documents-render.md](documents-render.md) | `render` defaults, `dynamics` (the personality table), `curves`, `views.graphs`, kit producer `flock`, crowd-scale policies, render validation and stamp capacity, the `rigid`/`carry`/`tether` facets. |
| [documents-motion.md](documents-motion.md) | A kit's `motion` row: `holds` (the only spelling of a vertical channel), `shaping` (velocity response), behaviour as program operations and their parameters (`planarTarget`), the worked kart example, body facts on the wire, `views.seatRig`. |
| [documents-composition.md](documents-composition.md) | Boot-authored topology/timing members (`References`, `Gravity`, `Portals`, `Simulation`, `Adjacencies`, `Metadata`); engine facts the quarantined worlds exercised (placement primitives, derived limits, author frame, body scale, contact); the sculpting library; `basis`/`imports` composition and merge rules; the validator; serialization conventions. |
| [documents-identity.md](documents-identity.md) | Owned-world identity documents: the catalog, seeding, discard/refusal classes, `WorldIdentity`, facts, seating, cross-document durable-state writes. |
| [input: bindings.md](../../input/references/bindings.md) | `WorldBindingComposer`: layer merge rules, context rows, wheel rows, the binding bar (the `input` skill owns it). |

## `puck.world.definition.v1`

`WorldDefinition` is one aggregate record whose positional section members are
all optional — every one carries `[JsonIgnore(Condition =
WhenWritingNull)]` and a `= null` default, so a document declaring none of
them still parses, and each section's own resolving accessor (the plain-named
property beside the `…Raw` constructor parameter) answers its own documented
ABSENT behavior. Declaration (= canonical-write) order is the contract a
`with`-expression or a new member's insertion point must respect. Reading
selectively: `Motion`, `SpawnPoints`, `Render`, `Screens`, `Machines`
(`WorldMachine.cs` — named deterministic devices whose lifetime is independent
of their output consumers: `name`/`engine`/`configuration` — provider-validated
— `running`, ordered `memory` bindings to Int world-state cells, and an
optional `cable` endpoint; `gaming-bricks`/`rom-forge` own the hosted-engine
contract, and `WorldScreenSource`'s `machine` case is how a screen displays
one), `Cameras`, `Population`, `PlayerDefaults`, `Channels`, `TargetRegisters`,
`BodyMotionPrograms`, `Kits`, `DefaultSeatKit`, `Assignment`, `Addons`,
`BindingOverlays`, `Storage`, `Creations`, `Placements`, `Authoring`,
`Speakers`, `Tunes`, `Patches`, `Audio`, `Collision`, `Gravity`, `Host`, `Views`,
`Looks`, `LookAssignment`, `Dynamics`, `Curves`, `Grants`, `Hud`, `State`,
`InputHold` (its own type, `WorldInputHoldAuthoring`, is the AUTHORED seconds
shape — `WorldDefinition.CompiledInputHold` is the compiled ticks form
runtime code consumes; see `WorldInputHoldSettings`'s remarks), `Rules`,
`Identity`, `Groups`, `Properties`, `Interactions`, `Generation`,
`Generators`, `References`, `Portals`,
`Simulation`, `Destinations`, `Admission`, `Adjacencies`, `Text`,
`Metadata`, `Icons`, `Theme`, `Markers`, `SeatModes`, `Probes`, `Captures`,
`Schedule`, `Update`, `Music`, `Navigation`, `Patterns`, `Tables`, `Search`,
`RuleGroups`, `Sets`, `Editor`, and `Timeline` — plus `Schema` and the
`[JsonExtensionData]` `Extensions` bag.
Scenery is authored through `Placements`.

`Dynamics`, `Curves`, `Rules`, `References`, `Gravity`, `Portals`,
`Simulation`, `Adjacencies`, and `Metadata` each carry decision/derivation
prose the schema cannot state — see
[documents-render.md](documents-render.md), [documents-rules.md](documents-rules.md),
and [documents-composition.md](documents-composition.md) respectively. Every
field NAME, type, and default not called out in one of those files is the
generated schema's to answer.

The `WorldSection` enum (`src/Puck.World.Schema/WorldGrant.cs`, declared
order — read the enum for the current member list): `Kits, Screens, Machines,
Cameras, Spawns, Motion, Population, Render, Addons,
Bindings, Creations, Placements, Authoring, Speakers, Tunes, Patches, Audio,
Collision, Host, Views, Looks, Grants, Hud, State, InputHold, Rules,
Groups, Properties, Interactions, PlayerDefaults, Probes, Dynamics,
Curves, Tables`.
It is the grant subject vocabulary
(`section:<name>`) and the mutation dispatch axis — narrower than
`WorldDefinition`'s own member list above: `Channels`,
`TargetRegisters`, `BodyMotionPrograms`, `Storage`, `Identity`,
`Generation`, `Generators`, `References`, `Portals`, `Simulation`,
`Destinations`, `Admission`, `Adjacencies`, `Text`, and `Metadata` carry no dispatch axis of their own (some
names also differ — `SpawnPoints`/`BindingOverlays`/`LookAssignment`/
`DefaultSeatKit`/`Assignment` dispatch through `Spawns`/`Bindings`/`Looks`/
`Kits` respectively; `PlayerDefaults` dispatches through
`WorldMutation.SetPlayerDefaults`). `Probes` is boot-authored
only — no `WorldMutation` kind targets it, so the section-scoped grant hold is
its whole authority surface.

## Capacity constants

- WorldBodiesLimits.CapacityCeiling is 4,096; each world authors its actual capacity. 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.
- `WorldHudCapacity` (`WorldHud.cs`): see [hud.md](hud.md).
- `StateCapacity` (`Puck.State/StateRow.cs`): `MaxRows = 1024`,
  `MaxCellsPerRow = TopologyCompilation.MaxCells` (an authored `capacity` may only narrow it),
  `MaxTextValueLength = 1024` (UTF-16 units, a text cell's value), and
  `MaxBodySlots = 128` across the `body` and `identity` lanes (the fixed
  per-body register/checkpoint width).
- WorldPlacementPolicy keeps the per-world 32,768 solid-collider ceiling and timeline cadence. Derived faces start after authored screen indices. No interpreter-era scene envelope is admitted or reserved.

## Routing map (one line each, all under `src/Puck.World.Schema/`)

- `WorldJsonPayload.cs` — the single door for author-supplied JSON text
  (`TryParse`, `IsParseFailure`, 120-char elided rejections).
- Refusal taxonomy (outside this directory): `src/Puck.State/RuleRefusal.cs`
  declares `RefusalKind` (protocol-fault vs verdict) and the
  `[Refusal(door, condition, kind)]` attribute; `src/Puck.World/RefusalCatalog.cs`
  builds the catalog `world.refusals` prints.
- `WorldAnchor.cs` — WHERE a placeable thing rides (shared by cameras and
  speakers); `WorldCameraProgram.cs` — HOW a camera frames, as an authored op
  list (`Puck.World.Client.WorldCameraRigCompiler` translates it to the
  document-blind IR in `Puck.SdfVm.Views`; see [views.md](views.md)).
- `WorldViews.cs` — the `views` section (slots, layouts, seat framing).
- `WorldState.cs` — the `state` section: `WorldStateSection` (the document's
  `IStateSection` — `world` rows, `body`/`identity` slot lanes, `lattices`) and
  `WorldStateRow` (a `Puck.State.StateRow` plus the `gatesDrive` and `field`
  traits). The row/cell substrate (`StateRow`, `StateCell`, `StateCapacity`), the
  domains (`StateDomain`, a closed union over `Puck.State/Union.cs`'s `[Union]`
  marker), the traits, the catalog (`StateCatalog`: ownership lane, storage shape,
  value kind, stable handle and lane-local ordinals), the topologies, the
  generators, and the patterns live in `src/Puck.State/`. See
  [documents-state.md](documents-state.md).
- `WorldDefinitionRows.cs` — the one row-find per section
  (`FindCreation`/`FindPlacement`/`FindKit`/`FindSpawnPoint`/`FindStateRow`),
  ordinal and allocation-free.
- `WorldStateReader.cs` — the definition-anchored door to `Puck.State.StateReader`,
  the ONE `(rows, rowName, key, tick)` → `(row, rawValue, text)` read over the
  `state` section. See [documents-state.md](documents-state.md).
- `WorldSpeaker.cs` — speaker rows, feeds, emission facets, tune/patch asset
  rows, audio defaults.
- `WorldColor.cs` — golden-ratio index palette for simulated avatars.
- `WorldHostTokens.cs` — the one spelling for backend/surface-format tokens
  (JSON converters + the `world.row.set host` payload grammar).
- `WorldAdjacencies.cs` — the authored boundary rows, fixed frame compilation,
  crossing test, derived overlap, reciprocal hysteresis, and corner topology;
  see [adjacency-and-federation.md](adjacency-and-federation.md) and
  [documents-composition.md](documents-composition.md).
- `ShadowTier.cs` — the shadow tier: off, or the cascades' resolution
  (`world.shadows`, `render.shadows`, a preset's `shadows`), which
  `WorldFramePresenter.ShadowResolutionOf` maps to `SdfShadowResolution`.
- `BindingVocabularyHook.cs` — the static injection seam the composition
  root wires with a `[ModuleInitializer]` (`WorldDataHookInstaller` in
  `Puck.World`) so validators reach the input vocabulary without this
  project referencing `Puck.Input`. See [bindings.md](../../input/references/bindings.md).

## Verifying a change here

**`.puck` sources first.** Edit the `.puck` file, then `puck lint <file> --strict`
(static + reference checks; self-installs the machine catalog so `Machines`/
cartridge-hosted checks resolve — no separate registration step), then
`puck compile <file> --validate` (lowers to JSON AND runs the SAME semantic
engine schema rules `WorldDefinitionValidator` enforces at boot — this is the
DSL-side closure with "The validator" in
[documents-composition.md](documents-composition.md), which also says what an
`import` brings in).
`puck decompile <path.json> [-o path.puck]` runs the reverse for an
existing hand-authored or generator-produced JSON world. None of the three
verbs touch a running `Puck.World`. Grammar, flags, and diagnostics beyond
this are [`puck-dsl`](../../puck-dsl/SKILL.md)'s.

**Then the engine.** No engine gate. Build the projects the change
touched (`dotnet build <project> -c Release -nodeReuse:false`; the integration
lane builds `Puck.slnx`, which carries the architecture lanes and XML-doc
diagnostics) and run `Puck.World`,
round-tripping the affected document over stdin (`world.status`, `world.save`,
`world.load`). Proven in-process by
`tests/Puck.World.Schema.Tests/StrictParseLawTests.cs`. Validate HUD document changes
by running the app — see [hud.md](hud.md)'s "Verifying" section for the
recipe. A `.puck` source compiled through `--validate` still needs this step:
`--validate` runs the same rules the boot path does, but only running the app
proves a document plays.
finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the workStars: 322kUpdated Claude CodeCodexVerifiedInstall
systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixesStars: 322kUpdated Claude CodeCodexVerifiedInstall
test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation codeStars: 322kUpdated Claude CodeCodexVerifiedInstall
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: 198kUpdated Claude CodeCodexVerifiedInstall