@forgeax/engine-render 0.1.2

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

@@ -0,0 +1,96 @@
+import { describe, expect, it } from 'vitest';
+
+type ProducerAudit = {
+  readonly producer: string;
+  readonly owner: 'built-in' | 'vfx-render';
+  readonly visible: string;
+  readonly hidden: string;
+  readonly restored: string;
+  readonly shadow: 'required' | 'N/A: baseline has no shadow contribution';
+};
+
+const PRODUCER_MATRIX: readonly ProducerAudit[] = [
+  {
+    producer: 'static-mesh',
+    owner: 'built-in',
+    visible: 'main dispatch exists',
+    hidden: 'main and shadow dispatch are empty',
+    restored: 'the same entity dispatches again',
+    shadow: 'required',
+  },
+  {
+    producer: 'skinned-mesh',
+    owner: 'built-in',
+    visible: 'main dispatch exists',
+    hidden: 'main and shadow dispatch are empty',
+    restored: 'the same entity dispatches again',
+    shadow: 'required',
+  },
+  {
+    producer: 'auto-fold-instances',
+    owner: 'built-in',
+    visible: 'visible members remain in the batch',
+    hidden: 'hidden members leave the batch',
+    restored: 'the same members return',
+    shadow: 'required',
+  },
+  {
+    producer: 'explicit-instances',
+    owner: 'built-in',
+    visible: 'the owner dispatches',
+    hidden: 'the owner dispatch is empty',
+    restored: 'the owner dispatches again',
+    shadow: 'required',
+  },
+  {
+    producer: 'sprite',
+    owner: 'built-in',
+    visible: 'main dispatch exists',
+    hidden: 'main and shadow dispatch are empty',
+    restored: 'the same entity dispatches again',
+    shadow: 'required',
+  },
+  {
+    producer: 'tilemap',
+    owner: 'built-in',
+    visible: 'derived render entities dispatch',
+    hidden: 'derived render entities dispatch nothing',
+    restored: 'derived render entities dispatch again',
+    shadow: 'required',
+  },
+  {
+    producer: 'vfx-particles',
+    owner: 'vfx-render',
+    visible: 'main-color contribution exists',
+    hidden: 'main-color contribution is empty',
+    restored: 'the same player contributes again',
+    shadow: 'N/A: baseline has no shadow contribution',
+  },
+];
+
+describe('visibility producer matrix audit', () => {
+  it('contains every producer and three explicit state criteria', () => {
+    expect(PRODUCER_MATRIX.map(({ producer }) => producer)).toEqual([
+      'static-mesh',
+      'skinned-mesh',
+      'auto-fold-instances',
+      'explicit-instances',
+      'sprite',
+      'tilemap',
+      'vfx-particles',
+    ]);
+    for (const row of PRODUCER_MATRIX) {
+      expect(row.visible).not.toBe('');
+      expect(row.hidden).not.toBe('');
+      expect(row.restored).not.toBe('');
+    }
+  });
+
+  it('requires real shadow evidence only from producers with a shadow path', () => {
+    const builtIn = PRODUCER_MATRIX.filter((row) => row.owner === 'built-in');
+    expect(builtIn.every((row) => row.shadow === 'required')).toBe(true);
+    expect(PRODUCER_MATRIX.find((row) => row.producer === 'vfx-particles')?.shadow).toBe(
+      'N/A: baseline has no shadow contribution',
+    );
+  });
+});

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

@@ -0,0 +1,26 @@
+import { World } from '@forgeax/engine-ecs';
+import {
+  Visibility,
+  type VisibilityState,
+  VisibilityStateValue,
+  visibilityStateFromU32,
+} from '@forgeax/engine-render';
+import { expectTypeOf } from 'vitest';
+
+const world = new World();
+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>();
+
+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);
+  expectTypeOf(decodedState).toEqualTypeOf<VisibilityState | undefined>();
+}

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

