@jgengine/shell 0.18.0 → 0.18.1

package/skills/jgengine-world/capabilities.md

@@ -4,6 +4,10 @@
 
 Reach for these before hand-rolling. Each row is *the thing you need* → *the primitive that already does it*.
 
+## ai-decision-graph — Evaluate serializable selector, sequence, condition, action, and utility AI decisions.
+
+- `createDecisionGraphRuntime` (function) · `import { createDecisionGraphRuntime } from "@jgengine/core/ai/decisionGraph"`
+
 ## ai-driver — difficulty-aware chase/route driving step producing throttle/brake/steer for the vehicle sim
 
 - `driveStep` (function) · `import { driveStep } from "@jgengine/core/ai/driver"`
@@ -16,6 +20,16 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `createDriverState` (function) · `import { createDriverState } from "@jgengine/core/ai/driver"`
 
+## anim-graph — data-first animation state machine with blend trees, crossfades, layers, and clip events
+
+- `createAnimGraphRuntime` (function) · `import { createAnimGraphRuntime } from "@jgengine/core/anim/animGraph"`
+
+## animation — inverse kinematics orient a bone toward a target with constrained yaw and pitch
+
+- `lookAt` (function) · `import { lookAt } from "@jgengine/core/anim/ikSolver"`
+- `solveFabrik` (function) · `import { solveFabrik } from "@jgengine/core/anim/ikSolver"`
+- `solveTwoBone` (function) · `import { solveTwoBone } from "@jgengine/core/anim/ikSolver"`
+
 ## area-effect-field — source-following area membership with enter/refresh/leave edges, stacking, and cleanup
 
 - `createAreaEffectField` (function) · `import { createAreaEffectField } from "@jgengine/core/world"`
@@ -102,6 +116,10 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 - `registerBuiltinTriggerActions` (function) · `import { registerBuiltinTriggerActions } from "@jgengine/core/scene/authoredTriggers"`
 - `registerTriggerAction` (function) · `import { registerTriggerAction } from "@jgengine/core/world"`
 
+## behavior-actions — register named callbacks for decision graph behavior descriptors
+
+- `registerBehaviorActions` (function) · `import { registerBehaviorActions } from "@jgengine/core/world"`
+
 ## behavior-control — pause/disable/resume/seek/inspect behavior instances per entity
 
 - `behaviorControl` (function) · `import { behaviorControl } from "@jgengine/core/world"`
@@ -142,6 +160,10 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `createCameraShake` (function) · `import { createCameraShake } from "@jgengine/core/world"`
 
+## character-controller — capsule walk over the physics backend — slide, step-up, slopes, crouch, platforms
+
+- `createCharacterController` (function) · `import { createCharacterController } from "@jgengine/core/movement/characterController"`
+
 ## city-district — polygon math for road-derived blocks, parcels, and buildable footprints
 
 - `Vec2` (type) · `import { Vec2 } from "@jgengine/core/world/cityGeometry"`
@@ -279,6 +301,14 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `DEFAULT_FORWARD` (const) · `import { DEFAULT_FORWARD } from "@jgengine/core/world"`
 
+## free-flight — camera-relative creative/spectator/noclip/hover flight with correct strafe, sprint, and optional gravity
+
+- `createFreeFlightController` (function) · `import { createFreeFlightController } from "@jgengine/core/world"`
+
+## gamepad-input — Resolve sampled gamepad input into actions with deadzones and response curves.
+
+- `resolveGamepadFrame` (function) · `import { resolveGamepadFrame } from "@jgengine/core/input/gamepadModel"`
+
 ## glide — gliding/wingsuit descent control from a launch
 
 - `createGlideModel` (function) · `import { createGlideModel } from "@jgengine/core/world"`
@@ -337,6 +367,10 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `generateLock` (function) · `import { generateLock } from "@jgengine/core/world"`
 
+## locomotion-graph — build the default idle/walk/run plus one-shot graph from clip names
+
+- `locomotionGraph` (function) · `import { locomotionGraph } from "@jgengine/core/anim/locomotionGraph"`
+
 ## map-annotations — player-drawn map annotation layer — freehand strokes, area shapes, and pinned notes, projected into the map's routes/zones props and serializable
 
 - `createAnnotationLayer` (function) · `import { createAnnotationLayer } from "@jgengine/core/world"`
@@ -378,6 +412,10 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `createOrderRegistry` (function) · `import { createOrderRegistry } from "@jgengine/core/world"`
 
