@jgengine/core 0.11.0 → 0.12.0

package/dist/runtime/hostedWorldSession.d.ts

@@ -1,6 +1,6 @@
 import type { CommandResult } from "../commands/commandRegistry.js";
 import type { ModelAssetRef } from "../scene/assetCatalog.js";
-import type { GameContext, GameContextContent } from "./gameContext.js";
+import type { GameContext, GameContextContent, GameContextModels } from "./gameContext.js";
 import type { GameDefinition, LoopPlayer } from "../game/defineGame.js";
 import { type HostedGameRunner, type InputFrame } from "./hostedGameRunner.js";
 import type { WorldDiff } from "./worldReplication.js";
@@ -42,6 +42,8 @@ export interface HostedWorldSessionOptions<TAssetRef extends ModelAssetRef, TMul
     store?: HostedWorldStore;
     /** Minimum elapsed ms between auto-saves on tick, measured against `now` (defaults to `Date.now` when omitted). Default `0` — persist on every revision-changing tick. */
     saveIntervalMs?: number;
+    /** Render-model lookup for collider auto-fit, forwarded to the runner — see {@link HostedGameRunnerOptions.models}. */
+    models?: GameContextModels;
 }
 /**
  * The stateful host substrate a long-lived backend binds (ws server, browser P2P host): a live

package/dist/runtime/hostedWorldSession.js

@@ -25,6 +25,7 @@ export function createHostedWorldSession(options) {
         ...(host === undefined ? {} : { host }),
         ...(now === undefined ? {} : { now }),
         ...(loaded === null ? {} : { restore: loaded.snapshot }),
+        ...(options.models === undefined ? {} : { models: options.models }),
     });
     let savedRevision = loaded?.revision ?? 0;
     let lastSaveAt = clock();

package/dist/runtime/worldSnapshot.d.ts

@@ -13,11 +13,20 @@ export interface SnapshotViewer {
  * - {@link project} narrows this module's snapshot to what one viewer may see (private state, area of
  *   interest). Absent → the module is world-public and every client receives it verbatim (the default).
  * - {@link version} is a monotone counter the host reads to skip re-serializing an unchanged module.
+ * - {@link decode} validates/coerces wire `unknown` into `T` before hydrate; returning `null` skips
+ *   that module (fail-soft) instead of poisoning live state with a bare cast.
  */
 export interface SnapshotModule<T = unknown> {
     readonly key: string;
     snapshot(): T;
     hydrate(data: T): void;
+    /**
+     * Optional wire codec: turn the raw snapshot value into a typed `T`, or `null` to skip this module.
+     * When present, {@link applyWorldSnapshot} runs it before {@link hydrate} and never calls hydrate on
+     * a failed decode — a bad host/client payload leaves the prior module state intact rather than
+     * throwing or applying garbage.
+     */
+    decode?(raw: unknown): T | null;
     /**
      * Narrow this module's full snapshot to what `viewer` is allowed to see — return the same shape
      * carrying only the visible subset (drop other players' private state, cull entities outside the
@@ -38,7 +47,10 @@ export type WorldSnapshot = Record<string, unknown>;
  * @internal
  */
 export declare function composeWorldSnapshot(modules: readonly SnapshotModule[], viewer?: SnapshotViewer): WorldSnapshot;
-/** Hydrate every registered module whose key is present in `snapshot`; keys absent from it are left untouched.
+/**
+ * Hydrate every registered module whose key is present in `snapshot`; keys absent from it are left
+ * untouched. When a module provides {@link SnapshotModule.decode}, a `null` decode skips that module
+ * (fail-soft) instead of calling hydrate with unvalidated wire data.
  * @internal
  */
 export declare function applyWorldSnapshot(modules: readonly SnapshotModule[], snapshot: WorldSnapshot): void;

package/dist/runtime/worldSnapshot.js

@@ -18,13 +18,25 @@ export function composeWorldSnapshot(modules, viewer) {
     }
     return snapshot;
 }
