@jgengine/core 0.12.0 → 0.14.0

package/dist/runtime/context/scene.js

@@ -2,7 +2,8 @@ import { createBodyBind } from "../../scene/bodyBind.js";
 import { createEntityStatsApi, seedStatValues, } from "../../scene/entityStats.js";
 import { createEntityStore, } from "../../scene/entityStore.js";
 import { createForms } from "../../scene/form.js";
-import { fittedEntityColliders, fittedObjectColliders, scaledEntityColliders, scaledObjectColliders, } from "../../scene/colliders.js";
+import { fittedEntityColliders, fittedObjectColliders, hasMeshColliderShape, measuredEntityColliders, measuredObjectColliders, meshEntityColliders, meshObjectColliders, scaledEntityColliders, scaledObjectColliders, } from "../../scene/colliders.js";
+import { prepareCollisionMeshSource } from "../../scene/collisionMesh.js";
 import { raycastObjects, raycastObjectsAll } from "../../scene/objectQuery.js";
 import { createObjectStore, objectVisualScale } from "../../scene/objectStore.js";
 import { createPaintLayer } from "../../scene/paintLayer.js";
@@ -82,6 +83,68 @@ export function createSceneSubsystem(d) {
         fittedObjectByCatalogId.set(catalogId, fitted);
         return fitted;
     }
