@jgengine/core 0.10.0 → 0.12.0

package/dist/scene/colliders.js

@@ -1,9 +1,11 @@
+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). */
 export const DEFAULT_ENTITY_BODY_HALF_EXTENTS = [0.35, 0.9, 0.35];
 /** Entity-local center of the default body hitbox (half its height above the feet). */
 export const DEFAULT_ENTITY_BODY_OFFSET = [0, 0.9, 0];
+/** @internal */
 export function defaultEntityColliders() {
     return {
         hitboxes: [
@@ -21,6 +23,35 @@ export function defaultEntityColliders() {
         ],
     };
 }
+/** 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 function scaledEntityColliders(scale) {
+    return {
+        hitboxes: [
+            {
+                name: "body",
+                purpose: "damage",
+                shape: {
+                    kind: "aabb",
+                    halfExtents: [
+                        DEFAULT_ENTITY_BODY_HALF_EXTENTS[0] * scale,
+                        DEFAULT_ENTITY_BODY_HALF_EXTENTS[1] * scale,
+                        DEFAULT_ENTITY_BODY_HALF_EXTENTS[2] * scale,
+                    ],
+                    offset: [
+                        DEFAULT_ENTITY_BODY_OFFSET[0] * scale,
+                        DEFAULT_ENTITY_BODY_OFFSET[1] * scale,
+                        DEFAULT_ENTITY_BODY_OFFSET[2] * scale,
+                    ],
+                },
+                damageEligible: true,
+                blocks: false,
+            },
+        ],
+    };
+}
+/** @internal */
 export function defaultObjectColliders(halfExtents = DEFAULT_OBJECT_HALF_EXTENTS) {
     return {
         body: {
@@ -32,7 +63,9 @@ export function defaultObjectColliders(halfExtents = DEFAULT_OBJECT_HALF_EXTENTS
         },
     };
 }
-/** 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 function scaledObjectColliders(scale) {
     return {
         body: {
@@ -48,6 +81,114 @@ 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)
         return [];
@@ -71,6 +212,7 @@ function resolveOne(def) {
         blocks,
     };
 }
+/** @internal */
 export function worldOffset(local, position, rotationY) {
     if (local === undefined)
         return position;
@@ -81,9 +223,11 @@ export function worldOffset(local, position, rotationY) {
     const lz = local[2];
     return [position[0] + lx * cos + lz * sin, position[1] + ly, position[2] - lx * sin + lz * cos];
 }
+/** @internal */
 export function colliderWorldCenter(collider, position, rotationY) {
     return worldOffset(collider.shape.offset, position, rotationY);
 }
+/** @internal */
 export function colliderBounds(collider, position, rotationY) {
     const center = colliderWorldCenter(collider, position, rotationY);
     if (collider.shape.kind === "sphere") {

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;