@forgeax/engine-render 0.1.3 → 0.1.6

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

@@ -31,20 +31,17 @@
 //   - 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 { Name } from '@forgeax/engine-scene';
+import { collectSubtree, Name } from '@forgeax/engine-scene';
 import { Skin } from '@forgeax/engine-skinning';
-import type { SkinAsset } from '@forgeax/engine-types';
-import { collectSubtree } from '../scene-utils/collect-subtree';
 
 // 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 interface SkinJointResolver {
-  resolveSkinAsset(skeletonHandle: number): SkinAsset | undefined;
-}
+export type { SkinJointResolver } from '@forgeax/engine-assets-runtime';
 
 interface JointPathUnresolvedError {
   code: 'skin-joint-path-unresolved';
@@ -118,7 +115,7 @@ export function postSpawnResolveJoints(
         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 AssetRegistry.load(sceneGuid, sceneAssetKind) recursively loaded each SkinAsset before instantiate (browser-async-pack-fetch path)`,
+          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 },
         },
       };

package/src/ssao-buffers.ts

@@ -10,17 +10,72 @@
 //                       label hdrp-ssao-uniform
 //
 // plan-strategy D-1: uniform carries view + projection + inverseProjection.
-// plan-strategy D-C: intensity scalar carried at offset 192 (vec4 pad slot)
-//   so the lighting shader can mix(1.0, ssao*ao, intensity) without a new UBO.
+// plan-strategy D-C: intensity, radius, and bias are carried at offset 192
+//   (the existing vec4 slot), so the lighting shader can mix(1.0, ssao*ao,
+//   intensity) without a new UBO.
 // The kernel uses a uniform buffer on every backend. 1024 B is below the
 // WebGL2 minimum fragment UBO size, so SSAO does not need a storage-buffer
 // capability gate.
 
-import type { Buffer, Texture } from '@forgeax/engine-rhi';
+import type { Buffer, Sampler, Texture, TextureView } from '@forgeax/engine-rhi';
 import { GPU_TEXTURE_USAGE_COPY_DST, GPU_TEXTURE_USAGE_TEXTURE_BINDING } from './gpu-texture-usage';
 import { GPU_BUFFER_USAGE_COPY_DST, GPU_BUFFER_USAGE_UNIFORM } from './gpu-usage';
-import type { RenderSystemRuntime } from './render-system';
-import { generateSsaoKernel, generateSsaoNoise, SSAO_KERNEL_SAMPLE_COUNT } from './ssao-data';
+import type { RenderSystemRuntime } from './record/render-context';
+
+// Deterministic host-side SSAO data is owned by the buffer allocator because
+// these values have no consumer outside the resources they initialize.
+export const SSAO_KERNEL_SAMPLE_COUNT = 64;
+const NOISE_SIZE = 16;
+
+function mulberry32(seed: number): () => number {
+  let state = seed | 0;
+  return () => {
+    state = (state + 0x6d2b79f5) | 0;
+    let t = Math.imul(state ^ (state >>> 15), 1 | state);
+    t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t;
+    return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+  };
+}
+
+function lerp(a: number, b: number, t: number): number {
+  return a + t * (b - a);
+}
+
+export function generateSsaoKernel(seed: number = 0): readonly Float32Array[] {
+  const rand = mulberry32(seed);
+  const kernel: Float32Array[] = [];
+  for (let i = 0; i < SSAO_KERNEL_SAMPLE_COUNT; i++) {
+    let x = rand() * 2 - 1;
+    let y = rand() * 2 - 1;
+    let z = rand();
+    const len = Math.sqrt(x * x + y * y + z * z);
+    x /= len;
+    y /= len;
+    z /= len;
+    const r = rand();
+    x *= r;
+    y *= r;
+    z *= r;
+    const scale = lerp(0.1, 1.0, (i / SSAO_KERNEL_SAMPLE_COUNT) ** 2);
+    const sample = new Float32Array(3);
+    sample[0] = x * scale;
+    sample[1] = y * scale;
+    sample[2] = z * scale;
+    kernel.push(sample);
+  }
+  return kernel;
+}
+
+export function generateSsaoNoise(seed: number = 0): Float32Array {
+  const rand = mulberry32(seed);
+  const noise = new Float32Array(NOISE_SIZE * 3);
+  for (let i = 0; i < NOISE_SIZE; i++) {
+    noise[i * 3 + 0] = rand() * 2 - 1;
+    noise[i * 3 + 1] = rand() * 2 - 1;
+    noise[i * 3 + 2] = 0;
+  }
+  return noise;
+}
 
 // Each vec3<f32> in a WGSL array is 16B (12B payload + 4B padding).
 // 64 samples * 16 B/sample = 1024 B.
@@ -30,7 +85,7 @@ const BYTES_PER_KERNEL_ELEMENT = 16;
 //   bytes [0..63]    view              mat4x4<f32>
 //   bytes [64..127]  projection        mat4x4<f32>
 //   bytes [128..191] inverseProjection mat4x4<f32>
-//   bytes [192..207] intensityPad      vec4<f32>  // x = intensity, y/z/w pad
+//   bytes [192..207] intensityPad      vec4<f32>  // x = intensity, y = radius, z = bias, w = pad
 //   bytes [208..255] padding           // align to 256B WebGPU UBO offset
 //
 // The total is rounded to 256B so the same UBO can host an additional
@@ -40,6 +95,110 @@ const UNIFORM_BYTES = 256;
 export const SSAO_UNIFORM_INTENSITY_OFFSET = UNIFORM_INTENSITY_OFFSET_BYTES;
 export const SSAO_UNIFORM_BYTES = UNIFORM_BYTES;
 
+// ── 1x1 white fallback texture (plan-strategy §D-B) ───────────────────────
+//
+// Single-PSO invariant: the HDRP unified BGL always declares a binding 7
+// texture_2d<f32>. When SSAO is disabled (or its resources are not yet
+// allocated), the bind group binds this 1x1 r8unorm texture filled with
+// 0xFF. r8unorm normalizes 255 -> 1.0, so the lighting shader reads
+// `ssaoFactor = 1.0`, and `mix(1.0, ssao*ao, intensity) = ao` collapses
+// back to the round-1 baseline (ambient = baked-AO only). No shader
+// recompile across enable/disable.
+
+interface SsaoFallbackResources {
+  readonly texture: Texture;
+  readonly view: TextureView;
+  readonly sampler: Sampler;
+}
+
+const fallbackCache = new WeakMap<RenderSystemRuntime, SsaoFallbackResources>();
+
+/**
+ * Lazily allocate the 1x1 r8unorm white fallback texture + a sampler for
+ * SSAO disabled / resource-missing path. Cached per RenderSystemRuntime so
+ * subsequent calls reuse the same resources (charter P5 one-owner).
+ *
+ * Returns `null` if `device.createTexture` / `createTextureView` /
+ * `createSampler` / `queue.writeTexture` fails; the caller (createBindGroup)
+ * propagates the structured RhiError that landed on `runtime.errorRegistry`.
+ */
+export function getOrCreateSsaoFallbackTexture(
+  runtime: RenderSystemRuntime,
+): SsaoFallbackResources | null {
+  const cached = fallbackCache.get(runtime);
+  if (cached !== undefined) return cached;
+
+  const device = runtime.device;
+  const texRes = device.createTexture({
+    label: 'hdrp-ssao-fallback-white',
+    size: { width: 1, height: 1, depthOrArrayLayers: 1 },
+    mipLevelCount: 1,
+    sampleCount: 1,
+    dimension: '2d',
+    format: 'r8unorm',
+    usage: GPU_TEXTURE_USAGE_TEXTURE_BINDING | GPU_TEXTURE_USAGE_COPY_DST,
+    textureBindingViewDimension: undefined,
+  });
+  if (!texRes.ok) {
+    runtime.errorRegistry.fire(texRes.error);
+    return null;
+  }
+
+  // r8unorm: a single byte 0xFF normalizes to 1.0 (white => AO = 1.0).
+  const whitePixel = new Uint8Array([255]);
+  const writeRes = device.queue.writeTexture(
+    {
+      texture: texRes.value,
+      mipLevel: 0,
+      origin: { x: 0, y: 0, z: 0 },
+    },
+    whitePixel,
+    { offset: 0, bytesPerRow: 256, rowsPerImage: 1 },
+    { width: 1, height: 1, depthOrArrayLayers: 1 },
+  );
+  if (!writeRes.ok) {
+    runtime.errorRegistry.fire(writeRes.error);
+    return null;
+  }
+
+  const viewRes = device.createTextureView(texRes.value, {
+    label: 'hdrp-ssao-fallback-white-view',
+    format: 'r8unorm',
+    dimension: '2d',
+    aspect: 'all',
+    baseMipLevel: 0,
+    mipLevelCount: 1,
+    baseArrayLayer: 0,
+    arrayLayerCount: 1,
+  });
+  if (!viewRes.ok) {
+    runtime.errorRegistry.fire(viewRes.error);
+    return null;
+  }
+
+  const samplerRes = device.createSampler({
+    label: 'hdrp-ssao-fallback-sampler',
+    magFilter: 'linear',
+    minFilter: 'linear',
+    mipmapFilter: 'linear',
+    addressModeU: 'clamp-to-edge',
+    addressModeV: 'clamp-to-edge',
+    addressModeW: 'clamp-to-edge',
+  });
+  if (!samplerRes.ok) {
+    runtime.errorRegistry.fire(samplerRes.error);
+    return null;
+  }
+
+  const resources: SsaoFallbackResources = {
+    texture: texRes.value,
+    view: viewRes.value,
+    sampler: samplerRes.value,
+  };
+  fallbackCache.set(runtime, resources);
+  return resources;
+}
+
 /**
  * SSAO GPU resources owned by this module (plan-strategy D-1, D-4).
  *
@@ -66,7 +225,7 @@ const cache = new WeakMap<RenderSystemRuntime, SsaoBuffers>();
  * On `device.createBuffer` / `device.createTexture` failure, fires a
  * structured error on the runtime's error registry and returns `null`.
  *
- * @returns SsaoBuffers on success, null if any allocation fails.
+ * @returns SsaoBuffers on success, null if an allocation fails.
  */
 export function getOrCreateSsaoBuffers(runtime: RenderSystemRuntime): SsaoBuffers | null {
   const cached = cache.get(runtime);
@@ -137,7 +296,7 @@ export function getOrCreateSsaoBuffers(runtime: RenderSystemRuntime): SsaoBuffer
   // follows the createRenderer.ts fallback-pixel pattern (line 4330).
   const noiseCopyRes = device.queue.writeTexture(
     {
-      texture: noiseTexRes.value as unknown as GPUTexture,
+      texture: noiseTexRes.value,
       mipLevel: 0,
       origin: { x: 0, y: 0, z: 0 },
     },

package/src/systems/skin-palette-allocator.ts

@@ -30,11 +30,11 @@
 //     amortized across frames).
 //
 //   Concept that does NOT branch by path: `bindingWindowBytes`. It is
-//   the static `pbr-skin-mesh-array-bgl @binding(1/2)` BG entry size,
+//   the static `pbr-skin-mesh-array-bgl @binding(1)` BG entry size,
 //   identical on both paths (WGSL declares the same layout). Record-
-//   stage uses it verbatim for both palettes when constructing the BG.
-//   dynOffset[1/2] on the uniform path is always 0 (entry size already
-//   equals buffer size); on the storage path both walk 0, 1536, 3072, ... .
+//   stage uses it verbatim when constructing the BG. dynOffset[1]
+//   on the uniform path is always 0 (entry size already equals buffer
+//   size); on the storage path it walks 0, 1536, 3072, ... .
 //
 // CPU pre-multiply (path-agnostic): writeJointPalette(slice, ibm, jointWorld)
 //   -> mat4 per joint: M_i = joint_world_i * IBM_i
@@ -46,17 +46,17 @@
 import type { Mat4 } from '@forgeax/engine-math';
 import { mat4 } from '@forgeax/engine-math';
 import type { Buffer, RhiDevice } from '@forgeax/engine-rhi';
-import { SkinPaletteOverflowError } from '../errors';
+import { SkinPaletteOverflowError } from '../errors/render';
 import {
   GPU_BUFFER_USAGE_COPY_DST,
   GPU_BUFFER_USAGE_STORAGE,
   GPU_BUFFER_USAGE_UNIFORM,
 } from '../gpu-usage';
-import type { SkinPaletteSlice } from '../render-system-extract';
+import type { SkinPaletteSlice } from './skin-palette-types';
 
 const MAT4_BYTES = 64; // 16 f32 * 4 bytes
-// MAX_JOINTS = 255 matches `pbr-skin-mesh-array-bgl @binding(1/2)` static BG
-// entry size: 255 * 64 = 16320 B. The number is the MAX joints any single
+// MAX_JOINTS = 255 matches `pbr-skin-mesh-array-bgl @binding(1)` static BG
+// entry size: 255 * 64 = 16320 B. The number is the MAX joints a single
 // skinned entity may have. On the storage path the shared buffer holds
 // many entities back-to-back; on the uniform path each entity owns one
 // 16320 B buffer.
@@ -73,7 +73,7 @@ const PALETTE_OFFSET_ALIGN = 256;
 
 export interface SkinPaletteAllocator {
   /**
-   * Static BG entry size for `pbr-skin-mesh-array-bgl @binding(1/2)`. Always
+   * Static BG entry size for `pbr-skin-mesh-array-bgl @binding(1)`. Always
    * `MAX_JOINTS * 64 = 16320`; consumers (record stage) bind this size
    * when building the BG. Path-independent.
    */
@@ -112,8 +112,6 @@ export interface SkinPaletteAllocator {
     ibms: readonly Float32Array[],
     jointWorlds: readonly Mat4[],
   ): void;
-  /** Upload the renderer projection's previous successful-submit palette. */
-  writePreviousJointPalette(slice: SkinPaletteSlice, jointMatrices: Float32Array): void;
   /**
    * Reset for next frame. Storage path: cursor rewinds, shared buffer
    * stays. Uniform path: per-entity buffer cursor rewinds (pool entries
@@ -129,7 +127,6 @@ export function createSkinPaletteAllocator(
 ): SkinPaletteAllocator {
   // Storage path: shared buffer state.
   let storageBuffer: Buffer | null = null;
-  let previousStorageBuffer: Buffer | null = null;
   let storageCapacity = 0;
   let storageCursor = 0;
 
@@ -140,12 +137,10 @@ export function createSkinPaletteAllocator(
   // entity count grows past the historical max). 16320 B / entry
   // bounded by maxUniformBufferBindingSize (>= 16384 by spec floor).
   const pool: Buffer[] = [];
-  const previousPool: Buffer[] = [];
   let poolCursor = 0;
 
   function ensureStorageCapacity(needed: number): void {
-    if (storageBuffer !== null && previousStorageBuffer !== null && needed <= storageCapacity)
-      return;
+    if (storageBuffer !== null && needed <= storageCapacity) return;
     let newCapacity = storageCapacity === 0 ? BINDING_WINDOW_BYTES : storageCapacity;
     while (newCapacity < needed) {
       // 1.5x grow, then next multiple of 256 for alignment (plan-strategy D-4).
@@ -161,35 +156,27 @@ export function createSkinPaletteAllocator(
       mappedAtCreation: false,
     });
     if (!bufRes.ok) throw bufRes.error;
-    const previousBufRes = device.createBuffer({
-      label: 'skin-palette-previous',
-      size: newCapacity,
-      usage: GPU_BUFFER_USAGE_STORAGE | GPU_BUFFER_USAGE_COPY_DST,
-      mappedAtCreation: false,
-    });
-    if (!previousBufRes.ok) throw previousBufRes.error;
     storageBuffer = bufRes.value;
-    previousStorageBuffer = previousBufRes.value;
     storageCapacity = newCapacity;
   }
 
-  function acquirePoolBuffer(buffers: Buffer[], label: string): Buffer {
-    if (poolCursor < buffers.length) {
-      const reused = buffers[poolCursor];
-      // biome-ignore lint/style/noNonNullAssertion: poolCursor < buffers.length guarantees the slot is set
+  function acquirePoolBuffer(): Buffer {
+    if (poolCursor < pool.length) {
+      const reused = pool[poolCursor];
+      // biome-ignore lint/style/noNonNullAssertion: poolCursor < pool.length guarantees the slot is set
       return reused!;
     }
     if (BINDING_WINDOW_BYTES > maxBindingSize) {
       throw new SkinPaletteOverflowError(BINDING_WINDOW_BYTES, maxBindingSize);
     }
     const bufRes = device.createBuffer({
-      label,
+      label: 'skin-palette',
       size: BINDING_WINDOW_BYTES,
       usage: GPU_BUFFER_USAGE_UNIFORM | GPU_BUFFER_USAGE_COPY_DST,
       mappedAtCreation: false,
     });
     if (!bufRes.ok) throw bufRes.error;
-    buffers.push(bufRes.value);
+    pool.push(bufRes.value);
     return bufRes.value;
   }
 
@@ -205,8 +192,6 @@ export function createSkinPaletteAllocator(
       ensureStorageCapacity(needed);
       // biome-ignore lint/style/noNonNullAssertion: ensureStorageCapacity throws if buffer cannot be created
       const buffer = storageBuffer!;
-      // biome-ignore lint/style/noNonNullAssertion: ensureStorageCapacity creates the pair atomically or throws
-      const previousBuffer = previousStorageBuffer!;
       // Cursor advances by the actual joint footprint, then rounds up to
       // PALETTE_OFFSET_ALIGN so the NEXT slice's byteOffset stays a valid
       // dynamic offset (WebGPU requires 256-byte alignment). Slices still pack
@@ -216,25 +201,12 @@ export function createSkinPaletteAllocator(
       storageCursor =
         (offset + jointCount * MAT4_BYTES + (PALETTE_OFFSET_ALIGN - 1)) &
         ~(PALETTE_OFFSET_ALIGN - 1);
-      return {
-        jointCount,
-        jointMatrices: new Float32Array(jointCount * 16),
-        byteOffset: offset,
-        buffer,
-        previousBuffer,
-      };
+      return { jointCount, byteOffset: offset, buffer };
     }
     // Uniform fallback: each slice gets its own 16320 B UBO.
-    const buffer = acquirePoolBuffer(pool, 'skin-palette');
-    const previousBuffer = acquirePoolBuffer(previousPool, 'skin-palette-previous');
+    const buffer = acquirePoolBuffer();
     poolCursor += 1;
-    return {
-      jointCount,
-      jointMatrices: new Float32Array(jointCount * 16),
-      byteOffset: 0,
-      buffer,
-      previousBuffer,
-    };
+    return { jointCount, byteOffset: 0, buffer };
   }
 
   function writeJointPalette(
@@ -247,37 +219,23 @@ export function createSkinPaletteAllocator(
     const payload = new Float32Array(count * 16);
     const temp = mat4.create();
     const ibm = mat4.create();
-    const ibmNums = ibm as unknown as number[];
     for (let i = 0; i < count; i++) {
       const ibmFlat = ibms[i];
       const jw = jointWorlds[i];
       if (ibmFlat === undefined || jw === undefined) continue;
       for (let k = 0; k < 16; k++) {
-        ibmNums[k] = ibmFlat[k] ?? 0;
+        ibm[k] = ibmFlat[k] ?? 0;
       }
       mat4.multiply(temp, jw, ibm);
       const base = i * 16;
       for (let j = 0; j < 16; j++) {
-        payload[base + j] = (temp as unknown as number[])[j] ?? 0;
+        payload[base + j] = temp[j] ?? 0;
       }
     }
-    slice.jointMatrices.set(payload);
     const res = device.queue.writeBuffer(slice.buffer, slice.byteOffset, payload);
     if (!res.ok) throw res.error;
   }
 
-  function writePreviousJointPalette(slice: SkinPaletteSlice, jointMatrices: Float32Array): void {
-    const count = Math.min(slice.jointCount * 16, jointMatrices.length);
-    if (count === 0) return;
-    const payload = jointMatrices.subarray(0, count);
-    const result = device.queue.writeBuffer(
-      slice.previousBuffer ?? slice.buffer,
-      slice.byteOffset,
-      payload,
-    );
-    if (!result.ok) throw result.error;
-  }
-
   function resetForFrame(): void {
     storageCursor = 0;
     poolCursor = 0;
@@ -288,7 +246,6 @@ export function createSkinPaletteAllocator(
     useStorageBuffer,
     allocateSlice,
     writeJointPalette,
-    writePreviousJointPalette,
     resetForFrame,
   };
 }

package/src/systems/skin-palette-types.ts

@@ -0,0 +1,14 @@
+import type { Buffer } from '@forgeax/engine-rhi';
+
+/**
+ * Per-draw palette slice metadata shared by the extract producer and the
+ * palette allocator. The slice carries the buffer identity so storage and
+ * uniform fallback paths converge at the record binding owner.
+ */
+export interface SkinPaletteSlice {
+  readonly jointCount: number;
+  /** Byte offset into buffer; uniform fallback slices always use zero. */
+  readonly byteOffset: number;
+  /** GPU buffer containing the slice's joint matrices. */
+  readonly buffer: Buffer;
+}

package/src/systems/transparent-sort-config.ts

@@ -57,9 +57,8 @@
 // other engine resource consumer).
 
 import type { World } from '@forgeax/engine-ecs';
-import type { Result } from '@forgeax/engine-types';
-import { err, ok } from '@forgeax/engine-types';
-import { ResourceInvalidValueError } from '../errors';
+import { ResourceInvalidValueError } from '@forgeax/engine-ecs/projection';
+import { err, ok, type Result } from '@forgeax/engine-types';
 
 // ────────────────────────────────────────────────────────────────────────────
 // POD interface + KV key + 3 named mode constants
@@ -82,6 +81,20 @@ export interface TransparentSortConfig {
   readonly yzAlpha: number;
 }
 
+/** Extract-stage POD consumed by the transparent-sort owner. */
+export interface TransparentEntry {
+  readonly entityIndex: number;
+  readonly materialHandle: number;
+  readonly layer: number;
+  readonly posX: number;
+  readonly posY: number;
+  readonly posZ: number;
+  readonly pivotY: number;
+  readonly sizeY: number;
+  readonly sortKey?: number | undefined;
+  readonly renderableIndex?: number | undefined;
+}
+
 /** World resource key for `TransparentSortConfig` KV entry. */
 export const TRANSPARENT_SORT_CONFIG_KEY = 'TransparentSortConfig' as const;
 
@@ -97,6 +110,15 @@ export const TRANSPARENT_SORT_MODE_LAYER_YZ = 2;
 /** 3D distance: sortValue = -(dist^2) to cameraPos, back-to-front (far first). */
 export const TRANSPARENT_SORT_MODE_DISTANCE = 3;
 
+/** Grouped authoring values and the single configuration operation. */
+export const TransparentSort = Object.freeze({
+  layerZ: TRANSPARENT_SORT_MODE_LAYER_Z,
+  layerY: TRANSPARENT_SORT_MODE_LAYER_Y,
+  layerYZ: TRANSPARENT_SORT_MODE_LAYER_YZ,
+  distance: TRANSPARENT_SORT_MODE_DISTANCE,
+  configure: setTransparentSortConfig,
+} as const);
+
 // ────────────────────────────────────────────────────────────────────────────
 // Internal: silent default + mode validity check
 // ────────────────────────────────────────────────────────────────────────────