@jgengine/core 0.11.0 → 0.13.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,31 @@ 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"`
+
+## building-lots — derive street-facing building lots from road frontage
+
+- `deriveBuildingLots` (function) · `import { deriveBuildingLots } from "@jgengine/core/world/buildingLots"`
+
+## 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 +150,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 +202,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 +240,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"`
@@ -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"`
@@ -325,6 +415,10 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `defineStopOrder` (function) · `import { defineStopOrder } from "@jgengine/core/world"`
 
+## street-generator — build a deterministic street/track graph (nodes, edges, streets, junctions, bridges, tunnels) from sliders
+
+- `generateStreets` (function) · `import { generateStreets } from "@jgengine/core/world/streetGenerator"`
+
 ## surface-drape — lift an XZ polyline onto sculpted terrain
 
 - `drapePolyline` (function) · `import { drapePolyline } from "@jgengine/core/world"`
@@ -357,6 +451,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 +466,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 whose colliders don't block stop obstructing, and non-opted assets keep the fitted box everywhere. Objects with no index `dims` are not stuck with the default unit box either: the shell measures what `renderObject`/dims-less models actually mount and reports it through `ctx.scene.object.reportBounds`, so a custom-rendered prop obstructs (and raycasts) as its real rendered footprint; only objects with nothing measurable keep the default box. 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/jgengine/reference-cartridge.md

