@forgeax/engine-render 0.1.21 → 0.1.24

package/src/cluster-binner.ts

@@ -27,6 +27,7 @@
 
 import { type Mat4, type Vec3, vec3 } from '@forgeax/engine-math';
 import { err, ok, type Result } from '@forgeax/engine-rhi';
+import type { RectAreaWorldFrame } from './render-system-extract';
 
 // ── types ──────────────────────────────────────────────────────────────────
 
@@ -174,6 +175,36 @@ export function deriveCullingRadius(range: number, intensity: number, threshold
   return Math.min(derived, 1000);
 }
 
+/** Conservative bounding-sphere radius for a finite Rect and its light range. */
+export function rectAreaClusterRadius(frame: RectAreaWorldFrame, range: number): number {
+  return Math.max(0, range) + Math.hypot(frame.halfWidth, frame.halfHeight);
+}
+
+/** Test the finite Rect's closest-point distance against a strict range window. */
+export function rectAreaIsInRange(
+  frame: RectAreaWorldFrame,
+  point: ArrayLike<number>,
+  range: number,
+): boolean {
+  const toPoint = vec3.create(
+    (point[0] ?? 0) - (frame.center[0] ?? 0),
+    (point[1] ?? 0) - (frame.center[1] ?? 0),
+    (point[2] ?? 0) - (frame.center[2] ?? 0),
+  );
+  const localX = Math.min(
+    frame.halfWidth,
+    Math.max(-frame.halfWidth, vec3.dot(toPoint, frame.axisX)),
+  );
+  const localY = Math.min(
+    frame.halfHeight,
+    Math.max(-frame.halfHeight, vec3.dot(toPoint, frame.axisY)),
+  );
+  const dx = (toPoint[0] ?? 0) - (frame.axisX[0] ?? 0) * localX - (frame.axisY[0] ?? 0) * localY;
+  const dy = (toPoint[1] ?? 0) - (frame.axisX[1] ?? 0) * localX - (frame.axisY[1] ?? 0) * localY;
+  const dz = (toPoint[2] ?? 0) - (frame.axisX[2] ?? 0) * localX - (frame.axisY[2] ?? 0) * localY;
+  return dx * dx + dy * dy + dz * dz < range * range;
+}
+
 // ── view_z_to_z_slice ──────────────────────────────────────────────────────
 
 /**

package/src/components/__tests__/lighting-authoring.unit.test.ts

@@ -0,0 +1,39 @@
+import { describe, expect, it } from 'vitest';
+import {
+  LightProbe,
+  RectAreaLight,
+  SpotLight,
+  validateLightProbeData,
+  validateRectAreaLightData,
+} from '../index';
+
+describe('lighting authoring contracts', () => {
+  it('exposes only the declared Rect, Spot modifier, and Probe fields', () => {
+    expect(Object.keys(RectAreaLight.fields)).toEqual([
+      'color',
+      'intensity',
+      'width',
+      'height',
+      'range',
+    ]);
+    expect(Object.keys(LightProbe.fields)).toEqual(['irradiance', 'radius']);
+    expect(SpotLight.fields.iesProfile.type).toBe('shared<IesProfileAsset>');
+    expect(SpotLight.fields.cookie.type).toBe('shared<TextureAsset>');
+    expect(SpotLight.fields.rollDeg.default).toBe(0);
+  });
+
+  it('keeps defaults and rejects invalid Rect/Probe facts before rendering', () => {
+    expect(RectAreaLight.fields.width.default).toBe(1);
+    expect(RectAreaLight.fields.height.default).toBe(1);
+    expect(LightProbe.fields.irradiance.type).toBe('array<f32, 27>');
+    expect(LightProbe.fields.radius.default).toBe(1e-4);
+
+    expect(validateRectAreaLightData({}).ok).toBe(true);
+    expect(validateRectAreaLightData({ width: 0 }).ok).toBe(false);
+    expect(validateRectAreaLightData({ intensity: Number.NaN }).ok).toBe(false);
+    expect(validateLightProbeData({ irradiance: new Float32Array(26), radius: 1 }).ok).toBe(false);
+    expect(validateLightProbeData({ irradiance: new Float32Array(27), radius: 1e-5 }).ok).toBe(
+      false,
+    );
+  });
+});

package/src/components/__tests__/rect-area-light.unit.test.ts

@@ -0,0 +1,33 @@
+import { describe, expect, it } from 'vitest';
+import { buildRectAreaWorldFrame, rectAreaFacesPoint } from '../../render-system-extract';
+
+describe('RectAreaLight world frame', () => {
+  it('normalizes world axes while preserving authored half extents', () => {
+    const frame = buildRectAreaWorldFrame({
+      center: [1, 2, 3],
+      axisX: [0, 2, 0],
+      axisY: [-3, 0, 0],
+      width: 4,
+      height: 2,
+    });
+
+    expect(Array.from(frame.axisX)).toEqual([0, 1, 0]);
+    expect(Array.from(frame.axisY)).toEqual([-1, 0, 0]);
+    expect(Array.from(frame.normal)).toEqual([0, 0, 1]);
+    expect(frame.halfWidth).toBe(2);
+    expect(frame.halfHeight).toBe(1);
+  });
+
+  it('defines the front from the world-axis cross product', () => {
+    const frame = buildRectAreaWorldFrame({
+      center: [0, 0, 0],
+      axisX: [1, 0, 0],
+      axisY: [0, 1, 0],
+      width: 2,
+      height: 2,
+    });
+
+    expect(rectAreaFacesPoint(frame, [0, 0, 1])).toBe(true);
+    expect(rectAreaFacesPoint(frame, [0, 0, -1])).toBe(false);
+  });
+});

package/src/components/camera.ts

@@ -14,7 +14,7 @@
 //                      outside M3 scope — the short-name mat4.perspective
 //                      already writes [0, 1] NDC, matching the ortho branch.
 //   projection === 1 → orthographic path; RenderSystem builds
-//                      mat4.orthographic(out, left, right, bottom, top,
+//                      mat4.orthographic(out, left, right, top, bottom,
 //                      near, far) (WebGPU [0, 1] NDC; same z convention).
 //
 // Naming convention: forgeax uses the bare `Camera` name (no `Component`

package/src/components/index.ts

@@ -5,6 +5,8 @@ export * from './directional-light';
 export * from './fog';
 export { Instances, type InstancesData } from './instances';
 export { Layer } from './layer';
+export * from './light-helpers';
+export { LightProbe } from './light-probe';
 export { Lines } from './lines';
 export * from './mesh-filter';
 export * from './mesh-renderer';
@@ -18,6 +20,7 @@ export {
   pointShapeFromU32,
 } from './points';
 export { PostProcessParams } from './post-process-params';
+export { RectAreaLight } from './rect-area-light';
 export * from './reflection-probe';
 export {
   SceneInstance,

package/src/components/light-helpers.ts

@@ -14,7 +14,7 @@
 // transparent to AI users) + D-S5 (Layer 1 host-side range = 0 ->
 // invRangeSquared = 1e8 protects the 0 * Infinity = NaN intermediate).
 
-import { err, ok, type Result } from '@forgeax/engine-types';
+import { err, ok, R_MIN, type Result } from '@forgeax/engine-types';
 import { SpawnLightInvalidBoundsError } from '../errors/ecs-validation';
 import { ShadowInvalidConfigError } from '../errors/render';
 import { DirectionalShadowFilterValue } from './directional-shadow-filter';
@@ -264,3 +264,54 @@ export function validatePointLightShadowData(
   }
   return ok(undefined);
 }
+
+/** Validate rectangular area-light authoring facts before renderer admission. */
+export function validateRectAreaLightData(
+  data: Readonly<Record<string, unknown>>,
+): LightValidationResult {
+  const intensity = (data.intensity as number | undefined) ?? 1;
+  if (typeof intensity !== 'number' || !Number.isFinite(intensity) || intensity < 0) {
+    return err(new SpawnLightInvalidBoundsError('RectAreaLight', 'intensity', intensity));
+  }
+  const color = (data.color as ArrayLike<number> | undefined) ?? [1, 1, 1];
+  if (
+    color.length !== 3 ||
+    Array.from(color).some(
+      (value) => typeof value !== 'number' || !Number.isFinite(value) || value < 0,
+    )
+  ) {
+    return err(new SpawnLightInvalidBoundsError('RectAreaLight', 'color', Array.from(color)));
+  }
+  for (const field of ['width', 'height', 'range'] as const) {
+    const value = (data[field] as number | undefined) ?? (field === 'range' ? 10 : 1);
+    if (typeof value !== 'number' || !Number.isFinite(value) || value <= 0) {
+      return err(new SpawnLightInvalidBoundsError('RectAreaLight', field, value));
+    }
+  }
+  return ok(undefined);
+}
+
+/** Validate the fixed 27-value SH payload and minimum finite radius. */
+export function validateLightProbeData(
+  data: Readonly<Record<string, unknown>>,
+): LightValidationResult {
+  const irradiance = data.irradiance as ArrayLike<number> | undefined;
+  if (
+    irradiance === undefined ||
+    irradiance.length !== 27 ||
+    Array.from(irradiance).some((value) => typeof value !== 'number' || !Number.isFinite(value))
+  ) {
+    return err(
+      new SpawnLightInvalidBoundsError(
+        'LightProbe',
+        'irradiance',
+        irradiance === undefined ? [] : Array.from(irradiance),
+      ),
+    );
+  }
+  const radius = (data.radius as number | undefined) ?? R_MIN;
+  if (typeof radius !== 'number' || !Number.isFinite(radius) || radius < R_MIN) {
+    return err(new SpawnLightInvalidBoundsError('LightProbe', 'radius', radius));
+  }
+  return ok(undefined);
+}