@@ -0,0 +1,84 @@
+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';
+
+function spawn(
+  world: World,
+  state: keyof typeof VisibilityStateValue,
+  parent?: EntityHandle,
+): EntityHandle {
+  const parentData = parent === undefined ? [] : [{ component: ChildOf, data: { parent } }];
+  return world
+    .spawn({ component: Visibility, data: { state: VisibilityStateValue[state] } }, ...parentData)
+    .unwrap();
+}
+
+describe('visibility resolver truth table', () => {
+  it('defaults root inherited to visible and preserves explicit states', () => {
+    const world = new World();
+    const inherited = spawn(world, 'inherited');
+    const hidden = spawn(world, 'hidden');
+    const visible = spawn(world, 'visible');
+
+    const snapshot = resolveVisibility(world);
+
+    expect(snapshot.get(inherited)).toMatchObject({
+      intent: 'inherited',
+      effective: 'visible',
+      source: 'default',
+    });
+    expect(snapshot.get(hidden)).toMatchObject({
+      intent: 'hidden',
+      effective: 'hidden',
+      source: 'self',
+    });
+    expect(snapshot.get(visible)).toMatchObject({
+      intent: 'visible',
+      effective: 'visible',
+      source: 'self',
+    });
+  });
+
+  it.each([
+    ['visible', 'inherited', 'visible'],
+    ['visible', 'hidden', 'hidden'],
+    ['visible', 'visible', 'visible'],
+    ['hidden', 'inherited', 'hidden'],
+    ['hidden', 'hidden', 'hidden'],
+    ['hidden', 'visible', 'visible'],
+  ] as const)('resolves parent %s and child %s as %s', (parentState, childState, expected) => {
+    const world = new World();
+    const parent = spawn(world, parentState);
+    const child = spawn(world, childState, parent);
+
+    const result = resolveVisibility(world);
+
+    expect(result.get(child)?.effective).toBe(expected);
+  });
+
+  it('lets explicit visible establish a new inherited baseline below a hidden ancestor', () => {
+    const world = new World();
+    const hiddenParent = spawn(world, 'hidden');
+    const visibleChild = spawn(world, 'visible', hiddenParent);
+    const inheritedGrandchild = spawn(world, 'inherited', visibleChild);
+
+    const snapshot = resolveVisibility(world);
+
+    expect(snapshot.get(hiddenParent)?.effective).toBe('hidden');
+    expect(snapshot.get(visibleChild)?.effective).toBe('visible');
+    expect(snapshot.get(inheritedGrandchild)?.effective).toBe('visible');
+    expect(snapshot.get(inheritedGrandchild)?.source).toBe('parent');
+  });
+
+  it('keeps the author intent queryable for a non-render hierarchy node', () => {
+    const world = new World();
+    const parent = world.spawn().unwrap();
+    const child = spawn(world, 'inherited', parent);
+
+    const result = resolveVisibility(world);
+
+    expect(result.get(parent)?.intent).toBeUndefined();
+    expect(result.get(child)?.effective).toBe('visible');
+  });
+});

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