-/** Hydrate every registered module whose key is present in `snapshot`; keys absent from it are left untouched.
+/**
+ * Hydrate every registered module whose key is present in `snapshot`; keys absent from it are left
+ * untouched. When a module provides {@link SnapshotModule.decode}, a `null` decode skips that module
+ * (fail-soft) instead of calling hydrate with unvalidated wire data.
  * @internal
  */
 export function applyWorldSnapshot(modules, snapshot) {
     for (const module of modules) {
-        if (Object.prototype.hasOwnProperty.call(snapshot, module.key)) {
-            module.hydrate(snapshot[module.key]);
+        if (!Object.prototype.hasOwnProperty.call(snapshot, module.key))
+            continue;
+        const raw = snapshot[module.key];
+        if (module.decode !== undefined) {
+            const decoded = module.decode(raw);
+            if (decoded === null)
+                continue;
+            module.hydrate(decoded);
+        }
+        else {
+            module.hydrate(raw);
         }
     }
 }

package/dist/scene/assetCatalog.d.ts

@@ -1,4 +1,5 @@
 import type { AssetSpace } from "./assetSpace.js";
+import type { CollisionMeshData } from "./collisionMesh.js";
 /** Measured horizontal footprint, footprint center, and lowest Y of a model in model space. */
 export interface ModelDims {
     footprint: {
@@ -10,11 +11,15 @@ export interface ModelDims {
         z: number;
     };
     minY: number;
+    /** Highest Y in model space (pre-scale). `maxY - minY` is the measured model height; absent in indexes generated before it was measured. */
+    maxY?: number;
 }
 export interface ModelAssetRef {
     url: string;
     /** Measured at asset reindex: horizontal footprint, footprint center, and lowest Y in model space (pre-scale). Lets the shell auto-center and ground-snap corner-pivot kit models. */
     dims?: ModelDims;
+    /** Opt-in compact triangle mesh extracted at asset reindex (see {@link "scene/collisionMesh".CollisionMeshData}) — feeds mesh-accurate hitboxes for concave models. */
+    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;
 }

package/dist/scene/assetSpace.js

@@ -1,3 +1,4 @@
+import { clamp } from "../math/scalar.js";
 /**
  * Asset-space metadata + placement rotation policy: the catalog-owned description of how a model sits
  * in its source space and how a placement tool may rotate it. Games author scenes against engine north
@@ -11,9 +12,6 @@
 const DEG2RAD = Math.PI / 180;
 const RAD2DEG = 180 / Math.PI;
 const FULL_TURN = 360;
-function clamp(value, min, max) {
-    return value < min ? min : value > max ? max : value;
-}
 /**
  * Wrap `degrees` into `[0, 360)` — the canonical heading range every policy and conversion here works
  * in. Non-finite input collapses to `0` so bad metadata never leaks a `NaN` heading downstream.

package/dist/scene/authoredTriggers.d.ts

@@ -71,6 +71,23 @@ export declare function getTriggerAction(id: string): TriggerActionDefinition |
 export declare function listTriggerActions(target?: TriggerSourceKind): TriggerActionDefinition[];
 /** Clears the action registry — tests only. @internal */
 export declare function clearTriggerActions(): void;
+/**
+ * The engine's built-in trigger actions — the shared `announce` / `win` / `advance` vocabulary every
+ * game gets for free, so "enter this zone → win" is authored entirely in the editor with no bespoke
+ * action code. Their params land flat on the object's `meta` like any registered action; drive them
+ * at runtime with the handlers from {@link createTriggerOutcome}.
+ *
+ * @capability authored-triggers built-in announce/win/advance actions authorable on any marker or volume
+ */
+export declare const BUILTIN_TRIGGER_ACTIONS: readonly TriggerActionDefinition[];
+/**
+ * Register the engine's built-in {@link BUILTIN_TRIGGER_ACTIONS} so they appear in the editor's
+ * trigger inspector. Idempotent; call at module load (a game may still register its own actions or
+ * re-register a built-in id to override it).
+ *
+ * @capability authored-triggers register the shared announce/win/advance actions
+ */
+export declare function registerBuiltinTriggerActions(): void;
 /** Resolve the proximity radius for a marker trigger from meta. @internal */
 export declare function triggerRadiusOf(meta: Record<string, unknown> | undefined, fallback?: number): number;
 /**
@@ -156,6 +173,39 @@ export declare function createAuthoredTriggerRuntime(options: {
     /** Override the collected trigger list (tests / hot-reload). Default: {@link collectAuthoredTriggers}. */
     triggers?: readonly AuthoredTrigger[];
 }): AuthoredTriggerRuntime;
