@jgengine/core 0.13.0 → 0.15.0-next.0

package/dist/runtime/runtimeSave.d.ts

@@ -12,7 +12,7 @@ export interface RuntimeSaveTarget {
     hydrate(snapshot: WorldSnapshot): void;
     subscribe(listener: () => void): () => void;
 }
-/** `"autosave"` writes a fresh capture on a debounce after any world change; `"manual"` writes only on an explicit `save()`/`checkpoint()` — the save-point / quest-trigger model. */
+/** `"autosave"` writes a fresh capture on a trailing timer while the world changes (at most once per `autosaveMs`, so a never-idle world still persists); `"manual"` writes only on an explicit `save()`/`checkpoint()` — the save-point / quest-trigger model. */
 export type RuntimeSaveMode = "autosave" | "manual";
 /** How {@link createRuntimeSave} is wired — the live world `target`, the `backend` it persists through, and optional mode/slot/versioning/cadence knobs. */
 export interface RuntimeSaveConfig {
@@ -29,7 +29,7 @@ export interface RuntimeSaveConfig {
     /** Save-format version; bump + pass {@link migrate} on a breaking world-shape change. */
     version?: number;
     migrate?: (data: unknown, fromVersion: number) => WorldSnapshot;
-    /** Debounce for `autosave` mode. Default `3000`. */
+    /** Trailing autosave interval (ms) for `autosave` mode — the world persists at most once per interval and always within one interval of its first unsaved change. Default `3000`. */
     autosaveMs?: number;
     now?: () => number;
     timers?: SaveTimers;
@@ -41,7 +41,7 @@ export type RuntimeSaveOptions = Omit<RuntimeSaveConfig, "target">;
  * Whole-world save/load bound to a live world and a pluggable backend. `save()`
  * captures `target.snapshot()` and writes it; `load()` reads it back and
  * `target.hydrate()`s the whole world. In `autosave` mode it also writes on a
- * debounce after any change. Named slots, versioned migration, and offline↔cloud
+ * trailing timer while the world keeps changing. Named slots, versioned migration, and offline↔cloud
  * (backend swap) all come for free from the underlying save store.
  */
 export interface RuntimeSave {

package/dist/runtime/runtimeSave.js

@@ -51,10 +51,19 @@ export function createRuntimeSave(config) {
         store.set(config.target.snapshot());
         return store.save();
     }
+    /**
+     * Arm a trailing autosave. A living world (AI, physics, the day/night clock)
+     * changes every frame, so a debounce that *reset* its timer on every change
+     * would never elapse and the game would never persist — the timer would be
+     * pushed forward faster than it could fire. Instead the first change since the
+     * last write arms a single timer and later changes ride that same timer; when
+     * it fires it captures the latest snapshot. The result is at most one write per
+     * `autosaveMs`, and always within `autosaveMs` of the first unsaved change,
+     * even while the world never stops moving.
+     */
     function scheduleAutosave() {
-        if (disposed || restoring)
+        if (disposed || restoring || pendingTimer !== null)
             return;
-        clearTimer();
         pendingTimer = timers.set(() => {
             pendingTimer = null;
             void persist();

package/dist/scene/assetDiagnostics.js

@@ -92,11 +92,11 @@ export function classifyAssetResponse(probe) {
     });
     if (status !== undefined && (status === 0 || status >= 400)) {
         const suffix = statusText === undefined || statusText.length === 0 ? "" : ` ${statusText}`;
-        return finish("missing", `Asset ${who} did not load: HTTP ${status}${suffix}. The file is not being served — provision the pack (e.g. \`assets pull <source>\`) or check the model path.`);
+        return finish("missing", `Asset ${who} did not load: HTTP ${status}${suffix}. The bytes are not being served at that path — run \`assets pull <source>\`, which provisions the pack into the dev server's served models dir (\`apps/dev/public/models\` in the jgengine monorepo) so no manual copy is needed; or check the model path.`);
     }
     const htmlContentType = contentType !== undefined && contentType.toLowerCase().includes("text/html");
     if (signature === "html" || (htmlContentType && signature !== "glb" && signature !== "gltf-json")) {
-        return finish("html", `Asset ${who} resolved to an HTML page, not a model — the dev server returned its fallback document because the file is missing. Provision the pack (\`assets pull <source>\`) so the bytes exist under the served path.`);
+        return finish("html", `Asset ${who} resolved to an HTML page, not a model — the dev server returned its fallback document because the file is missing. Run \`assets pull <source>\` to provision the pack into the served models dir (\`apps/dev/public/models\` in the jgengine monorepo); the bytes must exist there, no manual copy needed.`);
     }
     if (signature === "glb" || signature === "gltf-json")
         return finish("ok", `Asset ${who} loaded (${signature}).`);

package/dist/scene/autoTarget.js

@@ -1,3 +1,4 @@
+import { resolveRng } from "../random/resolveRng.js";
 function metric(policy, fromId, toId, deps) {
     switch (policy) {
         case "nearest":
@@ -21,7 +22,7 @@ export function selectAutoTarget(policy, fromId, deps) {
     if (candidates.length === 0)
         return null;
     if (policy === "random") {
-        const rng = deps.rng ?? Math.random;
+        const rng = resolveRng(deps.rng, "autoTarget");
         return candidates[Math.min(candidates.length - 1, Math.floor(rng() * candidates.length))];
     }
     const higher = prefersHigher(policy);

package/dist/scene/builtinSceneKinds.d.ts

@@ -1,5 +1,10 @@
 import { type ParamSchema } from "./sceneKinds.js";
-/** The scatter/foliage region schema — the fields the inspector exposed as hand-written `ScatterFields`. */
+/**
+ * The scatter/foliage region schema. `palette` (what fills the area) leads the schema body and
+ * `density` is the single coverage slider hoisted into the shared `CoverageSection` (see the kind's
+ * `coverage` descriptor), so a scatter region reads as Area → Assets → Density like every other
+ * scatterable kind; the rest is kind-specific tuning.
+ */
 export declare const SCATTER_SCHEMA: ParamSchema;
 /** Idempotently registers the engine's built-in environment scene kinds + generators. @internal */
 export declare function registerBuiltinSceneKinds(): void;

package/dist/scene/builtinSceneKinds.js

@@ -15,10 +15,17 @@ import { registerSoilKind } from "../world/soilKind.js";
 import { registerPoleLineKind } from "../world/poleLineKind.js";
 import { registerBuildingGenerator } from "../world/buildingGenerator.js";
 import { registerCityKind } from "../world/cityKind.js";
+import { describeScatterCoverage, densityCoverage } from "../world/scatterCoverage.js";
 import { registerSceneKind } from "./sceneKinds.js";
-/** The scatter/foliage region schema — the fields the inspector exposed as hand-written `ScatterFields`. */
+/**
+ * The scatter/foliage region schema. `palette` (what fills the area) leads the schema body and
+ * `density` is the single coverage slider hoisted into the shared `CoverageSection` (see the kind's
+ * `coverage` descriptor), so a scatter region reads as Area → Assets → Density like every other
+ * scatterable kind; the rest is kind-specific tuning.
+ */
 export const SCATTER_SCHEMA = {
     fields: [
+        { type: "weightedList", key: "palette", label: "species (weighted)", itemLabel: "grass / tree id", default: [{ item: "grass", weight: 1 }] },
         { type: "range", key: "density", label: "density", min: 0, max: 2, step: 0.01, default: 0.15, unit: "/m²" },
         { type: "number", key: "minSpacing", label: "spacing", step: 0.25, default: 1.5, min: 0 },
         { type: "number", key: "minScale", label: "min scale", step: 0.05, default: 0.8, min: 0 },
@@ -27,7 +34,6 @@ export const SCATTER_SCHEMA = {
         { type: "number", key: "edgeFalloff", label: "edge fade", step: 0.5, default: 0, min: 0 },
         { type: "bool", key: "alignToNormal", label: "align to slope", default: false },
         { type: "bool", key: "autoAvoid", label: "auto-avoid gameplay spots", default: true },
-        { type: "weightedList", key: "palette", label: "species (weighted)", itemLabel: "grass / tree id", default: [{ item: "grass", weight: 1 }] },
         { type: "seed", key: "seed", label: "seed", default: "" },
     ],
 };
@@ -45,6 +51,7 @@ export function registerBuiltinSceneKinds() {
         addCategory: "Studios",
         accent: "#34d399",
         schema: SCATTER_SCHEMA,
+        coverage: { spec: "scatter", densityKey: "density", assetsKey: "palette" },
         note: (object, params) => {
             const points = object.points ?? [];
             if (points.length < 3)
@@ -55,7 +62,7 @@ export function registerBuiltinSceneKinds() {
             }
             area = Math.abs(area) / 2;
             const density = typeof params["density"] === "number" ? params["density"] : 0;
-            return `≈ ${Math.floor(area * density).toLocaleString()} placements over ${Math.round(area).toLocaleString()} m²`;
+            return describeScatterCoverage(densityCoverage("scatter", area, density));
         },
     });
     registerWaterKind();

package/dist/scene/captureCheck.js

@@ -1,3 +1,4 @@
+import { resolveRng } from "../random/resolveRng.js";
 function clamp01(value) {
     return Math.min(1, Math.max(0, value));
 }
@@ -6,6 +7,6 @@ export function captureChance(input) {
     const hpFactor = 1 - clamp01(input.hpFraction) * 0.6;
     return clamp01((input.catchPower * hpFactor) / Math.max(difficulty, 0.0001));
 }
-export function rollCapture(input, rng = Math.random) {
-    return rng() < captureChance(input);
+export function rollCapture(input, rng) {
+    return resolveRng(rng, "rollCapture")() < captureChance(input);
 }

package/dist/scene/colliders.d.ts

@@ -128,6 +128,26 @@ export declare function measuredEntityColliders(bounds: MeasuredBounds): EntityC
  * @internal
  */
 export declare function measuredObjectColliders(bounds: MeasuredBounds): EntityColliderSet | null;
+/** Damage hitbox raycasting the actual triangles the renderer mounted for an entity kind — what
+ * `reportCollisionMesh` stores. Triangles are entity-local (scale/placement already applied), so the
+ * shape composes with identity `meshScale`/`meshTranslate`; bounds/broadphase read the clamped AABB.
+ * `null` when the mesh is degenerate, keeping the caller's existing fallback.
+ * @capability conforming-hitboxes shots aimed between a character's feet or past its shoulder MISS — the damage hitbox is the rendered model's own triangles, not a bounding box.
+ * @internal
+ */
+export declare function meshEntityColliders(mesh: PreparedCollisionMesh): EntityColliderSet | null;
+/** Blocking physical body raycasting the actual triangles the renderer mounted for an object catalog
+ * id — the mesh-accurate counterpart to `measuredObjectColliders`. Movement obstruction stays on the
+ * conservative AABB (no `boxes` decomposition at runtime); rays hit the real surface. `null` when
+ * degenerate.
+ * @internal
+ */
+export declare function meshObjectColliders(mesh: PreparedCollisionMesh): EntityColliderSet | null;
+/** True when any collider in the set already raycasts real triangles (index-derived mesh shapes win
+ * over runtime-measured ones — they are identical on a headless host).
+ * @internal
+ */
+export declare function hasMeshColliderShape(set: EntityColliderSet | null | undefined): boolean;
 /** @internal */
 export declare function resolveColliders(set: EntityColliderSet | null | undefined): ResolvedCollider[];
 /** @internal */

package/dist/scene/colliders.js

@@ -250,6 +250,84 @@ export function measuredObjectColliders(bounds) {
         },
     };
 }
+/** Root-node AABB of a prepared mesh (the BVH root bounds the whole soup) as a clamped
+ * entity-local box — `null` when degenerate. */
+function preparedMeshShape(mesh) {
+    const bounds = mesh.nodeBounds;
+    if (bounds.length < 6)
+        return null;
+    const min = [bounds[0], bounds[1], bounds[2]];
+    const max = [bounds[3], bounds[4], bounds[5]];
+    const box = measuredBox({ min, max });
+    if (box === null)
+        return null;
+    return {
+        kind: "mesh",
+        mesh,
+        meshScale: 1,
+        meshTranslate: [0, 0, 0],
+        halfExtents: box.halfExtents,
+        offset: box.offset,
+    };
+}
+/** Damage hitbox raycasting the actual triangles the renderer mounted for an entity kind — what
+ * `reportCollisionMesh` stores. Triangles are entity-local (scale/placement already applied), so the
+ * shape composes with identity `meshScale`/`meshTranslate`; bounds/broadphase read the clamped AABB.
+ * `null` when the mesh is degenerate, keeping the caller's existing fallback.
+ * @capability conforming-hitboxes shots aimed between a character's feet or past its shoulder MISS — the damage hitbox is the rendered model's own triangles, not a bounding box.
+ * @internal
+ */
+export function meshEntityColliders(mesh) {
+    const shape = preparedMeshShape(mesh);
+    if (shape === null)
+        return null;
+    return {
+        hitboxes: [
+            {
+                name: "body",
+                purpose: "damage",
+                shape,
+                damageEligible: true,
+                blocks: false,
+            },
+        ],
+    };
+}
+/** Blocking physical body raycasting the actual triangles the renderer mounted for an object catalog
+ * id — the mesh-accurate counterpart to `measuredObjectColliders`. Movement obstruction stays on the
+ * conservative AABB (no `boxes` decomposition at runtime); rays hit the real surface. `null` when
+ * degenerate.
+ * @internal
+ */
+export function meshObjectColliders(mesh) {
+    const shape = preparedMeshShape(mesh);
+    if (shape === null)
+        return null;
+    return {
+        body: {
+            name: "body",
+            purpose: "physical",
+            shape,
+            damageEligible: false,
+            blocks: true,
+        },
+    };
+}
+/** True when any collider in the set already raycasts real triangles (index-derived mesh shapes win
+ * over runtime-measured ones — they are identical on a headless host).
+ * @internal
+ */
+export function hasMeshColliderShape(set) {
+    if (set === null || set === undefined)
+        return false;
+    if (set.body?.shape.kind === "mesh")
+        return true;
+    for (const hitbox of set.hitboxes ?? []) {
+        if (hitbox.shape.kind === "mesh")
+            return true;
+    }
+    return false;
+}
 /** @internal */
 export function resolveColliders(set) {
     if (set === null || set === undefined)

package/dist/scene/collisionMesh.d.ts

@@ -77,6 +77,14 @@ export declare function voxelizeToBoxes(source: CollisionMeshSource, cellSize?:
     min: [number, number, number];
     max: [number, number, number];
 }[];
+/**
+ * Build a prepared BVH mesh straight from a runtime triangle soup (float positions + indices) —
+ * the renderer-fed counterpart to {@link prepareCollisionMesh}, feeding
+ * `ctx.scene.entity.reportCollisionMesh` / `ctx.scene.object.reportCollisionMesh` without a
+ * quantize/encode round-trip. Copies and sanitizes the input: triangles referencing out-of-range,
+ * non-finite, or repeated vertices are dropped. Returns `null` when no triangle survives.
+ */
+export declare function prepareCollisionMeshSource(source: CollisionMeshSource): PreparedCollisionMesh | null;
 /**
  * Decode a stored collision mesh and index it with a BVH. Memoized per data object, so the shell and
  * a headless host preparing the same catalog entry share one build. Returns `null` (also memoized)

package/dist/scene/collisionMesh.js

@@ -500,6 +500,54 @@ function buildBvh(positions, indices) {
         triOrder,
     };
 }
+/**
+ * Build a prepared BVH mesh straight from a runtime triangle soup (float positions + indices) —
+ * the renderer-fed counterpart to {@link prepareCollisionMesh}, feeding
+ * `ctx.scene.entity.reportCollisionMesh` / `ctx.scene.object.reportCollisionMesh` without a
+ * quantize/encode round-trip. Copies and sanitizes the input: triangles referencing out-of-range,
+ * non-finite, or repeated vertices are dropped. Returns `null` when no triangle survives.
+ */
+export function prepareCollisionMeshSource(source) {
+    const raw = source.positions;
+    const rawIndices = source.indices;
+    if (raw.length < 9 || raw.length % 3 !== 0)
+        return null;
+    if (rawIndices.length < 3 || rawIndices.length % 3 !== 0)
+        return null;
+    const vertexCount = raw.length / 3;
+    const positions = new Float32Array(raw.length);
+    const finite = new Uint8Array(vertexCount);
+    for (let v = 0; v < vertexCount; v += 1) {
+        const x = raw[v * 3];
+        const y = raw[v * 3 + 1];
+        const z = raw[v * 3 + 2];
+        if (!Number.isFinite(x) || !Number.isFinite(y) || !Number.isFinite(z))
+            continue;
+        positions[v * 3] = x;
+        positions[v * 3 + 1] = y;
+        positions[v * 3 + 2] = z;
+        finite[v] = 1;
+    }
+    const triangles = [];
+    for (let t = 0; t + 2 < rawIndices.length; t += 3) {
+        const a = rawIndices[t];
+        const b = rawIndices[t + 1];
+        const c = rawIndices[t + 2];
+        if (!Number.isInteger(a) || a < 0 || a >= vertexCount || finite[a] === 0)
+            continue;
+        if (!Number.isInteger(b) || b < 0 || b >= vertexCount || finite[b] === 0)
+            continue;
+        if (!Number.isInteger(c) || c < 0 || c >= vertexCount || finite[c] === 0)
+            continue;
+        if (a === b || b === c || a === c)
+            continue;
+        triangles.push(a, b, c);
+    }
+    if (triangles.length === 0)
+        return null;
+    const indices = new Uint32Array(triangles);
+    return { positions, indices, ...buildBvh(positions, indices) };
+}
 const preparedCache = new WeakMap();
 /**
  * Decode a stored collision mesh and index it with a BVH. Memoized per data object, so the shell and

package/dist/scene/entityStore.d.ts

@@ -22,6 +22,8 @@ export interface SceneEntity<TMeta = unknown> {
     role: EntityRole;
     movement: EntityMovement;
     behaviors: readonly BehaviorDescriptor[];
+    /** Render-only visibility: `true` skips the entity's visual entirely (seated vehicle riders, cutscene actors, stealth cloaks) while the entity keeps simulating — position, stats, AI targeting, and queries are untouched. Absent/`false` renders normally. */
+    hidden?: boolean;
     /** Game-defined per-instance data set at `spawn`/`update` and carried to `renderEntity`/queries — narrow with {@link entityMetaOf} (or a type guard) on read (#286.1); never encode state in the id/name string. */
     meta: TMeta;
 }
@@ -44,6 +46,7 @@ export interface SpawnOptions<TMeta = unknown> {
     role?: EntityRole;
     movement?: EntityMovement;
     behaviors?: readonly BehaviorDescriptor[];
+    hidden?: boolean;
     meta?: TMeta;
     /** When `id` is already spawned: `"throw"` (default), `"replace"` (fresh spawn over it — remount-safe world setup, #284.10), or `"keep"` (leave it untouched and return the id). */
     onExisting?: "throw" | "replace" | "keep";
@@ -68,7 +71,7 @@ export interface PoseConstraintFrame {
 }
 /** Return a replacement position to constrain the step, or nothing to accept it. */
 export type PoseConstraint = (frame: PoseConstraintFrame) => readonly [number, number, number] | undefined | void;
-export type EntityUpdatePatch<TMeta = unknown> = Partial<Pick<SceneEntity<TMeta>, "name" | "rotationY" | "rotationX" | "rotationZ" | "role" | "movement" | "behaviors" | "meta">> & {
+export type EntityUpdatePatch<TMeta = unknown> = Partial<Pick<SceneEntity<TMeta>, "name" | "rotationY" | "rotationX" | "rotationZ" | "role" | "movement" | "behaviors" | "hidden" | "meta">> & {
     /** Accepts the same friendly shapes as `spawn`/`setPose` (#286.13). Raw patch semantics — velocity is not derived; use `setPose` with `dt` for that. */
     position?: SpawnPositionInput;
 };

package/dist/scene/entityStore.js

@@ -91,6 +91,7 @@ export function createEntityStore() {
                 role: options.role ?? "prop",
                 movement: options.movement ?? {},
                 behaviors: options.behaviors ?? [],
+                ...(options.hidden === undefined ? {} : { hidden: options.hidden }),
                 meta: options.meta,
             });
             spawnPoses.set(id, { position, rotationY });
@@ -124,6 +125,8 @@ export function createEntityStore() {
                 current.movement = patch.movement;
             if (patch.behaviors !== undefined)
                 current.behaviors = patch.behaviors;
+            if (patch.hidden !== undefined)
+                current.hidden = patch.hidden;
             if (patch.meta !== undefined)
                 current.meta = patch.meta;
             store.set(id, current);

package/dist/scene/objectStore.d.ts

@@ -1,3 +1,4 @@
+import type { ModelAnimationConfig } from "../game/playableGame.js";
 import type { EntityPosition } from "./entityStore.js";
 export interface ObjectVisual {
     scale?: number | readonly [number, number, number];
@@ -11,12 +12,21 @@ export interface SceneObject {
     rotationY: number;
     parentSpace?: string;
     visual?: ObjectVisual;
+    /**
+     * Per-placement rig animation override applied on top of catalog resolution — the same shape as
+     * `ModelConfig.animation` (role→clip states, `"auto"`/`"none"`, speeds, fade, one-shot bindings).
+     * Authored in the editor as `marker.meta.animation` (#1274) and threaded here by
+     * `resolveAuthoredObjects` → `placeAuthoredObjects`; `undefined` keeps the catalog-resolved default.
+     */
+    animation?: ModelAnimationConfig | "auto" | "none";
 }
 export interface PlaceOptions {
     instanceId?: string;
     parentSpace?: string;
     rotation?: number;
     visual?: ObjectVisual;
+    /** Per-placement rig animation override stored on the placed {@link SceneObject}; same shape as `ModelConfig.animation`. Omit to keep the catalog-resolved default. */
+    animation?: ModelAnimationConfig | "auto" | "none";
     /** When `instanceId` is already placed: `"throw"` (default), `"replace"` (fresh placement over it — remount-safe world setup, #284.10), or `"keep"` (leave it untouched and return the id). */
     onExisting?: "throw" | "replace" | "keep";
 }

package/dist/scene/objectStore.js

@@ -1,5 +1,12 @@
 import { createObservableKeyedStore } from "../store/observableKeyedStore.js";
 const CELL_SIZE = 1;
+/**
+ * When an `inBox` query spans more than this many 1 m cells, walk the object list instead of the
+ * cell grid. Tall/wide colliders (city buildings) can inflate movement broadphase to hundreds of
+ * metres on each axis — at 1 m cells that is O(10⁶) empty `Map.get`s per frame and freezes `pose`.
+ * Linear scan over a few hundred objects is cheaper the moment the cell volume exceeds the scene.
+ */
+const IN_BOX_CELL_VOLUME_LIMIT = 4096;
 function cellIndexOf(value) {
     return Math.floor(value / CELL_SIZE);
 }
@@ -9,6 +16,10 @@ function cellKey(cx, cy, cz) {
 function cellKeyOf(position) {
     return cellKey(cellIndexOf(position[0]), cellIndexOf(position[1]), cellIndexOf(position[2]));
 }
+function objectInAabb(object, min, max) {
+    const [x, y, z] = object.position;
+    return x >= min[0] && x <= max[0] && y >= min[1] && y <= max[1] && z >= min[2] && z <= max[2];
+}
 export function createObjectStore() {
     const store = createObservableKeyedStore();
     const cellIndex = new Map();
@@ -60,6 +71,7 @@ export function createObjectStore() {
                 rotationY: options.rotation ?? 0,
                 ...(options.parentSpace !== undefined ? { parentSpace: options.parentSpace } : {}),
                 ...(options.visual !== undefined ? { visual: options.visual } : {}),
+                ...(options.animation !== undefined ? { animation: options.animation } : {}),
             });
             indexAdd(instanceId, position);
             return instanceId;
@@ -99,6 +111,7 @@ export function createObjectStore() {
                 position: current.position,
                 rotationY: current.rotationY,
                 ...(current.parentSpace !== undefined ? { parentSpace: current.parentSpace } : {}),
+                ...(current.animation !== undefined ? { animation: current.animation } : {}),
                 ...(visual !== undefined ? { visual } : {}),
             });
             return true;
@@ -145,13 +158,27 @@ export function createObjectStore() {
             return results;
         },
         inBox(min, max) {
-            const hits = [];
             const minCx = cellIndexOf(min[0]);
             const maxCx = cellIndexOf(max[0]);
             const minCy = cellIndexOf(min[1]);
             const maxCy = cellIndexOf(max[1]);
             const minCz = cellIndexOf(min[2]);
             const maxCz = cellIndexOf(max[2]);
+            const cellsX = Math.max(0, maxCx - minCx + 1);
+            const cellsY = Math.max(0, maxCy - minCy + 1);
+            const cellsZ = Math.max(0, maxCz - minCz + 1);
+            const cellVolume = cellsX * cellsY * cellsZ;
+            // Huge queries (city-scale movement broadphase inflated by tall building colliders): scanning
+            // every empty 1 m cell is far more expensive than testing the few hundred placed objects.
+            if (cellVolume > IN_BOX_CELL_VOLUME_LIMIT) {
+                const hits = [];
+                for (const object of store.arraySnapshot()) {
+                    if (objectInAabb(object, min, max))
+                        hits.push(object);
+                }
+                return hits;
+            }
+            const hits = [];
             for (let cx = minCx; cx <= maxCx; cx += 1) {
                 for (let cy = minCy; cy <= maxCy; cy += 1) {
                     for (let cz = minCz; cz <= maxCz; cz += 1) {
@@ -162,12 +189,8 @@ export function createObjectStore() {
                             const object = store.get(instanceId);
                             if (object === undefined)
                                 continue;
-                            const [x, y, z] = object.position;
-                            if (x >= min[0] && x <= max[0] &&
-                                y >= min[1] && y <= max[1] &&
-                                z >= min[2] && z <= max[2]) {
+                            if (objectInAabb(object, min, max))
                                 hits.push(object);
-                            }
                         }
                     }
                 }

package/dist/scene/sceneKinds.d.ts

@@ -145,6 +145,19 @@ export interface ParamSchema {
 export declare function findSchemaPreset(schema: ParamSchema, id: string): ParamPreset | undefined;
 /** Parsed params after `parseParams`: every schema field present with a validated, defaulted value. */
 export type ParsedParams = Record<string, number | boolean | string | WeightedParamEntry[]>;
+/**
+ * Marks a kind as *scatterable* — it fills an authored area with instances at one density under a
+ * bounded budget — so the editor renders the shared `CoverageSection` (Area → Assets → Density slider
+ * + budget note) that gives grass/scatter/city one authoring gesture. `spec` selects the unit + budget
+ * from `@jgengine/core/world/scatterCoverage`; `densityKey` is the single density slider hoisted into
+ * the coverage header (and hidden from the schema body below); `assetsKey` is the optional weighted
+ * "what fills it" palette summarized in the header.
+ */
+export interface SceneKindCoverage {
+    spec: import("../world/scatterCoverage.js").ScatterCoverageKind;
+    densityKey: string;
+    assetsKey?: string;
+}
 /**
  * Parse a raw `meta` bag against a schema into typed params — every field present, invalid/missing
  * values replaced by the field default, numbers clamped to their range. The single parser every
@@ -201,6 +214,12 @@ export interface SceneKindDefinition<TResolved = unknown> {
     resolve?: (object: SceneKindObject, params: ParsedParams, context: SceneKindResolveContext) => TResolved;
     /** Optional one-line readout under the inspector fields (estimate, dimensions) — owned by the studio. */
     note?: (object: SceneKindObject, params: ParsedParams) => string;
+    /**
+     * Optional scatterable-coverage descriptor. When set, the editor leads this kind's inspector with
+     * the shared Area / Assets / Density `CoverageSection` and surfaces the budget clamp-and-warn note,
+     * giving every scatterable kind (grass/scatter/city) one authoring pattern.
+     */
+    coverage?: SceneKindCoverage;
 }
 /** The raw document object a resolver receives — shape shared by markers, volumes, and paths. */
 export interface SceneKindObject {
@@ -246,6 +265,24 @@ export interface SceneKindResolveContext {
  * inspector, `+ Add` menu, and `AuthoredScene` renderer lookup all read this registry.
  */
 export declare function registerSceneKind<TResolved>(definition: SceneKindDefinition<TResolved>): void;
+/**
+ * Declare a game's own **click-to-place** marker kind in one call — the light path for logical
+ * markers a game reads off the document by `kind` (a stash, checkpoint, spawn point, bounty…), with
+ * none of a full studio's schema/resolver boilerplate. Registering it makes the kind a click-to-place
+ * tool in the editor's `+ Add` menu (grouped under `category`) and gives its markers an inspector for
+ * any `fields` you pass. Call at module load from a module the editor loads (a game's `editorLayers`
+ * import graph). Rendering is unaffected — the game still reads `kind` off `editorLayers.markers`.
+ */
+export declare function definePlaceableMarkerKind(options: {
+    kind: string;
+    label: string;
+    /** `+ Add` menu section header this kind groups under. Defaults to `"Custom"`. */
+    category?: string;
+    /** Accent hex for the menu entry + inspector header. */
+    accent?: string;
+    /** Optional inspector fields written into each marker's `meta` (e.g. a payout value). */
+    fields?: readonly ParamField[];
+}): string;
 /** The registered definition for a kind, or undefined if the kind is a plain (non-studio) kind. @internal */
 export declare function getSceneKind(kind: string): SceneKindDefinition | undefined;
 /** True when a kind has a registered studio definition (schema/inspector/renderer). @internal */

package/dist/scene/sceneKinds.js

@@ -198,6 +198,25 @@ const registry = new Map();
 export function registerSceneKind(definition) {
     registry.set(definition.kind, definition);
 }
+/**
+ * Declare a game's own **click-to-place** marker kind in one call — the light path for logical
+ * markers a game reads off the document by `kind` (a stash, checkpoint, spawn point, bounty…), with
+ * none of a full studio's schema/resolver boilerplate. Registering it makes the kind a click-to-place
+ * tool in the editor's `+ Add` menu (grouped under `category`) and gives its markers an inspector for
+ * any `fields` you pass. Call at module load from a module the editor loads (a game's `editorLayers`
+ * import graph). Rendering is unaffected — the game still reads `kind` off `editorLayers.markers`.
+ */
+export function definePlaceableMarkerKind(options) {
+    registerSceneKind({
+        kind: options.kind,
+        target: "marker",
+        label: options.label,
+        addCategory: options.category ?? "Custom",
+        ...(options.accent === undefined ? {} : { accent: options.accent }),
+        schema: { fields: options.fields ?? [] },
+    });
+    return options.kind;
+}
 /** The registered definition for a kind, or undefined if the kind is a plain (non-studio) kind. @internal */
 export function getSceneKind(kind) {
     return registry.get(kind);