@forgeax/engine-picking 0.1.31 → 0.1.32

package/README.md

@@ -15,11 +15,16 @@ never the reverse.
   through the camera, walks every renderable archetype, ray-AABB tests each
   pickable mesh's world-space bounding box, and returns the nearest
   `PickHit { entity, point, distance }` (or `undefined` on a miss). AABB
-  granularity (Three.js `Raycaster`-aligned MVP; per-triangle precision is
-  `pickVertex`).
+  granularity is intentional; use `pickTriangle` when exact surface and
+  occlusion ordering are required.
 - **`viewportToWorld(world, cameraEntity, screenX, screenY, viewportWidth, viewportHeight)`**
   — exposes the same camera unprojection as a world-space `Ray` for cursor
   placement, gizmos, and custom plane/triangle queries.
+- **`pickTriangle`** — exact static CPU triangle query for a screen ray. It
+  transforms indexed or non-indexed triangle-list vertices into world space,
+  returns the nearest world point, distance, barycentric weights, entity,
+  triangle index, and optional Catalog GUID, or reports `unavailable` when
+  CPU geometry or the current skinned pose cannot be tested.
 - **`pickVertexOnEntity` / `pickVertex`** — per-triangle vertex-level queries
   (editor vertex-snapping workflow). Three-state static-dispatch overload:
   without options -> `VertexHit | undefined`; with `{ limit: N }` -> `VertexHit[]`
@@ -74,7 +79,7 @@ if (hit) {
 
 `PickHit = { entity: EntityHandle; point: Vec3Like; distance: number }`. No
 `face` / `uv` / `normal` — AABB picking has no triangle resolution, so those
-would be a lie (use `pickVertex` for per-triangle vertices). Both `perspective`
+would be a lie (use `pickTriangle` or `pickVertex` for precise geometry). Both `perspective`
 and `orthographic` camera projections are supported. Reads the resolved
 `GlobalTransform.world` mat4 directly (feat-20260601 D-3), so the camera + candidates
 must have propagated transforms for the current frame.
@@ -117,6 +122,23 @@ Only `triangle-list` submeshes participate; skinned meshes report
 > `GlobalTransform.world` column-major mat4 directly; they never re-propagate. The
 > contract is identical across `pick` and `pickVertex*`.
 
+### Exact triangle (`pickTriangle`)
+
+| Function | Signature | Return |
+|:--|:--|:--|
+| `pickTriangle` | `(world, cameraEntity, screenX, screenY, vpW, vpH, options?)` | `TrianglePickResult` |
+
+`TrianglePickResult` is a closed three-state result: `hit` contains the
+nearest `TriangleHit`; `miss` means every candidate was tested and no triangle
+intersects the ray; `unavailable` names intersecting entities whose CPU
+geometry, current skinned pose, or explicit instance transforms cannot be
+tested. For an entity carrying `Instances`, pass its renderer-owned
+`InstanceCollectionStore` as `options.instances`; a hit then includes the
+zero-based `instanceIndex`. The picker uses the store's non-consuming `peek`
+read, so inspection cannot consume a later render upload range. Pass
+`AssetRegistry.guidOf` as `assetGuidOf` when provenance is needed. The query
+does not mutate the World or own an asset registry.
+
 ### Tile-cell (`pickTile`)
 
 | Function | Signature | Return |
@@ -164,5 +186,6 @@ miss returns `undefined`).
 - `src/pick.ts` — `pick` + `PickHit`
 - `src/pick-vertex.ts` — `pickVertex` / `pickVertexOnEntity` + `VertexHit`
 - `src/pick-tile.ts` — `pickTile` + `PickTileHit` / `PickTileError`
+- `src/pick-triangle.ts` — exact triangle/occlusion query + unavailable state
 - `src/pick-errors.ts` — `PickError` / `PickErrorCode` (error SSOT)
 - `src/pick-core.ts` — shared camera->ray skeleton (internal)

package/dist/__tests__/pick-triangle.unit.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=pick-triangle.unit.test.d.ts.map

