@jgengine/shell 0.11.0 → 0.12.0

package/skills/jgengine-world/capabilities.md

@@ -63,16 +63,30 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `defineAttackMoveOrder` (function) · `import { defineAttackMoveOrder } from "@jgengine/core/world"`
 
-## authored-objects — place catalog mesh props from an editor document
+## authored-entities — spawn authored mob/boss markers from the editor document at runtime
 
+- `authoredEntitySpawns` (function) · `import { authoredEntitySpawns } from "@jgengine/core/world/authoredEntities"`
+
+## authored-objects — marker kinds resolved as entity spawns, not static props
+
+- `ENTITY_MARKER_KINDS` (const) · `import { ENTITY_MARKER_KINDS } from "@jgengine/core/world/authoredObjects"`
 - `markerCatalogId` (function) · `import { markerCatalogId } from "@jgengine/core/world"`
 - `placeAuthoredObjects` (function) · `import { placeAuthoredObjects } from "@jgengine/core/world"`
 - `resolveAuthoredObjects` (function) · `import { resolveAuthoredObjects } from "@jgengine/core/world"`
 
-## authored-triggers — schema'd on/action vocabulary on volumes and markers with runtime dispatch
+## authored-spawn — read spawn points and markers from the editor document
+
+- `authoredSpawnPosition` (function) · `import { authoredSpawnPosition } from "@jgengine/core/world/authoredSpawn"`
+- `authoredSpawnRotation` (function) · `import { authoredSpawnRotation } from "@jgengine/core/world/authoredSpawn"`
+- `markersOfKind` (function) · `import { markersOfKind } from "@jgengine/core/world/authoredSpawn"`
 
+## authored-triggers — built-in announce/win/advance actions authorable on any marker or volume
+
+- `BUILTIN_TRIGGER_ACTIONS` (const) · `import { BUILTIN_TRIGGER_ACTIONS } from "@jgengine/core/scene/authoredTriggers"`
 - `collectAuthoredTriggers` (function) · `import { collectAuthoredTriggers } from "@jgengine/core/world"`
 - `createAuthoredTriggerRuntime` (function) · `import { createAuthoredTriggerRuntime } from "@jgengine/core/world"`
+- `createTriggerOutcome` (function) · `import { createTriggerOutcome } from "@jgengine/core/scene/authoredTriggers"`
+- `registerBuiltinTriggerActions` (function) · `import { registerBuiltinTriggerActions } from "@jgengine/core/scene/authoredTriggers"`
 - `registerTriggerAction` (function) · `import { registerTriggerAction } from "@jgengine/core/world"`
 
 ## behavior-control — pause/disable/resume/seek/inspect behavior instances per entity
@@ -87,6 +101,27 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `createBodyBind` (function) · `import { createBodyBind } from "@jgengine/core/world"`
 
+## build-footprint-cells — grid cells a snapped build piece footprint covers (footprintGrid occupancy bridge)
+
+- `footprintCells` (function) · `import { footprintCells } from "@jgengine/core/world/buildSockets"`
+
+## build-socket-catalog — data-driven named-socket snap catalog for modular base building
+
+- `createBuildSocketCatalog` (function) · `import { createBuildSocketCatalog } from "@jgengine/core/world/buildSockets"`
+
+## city-district — polygon math for road-derived blocks, parcels, and buildable footprints
+
+- `Vec2` (type) · `import { Vec2 } from "@jgengine/core/world/cityGeometry"`
+- `resolveCityObject` (function) · `import { resolveCityObject } from "@jgengine/core/world"`
+
+## companion-intent — resolve a companion's command + threat context into a per-tick follow/hold/engage/assist intent
+
+- `resolveCompanionIntent` (function) · `import { resolveCompanionIntent } from "@jgengine/core/scene/companion"`
+
+## companion-roster — manage tamed companions — allegiance, commands, per-companion stats/leveling, and mobBrain-shaped intent
+
+- `createCompanionRoster` (function) · `import { createCompanionRoster } from "@jgengine/core/scene/companion"`
+
 ## contour-interval — readable auto-spacing for elevation contours
 
 - `chooseContourInterval` (function) · `import { chooseContourInterval } from "@jgengine/core/world"`