+    const measuredEntityByKind = new Map();
+    const measuredObjectByCatalogId = new Map();
+    function reportEntityBounds(kind, bounds) {
+        if (bounds === null) {
+            const existed = measuredEntityByKind.delete(kind);
+            if (existed)
+                signalNotify();
+            return existed;
+        }
+        const measured = measuredEntityColliders(bounds);
+        if (measured === null)
+            return false;
+        measuredEntityByKind.set(kind, measured);
+        signalNotify();
+        return true;
+    }
+    const meshEntityByKind = new Map();
+    const meshObjectByCatalogId = new Map();
+    function reportEntityCollisionMesh(kind, mesh) {
+        if (mesh === null) {
+            const existed = meshEntityByKind.delete(kind);
+            if (existed)
+                signalNotify();
+            return existed;
+        }
+        const prepared = prepareCollisionMeshSource(mesh);
+        const set = prepared === null ? null : meshEntityColliders(prepared);
+        if (set === null)
+            return false;
+        meshEntityByKind.set(kind, set);
+        signalNotify();
+        return true;
+    }
+    function reportObjectCollisionMesh(catalogId, mesh) {
+        if (mesh === null) {
+            const existed = meshObjectByCatalogId.delete(catalogId);
+            if (existed)
+                signalNotify();
+            return existed;
+        }
+        const prepared = prepareCollisionMeshSource(mesh);
+        const set = prepared === null ? null : meshObjectColliders(prepared);
+        if (set === null)
+            return false;
+        meshObjectByCatalogId.set(catalogId, set);
+        signalNotify();
+        return true;
+    }
+    function reportObjectBounds(catalogId, bounds) {
+        if (bounds === null) {
+            const existed = measuredObjectByCatalogId.delete(catalogId);
+            if (existed)
+                signalNotify();
+            return existed;
+        }
+        const measured = measuredObjectColliders(bounds);
+        if (measured === null)
+            return false;
+        measuredObjectByCatalogId.set(catalogId, measured);
+        signalNotify();
+        return true;
+    }
     function entityCollidersOf(instanceId) {
         const override = entityColliders.get(instanceId);
         if (override !== undefined)
@@ -92,8 +155,18 @@ export function createSceneSubsystem(d) {
         const kind = entities.get(instanceId)?.name;
         if (kind !== undefined) {
             const fitted = fittedEntitySetFor(kind);
+            // Index-derived mesh shapes win (identical on a headless host); otherwise a runtime-reported
+            // collision mesh upgrades the fitted/measured bounding box to the rendered triangles.
+            if (fitted !== null && hasMeshColliderShape(fitted))
+                return fitted;
+            const runtimeMesh = meshEntityByKind.get(kind);
+            if (runtimeMesh !== undefined)
+                return runtimeMesh;
             if (fitted !== null)
                 return fitted;
+            const measured = measuredEntityByKind.get(kind);
+            if (measured !== undefined)
+                return measured;
         }
         const scale = entry?.scale;
         if (scale !== undefined && scale !== 1)
@@ -116,8 +189,16 @@ export function createSceneSubsystem(d) {
         if (object === null)
             return null;
         const fitted = fittedObjectSetFor(object.catalogId);
+        if (fitted !== null && hasMeshColliderShape(fitted))
+            return fitted;
+        const runtimeMesh = meshObjectByCatalogId.get(object.catalogId);
+        if (runtimeMesh !== undefined)
+            return runtimeMesh;
         if (fitted !== null)
             return fitted;
+        const measured = measuredObjectByCatalogId.get(object.catalogId);
+        if (measured !== undefined)
+            return measured;
         if (object.visual?.scale === undefined)
             return null;
         return scaledObjectColliders(objectVisualScale(object.visual));
@@ -254,6 +335,8 @@ export function createSceneSubsystem(d) {
             signalNotify();
         },
         collidersOf: objectCollidersOf,
+        reportBounds: reportObjectBounds,
+        reportCollisionMesh: reportObjectCollisionMesh,
         selection: objectSelection,
     };
     return {
@@ -272,6 +355,8 @@ export function createSceneSubsystem(d) {
         objectColliders,
         entityCollidersOf,
         objectCollidersOf,
+        reportEntityBounds,
+        reportEntityCollisionMesh,
         entityVisualScaleOf,
         forms,
         paintLayer,

package/dist/runtime/gameContext.js

@@ -6,6 +6,7 @@ import { createGameFeed } from "../game/feed.js";
 import { setGamePhase } from "../game/gamePhase.js";
 import { createLootRegistry, grantDrops } from "../game/lootTable.js";
 import { createSocial } from "../game/social.js";
+import { splitStack } from "../inventory/inventoryModel.js";
 import { createItemUse } from "../item/use.js";
 import { createWeaponStats } from "../item/weapon.js";
 import {} from "../scene/entityStats.js";
@@ -55,7 +56,7 @@ export function createGameContext(options) {
         ...(occluder !== undefined ? { occluder } : {}),
         ...(options.models !== undefined ? { models: options.models } : {}),
     });
-    const { entities, objects, statsByInstance, entityStats, ensureInstanceStats, catalogEntry, spatial, combatSpatial, sceneRaycast, targeting, entityColliders, entityCollidersOf, objectCollidersOf, entityVisualScaleOf, forms, paintLayer, spawnEntity, despawnEntity, moveEntityTowardCommit, resetAllToSpawn, bind, sceneObjects, } = scene;
+    const { entities, objects, statsByInstance, entityStats, ensureInstanceStats, catalogEntry, spatial, combatSpatial, sceneRaycast, targeting, entityColliders, entityCollidersOf, objectCollidersOf, reportEntityBounds, reportEntityCollisionMesh, entityVisualScaleOf, forms, paintLayer, spawnEntity, despawnEntity, moveEntityTowardCommit, resetAllToSpawn, bind, sceneObjects, } = scene;
     // --- Shared game services (weapon, feed, features bag, commands, item use) ---
     const weapon = createWeaponStats((itemId) => content.itemById?.(itemId));
     const feed = createGameFeed(definition.feed);
@@ -114,6 +115,45 @@ export function createGameContext(options) {
     });
     const { inventoryIds, inventoryByUser, inventoryFor, layouts, wallets, walletOf, economy, putIntoAnyInventory, playerStatsFor, pose, possession, motionByUser, motionFor, loadouts, seedUserPool, } = playerSys;
     scene.setOnAfterDespawn((instanceId) => pose.clear(instanceId));
+    // Built-in inventory mutation commands so a HUD grid drives moves/splits through the notifying
+    // command path (a raw InventorySet mutation would not re-render React). Each resolves the acting
+    // user's own inventory, so it respects `privatePerUser` replication.
+    const knownInventory = (inventoryId) => layouts[inventoryId] !== undefined;
+    const slotInRange = (inventoryId, slot) => typeof slot === "number" && Number.isInteger(slot) && slot >= 0 && slot < layouts[inventoryId].slots;
+    commandRegistry.define("inventory.move", {
+        validate(_state, input) {
+            if (!knownInventory(input.inventoryId))
+                return { reason: `unknown inventory "${input.inventoryId}"` };
+            if (!slotInRange(input.inventoryId, input.from) || !slotInRange(input.inventoryId, input.to)) {
+                return { reason: "invalid-slot" };
+            }
+            return null;
+        },
+        apply(_state, input) {
+            const inventory = inventoryFor(activeUserId());
+            // A rejected move (empty source, wrong-kind, no-space) is a harmless no-op: the item bounces back.
+            inventory.move(input.inventoryId, input.from, input.inventoryId, input.to);
+        },
+    });
+    commandRegistry.define("inventory.split", {
+        validate(_state, input) {
+            if (!knownInventory(input.inventoryId))
+                return { reason: `unknown inventory "${input.inventoryId}"` };
+            if (!slotInRange(input.inventoryId, input.slot))
+                return { reason: "invalid-slot" };
+            if (input.toSlot !== undefined && !slotInRange(input.inventoryId, input.toSlot)) {
+                return { reason: "invalid-slot" };
+            }
+            return null;
+        },
+        apply(_state, input) {
+            const inventory = inventoryFor(activeUserId());
+            const result = splitStack(inventory.state(input.inventoryId), input.slot, input.amount, input.toSlot);
+            if (result.status === "rejected")
+                return;
+            inventory.replaceState(input.inventoryId, result.state);
+        },
+    });
     const loot = {
         register: lootRegistry.register,
         has: lootRegistry.has,
@@ -328,6 +368,8 @@ export function createGameContext(options) {
                     signal.notify();
                 },
                 collidersOf: entityCollidersOf,
+                reportBounds: reportEntityBounds,
+                reportCollisionMesh: reportEntityCollisionMesh,
                 visualScaleOf: entityVisualScaleOf,
                 form: forms,
                 paint: paintLayer,
@@ -472,16 +514,21 @@ function saveKey(name) {
     const slug = name.trim().toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/(^-|-$)/g, "");
     return `jgengine:save:${slug === "" ? "game" : slug}`;
 }
-/** Explicit `options.save` wins (the shell can inject any backend, e.g. cloud); otherwise `defineGame({ persist })` auto-wires a localStorage save for offline/single-player worlds only. */
+/**
+ * Explicit `options.save` wins (the shell can inject any backend, e.g. cloud); otherwise an offline /
+ * single-player world auto-wires a `localStorage` whole-world save **by default** — a game gets `ctx.game.save`
+ * and autosave without touching `persist`. Only an explicit `persist: false` opts out; a host-authoritative
+ * multiplayer world never persists to `localStorage` (its host owns persistence) regardless of `persist`.
+ */
 function resolveSaveOptions(definition, options) {
     if (options.save !== undefined)
         return options.save;
     const persist = definition.persist;
-    if (persist === undefined || persist === false)
+    if (persist === false)
         return undefined;
     if (!isOffline(definition.multiplayer))
         return undefined;
-    const config = persist === true ? {} : persist;
+    const config = persist === undefined || persist === true ? {} : persist;
     return {
         backend: config.storage === "memory" ? memorySaveBackend() : localSaveBackend(),
         mode: config.mode,

package/dist/runtime/gameContextTypes.d.ts

@@ -2,6 +2,7 @@ import type { CardPile, CardPileConfig } from "../cards/cardPile.js";
 import type { EffectInput, EffectResult, EffectVia, ReceiveMap, SingleTargetEffectInput } from "../combat/effects.js";
 import type { ProjectileSystem } from "../combat/projectiles.js";
 import type { HitReaction, HitReactionConfig, ImpactPresetName } from "../combat/hitReaction.js";
+import type { VfxPresetName } from "../combat/vfxPresets.js";
 import type { TelegraphShape } from "../combat/telegraph.js";
 import type { CommandDefinition, CommandResult } from "../commands/commandRegistry.js";
 import type { ChargeOptions as WalletChargeOptions } from "../economy/wallet.js";
@@ -33,7 +34,8 @@ import type { PaintLayer } from "../scene/paintLayer.js";
 import type { EntityStatsApi, StatCatalog } from "../scene/entityStats.js";
 import type { EntityBlackboard, EntityPose, EntityPosition, EntityStore, SceneEntity, SpawnOptions, SpawnPose } from "../scene/entityStore.js";
 import type { Forms } from "../scene/form.js";
-import type { EntityColliderSet, ModelBodySource } from "../scene/colliders.js";
+import type { EntityColliderSet, MeasuredBounds, ModelBodySource } from "../scene/colliders.js";
+import type { CollisionMeshSource } from "../scene/collisionMesh.js";
 import type { ObjectRaycastHit, ObjectRaycastInput } from "../scene/objectQuery.js";
 import type { ObjectStore } from "../scene/objectStore.js";
 import type { Roster } from "../scene/roster.js";
@@ -135,6 +137,24 @@ export interface SceneObjectContext extends ObjectStore {
     raycastAll(input: ObjectRaycastInput): readonly ObjectRaycastHit[];
     setColliders(instanceId: string, colliders: EntityColliderSet | null): void;
     collidersOf(instanceId: string): EntityColliderSet | null;
+    /**
+     * Report the entity-local AABB the renderer actually mounted for `catalogId` — stored per catalog
+     * id as a blocking physical body and consulted after authored `colliders` and index-`dims` fitted
+     * models, before the visual-scale fallback. The shell reports custom `renderObject` content and
+     * dims-less models automatically, so a placed prop's body wraps its real rendered shape instead of
+     * a unit-cube guess. Pass `null` to clear. Returns `false` when the bounds are degenerate.
+     * @capability measured-colliders hitboxes and blocking bodies wrap what the renderer actually mounted — custom render props and dims-less models stop falling back to fixed-size boxes.
+     */
+    reportBounds(catalogId: string, bounds: MeasuredBounds | null): boolean;
+    /**
+     * Report the entity-local triangle soup the renderer actually mounted for `catalogId` — stored per
+     * catalog id as a blocking physical body whose raycasts hit the real surface (a BVH over the
+     * triangles) while movement obstruction keeps the conservative AABB. Consulted right after
+     * authored `colliders` / index collision meshes and before the fitted-box, measured-bounds, and
+     * visual-scale fallbacks. The shell reports rendered models automatically. Pass `null` to clear.
+     * Returns `false` when no valid triangle survives.
+     */
+    reportCollisionMesh(catalogId: string, mesh: CollisionMeshSource | null): boolean;
     /**
      * Per-instance selection/highlight state for placed objects — the reactive counterpart to
      * `worldHealthBars`/`nameplates` (entities), so a build-mode or RTS selection ring reads
@@ -156,10 +176,22 @@ export interface FloatTextInput {
     crit?: boolean;
     scale?: number;
 }
-/** Request a transient spell/ability VFX burst; `from`/`to` accept an instance id or a world point, `color` is a `0xRRGGBB` tint, and `durationMs` defaults per `kind`. */
+/**
+ * Request a transient spell/ability VFX burst. The easy path is a named `preset` —
+ * `vfx({ preset: "arrow", from: caster, to: enemy })` renders a visible bolt with no color
+ * or archetype tuning; `"lightning"`, `"web"`, `"slash"`, `"shield"`, `"heal"`, `"explosion"`
+ * and the rest of {@link vfxPresets} likewise just work. `from`/`to` accept an instance id
+ * (the shell follows its live pose) or a fixed world point. Anything you also pass — `kind`,
+ * `color` (`0xRRGGBB`), `radius`, `durationMs` — overrides the preset; supply `kind` + `color`
+ * yourself for a fully custom burst with no preset. `durationMs` defaults per `kind`.
+ */
 export interface VfxInput {
-    kind: VfxKind;
-    color: number;
+    /** A named visual flavor from {@link vfxPresets}. Fills in `kind`/`color`/defaults; explicit fields below still win. */
+    preset?: VfxPresetName | (string & {});
+    /** Visual archetype. Optional when `preset` is given; required otherwise. */
+    kind?: VfxKind;
+    /** `0xRRGGBB` tint. Optional when `preset` is given; required otherwise. */
+    color?: number;
     from?: string | readonly [number, number, number];
     to?: string | readonly [number, number, number];
     radius?: number;
@@ -242,6 +274,28 @@ export interface SceneEntityContext {
     invalidateSpatial: SpatialApi["invalidate"];
     setColliders(instanceId: string, colliders: EntityColliderSet | null): void;
     collidersOf(instanceId: string): EntityColliderSet | null;
+    /**
+     * Report the entity-local AABB the renderer actually mounted for `kind` — stored per kind as a
+     * tight damage hitbox and consulted after authored `colliders` and index-`dims` fitted models,
+     * before the scale/humanoid-default fallbacks. The shell reports custom `renderEntity` content and
+     * dims-less models automatically, so hitboxes wrap the rendered mesh instead of the fixed
+     * 0.7×1.8×0.7 box. Runtime-measured on the client; authoritative hosts that never render should
+     * author `colliders` or model `dims` instead. Pass `null` to clear. Returns `false` when the
+     * bounds are degenerate.
+     * @capability measured-hitboxes an entity rendered with a custom mesh takes hits in a box matching its rendered bounds, not the fixed humanoid rectangle.
+     */
+    reportBounds(kind: string, bounds: MeasuredBounds | null): boolean;
+    /**
+     * Report the entity-local triangle soup the renderer actually mounted for `kind` — stored per kind
+     * as a damage hitbox that raycasts the model's own triangles (BVH), so shots aimed between a
+     * character's feet or past its shoulder miss instead of hitting a bounding box. Consulted right
+     * after authored `colliders` / index collision meshes and before the fitted-box and
+     * measured-bounds fallbacks. The shell reports rendered models automatically; authoritative hosts
+     * that never render should author `colliders` or index collision meshes for identical results.
+     * Pass `null` to clear. Returns `false` when no valid triangle survives.
+     * @capability conforming-hitboxes shots aimed between a character's feet or past its shoulder MISS — damage raycasts hit the rendered model's triangles, not its bounding box.
+     */
+    reportCollisionMesh(kind: string, mesh: CollisionMeshSource | null): boolean;
     /** Uniform visual scale from the entity's catalog entry (1 when unscaled). */
     visualScaleOf(instanceId: string): number;
     form: Forms;

package/dist/runtime/headlessRunner.d.ts

@@ -36,6 +36,17 @@ export interface HeadlessRunnerOptions<TAssetRef extends ModelAssetRef, TMultipl
     /** Render-model lookup for collider auto-fit — pass what the shell would derive from `entityModels`/`objectModels` so headless raycasts hit the same boxes as play. */
     models?: GameContextModels;
 }
+/** Canvas-free command/intent surface for {@link HeadlessRunner} — invoke a game's registered UI commands and read the resulting reactive state off `ctx`. */
+export interface HeadlessCommandInterface {
+    /** Invoke a registered command/intent by name against the live context. Throws on `unknown-command` or a validation rejection so a headless UI-flow test fails loudly instead of silently no-op'ing. */
+    invoke(name: string, input?: unknown): void;
+    /** Non-throwing {@link invoke} returning the raw command result (inspect `status`). */
+    tryInvoke(name: string, input?: unknown): ReturnType<GameContext["game"]["commands"]["run"]>;
+    /** Registered command names. */
+    names(): string[];
+    /** Is a command registered? */
+    has(name: string): boolean;
+}
 /**
  * A renderer-free driver for a game loop: builds a {@link GameContext} from a {@link GameDefinition}, runs the init
  * hooks, then advances the simulation one step at a time from injected input. No React, R3F, or three.js — the whole
@@ -58,5 +69,7 @@ export interface HeadlessRunner {
     step(dtSeconds: number, input?: HeadlessInput): number;
     /** Publish input without advancing — for pre-seeding the held set before the first {@link step}. */
     publishInput(input: HeadlessInput): void;
+    /** Drive the game's own UI commands / intents headlessly — the same registry `ctx.game.commands` and the shell's command sink dispatch into. No renderer, no pointer simulation: dispatch an intent, then read reactive state off `ctx`. */
+    readonly ui: HeadlessCommandInterface;
 }
 export declare function createHeadlessRunner<TAssetRef extends ModelAssetRef, TMultiplayer>(options: HeadlessRunnerOptions<TAssetRef, TMultiplayer>): HeadlessRunner;

package/dist/runtime/headlessRunner.js

@@ -29,6 +29,20 @@ export function createHeadlessRunner(options) {
         input: ctx.input,
         userId: player.userId,
         publishInput,
+        ui: {
+            invoke(name, input) {
+                const result = ctx.game.commands.run(name, input);
+                if (result.status === "unknown-command") {
+                    throw new Error(`headless ui.invoke: unknown command "${name}" — define it via ctx.game.commands.define`);
+                }
+                if (result.status === "rejected") {
+                    throw new Error(`headless ui.invoke: command "${name}" rejected — ${result.reason}`);
+                }
+            },
+            tryInvoke: (name, input) => ctx.game.commands.run(name, input),
+            names: () => ctx.game.commands.names(),
+            has: (name) => ctx.game.commands.has(name),
+        },
         step(dtSeconds, input) {
             if (input !== undefined)
                 publishInput(input);

package/dist/scene/assetCatalog.d.ts

@@ -22,6 +22,8 @@ export interface ModelAssetRef {
     collisionMesh?: CollisionMeshData;
     /** Authored asset-space metadata — canonical facing (degrees), source-unit scale, footprint, anchor, bounds, and rotation policy. The upstream owner of placement corrections; see {@link "scene/assetSpace".AssetSpace}. */
     space?: AssetSpace;
+    /** Animation clip names read from the GLB at asset reindex. Lets the shell auto-animate rigged catalog assets (semantic clip roles → default idle/walk/run + one-shots) with no game-side clip strings. */
+    clips?: readonly string[];
 }
 /**
  * A catalog entry backed by a registered {@link registerAssetGenerator} instead of a GLB URL — a

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/colliders.d.ts

@@ -107,6 +107,47 @@ export declare function fittedEntityColliders(model: ModelBodySource): EntityCol
  * @internal
  */
 export declare function fittedObjectColliders(model: ModelBodySource): EntityColliderSet | null;
+/**
+ * Entity-local AABB of what the renderer actually mounted for a kind — the runtime counterpart to
+ * index-measured `dims`. Reported through `ctx.scene.entity.reportBounds` /
+ * `ctx.scene.object.reportBounds` (the shell does this automatically for custom
+ * `renderEntity`/`renderObject` content and models without index dims) so collider resolution can
+ * wrap the real rendered shape instead of a fixed-size guess.
+ */
+export interface MeasuredBounds {
+    min: EntityPosition;
+    max: EntityPosition;
+}
+/** Damage hitbox exactly wrapping runtime-measured render bounds — what `reportBounds` stores for an
+ * entity kind. `null` when the bounds are degenerate, keeping the caller's existing fallback.
+ * @internal
+ */
+export declare function measuredEntityColliders(bounds: MeasuredBounds): EntityColliderSet | null;
+/** Blocking physical body exactly wrapping runtime-measured render bounds — what `reportBounds`
+ * stores for an object catalog id. `null` when the bounds are degenerate.
+ * @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

@@ -188,6 +188,146 @@ export function fittedObjectColliders(model) {
         },
     };
 }
+/** Thin measured axes (decals, blades, flat panels) keep at least this half-extent so the box stays hittable. */
+const MIN_MEASURED_HALF_EXTENT = 0.01;
+/** Tight AABB from measured bounds — `null` when inverted, non-finite, or a degenerate point. */
+function measuredBox(bounds) {
+    const { min, max } = bounds;
+    let volume = 0;
+    for (let axis = 0; axis < 3; axis += 1) {
+        const lo = min[axis];
+        const hi = max[axis];
+        if (!Number.isFinite(lo) || !Number.isFinite(hi) || hi < lo)
+            return null;
+        volume = Math.max(volume, hi - lo);
+    }
+    if (!(volume > 0))
+        return null;
+    return {
+        halfExtents: [
+            Math.max((max[0] - min[0]) / 2, MIN_MEASURED_HALF_EXTENT),
+            Math.max((max[1] - min[1]) / 2, MIN_MEASURED_HALF_EXTENT),
+            Math.max((max[2] - min[2]) / 2, MIN_MEASURED_HALF_EXTENT),
+        ],
+        offset: [(min[0] + max[0]) / 2, (min[1] + max[1]) / 2, (min[2] + max[2]) / 2],
+    };
+}
+/** Damage hitbox exactly wrapping runtime-measured render bounds — what `reportBounds` stores for an
+ * entity kind. `null` when the bounds are degenerate, keeping the caller's existing fallback.
+ * @internal
+ */
+export function measuredEntityColliders(bounds) {
+    const box = measuredBox(bounds);
+    if (box === null)
+        return null;
+    return {
+        hitboxes: [
+            {
+                name: "body",
+                purpose: "damage",
+                shape: { kind: "aabb", halfExtents: box.halfExtents, offset: box.offset },
+                damageEligible: true,
+                blocks: false,
+            },
+        ],
+    };
+}
+/** Blocking physical body exactly wrapping runtime-measured render bounds — what `reportBounds`
+ * stores for an object catalog id. `null` when the bounds are degenerate.
+ * @internal
+ */
+export function measuredObjectColliders(bounds) {
+    const box = measuredBox(bounds);
+    if (box === null)
+        return null;
+    return {
+        body: {
+            name: "body",
+            purpose: "physical",
+            shape: { kind: "aabb", halfExtents: box.halfExtents, offset: box.offset },
+            damageEligible: false,
+            blocks: true,
+        },
+    };
+}
+/** 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)