@forgeax/engine-picking 0.1.30 → 0.1.32

package/src/__tests__/pick-triangle.unit.test.ts

@@ -0,0 +1,292 @@
+import { AssetRegistry } from '@forgeax/engine-assets-runtime';
+import { World } from '@forgeax/engine-ecs';
+import { AssetGuid } from '@forgeax/engine-pack/guid';
+import {
+  CAMERA_PROJECTION_PERSPECTIVE,
+  Camera,
+  InstanceCollectionStore,
+  Instances,
+  MeshFilter,
+  MeshRenderer,
+} from '@forgeax/engine-render';
+import { propagateTransforms, Transform } from '@forgeax/engine-scene';
+import type { Handle, MeshAsset } from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+import { pickTriangle, type TrianglePickOptions, type TrianglePickResult } from '../pick-triangle';
+import { makeMockShaderRegistry } from './helpers/mock-shader-registry';
+
+const VP = 600;
+
+function registerMesh(
+  world: World,
+  assets: AssetRegistry,
+  positions: readonly number[],
+  indices?: readonly number[],
+  topology: 'triangle-list' | 'triangle-strip' = 'triangle-list',
+) {
+  const position = new Float32Array(positions);
+  const result = assets.catalog<MeshAsset>(AssetGuid.format(AssetGuid.random()), {
+    kind: 'mesh',
+    vertices: position,
+    ...(indices === undefined ? {} : { indices: new Uint16Array(indices) }),
+    attributes: { position },
+    submeshes: [
+      {
+        indexOffset: 0,
+        indexCount: indices?.length ?? 0,
+        vertexCount: Math.floor(position.length / 3),
+        topology,
+        materialSlot: 0,
+      },
+    ],
+    materialSlots: [{ slotName: 'Default' }],
+  });
+  if (!result.ok) throw result.error;
+  return world.allocSharedRef('MeshAsset', result.value) as Handle<'MeshAsset', 'shared'>;
+}
+
+function makeScene() {
+  const world = new World();
+  const assets = new AssetRegistry(makeMockShaderRegistry());
+  const instanceCollections = new InstanceCollectionStore();
+  const material = assets.catalog(AssetGuid.format(AssetGuid.random()), {
+    kind: 'material',
+    passes: [
+      {
+        name: 'Forward',
+        program: { module: 'forgeax::default-unlit' },
+        renderState: { tags: { LightMode: 'Forward' }, queue: 2000 },
+      },
+    ],
+    values: { baseColor: [1, 1, 1] },
+  });
+  if (!material.ok) throw material.error;
+  const materialHandle = world.allocSharedRef('MaterialAsset', material.value);
+  const camera = world
+    .spawn(
+      { component: Transform, data: { pos: [0, 0, 5], quat: [0, 0, 0, 1], scale: [1, 1, 1] } },
+      {
+        component: Camera,
+        data: {
+          fov: Math.PI / 4,
+          aspect: 1,
+          near: 0.1,
+          far: 100,
+          projection: CAMERA_PROJECTION_PERSPECTIVE,
+          left: -1,
+          right: 1,
+          top: 1,
+          bottom: -1,
+        },
+      },
+    )
+    .unwrap();
+  return { world, assets, materialHandle, camera, instanceCollections };
+}
+
+function spawnMesh(
+  scene: ReturnType<typeof makeScene>,
+  mesh: Handle<'MeshAsset', 'shared'>,
+  transform: { pos?: [number, number, number]; scale?: [number, number, number] } = {},
+) {
+  return scene.world
+    .spawn(
+      {
+        component: Transform,
+        data: {
+          pos: transform.pos ?? [0, 0, 0],
+          quat: [0, 0, 0, 1],
+          scale: transform.scale ?? [1, 1, 1],
+        },
+      },
+      { component: MeshFilter, data: { assetHandle: mesh } },
+      { component: MeshRenderer, data: { materials: [scene.materialHandle] } },
+    )
+    .unwrap();
+}
+
+function spawnInstancedMesh(
+  scene: ReturnType<typeof makeScene>,
+  mesh: Handle<'MeshAsset', 'shared'>,
+  translations: readonly number[],
+) {
+  const transforms = new Float32Array(translations.length * 16);
+  for (let index = 0; index < translations.length; index += 1) {
+    const offset = index * 16;
+    transforms[offset] = 1;
+    transforms[offset + 5] = 1;
+    transforms[offset + 10] = 1;
+    transforms[offset + 15] = 1;
+    transforms[offset + 12] = translations[index] as number;
+  }
+  const collection = scene.instanceCollections.create({ transforms }).unwrap();
+  return scene.world
+    .spawn(
+      {
+        component: Transform,
+        data: { pos: [0, 0, 0], quat: [0, 0, 0, 1], scale: [1, 1, 1] },
+      },
+      { component: MeshFilter, data: { assetHandle: mesh } },
+      { component: MeshRenderer, data: { materials: [scene.materialHandle] } },
+      { component: Instances, data: { collectionId: collection.collectionId } },
+    )
+    .unwrap();
+}
+
+function unsupportedSkinnedMesh(scene: ReturnType<typeof makeScene>) {
+  const mesh: MeshAsset = {
+    kind: 'mesh',
+    vertices: new Float32Array([-1, -1, 0, 1, -1, 0, 0, 1, 0]),
+    attributes: {
+      position: new Float32Array([-1, -1, 0, 1, -1, 0, 0, 1, 0]),
+      skinIndex: new Uint16Array(12),
+      skinWeight: new Float32Array(12),
+    },
+    aabb: new Float32Array([-1, -1, 0, 1, 1, 0]),
+    submeshes: [
+      { indexOffset: 0, indexCount: 0, vertexCount: 3, topology: 'triangle-list', materialSlot: 0 },
+    ],
+    materialSlots: [{ slotName: 'Default' }],
+  };
+  return scene.world.allocSharedRef('MeshAsset', mesh) as Handle<'MeshAsset', 'shared'>;
+}
+
+function query(
+  scene: ReturnType<typeof makeScene>,
+  x = VP / 2,
+  y = VP / 2,
+  options: TrianglePickOptions = {},
+): TrianglePickResult {
+  propagateTransforms(scene.world);
+  return pickTriangle(scene.world, scene.camera, x, y, VP, VP, options);
+}
+
+describe('pickTriangle', () => {
+  it('returns the nearest exact hit and barycentric point', () => {
+    const scene = makeScene();
+    const near = registerMesh(scene.world, scene.assets, [-1, -1, 0, 1, -1, 0, 0, 1, 0], [0, 1, 2]);
+    const far = registerMesh(
+      scene.world,
+      scene.assets,
+      [-1, -1, -2, 1, -1, -2, 0, 1, -2],
+      [0, 1, 2],
+    );
+    const nearEntity = spawnMesh(scene, near);
+    spawnMesh(scene, far);
+
+    const result = query(scene);
+    expect(result.status).toBe('hit');
+    if (result.status !== 'hit') return;
+    expect(result.hit.entity).toBe(nearEntity);
+    expect(result.hit.point[2]).toBeCloseTo(0, 4);
+    expect(result.hit.distance).toBeCloseTo(4.9, 2);
+    expect(result.hit.barycentric.reduce((sum, value) => sum + value, 0)).toBeCloseTo(1, 6);
+    expect(result.hit.precision).toBe('triangle');
+  });
+
+  it('uses transformed world vertices, so a wall opening reaches the rear sign', () => {
+    const scene = makeScene();
+    // Four bars surround the center opening. Their combined AABB covers the
+    // whole wall, but no triangle occupies the center ray.
+    const wallPositions = [
+      -1, 0.5, 0, 1, 0.5, 0, 1, 1, 0, -1, 0.5, 0, 1, 1, 0, -1, 1, 0, -1, -1, 0, 1, -1, 0, 1, -0.5,
+      0, -1, -1, 0, 1, -0.5, 0, -1, -0.5, 0, -1, -0.5, 0, -0.5, -0.5, 0, -0.5, 0.5, 0, -1, -0.5, 0,
+      -0.5, 0.5, 0, -1, 0.5, 0, 0.5, -0.5, 0, 1, -0.5, 0, 1, 0.5, 0, 0.5, -0.5, 0, 1, 0.5, 0, 0.5,
+      0.5, 0,
+    ];
+    const wall = registerMesh(scene.world, scene.assets, wallPositions);
+    const sign = registerMesh(
+      scene.world,
+      scene.assets,
+      [-0.5, -0.5, -2, 0.5, -0.5, -2, 0.5, 0.5, -2, -0.5, 0.5, -2],
+    );
+    const wallEntity = spawnMesh(scene, wall);
+    const signEntity = spawnMesh(scene, sign);
+
+    const result = query(scene);
+    expect(result.status).toBe('hit');
+    if (result.status !== 'hit') return;
+    expect(result.hit.entity).toBe(signEntity);
+    expect(result.hit.entity).not.toBe(wallEntity);
+  });
+
+  it('handles non-uniform transformed instances and reports unavailable CPU/skinned data', () => {
+    const scene = makeScene();
+    const mesh = registerMesh(
+      scene.world,
+      scene.assets,
+      [-0.5, -0.5, 0, 0.5, -0.5, 0, 0, 0.5, 0],
+      [0, 1, 2],
+    );
+    const entity = spawnMesh(scene, mesh, { pos: [0, 0, 0], scale: [2, 3, 1] });
+    const transformed = query(scene);
+    expect(transformed.status).toBe('hit');
+    if (transformed.status === 'hit') expect(transformed.hit.entity).toBe(entity);
+
+    const unsupported = unsupportedSkinnedMesh(scene);
+    spawnMesh(scene, unsupported);
+    const result = query(scene);
+    expect(result.status).toBe('unavailable');
+  });
+
+  it('resolves explicit Instances matrices and identifies the hit ordinal', () => {
+    const scene = makeScene();
+    const mesh = registerMesh(
+      scene.world,
+      scene.assets,
+      [-0.5, -0.5, 0, 0.5, -0.5, 0, 0, 0.5, 0],
+      [0, 1, 2],
+    );
+    const entity = spawnInstancedMesh(scene, mesh, [5, 0]);
+
+    const result = query(scene, VP / 2, VP / 2, { instances: scene.instanceCollections });
+    expect(result.status).toBe('hit');
+    if (result.status !== 'hit') return;
+    expect(result.hit.entity).toBe(entity);
+    expect(result.hit.instanceIndex).toBe(1);
+  });
+
+  it('fails closed when an explicit Instances resolver is absent', () => {
+    const scene = makeScene();
+    const mesh = registerMesh(
+      scene.world,
+      scene.assets,
+      [-0.5, -0.5, 0, 0.5, -0.5, 0, 0, 0.5, 0],
+      [0, 1, 2],
+    );
+    spawnInstancedMesh(scene, mesh, [0]);
+
+    expect(query(scene).status).toBe('unavailable');
+    const result = query(scene);
+    expect(result.status).toBe('unavailable');
+    if (result.status === 'unavailable') {
+      expect(result.reason).toBe('instance-transforms-unavailable');
+    }
+  });
+
+  it('returns a miss for an indexed/non-indexed mesh outside the ray', () => {
+    const scene = makeScene();
+    const mesh = registerMesh(scene.world, scene.assets, [-1, -1, 0, 1, -1, 0, 0, 1, 0]);
+    spawnMesh(scene, mesh, { pos: [10, 0, 0] });
+    expect(query(scene).status).toBe('miss');
+  });
+
+  it('intersects indexed triangle strips with alternating winding', () => {
+    const scene = makeScene();
+    const positions = [-1, -1, 0, 1, -1, 0, -1, 1, 0, 1, 1, 0];
+    const indexed = registerMesh(
+      scene.world,
+      scene.assets,
+      positions,
+      [0, 1, 2, 3],
+      'triangle-strip',
+    );
+    const indexedEntity = spawnMesh(scene, indexed);
+
+    const result = query(scene);
+    expect(result.status).toBe('hit');
+    if (result.status !== 'hit') return;
+    expect(result.hit.entity).toBe(indexedEntity);
+    expect(result.hit.triangleIndex).toBe(0);
+  });
+});