@@ -111,6 +146,10 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `entityMetaOf` (function) · `import { entityMetaOf } from "@jgengine/core/world"`
 
+## flight-dynamics — simulate fixed-wing, helicopter, and VTOL aircraft
+
+- `createAircraftDynamics` (function) · `import { createAircraftDynamics } from "@jgengine/core/world"`
+
 ## follow-trail — trailing follower/snake formation that chases a leader
 
 - `createLeaderTrail` (function) · `import { createLeaderTrail } from "@jgengine/core/world"`
@@ -159,6 +198,12 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `createGrappleSwing` (function) · `import { createGrappleSwing } from "@jgengine/core/world"`
 
+## gravity-field — sample configurable uniform, radial, or combined gravity
+
+- `combineGravity` (function) · `import { combineGravity } from "@jgengine/core/world"`
+- `pointGravity` (function) · `import { pointGravity } from "@jgengine/core/world"`
+- `uniformGravity` (function) · `import { uniformGravity } from "@jgengine/core/world"`
+
 ## hold-order — stand-ground order that holds position until preempted or canceled
 
 - `defineHoldOrder` (function) · `import { defineHoldOrder } from "@jgengine/core/world"`
@@ -191,6 +236,23 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `generateLock` (function) · `import { generateLock } from "@jgengine/core/world"`
 
+## mesh-hitboxes — shots pass through holes in concave models — opted-in catalog assets raycast their actual triangles instead of the fitted box.
+
+- `ColliderShape` (type) · `import { ColliderShape } from "@jgengine/core/scene/colliders"`
+
+## mesh-movement — the walking player slides against a mesh collider's compound `boxes` — a capsule walks THROUGH an opted-in archway opening and is stopped by its pillars/lintel instead of one outer box.
+
+- `ColliderShape` (type) · `import { ColliderShape } from "@jgengine/core/scene/colliders"`
+
+## minimap-bake — rasterize authored terrain + zones into a top-down minimap image
+
+- `bakeMinimapImage` (function) · `import { bakeMinimapImage } from "@jgengine/core/world"`
+- `minimapBakeToPngDataUri` (function) · `import { minimapBakeToPngDataUri } from "@jgengine/core/world"`
+
+## minimap-track — project a world point to a 0..1 fraction along a linear track axis
+
+- `trackFraction` (function) · `import { trackFraction } from "@jgengine/core/world/minimapTrack"`
+
 ## model-sockets — named attachment points read from a model
 
 - `ModelNode` (interface) · `import { ModelNode } from "@jgengine/core/world"`
@@ -219,6 +281,10 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `pathLength` (function) · `import { pathLength } from "@jgengine/core/world"`
 
+## path-network — build a deterministic road/track graph (nodes, edges, streets, junctions, bridges, tunnels) from sliders
+
+- `buildPathNetwork` (function) · `import { buildPathNetwork } from "@jgengine/core/world/pathNetwork"`
+
 ## path-terrain — apply flatten/grade/carve/retaining path profiles to a terrain field
 
 - `applyPathProfiles` (function) · `import { applyPathProfiles } from "@jgengine/core/world"`
@@ -228,6 +294,10 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `definePatrolOrder` (function) · `import { definePatrolOrder } from "@jgengine/core/world"`
 
+## 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"`
+
 ## place-asset — resolve a placement commit into a shared asset placement payload
 
 - `PlaceAssetResult` (interface) · `import { PlaceAssetResult } from "@jgengine/core/world"`
@@ -248,10 +318,26 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 - `parseRotationPolicy` (function) · `import { parseRotationPolicy } from "@jgengine/core/world"`
 - `snapHeading` (function) · `import { snapHeading } from "@jgengine/core/world"`
 
