@forgeax/engine-render 0.0.0-dev.8d955ade1c79

package/src/scene-instances/post-spawn-resolve-joints.ts

@@ -0,0 +1,165 @@
+// @forgeax/engine-runtime — postSpawnResolveJoints hook (M1 / T-14).
+//
+// Invoked after sceneInstances.instantiate to auto-wire Skin.joints: Entity[]
+// from the SkinAsset.jointPaths via Name-component lookup on the
+// spawned entity subtree. This is the v1 missing item #2: instantiate auto-calls
+// postSpawnResolveJoints so AI users never manually populate Skin.joints.
+//
+// Resolution protocol (plan-strategy D-6a + tweak-20260611 D-7 subtree-scope):
+//   - From the spawnRoot, walk ChildOf relations BFS to collect the spawned
+//     subtree's entities. nameIndex is built only over those entities.
+//   - For each Skin-bearing entity in the subtree, resolve the skeleton handle
+//     to jointPaths via the resolver.
+//   - For each jointPath leaf name, match against the subtree-local Name index.
+//   - Same-name sibling within the subtree: first-match with console.warn (D-6a).
+//   - Missing entity: fail-fast 'skin-joint-path-unresolved' error.
+//   - Empty jointPaths: no-op (no crash).
+//
+// Why subtree-scope (tweak-20260611 D-7):
+//   Without scope, multiple instantiate() calls on the same SceneAsset (e.g. 3
+//   Fox foxes side-by-side) all wire to the FIRST instance's joint entities
+//   because Name leaf strings collide globally — Skin.joints[] points to
+//   instance-0's bones for every spawn, three foxes share one skeleton, poses
+//   cannot differ. Scoping to ChildOf descendants of spawnRoot eliminates the
+//   collision: each spawn has its own copy of the subtree, names collide only
+//   among siblings within the same spawn, where D-6a's first-match-with-warn
+//   remains the correct policy.
+//
+// Decision anchors:
+//   - requirements AC-14 (post-spawn auto-wire)
+//   - plan-strategy D-6a (first-match strategy within subtree)
+//   - tweak-20260611 plan-strategy D-7 (subtree-scope)
+//   - charter P3 (explicit failure: path-unresolved fail-fast)
+
+import type { SkinJointResolver } from '@forgeax/engine-assets-runtime';
+import type { EntityHandle, World } from '@forgeax/engine-ecs';
+import { collectSubtree, Name } from '@forgeax/engine-scene';
+import { Skin } from '@forgeax/engine-skinning';
+
+// feat-20260705-runtime-tier2-decomposition M1 / w6 (D-1): SkinJointResolver
+// relocated to registry/instantiate.ts so the hook contract travels with the
+// instantiate cluster into @forgeax/engine-assets-runtime. Imported back here as
+// a forward (runtime -> assets-runtime-bound module) type-only reference and
+// re-exported for existing consumers of this module's SkinJointResolver export.
+export type { SkinJointResolver } from '@forgeax/engine-assets-runtime';
+
+interface JointPathUnresolvedError {
+  code: 'skin-joint-path-unresolved';
+  expected: string;
+  hint: string;
+  detail: {
+    skinEntity: number;
+    path: readonly string[];
+    failedAtIndex: number;
+  };
+}
+
+interface SkinAssetUnresolvedError {
+  code: 'skin-asset-unresolved';
+  expected: string;
+  hint: string;
+  detail: {
+    skinEntity: number;
+    skeletonHandle: number;
+  };
+}
+
+type ResolveError = JointPathUnresolvedError | SkinAssetUnresolvedError;
+
+export function postSpawnResolveJoints(
+  world: World,
+  resolver: SkinJointResolver,
+  spawnRoot: EntityHandle,
+): { ok: true } | { ok: false; error: ResolveError } {
+  // tweak-20260611 D-7: scope nameIndex to the spawnRoot's ChildOf-descendant
+  // subtree (incl. spawnRoot itself). Multiple instantiate() calls on the same
+  // SceneAsset each get an independent subtree, so leaf-name collisions across
+  // instances no longer wire all spawns to the first instance's joints.
+  const subtree = collectSubtree(world, spawnRoot);
+  const nameIndex = new Map<string, number[]>();
+  const nameQuery = world.query({ read: [Name] });
+  if (nameQuery.ok) {
+    for (const row of nameQuery.value) {
+      if (!subtree.has(row.entity as number)) continue;
+      const nameVal = row.get(Name).value;
+      const list = nameIndex.get(nameVal) ?? [];
+      list.push(row.entity);
+      nameIndex.set(nameVal, list);
+    }
+  }
+
+  // Walk Skin-bearing entities IN THE SUBTREE and resolve joints. Skin is
+  // matched through the owner identity projection, and entities outside the subtree
+  // are filtered after readEntityAt (cheaper than per-archetype filtering).
+  const skinQuery = world.query({ read: [Skin] });
+  if (!skinQuery.ok) return { ok: true };
+  for (const queryRow of skinQuery.value) {
+    const entity = queryRow.entity;
+    if (!subtree.has(entity as number)) continue;
+    const skeletonHandle = queryRow.get(Skin).skeleton as number;
+
+    const skinAsset = resolver.resolveSkinAsset(skeletonHandle);
+    if (skinAsset === undefined) {
+      // feat-20260612 M2 fixup: was a silent `continue` that left
+      // `Skin.joints` empty -- the M2-introduced
+      // JointCountMismatchError fail-fast in render-system-extract then
+      // triggered every frame on the browser-async-pack-fetch path.
+      // The cure is to load SkinAssets through the SceneAsset.skinGuids
+      // cross-edge (gltfImporter scene branch emits the SkinAsset GUIDs into
+      // the scene envelope's refs[], the runtime recursion source) so this
+      // resolver should always succeed; if it does not, fail-fast here
+      // with a precise errorCode rather than silently producing an
+      // unresolvable Skin.joints state.
+      return {
+        ok: false,
+        error: {
+          code: 'skin-asset-unresolved',
+          expected: `SkinAsset registered for skeleton handle ${skeletonHandle} when instantiate triggers postSpawnResolveJoints`,
+          hint: `SkinAsset matching skeletonGuid for handle ${skeletonHandle} was not found in AssetRegistry; verify the SceneAsset.skinGuids[] cross-edge is populated by the importer (gltfImporter scene branch) and that loadByGuid<SceneAsset> recursively loaded each SkinAsset before instantiate (browser-async-pack-fetch path)`,
+          detail: { skinEntity: entity, skeletonHandle },
+        },
+      };
+    }
+
+    const jointEntityList: number[] = [];
+    for (const jointPath of skinAsset.jointPaths) {
+      const pathSegments = jointPath.split('/').filter(Boolean);
+      if (pathSegments.length === 0) continue;
+
+      const leafName = pathSegments[pathSegments.length - 1];
+      if (leafName === undefined) continue;
+
+      const nameMatches = nameIndex.get(leafName);
+      if (nameMatches === undefined || nameMatches.length === 0) {
+        return {
+          ok: false,
+          error: {
+            code: 'skin-joint-path-unresolved',
+            expected: `joint entity with Name="${leafName}" exists in the spawned subtree (root entity ${spawnRoot})`,
+            hint: `joint path "${jointPath}" for skin entity ${entity} could not be resolved within spawnRoot ${spawnRoot}'s ChildOf-subtree; verify glTF node names are preserved and instantiateScene seeded a Children mirror`,
+            detail: {
+              skinEntity: entity,
+              path: pathSegments,
+              failedAtIndex: pathSegments.length - 1,
+            },
+          },
+        };
+      }
+
+      if (nameMatches.length > 1) {
+        console.warn(
+          `[Skin] same-name sibling: "${leafName}" matches ${nameMatches.length} entities ` +
+            `within spawn subtree of root ${spawnRoot}; using first-match (entity ${nameMatches[0]}) per D-6a`,
+        );
+      }
+
+      jointEntityList.push(nameMatches[0] as number);
+    }
+
+    world.set(entity, Skin, {
+      joints: new Uint32Array(jointEntityList),
+    } as never);
+  }
+
+  return { ok: true };
+}