package/dist/__tests__/pick-triangle.unit.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pick-triangle.unit.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/pick-triangle.unit.test.ts"],"names":[],"mappings":""}

package/dist/index.d.ts

@@ -3,6 +3,7 @@ export { pick } from './pick';
 export type { PickErrorCode } from './pick-errors';
 export { PickError } from './pick-errors';
 export { type PickTileError, type PickTileHit, pickTile } from './pick-tile';
+export { pickTriangle, type TriangleHit, type TrianglePickOptions, type TrianglePickResult, type TrianglePickUnavailableReason, } from './pick-triangle';
 export type { VertexHit } from './pick-vertex';
 export { pickVertex, pickVertexOnEntity } from './pick-vertex';
 export { viewportToWorld } from './viewport-to-world';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AASA,YAAY,EAAE,OAAO,EAAE,MAAM,QAAQ,CAAC;AACtC,OAAO,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAC;AAG9B,YAAY,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AACnD,OAAO,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAE1C,OAAO,EAAE,KAAK,aAAa,EAAE,KAAK,WAAW,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAE7E,YAAY,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAC/C,OAAO,EAAE,UAAU,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AAC/D,OAAO,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AASA,YAAY,EAAE,OAAO,EAAE,MAAM,QAAQ,CAAC;AACtC,OAAO,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAC;AAG9B,YAAY,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AACnD,OAAO,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAE1C,OAAO,EAAE,KAAK,aAAa,EAAE,KAAK,WAAW,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAC7E,OAAO,EACL,YAAY,EACZ,KAAK,WAAW,EAChB,KAAK,mBAAmB,EACxB,KAAK,kBAAkB,EACvB,KAAK,6BAA6B,GACnC,MAAM,iBAAiB,CAAC;AAEzB,YAAY,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAC/C,OAAO,EAAE,UAAU,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AAC/D,OAAO,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC"}

package/dist/index.mjs

@@ -1,6 +1,6 @@
 import { resolveAssetHandle } from '@forgeax/engine-assets-runtime';
 import { vec2, box3, ray, vec3, mat4 } from '@forgeax/engine-math';
-import { MeshFilter, MeshRenderer, Camera, cameraProjectionFromF32 } from '@forgeax/engine-render';
+import { MeshFilter, MeshRenderer, Instances, Camera, cameraProjectionFromF32 } from '@forgeax/engine-render';
 import { Transform, GlobalTransform, ChildOf } from '@forgeax/engine-scene';
 import { toShared, err, ok } from '@forgeax/engine-types';
 import { Entity } from '@forgeax/engine-ecs';
@@ -171,6 +171,238 @@ function pickTile(world, tilemapEntity, worldX, worldY) {
   }
   return ok(null);
 }