@@ -0,0 +1,59 @@
+import { World } from '@forgeax/engine-ecs';
+import { ChildOf } from '@forgeax/engine-scene';
+import { describe, expect, it } from 'vitest';
+import { resolveVisibility, Visibility, VisibilityStateValue } from '../index';
+
+describe('visibility snapshot contract', () => {
+  it('projects intent and effective state without writing a derived component', () => {
+    const world = new World();
+    const parent = world
+      .spawn({ component: Visibility, data: { state: VisibilityStateValue.hidden } })
+      .unwrap();
+    const child = world
+      .spawn(
+        { component: Visibility, data: { state: VisibilityStateValue.inherited } },
+        { component: ChildOf, data: { parent } },
+      )
+      .unwrap();
+
+    const snapshot = resolveVisibility(world);
+    const childResult = snapshot.get(child);
+
+    expect(childResult).toMatchObject({ intent: 'inherited', effective: 'hidden' });
+    expect(snapshot.diagnostics).toEqual([]);
+    expect(world.components.resolve('EffectiveVisibility')).toBeUndefined();
+  });
+
+  it('is read-only and does not retain a previous World result', () => {
+    const first = new World();
+    const firstEntity = first
+      .spawn({ component: Visibility, data: { state: VisibilityStateValue.hidden } })
+      .unwrap();
+    const firstSnapshot = resolveVisibility(first);
+    expect(firstSnapshot.get(firstEntity)?.effective).toBe('hidden');
+
+    const second = new World();
+    second.spawn().unwrap();
+    const secondEntity = second
+      .spawn({ component: Visibility, data: { state: VisibilityStateValue.visible } })
+      .unwrap();
+    const secondSnapshot = resolveVisibility(second);
+
+    expect(secondSnapshot).not.toBe(firstSnapshot);
+    expect(secondSnapshot.get(secondEntity)?.effective).toBe('visible');
+    // The first numeric handle is occupied by a non-visibility entity in the
+    // second World, so a prior World snapshot cannot leak a result into it.
+    expect(secondSnapshot.get(firstEntity)).toBeUndefined();
+  });
+
+  it('exposes diagnostics alongside entity queries for a broken parent edge', () => {
+    const world = new World();
+    const child = world
+      .spawn({ component: Visibility, data: { state: VisibilityStateValue.inherited } })
+      .unwrap();
+    const snapshot = resolveVisibility(world);
+
+    expect(snapshot.get(child)?.intent).toBe('inherited');
+    expect(snapshot.diagnostics).toBeDefined();
+  });
+});

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

@@ -0,0 +1,21 @@
+// @perf-budget-skip: intentional public render-barrel vocabulary smoke gate.
+
+import { describe, expect, it } from 'vitest';
+
+describe('render vocabulary', () => {
+  it('exposes the core render roster from the render package', async () => {
+    const render = await import('../index');
+    expect(render.Camera).toBeDefined();
+    expect(render.MeshFilter).toBeDefined();
+    expect(render.MeshRenderer).toBeDefined();
+    expect(render.DirectionalLight).toBeDefined();
+    expect(render.PointLight).toBeDefined();
+    expect(render.SpotLight).toBeDefined();
+    expect(render.Layer).toBeDefined();
+    expect(render.SortKey).toBeDefined();
+    expect(render.Instances).toBeDefined();
+    expect(render.PostProcessParams).toBeDefined();
+    expect(render.TONEMAP_REINHARD).toBeDefined();
+    expect(render.tonemapToU32).toBeDefined();
+  }, 15_000);
+});

package/src/assets/__tests__/asset-decoders.unit.test.ts

@@ -0,0 +1,92 @@
+import type { AssetEnvelopeV2, MaterialAsset } from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+import { materialContribution } from '../asset-decoders';
+
+function envelope(payload: MaterialAsset, refs: readonly string[]): AssetEnvelopeV2<MaterialAsset> {
+  return {
+    guid: '00000000-0000-7000-8000-000000000031',
+    kind: 'material',
+    payload,
+    refs,
+    artifacts: {},
+  };
+}
+
+describe('material asset decoder', () => {
+  it('projects shorthand texture and parent refs from Pack wire indices to GUIDs', async () => {
+    const result = await materialContribution.decoder.decode({
+      envelope: envelope(
+        {
+          kind: 'material',
+          parent: 1 as never,
+          values: { baseColorTexture: 0, roughness: 0.5 },
+        },
+        ['00000000-0000-7000-8000-000000000041', '00000000-0000-7000-8000-000000000042'],
+      ),
+      artifacts: undefined as never,
+      signal: new AbortController().signal,
+    });
+
+    expect(result).toEqual({
+      ok: true,
+      value: {
+        kind: 'material',
+        parent: '00000000-0000-7000-8000-000000000042',
+        values: {
+          baseColorTexture: '00000000-0000-7000-8000-000000000041',
+          roughness: 0.5,
+        },
+      },
+    });
+  });
+
+  it('projects texture and sampler refs from Pack wire indices to GUIDs', async () => {
+    const material: MaterialAsset = {
+      kind: 'material',
+      values: {
+        baseColorTexture: { texture: 0, sampler: 1 },
+      },
+    };
+
+    const result = await materialContribution.decoder.decode({
+      envelope: envelope(material, [
+        '00000000-0000-7000-8000-000000000041',
+        '00000000-0000-7000-8000-000000000042',
+      ]),
+      artifacts: undefined as never,
+      signal: new AbortController().signal,
+    });
+
+    expect(result).toEqual({
+      ok: true,
+      value: {
+        ...material,
+        values: {
+          baseColorTexture: {
+            texture: '00000000-0000-7000-8000-000000000041',
+            sampler: '00000000-0000-7000-8000-000000000042',
+          },
+        },
+      },
+    });
+  });
+
+  it('rejects a material wire ref that is not present in refs[]', async () => {
+    const result = await materialContribution.decoder.decode({
+      envelope: envelope(
+        {
+          kind: 'material',
+          values: { baseColorTexture: { texture: 1 } },
+        },
+        ['00000000-0000-7000-8000-000000000041'],
+      ),
+      artifacts: undefined as never,
+      signal: new AbortController().signal,
+    });
+
+    expect(result).toMatchObject({
+      ok: false,
+      error: { code: 'asset-package-invalid' },
+    });
+  });
+});