package/src/index.ts

@@ -15,6 +15,13 @@ export type { PickErrorCode } from './pick-errors';
 export { PickError } from './pick-errors';
 // --- tile-cell pick (Tilemap query) ---
 export { type PickTileError, type PickTileHit, pickTile } from './pick-tile';
+export {
+  pickTriangle,
+  type TriangleHit,
+  type TrianglePickOptions,
+  type TrianglePickResult,
+  type TrianglePickUnavailableReason,
+} from './pick-triangle';
 // --- vertex-level pick (per-entity + full-scene) ---
 export type { VertexHit } from './pick-vertex';
 export { pickVertex, pickVertexOnEntity } from './pick-vertex';

package/src/pick-triangle.ts

@@ -0,0 +1,347 @@
+// pick-triangle.ts — precise screen ray / triangle query.
+//
+// This is the precise companion to pick()'s inexpensive world-AABB query. CPU
+// triangle vertices are transformed into world space before testing the shared
+// world ray. That keeps non-uniformly transformed instances and nearest-
+// occluder ordering correct.
+
+import { resolveAssetHandle } from '@forgeax/engine-assets-runtime';
+import type { EntityHandle, World } from '@forgeax/engine-ecs';
+import { mat4, ray, type Vec3Like, vec3 } from '@forgeax/engine-math';
+import type { InstanceCollectionId, InstanceCollectionStore } from '@forgeax/engine-render';
+import { Instances, MeshFilter, MeshRenderer } from '@forgeax/engine-render';
+import { GlobalTransform, Transform } from '@forgeax/engine-scene';
+import type { MeshAsset } from '@forgeax/engine-types';
+import { toShared } from '@forgeax/engine-types';
+import { computeScreenRay, readWorldMatrix } from './pick-core';
+
+export interface TriangleHit {
+  readonly entity: EntityHandle;
+  /** Zero-based triangle index across supported triangle submeshes. */
+  readonly triangleIndex: number;
+  /** Exact world-space intersection point. */
+  readonly point: Vec3Like;
+  /** Distance from the screen ray origin in world units. */
+  readonly distance: number;
+  /** Barycentric weights for the triangle's first, second, and third vertices. */
+  readonly barycentric: readonly [number, number, number];
+  /** Present when the caller supplied the registry's payload identity resolver. */
+  readonly assetGuid?: string;
+  /** Zero-based explicit instance ordinal when the entity owns Instances. */
+  readonly instanceIndex?: number;
+  readonly precision: 'triangle';
+}
+
+export type TrianglePickUnavailableReason =
+  | 'cpu-geometry-unavailable'
+  | 'skinned-pose-unavailable'
+  | 'instance-transforms-unavailable';
+
+export type TrianglePickResult =
+  | { readonly status: 'hit'; readonly hit: TriangleHit }
+  | { readonly status: 'miss'; readonly precision: 'triangle' }
+  | {
+      readonly status: 'unavailable';
+      readonly precision: 'unavailable';
+      readonly reason: TrianglePickUnavailableReason;
+      readonly entities: readonly EntityHandle[];
+    };
+
+export interface TrianglePickOptions {
+  /** Resolve a loaded MeshAsset payload to its existing Catalog GUID. */
+  readonly assetGuidOf?: (asset: MeshAsset) => string | undefined;
+  /** Read explicit instance matrices without advancing the renderer upload cursor. */
+  readonly instances?: Pick<InstanceCollectionStore, 'peek'>;
+}
+
+function narrowPosition(position: MeshAsset['attributes']['position']): Float32Array | undefined {
+  if (position instanceof Float32Array) return position;
+  if (position instanceof ArrayBuffer) return new Float32Array(position);
+  return undefined;
+}
+
+function worldAabbHit(
+  screenRay: ray.Ray,
+  aabb: MeshAsset['aabb'],
+  worldMatrix: mat4.Mat4Like,
+): boolean {
+  if (aabb === undefined || (aabb[0] as number) > (aabb[3] as number)) return true;
+  const corners: readonly Vec3Like[] = [
+    [aabb[0] as number, aabb[1] as number, aabb[2] as number],
+    [aabb[3] as number, aabb[1] as number, aabb[2] as number],
+    [aabb[0] as number, aabb[4] as number, aabb[2] as number],
+    [aabb[3] as number, aabb[4] as number, aabb[2] as number],
+    [aabb[0] as number, aabb[1] as number, aabb[5] as number],
+    [aabb[3] as number, aabb[1] as number, aabb[5] as number],
+    [aabb[0] as number, aabb[4] as number, aabb[5] as number],
+    [aabb[3] as number, aabb[4] as number, aabb[5] as number],
+  ];
+  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] as number);
+    minY = Math.min(minY, world[1] as number);
+    minZ = Math.min(minZ, world[2] as number);
+    maxX = Math.max(maxX, world[0] as number);
+    maxY = Math.max(maxY, world[1] as number);
+    maxZ = Math.max(maxZ, world[2] as number);
+  }
+  return ray.rayAabbIntersects(screenRay, [minX, minY, minZ, maxX, maxY, maxZ]).hit;
+}
+
+function pointOnRay(screenRay: ray.Ray, point: Vec3Like): number {
+  const dx = (point[0] as number) - (screenRay[0] as number);
+  const dy = (point[1] as number) - (screenRay[1] as number);
+  const dz = (point[2] as number) - (screenRay[2] as number);
+  return (
+    dx * (screenRay[3] as number) + dy * (screenRay[4] as number) + dz * (screenRay[5] as number)
+  );
+}
+
+/**
+ * Return the nearest exact triangle hit for a viewport ray.
+ *
+ * A result of `unavailable` is deliberate: a skinned mesh or a mesh without
+ * CPU position data cannot make a truthful nearest-occluder claim. The query
+ * only reports that state when such an entity's broad-phase AABB intersects
+ * the ray, so unrelated unsupported meshes do not hide a valid hit.
+ */
+export function pickTriangle(
+  world: World,
+  cameraEntity: EntityHandle,
+  screenX: number,
+  screenY: number,
+  viewportWidth: number,
+  viewportHeight: number,
+  options: TrianglePickOptions = {},
+): TrianglePickResult {
+  const screen = computeScreenRay(
+    world,
+    cameraEntity,
+    screenX,
+    screenY,
+    viewportWidth,
+    viewportHeight,
+  );
+  if (screen === undefined) return { status: 'miss', precision: 'triangle' };
+
+  const origin = screen.ray;
+  const query = world
+    .query({
+      read: [Transform, GlobalTransform, MeshFilter, MeshRenderer],
+      optional: [Instances],
+    })
+    .unwrap();
+  let best: TriangleHit | undefined;
+  let unsupportedReason: TrianglePickUnavailableReason | undefined;
+  const unsupportedEntities: EntityHandle[] = [];
+
+  for (const row of query) {
+    const rawHandle = Math.round(row.get(MeshFilter).assetHandle as number);
+    if (rawHandle === 0) continue;
+    const resolved = resolveAssetHandle<MeshAsset>(world, toShared<'MeshAsset'>(rawHandle));
+    if (!resolved.ok) continue;
+    const mesh = resolved.value;
+    const entity = row.entity;
+    const entityWorldMatrix = readWorldMatrix(world, entity);
+    if (entityWorldMatrix === undefined) continue;
+    const instancesData = row.get(Instances);
+    let instanceTransforms: Float32Array | undefined;
+    let instanceCount = 1;
+    if (instancesData !== undefined) {
+      if (options.instances === undefined) {
+        unsupportedReason ??= 'instance-transforms-unavailable';
+        unsupportedEntities.push(entity);
+        continue;
+      }
+      const snapshot = options.instances.peek(instancesData.collectionId as InstanceCollectionId);
+      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 !== undefined && mesh.attributes.skinWeight !== undefined;
+    if (skinned) {
+      let intersects = false;
+      for (let instanceIndex = 0; instanceIndex < instanceCount; instanceIndex += 1) {
+        const drawWorld =
+          instanceTransforms === undefined
+            ? (entityWorldMatrix as unknown as mat4.Mat4Like)
+            : mat4.multiply(
+                mat4.create(),
+                entityWorldMatrix as unknown as mat4.Mat4Like,
+                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 === undefined || positions.length < 3) {
+      let intersects = false;
+      for (let instanceIndex = 0; instanceIndex < instanceCount; instanceIndex += 1) {
+        const drawWorld =
+          instanceTransforms === undefined
+            ? (entityWorldMatrix as unknown as mat4.Mat4Like)
+            : mat4.multiply(
+                mat4.create(),
+                entityWorldMatrix as unknown as mat4.Mat4Like,
+                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 === undefined
+          ? (entityWorldMatrix as unknown as mat4.Mat4Like)
+          : mat4.multiply(
+              mat4.create(),
+              entityWorldMatrix as unknown as mat4.Mat4Like,
+              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: number, i1: number, i2: number, index: number): void => {
+        if (i0 < 0 || i1 < 0 || i2 < 0 || i0 > maxVertex || i1 > maxVertex || i2 > maxVertex)
+          return;
+        const a = [
+          positions[i0 * 3] as number,
+          positions[i0 * 3 + 1] as number,
+          positions[i0 * 3 + 2] as number,
+        ] as Vec3Like;
+        const b = [
+          positions[i1 * 3] as number,
+          positions[i1 * 3 + 1] as number,
+          positions[i1 * 3 + 2] as number,
+        ] as Vec3Like;
+        const c = [
+          positions[i2 * 3] as number,
+          positions[i2 * 3 + 1] as number,
+          positions[i2 * 3 + 2] as number,
+        ] as Vec3Like;
+        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;
+        // The local ray origin is stored in the first three slots; construct the
+        // point explicitly to avoid relying on a mutable Ray alias.
+        worldPoint[0] = (origin[0] as number) + (origin[3] as number) * hit.t;
+        worldPoint[1] = (origin[1] as number) + (origin[4] as number) * hit.t;
+        worldPoint[2] = (origin[2] as number) + (origin[5] as number) * hit.t;
+        const distance = pointOnRay(origin, worldPoint);
+        if (
+          !Number.isFinite(distance) ||
+          distance < 0 ||
+          (best !== undefined && distance >= best.distance)
+        )
+          return;
+        const assetGuid = options.assetGuidOf?.(mesh);
+        best = {
+          entity,
+          triangleIndex: index,
+          point: [worldPoint[0], worldPoint[1], worldPoint[2]] as unknown as Vec3Like,
+          distance,
+          barycentric: [1 - hit.u - hit.v, hit.u, hit.v],
+          ...(assetGuid === undefined ? {} : { assetGuid }),
+          ...(instanceTransforms === undefined ? {} : { 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 !== undefined && 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] as number;
+              const i1 = indices[base + 1] as number;
+              const i2 = indices[base + 2] as number;
+              // WebGPU alternates strip winding after every vertex. The
+              // intersection is double-sided, but preserving the primitive's
+              // authored order keeps barycentrics and triangle identity honest.
+              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] as number,
+                indices[base + 1] as number,
+                indices[base + 2] as number,
+                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 !== undefined) {
+    return {
+      status: 'unavailable',
+      precision: 'unavailable',
+      reason: unsupportedReason,
+      entities: unsupportedEntities,
+    };
+  }
+  return best === undefined
+    ? { status: 'miss', precision: 'triangle' }
+    : { status: 'hit', hit: best };
+}

package/src/pick-vertex.ts

@@ -293,12 +293,16 @@ function collectVertexHits(
     const cy = positions[i2 * 3 + 1] as number;
     const cz = positions[i2 * 3 + 2] as number;
 
-    const triResult = ray.rayTriangleIntersects(
-      r,
-      [ax, ay, az] as unknown as Vec3Like,
-      [bx, by, bz] as unknown as Vec3Like,
-      [cx, cy, cz] as unknown as Vec3Like,
-    );
+    // The screen ray is in world space. Transform the triangle into that same
+    // space before testing it; testing local positions against a world ray
+    // makes translated/rotated/non-uniform instances return false hits.
+    const worldA = vec3.create();
+    const worldB = vec3.create();
+    const worldC = vec3.create();
+    mat4.transformPoint(worldA, entityWMLike, [ax, ay, az] as unknown as Vec3Like);
+    mat4.transformPoint(worldB, entityWMLike, [bx, by, bz] as unknown as Vec3Like);
+    mat4.transformPoint(worldC, entityWMLike, [cx, cy, cz] as unknown as Vec3Like);
+    const triResult = ray.rayTriangleIntersects(r, worldA, worldB, worldC);
 
     if (!triResult.hit) return;
 
@@ -310,8 +314,7 @@ function collectVertexHits(
       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] as unknown as Vec3Like);
+      const worldVec = vi === i0 ? worldA : vi === i1 ? worldB : worldC;
       const wx = worldVec[0] as number;
       const wy = worldVec[1] as number;
       const wz = worldVec[2] as number;