@forgeax/engine-picking 0.1.2

package/src/pick-core.ts

@@ -0,0 +1,114 @@
+// pick-core.ts — shared picking skeleton for pick() / pickVertex*() (feat-20260705 M2 M0).
+//
+// `pick.ts` (screen-to-entity ray-AABB) and `pick-vertex.ts` (vertex-level) share a
+// verbatim skeleton (F11): the `Transform.world` row type, the row reader, and the
+// camera-validation → view=invert(worldMatrix) → projection-branch → screenToRay
+// sequence. This module is the single source of truth for that skeleton
+// (architecture-principles §2 Derive, Don't Duplicate; AC-201). pick.ts and
+// pick-vertex.ts import from here rather than each maintaining their own copy.
+//
+// Error channel (charter P3): a `cameraEntity` that carries no `Camera` is the one
+// unrecoverable precondition — `computeScreenRay` throws a structured `PickError`
+// (`code: 'camera-component-missing'`). A camera entity that carries no resolvable
+// `Transform.world` is a degenerate miss (no view matrix can be built) — signalled by
+// a `undefined` return, which callers translate to their own miss shape
+// (`undefined` for pick, `[]`/`undefined` for the vertex queries).
+
+import type { EntityHandle, World } from '@forgeax/engine-ecs';
+import { mat4, ray } from '@forgeax/engine-math';
+import { Camera, type CameraProjection, cameraProjectionFromF32 } from '@forgeax/engine-render';
+import { Transform } from '@forgeax/engine-scene';
+import { PickError } from './pick-errors';
+
+/**
+ * Read an entity's resolved world mat4 (16 column-major floats) from the
+ * `Transform.world` column array view (feat-20260601 D-3). Returns a fresh
+ * copy (the view aliases live slot bytes); `undefined` when the entity has no
+ * Transform / world column.
+ */
+export function readWorldMatrix(world: World, entity: EntityHandle): Float32Array | undefined {
+  const result = world.get(entity, Transform);
+  return result.ok ? new Float32Array(result.value.world) : undefined;
+}
+
+/**
+ * The screen-to-world ray plus the camera matrices used to build it.
+ *
+ *   - `ray`            — the unprojected world-space pick ray (origin + direction).
+ *   - `view`           — `invert(camera Transform.world)`.
+ *   - `proj`           — the camera projection matrix (perspective / orthographic).
+ *   - `projectionKind` — the resolved camera projection discriminant.
+ *
+ * `view` and `proj` are returned separately so vertex picking can build its own
+ * `viewProj = proj * view` for `worldToScreen` without recomputing the branch.
+ */
+export interface ScreenRay {
+  readonly ray: ray.Ray;
+  readonly view: mat4.Mat4;
+  readonly proj: mat4.Mat4;
+  readonly projectionKind: CameraProjection;
+}
+
+/**
+ * Build the screen-to-world ray for `cameraEntity` at the viewport-relative
+ * `(screenX, screenY)` coordinate: validate the camera component, read its world
+ * transform, invert it to a view matrix, branch the projection on the camera
+ * discriminant, and unproject the coordinate into a world-space ray.
+ *
+ * @returns The `ScreenRay`, or `undefined` when the camera entity carries no
+ *   resolvable `Transform.world` (a degenerate miss — no view matrix can be built).
+ * @throws {PickError} `code: 'camera-component-missing'` when `cameraEntity` has no `Camera`.
+ */
+export function computeScreenRay(
+  world: World,
+  cameraEntity: EntityHandle,
+  screenX: number,
+  screenY: number,
+  viewportWidth: number,
+  viewportHeight: number,
+): ScreenRay | undefined {
+  // An invalid viewport cannot define a screen ray; refuse it before the lower
+  // math layer's safe fallback can become a fabricated origin hit.
+  if (
+    !Number.isFinite(viewportWidth) ||
+    !Number.isFinite(viewportHeight) ||
+    viewportWidth <= 0 ||
+    viewportHeight <= 0
+  ) {
+    return undefined;
+  }
+
+  // --- precondition: camera component present (structured error, charter P3) ---
+  const camRes = world.get(cameraEntity, Camera);
+  if (!camRes.ok) {
+    throw new PickError(cameraEntity as unknown as number);
+  }
+  const cam = camRes.value;
+
+  // --- camera world transform (feat-20260601 D-3: read Transform.world mat4) ---
+  const camWorld = readWorldMatrix(world, cameraEntity);
+  if (camWorld === undefined) {
+    // A camera entity without a Transform cannot define a view matrix; treat the
+    // degenerate case as a miss rather than fabricating an identity view (no spurious hit).
+    return undefined;
+  }
+
+  // --- view = invert(camera world mat4) ---
+  const view = mat4.create();
+  mat4.invert(view, camWorld as unknown as mat4.Mat4Like);
+
+  // --- projection: branch on the camera discriminant (research Finding 5a) ---
+  const projectionKind = cameraProjectionFromF32(cam.projection);
+  const proj = mat4.create();
+  if (projectionKind === 'orthographic') {
+    mat4.orthographic(proj, cam.left, cam.right, cam.bottom, cam.top, cam.near, cam.far);
+  } else {
+    mat4.perspective(proj, cam.fov, cam.aspect, cam.near, cam.far);
+  }
+
+  // --- screen -> world ray (two-point unproject; clamp + NaN/Inf sanitized inside) ---
+  const r = ray.create();
+  ray.screenToRay(r, screenX, screenY, viewportWidth, viewportHeight, view, proj, projectionKind);
+
+  return { ray: r, view, proj, projectionKind };
+}