package/src/assets/__tests__/mipmap-generator.unit.test.ts

@@ -0,0 +1,52 @@
+import { ok } from '@forgeax/engine-rhi';
+import { describe, expect, it } from 'vitest';
+import {
+  getOrCreateMipmapPipeline,
+  type MipmapDevice,
+  type MipmapShaderModuleFactory,
+  mipmapCacheSize,
+  numMipLevels,
+} from '../../mipmap-generator';
+
+let nextResourceId = 0;
+
+function makeStubDevice(): MipmapDevice {
+  return {
+    createSampler: () => ok({ tag: `sampler-${nextResourceId++}` }),
+    createBindGroupLayout: () => ok({ tag: `bgl-${nextResourceId++}` }),
+    createPipelineLayout: () => ok({ tag: `layout-${nextResourceId++}` }),
+    createRenderPipeline: (desc: { fragment?: { targets?: Array<{ format?: string }> } }) =>
+      ok({ tag: `pipeline-${nextResourceId++}`, format: desc.fragment?.targets?.[0]?.format }),
+  } as unknown as MipmapDevice;
+}
+
+const shaderFactory: MipmapShaderModuleFactory = async () => ok({ tag: 'shader' });
+
+describe('render mipmap owner', () => {
+  it('derives the full mip chain from the largest dimension', () => {
+    expect(numMipLevels({ width: 1, height: 1 })).toBe(1);
+    expect(numMipLevels({ width: 300, height: 200 })).toBe(9);
+  });
+
+  it('caches pipelines by device and format', async () => {
+    const device = makeStubDevice();
+    const first = await getOrCreateMipmapPipeline(device, 'rgba8unorm', shaderFactory);
+    const second = await getOrCreateMipmapPipeline(device, 'rgba8unorm', shaderFactory);
+    const srgb = await getOrCreateMipmapPipeline(device, 'rgba8unorm-srgb', shaderFactory);
+
+    expect(first.ok && second.ok && first.value).toBe(second.ok && second.value);
+    expect(srgb.ok).toBe(true);
+    expect(mipmapCacheSize(device)).toBe(2);
+  });
+
+  it('isolates caches across devices', async () => {
+    const deviceA = makeStubDevice();
+    const deviceB = makeStubDevice();
+    const fromA = await getOrCreateMipmapPipeline(deviceA, 'rgba8unorm', shaderFactory);
+    const fromB = await getOrCreateMipmapPipeline(deviceB, 'rgba8unorm', shaderFactory);
+
+    expect(fromA.ok && fromB.ok && fromA.value).not.toBe(fromB.ok && fromB.value);
+    expect(mipmapCacheSize(deviceA)).toBe(1);
+    expect(mipmapCacheSize(deviceB)).toBe(1);
+  });
+});

package/src/assets/__tests__/render-asset-port.unit.test.ts

