@forgeax/engine-render 0.1.4 → 0.1.7

package/src/__tests__/visibility-instances.integration.test.ts

@@ -1,24 +1,20 @@
+import { HANDLE_CUBE } from '@forgeax/engine-assets-runtime';
 import { World } from '@forgeax/engine-ecs';
-import { createPrimitiveMesh } from '@forgeax/engine-geometry';
-import {
-  extractFrames,
-  Instances,
-  MeshFilter,
-  MeshRenderer,
-  Visibility,
-  VisibilityStateValue,
-} from '@forgeax/engine-render/internal';
 import { Transform } from '@forgeax/engine-scene';
 import { describe, expect, it } from 'vitest';
+import { Instances } from '../components/instances';
+import { MeshFilter } from '../components/mesh-filter';
+import { MeshRenderer } from '../components/mesh-renderer';
+import { Visibility, VisibilityStateValue } from '../components/visibility';
+import { extractFrames } from '../render-system-extract';
 
 const IDENTITY = new Float32Array([1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1]);
 
 function spawnInstance(world: World, state: keyof typeof VisibilityStateValue) {
-  const meshHandle = world.internSharedRef('MeshAsset', createPrimitiveMesh('cube').unwrap());
   return world
     .spawn(
       { component: Transform, data: {} },
-      { component: MeshFilter, data: { assetHandle: meshHandle } },
+      { component: MeshFilter, data: { assetHandle: HANDLE_CUBE } },
       { component: MeshRenderer, data: {} },
       { component: Instances, data: { transforms: new Float32Array(IDENTITY) } },
       { component: Visibility, data: { state: VisibilityStateValue[state] } },

package/src/__tests__/visibility-multi-world.integration.test.ts

@@ -1,12 +1,31 @@
 import { World } from '@forgeax/engine-ecs';
-import {
-  extractFrames,
-  resolveVisibility,
-  Visibility,
-  VisibilityStateValue,
-} from '@forgeax/engine-render/internal';
 import { ChildOf } from '@forgeax/engine-scene';
 import { describe, expect, it } from 'vitest';
+import { Visibility, VisibilityStateValue } from '../components/visibility';
+import { resolveVisibility } from '../extract/visibility';
+import type { MaterialSnapshot, RenderableSnapshot } from '../render-system-extract';
+import { extractFrames } from '../render-system-extract';
+import { RenderScene } from '../scene/render-scene';
+
+const sceneMaterial = {} as MaterialSnapshot;
+
+function sceneSnapshot(worldId: number, entityKey: number, x: number): RenderableSnapshot {
+  const world = new Float32Array(16);
+  world[0] = 1;
+  world[5] = 1;
+  world[10] = 1;
+  world[15] = 1;
+  world[12] = x;
+  return {
+    assetHandle: 1,
+    transform: { world },
+    material: sceneMaterial,
+    materials: [sceneMaterial],
+    materialBindingSources: ['engine-default'],
+    worldId,
+    entityKey,
+  };
+}
 
 describe('visibility World isolation', () => {
   it('does not share intent or effective results for equal entity handles', () => {
@@ -51,4 +70,17 @@ describe('visibility World isolation', () => {
     expect(frame.visibilitySnapshots[0]?.get(firstChild)?.effective).toBe('hidden');
     expect(frame.visibilitySnapshots[1]?.get(secondChild)?.effective).toBe('visible');
   });
+
+  it('keeps equal entity keys isolated when multi-world scene order changes', () => {
+    const scene = new RenderScene();
+    scene.reset([sceneSnapshot(0, 3, 1), sceneSnapshot(1, 3, 2)]);
+    const first = scene.slot(0, 3);
+    const second = scene.slot(1, 3);
+
+    scene.reset([sceneSnapshot(1, 3, 2), sceneSnapshot(0, 3, 1)]);
+
+    expect(scene.slot(0, 3)).toMatchObject({ slot: first?.slot, generation: first?.generation });
+    expect(scene.slot(1, 3)).toMatchObject({ slot: second?.slot, generation: second?.generation });
+    expect(scene.materialize().map((entry) => entry.worldId)).toEqual([1, 0]);
+  });
 });

package/src/__tests__/visibility-producer-matrix.integration.test.ts

@@ -1,22 +1,18 @@
+import { HANDLE_CUBE, HANDLE_QUAD, resolveTilesetRuntime } from '@forgeax/engine-assets-runtime';
 import { type EntityHandle, World } from '@forgeax/engine-ecs';
-import { createPrimitiveMesh, type PrimitiveMeshKind } from '@forgeax/engine-geometry';
-import {
-  extractFrames,
-  Instances,
-  MeshFilter,
-  MeshRenderer,
-  SpriteInstances,
-  TileLayer,
-  Tilemap,
-  tilemapChunkExtractSystem,
-  Visibility,
-  VisibilityStateValue,
-} from '@forgeax/engine-render/internal';
 import { ChildOf, Transform } from '@forgeax/engine-scene';
 import { Skin } from '@forgeax/engine-skinning';
-import type { TextureAsset, TilesetAsset } from '@forgeax/engine-types';
+import { type TilesetAsset, toShared } from '@forgeax/engine-types';
 import { describe, expect, it } from 'vitest';
-import { resolveTilesetRuntime } from '../tilemap/resolve-tileset-runtime';
+import { Instances } from '../components/instances';
+import { MeshFilter } from '../components/mesh-filter';
+import { MeshRenderer } from '../components/mesh-renderer';
+import { SpriteInstances } from '../components/sprite-instances';
+import { TileLayer } from '../components/tile-layer';
+import { Tilemap } from '../components/tilemap';
+import { Visibility, VisibilityStateValue } from '../components/visibility';
+import { extractFrames } from '../render-system-extract';
+import { tilemapChunkExtractSystem } from '../tilemap-chunk-extract-system';
 
 const IDENTITY = new Float32Array([1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1]);
 
@@ -25,16 +21,11 @@ type ProducerCase = {
   readonly setup: (world: World) => EntityHandle;
 };
 
-function primitiveMesh(world: World, kind: PrimitiveMeshKind) {
-  return world.internSharedRef('MeshAsset', createPrimitiveMesh(kind).unwrap());
-}
-
 function staticMesh(world: World): EntityHandle {
-  const meshHandle = primitiveMesh(world, 'cube');
   return world
     .spawn(
       { component: Transform, data: {} },
-      { component: MeshFilter, data: { assetHandle: meshHandle } },
+      { component: MeshFilter, data: { assetHandle: HANDLE_CUBE } },
       { component: MeshRenderer, data: {} },
       { component: Visibility, data: { state: VisibilityStateValue.hidden } },
     )
@@ -42,24 +33,22 @@ function staticMesh(world: World): EntityHandle {
 }
 
 function skinnedMesh(world: World): EntityHandle {
-  const meshHandle = primitiveMesh(world, 'cube');
   return world
     .spawn(
       { component: Transform, data: {} },
-      { component: MeshFilter, data: { assetHandle: meshHandle } },
+      { component: MeshFilter, data: { assetHandle: HANDLE_CUBE } },
       { component: MeshRenderer, data: {} },
-      { component: Skin, data: { joints: [] } },
+      { component: Skin, data: { skeleton: toShared<'SkeletonAsset'>(999), joints: [] } },
       { component: Visibility, data: { state: VisibilityStateValue.hidden } },
     )
     .unwrap();
 }
 
 function spriteMesh(world: World): EntityHandle {
-  const meshHandle = primitiveMesh(world, 'quad');
   return world
     .spawn(
       { component: Transform, data: {} },
-      { component: MeshFilter, data: { assetHandle: meshHandle } },
+      { component: MeshFilter, data: { assetHandle: HANDLE_QUAD } },
       { component: MeshRenderer, data: {} },
       {
         component: SpriteInstances,
@@ -71,11 +60,10 @@ function spriteMesh(world: World): EntityHandle {
 }
 
 function autoFoldInstances(world: World): EntityHandle {
-  const meshHandle = primitiveMesh(world, 'cube');
   return world
     .spawn(
       { component: Transform, data: {} },
-      { component: MeshFilter, data: { assetHandle: meshHandle } },
+      { component: MeshFilter, data: { assetHandle: HANDLE_CUBE } },
       { component: MeshRenderer, data: {} },
       { component: Instances, data: { transforms: IDENTITY } },
       { component: Visibility, data: { state: VisibilityStateValue.hidden } },
@@ -84,11 +72,10 @@ function autoFoldInstances(world: World): EntityHandle {
 }
 
 function explicitInstances(world: World): EntityHandle {
-  const meshHandle = primitiveMesh(world, 'cube');
   return world
     .spawn(
       { component: Transform, data: {} },
-      { component: MeshFilter, data: { assetHandle: meshHandle } },
+      { component: MeshFilter, data: { assetHandle: HANDLE_CUBE } },
       { component: MeshRenderer, data: {} },
       { component: Instances, data: { transforms: IDENTITY } },
       { component: Visibility, data: { state: VisibilityStateValue.hidden } },
@@ -107,17 +94,7 @@ function tilemap(world: World): EntityHandle {
     regions: [{ x: 0, y: 0, width: 16, height: 16 }],
     tiles: [{ regionIndex: 0 }],
   };
-  const atlas: TextureAsset = {
-    kind: 'texture',
-    width: 16,
-    height: 16,
-    format: 'rgba8unorm',
-    data: new Uint8Array(16 * 16 * 4),
-    colorSpace: 'srgb',
-    mipmap: false,
-  };
-  const lookup = (guid: string) =>
-    guid === 'test/tileset' ? tileset : guid === 'visibility/atlas' ? atlas : undefined;
+  const lookup = (guid: string) => (guid === 'test/tileset' ? tileset : undefined);
   const map = world
     .spawn(
       { component: Tilemap, data: { cols: 1, rows: 1, tileset: 'test/tileset' } },

package/src/__tests__/visibility-public-surface.test-d.ts

@@ -1,10 +1,5 @@
 import { World } from '@forgeax/engine-ecs';
-import {
-  Visibility,
-  type VisibilityState,
-  VisibilityStateValue,
-  visibilityStateFromU32,
-} from '@forgeax/engine-render';
+import { Visibility, type VisibilityState, VisibilityStateValue } from '@forgeax/engine-render';
 import { expectTypeOf } from 'vitest';
 
 const world = new World();
@@ -13,14 +8,20 @@ const entity = world.spawn({ component: Visibility, data: {} }).unwrap();
 expectTypeOf(VisibilityStateValue.inherited).toEqualTypeOf<0>();
 expectTypeOf(VisibilityStateValue.hidden).toEqualTypeOf<1>();
 expectTypeOf(VisibilityStateValue.visible).toEqualTypeOf<2>();
-expectTypeOf(visibilityStateFromU32(0)).toEqualTypeOf<VisibilityState | undefined>();
-expectTypeOf(visibilityStateFromU32(99)).toEqualTypeOf<VisibilityState | undefined>();
+expectTypeOf<VisibilityState>().toEqualTypeOf<'inherited' | 'hidden' | 'visible'>();
 
 world.set(entity, Visibility, { state: VisibilityStateValue.visible });
 
 const query = world.query({ read: [Visibility] }).unwrap();
 for (const row of query) {
   const rawState = row.get(Visibility).state;
-  const decodedState = visibilityStateFromU32(rawState ?? VisibilityStateValue.inherited);
+  const decodedState: VisibilityState | undefined =
+    rawState === VisibilityStateValue.hidden
+      ? 'hidden'
+      : rawState === VisibilityStateValue.visible
+        ? 'visible'
+        : rawState === VisibilityStateValue.inherited
+          ? 'inherited'
+          : undefined;
   expectTypeOf(decodedState).toEqualTypeOf<VisibilityState | undefined>();
 }

package/src/__tests__/visibility-resolver.unit.test.ts

@@ -1,7 +1,8 @@
 import { type EntityHandle, World } from '@forgeax/engine-ecs';
 import { ChildOf } from '@forgeax/engine-scene';
 import { describe, expect, it } from 'vitest';
-import { resolveVisibility, Visibility, VisibilityStateValue } from '../index';
+import { resolveVisibility } from '../extract/visibility';
+import { Visibility, VisibilityStateValue } from '../index';
 
 function spawn(
   world: World,

package/src/__tests__/visibility-resource-short-circuit.unit.test.ts

@@ -0,0 +1,80 @@
+import { AssetRegistry, HANDLE_CUBE } from '@forgeax/engine-assets-runtime';
+import { World } from '@forgeax/engine-ecs';
+import { Transform } from '@forgeax/engine-scene';
+import { toShared } from '@forgeax/engine-types';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { MeshFilter } from '../components/mesh-filter';
+import { MeshRenderer } from '../components/mesh-renderer';
+import { Visibility, VisibilityStateValue } from '../components/visibility';
+import { extractFrames } from '../render-system-extract';
+
+afterEach(() => {
+  vi.restoreAllMocks();
+});
+
+function captureWorldErrors(): Array<{ readonly code: string }> {
+  const errors: Array<{ readonly code: string }> = [];
+  vi.spyOn(console, 'error').mockImplementation((...args: unknown[]) => {
+    const error = args[args.length - 1];
+    if (typeof error === 'object' && error !== null && 'code' in error) {
+      errors.push(error as { readonly code: string });
+    }
+  });
+  return errors;
+}
+
+function codesForInvalidMaterial(state: number): { hidden: string[]; visible: string[] } {
+  const world = new World();
+  const assets = new AssetRegistry({} as never);
+  const errors = captureWorldErrors();
+  const entity = world
+    .spawn(
+      { component: Transform, data: {} },
+      { component: MeshFilter, data: { assetHandle: HANDLE_CUBE } },
+      { component: MeshRenderer, data: { materials: [toShared<'MaterialAsset'>(999)] } },
+      { component: Visibility, data: { state } },
+    )
+    .unwrap();
+
+  extractFrames([world], 0, assets);
+  const hiddenCodes = errors.map((error) => error.code);
+  world.set(entity, Visibility, { state: VisibilityStateValue.visible }).unwrap();
+  const beforeVisible = errors.length;
+  extractFrames([world], 0, assets);
+  return { hidden: hiddenCodes, visible: errors.slice(beforeVisible).map((error) => error.code) };
+}
+
+describe('visibility resource short circuit', () => {
+  it('does not resolve a bad override while hidden, then restores the fallback diagnostic', () => {
+    const codes = codesForInvalidMaterial(VisibilityStateValue.hidden);
+
+    expect(codes.hidden).toEqual([]);
+    expect(codes.visible).toContain('mesh-renderer-material-override-invalid');
+  });
+
+  it('does not validate override overflow while hidden', () => {
+    const world = new World();
+    const assets = new AssetRegistry({} as never);
+    const errors = captureWorldErrors();
+    const entity = world
+      .spawn(
+        { component: Transform, data: {} },
+        { component: MeshFilter, data: { assetHandle: HANDLE_CUBE } },
+        {
+          component: MeshRenderer,
+          data: {
+            materials: [toShared<'MaterialAsset'>(998), toShared<'MaterialAsset'>(999)],
+          },
+        },
+        { component: Visibility, data: { state: VisibilityStateValue.hidden } },
+      )
+      .unwrap();
+
+    extractFrames([world], 0, assets);
+    expect(errors).toEqual([]);
+
+    world.set(entity, Visibility, { state: VisibilityStateValue.visible }).unwrap();
+    extractFrames([world], 0, assets);
+    expect(errors.map((error) => error.code)).toContain('mesh-renderer-material-override-overflow');
+  });
+});

package/src/__tests__/visibility-snapshot-contract.unit.test.ts

@@ -1,7 +1,8 @@
 import { World } from '@forgeax/engine-ecs';
 import { ChildOf } from '@forgeax/engine-scene';
 import { describe, expect, it } from 'vitest';
-import { resolveVisibility, Visibility, VisibilityStateValue } from '../index';
+import { Visibility, VisibilityStateValue } from '../components/visibility';
+import { resolveVisibility } from '../extract/visibility';
 
 describe('visibility snapshot contract', () => {
   it('projects intent and effective state without writing a derived component', () => {

package/src/__tests__/vocabulary.unit.test.ts

@@ -16,6 +16,6 @@ describe('render vocabulary', () => {
     expect(render.Instances).toBeDefined();
     expect(render.PostProcessParams).toBeDefined();
     expect(render.TONEMAP_REINHARD).toBeDefined();
-    expect(render.tonemapToU32).toBeDefined();
+    expect('tonemapToU32' in render).toBe(false);
   }, 15_000);
 });

package/src/assembly/backend-contract.ts

@@ -0,0 +1,57 @@
+import type {
+  Result,
+  RhiCanvasContext,
+  RhiDevice,
+  RhiError,
+  RhiInstance,
+  ShaderModule,
+} from '@forgeax/engine-rhi';
+
+/** Optional host hooks for recorder and device-lifecycle capabilities. */
+export interface RhiBackendInstrumentation {
+  readonly resolveSurfaceDevice?: (device: RhiDevice) => Result<RhiDevice, RhiError>;
+  readonly onFrameBoundary?: () => void;
+  readonly onDeviceLost?: () => void;
+}
+
+/** Runtime-owned backend services injected into the render assembly. */
+export interface RhiBackendPack {
+  readonly rhi: RhiInstance & {
+    readonly acquireCanvasContext: (
+      canvas: HTMLCanvasElement | OffscreenCanvas,
+    ) => Result<RhiCanvasContext, RhiError>;
+  };
+  readonly createShaderModule?: (
+    device: RhiDevice,
+    desc: { code: string; label?: string | undefined },
+  ) => Promise<Result<ShaderModule, RhiError>>;
+  readonly translateErrorEventToRhiError?: (event: unknown) => {
+    readonly ok: false;
+    readonly error: RhiError;
+  };
+  /** @internal */
+  readonly _internal_getRawDevice?: (device: RhiDevice) => unknown | undefined;
+  /** Optional lifecycle hooks owned by the host capability being injected. */
+  readonly instrumentation?: RhiBackendInstrumentation;
+}
+
+export interface EngineEnvironmentErrorDetail {
+  readonly webgpuError?: RhiError | Error | undefined;
+  readonly wgpuError?: RhiError | Error | undefined;
+}
+
+export class EngineEnvironmentError extends Error {
+  readonly reason: string;
+  readonly webgpuError?: RhiError | Error | undefined;
+  readonly wgpuError?: RhiError | Error | undefined;
+  readonly detail: EngineEnvironmentErrorDetail;
+
+  constructor(reason: string, detail: EngineEnvironmentErrorDetail = {}) {
+    super(`forgeax-engine: no usable backend (${reason})`);
+    this.name = 'EngineEnvironmentError';
+    this.reason = reason;
+    this.webgpuError = detail.webgpuError;
+    this.wgpuError = detail.wgpuError;
+    this.detail = detail;
+  }
+}