+## pole-line — editor-authorable poles + sagging cables along a path
+
+- `POLE_LINE_KIND` (const) · `import { POLE_LINE_KIND } from "@jgengine/core/world/poleLineKind"`
+
+## population-director — ambient per-region creature population manager with timed weighted respawns and caps
+
+- `createPopulationDirector` (function) · `import { createPopulationDirector } from "@jgengine/core/ai/populationDirector"`
+
+## portable-marker-source — project caller-owned arrays or subscribable stores into cached minimap marker snapshots without a MarkerSet
+
+- `createMarkerSource` (function) · `import { createMarkerSource } from "@jgengine/core/world"`
+
 ## proximity-prompt — a "press E" contextual prompt shown near an interactable
 
 - `resolveActivePrompt` (function) · `import { resolveActivePrompt } from "@jgengine/core/world"`
 
+## pursuit — chase-to-reach cooldown-gated attack with optional leash-to-home; owns the attack cooldown
+
+- `advancePursuit` (function) · `import { advancePursuit } from "@jgengine/core/ai/pursuit"`
+
 ## qte — a quick-time-event timed input sequence with hit windows
 
 - `evaluateQteSequence` (function) · `import { evaluateQteSequence } from "@jgengine/core/world"`
@@ -260,6 +346,10 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `tierForStanding` (function) · `import { tierForStanding } from "@jgengine/core/world"`
 
+## resource-node — depletable, respawning harvest nodes with tool-dependent yields
+
+- `createResourceNodeField` (function) · `import { createResourceNodeField } from "@jgengine/core/world/resourceNode"`
+
 ## rts-control-groups — map Ctrl+digit / digit / double-tap presses onto selection-bookmark bind / recall / focus intents
 
 - `controlGroupKey` (function) · `import { controlGroupKey } from "@jgengine/core/world"`
@@ -357,6 +447,10 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `terrainContourGuides` (function) · `import { terrainContourGuides } from "@jgengine/core/world"`
 
+## terrain-raycast — pick a point on a heightfield along a camera/pointer ray
+
+- `raycastHeightField` (function) · `import { raycastHeightField } from "@jgengine/core/world/terrain"`
+
 ## touch-controls — default on-screen button silhouette for a touch action
 
 - `touchButtonShape` (function) · `import { touchButtonShape } from "@jgengine/core/input/touchScheme"`
@@ -368,3 +462,15 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 ## volumetric-clouds — raymarched cloud layer sky option
 
 - `VolumetricCloudsConfig` (interface) · `import { VolumetricCloudsConfig } from "@jgengine/core/world"`
+
+## world-environment — compose editor/preset-derived outdoor dressing — terrain, weather, water, structures — into a legacy environment feature
+
+- `environment` (function) · `import { environment } from "@jgengine/core/world"`
+
+## 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"`
+
+## world-seed — derive a deterministic generator/scatter seed from world id + save/run seed
+
+- `seedForPlace` (function) · `import { seedForPlace } from "@jgengine/core/world"`

package/skills/jgengine-world/recipes/commanding-entities.md