+## particle-director — game-reachable VFX seam: queue one-shot particle bursts and keyed follow-capable standing emitters as serializable data for the shell to render
+
+- `createParticleDirector` (function) · `import { createParticleDirector } from "@jgengine/core/vfx/particleDirector"`
+
 ## particle-system — deterministic pooled particle emitter with SoA render buffers, burst/continuous emission, gravity/drag, size/color/alpha-over-life, and serializable state
 
 - `createParticleSystem` (function) · `import { createParticleSystem } from "@jgengine/core/world"`
@@ -403,6 +441,22 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `definePatrolOrder` (function) · `import { definePatrolOrder } from "@jgengine/core/world"`
 
+## perception-service — retain sight, sound, and damage observations with range, cone, occlusion, and decay policy
+
+- `createPerception` (function) · `import { createPerception } from "@jgengine/core/sensor/perception"`
+
+## physics-backend — one interface over interchangeable rigid-body solvers — bodies, joints, raycast, shapecast, snapshot
+
+- `PhysicsBackend` (interface) · `import { PhysicsBackend } from "@jgengine/core/physics/physicsBackend"`
+
+## physics-backend-conformance — the shared test contract a physics adapter runs to prove it matches the seam
+
+- `runPhysicsBackendConformance` (function) · `import { runPhysicsBackendConformance } from "@jgengine/core/physics/physicsBackendConformance"`
+
+## physics-world-backend — the zero-dependency PhysicsWorld solver exposed through the PhysicsBackend seam
+
+- `createPhysicsWorldBackend` (function) · `import { createPhysicsWorldBackend } from "@jgengine/core/physics/physicsWorldBackend"`
+
 ## piece-sockets-from-model — derive build-piece snap sockets from a model's named attach points
 
 - `pieceSocketsFromModel` (function) · `import { pieceSocketsFromModel } from "@jgengine/core/world/buildSockets"`
@@ -451,6 +505,14 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `evaluateQteSequence` (function) · `import { evaluateQteSequence } from "@jgengine/core/world"`
 
+## rapier-physics-backend — native capsules, shapecasts, rotation, CCD, joints, and collision queries
+
+- `createRapierBackend` (function) · `import { createRapierBackend } from "@jgengine/rapier"`
+
+## rate-window-policy — Evaluate deterministic request windows with retry timing.
+
+- `decideRateWindow` (function) · `import { decideRateWindow } from "@jgengine/core/time/rateWindow"`
+
 ## reputation — faction standing that crosses named reputation tiers
 
 - `tierForStanding` (function) · `import { tierForStanding } from "@jgengine/core/world"`
@@ -560,6 +622,14 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `surfaceRing` (function) · `import { surfaceRing } from "@jgengine/core/world"`
 
+## tactical-cover-points — derive cover candidates from navigation-mesh boundaries
+
+- `coverPoints` (function) · `import { coverPoints } from "@jgengine/core/ai/tacticalQueries"`
+
+## tactical-position-score — rank bounded tactical positions with caller-defined weights
+
+- `scorePositions` (function) · `import { scorePositions } from "@jgengine/core/ai/tacticalQueries"`
+
 ## target-acquirer — stateful held-target wrapper over an acquisition policy with retention
 
 - `createTargetAcquirer` (function) · `import { createTargetAcquirer } from "@jgengine/core/world"`
@@ -584,6 +654,30 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `raycastHeightField` (function) · `import { raycastHeightField } from "@jgengine/core/world/terrain"`
 
+## territory-cell-chunk — Map ownership cells to persisted world chunks.
+
+- `territoryChunkKey` (function) · `import { territoryChunkKey } from "@jgengine/core/world/territory"`
+
+## territory-footprint — Resolve exactly the ownership cells touched by a placement footprint.
+
+- `territoryFootprintCells` (function) · `import { territoryFootprintCells } from "@jgengine/core/world/territory"`
+
+## territory-owner-query — Read a loaded land cell owner for authoritative placement checks.
+
+- `territoryOwnerOf` (function) · `import { territoryOwnerOf } from "@jgengine/core/world/territory"`
+
+## territory-ownership — Claim, release and query land through host-owned snapshot storage.
+
+- `createTerritory` (function) · `import { createTerritory } from "@jgengine/core/world/territory"`
+
+## territory-placement — Purchase footprint cells atomically with object placement.
+
+- `placeWithTerritory` (function) · `import { placeWithTerritory } from "@jgengine/core/world/territory"`
+
+## territory-read-scope — Load the footprint and foreign-owner gap without scanning the world.
+
+- `territoryChunkKeys` (function) · `import { territoryChunkKeys } from "@jgengine/core/world/territory"`
+
 ## touch-controls — switch the on-screen touch control set when gameplay context changes (enter/exit vehicle, mount, build mode)
 
 - `setTouchControlsMode` (function) · `import { setTouchControlsMode } from "@jgengine/core/input/touchControlsMode"`