@@ -0,0 +1,54 @@
+import type { ShaderRegistry } from '@forgeax/engine-shader';
+import type { MaterialAsset } from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+import { createRenderAssetPort } from '../render-asset-port';
+
+function shaderRegistry(): ShaderRegistry {
+  return {
+    findMaterialArtifact: () => ({ ok: false, error: new Error('not registered') }),
+  } as unknown as ShaderRegistry;
+}
+
+function material(module: string): MaterialAsset {
+  return {
+    kind: 'material',
+    passes: [
+      {
+        name: 'Forward',
+        program: { module },
+        renderState: { tags: { LightMode: 'Forward' }, queue: 2000 },
+      },
+    ],
+  };
+}
+
+describe('render asset port', () => {
+  it('publishes typed payloads with stable GUID lookup and mutation epochs', () => {
+    const payloads = new Map<string, MaterialAsset>();
+    let epoch = 0;
+    const port = createRenderAssetPort(shaderRegistry(), {
+      get epoch() {
+        return epoch;
+      },
+      lookup: <T>(guid: string) => payloads.get(guid.toLowerCase()) as T | undefined,
+      guidOf: (asset) => [...payloads.entries()].find(([, payload]) => payload === asset)?.[0],
+    });
+    const first = material('first');
+    const replacement = material('replacement');
+
+    expect(port.epoch).toBe(0);
+    payloads.set('abc', first);
+    epoch += 1;
+    expect(port.epoch).toBe(1);
+    expect(port.lookup<MaterialAsset>('abc')).toBe(first);
+    expect(port.guidOf(first)).toBe('abc');
+
+    epoch += 0;
+    expect(port.epoch).toBe(1);
+    payloads.set('abc', replacement);
+    epoch += 1;
+    expect(port.epoch).toBe(2);
+    expect(port.lookup<MaterialAsset>('ABC')).toBe(replacement);
+    expect(port.guidOf(first)).toBeUndefined();
+  });
+});

package/src/assets/__tests__/resolve-render-asset.unit.test.ts

@@ -0,0 +1,47 @@
+import { World } from '@forgeax/engine-ecs';
+import { createPrimitiveMesh } from '@forgeax/engine-geometry';
+import type { Asset } from '@forgeax/engine-types';
+import { BUILTIN_BASE, handleSlot } from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+import { resolveRenderAsset } from '../resolve-render-asset';
+
+describe('render handle resolution', () => {
+  it('resolves World-owned primitive meshes', () => {
+    const world = new World();
+    const cubeHandle = world.internSharedRef('MeshAsset', createPrimitiveMesh('cube').unwrap());
+    const triangleHandle = world.internSharedRef(
+      'MeshAsset',
+      createPrimitiveMesh('triangle').unwrap(),
+    );
+
+    const cube = resolveRenderAsset(world, cubeHandle);
+    const triangle = resolveRenderAsset(world, triangleHandle);
+
+    expect(cube.ok && cube.value.kind).toBe('mesh');
+    expect(triangle.ok && triangle.value.kind).toBe('mesh');
+    expect(handleSlot(cubeHandle)).toBe(BUILTIN_BASE);
+  });
+
+  it('resolves user handles from the owning World shared-ref store', () => {
+    const world = new World();
+    const payload = createPrimitiveMesh('cube').unwrap();
+    const handle = world.allocSharedRef('MeshAsset', payload);
+
+    const resolved = resolveRenderAsset<Asset>(world, handle);
+
+    expect(resolved).toEqual({ ok: true, value: payload });
+  });
+
+  it('returns a closed error for a handle owned by another World', () => {
+    const world = new World();
+    const foreignWorld = new World();
+    const foreignHandle = foreignWorld.allocSharedRef(
+      'MeshAsset',
+      createPrimitiveMesh('cube').unwrap(),
+    );
+    const resolved = resolveRenderAsset(world, foreignHandle);
+
+    expect(resolved.ok).toBe(false);
+    if (!resolved.ok) expect(resolved.error.code).toBe('shared-ref-released');
+  });
+});