@@ -0,0 +1,128 @@
+# Recipe — commanding entities (select → order → tick → resolve)
+
+**What this wires:** direct command over a group of entities — pick some, issue
+intent, watch them carry it out and interact on arrival. This is a *composition*,
+not a genre. The exact same wiring is the command layer of a base-defense wave, a
+squad-tactics turn, a creature-herding puzzle, or the topdown-survival phase of a
+game that was a card game a minute ago. You swap content, camera, and
+win-condition — never this architecture.
+
+It composes four primitives across three seams. The engine never touches your
+entity store directly; you supply narrow adapters, so the same command loop runs
+over any movement/combat model.
+
+## The seams
+
+- **Pick → ids.** `createSelectionSet` is an ordered, de-duplicated set of entity
+  ids. What *fills* it is up to you — a pointer marquee, a card that names a lane,
+  an ability that grabs everything in a radius, an AI planner. Selection is just
+  ids; it does not know or care how they were chosen.
+- **Intent → per-entity queue.** Build one shared `createOrderRegistry` and give
+  each commandable entity its own `createOrderQueue`. Register verbs as *data*
+  (`defineMoveOrder`, `defineAttackMoveOrder`, `defineTargetedOrder`, or your
+  own). Every verb composes over two adapters **you** implement against your
+  entity store: `OrderMover` (`position` / `moveToward` / `halt`) and
+  `OrderTargeting` (`acquire` / `positionOf`). This adapter boundary is what makes
+  the loop genre-free.
+- **Resolve → your effect.** In `onTick`, advance each queue. Engagement verbs
+  write `{ engaging, inRange }` into `order.state`; you read that flag and resolve
+  the actual interaction your way — damage, harvest, repair, heal, dialogue —
+  through the combat seam `ctx.scene.entity.effect(...)`. Orders decide *when*;
+  the game decides *what*.
+
+## Connected wiring
+
+```ts
+import { createSelectionSet } from "@jgengine/core/scene/selection";
+import {
+  createOrderRegistry,
+  createOrderQueue,
+  defineMoveOrder,
+  defineAttackMoveOrder,
+  defineTargetedOrder,
+} from "@jgengine/core/world";
+
+// --- once, at setup -------------------------------------------------------
+
+// Adapters bind orders to YOUR entity store — the only game-specific glue.
+const mover = {
+  position: (id) => entities.get(id).pos,
+  moveToward: (id, to, dt) => stepToward(entities.get(id), to, dt), // your movement
+  halt: (id) => (entities.get(id).vel = [0, 0, 0]),
+};
+const targeting = {
+  positionOf: (id) => entities.get(id)?.pos,
+  acquire: (id) => nearestEnemyOf(id), // your target pick (kd-tree, grid, faction…)
+};
+
+const registry = createOrderRegistry();
+registry.register(defineMoveOrder({ kind: "move", mover }));
+registry.register(defineAttackMoveOrder({ kind: "attack-move", mover, targeting }));
+registry.register(defineTargetedOrder({ kind: "attack", mover, targeting }));
+
+const queues = new Map(); // entityId -> OrderQueue
+const queueOf = (id) => {
+  let q = queues.get(id);
+  if (!q) queues.set(id, (q = createOrderQueue(registry)));
+  return q;
+};
+
+const selection = createSelectionSet();
+
+// --- on a command (pointer marquee, a card play, an ability, an AI plan) --
+
+function commandSelection(kind, payload) {
+  for (const id of selection) {
+    queueOf(id).issue({ kind, payload, policy: "replace" }); // shift-queue => "append"
+  }
+}
+// e.g. commandSelection("attack-move", { point: worldHit });
+
+// --- every frame ----------------------------------------------------------
+
+function onTick(ctx, dt) {
+  for (const [id, q] of queues) {
+    q.tick(ctx, dt); // activates/advances/completes orders, drives the mover
+    const active = q.active;
+    if (active?.state?.inRange) {
+      // Engagement verb says a target is in range — resolve it the game's way.
+      ctx.scene.entity.effect({ from: id, to: active.state.target, effect: "damage" });
+    }
+  }
+}
+```
+
+That is the whole command loop. Everything genre-specific lives in the three
+functions you supplied (`stepToward`, `nearestEnemyOf`, and the `"damage"` effect)
+— never in the order/selection primitives.
+
+## Composing it into different games (and hybrids)
+
+The wiring above is fixed; four independent knobs turn it into different play:
+
+- **Who fills the selection.** Pointer marquee for an RTS; a targeting card for a
+  card-driven skirmish; an AoE ability for a spell; an AI director for autobattle.
+  Same `selection`, different caller.
+- **Which camera renders it.** `topDown`, `rts`, `shoulder`, or `first` — camera is
+  presentation and reads none of this. Swapping the rig never touches the loop.
+- **What the effect does.** `"damage"` for combat; register a `defineTargetedOrder`
+  with a `"harvest"` / `"repair"` / `"talk"` effect for non-combat command. The
+  engagement seam is generic; combat is one instance.
+- **When intent arrives.** A **mutating** game reuses one set of queues across
+  phases: the card-game phase calls `issue()` from card plays; when it turns into
+  a topdown-survival phase, the *same* queues now take `move` / `attack-move` from
+  pointer input. You changed who calls `issue()`, not the architecture.
+
+## Where to go next
+
+- Marquee/box-select and right-click-to-command come from the shell pointer seam
+  (`PlayableGame.pointer`: `select`, `selectFilter`, `orderCommand`) — that is the
+  pointer *picker* that fills `selection` and calls `commandSelection`; see
+  `jgengine-ui` for the pointer wiring.
+- Pathing for `moveToward` can use `findPath` (`@jgengine/core/nav/navGrid`) over a
+  walkable grid; the mover adapter is where it plugs in.
+- Formations, order preemption policies, save/replication of in-flight orders, and
+  the full order-kind contract are in [../reference.md](../reference.md) under
+  *Entity orders (command queue)*.
+- Damage numbers, death, and rewards are `jgengine-combat`; the effect call above
+  is the seam into it.

