@jgengine/core 0.10.0 → 0.12.0

package/dist/scene/behaviorRuntime.d.ts

@@ -0,0 +1,75 @@
+import { type PathFollowState, type PathProgress, type Waypoint } from "../nav/pathFollow.js";
+import type { GameContext } from "../runtime/gameContext.js";
+/** Whether a behavior instance advances and writes pose (`active`), is temporarily suspended retaining
+ * state (`paused`), or is held off until re-enabled (`disabled`). */
+export type BehaviorStatus = "active" | "paused" | "disabled";
+/**
+ * Catch-up policy applied when a paused instance resumes. `freeze` (default, deterministic) discards
+ * the time spent paused; `advance` silently fast-forwards the instance by the paused duration without
+ * emitting intermediate pose writes. Only patrol honors `advance`; wander treats it as `freeze`.
+ */
+export type BehaviorResumePolicy = "freeze" | "advance";
+/** Serializable snapshot of one behavior instance — round-trips exactly through
+ * {@link BehaviorControl.serialize}/{@link BehaviorControl.restore}. */
+export type BehaviorSnapshot = {
+    readonly kind: "patrol";
+    readonly state: PathFollowState;
+} | {
+    readonly kind: "wander";
+    readonly origin: Waypoint;
+    readonly target: Waypoint | null;
+};
+/** Inspection readout for editor/debug tooling, from {@link BehaviorControl.inspect}/{@link BehaviorControl.list}. */
+export interface BehaviorInspection {
+    id: string;
+    kind: "patrol" | "wander";
+    status: BehaviorStatus;
+    reason: string | null;
+}
+/**
+ * Per-entity control surface for the behavior runtime — pause/resume/disable/enable an instance,
+ * seek it to semantic progress, serialize/restore its state, and inspect it, all keyed by stable
+ * entity id without a full-world scan. Obtain it with {@link behaviorControl}.
+ */
+export interface BehaviorControl {
+    /** Current status of the instance, or `null` if the entity has no live behavior. */
+    status(id: string): BehaviorStatus | null;
+    /** Human-readable reason attached to the last pause/disable, or `null`. */
+    reason(id: string): string | null;
+    /** Suspend advancement and pose writes, retaining state. No-op (`false`) if not active. */
+    pause(id: string, reason?: string): boolean;
+    /** Resume a paused instance, applying the catch-up `policy` (default `freeze`). */
+    resume(id: string, policy?: BehaviorResumePolicy): boolean;
+    /** Hold the instance off (no advance, no pose) until {@link enable}. Retains state. */
+    disable(id: string, reason?: string): boolean;
+    /** Re-activate a disabled instance from its retained state (no catch-up). */
+    enable(id: string): boolean;
+    /** Jump a patrol instance to semantic {@link PathProgress}. Returns `false` for non-patrol instances. */
+    seek(id: string, progress: PathProgress): boolean;
+    /** Capture the instance's exact serializable state, or `null` if absent. */
+    serialize(id: string): BehaviorSnapshot | null;
+    /** Restore an instance from a {@link BehaviorSnapshot} of the matching kind. */
+    restore(id: string, snapshot: BehaviorSnapshot): boolean;
+    /** Inspect one instance, or `null` if absent. */
+    inspect(id: string): BehaviorInspection | null;
+    /** Inspect every live instance (bounded by spawned behavior entities). */
+    list(): BehaviorInspection[];
+}
+/**
+ * Advance every spawned entity carrying a `patrol` or `wander` {@link BehaviorDescriptor} one tick — the
+ * engine reads the descriptor, keeps the per-entity nav state itself, and poses the entity, so ambient
+ * traffic and idle NPC routes are register-once (attach the behavior at spawn) instead of a per-game
+ * per-frame `advancePathFollow` + `setPose` loop. Instances that are paused or disabled through
+ * {@link behaviorControl} retain their state and are skipped. The shell/host call this each frame; a game never does.
+ *
+ * @capability behavior-tick auto-advance patrol/wander behaviors on spawned entities, no per-game route loop
+ */
+export declare function advanceBehaviors(ctx: GameContext, dt: number): void;
+/**
+ * Obtain the per-context {@link BehaviorControl} surface for suspending, resuming, seeking, serializing,
+ * and inspecting behavior instances by entity id — the lifecycle contract games use to hand pose
+ * ownership to possession/streaming/staggering code instead of bypassing the behavior runtime.
+ *
+ * @capability behavior-control pause/disable/resume/seek/inspect behavior instances per entity
+ */
+export declare function behaviorControl(ctx: GameContext): BehaviorControl;