+/** Serializable read-model the built-in trigger actions write — the HUD/game reads it each frame. */
+export interface TriggerOutcome {
+    /** True once a `win` action fired. */
+    won: boolean;
+    /** Latest announce/win/advance message to surface, or null before any fires. */
+    message: string | null;
+    /** Tone for the latest message: `"info" | "warn" | "good"`. */
+    tone: string;
+    /** Current objective id from the latest `advance`, or null. */
+    objective: string | null;
+    /** Bumped on every change — a cheap key for `useSyncExternalStore`. */
+    revision: number;
+}
+/** Outcome store: the built-in action handlers plus a subscribable snapshot of what they produced. */
+export interface TriggerOutcomeStore {
+    /** Current outcome snapshot (stable reference until the next change). */
+    get(): TriggerOutcome;
+    /** Subscribe to outcome changes; returns an unsubscribe fn. */
+    subscribe(listener: () => void): () => void;
+    /** Handlers for `createAuthoredTriggerRuntime({ handlers })` — wires announce/win/advance. */
+    handlers: TriggerHandlers;
+    /** Reset to the initial (un-won) outcome — new run / retry. */
+    reset(): void;
+}
+/**
+ * Default runtime for the built-in {@link BUILTIN_TRIGGER_ACTIONS}: a small serializable outcome the
+ * HUD renders, with no engine-side UI. Pass {@link TriggerOutcomeStore.handlers} to
+ * {@link createAuthoredTriggerRuntime} and read {@link TriggerOutcomeStore.get} from the HUD via
+ * `useSyncExternalStore` — that is the whole zero-code "reach the zone to win" wiring.
+ *
+ * @capability authored-triggers headless win/announce/objective outcome for the built-in actions
+ */
+export declare function createTriggerOutcome(): TriggerOutcomeStore;
 /**
  * Build a meta patch that sets a single flat trigger (`on` + `action` + optional param fields) and
  * clears a multi-trigger list if present. Used by the editor inspector.

package/dist/scene/authoredTriggers.js

@@ -41,6 +41,64 @@ export function listTriggerActions(target) {
 export function clearTriggerActions() {
     actionRegistry.clear();
 }
+/**
+ * The engine's built-in trigger actions — the shared `announce` / `win` / `advance` vocabulary every
+ * game gets for free, so "enter this zone → win" is authored entirely in the editor with no bespoke
+ * action code. Their params land flat on the object's `meta` like any registered action; drive them
+ * at runtime with the handlers from {@link createTriggerOutcome}.
+ *
+ * @capability authored-triggers built-in announce/win/advance actions authorable on any marker or volume
+ */
+export const BUILTIN_TRIGGER_ACTIONS = [
+    {
+        id: "announce",
+        label: "Announce",
+        schema: {
+            fields: [
+                { type: "text", key: "message", label: "Message", default: "Entered zone" },
+                {
+                    type: "select",
+                    key: "tone",
+                    label: "Tone",
+                    options: [
+                        { value: "info", label: "Info" },
+                        { value: "warn", label: "Warn" },
+                        { value: "good", label: "Good" },
+                    ],
+                    default: "info",
+                },
+            ],
+        },
+    },
+    {
+        id: "win",
+        label: "Win the game",
+        schema: {
+            fields: [{ type: "text", key: "message", label: "Message", default: "You win!" }],
+        },
+    },
+    {
+        id: "advance",
+        label: "Advance objective",
+        schema: {
+            fields: [
+                { type: "text", key: "objective", label: "Next objective", default: "" },
+                { type: "text", key: "message", label: "Message", default: "" },
+            ],
+        },
+    },
+];
+/**
+ * Register the engine's built-in {@link BUILTIN_TRIGGER_ACTIONS} so they appear in the editor's
+ * trigger inspector. Idempotent; call at module load (a game may still register its own actions or
+ * re-register a built-in id to override it).
+ *
+ * @capability authored-triggers register the shared announce/win/advance actions
+ */
+export function registerBuiltinTriggerActions() {
+    for (const definition of BUILTIN_TRIGGER_ACTIONS)
+        registerTriggerAction(definition);
+}
 function isTriggerEvent(value) {
     return typeof value === "string" && TRIGGER_EVENTS.includes(value);
 }
