@forgeax/engine-vfx-render 0.1.4 → 0.1.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forgeax/engine-vfx-render",
-  "version": "0.1.4",
+  "version": "0.1.7",
   "private": false,
   "type": "module",
   "license": "Apache-2.0",
@@ -22,13 +22,13 @@
     "LICENSE"
   ],
   "dependencies": {
-    "@forgeax/engine-assets-runtime": "0.1.4",
-    "@forgeax/engine-ecs": "0.1.4",
-    "@forgeax/engine-math": "0.1.4",
-    "@forgeax/engine-render": "0.1.4",
-    "@forgeax/engine-scene": "0.1.4",
-    "@forgeax/engine-types": "0.1.4",
-    "@forgeax/engine-vfx": "0.1.4"
+    "@forgeax/engine-assets-runtime": "0.1.7",
+    "@forgeax/engine-ecs": "0.1.7",
+    "@forgeax/engine-math": "0.1.7",
+    "@forgeax/engine-render": "0.1.7",
+    "@forgeax/engine-scene": "0.1.7",
+    "@forgeax/engine-types": "0.1.7",
+    "@forgeax/engine-vfx": "0.1.7"
   },
   "devDependencies": {},
   "forgeax": {

package/src/__tests__/billboard-advanced.integration.test.ts

@@ -43,27 +43,4 @@ describe('billboard advanced executable inputs', () => {
       error: { code: 'vfx-renderer-depth-missing' },
     });
   });
-
-  it('changes soft-particle alpha when scene depth changes before Fog mixing', () => {
-    const nearDepth = resolveBillboardAdvancedState(renderer, {
-      age: 0.1,
-      lifetime: 1,
-      particleDepth: 0.7,
-      sceneDepth: 0.75,
-      depthAvailable: true,
-    });
-    const farDepth = resolveBillboardAdvancedState(renderer, {
-      age: 0.1,
-      lifetime: 1,
-      particleDepth: 0.7,
-      sceneDepth: 1.0,
-      depthAvailable: true,
-    });
-
-    expect(nearDepth.ok).toBe(true);
-    expect(farDepth.ok).toBe(true);
-    if (nearDepth.ok && farDepth.ok) {
-      expect(farDepth.value.softParticleFade).toBeGreaterThan(nearDepth.value.softParticleFade);
-    }
-  });
 });

package/src/__tests__/fog-producer.integration.test.ts

@@ -29,7 +29,7 @@ describe('VFX Fog producer contract', () => {
     }
   });
 