+function narrowPosition(position) {
+  if (position instanceof Float32Array) return position;
+  if (position instanceof ArrayBuffer) return new Float32Array(position);
+  return void 0;
+}
+function worldAabbHit(screenRay, aabb, worldMatrix) {
+  if (aabb === void 0 || aabb[0] > aabb[3]) return true;
+  const corners = [
+    [aabb[0], aabb[1], aabb[2]],
+    [aabb[3], aabb[1], aabb[2]],
+    [aabb[0], aabb[4], aabb[2]],
+    [aabb[3], aabb[4], aabb[2]],
+    [aabb[0], aabb[1], aabb[5]],
+    [aabb[3], aabb[1], aabb[5]],
+    [aabb[0], aabb[4], aabb[5]],
+    [aabb[3], aabb[4], aabb[5]]
+  ];
+  const world = vec3.create();
+  let minX = Infinity;
+  let minY = Infinity;
+  let minZ = Infinity;
+  let maxX = -Infinity;
+  let maxY = -Infinity;
+  let maxZ = -Infinity;
+  for (const corner of corners) {
+    mat4.transformPoint(world, worldMatrix, corner);
+    minX = Math.min(minX, world[0]);
+    minY = Math.min(minY, world[1]);
+    minZ = Math.min(minZ, world[2]);
+    maxX = Math.max(maxX, world[0]);
+    maxY = Math.max(maxY, world[1]);
+    maxZ = Math.max(maxZ, world[2]);
+  }
+  return ray.rayAabbIntersects(screenRay, [minX, minY, minZ, maxX, maxY, maxZ]).hit;
+}
+function pointOnRay(screenRay, point) {
+  const dx = point[0] - screenRay[0];
+  const dy = point[1] - screenRay[1];
+  const dz = point[2] - screenRay[2];
+  return dx * screenRay[3] + dy * screenRay[4] + dz * screenRay[5];
+}
+function pickTriangle(world, cameraEntity, screenX, screenY, viewportWidth, viewportHeight, options = {}) {
+  const screen = computeScreenRay(
+    world,
+    cameraEntity,
+    screenX,
+    screenY,
+    viewportWidth,
+    viewportHeight
+  );
+  if (screen === void 0) return { status: "miss", precision: "triangle" };
+  const origin = screen.ray;
+  const query = world.query({
+    read: [Transform, GlobalTransform, MeshFilter, MeshRenderer],
+    optional: [Instances]
+  }).unwrap();
+  let best;
+  let unsupportedReason;
+  const unsupportedEntities = [];
+  for (const row of query) {
+    const rawHandle = Math.round(row.get(MeshFilter).assetHandle);
+    if (rawHandle === 0) continue;
+    const resolved = resolveAssetHandle(world, toShared(rawHandle));
+    if (!resolved.ok) continue;
+    const mesh = resolved.value;
+    const entity = row.entity;
+    const entityWorldMatrix = readWorldMatrix(world, entity);
+    if (entityWorldMatrix === void 0) continue;
+    const instancesData = row.get(Instances);
+    let instanceTransforms;
+    let instanceCount = 1;
+    if (instancesData !== void 0) {
+      if (options.instances === void 0) {
+        unsupportedReason ??= "instance-transforms-unavailable";
+        unsupportedEntities.push(entity);
+        continue;
+      }
+      const snapshot = options.instances.peek(instancesData.collectionId);
+      if (!snapshot.ok) {
+        unsupportedReason ??= "instance-transforms-unavailable";
+        unsupportedEntities.push(entity);
+        continue;
+      }
+      instanceTransforms = snapshot.value.transforms;
+      instanceCount = snapshot.value.count;
+    }
+    const positions = narrowPosition(mesh.attributes.position);
+    const skinned = mesh.attributes.skinIndex !== void 0 && mesh.attributes.skinWeight !== void 0;
+    if (skinned) {
+      let intersects = false;
+      for (let instanceIndex = 0; instanceIndex < instanceCount; instanceIndex += 1) {
+        const drawWorld = instanceTransforms === void 0 ? entityWorldMatrix : mat4.multiply(
+          mat4.create(),
+          entityWorldMatrix,
+          instanceTransforms.subarray(instanceIndex * 16, instanceIndex * 16 + 16)
+        );
+        if (worldAabbHit(origin, mesh.aabb, drawWorld)) {
+          intersects = true;
+          break;
+        }
+      }
+      if (!intersects) continue;
+      unsupportedReason ??= "skinned-pose-unavailable";
+      unsupportedEntities.push(entity);
+      continue;
+    }
+    if (positions === void 0 || positions.length < 3) {
+      let intersects = false;
+      for (let instanceIndex = 0; instanceIndex < instanceCount; instanceIndex += 1) {
+        const drawWorld = instanceTransforms === void 0 ? entityWorldMatrix : mat4.multiply(
+          mat4.create(),
+          entityWorldMatrix,
+          instanceTransforms.subarray(instanceIndex * 16, instanceIndex * 16 + 16)
+        );
+        if (worldAabbHit(origin, mesh.aabb, drawWorld)) {
+          intersects = true;
+          break;
+        }
+      }
+      if (!intersects) continue;
+      unsupportedReason ??= "cpu-geometry-unavailable";
+      unsupportedEntities.push(entity);
+      continue;
+    }
+    for (let instanceIndex = 0; instanceIndex < instanceCount; instanceIndex += 1) {
+      const drawWorld = instanceTransforms === void 0 ? entityWorldMatrix : mat4.multiply(
+        mat4.create(),
+        entityWorldMatrix,
+        instanceTransforms.subarray(instanceIndex * 16, instanceIndex * 16 + 16)
+      );
+      if (!worldAabbHit(origin, mesh.aabb, drawWorld)) continue;
+      const worldA = vec3.create();
+      const worldB = vec3.create();
+      const worldC = vec3.create();
+      const worldPoint = vec3.create();
+      let triangleIndex = 0;
+      const indices = mesh.indices;
+      const maxVertex = Math.floor(positions.length / 3) - 1;
+      const test = (i0, i1, i2, index) => {
+        if (i0 < 0 || i1 < 0 || i2 < 0 || i0 > maxVertex || i1 > maxVertex || i2 > maxVertex)
+          return;
+        const a = [
+          positions[i0 * 3],
+          positions[i0 * 3 + 1],
+          positions[i0 * 3 + 2]
+        ];
+        const b = [
+          positions[i1 * 3],
+          positions[i1 * 3 + 1],
+          positions[i1 * 3 + 2]
+        ];
+        const c = [
+          positions[i2 * 3],
+          positions[i2 * 3 + 1],
+          positions[i2 * 3 + 2]
+        ];
+        mat4.transformPoint(worldA, drawWorld, a);
+        mat4.transformPoint(worldB, drawWorld, b);
+        mat4.transformPoint(worldC, drawWorld, c);
+        const hit = ray.rayTriangleIntersects(origin, worldA, worldB, worldC);
+        if (!hit.hit) return;
+        worldPoint[0] = origin[0] + origin[3] * hit.t;
+        worldPoint[1] = origin[1] + origin[4] * hit.t;
+        worldPoint[2] = origin[2] + origin[5] * hit.t;
+        const distance = pointOnRay(origin, worldPoint);
+        if (!Number.isFinite(distance) || distance < 0 || best !== void 0 && distance >= best.distance)
+          return;
+        const assetGuid = options.assetGuidOf?.(mesh);
+        best = {
+          entity,
+          triangleIndex: index,
+          point: [worldPoint[0], worldPoint[1], worldPoint[2]],
+          distance,
+          barycentric: [1 - hit.u - hit.v, hit.u, hit.v],
+          ...assetGuid === void 0 ? {} : { assetGuid },
+          ...instanceTransforms === void 0 ? {} : { instanceIndex },
+          precision: "triangle"
+        };
+      };
+      for (const submesh of mesh.submeshes) {
+        if (submesh.topology !== "triangle-list" && submesh.topology !== "triangle-strip") continue;
+        const strip = submesh.topology === "triangle-strip";
+        if (indices !== void 0 && indices.length > 0 && submesh.indexCount > 0) {
+          const count = strip ? Math.max(0, submesh.indexCount - 2) : Math.floor(submesh.indexCount / 3);
+          for (let localTriangle = 0; localTriangle < count; localTriangle += 1) {
+            if (strip) {
+              const base = submesh.indexOffset + localTriangle;
+              const i0 = indices[base];
+              const i1 = indices[base + 1];
+              const i2 = indices[base + 2];
+              if ((localTriangle & 1) === 0) test(i0, i1, i2, triangleIndex);
+              else test(i2, i1, i0, triangleIndex);
+            } else {
+              const base = submesh.indexOffset + localTriangle * 3;
+              test(
+                indices[base],
+                indices[base + 1],
+                indices[base + 2],
+                triangleIndex
+              );
+            }
+            triangleIndex += 1;
+          }
+        } else {
+          const count = strip ? Math.max(0, submesh.vertexCount - 2) : Math.floor(submesh.vertexCount / 3);
+          for (let localTriangle = 0; localTriangle < count; localTriangle += 1) {
+            if (strip) {
+              const i0 = localTriangle;
+              const i1 = localTriangle + 1;
+              const i2 = localTriangle + 2;
+              if ((localTriangle & 1) === 0) test(i0, i1, i2, triangleIndex);
+              else test(i2, i1, i0, triangleIndex);
+            } else {
+              const base = localTriangle * 3;
+              test(base, base + 1, base + 2, triangleIndex);
+            }
+            triangleIndex += 1;
+          }
+        }
+      }
+    }
+  }
+  if (unsupportedReason !== void 0) {
+    return {
+      status: "unavailable",
+      precision: "unavailable",
+      reason: unsupportedReason,
+      entities: unsupportedEntities
+    };
+  }
+  return best === void 0 ? { status: "miss", precision: "triangle" } : { status: "hit", hit: best };
+}
 var _scratchVec2 = vec2.create();
 function pointToRayDist(px, py, pz, ox, oy, oz, dx, dy, dz) {
   const ex = px - ox;
@@ -221,7 +453,7 @@ function rayHitsWorldAabb(r, localAabb, worldMat) {
   );
   return aabbResult.hit;
 }