@@ -311,6 +369,62 @@ export function createAuthoredTriggerRuntime(options) {
         },
     };
 }
+const INITIAL_OUTCOME = { won: false, message: null, tone: "info", objective: null, revision: 0 };
+/**
+ * Default runtime for the built-in {@link BUILTIN_TRIGGER_ACTIONS}: a small serializable outcome the
+ * HUD renders, with no engine-side UI. Pass {@link TriggerOutcomeStore.handlers} to
+ * {@link createAuthoredTriggerRuntime} and read {@link TriggerOutcomeStore.get} from the HUD via
+ * `useSyncExternalStore` — that is the whole zero-code "reach the zone to win" wiring.
+ *
+ * @capability authored-triggers headless win/announce/objective outcome for the built-in actions
+ */
+export function createTriggerOutcome() {
+    let outcome = INITIAL_OUTCOME;
+    const listeners = new Set();
+    const commit = (next) => {
+        outcome = { ...next, revision: outcome.revision + 1 };
+        for (const listener of listeners)
+            listener();
+    };
+    const messageOf = (event, fallback) => {
+        const value = event.params.message;
+        return typeof value === "string" && value.length > 0 ? value : fallback;
+    };
+    const stringParam = (event, key) => {
+        const value = event.params[key];
+        return typeof value === "string" && value.length > 0 ? value : undefined;
+    };
+    return {
+        get: () => outcome,
+        subscribe(listener) {
+            listeners.add(listener);
+            return () => {
+                listeners.delete(listener);
+            };
+        },
+        handlers: {
+            announce: (event) => {
+                commit({ won: outcome.won, message: messageOf(event, "Entered zone"), tone: stringParam(event, "tone") ?? "info", objective: outcome.objective });
+            },
+            win: (event) => {
+                commit({ won: true, message: messageOf(event, "You win!"), tone: "good", objective: outcome.objective });
+            },
+            advance: (event) => {
+                commit({
+                    won: outcome.won,
+                    message: stringParam(event, "message") ?? outcome.message,
+                    tone: outcome.tone,
+                    objective: stringParam(event, "objective") ?? outcome.objective,
+                });
+            },
+        },
+        reset() {
+            outcome = INITIAL_OUTCOME;
+            for (const listener of listeners)
+                listener();
+        },
+    };
+}
 /**
  * Build a meta patch that sets a single flat trigger (`on` + `action` + optional param fields) and
  * clears a multi-trigger list if present. Used by the editor inspector.

package/dist/scene/builtinSceneKinds.js

@@ -2,16 +2,19 @@
  * Registers the engine's built-in *environment* scene kinds against the {@link registerSceneKind}
  * seam: `scatter` (the proof adopter — its inspector, `+ Add` entry, and parse now come from the
  * registry), `water` (a reusable parametric water surface), `grass_field` (GPU vertex-wind grass), and
- * `soil` (crack/moss ground-variation patch). These are genre-agnostic engine primitives, like terrain.
- * Domain studios (poles, bookcases, …) are NOT built in — they register themselves from example/game
- * code via the same public seam, needing zero engine edits (see `examples/studios`). Call
+ * `soil` (crack/moss ground-variation patch), and `pole_line` (poles + sagging cables along a path).
+ * These are genre-agnostic engine primitives, like terrain. Domain studios (bookcases, …) are NOT
+ * built in — they register themselves from example/game code via the same public seam, needing zero
+ * engine edits (see `examples/studios`). Call
  * {@link registerBuiltinSceneKinds} once at startup (idempotent).
  */
 import { SCATTER_PATH_KIND } from "../world/scatterRegion.js";
 import { registerWaterKind } from "../world/waterKind.js";
 import { registerGrassKind } from "../world/grassKind.js";
 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 { registerSceneKind } from "./sceneKinds.js";
 /** The scatter/foliage region schema — the fields the inspector exposed as hand-written `ScatterFields`. */
 export const SCATTER_SCHEMA = {
@@ -58,5 +61,7 @@ export function registerBuiltinSceneKinds() {
     registerWaterKind();
     registerGrassKind();
     registerSoilKind();
+    registerCityKind();
+    registerPoleLineKind();
     registerBuildingGenerator();
 }

package/dist/scene/colliders.d.ts

@@ -1,5 +1,14 @@
+import type { ModelDims } from "./assetCatalog.js";
+import { type CollisionMeshData, type PreparedCollisionMesh } from "./collisionMesh.js";
 import type { EntityPosition } from "./entityStore.js";
 export type ColliderPurpose = "physical" | "damage";
+/**
+ * Collision geometry in entity-local space. `sphere` and `aabb` are analytic; `mesh` carries a
+ * prepared triangle mesh so opted-in concave models raycast their real surface while bounds and
+ * broadphase keep reading the conservative `halfExtents`.
+ * @capability mesh-hitboxes shots pass through holes in concave models — opted-in catalog assets raycast their actual triangles instead of the fitted box.
+ * @capability 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.
+ */
 export type ColliderShape = {
     kind: "sphere";
     radius: number;
@@ -8,6 +17,27 @@ export type ColliderShape = {
     kind: "aabb";
     halfExtents: EntityPosition;
     offset?: EntityPosition;
+} | {
+    kind: "mesh";
+    /** Prepared triangle mesh in model space — engine-derived from an opted-in catalog asset, never hand-authored. */
+    mesh: PreparedCollisionMesh;
+    /** Uniform model→entity-local scale (same composition as the fitted box). */
+    meshScale: number;
+    /** Entity-local translation applied after `meshScale`. */
+    meshTranslate: EntityPosition;
+    /** Conservative entity-local AABB of the placed mesh — bounds/broadphase read this exactly like an `aabb`. */
+    halfExtents: EntityPosition;
+    /**
+     * Optional compact entity-local solid decomposition (from the model's `collisionMesh.boxes`, scaled
+     * and translated onto the placement exactly like `mesh`). Movement obstruction slides against these
+     * sub-boxes so a capsule walks THROUGH a concave opening; raycasts still use `mesh`. Absent when the
+     * model shipped no `boxes`.
+     */
+    boxes?: readonly {
+        min: EntityPosition;
+        max: EntityPosition;
+    }[];
+    offset?: EntityPosition;
 };
 export interface ColliderDef {
     name: string;
@@ -49,6 +79,34 @@ export declare function defaultObjectColliders(halfExtents?: EntityPosition): En
  * @internal
  */
 export declare function scaledObjectColliders(scale: readonly [number, number, number]): EntityColliderSet;
+/**
+ * The render-config subset collider fitting reads — structurally satisfied by a resolved `ModelConfig`,
+ * so the shell can hand its render config straight to the fitting math without a conversion step.
+ */
+export interface ModelBodySource {
+    /** Measured model-space bounds from the asset index; fitting requires `dims` with `maxY`. */
+    dims?: ModelDims;
+    /** Uniform render scale. Default `1`. */
+    scale?: number;
+    /** Normalize-to-height in world units — fitting composes it exactly like the renderer (`targetHeight / measured height`, multiplied by `scale`). */
+    targetHeight?: number;
+    /** Vertical render offset added to the placement Y. Default `0`. */
+    y?: number;
+    /** Placement registration. `"center"` (default) centers the footprint and grounds `minY` on the placement point; `"origin"` renders at the raw model origin. */
+    anchor?: "center" | "origin";
+    /** Opt-in triangle collision mesh extracted at asset reindex; when present, fitting emits a mesh-accurate shape (rays pass through holes in concave models) instead of the fitted box. */
+    collisionMesh?: CollisionMeshData;
+}
+/** Damage hitbox fitted to the rendered model's measured bounds — the model-aware replacement for the
+ * fixed humanoid default. `null` when the model is unmeasured, keeping the caller's existing fallback.
+ * @internal
+ */
+export declare function fittedEntityColliders(model: ModelBodySource): EntityColliderSet | null;
+/** Blocking physical body fitted to the rendered model's measured bounds — the model-aware replacement
+ * for the unit-cube-times-scale guess. `null` when the model is unmeasured.
+ * @internal
+ */
+export declare function fittedObjectColliders(model: ModelBodySource): EntityColliderSet | null;
 /** @internal */
 export declare function resolveColliders(set: EntityColliderSet | null | undefined): ResolvedCollider[];
 /** @internal */

package/dist/scene/colliders.js

@@ -1,3 +1,4 @@
+import { prepareCollisionMesh } from "./collisionMesh.js";
 export const DEFAULT_ENTITY_HIT_RADIUS = 0.5;
 export const DEFAULT_OBJECT_HALF_EXTENTS = [0.5, 0.5, 0.5];
 /** Matches the shell's fallback actor capsule (~0.7m wide, feet at y=0 to head at ~1.8m). */
@@ -80,6 +81,113 @@ export function scaledObjectColliders(scale) {
         },
     };
 }
+/**
+ * The entity-local AABB the rendered model actually occupies, from measured dims + render config — the
+ * same scale/normalize/anchor math the shell uses to place the mesh, so box equals visual by
+ * construction. `null` when the model is unmeasured (`dims`/`maxY` absent) or degenerate.
+ */
+function fittedModelBox(model) {
+    const dims = model.dims;
+    if (dims === undefined || dims.maxY === undefined)
+        return null;
+    const { w, d } = dims.footprint;
+    const height = dims.maxY - dims.minY;
+    if (!(w > 0) || !(d > 0) || !(height > 0))
+        return null;
+    if (!Number.isFinite(w) || !Number.isFinite(d) || !Number.isFinite(height))
+        return null;
+    const normalize = model.targetHeight !== undefined && model.targetHeight > 0 ? model.targetHeight / height : 1;
+    const scale = (model.scale ?? 1) * normalize;
+    if (!(scale > 0) || !Number.isFinite(scale))
+        return null;
+    const baseY = model.y ?? 0;
+    // The renderer centers/grounds whenever it normalizes to targetHeight or anchors "center" (the
+    // default); only a raw-origin model without targetHeight keeps its authored pivot.
+    const centered = model.targetHeight !== undefined || (model.anchor ?? "center") === "center";
+    const halfExtents = [(w / 2) * scale, (height / 2) * scale, (d / 2) * scale];
+    const offset = centered
+        ? [0, baseY + (height / 2) * scale, 0]
+        : [dims.center.x * scale, baseY + (dims.minY + height / 2) * scale, dims.center.z * scale];
+    // Maps the model point (center.x, minY, center.z) to the entity-local (0, baseY, 0) the box grounds
+    // on when centered; a raw-origin model keeps its authored pivot and only takes the render offset.
+    const meshTranslate = centered
+        ? [-dims.center.x * scale, baseY - dims.minY * scale, -dims.center.z * scale]
+        : [0, baseY, 0];
+    return { halfExtents, offset, scale, meshTranslate };
+}
+/** Map a model-space point onto entity-local space with the mesh shape's uniform `scale` and per-axis
+ * `translate` (`coord * scale + translate`) — the same composition applied to `meshScale`/`meshTranslate`,
+ * so a model-space AABB corner lands exactly where the placed mesh puts it. `scale > 0` keeps min<max. */
+function scaleTranslatePoint(point, scale, translate) {
+    return [point[0] * scale + translate[0], point[1] * scale + translate[1], point[2] * scale + translate[2]];
+}
+/** The fitted collider shape for a rendered model: a mesh-accurate triangle shape when the model
+ * opts in with a decodable `collisionMesh`, otherwise the conservative fitted box. `null` when the
+ * model is unmeasured or degenerate.
+ */
+function fittedBodyShape(model) {
+    const box = fittedModelBox(model);
+    if (box === null)
+        return null;
+    const mesh = model.collisionMesh !== undefined ? prepareCollisionMesh(model.collisionMesh) : null;
+    if (mesh !== null) {
+        const sourceBoxes = model.collisionMesh?.boxes;
+        const boxes = sourceBoxes !== undefined && sourceBoxes.length > 0
+            ? sourceBoxes.map((b) => ({
+                min: scaleTranslatePoint(b.min, box.scale, box.meshTranslate),
+                max: scaleTranslatePoint(b.max, box.scale, box.meshTranslate),
+            }))
+            : undefined;
+        return {
+            kind: "mesh",
+            mesh,
+            meshScale: box.scale,
+            meshTranslate: box.meshTranslate,
+            halfExtents: box.halfExtents,
+            ...(boxes !== undefined ? { boxes } : {}),
+            offset: box.offset,
+        };
+    }
+    return { kind: "aabb", halfExtents: box.halfExtents, offset: box.offset };
+}
+/** Damage hitbox fitted to the rendered model's measured bounds — the model-aware replacement for the
+ * fixed humanoid default. `null` when the model is unmeasured, keeping the caller's existing fallback.
+ * @internal
+ */
+export function fittedEntityColliders(model) {
+    const shape = fittedBodyShape(model);
+    if (shape === null)
+        return null;
+    return {
+        hitboxes: [
+            {
+                name: "body",
+                purpose: "damage",
+                shape,
+                damageEligible: true,
+                blocks: false,
+            },
+        ],
+    };
+}
+/** Blocking physical body fitted to the rendered model's measured bounds — the model-aware replacement
+ * for the unit-cube-times-scale guess. `null` when the model is unmeasured.
+ * @internal
+ */
+export function fittedObjectColliders(model) {
+    const shape = fittedBodyShape(model);
+    if (shape === null)
+        return null;
+    return {
+        body: {
+            name: "body",
+            purpose: "physical",
+            shape,
+            damageEligible: false,
+            blocks: true,
+        },
+    };
+}
 /** @internal */
 export function resolveColliders(set) {
     if (set === null || set === undefined)

package/dist/scene/collisionMesh.d.ts

@@ -0,0 +1,94 @@
+import type { EntityPosition } from "./entityStore.js";
+/**
+ * Compact, serializable triangle collision mesh measured at asset reindex — the renderer-free source
+ * of mesh-accurate hitboxes. Positions are welded onto a 16-bit grid spanning `min`..`max` (model
+ * space) and stored base64-encoded, so an opted-in catalog asset ships its collision triangles inside
+ * the generated index without the runtime ever touching the rendered scene graph.
+ */
+export interface CollisionMeshData {
+    /** Model-space bounds of the encoded vertices — the quantization frame. */
+    min: readonly [number, number, number];
+    max: readonly [number, number, number];
+    /** Welded vertex count; `positions` holds exactly `vertexCount * 3` u16 values. */
+    vertexCount: number;
+    /** Triangle count; `indices` holds exactly `triangleCount * 3` values. */
+    triangleCount: number;
+    /** Base64 little-endian u16 xyz triples, each axis normalized 0..65535 across `min`..`max`. */
+    positions: string;
+    /** Base64 little-endian triangle vertex indices — u16, or u32 when `vertexCount` exceeds 65536. */
+    indices: string;
+    /**
+     * Optional compact model-space solid decomposition from {@link voxelizeToBoxes} — a deterministic set
+     * of AABBs approximating the model's filled volume so movement obstruction can slide a capsule against
+     * the real pillars/lintel of a concave opening (walk THROUGH an arch) instead of one outer box. Absent
+     * for models whose voxelization is empty, keeping box-less assets byte-identical.
+     */
+    boxes?: readonly {
+        min: readonly [number, number, number];
+        max: readonly [number, number, number];
+    }[];
+}
+/** Raw triangle soup for {@link encodeCollisionMesh}: model-space xyz triples plus triangle indices. */
+export interface CollisionMeshSource {
+    positions: ArrayLike<number>;
+    indices: ArrayLike<number>;
+}
+/**
+ * Decoded, BVH-indexed triangles ready for per-ray queries — build once per asset via
+ * {@link prepareCollisionMesh}. Treat the fields as opaque; they exist so the raycast hot path can
+ * run allocation-free over flat arrays.
+ */
+export interface PreparedCollisionMesh {
+    /** Dequantized model-space vertex xyz triples. */
+    readonly positions: Float32Array;
+    /** Triangle vertex indices, 3 per triangle. */
+    readonly indices: Uint32Array;
+    /** Per-node AABBs, 6 floats (minXYZ, maxXYZ) per node. */
+    readonly nodeBounds: Float32Array;
+    /** Leaf: first slot in `triOrder`. Internal: right-child node index (left child is `node + 1`). */
+    readonly nodeStart: Int32Array;
+    /** Leaf: triangle count (> 0). Internal: 0. */
+    readonly nodeCount: Int32Array;
+    /** Triangle indices grouped by leaf ranges. */
+    readonly triOrder: Uint32Array;
+}
+/** Nearest triangle impact from {@link raycastCollisionMesh}: world distance along the ray and the world-space geometric normal facing the ray. */
+export interface CollisionMeshHit {
+    distance: number;
+    normal: EntityPosition;
+}
+/**
+ * Quantize a triangle soup onto the 16-bit grid, weld coincident vertices, and drop triangles that
+ * collapse — the reindex-time compressor producing {@link CollisionMeshData}. Returns `null` when no
+ * finite, non-degenerate triangle survives.
+ */
+export declare function encodeCollisionMesh(source: CollisionMeshSource): CollisionMeshData | null;
+/**
+ * Decompose a triangle soup into a compact, deterministic set of model-space AABBs approximating its
+ * solid volume — the movement-obstruction counterpart to the raycast BVH. Rasterizes triangles onto a
+ * `cellSize` voxel grid, fills each vertical column between its lowest and highest occupied voxel (so a
+ * solid becomes solid and a concave opening — an archway — keeps its central gap empty while its pillars
+ * and lintel fill in), then greedy-merges occupied voxels into AABBs in a fixed z→y→x order. Pure and
+ * allocation-tolerant (runs once per asset at reindex). Caps the output at `maxBoxes`, folding any
+ * remainder into one enclosing AABB so obstruction stays conservative. Returns `[]` for degenerate input.
+ * @internal
+ */
+export declare function voxelizeToBoxes(source: CollisionMeshSource, cellSize?: number, maxBoxes?: number): {
+    min: [number, number, number];
+    max: [number, number, number];
+}[];
+/**
+ * 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)
+ * when the payload is malformed.
+ */
+export declare function prepareCollisionMesh(data: CollisionMeshData): PreparedCollisionMesh | null;
+/**
+ * Nearest triangle hit for a world-space ray against a prepared mesh placed like its rendered model:
+ * model space scaled uniformly by `scale`, translated by entity-local `translate`, yaw-rotated by
+ * `rotationY`, and moved to `position` — the same composition {@link "scene/colliders".ModelBodySource}
+ * fitting applies to the AABB. Allocation-free until the returned hit. `distance` is world distance
+ * along `direction` (callers pass `direction` normalized); `normal` is the world-space geometric
+ * triangle normal facing the ray.
+ */
+export declare function raycastCollisionMesh(mesh: PreparedCollisionMesh, origin: EntityPosition, direction: EntityPosition, maxDistance: number, position: EntityPosition, rotationY: number, scale: number, translate: EntityPosition): CollisionMeshHit | null;