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