package/src/pick-errors.ts

@@ -0,0 +1,69 @@
+// @forgeax/engine-picking — pick error model (feat-20260529-picking-raycasting-screen-to-entity M3 / w9).
+//
+// PickError code owner + derived PickErrorCode projection. The screen-to-entity
+// `pick(...)` free function returns `undefined` for the recoverable miss path (no ray
+// hit) and surfaces a structured PickError ONLY for the one unrecoverable precondition
+// failure: the supplied cameraEntity does not hold a `Camera` component, so no view /
+// projection matrix can be built. Separating the error channel (PickError) from the
+// normal miss channel (undefined) lets AI users branch with `if (hit)` for the common
+// case and inspect `.code` for the precondition failure (charter P3).
+//
+// D-1: a NEW closed union rather than reusing RuntimeErrorCode. RuntimeErrorCode's 8
+// members are all render / skin / shadow domain; folding a picking precondition into it
+// would dilute its semantic focus. A dedicated single-member union keeps the picking
+// error surface cohesive and additively evolvable (AGENTS.md Error model minor add-only).
+//
+// Related: requirements AC-11 (structured error signal) + AC-13 (closed-union SSOT);
+//          plan-strategy D-1; plan-tasks.json w9 acceptanceCheck; charter P3.
+
+/**
+ * Detail for the `PickError` camera-component-missing code.
+ *
+ * Carries the offending camera entity (packed `Entity` u32) so AI consumers can read
+ * `.detail.cameraEntity` by property access (charter P4) — no string parsing of the
+ * human-facing message.
+ */
+export interface PickCameraMissingDetail {
+  readonly cameraEntity: number;
+}
+
+/**
+ * Structured error for the picking precondition failure: the supplied `cameraEntity`
+ * does not hold a `Camera` component, so `pick()` cannot build the view / projection
+ * matrices needed to unproject the screen coordinate.
+ *
+ * Three-field structured surface per the AGENTS.md error model + `.detail`:
+ *   - `.code = 'camera-component-missing'` (closed `PickErrorCode`)
+ *   - `.expected` — the expected precondition (camera entity carries a `Camera`)
+ *   - `.hint` — an actionable `world.set` recovery directive
+ *   - `.detail = { cameraEntity }` — the offending entity (charter P4)
+ *
+ * Surfaced (not the normal miss path): a no-hit ray returns `undefined` from `pick()`;
+ * this error is reserved for the unrecoverable precondition (charter P3 explicit failure,
+ * separate channel from the recoverable miss).
+ */
+export class PickError extends Error {
+  readonly code = 'camera-component-missing';
+  readonly expected: string;
+  readonly hint: string;
+  readonly detail: PickCameraMissingDetail;
+
+  constructor(cameraEntity: number) {
+    const expected = 'cameraEntity holds a Camera component';
+    const hint =
+      `cameraEntity ${cameraEntity} has no Camera component; spawn or attach one before ` +
+      'picking, e.g. world.set(cameraEntity, Camera, { fov: Math.PI / 4, aspect, near, far })';
+    super(`pick: cameraEntity ${cameraEntity} has no Camera component`);
+    this.name = 'PickError';
+    this.expected = expected;
+    this.hint = hint;
+    this.detail = { cameraEntity };
+  }
+}
+
+/**
+ * Closed union of picking precondition error codes, derived from the PickError owner.
+ *
+ * AI users perform exhaustive `switch (err.code)` without a default; TS guards completeness.
+ */
+export type PickErrorCode = PickError['code'];