-function narrowPosition(positionAttr) {
+function narrowPosition2(positionAttr) {
   if (positionAttr instanceof Float32Array) {
     return positionAttr;
   }
@@ -263,7 +495,7 @@ function collectVertexHits(world, cameraEntity, screenX, screenY, viewportWidth,
     return [];
   }
   const mesh = meshRes.value;
-  const positions = narrowPosition(mesh.attributes.position);
+  const positions = narrowPosition2(mesh.attributes.position);
   if (positions === void 0 || positions.length < 3) {
     return [];
   }
@@ -292,12 +524,13 @@ function collectVertexHits(world, cameraEntity, screenX, screenY, viewportWidth,
     const cx = positions[i2 * 3 + 0];
     const cy = positions[i2 * 3 + 1];
     const cz = positions[i2 * 3 + 2];
-    const triResult = ray.rayTriangleIntersects(
-      r,
-      [ax, ay, az],
-      [bx, by, bz],
-      [cx, cy, cz]
-    );
+    const worldA = vec3.create();
+    const worldB = vec3.create();
+    const worldC = vec3.create();
+    mat4.transformPoint(worldA, entityWMLike, [ax, ay, az]);
+    mat4.transformPoint(worldB, entityWMLike, [bx, by, bz]);
+    mat4.transformPoint(worldC, entityWMLike, [cx, cy, cz]);
+    const triResult = ray.rayTriangleIntersects(r, worldA, worldB, worldC);
     if (!triResult.hit) return;
     for (const [vi, lx, ly, lz] of [
       [i0, ax, ay, az],
@@ -306,8 +539,7 @@ function collectVertexHits(world, cameraEntity, screenX, screenY, viewportWidth,
     ]) {
       if (Number.isNaN(lx) || Number.isNaN(ly) || Number.isNaN(lz)) continue;
       if (!Number.isFinite(lx) || !Number.isFinite(ly) || !Number.isFinite(lz)) continue;
-      const worldVec = vec3.create();
-      mat4.transformPoint(worldVec, entityWMLike, [lx, ly, lz]);
+      const worldVec = vi === i0 ? worldA : vi === i1 ? worldB : worldC;
       const wx = worldVec[0];
       const wy = worldVec[1];
       const wz = worldVec[2];
@@ -435,6 +667,6 @@ function viewportToWorld(world, cameraEntity, screenX, screenY, viewportWidth, v
   return computeScreenRay(world, cameraEntity, screenX, screenY, viewportWidth, viewportHeight)?.ray;
 }
 
-export { PickError, pick, pickTile, pickVertex, pickVertexOnEntity, viewportToWorld };
+export { PickError, pick, pickTile, pickTriangle, pickVertex, pickVertexOnEntity, viewportToWorld };
 //# sourceMappingURL=index.mjs.map
 //# sourceMappingURL=index.mjs.map