@jgengine/core 0.11.0 → 0.13.0

package/dist/runtime/hostPolicy.js

@@ -0,0 +1,68 @@
+import { normalizeJoinCode } from "../multiplayer/matchmaking.js";
+/**
+ * True when a server's `visibility` should surface in public listings / browse results.
+ * @capability host-listing-filter exclude private sessions from public browse results
+ */
+export function isListablePublicly(visibility) {
+    return (visibility ?? "public") !== "private";
+}
+/**
+ * Private-server join-code gate. Existing members always pass; non-members must present a
+ * matching `joinCode` (loose-normalized via {@link normalizeJoinCode}). Callers still decide
+ * whether the server is private — this only answers the code/membership half.
+ * @capability host-join-code-gate membership-or-code gate for private hosted servers
+ */
+export function canJoinPrivateServer(args) {
+    if (args.isMember)
+        return true;
+    if (args.joinCode === undefined || args.suppliedCode === undefined)
+        return false;
+    return normalizeJoinCode(args.suppliedCode) === normalizeJoinCode(args.joinCode);
+}
+/** Whether `userId` is already on the server's member roster. */
+export function isServerMember(memberUserIds, userId) {
+    return memberUserIds.includes(userId);
+}
+/**
+ * True when the server has no free slots for a non-member. Existing members never count as
+ * "full" so rejoin/leave cycles keep working.
+ */
+export function isServerFull(memberUserIds, slotsPerServer, userId) {
+    return memberUserIds.length >= slotsPerServer && !memberUserIds.includes(userId);
+}
+/**
+ * Whether a private-visibility server blocks this join (non-member without a matching code).
+ * Public / undefined visibility never blocks.
+ */
+export function isPrivateJoinBlocked(args) {
+    if ((args.visibility ?? "public") !== "private")
+        return false;
+    return !canJoinPrivateServer({
+        isMember: isServerMember(args.memberUserIds, args.userId),
+        joinCode: args.joinCode,
+        suppliedCode: args.suppliedCode,
+    });
+}
+/** Roster after a successful join: unchanged when already a member, else appended. */
+export function withJoinedMember(memberUserIds, userId) {
+    return memberUserIds.includes(userId) ? [...memberUserIds] : [...memberUserIds, userId];
+}
+/** Roster after a leave: `userId` removed; order of remaining members preserved. */
+export function withoutMember(memberUserIds, userId) {
+    return memberUserIds.filter((id) => id !== userId);
+}
+/** Status after a leave: empty rooms reopen; non-empty rooms keep their current status. */
+export function statusAfterLeave(remainingMemberCount, currentStatus) {
+    return remainingMemberCount === 0 ? "open" : currentStatus;
+}
+/**
+ * Auto-match candidate when no `serverId` is supplied: already a member, or a public room with
+ * free capacity. Private rooms are never auto-picked (join-by-code / direct id only).
+ */
+export function isAutoJoinCandidate(args) {
+    if (isServerMember(args.memberUserIds, args.userId))
+        return true;
+    if (args.memberUserIds.length >= args.slotsPerServer)
+        return false;
+    return isListablePublicly(args.visibility);
+}

package/dist/runtime/hostedGameRunner.d.ts

@@ -1,7 +1,7 @@
 import type { CommandResult } from "../commands/commandRegistry.js";
 import type { GameDefinition, LoopPlayer } from "../game/defineGame.js";
 import type { ModelAssetRef } from "../scene/assetCatalog.js";
-import { type GameContext, type GameContextContent } from "./gameContext.js";
+import { type GameContext, type GameContextContent, type GameContextModels } from "./gameContext.js";
 import { type InputFrame } from "./inputSnapshot.js";
 import { type WorldDiff } from "./worldReplication.js";
 import type { SnapshotViewer, WorldSnapshot } from "./worldSnapshot.js";
@@ -21,6 +21,8 @@ export interface HostedGameRunnerOptions<TAssetRef extends ModelAssetRef, TMulti
      * snapshot overlays the world state it seeded. Omit for a long-lived stateful host (ws) that keeps one runner.
      */
     restore?: WorldSnapshot;
+    /** Render-model lookup for collider auto-fit — pass the same lookup the shell derives from `entityModels`/`objectModels` so host and clients resolve identical hitboxes. */
+    models?: GameContextModels;
 }
 /**
  * The GameContext-loop equivalent of the pure-reducer `createGameHost`: one authoritative `createGameContext`

package/dist/runtime/hostedGameRunner.js

@@ -16,6 +16,7 @@ export function createHostedGameRunner(options) {
         player: host ?? { userId: "host", isNew: true },
         ...(now === undefined ? {} : { now }),
         ...(definition.replication === undefined ? {} : { replication: definition.replication }),
+        ...(options.models === undefined ? {} : { models: options.models }),
     });
     const loop = definition.loop ?? {};
     const replicator = createWorldReplicator(() => ctx.snapshot(), {

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,13 +11,19 @@ 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;
+    /** 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/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,55 @@ 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;
+/**
+ * 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;
 /** @internal */
 export declare function resolveColliders(set: EntityColliderSet | null | undefined): ResolvedCollider[];
 /** @internal */