package/dist/scene/behaviorRuntime.js

@@ -0,0 +1,217 @@
+import { seededRng } from "../random/rng.js";
+import { advancePathFollow, createPathFollow, pathFollowSeek, } from "../nav/pathFollow.js";
+import { perContext } from "../runtime/perContext.js";
+const DEFAULT_WANDER_SPEED = 1.5;
+const WANDER_ARRIVAL = 0.6;
+function patrolOf(entity) {
+    return entity.behaviors.find((b) => b.kind === "patrol") ?? null;
+}
+function wanderOf(entity) {
+    return entity.behaviors.find((b) => b.kind === "wander") ?? null;
+}
+const runtimeOf = perContext((ctx) => {
+    const nav = new Map();
+    const refresh = () => {
+        const live = new Set();
+        for (const entity of ctx.scene.entity.list()) {
+            live.add(entity.id);
+            if (nav.has(entity.id))
+                continue;
+            const patrol = patrolOf(entity);
+            if (patrol !== null) {
+                const config = { waypoints: patrol.waypoints, speed: patrol.speed, loop: patrol.loop };
+                nav.set(entity.id, {
+                    kind: "patrol",
+                    config,
+                    state: patrol.startProgress !== undefined ? pathFollowSeek(config, patrol.startProgress) : createPathFollow(config),
+                    groundClamp: patrol.groundClamp ?? false,
+                    status: "active",
+                    reason: null,
+                    pausedElapsed: 0,
+                });
+                continue;
+            }
+            const wander = wanderOf(entity);
+            if (wander !== null) {
+                nav.set(entity.id, {
+                    kind: "wander",
+                    radius: wander.radius,
+                    origin: entity.position,
+                    target: null,
+                    roll: seededRng(`wander:${entity.id}`),
+                    status: "active",
+                    reason: null,
+                    pausedElapsed: 0,
+                });
+            }
+        }
+        for (const id of nav.keys())
+            if (!live.has(id))
+                nav.delete(id);
+    };
+    ctx.scene.entity.subscribeMembership(refresh);
+    refresh();
+    return { nav };
+});
+function stepWander(ctx, id, nav, dt) {
+    const entity = ctx.scene.entity.get(id);
+    if (entity === null)
+        return;
+    const [px, , pz] = entity.position;
+    if (nav.target === null || Math.hypot(px - nav.target[0], pz - nav.target[2]) < WANDER_ARRIVAL) {
+        const angle = nav.roll() * Math.PI * 2;
+        const distance = Math.sqrt(nav.roll()) * nav.radius;
+        const tx = nav.origin[0] + Math.cos(angle) * distance;
+        const tz = nav.origin[2] + Math.sin(angle) * distance;
+        nav.target = [tx, ctx.world.groundHeightAt(tx, tz), tz];
+    }
+    const speed = entity.movement.walkSpeed ?? DEFAULT_WANDER_SPEED;
+    const dx = nav.target[0] - px;
+    const dz = nav.target[2] - pz;
+    const dist = Math.hypot(dx, dz);
+    if (dist < 1e-6)
+        return;
+    const step = Math.min(dist, speed * dt);
+    const nx = px + (dx / dist) * step;
+    const nz = pz + (dz / dist) * step;
+    ctx.scene.entity.setPose(id, {
+        position: [nx, ctx.world.groundHeightAt(nx, nz), nz],
+        rotationY: Math.atan2(dx, dz),
+        dt,
+    });
+}
+function posePatrol(ctx, id, nav, dt) {
+    const [x, y, z] = nav.state.position;
+    ctx.scene.entity.setPose(id, {
+        position: nav.groundClamp ? [x, ctx.world.groundHeightAt(x, z), z] : [x, y, z],
+        rotationY: nav.state.heading,
+        dt,
+    });
+}
+/**
+ * Advance every spawned entity carrying a `patrol` or `wander` {@link BehaviorDescriptor} one tick — the
+ * engine reads the descriptor, keeps the per-entity nav state itself, and poses the entity, so ambient
+ * traffic and idle NPC routes are register-once (attach the behavior at spawn) instead of a per-game
+ * per-frame `advancePathFollow` + `setPose` loop. Instances that are paused or disabled through
+ * {@link behaviorControl} retain their state and are skipped. The shell/host call this each frame; a game never does.
+ *
+ * @capability behavior-tick auto-advance patrol/wander behaviors on spawned entities, no per-game route loop
+ */
+export function advanceBehaviors(ctx, dt) {
+    if (dt <= 0)
+        return;
+    const { nav } = runtimeOf(ctx);
+    if (nav.size === 0)
+        return;
+    for (const [id, entry] of nav) {
+        if (entry.status !== "active") {
+            if (entry.status === "paused")
+                entry.pausedElapsed += dt;
+            continue;
+        }
+        if (entry.kind === "patrol") {
+            entry.state = advancePathFollow(entry.config, entry.state, dt);
+            posePatrol(ctx, id, entry, dt);
+        }
+        else {
+            stepWander(ctx, id, entry, dt);
+        }
+    }
+}
+/**
+ * Obtain the per-context {@link BehaviorControl} surface for suspending, resuming, seeking, serializing,
+ * and inspecting behavior instances by entity id — the lifecycle contract games use to hand pose
+ * ownership to possession/streaming/staggering code instead of bypassing the behavior runtime.
+ *
+ * @capability behavior-control pause/disable/resume/seek/inspect behavior instances per entity
+ */
+export function behaviorControl(ctx) {
+    const { nav } = runtimeOf(ctx);
+    const setStatus = (id, status, reason) => {
+        const entry = nav.get(id);
+        if (entry === undefined)
+            return false;
+        entry.status = status;
+        entry.reason = reason;
+        return true;
+    };
+    return {
+        status: (id) => nav.get(id)?.status ?? null,
+        reason: (id) => nav.get(id)?.reason ?? null,
+        pause: (id, reason) => {
+            const entry = nav.get(id);
+            if (entry === undefined || entry.status !== "active")
+                return false;
+            entry.status = "paused";
+            entry.reason = reason ?? null;
+            entry.pausedElapsed = 0;
+            return true;
+        },
+        resume: (id, policy = "freeze") => {
+            const entry = nav.get(id);
+            if (entry === undefined || entry.status !== "paused")
+                return false;
+            if (policy === "advance" && entry.kind === "patrol" && entry.pausedElapsed > 0) {
+                entry.state = advancePathFollow(entry.config, entry.state, entry.pausedElapsed);
+                // Emit a single final pose at the caught-up position (no intermediate writes).
+                posePatrol(ctx, id, entry, entry.pausedElapsed);
+            }
+            entry.status = "active";
+            entry.reason = null;
+            entry.pausedElapsed = 0;
+            return true;
+        },
+        disable: (id, reason) => setStatus(id, "disabled", reason ?? null),
+        enable: (id) => {
+            const entry = nav.get(id);
+            if (entry === undefined || entry.status !== "disabled")
+                return false;
+            entry.status = "active";
+            entry.reason = null;
+            entry.pausedElapsed = 0;
+            return true;
+        },
+        seek: (id, progress) => {
+            const entry = nav.get(id);
+            if (entry === undefined || entry.kind !== "patrol")
+                return false;
+            entry.state = pathFollowSeek(entry.config, progress);
+            return true;
+        },
+        serialize: (id) => {
+            const entry = nav.get(id);
+            if (entry === undefined)
+                return null;
+            if (entry.kind === "patrol")
+                return { kind: "patrol", state: { ...entry.state } };
+            return { kind: "wander", origin: [...entry.origin], target: entry.target === null ? null : [...entry.target] };
+        },
+        restore: (id, snapshot) => {
+            const entry = nav.get(id);
+            if (entry === undefined || entry.kind !== snapshot.kind)
+                return false;
+            if (entry.kind === "patrol" && snapshot.kind === "patrol") {
+                entry.state = { ...snapshot.state };
+                return true;
+            }
+            if (entry.kind === "wander" && snapshot.kind === "wander") {
+                entry.origin = [...snapshot.origin];
+                entry.target = snapshot.target === null ? null : [...snapshot.target];
+                return true;
+            }
+            return false;
+        },
+        inspect: (id) => {
+            const entry = nav.get(id);
+            if (entry === undefined)
+                return null;
+            return { id, kind: entry.kind, status: entry.status, reason: entry.reason };
+        },
+        list: () => {
+            const out = [];
+            for (const [id, entry] of nav)
+                out.push({ id, kind: entry.kind, status: entry.status, reason: entry.reason });
+            return out;
+        },
+    };
+}