package/src/pick-tile.ts

@@ -0,0 +1,157 @@
+// pick-tile.ts - cell-level Tilemap query (feat-20260608 M0 baseline rebuild).
+//
+// `pickTile(world, tilemapEntity, worldX, worldY)` is a free function (not a
+// method on `World` -- charter F1 single-import barrel from
+// `@forgeax/engine-runtime`). It converts world-space coordinates into the
+// Tilemap's local cell grid, walks every TileLayer that ChildOf-s the
+// supplied tilemap, and returns the FIRST non-zero tile id seen when scanning
+// layers in DESCENDING `layerOrder` (highest layer drawn on top wins).
+//
+// charter mapping:
+//   - P3 explicit failure as value: out-of-bounds and "every layer empty"
+//     resolve to `Result.ok(null)` -- never throws or fires onError. Dead
+//     handles and live entities without Tilemap are separate structural
+//     failures; the `PickTileError` union is closed to two variants and stays
+//     a runtime-only type (not exported through `@forgeax/engine-types`, since
+//     pickTile is a runtime-only system).
+//   - P4 consistent abstraction: matches the `pick(world, ...)` raycast
+//     surface in pick.ts -- free function, world+entity input, structured
+//     error union, hit-or-null return.
+//   - F1 single-import: exported from `@forgeax/engine-picking`'s barrel.
+//
+// Anchors: requirements §integration-points (engine-runtime pickTile);
+// plan-tasks m0-t8; plan-strategy §D-5 file-by-file ECS API adaptation
+// (World-owned Query pattern from render-system-extract.ts).
+
+import { Entity, type EntityHandle, type World } from '@forgeax/engine-ecs';
+import { mat4, vec3 } from '@forgeax/engine-math';
+import { TileLayer, Tilemap } from '@forgeax/engine-render/authoring';
+import { ChildOf, Transform } from '@forgeax/engine-scene';
+import { err, ok, type Result } from '@forgeax/engine-types';
+
+/**
+ * Closed error union for `pickTile` (charter P3 + P4). Two variants cover the
+ * structural-break paths; "ray hit nothing" is a value (`Result.ok(null)`),
+ * not an error.
+ */
+export type PickTileError =
+  | { readonly code: 'tilemap-not-found'; readonly tilemapEntity: EntityHandle }
+  | { readonly code: 'tilemap-component-missing'; readonly tilemapEntity: EntityHandle };
+
+/**
+ * Successful picking outcome. Returned through `Result.ok`; a `null` value
+ * means the query landed in-bounds but every layer at that cell was empty
+ * (or the point was outside the tilemap world bounds).
+ */
+export interface PickTileHit {
+  readonly layerEntity: EntityHandle;
+  readonly cellX: number;
+  readonly cellY: number;
+  readonly tileId: number;
+}
+
+/**
+ * Find the topmost non-zero tile under `(worldX, worldY)` for a given
+ * Tilemap entity, walking child TileLayer entities in DESCENDING
+ * `layerOrder`.
+ *
+ * @returns
+ *   - `Result.ok(PickTileHit)` for a non-zero cell on some layer.
+ *   - `Result.ok(null)` for an empty cell or out-of-bounds query.
+ *   - `Result.err({ code: 'tilemap-not-found' })` for a dead handle.
+ *   - `Result.err({ code: 'tilemap-component-missing' })` for a live entity
+ *     without a Tilemap component.
+ *
+ * The caller must propagate the World so `Transform.world` is current. A
+ * singular world transform follows `mat4.invert`'s deterministic identity
+ * fallback, which keeps this error union structural rather than adding a
+ * third diagnostic arm.
+ */
+export function pickTile(
+  world: World,
+  tilemapEntity: EntityHandle,
+  worldX: number,
+  worldY: number,
+): Result<PickTileHit | null, PickTileError> {
+  const entityResult = world.get(tilemapEntity, Entity);
+  if (!entityResult.ok) {
+    return err({ code: 'tilemap-not-found', tilemapEntity });
+  }
+
+  const tilemapResult = world.get(tilemapEntity, Tilemap);
+  if (!tilemapResult.ok) {
+    return err({ code: 'tilemap-component-missing', tilemapEntity });
+  }
+  const tilemap = tilemapResult.value;
+  const cols = tilemap.cols;
+  const rows = tilemap.rows;
+  // feat-20260709 M3: tileSize is one inline array<f32,2> column; the
+  // world.get read path materialises it as a Float32Array ([width, height]).
+  const tileSizeX = tilemap.tileSize[0] ?? 1;
+  const tileSizeY = tilemap.tileSize[1] ?? 1;
+
+  // Tilemap entities without a Transform retain the origin-default path. For
+  // transformed maps, the full propagated affine inverse is the only correct
+  // way to recover local cell coordinates under rotation and non-uniform scale.
+  let localX = worldX;
+  let localY = worldY;
+  const transformResult = world.get(tilemapEntity, Transform);
+  if (transformResult.ok) {
+    const w = transformResult.value.world;
+    if (w !== undefined && w.length >= 16) {
+      const local = mat4.transformPoint(vec3.create(), mat4.invert(mat4.create(), w), [
+        worldX,
+        worldY,
+        0,
+      ]);
+      localX = local[0] ?? 0;
+      localY = local[1] ?? 0;
+    }
+  }
+
+  if (tileSizeX <= 0 || tileSizeY <= 0) return ok(null);
+  if (localX < 0 || localY < 0) return ok(null);
+
+  const cellX = Math.floor(localX / tileSizeX);
+  const cellY = Math.floor(localY / tileSizeY);
+  if (cellX < 0 || cellY < 0 || cellX >= cols || cellY >= rows) return ok(null);
+
+  // Collect every TileLayer ChildOf-ing the supplied Tilemap entity, with
+  // its layerOrder + tile array snapshot through one row iterator.
+  type LayerInfo = {
+    readonly entity: EntityHandle;
+    readonly tiles: ArrayLike<number>;
+    readonly layerOrder: number;
+  };
+  const layers: LayerInfo[] = [];
+  const layerQuery = world.query({ read: [TileLayer, ChildOf] }).unwrap();
+  for (const row of layerQuery) {
+    const layerEntity = row.entity;
+    const parent = row.get(ChildOf).parent;
+    if ((parent as unknown as number) !== (tilemapEntity as unknown as number)) continue;
+    const layerData = world.get(layerEntity, TileLayer);
+    if (!layerData.ok) continue;
+    layers.push({
+      entity: layerEntity,
+      tiles: layerData.value.tiles as ArrayLike<number>,
+      layerOrder: row.get(TileLayer).layerOrder,
+    });
+  }
+
+  layers.sort((a, b) => b.layerOrder - a.layerOrder);
+
+  const cellIndex = cellY * cols + cellX;
+  for (const layer of layers) {
+    if (cellIndex >= layer.tiles.length) continue;
+    const tileId = layer.tiles[cellIndex] ?? 0;
+    if (tileId !== 0) {
+      return ok({
+        layerEntity: layer.entity,
+        cellX,
+        cellY,
+        tileId,
+      });
+    }
+  }
+  return ok(null);
+}