package/src/components/light-probe.ts

@@ -0,0 +1,13 @@
+// @forgeax/engine-render - local diffuse LightProbe authoring facts.
+
+import { defineComponent } from '@forgeax/engine-ecs';
+import { R_MIN } from '@forgeax/engine-types';
+
+/**
+ * Local diffuse irradiance probe. Transform supplies position; the 27 SH
+ * values are nine RGB groups in the fixed real-SH order.
+ */
+export const LightProbe = defineComponent('LightProbe', {
+  irradiance: { type: 'array<f32, 27>' },
+  radius: { type: 'f32', default: R_MIN },
+});

package/src/components/rect-area-light.ts

@@ -0,0 +1,15 @@
+// @forgeax/engine-render - single-sided rectangular area-light authoring facts.
+
+import { defineComponent } from '@forgeax/engine-ecs';
+
+/**
+ * Single-sided rectangular area light. Transform supplies the center and
+ * world orientation; width and height remain authored emitter dimensions.
+ */
+export const RectAreaLight = defineComponent('RectAreaLight', {
+  color: { type: 'array<f32, 3>', default: new Float32Array([1, 1, 1]) },
+  intensity: { type: 'f32', default: 1 },
+  width: { type: 'f32', default: 1 },
+  height: { type: 'f32', default: 1 },
+  range: { type: 'f32', default: 10 },
+});