package/dist/scene/behaviors.d.ts

@@ -1,5 +1,5 @@
 import { type ProximityPrompt } from "../interaction/proximityPrompt.js";
-import type { Waypoint } from "../nav/pathFollow.js";
+import type { PathProgress, Waypoint } from "../nav/pathFollow.js";
 export interface WanderBehavior {
     kind: "wander";
     radius: number;
@@ -9,6 +9,16 @@ export interface PatrolBehavior {
     waypoints: readonly Waypoint[];
     speed: number;
     loop: boolean;
+    /**
+     * Optional initial progress the follower is seeded at instead of waypoint zero — lets a fleet of
+     * route followers start at distributed phases. Round-trips through the behavior lifecycle seek/serialize.
+     */
+    startProgress?: PathProgress;
+    /**
+     * Sample world ground height for the pose Y each tick, so a route authored in the XZ plane rides
+     * uneven terrain. Default false (waypoint Y is used verbatim).
+     */
+    groundClamp?: boolean;
 }
 export interface PromptableBehavior {
     kind: "promptable";
@@ -21,10 +31,12 @@ export type BehaviorDescriptor = WanderBehavior | PatrolBehavior | PromptableBeh
 export declare function wander({ radius }: {
     radius: number;
 }): WanderBehavior;
-export declare function patrol({ waypoints, speed, loop, }: {
+export declare function patrol({ waypoints, speed, loop, startProgress, groundClamp, }: {
     waypoints: readonly Waypoint[];
     speed: number;
     loop?: boolean;
+    startProgress?: PathProgress;
+    groundClamp?: boolean;
 }): PatrolBehavior;
 export declare function promptable(prompt: ProximityPrompt): PromptableBehavior;
 export declare function talkable(dialogueId: string): PromptableBehavior;

package/dist/scene/behaviors.js

@@ -2,8 +2,13 @@ import { command, keybind, proximityPrompt, } from "../interaction/proximityProm
 export function wander({ radius }) {
     return { kind: "wander", radius };
 }
-export function patrol({ waypoints, speed, loop = true, }) {
-    return { kind: "patrol", waypoints, speed, loop };
+export function patrol({ waypoints, speed, loop = true, startProgress, groundClamp, }) {
+    const behavior = { kind: "patrol", waypoints, speed, loop };
+    if (startProgress !== undefined)
+        behavior.startProgress = startProgress;
+    if (groundClamp !== undefined)
+        behavior.groundClamp = groundClamp;
+    return behavior;
 }
 export function promptable(prompt) {
     return { kind: "promptable", prompt };

package/dist/scene/bodyBind.d.ts

@@ -0,0 +1,60 @@
+import type { EntityRole, EntityUpdatePatch, SpawnPositionInput } from "./entityStore.js";
+/**
+ * One sim body's per-tick pose, as the game's simulation computed it — the shape a game already builds
+ * to hand to `setPose`, just declared instead of imperatively pushed. `kind` is the entity catalog name
+ * used only the first time `id` is seen (a respawn/despawn never re-reads it).
+ */
+export interface BodySnapshot {
+    id: string;
+    kind: string;
+    position: SpawnPositionInput;
+    rotationY?: number;
+    rotationX?: number;
+    rotationZ?: number;
+    role?: EntityRole;
+    meta?: unknown;
+}
+/** The options a {@link BodyBindDeps.spawn} call receives for an id seen for the first time. */
+export interface BodyBindSpawnInput {
+    id: string;
+    position: SpawnPositionInput;
+    rotationY?: number;
+    rotationX?: number;
+    rotationZ?: number;
+    role?: EntityRole;
+    meta?: unknown;
+}
+/** The pose a {@link BodyBindDeps.setPose} call receives for an id already bound. */
+export interface BodyBindPose {
+    position: SpawnPositionInput;
+    rotationY?: number;
+    rotationX?: number;
+    rotationZ?: number;
+    dt?: number;
+}
+/** Structural entity-store seam a {@link BodyBind} mirrors onto — satisfied by `ctx.scene.entity` itself. */
+export interface BodyBindDeps {
+    has(id: string): boolean;
+    spawn(kind: string, options: BodyBindSpawnInput): string;
+    despawn(id: string): boolean;
+    setPose(id: string, pose: BodyBindPose): boolean;
+    update(id: string, patch: EntityUpdatePatch): boolean;
+}
+/** The lazily-keyed handle `ctx.scene.entity.bind(key)` returns. */
+export interface BodyBind {
+    /**
+     * Mirror this tick's `bodies` onto scene entities: spawns an id seen for the first time (catalog
+     * `kind` from its snapshot), poses one already bound, despawns one this bind previously spawned that
+     * is now absent from `bodies`. `dt` (when given) derives `velocity` the same as a direct `setPose`.
+     */
+    sync(bodies: Iterable<BodySnapshot>, dt?: number): void;
+    /** Ids this bind currently considers itself responsible for (spawned by, and not yet despawned by, `sync`). */
+    boundIds(): ReadonlySet<string>;
+}
+/**
+ * Mirror a sim's body snapshots onto scene entities each tick — spawn on first sight, pose while bound,
+ * despawn on drop — replacing a per-body `setPose` loop plus its `despawn`/`spawn` respawn dance.
+ *
+ * @capability body-bind mirror sim-body snapshots onto scene entities each tick, no per-body setPose
+ */
+export declare function createBodyBind(deps: BodyBindDeps): BodyBind;

package/dist/scene/bodyBind.js

@@ -0,0 +1,51 @@
+/**
+ * Mirror a sim's body snapshots onto scene entities each tick — spawn on first sight, pose while bound,
+ * despawn on drop — replacing a per-body `setPose` loop plus its `despawn`/`spawn` respawn dance.
+ *
+ * @capability body-bind mirror sim-body snapshots onto scene entities each tick, no per-body setPose
+ */
+export function createBodyBind(deps) {
+    const bound = new Set();
+    return {
+        sync(bodies, dt) {
+            const seen = new Set();
+            for (const body of bodies) {
+                seen.add(body.id);
+                const alreadyBound = bound.has(body.id);
+                if (!alreadyBound && !deps.has(body.id)) {
+                    deps.spawn(body.kind, {
+                        id: body.id,
+                        position: body.position,
+                        rotationY: body.rotationY,
+                        rotationX: body.rotationX,
+                        rotationZ: body.rotationZ,
+                        role: body.role,
+                        meta: body.meta,
+                    });
+                }
+                else {
+                    deps.setPose(body.id, {
+                        position: body.position,
+                        rotationY: body.rotationY,
+                        rotationX: body.rotationX,
+                        rotationZ: body.rotationZ,
+                        ...(dt === undefined ? {} : { dt }),
+                    });
+                    if (body.role !== undefined || body.meta !== undefined) {
+                        deps.update(body.id, { role: body.role, meta: body.meta });
+                    }
+                }
+                bound.add(body.id);
+            }
+            for (const id of bound) {
+                if (seen.has(id))
+                    continue;
+                deps.despawn(id);
+                bound.delete(id);
+            }
+        },
+        boundIds() {
+            return bound;
+        },
+    };
+}

package/dist/scene/builtinSceneKinds.d.ts

@@ -0,0 +1,5 @@
+import { type ParamSchema } from "./sceneKinds.js";
+/** The scatter/foliage region schema — the fields the inspector exposed as hand-written `ScatterFields`. */
+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

@@ -0,0 +1,67 @@
+/**
+ * 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), 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 = {
+    fields: [
+        { 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 },
+        { type: "number", key: "maxScale", label: "max scale", step: 0.05, default: 1.3, min: 0 },
+        { type: "number", key: "maxSlope", label: "max slope", step: 0.05, default: 0, min: 0 },
+        { 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: "" },
+    ],
+};
+let registered = false;
+/** Idempotently registers the engine's built-in environment scene kinds + generators. @internal */
+export function registerBuiltinSceneKinds() {
+    if (registered)
+        return;
+    registered = true;
+    registerSceneKind({
+        kind: SCATTER_PATH_KIND,
+        target: "path",
+        label: "Foliage / scatter",
+        pathShape: "area",
+        addCategory: "Studios",
+        accent: "#34d399",
+        schema: SCATTER_SCHEMA,
+        note: (object, params) => {
+            const points = object.points ?? [];
+            if (points.length < 3)
+                return "Draw at least 3 points to close the region.";
+            let area = 0;
+            for (let i = 0, j = points.length - 1; i < points.length; j = i, i += 1) {
+                area += points[j].x * points[i].z - points[i].x * points[j].z;
+            }
+            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²`;
+        },
+    });
+    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;
@@ -37,13 +67,53 @@ export declare const DEFAULT_OBJECT_HALF_EXTENTS: EntityPosition;
 export declare const DEFAULT_ENTITY_BODY_HALF_EXTENTS: EntityPosition;
 /** Entity-local center of the default body hitbox (half its height above the feet). */
 export declare const DEFAULT_ENTITY_BODY_OFFSET: EntityPosition;
+/** @internal */
 export declare function defaultEntityColliders(): EntityColliderSet;
+/** Humanoid damage box uniformly scaled to match a visually scaled mesh, kept grounded (offset stays half its height). At scale 1 this equals `defaultEntityColliders()`.
+ * @internal
+ */
+export declare function scaledEntityColliders(scale: number): EntityColliderSet;
+/** @internal */
 export declare function defaultObjectColliders(halfExtents?: EntityPosition): EntityColliderSet;
-/** Blocking physical body derived from an object's rendered scale: a grounded box spanning the visual (base at y=0, matching the shell's fallback mesh). */
+/** Blocking physical body derived from an object's rendered scale: a grounded box spanning the visual (base at y=0, matching the shell's fallback mesh).
+ * @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 */
 export declare function worldOffset(local: EntityPosition | undefined, position: EntityPosition, rotationY: number): EntityPosition;
+/** @internal */
 export declare function colliderWorldCenter(collider: ResolvedCollider, position: EntityPosition, rotationY: number): EntityPosition;
+/** @internal */
 export declare function colliderBounds(collider: ResolvedCollider, position: EntityPosition, rotationY: number): {
     min: EntityPosition;
     max: EntityPosition;