-  it('keeps VFX coverage on the existing reactive graphics lane', () => {
+  it('keeps VFX coverage on the current graphics feature lane', () => {
     const feature = readFileSync(
       fileURLToPath(new URL('../feature/gpu-particle-feature.ts', import.meta.url)),
       'utf8',
@@ -38,9 +38,10 @@ describe('VFX Fog producer contract', () => {
       fileURLToPath(new URL('../feature/camera.ts', import.meta.url)),
       'utf8',
     );
-    expect(feature).toContain("temporalCoverage: 'reactive'");
+    expect(feature).toContain('requiredCapabilities');
+    expect(feature).toContain('identity: IDENTITY');
     expect(feature).not.toMatch(/fog(?:History|Texture|Registry)/i);
-    expect(feature).toContain('worldPosition');
+    expect(feature).toContain('worldCenter');
     expect(camera).toContain('position');
     expect(camera).toContain('viewProjection');
   });

package/src/__tests__/gpu-host.integration.test.ts

@@ -1,15 +1,12 @@
-import { createAssetRegistry, createCatalogSource } from '@forgeax/engine-assets-runtime';
 import { World } from '@forgeax/engine-ecs';
-import { RenderFeaturePreparationFailedError } from '@forgeax/engine-render';
-import { err, ok } from '@forgeax/engine-types';
+import type { Asset, MaterialAsset } from '@forgeax/engine-types';
 import {
   ParticleEffectPlayer,
   VFX_GPU_RUNTIME_RESOURCE_KEY,
   type VfxGpuRuntime,
   type VfxGpuTickIntent,
-  vfxGpuEffectContribution,
 } from '@forgeax/engine-vfx';
-import { describe, expect, it, vi } from 'vitest';
+import { describe, expect, it } from 'vitest';
 import { gpuParticleRenderFeature } from '../feature/gpu-particle-feature.js';
 import {
   createCameraProvider,
@@ -21,12 +18,10 @@ import {
 describe('GPU VFX public host', () => {
   it('owns loader and FixedUpdate attachment without exposing simulation internals', async () => {
     const world = new World();
-    const installed: unknown[] = [];
+    const registered: unknown[] = [];
     const assets = {
-      installDecoder: (kind: unknown, decoder: unknown) => {
-        installed.push({ kind, decoder });
-        return { kind: 'particle-effect', dispose: () => {} };
-      },
+      loaders: { registerPackLoader: (loader: unknown) => registered.push(loader) },
+      lookup: () => undefined,
     };
     const host = createVfxRuntimeHost({
       camera: {
@@ -41,45 +36,104 @@ describe('GPU VFX public host', () => {
 
     const attached = await host.attachWorld({ world, assets: assets as never });
     expect(attached).toMatchObject({ ok: true, value: { state: 'attached' } });
-    expect(installed).toHaveLength(1);
+    expect(registered).toHaveLength(1);
     expect(host.feature.requiredMaterialShaders).toEqual(
       Object.values(PARTICLE_SHADER_IDENTIFIERS),
     );
-    expect(host.feature.inspect()).toEqual({
-      frameNumber: -1,
-      dispatches: 0,
-      indirectDraws: 0,
-      subjectOutputs: 0,
-    });
     expect(await host.detachWorld({ world })).toMatchObject({
       ok: true,
       value: { state: 'detached' },
     });
   });
 
-  it('shares an App-selected GPU decoder when the host attaches the same registry', async () => {
+  it('preserves the asset registry receiver while planning a material projection', async () => {
     const world = new World();
-    const assets = createAssetRegistry({
-      catalog: createCatalogSource({ entries: [] }),
-    });
-    assets.installDecoder(vfxGpuEffectContribution.kind, vfxGpuEffectContribution.decoder);
-    const host = createVfxRuntimeHost({ camera: { read: () => undefined } });
+    const lookups: string[] = [];
+    class StatefulAssets {
+      readonly material: MaterialAsset = { kind: 'material', values: {} };
+      readonly loaders = { registerPackLoader: () => {} };
 
-    expect(await host.attachWorld({ world, assets })).toMatchObject({
-      ok: true,
-      value: { state: 'attached' },
-    });
-    expect(await host.detachWorld({ world })).toMatchObject({
-      ok: true,
-      value: { state: 'detached' },
+      lookup<T extends Asset = Asset>(guid: string): T | undefined {
+        if (this !== assets) throw new Error('asset registry receiver was lost');
+        lookups.push(guid);
+        return guid === 'material-guid' ? (this.material as T) : undefined;
+      }
+    }
+    const assets = new StatefulAssets();
+    const host = createVfxRuntimeHost({
+      camera: {
+        read: () => ({
+          position: new Float32Array(3),
+          right: new Float32Array([1, 0, 0]),
+          up: new Float32Array([0, 1, 0]),
+          viewProjection: new Float32Array([1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1]),
+        }),
+      },
     });
-    assets.dispose();
+    expect(await host.attachWorld({ world, assets })).toMatchObject({ ok: true });
+
+    const intent = {
+      player: world.spawn().unwrap(),
+      fixedDelta: 1 / 60,
+      phaseTick: 0,
+      seed: 1,
+      playCycle: 0,
+      spawnCount: 1,
+      firstParticleId: 0,
+      reset: true,
+      channelInputs: [],
+      emitter: {
+        id: 'receiver-check',
+        capacity: 4,
+        backend: { required: 'gpu' },
+        space: 'world',
+        simulationWhenCulled: 'continue',
+        schedule: { rate: 0, bursts: [] },
+        bounds: { kind: 'sphere', center: [0, 0, 0], radius: 1 },
+        wgsl: '// receiver check',
+        reflection: { entryPoints: [], bindings: [] },
+        renderers: [{ kind: 'billboard', material: 'material-guid' }],
+      },
+    } as unknown as VfxGpuTickIntent;
+    const planned = host.feature.plan(
+      {
+        worlds: [
+          {
+            world,
+            runtime: {
+              isEmitterSessionEnabled: () => true,
+              setEmitterCameraVisibility: () => {},
+              markEventDispatched: () => {},
+              commit: () => {},
+            },
+            camera: {
+              position: new Float32Array(3),
+              right: new Float32Array([1, 0, 0]),
+              up: new Float32Array([0, 1, 0]),
+              viewProjection: new Float32Array([1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1]),
+            },
+            intents: [intent],
+          },
+        ],
+        frameNumber: 1,
+      } as never,
+      {
+        targets: [],
+        caps: {},
+        frame: { frameNumber: 1 },
+        generation: 1,
+      } as never,
+    );
+    expect(planned.ok).toBe(true);
+    expect(lookups).toEqual(['material-guid']);
+    await host.detachWorld({ world });
   });
 
   it('fences preview controls to one attached host generation', async () => {
     const world = new World();
     const assets = {
-      installDecoder: () => ({ kind: 'particle-effect', dispose: () => {} }),
+      loaders: { registerPackLoader: () => {} },
+      lookup: () => undefined,
     };
     const host = createVfxRuntimeHost({ camera: { read: () => undefined } });
     expect(host.acquireControl(world)).toMatchObject({
@@ -145,7 +199,7 @@ describe('GPU VFX public host', () => {
     expect(host.acquireControl(world)).toMatchObject({ ok: true, value: { generation: 2 } });
   });
 
-  it('starts every pending emitter program in one prepare frame', () => {
+  it('declares every pending emitter program in one feature plan', () => {
     const world = new World();
     const player = world.spawn().unwrap();
     const intent = (id: string): VfxGpuTickIntent => ({
@@ -206,45 +260,41 @@ describe('GPU VFX public host', () => {
         lastSequence: -1,
       },
     });
-    const prepareProgram = vi.fn((name: string) =>
-      err(
-        new RenderFeaturePreparationFailedError(
-          'forgeax.vfx-render.gpu-particles',
-          -1,
-          'prepare-gpu-program',
-          'pipeline',
-          name,
-          'rhi-not-available:compile pending',
-          'next-frame',
-        ),
-      ),
-    );
     const feature = gpuParticleRenderFeature({ camera: { read: () => undefined } });
-
-    const prepared = feature.prepare(
+    const planned = feature.plan(
       {
         worlds: [
           {
             world,
-            runtime: {},
-            camera: {},
+            runtime: {
+              isEmitterSessionEnabled: () => true,
+              setEmitterCameraVisibility: () => {},
+              markEventDispatched: () => {},
+              commit: () => {},
+            },
+            camera: {
+              position: new Float32Array(3),
+              right: new Float32Array([1, 0, 0]),
+              up: new Float32Array([0, 1, 0]),
+              viewProjection: new Float32Array([1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1]),
+            },
             intents: [intent('first'), intent('second')],
           },
         ],
         frameNumber: 1,
       } as never,
-      { gpu: { prepareProgram }, targets: [] } as never,
+      { targets: [], caps: {}, frame: { frameNumber: 1 }, generation: 1 } as never,
     );
-
-    expect(prepared).toMatchObject({ ok: false, error: { detail: { recovery: 'next-frame' } } });
-    expect(prepareProgram).toHaveBeenCalledTimes(2);
-    expect(prepareProgram.mock.calls.map(([name]) => name)).toEqual([
-      expect.stringContaining('.first.'),
-      expect.stringContaining('.second.'),
-    ]);
+    expect(planned.ok).toBe(true);
+    if (!planned.ok) return;
+    expect(
+      planned.value.resources
+        .filter((resource) => resource.kind === 'compute-program')
+        .map((resource) => resource.name),
+    ).toEqual([expect.stringContaining('.first.'), expect.stringContaining('.second.')]);
   });
 
-  it('fences render consumption and keeps masked bindings warm', () => {
+  it('keeps masked bindings warm and sends effect-relative time to WGSL', () => {
     const world = new World();
     const player = world.spawn().unwrap();
     const intent = (tick: number): VfxGpuTickIntent => ({
@@ -306,38 +356,11 @@ describe('GPU VFX public host', () => {
       },
     });
     let sessionEnabled = true;
-    let renderConsumptionEnabled = true;
-    let generation = 0;
-    const liveBindings = new Set<object>();
-    const prepareProgram = vi.fn(() => ok({ generation: 1 } as never));
-    const prepareBuffer = vi.fn((_name: string, _descriptor: { readonly data?: Uint8Array }) =>
-      ok({ generation: 1 } as never),
-    );
-    const prepareBindings = vi.fn(() => {
-      generation += 1;
-      const reference = { generation: 1, id: generation };
-      liveBindings.add(reference);
-      return ok(reference as never);
-    });
-    const retainBindings = vi.fn((references: readonly object[]) =>
-      references.every((reference) => liveBindings.has(reference))
-        ? ok(undefined)
-        : err(
-            new RenderFeaturePreparationFailedError(
-              'forgeax.vfx-render.gpu-particles',
-              -1,
-              'retain-gpu-bindings',
-              'bindings',
-              'persistent-bindings',
-              'bindings-unavailable',
-              'next-frame',
-            ),
-          ),
-    );
     const runtime = {
-      hasPlayer: () => true,
       isEmitterSessionEnabled: () => sessionEnabled,
       setEmitterCameraVisibility: () => {},
+      markEventDispatched: () => {},
+      commit: () => {},
     };
     const camera = {
       position: new Float32Array(3),
@@ -345,45 +368,39 @@ describe('GPU VFX public host', () => {
       up: new Float32Array([0, 1, 0]),
       viewProjection: new Float32Array(16),
     };
-    const feature = gpuParticleRenderFeature({
-      camera: { read: () => camera },
-      playerConsumption: { isEnabled: () => renderConsumptionEnabled },
-    });
-    const context = {
-      gpu: { prepareProgram, prepareBuffer, prepareBindings, retainBindings },
-      targets: [],
-    } as never;
+    const feature = gpuParticleRenderFeature({ camera: { read: () => camera } });
+    const context = { targets: [], caps: {}, frame: { frameNumber: 1 }, generation: 1 } as never;
     const frame = (intents: readonly VfxGpuTickIntent[], frameNumber: number) =>
       ({
         worlds: [{ world, runtime, camera, intents }],
         frameNumber,
       }) as never;
 
-    expect(feature.prepare(frame([intent(0)], 1), context).ok).toBe(true);
-    const runtimeWrite = prepareBuffer.mock.calls.find(([name]) => name.includes('.runtime.'))?.[1];
-    expect(runtimeWrite?.data).toBeInstanceOf(Uint8Array);
-    expect(new Uint32Array((runtimeWrite?.data as Uint8Array).buffer)[1]).toBe(7);
-    renderConsumptionEnabled = false;
-    expect(feature.prepare(frame([], 2), context).ok).toBe(true);
-    // Despawned players must not fall back to the retained lastIntent,
-    // otherwise the missing Transform is rendered once at world origin.
-    expect(retainBindings).toHaveBeenCalledTimes(1);
-    renderConsumptionEnabled = true;
+    const active = feature.plan(frame([intent(0)], 1), context);
+    expect(active.ok).toBe(true);
+    if (!active.ok) return;
+    const runtimeWrite = active.value.resources.find(
+      (resource) => resource.kind === 'buffer' && resource.name.endsWith('.runtime'),
+    );
+    expect(runtimeWrite?.kind === 'buffer' ? runtimeWrite.data : undefined).toBeInstanceOf(
+      Uint8Array,
+    );
+    const runtimeBytes = runtimeWrite?.kind === 'buffer' ? runtimeWrite.data : undefined;
+    expect(new Uint32Array((runtimeBytes as Uint8Array).buffer)[1]).toBe(7);
     sessionEnabled = false;
-    expect(feature.prepare(frame([], 3), context).ok).toBe(true);
-    // Session isolation is not a resource lifetime boundary. A paused player
-    // can be re-enabled without a fresh simulation intent, so the masked frame
-    // must keep its prepared bindings warm while contributing no work.
-    expect(retainBindings).toHaveBeenCalledTimes(2);
+    const masked = feature.plan(frame([intent(1)], 2), context);
+    expect(masked).toMatchObject({ ok: true, value: { resources: [], passes: [] } });
     sessionEnabled = true;
-    expect(feature.prepare(frame([], 4), context).ok).toBe(true);
-    expect(retainBindings).toHaveBeenLastCalledWith([expect.objectContaining({ id: generation })]);
+    const resumed = feature.plan(frame([intent(2)], 3), context);
+    expect(resumed.ok).toBe(true);
+    if (resumed.ok) expect(resumed.value.resources.length).toBeGreaterThan(0);
   });
 
   it('rejects a second host without replacing the first World runtime', async () => {
     const world = new World();
     const assets = {
-      installDecoder: () => ({ kind: 'particle-effect', dispose: () => {} }),
+      loaders: { registerPackLoader: () => {} },
+      lookup: () => undefined,
     };
     const options = {
       camera: {
@@ -426,7 +443,8 @@ describe('GPU VFX public host', () => {
   it('returns an empty keyed inspection aggregate before a player is present', async () => {
     const world = new World();
     const assets = {
-      installDecoder: () => ({ kind: 'particle-effect', dispose: () => {} }),
+      loaders: { registerPackLoader: () => {} },
+      lookup: () => undefined,
     };
     const host = createVfxRuntimeHost({ camera: { read: () => undefined } });
     await host.attachWorld({ world, assets: assets as never });

package/src/__tests__/particle-resources.unit.test.ts

@@ -4,7 +4,6 @@ import {
   canonicalMeshVertices,
   particleMaterialPass,
   particleMaterialUsesBindings,
-  particleMaterialUsesSceneDepth,
 } from '../feature/particle-resources.js';
 
 describe('particle mesh resources', () => {
@@ -54,14 +53,6 @@ describe('particle material pass', () => {
     });
   });
 
-  it('uses the renderer-owned shader contract for scene-depth selection', () => {
-    expect(particleMaterialUsesSceneDepth('group-0-resource')).toBe(true);
-    expect(particleMaterialUsesSceneDepth('view-with-resource')).toBe(true);
-    expect(particleMaterialUsesSceneDepth('group-0')).toBe(false);
-    expect(particleMaterialUsesSceneDepth('view-only')).toBe(false);
-    expect(particleMaterialUsesSceneDepth('render-material')).toBe(false);
-  });
-
   it('does not mistake an ordinary Forward pass for a particle shader', () => {
     const material: MaterialAsset = {
       kind: 'material',

package/src/__tests__/stage-plan.integration.test.ts

@@ -1,6 +1,10 @@
 import { readFileSync } from 'node:fs';
 import { resolve } from 'node:path';
+import type { RenderFeaturePlan } from '@forgeax/engine-render';
+import type { VfxGpuTickIntent } from '@forgeax/engine-vfx';
 import { describe, expect, it } from 'vitest';
+import { freezeRenderFeaturePlan } from '../../../render/src/features/plan';
+import { gpuParticleRenderFeature } from '../feature/gpu-particle-feature.js';
 
 const stagePlanPath = resolve(import.meta.dirname, '../feature/stage-plan.ts');
 
@@ -13,4 +17,132 @@ describe('VFX managed stage execution seam', () => {
     expect(source).toContain('forgeax_vfx_stage_');
     expect(source).not.toContain('authorRawDispatch');
   });
+
+  it('projects a VFX stage into the closed render feature plan surface', () => {
+    const source = readFileSync(
+      resolve(import.meta.dirname, '../feature/gpu-particle-feature.ts'),
+      'utf8',
+    );
+    const plan: RenderFeaturePlan = { resources: [], passes: [] };
+    expect(source).toContain('RenderFeaturePlan');
+    expect(source).not.toMatch(/GPUCommandEncoder|queue\.submit|encoder\.finish/);
+    expect(plan.passes).toEqual([]);
+  });
+
+  it('declares storage-produced indirect work and dependent raster descriptors', () => {
+    const intent = {
+      sequence: 1,
+      player: 1,
+      emitter: {
+        id: 'spark',
+        capacity: 4,
+        space: 'world',
+        bounds: { kind: 'sphere', center: [0, 0, 0], radius: 1 },
+        wgsl: '// cooked VFX program',
+        reflection: {
+          entryPoints: ['forgeax_vfx_spawn_main', 'forgeax_vfx_billboard_main'],
+          bindings: [
+            {
+              entries: [
+                { binding: 0, visibility: 4, buffer: { type: 'storage' } },
+                { binding: 1, visibility: 4, buffer: { type: 'uniform' } },
+                { binding: 4, visibility: 4, buffer: { type: 'storage' } },
+                { binding: 6, visibility: 4, buffer: { type: 'storage' } },
+              ],
+            },
+          ],
+          stages: [],
+          dataInterfaces: [],
+        },
+        renderers: [
+          {
+            kind: 'billboard',
+            material: 'material-guid',
+            blend: 'additive',
+            sorting: 'none',
+          },
+        ],
+      },
+      programFingerprint: 'spark-program',
+      reset: true,
+      fixedDelta: 1 / 60,
+      phaseTick: 0,
+      tick: 0,
+      seed: 1,
+      playCycle: 0,
+      spawnCount: 1,
+      firstParticleId: 0,
+      instanceGeneration: 1,
+      channelInputs: [],
+      eventCounters: {},
+    } as unknown as VfxGpuTickIntent;
+    const runtime = {
+      isEmitterSessionEnabled: () => true,
+      setEmitterCameraVisibility: () => {},
+      markEventDispatched: () => {},
+      commit: () => {},
+    };
+    const feature = gpuParticleRenderFeature({ camera: { read: () => undefined } });
+    const planned = feature.plan(
+      {
+        worlds: [
+          {
+            world: {},
+            runtime,
+            camera: {
+              position: new Float32Array(3),
+              right: new Float32Array([1, 0, 0]),
+              up: new Float32Array([0, 1, 0]),
+              viewProjection: new Float32Array([1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1]),
+            },
+            intents: [intent],
+          },
+        ],
+        frameNumber: 1,
+      } as never,
+      {
+        caps: {} as never,
+        frame: { frameNumber: 1 },
+        generation: 1,
+        targets: [
+          { name: 'scene-color', kind: 'color', format: 'rgba16float', sampleCount: 1 },
+          { name: 'scene-depth', kind: 'depth', format: 'depth24plus', sampleCount: 1 },
+        ],
+      },
+    );
+
+    expect(planned.ok).toBe(true);
+    if (!planned.ok) return;
+    expect(
+      freezeRenderFeaturePlan(feature.identity, planned.value, [
+        { name: 'scene-color', kind: 'color', format: 'rgba16float', sampleCount: 1 },
+        { name: 'scene-depth', kind: 'depth', format: 'depth24plus', sampleCount: 1 },
+      ]).ok,
+    ).toBe(true);
+    expect(planned.value.resources).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({
+          kind: 'buffer',
+          name: expect.stringContaining('.indirect'),
+          usage: ['storage', 'indirect'],
+        }),
+        expect.objectContaining({ kind: 'graphics-program' }),
+        expect.objectContaining({ kind: 'graphics-bindings' }),
+        expect.objectContaining({ kind: 'vertex-data' }),
+      ]),
+    );
+    expect(planned.value.passes).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({ kind: 'compute' }),
+        expect.objectContaining({
+          kind: 'raster',
+          draws: [
+            expect.objectContaining({
+              draw: expect.objectContaining({ kind: 'draw-indirect' }),
+            }),
+          ],
+        }),
+      ]),
+    );
+  });
 });