@@ -601,6 +695,10 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `resolveWalkerStep` (function) · `import { resolveWalkerStep } from "@jgengine/core/movement/solidObstacles"`
 
+## walker-solid-step-source — slide a step against solid geometry from a pure rules package
+
+- `resolveSourceWalkerStep` (function) · `import { resolveSourceWalkerStep } from "@jgengine/core/movement/solidObstacles"`
+
 ## wave-runner — observable serializable wave/spawn runner over the seeded spawn director — WAVE N, wave progress, budget/alert readout, onSpawn sink, snapshot/restore
 
 - `createWaveRunner` (function) · `import { createWaveRunner } from "@jgengine/core/world"`
@@ -620,6 +718,10 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 - `buildTrimmedIntersections` (function) · `import { buildTrimmedIntersections } from "@jgengine/core/world"`
 - `trimBandAtJunctions` (function) · `import { trimBandAtJunctions } from "@jgengine/core/world"`
 
+## world-physics-colliders — Synchronize terrain and authored static colliders with a physics backend.
+
+- `syncWorldColliders` (function) · `import { syncWorldColliders } from "@jgengine/core/physics/worldColliders"`
+
 ## world-place — declare the place a game happens in — flat/round/voxel/board ground, surface laws, per-place physics
 
 - `world` (function) · `import { world } from "@jgengine/core/world"`

package/skills/level-design/SKILL.md

@@ -11,7 +11,7 @@ Own the spatial realization of game design: player metrics, topology, routes, la
 
 All authorable world content belongs in `editor.scene.json`, changed through the editor GUI or RPC/CLI. Never hand-edit the document or keep geometry, paths, spawns, zones, objectives, terrain, foliage, encounters, or coordinate arrays in code. File an editor `[FEATURE]` issue before any fallback.
 
-Read [references/application-playbook.md](references/application-playbook.md) only when the task explicitly calls for spatial design depth — a level/world design brief, an audit or redesign, or "make this fun/better" work; it is not a mandatory step of creating a game. Read [references/live-editor-loop.md](references/live-editor-loop.md) whenever live captures, an editor-agent handoff, or iterative scene improvement is involved. Read [references/field-guide.md](references/field-guide.md) for metric families, topology, pacing, genre lenses, accessibility, and research.
+For a greenfield build, read [references/application-playbook.md](references/application-playbook.md) and produce its greenfield contract (promise, pillars, anti-pillars, core decision, and falsifier) before writing code. Audits may read only the playbook's audit sections. Read [references/live-editor-loop.md](references/live-editor-loop.md) whenever live captures, an editor-agent handoff, or iterative scene improvement is involved. Read [references/field-guide.md](references/field-guide.md) for metric families, topology, pacing, genre lenses, accessibility, and research.
 
 ## Choose the mode
 

package/skills/jgengine-ui/references/visual-scorecard.md