@@ -1,72 +0,0 @@
-# jgengine-api — Cartridge
-
-Reference module for the [`jgengine`](./SKILL.md) skill. Load this when building a game as a **cartridge** — one declarative config instead of hand-wired loop/state/UI files. A cartridge game is ~75% smaller than the classic shape and nearly all of it is data; reach for `defineGame` + `defineSystem` ([reference-systems.md](./reference-systems.md)) when the simulation outgrows cartridge archetypes — same single authoring model, no rewrite cliff.
-
-## Why
-
-Across the classic games, 78–91% of each game's LOC was generic wiring restated per game: a run-state store with subscribe/notify, chase-and-contact enemy loops, auto-fire weapon routines, magnet pickups, draft plumbing, phase-gated HUD trees, and tests for all of it. The cartridge layer owns every one of those; the game ships only its **data** (catalogs, tuning, layout) and any genuinely bespoke rules through typed escape hatches.
-
-## Shape
-
-`game.config.ts` is the whole game — `cartridge({...})` from `@jgengine/shell/cartridge` compiles the config into a `PlayableGame` (validating it first — a bad reference throws at import with a list of problems). `loop.ts` and `world.ts` disappear; the spec carries the world feature and the loop is engine-owned. `main.tsx` is 5 lines via `mountGame` (`@/components/ui/mount`, registry). Sprites/SVG art stay in `src/game/assets.ts`; the game keeps one test file under `src/game/`.
-
-```ts
-import { cartridge, type CartridgeConfig } from "@jgengine/shell/cartridge";
-import { standardCartridgePanels } from "@/components/ui/cartridge-panels";
-
-export const config: CartridgeConfig = {
-  name, seed, panels: standardCartridgePanels, assets, entitySprites,
-  flow: { start: "gate", countdownSeconds: 3, restart: true },  // press-to-start → 3-2-1 → playing; "restart" command
-  player: { kind, health, walkSpeed },              // compiled into content + spawned per player
-  enemies: { id: { label, health, walkSpeed, xp, contact: { damage, intervalSeconds }, behavior: "chase" | "none" } },
-  combat: { contactRadius },
-  spawning: { director: SpawnDirectorConfig, placement: { kind: "ring", radius } },
-  weapons: { id: { kind: "projectile" | "orbit" | "pulse" | "custom", damage, cooldownMs, maxLevel, ... } },
-  progression: { xp: Curve, maxLevel, draft: { choices, upgrades } },
-  fields: { magnetRadius, damageMultiplier },       // named run-scalars upgrades mutate
-  xpGems: { collectRadius, pullSpeed, rarityThresholds, defaultRarity },
-  rules: { win: { kind: "survive", seconds }, lose: { kind: "playerDeath" } | { kind: "custom", check }, killLeaderboardStat },
-  world, physics, camera, worldItem, theme, hud, screens,   // screens: start/win/lose
-};
-export const game = cartridge(config);
-```
-
-The run is a phase machine every game gets for free: `start → countdown → playing → won | lost`. `flow.start: "gate"` renders `screens.start` (TitleScreen binding) until begin; `flow.countdownSeconds` renders the big-number countdown; `flow.restart: true` registers a `restart` command that resets the run in place, clears cartridge entities, and restores player stats — no hand-rolled session store, phase union, or reset function. `run.playingSeconds` is the run clock (drives the survive rule and the timer panel), so pauses and pre-game phases never skew timing.
-
-## Cartridge surface (`@jgengine/shell/cartridge/`)
-
-The survivor-shaped defaults (XP gems, contact-radius melee, orbit/pulse/projectile weapons) are a genre archetype, not a core primitive — the whole cartridge implementation lives in `@jgengine/shell` (opt-in, alongside its React binding), never in `@jgengine/core`. `core` only supplies the generic pieces it composes: `spawnDirector`, `abilityKit`, `leveling`/`progression`, `runDraft`, `autoTarget`. A puzzle or tactics game imports none of this.
-
-- `@jgengine/shell/cartridge/spec` — the `CartridgeSpec` types, `Leveled` values (`number | { base, perLevel, min?, max? } | { table }` resolved by `leveled(value, level)`), `WASD_KEYBINDS` (the default when `input` is omitted).
-- `@jgengine/shell/cartridge/runtime` — `createCartridge(spec)` → `{ content, loop, run(ctx), weaponKit(ctx), chooseUpgrade(ctx, offerId) }`. Owns the run store (outcome/kills/fields/weapon levels, subscribe/notify), spawn director advance + ring placement, chase + contact-damage enemies (terrain-grounded), the three weapon archetypes with auto-targeting, magnet xp-gem pickups feeding `leveling()`, pause-and-draft level-ups, kill → gem drop + leaderboard, and win/lose rules.
-- `@jgengine/shell/cartridge/validate` — `validateCartridge(spec)` → problem list: spawn waves must reference declared enemies, upgrades must reference declared weapons/fields, stacks can't exceed weapon `maxLevel`, tuning must be positive, rarity thresholds descending. The game's test asserts it returns `[]`.
-
-Weapon archetypes: `projectile` (auto-target nearest in `range`, travel-time bolt fx), `orbit` (leveled blade count/radius sweeping `hitRadius`), `pulse` (radial AoE with linear falloff and an expanding-ring fx). Upgrade effects: `weaponLevel` (+1 level per stack), `statBonus` (+max and +current on pick), `fieldAdd` / `fieldMultiply` (recomputed from stacks). Weapon damage is multiplied by the `damageMultiplier` field when declared.
-
-## Presentation (shell + registry)
-
-`hud.panels` is a schema — items `vital | xp | timer | score | abilityBar | component`, anchored via the movable HUD layout; `screens.win/lose` render the results/death screens; the upgrade-draft modal appears whenever a draft is pending. The shell renders the frame and injects concrete components through the `panels` seam — `standardCartridgePanels` (registry `cartridge-panels`) binds the jgengine UI kit; swap any binding for a custom component without touching the engine. Weapon fx render engine-side from the run store's bolt/pulse feeds (`fxColor`/`fxEmissive` per weapon). `theme` is the `--jg-*` CSS var block — hand-pick it or derive from a few seed colors with `deriveJgTheme` (registry `jg-theme`).
-
-## Escape hatches — bespoke logic without leaving the cartridge
-
-- `weapons.<id> = { kind: "custom", fire(ctx, run, args) }` — cooldown/level/damage handled for you; the fire shape is yours.
-- `spawning.placement = { kind: "custom", position(ctx, run) }`.
-- `rules.win = { kind: "custom", check(ctx, run) }`.
-- `progression.draft.upgrades[].effect = { kind: "custom", apply(ctx, run, stacks) }`.
-- `systems: [(ctx, run, dt) => ...]` — extra per-tick simulation after the built-ins, only while playing.
-- `hud` items `{ kind: "component", Component }` — arbitrary React panels alongside the schema ones.
-
-A game that is *mostly* bespoke simulation (custom physics, session machines) should keep `defineGame` and write its systems — the cartridge is for games whose shape the archetypes already cover.
-
-## Testing
-
-Cartridge behaviors are engine-tested once (`packages/shell/src/cartridge/runtime.test.ts`); the game test is one call plus any game-specific assertions:
-
-```ts
-import { bootCartridge, cartridgeSmokeTest, tickCartridge } from "@jgengine/shell/cartridge/testkit";
-cartridgeSmokeTest(config);   // validate + world summary + headless run/spawn/kill/gem smoke
-```
-
-`bootCartridge`/`tickCartridge` build a headless `GameContext` and drive the loop (auto-choosing drafts) for custom assertions — see `@jgengine/shell/cartridge/testkit`. The testkit imports `bun:test`; import it from test files only.
-
-Barrel surface tokens: createKeyValueStore createUnlocks durabilityFraction isComplete isOverdrawn memorySaveBackend partInSlot pruneToasts policyProjectsViewers projectByVisibleIds projectEntitiesForViewer projectPerUserForViewer visibleEntityIds applyDeltaToSnapshot applySurfaceDeltaToSnapshot boundaryNeighbors catenaryCurve distanceToPolygonEdge footprintObstacles hasValidAdjacency pointInPolygon polygonArea polygonBounds populateNavGridFromEnvironment readScatterPalette readScatterRules revertDeltaFromSnapshot revertSurfaceDeltaFromSnapshot slopeStepCost solveLock solveLockPath