package/skills/jgengine-world/reference.md

@@ -2,9 +2,35 @@
 
 Reference module for the [`jgengine-world` API](SKILL.md) skill. Load this when you need the renderer-free world surface.
 
-## World features
+## World = place (the definition of a world)
 
-Descriptors from `@jgengine/core/world/features` — config data the runner/world layer interprets:
+A world is the place a game happens in — substrate + laws — declared with `world()` from
+`@jgengine/core/world/place`. It is never a coded diorama: sky look, foliage scatter, props, and
+sculpt are scene content authored in the editor (`jgengine-editor`), and the engine renders its
+default sky when the document has none.
+
+```ts
+import { world } from "@jgengine/core/world/place";
+
+export const overworld = world({
+  id: "overworld",                                      // place identity: saves, seeds, switching
+  ground: { mode: "flat", size: { x: Infinity, z: Infinity } },
+  physics: { gravity: -24 },                            // laws of THIS place
+});
+```
+
+- `ground.mode` discriminates `size`: `flat` takes `{ x, z }` (or `{ x, y, z }`; `Infinity` = unbounded axis), `round` takes `{ radius }` only, `voxel` takes the generator domain `{ x, y, z }` (axes may be `Infinity`), `board` takes `{ x, y }` in cells/layout units (2D surface you look at — grid games, solitaire, tabletop; `stage` is a `board` alias). TS rejects a `radius` on `flat` and `x`/`z` on `round`.
+- `ground.surface` is optional matter/feel law (`{ matter?, friction?, restitution?, traits? }`) systems and audio read — metal vs slime vs felt changes the feel of the *same* rule systems, never forks them. Not a theme kit.
+- `ground.generator` (procedural modes) is algorithm params only — never a seed, never a genre/franchise preset.
+- **No `seed` in a world definition, ever.** The engine derives seeds from world `id` + save/run via `seedForPlace(id, runSeed)` and injects them into generators and scatter.
+- Multiple worlds per game are first-class: one `world()` per place, each with its own ground + physics (`defineGameDefinition` resolves the active place's physics over the game default). Pure UI/rules games omit `world` entirely.
+- Thin defaults: `flat` + infinite axes + default physics for 3D, `board` for 2D, or no world at all. Never scaffold a "meadow with sky preset and seeded grass" — that is editor content.
+
+## Legacy world features
+
+Descriptors from `@jgengine/core/world/features` — legacy code-declared world shapes kept for
+existing games. Do not start new worlds here; `environment()` is now the consumption target for
+editor/preset-written scene data (`environmentContentFromDocument`), not a world definition:
 
 | Feature | Use |
 |---------|-----|
@@ -25,6 +51,11 @@ Descriptors from `@jgengine/core/world/features` — config data the runner/worl
 
 `parentSpace` positions are local to that space — convert at seams only.
 
+Display-only map consumers use the portable `MarkerView` / `MarkerSource`
+contracts in `@jgengine/core/world/markers`; the React integration and complete
+external-store walkthrough are owned by the
+[portable minimap recipe](../jgengine-ui/recipes/portable-minimap.md).
+
 ### Query primitives (renderer-free, for gameplay)
 
 Pure `@jgengine/core` functions so gameplay reads the same world the shell renders — no three.js needed:
@@ -84,7 +115,7 @@ Turn data-only placement into the build tooling of Valheim/Enshrouded/The Sims/F
 
 **Body shape: box or sphere.** `AddBodyOptions` is a discriminated union — `{ shape?: "box", halfExtents }` (box is the default, `shape` omittable) or `{ shape: "sphere", radius }` (the radius fills all three half-extent columns, so broadphase/bounds see the sphere's enclosing AABB). `world.shape[i]` (`SHAPE_BOX` / `SHAPE_SPHERE`) reports a live body's shape for a consumer walking the raw SoA arrays. Sphere-sphere and sphere-box pairs resolve with a proper radial normal (not the axis-aligned box/box path) — balls, projectile bodies, and rolling debris collide correctly against both boxes and each other.
 
-**Collision shapes are box/sphere/voxel only.** Every collider in the engine — `PhysicsWorld` bodies (box `halfExtents` or sphere `radius`), object/entity picking (`scene/objectQuery` raycasts against unit boxes), and `world/voxelField`/`world/carve` blocks — is an axis-aligned box, a sphere, or a voxel cell. Arbitrary authored level-mesh collision (a sculpted GLB as a collider) is not supported. The seams for custom collision are `movement.beforeCommit` (steer or replace the walk controller's resolved step) and object raycasts (query the scene yourself and react) — not a mesh collider.
+**Collision shapes are box/sphere/voxel — plus opt-in triangle meshes for raycasts and mesh-accurate walk obstruction.** Every collider in the engine — `PhysicsWorld` bodies (box `halfExtents` or sphere `radius`), object/entity picking (`scene/objectQuery` raycasts against unit boxes), and `world/voxelField`/`world/carve` blocks — is an axis-aligned box, a sphere, or a voxel cell. The one exception is opted-in catalog assets: an asset listed in `@jgengine/assets` `COLLISION_MESH_ASSET_IDS` ships a compact quantized triangle mesh in the generated index (`scene/collisionMesh` `CollisionMeshData`, extracted from the GLB at reindex — never from the rendered scene, so a headless host resolves the same shape) **plus a deterministic compound-box decomposition** (`voxelizeToBoxes` → `CollisionMeshData.boxes`, a voxel-rasterize + column-fill + greedy-merge of the model's solid volume). Collider auto-fit then (a) raycasts the actual triangles through a precomputed BVH — shots pass through a torus hole or an archway instead of hitting the fitted box; and (b) exposes the compound boxes on the fitted `mesh` `ColliderShape` (`ColliderShape.mesh.boxes`, scaled/translated onto the placement like the mesh). The `collideObjects` walk controller consumes these in `stepPlayerMovement` (host and client alike, so parity is automatic): it gathers obstacles from resolved blocking physical colliders via a bounded `object.inBox` broadphase (reach ≥ radius + max half-extent, so a wide wall's full span blocks, not a phantom 1 m box), carries each collider's real `halfExtents`/`offset` — or, for a mesh collider, the compound sub-boxes — yaw-rotated onto the obstacle, and slides the capsule against **each** sub-box (`resolveObstacleStep`), so a capsule walks THROUGH an archway opening and is stopped by its pillars/lintel/sill. `PhysicsWorld` and overlap tests still see the conservative fitted AABB; objects with no resolved collider keep today's default box, objects whose colliders don't block stop obstructing, and non-opted assets keep the fitted box everywhere. The seams for custom *walk* collision remain `movement.beforeCommit` and object raycasts.
 
 **Ballistic collision sweep (`physics/ballisticSweep`).** `createBallisticSweep(world, { step?, radius? })` → `BallisticSweep`, a `(origin, velocity, gravity, maxTime) => BallisticSweepHit | null` function that marches the closed-form arc (constant gravity, straight lateral) through a `PhysicsWorld` and reports the first sample inside any live body's AABB (sleeping bodies included), refined by one bisection step; `null` means the whole arc is clear. `step` (default 1/60) is the march interval in seconds, `radius` (default 0) inflates every body's AABB before the point test — pass the projectile's own radius. Wire it into `combat/projectiles` via `ProjectileSystemDeps.sweepBallistic`: when set, a ballistic shot settles at the swept impact point instead of the closed-form landing; omitted or `null` falls back to that closed-form arc.
 
@@ -160,6 +191,15 @@ runtime.step({
 // types: TriggerEvent · TriggerActionDefinition · AuthoredTrigger · TriggerHandlers · TriggerSourceKind · AuthoredTriggerRuntime
 ```
 
+**Built-in actions** — every game gets `announce` / `win` / `advance` for free, so "enter this zone → win" is authored entirely in the editor with no bespoke action code. `registerBuiltinTriggerActions()` exposes them in the inspector; `createTriggerOutcome()` returns a headless, serializable `TriggerOutcome` (`{ won, message, tone, objective, revision }`) plus the `handlers` to pass the runtime — the HUD reads it via `useSyncExternalStore`. That pair is the whole zero-code "reach the goal to win" wiring the create scaffold ships (a `goal` marker with `{ on: enter, action: win }`).
+
+```ts
+registerBuiltinTriggerActions();                 // announce/win/advance in the editor
+const outcome = createTriggerOutcome();          // { get, subscribe, handlers, reset }
+const runtime = createAuthoredTriggerRuntime({ document: editorLayers, handlers: outcome.handlers });
+// HUD: const status = useSyncExternalStore(outcome.subscribe, outcome.get, outcome.get);  // status.won / status.message
+```
+
 Multi-triggers: `meta.triggers: [{ on, action, ...params }]`. Editor inspector renders action params from the declared schema when the game has registered actions.
 
 ### Continuous area effects (source-following membership)
@@ -219,4 +259,3 @@ Path progress adapter (`nav/pathFollow`): `PathProgress` is `{ kind: "normalized
 - **Preemption policy** on each issue: `replace` (preempt active + clear pending), `append` (shift-queue), `front` (jump the queue without dropping the active order), `reject` (refuse while busy). Mark an order `uninterruptible` and a replacing order waits until it finishes; explicit `cancelActive` still forces it.
 - **Order kinds** are `OrderKind<Ctx, Payload>` with `start`/`update`/`finish`, composed over two narrow adapters — `OrderMover` (`position`/`moveToward`/`halt`) and `OrderTargeting` (`acquire`/`positionOf`). Built-ins ship as ordinary compositions with a configurable `kind` string so a game re-skins a verb ("harvest") without engine edits: `defineMoveOrder`, `defineStopOrder`, `defineHoldOrder`, `defineAttackMoveOrder`, `defineTargetedOrder`, `definePatrolOrder`. Engagement verbs write `{ engaging, inRange }` into `order.state`; the game reads it to run the actual attack/effect, keeping combat resolution game-side.
 
-

package/skills/level-design/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: level-design
+description: Design, audit, author, implement, and validate readable levels, worlds, encounters, navigation, and pacing.
+---
+
+# Level design
+
+## Ownership
+
+Own the spatial realization of game design: player metrics, topology, routes, landmarks, gates, encounter geometry, challenge sequencing, exploration, pacing, recovery, and spatial storytelling. Use `game-design` for the player promise and loops, `jgengine-editor` to author space, and `jgengine-world` to consume it.
+
+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.
+
+## Choose the mode
+
+### Greenfield
+
+Measure the real controller, camera, interaction, combat, AI, and network constraints in an authored metric gym. Produce a topology graph, critical/optional route model, beat sheet, learning sequence, encounter cards, authoring plan, and falsifiable completion scenario before art production.
+
+### Existing game
+
+Start with a spatial-truth audit. Inventory every source of coordinates and semantics; report any gameplay placement outside `editor.scene.json` as a blocking ownership defect. Reconstruct the critical path and representative optional path from scene data and live play. Measure travel, decision, encounter, retry, and recovery time. Inspect first-look orientation, reverse navigation, affordances, spawn safety, combat positions, pacing contrast, and visual hierarchy.
+
+“Improve with level design” is an authoring and implementation request. Do not stop at a map critique: select the highest-leverage route/zone/encounter slice, author the change through editor operations, connect runtime semantics, and prove it in play.
+
+For a live editor handoff, send evidence and an executable authoring contract—not an aesthetic request. Require the editor agent to inspect authority, document revision, ids, layers, assets, runtime state, and tool support before mutation; apply one coherent hypothesis through undoable operations; then return the exact revision/change log for replay and comparison. Stop when the live editor is not connected to the runtime's authoritative scene or the required operation is unsupported.
+
+## Required output contract
+
+Make every level-design pass yield:
+
+1. **Spatial truth audit:** scene counts and semantic kinds plus every code-owned coordinate table, generated placement, or duplicated position that must migrate.
+2. **Metric sheet:** measured movement, camera, interaction, weapon/AI, readability, density, performance, multiplayer, and retry constraints with units.
+3. **Topology and journey:** nodes/edges, critical and optional routes, gates, returns, landmarks, expected traversal times, and first-minute/mission/campaign beats.
+4. **Zone/encounter diagnosis:** purpose, entry knowledge/state, choices, geometry, actors, escalation, resources, exits, failure/reset, reward, and downstream change.
+5. **Bottleneck ranking:** observed symptom, player consequence, root cause, evidence, reach, confidence, effort, dependencies, and ownership.
+6. **Editor change set:** exact semantic ids/kinds and operations to add/move/remove for paths, markers, zones, spawns, objectives, checkpoints, props, and terrain—without putting coordinates in code.
+7. **Acceptance evidence:** document assertions, route/encounter tests, fresh-player play scenario, pacing/wayfinding thresholds, inspected screenshots, and before/after comparison.
+
+## Execution rules
+
+- Graph before geometry; graybox before art; gameplay and wayfinding before decoration.
+- Present decision-relevant information before commitment. Make alternate routes differ in risk, cost, verbs, information, reward, or experience.
+- Sequence teaching through cue, safe use, feedback, independent test, combination, transformation, and mastery as the audience requires.
+- Align composition, landmark, value/color, motion, audio, affordance, path shape, and optional UI guidance. No marker can repair contradictory space.
+- Design pacing across separate threat, motor, cognitive, navigation, emotional, resource, and social axes. Constant pressure or empty traversal is not pacing.
+- Make every encounter support intended verbs, counterplay, retreat, fair spawns, recovery, and bounded performance.
+- Populate only after the graybox survives play. Preserve silhouettes, safe footing, goals, threats, interactables, teams, and traversal boundaries through art passes.
+
+## Completion
+
+An audit or prettier screenshot is not completion for a build/improve request. Finish when the scene document owns spatial truth; a fresh target player can orient, choose, act, recover, and complete the scenario without coaching; the route has intentional decisions and pacing; encounter exploits and alternate states are tested; and `jgengine-verify` records document, gameplay, and inspected visual evidence.

package/skills/level-design/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Level Design"
+  short_description: "Design readable, paced, playable spaces"
+  default_prompt: "Use $level-design to observe this world live, brief and drive the editor agent through an authoritative scene change, then replay the same journey and prove the result."