@@ -1,73 +0,0 @@
-# Visual scorecard
-
-This repeatable 0–3 rubric makes "looks shipped" consistent across sessions and usable by a fresh-eyes reviewer. Apply it to milestone shots, not every tweak, and place the scored table beside PR screenshots.
-
-Structure and thresholds adapted (concept only, reworded for this stack — not copied verbatim) from `majidmanzarpour/threejs-game-skills`' `visual-scorecard.md` (MIT); see `CREDITS.md`.
-
-## The 0–3 scale
-
-Score each category independently against what's actually in the shot, not what the code intends.
-
-| Score | Meaning |
-| --- | --- |
-| **0** | Engine defaults or debug output. Untextured primitives, default grey material, flat ambient light, no sky/fog treatment, no authored placement. |
-| **1** | Basic styled prototype. Readable and on-genre, but generic — solid-color materials, one light, sparse or untuned `AuthoredScene` content, no distinct silhouettes. |
-| **2** | Premium stylized. Authored silhouettes on hero/obstacles, a coherent material system (not one grey PBR everywhere), tuned `environment()` lighting/sky/post, foliage and props placed through the editor read as a real place, not a demo. |
-| **3** | Showcase art direction. Everything in 2, plus: no repeated silhouette anywhere in frame, deliberate foreground/midground/background composition, purposeful VFX and motion, a HUD that could not be mistaken for another game. Reads like a store page, not a build. |
-
-## The 10 categories
-
-Score all ten from one `--mode play` shot plus deterministic world/document evidence from `jgengine-verify`. Data presence is a prerequisite, not a substitute for visual judgment.
-
-1. **Art direction** — one coherent palette and mood across ground, props, sky, and UI; not three unrelated hue choices stapled together.
-2. **Hero/player** — an authored silhouette and material set the player is meant to be, not a default primitive or a capsule with an emissive glow standing in for a character.
-3. **Obstacles/enemies** — distinct types read apart at a glance; not one mesh reused at different scales/colors.
-4. **Rewards/interactables** — visually distinct from hazards and terrain at a glance, not the same proxy geometry as everything else.
-5. **World/environment** — foreground, midground, and background read as separate layers (props/landmarks near camera, terrain shaping mid-distance, sky/fog treatment at the horizon); not one flat plane running to a bare horizon.
-6. **Materials/textures** — terrain and props carry texture and color variation (`environment({ sculpt, materialRegions })`, catalog GLBs via `jgengine-assets`), not flat untextured solids.
-7. **Lighting/render** — a tuned daylight/sun+hemisphere rig and post stack (per `look: "cinematic"`, #773), not the bare untouched three.js default light.
-8. **VFX/motion** — particle/motion feedback tied to actual gameplay events (hits, pickups, weather), not absent, and not one looping default effect standing in everywhere.
-9. **UI/HUD** — a game-specific `HudCanvas`/`HudPanel` composition with unique art direction; fails automatically if it could pass for a generic admin dashboard **or** for another game shipping stock engine widgets/theme presets unskinned.
-10. **Performance evidence** — the look holds at the scale the game actually runs (`InstancedScatter` density, many entities), not only a hand-posed hero shot with three objects in frame.
-
-## Measured-evidence row
-
-Pixel metrics from `bun run shoot <id> --mode play --inspect` (or `bun run inspect-shot.ts <shot.png>` on an existing PNG — [#788](https://github.com/Noisemaker111/jgengine/issues/788), shipped) are the objective inputs to categories 5–7 — they don't replace the eye, they catch what a rushed glance misses. Output lands at `shots/<name>.metrics.json`:
-
-| Metric | Threshold | Flags |
-| --- | --- | --- |
-| `colorEntropyBits` | `< 3.0` | sparse palette |
-| `dominantColorShare` | `> 0.6` | sparse / one material dominates the frame |
-| `edgeDensity` | `< 0.04` | primitive-dominant, too few silhouettes |
-| `luminance.contrast` | `< 60` | fog/post compressing out real geometry |
-
-Any metric over threshold caps the affected category at **1** regardless of how the shot reads by eye — the number is a floor, not a veto the eye can talk it out of. `--strict` hard-fails on a crossed threshold for CI; the scorecard itself always records this row from the JSON, never "not measured."
-
-## Pass thresholds
-
-- **Premium**: every category ≥ 2, average ≥ 2.3.
-- **Showcase**: at least 6 categories at 3, no category < 2, average ≥ 2.7.
-
-Below "premium" on a claimed milestone is not shippable; keep working the art stack or narrow the claim.
-
-## Automatic failures
-
-Any one of these fails the shot regardless of the averaged score:
-
-- **Primitive-dominant shots** — untextured boxes/spheres/cylinders make up the visible mass of the frame.
-- **Default primitive + glow standing in for a hero** — an emissive-glow capsule/sphere is not a character, even at full brightness.
-- **One repeated silhouette everywhere** — `InstancedScatter`'s stylized proxy species (or any single catalog model) used with no palette variety across the whole visible world.
-- **Fog/bloom hiding missing geometry** — atmosphere used to obscure an empty or unfinished scene instead of to add depth to a populated one.
-- **No active-play shot** — only editor/menu/poster shots submitted. `--mode play` (or `drive` past the menu) evidence is mandatory; a scene that only looks good in the editor camera hasn't proven anything about how the game actually reads.
-
-## Fresh-eyes review and the lower-score rule
-
-Hand a reviewer **only** the screenshots, this rubric, and the measured-evidence JSON — no PR description, no "here's what I was going for." A reviewer who knows the intent scores the intent; a fresh reviewer scores the pixels, which is the only thing a player ever sees.
-
-- The author scores first (self-score).
-- A fresh-eyes pass (a different session, or the same session after clearing framing context) scores independently.
-- Where the two disagree, **the PR carries the lower score**, never the average and never the higher one. Optimistic self-scoring is the failure mode this guards against — take the lower number and keep working the art stack instead of arguing the rubric.
-
-## Using this in a PR
-
-Any PR that changes what a player sees pastes the ten-category table (score + one-line reason per category below 2), the measured-evidence row, and the reconciled score next to embedded screenshots. Report that verdict through `jgengine-verify`'s evidence format.