package/src/shadow-atlas.ts

@@ -0,0 +1,244 @@
+// @forgeax/engine-runtime - ShadowAtlas (cube_array depth atlas for point-light shadows).
+//
+// feat-20260612-point-light-shadows-urp-hdrp M3 / T-M3-1 (plan-strategy §D-1).
+//
+// Lazy-allocated `texture_depth_cube_array` (depth32float) + per-face 2D
+// TextureView cache. One layer per shadow-casting PointLight (cap = 4 enforced
+// by the PointLightShadow ECS component cardinality). Total texel footprint at
+// the 512x512 default = 4 layers x 6 faces x 512 x 512 x 4 B = 24 MiB.
+//
+// Why a separate module (vs inlining into createRenderer / pipelineState):
+// - zero-shadow scene path stays allocation-free (AC-09): we never call
+//   `device.createTexture` on the cube_array unless `ensure(...)` is invoked
+//   from the extract / record path on a frame that has at least one
+//   PointLightShadow snapshot.
+// - face-view cache is keyed (layer, face) and built lazily during the
+//   per-light shadow caster pass; the cache is invalidated together with the
+//   atlas when `dispose()` runs (renderer teardown or layers re-allocation).
+// - the helper descriptors live in `@forgeax/engine-rhi`
+//   (`cubeArrayDepthDescriptor` / `cubeArrayDepthFaceView` /
+//   `comparisonSamplerDescriptor`) per T-M0-3; this file is the runtime-side
+//   owner of the GPU resources they describe.
+//
+// Lifecycle:
+//   1. `new ShadowAtlas(device, { faceSize, layers })` — construct the
+//      manager; no GPU work yet.
+//   2. `atlas.ensure()` — first call allocates the cube_array texture +
+//      cube_array sampling view + comparison sampler (idempotent thereafter).
+//   3. `atlas.faceView(layer, face)` — lazy 2D depth view used as a render-
+//      pass attachment for the corresponding cube face. Cached per (layer,
+//      face).
+//   4. `atlas.dispose()` — releases the GPU resources and clears caches.
+//      `ensure()` after `dispose()` re-allocates from scratch.
+
+import {
+  comparisonSamplerDescriptor,
+  cubeArrayDepthDescriptor,
+  cubeArrayDepthFaceView,
+  type RhiDevice,
+  type Sampler,
+  type Texture,
+  type TextureView,
+} from '@forgeax/engine-rhi';
+
+import {
+  PointShadowAtlasBoundsViolationError,
+  PointShadowAtlasUninitializedError,
+} from './errors/render';
+import { GPU_TEXTURE_USAGE_RENDER_ATTACHMENT_AND_TEXTURE_BINDING } from './gpu-texture-usage';
+
+/**
+ * Construction options for {@link ShadowAtlas}.
+ */
+export interface ShadowAtlasOptions {
+  /** Per-face square size in pixels. Default 512 (PointLightShadow.mapSize default). */
+  readonly faceSize?: number;
+  /** Number of cube layers. Default 4 (= PointLightShadow cardinality cap). */
+  readonly layers?: number;
+}
+
+/** Default per-face square size in pixels. Mirrors PointLightShadow.mapSize default. */
+export const SHADOW_ATLAS_DEFAULT_FACE_SIZE = 512;
+/** Default cube layer count. Mirrors PointLightShadow cardinality cap. */
+export const SHADOW_ATLAS_DEFAULT_LAYERS = 4;
+
+/**
+ * Cube-array depth atlas for point-light shadows.
+ *
+ * Shape: `texture_depth_cube_array` (depth32float) with `layers = 4` and per-
+ * face size `faceSize x faceSize`. The cube_array sampling view feeds
+ * `@group(0) @binding(5)` in URP shaders; the per-face 2D view feeds the
+ * shadow-caster render pass attachment for one (layer, face) at a time
+ * (WebGPU forbids cube views as render-pass attachments).
+ *
+ * Construction performs no GPU work. The first `ensure()` call allocates the
+ * texture + view + sampler. `dispose()` releases everything; later `ensure()`
+ * calls re-allocate.
+ *
+ * @example Lazy allocation in the extract / record path:
+ * ```
+ * if (lights.pointShadow.length > 0) {
+ *   atlas.ensure();
+ *   for (const ps of lights.pointShadow) {
+ *     for (let face = 0; face < 6; face++) {
+ *       const view = atlas.faceView(ps.shadowAtlasLayer, face);
+ *       // ... begin shadow caster pass with `view` as the depth attachment
+ *     }
+ *   }
+ * }
+ * ```
+ */
+export class ShadowAtlas {
+  /** Backing cube_array depth texture. `null` until `ensure()` has run. */
+  private texture: Texture | null = null;
+  /**
+   * Whole-atlas cube_array sampling view used by URP shaders that bind the
+   * atlas at `@group(0) @binding(5)`. `null` until `ensure()` has run.
+   */
+  private cubeArrayView: TextureView | null = null;
+  /** Comparison sampler for `texture_depth_cube_array`. */
+  private compareSampler: Sampler | null = null;
+  /** Per-face 2D depth view cache, keyed by `layer * 6 + face`. */
+  private readonly faceViews = new Map<number, TextureView>();
+  /** Per-face label cache (debug aid). Reused on re-creation. */
+  private readonly device: RhiDevice;
+  /** Per-face square size in pixels. */
+  readonly faceSize: number;
+  /** Cube layer count. */
+  readonly layers: number;
+
+  constructor(device: RhiDevice, options: ShadowAtlasOptions = {}) {
+    this.device = device;
+    this.faceSize = options.faceSize ?? SHADOW_ATLAS_DEFAULT_FACE_SIZE;
+    this.layers = options.layers ?? SHADOW_ATLAS_DEFAULT_LAYERS;
+  }
+
+  /**
+   * Returns `true` once the atlas texture is allocated. Used by the extract /
+   * record path to gate "no PointLightShadow → no allocation" (AC-09) — the
+   * caller calls {@link ensure} on a frame that has at least one snapshot;
+   * before that, `isAllocated()` stays `false` and tests can assert no GPU
+   * resources were created.
+   */
+  isAllocated(): boolean {
+    return this.texture !== null;
+  }
+
+  /**
+   * Lazy-allocate the atlas texture + cube_array sampling view + comparison
+   * sampler. Idempotent: subsequent calls are zero-cost no-ops once the
+   * resources exist.
+   *
+   * Throws (via the RHI error registry) on allocation failure. This is the
+   * only path that touches the GPU — keeping it inside one method makes the
+   * "zero-shadow scene = zero allocation" gate easy to enforce: the renderer
+   * never calls this method on a frame with no PointLightShadow entities.
+   */
+  ensure(): void {
+    if (this.texture !== null) return;
+    const usage = GPU_TEXTURE_USAGE_RENDER_ATTACHMENT_AND_TEXTURE_BINDING;
+    const texDesc = cubeArrayDepthDescriptor(this.faceSize, this.layers, usage);
+    const texRes = this.device.createTexture(texDesc);
+    if (!texRes.ok) throw texRes.error;
+    this.texture = texRes.value;
+
+    const viewRes = this.device.createTextureView(this.texture, {
+      label: 'shadow-atlas-cube-array-view',
+      dimension: 'cube-array',
+      aspect: 'depth-only',
+      baseArrayLayer: 0,
+      arrayLayerCount: 6 * this.layers,
+      baseMipLevel: 0,
+      mipLevelCount: 1,
+    });
+    if (!viewRes.ok) {
+      this.device.destroyTexture(this.texture);
+      this.texture = null;
+      throw viewRes.error;
+    }
+    this.cubeArrayView = viewRes.value;
+
+    const sampRes = this.device.createSampler(comparisonSamplerDescriptor());
+    if (!sampRes.ok) {
+      this.device.destroyTexture(this.texture);
+      this.texture = null;
+      this.cubeArrayView = null;
+      throw sampRes.error;
+    }
+    this.compareSampler = sampRes.value;
+  }
+
+  /**
+   * Whole-atlas cube_array sampling view (`texture_depth_cube_array`). Returns
+   * `null` if the atlas is not yet allocated; the caller should gate on a
+   * non-null pointShadow array before calling {@link ensure} + this getter.
+   */
+  getAtlasView(): TextureView | null {
+    return this.cubeArrayView;
+  }
+
+  /**
+   * Comparison sampler (`compare: 'less'`) for cube_array depth sampling.
+   * Returns `null` if the atlas is not yet allocated.
+   */
+  getComparisonSampler(): Sampler | null {
+    return this.compareSampler;
+  }
+
+  /**
+   * Backing texture handle. Returns `null` if the atlas is not yet allocated.
+   */
+  getTexture(): Texture | null {
+    return this.texture;
+  }
+
+  /**
+   * Lazy 2D depth view selecting `(layer, face)` (the caller passes
+   * `shadowAtlasLayer` from the snapshot and a face index 0..5). Used as the
+   * depth attachment of the shadow-caster render pass for one cube face.
+   *
+   * Caches per `(layer, face)` so the per-frame shadow loop pays zero
+   * `createTextureView` cost after the first allocation. Cache is cleared on
+   * {@link dispose}.
+   *
+   * @throws PointShadowAtlasUninitializedError if the atlas is not yet
+   *   allocated (caller must call {@link ensure} first).
+   * @throws PointShadowAtlasBoundsViolationError if `layer` or `face` is out
+   *   of range.
+   * @throws RhiError if the underlying `createTextureView` fails.
+   */
+  faceView(layer: number, face: number): TextureView {
+    if (this.texture === null) {
+      throw new PointShadowAtlasUninitializedError();
+    }
+    if (layer < 0 || layer >= this.layers) {
+      throw new PointShadowAtlasBoundsViolationError('layer', layer, this.layers);
+    }
+    if (face < 0 || face >= 6) {
+      throw new PointShadowAtlasBoundsViolationError('face', face, 6);
+    }
+    const key = layer * 6 + face;
+    const cached = this.faceViews.get(key);
+    if (cached !== undefined) return cached;
+    const desc = cubeArrayDepthFaceView(layer, face);
+    const r = this.device.createTextureView(this.texture, desc);
+    if (!r.ok) throw r.error;
+    this.faceViews.set(key, r.value);
+    return r.value;
+  }
+
+  /**
+   * Release the GPU resources and clear the per-face view cache. Idempotent;
+   * subsequent calls are zero-cost. After dispose, `isAllocated()` returns
+   * `false` and the next `ensure()` re-allocates from scratch.
+   */
+  dispose(): void {
+    this.faceViews.clear();
+    if (this.texture !== null) {
+      this.device.destroyTexture(this.texture);
+      this.texture = null;
+    }
+    this.cubeArrayView = null;
+    this.compareSampler = null;
+  }
+}