@forgeax/engine-render 0.1.33 → 0.1.35

package/src/plugin.ts

@@ -1,7 +1,9 @@
 import type { Component, World } from '@forgeax/engine-ecs';
 import type { Plugin } from '@forgeax/engine-plugin';
 import { Atmosphere } from './components/atmosphere';
+import { BarrelDistortion } from './components/barrel-distortion';
 import { Camera } from './components/camera';
+import { CloudLayer } from './components/cloud-layer';
 import { DepthOfField } from './components/depth-of-field';
 import { DirectionalLight } from './components/directional-light';
 import { DynamicResolution } from './components/dynamic-resolution';
@@ -31,7 +33,9 @@ import { Visibility } from './components/visibility';
 
 const RENDER_COMPONENTS: readonly Component[] = [
   Atmosphere,
+  BarrelDistortion,
   Camera,
+  CloudLayer,
   DirectionalLight,
   DynamicResolution,
   DepthOfField,

package/src/points-lines/__tests__/points-lines.bench.ts

@@ -1,6 +1,12 @@
 import { World } from '@forgeax/engine-ecs';
 import { buildMeshAttributeMapForUvSets } from '@forgeax/engine-geometry';
 import { buildProfileModel, createProfiler } from '@forgeax/engine-profiler';
+import type { RhiRenderPassEncoder } from '@forgeax/engine-rhi';
+import { rhi } from '@forgeax/engine-rhi-null';
+import { Transform } from '@forgeax/engine-scene';
+import { err, type MeshAsset, ok } from '@forgeax/engine-types';
+import { bench, describe } from 'vitest';
+import { createRenderer as constructRenderer } from '../../assembly/factory';
 import {
   Camera,
   Lines,
@@ -10,13 +16,7 @@ import {
   PointShapeValue,
   Points,
   perspective,
-} from '@forgeax/engine-render';
-import type { RhiRenderPassEncoder } from '@forgeax/engine-rhi';
-import { rhi } from '@forgeax/engine-rhi-null';
-import { Transform } from '@forgeax/engine-scene';
-import { err, type MeshAsset, ok } from '@forgeax/engine-types';
-import { bench, describe } from 'vitest';
-import { createRenderer as constructRenderer } from '../../assembly/factory';
+} from '../../index';
 import { recordPointsLinesDraw } from '../../record/main-pass-geometry';
 import { admitPointsLines } from '../admission';
 import { PointsLinesExpansionCache } from '../expansion-cache';
@@ -186,7 +186,7 @@ function makeRealScene(
 async function createRealRoute(): Promise<RealRoute> {
   const profiler = createProfiler();
   const renderer = await constructRenderer(
-    { getContext: () => null },
+    { width: 1280, height: 720, getContext: () => null },
     { rhi, profiler },
     { shaderManifestUrl: manifestUrl() },
   );
@@ -328,6 +328,15 @@ const LINE_MESH = buildMesh('line-list');
 validateWorkload(POINT_MESH, LINE_MESH);
 const REAL_ROUTE = await createRealRoute();
 const REAL_PROFILE = await captureProfile(REAL_ROUTE, REAL_ROUTE.pointsLines);
+const recordedPointsLines = REAL_ROUTE.renderer.inspect().renderScene.pointsLines;
+if (
+  recordedPointsLines.length !== 2 ||
+  recordedPointsLines.some((entry) => entry.drawCount === 0 || entry.refusal !== undefined) ||
+  !recordedPointsLines.some((entry) => entry.pointCount === POINT_COUNT) ||
+  !recordedPointsLines.some((entry) => entry.segmentCount === SEGMENT_COUNT)
+) {
+  throw new Error('Points/Lines benchmark must draw its complete authored workload');
+}
 const DIRECT_PROFILE = await captureProfile(REAL_ROUTE, REAL_ROUTE.direct);
 
 function phaseDeltas(): Readonly<Record<string, number>> {

package/src/prepare/prepared-graphics-resolver.ts

@@ -115,6 +115,8 @@ export interface PreparedGraphicsResolvedSnapshot {
   readonly resolveGpuBuffer?: (
     reference: import('../features/prepared-gpu-work').RenderFeatureGpuBufferRef,
   ) => RenderFeatureResolvedGpuBuffer | undefined;
+  /** Resolve a feature-owned prepared buffer by its declarative resource name. */
+  readonly resolveGpuResource?: (name: string) => RenderFeatureResolvedGpuBuffer | undefined;
 }
 
 function preparationFailure(

package/src/publication/__tests__/derived-geometry.integration.test.ts

@@ -0,0 +1,177 @@
+import { AssetRegistry, HANDLE_CUBE } from '@forgeax/engine-assets-runtime';
+import { World } from '@forgeax/engine-ecs';
+import { AssetGuid } from '@forgeax/engine-pack/guid';
+import { rhi } from '@forgeax/engine-rhi-null';
+import { Transform } from '@forgeax/engine-scene';
+import { ShaderRegistry } from '@forgeax/engine-shader';
+import { Skin } from '@forgeax/engine-skinning';
+import { expect, it } from 'vitest';
+import { createSkinPaletteOwner } from '../../assembly/skin-palette-owner';
+import { Instances, MeshFilter, MeshRenderer } from '../../components';
+import { GlyphText } from '../../components/glyph-text';
+import { InstanceProjectionStore } from '../../instances';
+import { PersistentRenderScene } from '../../scene/render-scene';
+import { renderPublicationTransfers } from '../contract';
+import { preparePublicationGeometry } from '../prepare-geometry';
+import { createRenderPublisher } from '../publisher';
+import { RenderPublicationReceiver } from '../receiver';
+
+function required<T>(value: T | undefined): T {
+  if (value === undefined) throw new Error('Missing expected render projection');
+  return value;
+}
+
+function fixture() {
+  const world = new World();
+  const assets = new AssetRegistry(new ShaderRegistry({ manifestUrl: undefined }));
+  const identity = { source: 'derived-geometry', epoch: 1 };
+  const publisher = createRenderPublisher(world, assets, identity);
+  const receiver = new RenderPublicationReceiver(identity);
+  const scene = new PersistentRenderScene();
+  const instances = new InstanceProjectionStore();
+  const publish = (palette?: ReturnType<typeof createSkinPaletteOwner>) => {
+    world.update(0).unwrap();
+    const candidate = publisher.prepare(0).unwrap();
+    const packet = structuredClone(candidate.packet);
+    candidate.accept();
+    const received = receiver.accept(packet).unwrap();
+    const prepared = preparePublicationGeometry(received, scene, palette, assets, instances);
+    const frame = scene.consumePublication(prepared);
+    publisher.recycle(packet.revision, renderPublicationTransfers(packet)).unwrap();
+    return { packet, frame };
+  };
+  const spawn = () =>
+    world
+      .spawn(
+        { component: Transform, data: {} },
+        { component: MeshFilter, data: { assetHandle: HANDLE_CUBE } },
+        { component: MeshRenderer, data: {} },
+      )
+      .unwrap();
+  return { world, assets, publisher, receiver, scene, instances, publish, spawn };
+}
+const matrix = () => new Float32Array([1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1]);
+
+it('derives glyph meshes in the source World and republishes edits under the same mesh handle', () => {
+  const f = fixture();
+  const font = f.world.allocSharedRef('FontAsset', {
+    kind: 'font',
+    atlas: AssetGuid.random(),
+    sampler: AssetGuid.random(),
+    glyphs: {
+      65: {
+        advance: 10,
+        bearingX: 0,
+        bearingY: 8,
+        size: { w: 8, h: 8 },
+        region: { x: 0, y: 0, w: 8, h: 8 },
+      },
+    },
+    common: {
+      lineHeight: 12,
+      base: 8,
+      distanceRange: 4,
+      pxRange: 4,
+      atlasWidth: 8,
+      atlasHeight: 8,
+    },
+  });
+  const label = f.world
+    .spawn(
+      { component: Transform, data: {} },
+      { component: GlyphText, data: { fontHandle: font, text: 'A', fontSize: 1 } },
+    )
+    .unwrap();
+  const initial = f.publish();
+  expect(initial.frame.renderables.map((row) => row.entityKey)).toContain(label);
+  const handle = f.world.get(label, MeshFilter).unwrap().assetHandle;
+  const mesh = initial.packet.assets.find((row) => row.handle === handle)?.value;
+  expect(mesh?.kind).toBe('mesh');
+  f.world.set(label, GlyphText, { text: 'AAA' }).unwrap();
+  const edited = f.publish();
+  expect(f.world.get(label, MeshFilter).unwrap().assetHandle).toBe(handle);
+  expect(edited.packet.invalidatedAssets).toContain(handle);
+  const next = edited.packet.assets.find((row) => row.handle === handle)?.value;
+  expect(
+    next?.kind === 'mesh' && mesh?.kind === 'mesh' && next.vertices.length > mesh.vertices.length,
+  ).toBe(true);
+  f.publisher.dispose();
+  const later = f.world
+    .spawn({ component: GlyphText, data: { fontHandle: font, text: 'A' } })
+    .unwrap();
+  f.world.update(0).unwrap();
+  expect(f.world.hasComponent(later, MeshFilter)).toBe(false);
+});
+
+it('retains instance history on pose edits and retires it across removal and topology changes', () => {
+  const f = fixture();
+  const entity = f.spawn();
+  f.world.addComponent(entity, { component: Instances, data: { transforms: matrix() } }).unwrap();
+  const initial = required(f.publish().frame.renderables[0]?.instances);
+  const moved = matrix();
+  moved[12] = 2;
+  f.world.set(entity, Instances, { transforms: moved }).unwrap();
+  const edited = required(f.publish().frame.renderables[0]?.instances);
+  expect(edited.collectionId).toBe(initial.collectionId);
+  expect(edited.generations).toEqual(initial.generations);
+  expect(edited.revision).toBe(required(initial.revision) + 1);
+  f.world
+    .set(entity, Instances, { transforms: new Float32Array([...matrix(), ...matrix()]) })
+    .unwrap();
+  const resized = required(f.publish().frame.renderables[0]?.instances);
+  expect(resized.generations?.[0]).not.toBe(initial.generations?.[0]);
+  f.world.removeComponent(entity, Instances).unwrap();
+  f.publish();
+  f.world.addComponent(entity, { component: Instances, data: { transforms: matrix() } }).unwrap();
+  const restored = required(f.publish().frame.renderables[0]?.instances);
+  expect(restored.collectionId).not.toBe(initial.collectionId);
+  f.publisher.dispose();
+});
+
+it.each([
+  true,
+  false,
+])('keeps untouched skin palettes and reclaims removed slices (storage=%s)', async (storage) => {
+  const device = (await (await rhi.requestAdapter()).unwrap().requestDevice()).unwrap();
+  const palette = createSkinPaletteOwner(device, storage);
+  const f = fixture();
+  const skeleton = f.world.allocSharedRef('SkeletonAsset', {
+    kind: 'skeleton',
+    jointCount: 1,
+    inverseBindMatrices: matrix(),
+  });
+  const joint = f.world.spawn({ component: Transform, data: {} }).unwrap();
+  const first = f.spawn(),
+    second = f.spawn();
+  for (const entity of [first, second])
+    f.world
+      .addComponent(entity, {
+        component: Skin,
+        data: { skeleton, joints: new Uint32Array([joint]) },
+      })
+      .unwrap();
+  const initial = f.publish(palette).frame;
+  const one = required(initial.renderables.find((row) => row.entityKey === first)?.skin);
+  const two = required(initial.renderables.find((row) => row.entityKey === second)?.skin);
+  expect(one).toBeDefined();
+  expect(two).toBeDefined();
+  f.world.removeComponent(first, Skin).unwrap();
+  const removed = f.publish(palette).frame;
+  expect(removed.renderables.find((row) => row.entityKey === first)?.skin).toBeUndefined();
+  expect(removed.renderables.find((row) => row.entityKey === second)?.skin?.fence).toBe(two.fence);
+  f.world.set(joint, Transform, { pos: [1, 0, 0] }).unwrap();
+  const moved = required(
+    f.publish(palette).frame.renderables.find((row) => row.entityKey === second)?.skin,
+  );
+  expect(moved.fence).toBe(two.fence);
+  expect(moved.uploadBytes).toBe(64);
+  f.world
+    .addComponent(first, { component: Skin, data: { skeleton, joints: new Uint32Array([joint]) } })
+    .unwrap();
+  const restored = required(
+    f.publish(palette).frame.renderables.find((row) => row.entityKey === first)?.skin,
+  );
+  expect(restored.fence).not.toBe(one.fence);
+  f.publisher.dispose();
+  palette.dispose();
+});

package/src/publication/__tests__/features.integration.test.ts

@@ -0,0 +1,122 @@
+import { AssetRegistry, HANDLE_CUBE, resolveAssetHandle } from '@forgeax/engine-assets-runtime';
+import { World } from '@forgeax/engine-ecs';
+import { AssetGuid } from '@forgeax/engine-pack/guid';
+import { Transform } from '@forgeax/engine-scene';
+import { ShaderRegistry } from '@forgeax/engine-shader';
+import { type MeshAsset, ok } from '@forgeax/engine-types';
+import { expect, it } from 'vitest';
+import { MeshFilter, MeshRenderer } from '../../components';
+import type { RenderFeature } from '../../features/types';
+import { renderPublicationTransfers } from '../contract';
+import { createRenderPublisher } from '../publisher';
+import { RenderPublicationReceiver } from '../receiver';
+
+it('acknowledges only submitted source data, rejecting stale and duplicate receipts atomically', () => {
+  const world = new World();
+  const assets = new AssetRegistry(new ShaderRegistry({ manifestUrl: undefined }));
+  const consumed: unknown[] = [];
+  let value = 1;
+  const feature: RenderFeature<unknown> = {
+    identity: 'source-events',
+    extract: () => ok({ value }),
+    plan: () => ok({ resources: [], passes: [] }),
+    onSourceFrameSubmitted: (data, feedback) => consumed.push({ data, feedback }),
+  };
+  const publisher = createRenderPublisher(world, assets, { source: 'ack', epoch: 1 }, undefined, [
+    feature,
+  ]);
+  const candidate = publisher.prepare(0).unwrap();
+  const packet = structuredClone(candidate.packet, {
+    transfer: renderPublicationTransfers(candidate.packet),
+  });
+  candidate.accept();
+  value = 2;
+  expect(consumed).toEqual([]);
+  expect(publisher.acknowledgeFeatures(0, [{ identity: feature.identity, feedback: 1 }]).ok).toBe(
+    false,
+  );
+  expect(
+    publisher.acknowledgeFeatures(1, [
+      { identity: feature.identity, feedback: 1 },
+      { identity: 'unknown', feedback: 1 },
+    ]).ok,
+  ).toBe(false);
+  expect(consumed).toEqual([]);
+  publisher.acknowledgeFeatures(1, [{ identity: feature.identity, feedback: 1 }]).unwrap();
+  expect(consumed).toEqual([{ data: { value: 1 }, feedback: 1 }]);
+  expect(publisher.acknowledgeFeatures(1, [{ identity: feature.identity, feedback: 1 }]).ok).toBe(
+    false,
+  );
+  publisher.recycle(1, renderPublicationTransfers(packet)).unwrap();
+  const next = publisher.prepare(1).unwrap();
+  next.discard();
+  expect(consumed).toHaveLength(1);
+  publisher.dispose();
+});
+
+it('publishes feature-only GUID resources and retires them when the producer drops the root', () => {
+  const world = new World();
+  const assets = new AssetRegistry(new ShaderRegistry({ manifestUrl: undefined }));
+  const guid = '12345678-1234-1234-1234-123456789abc';
+  const mesh = resolveAssetHandle<MeshAsset>(world, HANDLE_CUBE).unwrap();
+  assets.catalog(guid, mesh);
+  let roots = [guid];
+  const feature: RenderFeature<unknown> = {
+    identity: 'guid-consumer',
+    extract: () => ok({}),
+    assetDependencies: () => roots,
+    plan: () => ok({ resources: [], passes: [] }),
+  };
+  const identity = { source: 'feature-assets', epoch: 1 };
+  const publisher = createRenderPublisher(world, assets, identity, undefined, [feature]);
+  const receiver = new RenderPublicationReceiver(identity);
+  const first = publisher.prepare(0).unwrap();
+  const packet = structuredClone(first.packet);
+  first.accept();
+  const accepted = receiver.accept(packet).unwrap();
+  expect(accepted.resources.lookupAsset(guid)).toEqual(mesh);
+  expect(packet.assets.filter((row) => row.guid === guid)).toHaveLength(1);
+  publisher.recycle(1, renderPublicationTransfers(packet)).unwrap();
+  roots = [];
+  const next = publisher.prepare(1).unwrap();
+  expect(next.packet.retiredAssets).toContain(accepted.resources.handleForGuid(guid));
+  receiver.accept(next.packet).unwrap();
+  expect(accepted.resources.lookupAsset(guid)).toBeUndefined();
+  next.discard();
+  publisher.dispose();
+});
+
+it('publishes LOD GUID dependencies and rejects a missing lower-detail asset before acceptance', () => {
+  const world = new World();
+  const assets = new AssetRegistry(new ShaderRegistry({ manifestUrl: undefined }));
+  const guid = '12345678-1234-1234-1234-123456789abc';
+  const mesh = resolveAssetHandle<MeshAsset>(world, HANDLE_CUBE).unwrap();
+  assets.catalog(guid, mesh);
+  const parsed = AssetGuid.parse(guid);
+  if (!parsed.ok) throw parsed.error;
+  const assetHandle = world.allocSharedRef('MeshAsset', {
+    ...mesh,
+    lods: [{ mesh: parsed.value, screenCoverage: 0.5 }],
+  });
+  world
+    .spawn(
+      { component: Transform, data: {} },
+      { component: MeshFilter, data: { assetHandle } },
+      { component: MeshRenderer, data: {} },
+    )
+    .unwrap();
+  const identity = { source: 'lod-assets', epoch: 1 };
+  const publisher = createRenderPublisher(world, assets, identity);
+  const receiver = new RenderPublicationReceiver(identity);
+  const candidate = publisher.prepare(0).unwrap();
+  expect(candidate.packet.assets.some((row) => row.guid === guid)).toBe(true);
+  const missing = {
+    ...candidate.packet,
+    assets: candidate.packet.assets.filter((row) => row.guid !== guid),
+  };
+  expect(receiver.accept(missing).ok).toBe(false);
+  expect(receiver.acceptedRevision).toBe(0);
+  expect(receiver.accept(structuredClone(candidate.packet)).ok).toBe(true);
+  candidate.discard();
+  publisher.dispose();
+});

package/src/publication/__tests__/programs.unit.test.ts

@@ -0,0 +1,25 @@
+import { AssetRegistry } from '@forgeax/engine-assets-runtime';
+import { ShaderRegistry } from '@forgeax/engine-shader';
+import { expect, it } from 'vitest';
+import { installPublicationPrograms } from '../programs';
+
+it('rejects conflicting programs atomically and preserves the installed shader', () => {
+  const shaders = new ShaderRegistry({ manifestUrl: undefined });
+  const assets = new AssetRegistry(shaders);
+  const first = { key: 'forgeax::publication-test', shader: { source: 'first', paramSchema: [] } };
+  installPublicationPrograms(assets, [first]);
+  expect(() =>
+    installPublicationPrograms(assets, [
+      { key: 'forgeax::new-test', shader: { source: 'new', paramSchema: [] } },
+      { ...first, shader: { ...first.shader, source: 'conflict' } },
+    ]),
+  ).toThrow('conflicting immutable shader');
+  expect(shaders.findMaterialArtifact('forgeax::new-test').ok).toBe(false);
+  expect(shaders.findMaterialArtifact(first.key).unwrap().source).toBe('first');
+  expect(() => installPublicationPrograms(assets, [first, first])).toThrow('duplicate');
+  expect(() =>
+    installPublicationPrograms(assets, [
+      { ...first, artifact: { key: 'wrong', bytes: new Uint8Array() } },
+    ]),
+  ).toThrow('mismatched');
+});