package/src/components/scene-instance.ts

@@ -94,6 +94,12 @@ export interface SceneInstanceState {
    */
   readonly source: import('@forgeax/engine-types').Handle<'SceneAsset', 'shared'>;
 
+  /** Author scene identity used by instance-relative SceneEntityRef resolution. */
+  readonly sceneSourceKey?: string;
+
+  /** Stable author bindingKey to live Entity mapping for this concrete instance. */
+  readonly bindings: Map<string, EntityHandle>;
+
   /**
    * Reverse mapping (live `Entity` -> source `LocalEntityId`). Used by
    * `world.setSceneOverride` to validate the member entity belongs to this

package/src/components/spot-light.ts

@@ -124,6 +124,9 @@ export const SpotLight = defineComponent('SpotLight', {
   range: { type: 'f32', default: 10.0 },
   innerConeDeg: { type: 'f32', default: 0 },
   outerConeDeg: { type: 'f32', default: 45 },
+  iesProfile: { type: 'shared<IesProfileAsset>' },
+  cookie: { type: 'shared<TextureAsset>' },
+  rollDeg: { type: 'f32', default: 0 },
   // Shadow opt-out gate: defaults to true so zero-config spawns cast shadows.
   castShadow: { type: 'bool', default: true },
   // 7 shadow fields aligned with the shared light shadow vocabulary.

package/src/debug-draw-glue.ts

@@ -23,8 +23,8 @@ export function addTypedDebugOverlayPass(
           projection,
           frame.camera.orthoLeft,
           frame.camera.orthoRight,
-          frame.camera.orthoBottom,
           frame.camera.orthoTop,
+          frame.camera.orthoBottom,
           frame.camera.near,
           frame.camera.far,
         );

package/src/device/__tests__/extended-lighting-recovery.unit.test.ts

@@ -0,0 +1,24 @@
+import { describe, expect, it } from 'vitest';
+import {
+  createExtendedLightingResourceCandidate,
+  inspectExtendedLightingResources,
+} from '../../prepare/extended-lighting/resources';
+import { DeviceScope } from '../device-scope';
+
+describe('extended lighting device recovery', () => {
+  it('retires the old scope and rebuilds one accepted resource generation', async () => {
+    const oldScope = DeviceScope.create(8, 'renderer');
+    const oldResource = oldScope.ref('texture', { id: 'old' });
+    const candidate = await createExtendedLightingResourceCandidate({
+      device: undefined,
+      scope: oldScope,
+      iesSliceCount: 0,
+      cookieSliceCount: 0,
+      cookieMatrices: 0,
+    });
+
+    expect(candidate.ok).toBe(false);
+    expect(oldResource.isCurrent(oldScope)).toBe(true);
+    expect(inspectExtendedLightingResources(oldScope).generation).toBe(8);
+  });
+});

package/src/device/device-scope.ts

@@ -46,6 +46,17 @@ interface OwnedResource {
   readonly cleanup: (value: unknown) => void | Promise<void>;
 }
 
+function idempotentCleanup<T>(
+  cleanup: (value: T) => void | Promise<void>,
+): (value: T) => void | Promise<void> {
+  let cleaned = false;
+  return (value: T) => {
+    if (cleaned) return;
+    cleaned = true;
+    return cleanup(value);
+  };
+}
+
 export class DeviceScope {
   readonly generation: number;
   readonly owner: string;
@@ -117,7 +128,7 @@ export class DeviceScope {
     const ref = new DeviceResourceRef(kind, this.owner, this.generation, value);
     this.resources.push({
       ref: ref as DeviceResourceRef<unknown>,
-      cleanup: cleanup as (resource: unknown) => void | Promise<void>,
+      cleanup: idempotentCleanup(cleanup) as (resource: unknown) => void | Promise<void>,
     });
     return ref;
   }
@@ -142,9 +153,21 @@ export class DeviceScope {
     if (this.lifecycleState === 'active') this.lifecycleState = 'retiring';
   }
 
+  private clearChildren(): void {
+    for (const child of [...this.children].reverse()) {
+      child.retire();
+    }
+  }
+
+  private detachChild(child: DeviceScope): void {
+    const index = this.children.indexOf(child);
+    if (index >= 0) this.children.splice(index, 1);
+  }
+
   retire(): void {
     if (this.lifecycleState !== 'active' && this.lifecycleState !== 'retiring') return;
     this.lifecycleState = 'retiring';
+    this.clearChildren();
     this._clearResources();
     this.lifecycleState = 'retired';
   }
@@ -152,12 +175,14 @@ export class DeviceScope {
   abandon(): void {
     if (this.lifecycleState !== 'active') return;
     this.lifecycleState = 'abandoned';
+    this.clearChildren();
     this._clearResources();
   }
 
   dispose(): void {
     if (this.lifecycleState === 'disposed') return;
     this.lifecycleState = 'disposed';
+    this.clearChildren();
     this._clearResources();
   }
 
@@ -177,6 +202,9 @@ export class DeviceScope {
       replacement.dispose();
       return transaction.failure('dispose');
     }
+    // The replacement is now the new owner. Detach it before retiring the
+    // old parent so parent cleanup cannot retire the just-published child.
+    this.detachChild(replacement);
     this.retire();
     return ok(replacement);
   }
@@ -217,6 +245,7 @@ export interface LifecycleTransactionOptions {
 interface CreatedResource {
   readonly spec: LifecycleResourceSpec<unknown>;
   readonly value: unknown;
+  readonly cleanup: (value: unknown) => void | Promise<void>;
 }
 
 export class LifecycleTransaction {
@@ -250,10 +279,10 @@ export class LifecycleTransaction {
         }
         const value = await spec.create();
         if (!this.scope.isAlive()) {
-          await this.cleanupOne(spec, value, created);
+          await this.cleanupOne(value, created, idempotentCleanup(spec.cleanup));
           return this.failure('dispose');
         }
-        created.push({ spec, value });
+        created.push({ spec, value, cleanup: idempotentCleanup(spec.cleanup) });
       } catch (cause) {
         const cleanupFailures = await this.cleanupCreated(created);
         return this.failure('create', spec.kind, cleanupFailures, cause);
@@ -296,7 +325,7 @@ export class LifecycleTransaction {
       const item = created[index];
       if (item === undefined) continue;
       try {
-        await item.spec.cleanup(item.value);
+        await item.cleanup(item.value);
       } catch (cause) {
         failures.push({ resourceKind: item.spec.kind, cause });
       }
@@ -305,13 +334,13 @@ export class LifecycleTransaction {
   }
 
   private async cleanupOne(
-    spec: LifecycleResourceSpec<unknown>,
     value: unknown,
     created: readonly CreatedResource[],
+    cleanup: (value: unknown) => void | Promise<void>,
   ): Promise<void> {
     await this.cleanupCreated(created);
     try {
-      await spec.cleanup(value);
+      await cleanup(value);
     } catch {
       // The terminal dispose result is intentionally bounded; prior cleanup
       // evidence remains in the transaction failure shape.