@forgeax/engine-vfx-render 0.0.0-dev.8d955ade1c79

package/src/__tests__/inspect-snapshot.integration.test.ts

@@ -0,0 +1,26 @@
+import { describe, expect, it } from 'vitest';
+import { createVfxRenderInspectSnapshot } from '../feature/gpu-particle-feature.js';
+
+describe('VFX render inspect projection', () => {
+  it('reports topology counters, stage readiness, provider state, and timing', () => {
+    const snapshot = createVfxRenderInspectSnapshot({
+      topology: 'beam',
+      capacity: 12,
+      produced: 6,
+      dropped: 1,
+      stageReadiness: [{ id: 'turbulence', state: 'ready', generation: 3 }],
+      providerReadiness: { readiness: 'ready', generation: 3 },
+      gpuTiming: { frameMs: 0.8, samples: 8 },
+    });
+
+    expect(snapshot).toEqual(
+      expect.objectContaining({
+        topology: 'beam',
+        counters: { capacity: 12, produced: 6, dropped: 1 },
+        stageReadiness: expect.arrayContaining([expect.objectContaining({ id: 'turbulence' })]),
+        providerReadiness: { readiness: 'ready', generation: 3 },
+        gpuTiming: { frameMs: 0.8, samples: 8 },
+      }),
+    );
+  });
+});

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

@@ -0,0 +1,66 @@
+import type { MaterialAsset, MeshAsset } from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+import {
+  canonicalMeshVertices,
+  particleMaterialPass,
+  particleMaterialUsesBindings,
+} from '../feature/particle-resources.js';
+
+describe('particle mesh resources', () => {
+  it('preserves authored canonical vertices when the attribute map is empty', () => {
+    const vertices = new Float32Array([
+      0, 1, 0, 0, 1, 0, 0.5, 1, 1, 0, 0, 1, 0, -1, 0, 0, -1, 0, 0.5, 0, 1, 0, 0, 1,
+    ]);
+    const mesh = {
+      vertices,
+      indices: new Uint16Array([0, 1, 0]),
+      attributes: {},
+      submeshes: [],
+    } as unknown as MeshAsset;
+
+    expect(canonicalMeshVertices(mesh)).toBe(vertices);
+  });
+});
+
+describe('particle material pass', () => {
+  it('only requests the shared material bind group for a declared parameter contract', () => {
+    expect(particleMaterialUsesBindings(undefined)).toBe(false);
+    expect(particleMaterialUsesBindings({ kind: 'material', values: {} })).toBe(false);
+    expect(
+      particleMaterialUsesBindings({
+        kind: 'material',
+        parameters: [{ name: 'maskTexture', type: 'texture' }],
+        values: {},
+      }),
+    ).toBe(true);
+  });
+  it('uses the renderer-specific authored shader and render state', () => {
+    const material: MaterialAsset = {
+      kind: 'material',
+      passes: [
+        { name: 'Forward', program: { module: 'game::standard' } },
+        {
+          name: 'particle-billboard',
+          program: { module: 'game::hex-sigil' },
+          renderState: { depthWriteEnabled: false, cullMode: 'none' },
+        },
+      ],
+    };
+
+    expect(particleMaterialPass('billboard', material)).toEqual({
+      shader: 'game::hex-sigil',
+      renderState: { depthWriteEnabled: false, cullMode: 'none' },
+    });
+  });
+
+  it('does not mistake an ordinary Forward pass for a particle shader', () => {
+    const material: MaterialAsset = {
+      kind: 'material',
+      passes: [{ name: 'Forward', program: { module: 'game::standard' } }],
+    };
+
+    expect(particleMaterialPass('mesh', material)).toEqual({
+      shader: 'forgeax::vfx-render.particles.mesh',
+    });
+  });
+});

package/src/__tests__/render-vocabulary-owner.test-d.ts

@@ -0,0 +1,81 @@
+import { readFileSync } from 'node:fs';
+import type { ParticleRendererSource } from '@forgeax/engine-vfx';
+import { describe, expect, expectTypeOf, it } from 'vitest';
+import type {
+  createVfxRenderInspectSnapshot,
+  topologyRecoveryHint,
+  VfxRenderInspectInput,
+} from '../feature/gpu-particle-feature.js';
+import type {
+  ParticleMaterialPass,
+  particleMaterialPass,
+  TopologyResourcePlan,
+} from '../feature/particle-resources.js';
+import type { VfxStagePlanObservation } from '../feature/stage-plan.js';
+
+type RendererKind = ParticleRendererSource['kind'];
+type TopologyRenderer = Extract<ParticleRendererSource, { readonly capacity: number }>;
+type TopologyKind = TopologyRenderer['kind'];
+type StageOutput = VfxStagePlanObservation['stageOutput'];
+
+const gpuFeatureSource = readFileSync(
+  new URL('../feature/gpu-particle-feature.ts', import.meta.url),
+  'utf8',
+);
+const particleResourcesSource = readFileSync(
+  new URL('../feature/particle-resources.ts', import.meta.url),
+  'utf8',
+);
+const normalizedGpuFeatureSource = gpuFeatureSource.replace(/\s+/g, ' ');
+const normalizedParticleResourcesSource = particleResourcesSource.replace(/\s+/g, ' ');
+
+describe('VFX render vocabulary owners', () => {
+  it('keeps the full renderer vocabulary exact and bilateral', () => {
+    expectTypeOf<RendererKind>().toEqualTypeOf<
+      'billboard' | 'mesh' | 'ribbon' | 'trail' | 'beam'
+    >();
+    expectTypeOf<RendererKind>().toEqualTypeOf<VfxRenderInspectInput['topology']>();
+    expectTypeOf<VfxRenderInspectInput['topology']>().toEqualTypeOf<RendererKind>();
+    expectTypeOf<
+      Parameters<typeof createVfxRenderInspectSnapshot>[0]['topology']
+    >().toEqualTypeOf<RendererKind>();
+    expectTypeOf<Parameters<typeof particleMaterialPass>[0]>().toEqualTypeOf<RendererKind>();
+    expectTypeOf<ParticleMaterialPass>().toEqualTypeOf<ReturnType<typeof particleMaterialPass>>();
+  });
+
+  it('derives topology-only views from required-capacity renderers', () => {
+    expectTypeOf<TopologyKind>().toEqualTypeOf<'ribbon' | 'trail' | 'beam'>();
+    expectTypeOf<TopologyKind>().toEqualTypeOf<Parameters<typeof topologyRecoveryHint>[0]>();
+    expectTypeOf<Parameters<typeof topologyRecoveryHint>[0]>().toEqualTypeOf<TopologyKind>();
+    expectTypeOf<TopologyResourcePlan['topology']>().toEqualTypeOf<TopologyKind>();
+    expectTypeOf<TopologyKind>().toEqualTypeOf<TopologyResourcePlan['topology']>();
+  });
+
+  it('derives stage output and keeps the private emitter state projection', () => {
+    expectTypeOf<StageOutput>().toEqualTypeOf<'active' | 'last-known-good' | 'empty'>();
+    expect(normalizedGpuFeatureSource).toContain(
+      "type VfxStageOutput = VfxStagePlanObservation['stageOutput'];",
+    );
+    expect(gpuFeatureSource).toContain('stageOutput: VfxStageOutput;');
+    expect(gpuFeatureSource).not.toContain("stageOutput: 'active' | 'last-known-good' | 'empty';");
+  });
+
+  it('keeps both production projections derived from the source owner', () => {
+    expect(normalizedGpuFeatureSource).toContain(
+      "type ParticleRendererKind = ParticleRendererSource['kind'];",
+    );
+    expect(normalizedParticleResourcesSource).toContain(
+      "type ParticleRendererKind = ParticleRendererSource['kind'];",
+    );
+    expect(normalizedGpuFeatureSource).toContain(
+      'type ParticleTopologyRenderer = Extract<ParticleRendererSource, { readonly capacity: number }>;',
+    );
+    expect(normalizedParticleResourcesSource).toContain(
+      'type ParticleTopologyRenderer = Extract<ParticleRendererSource, { readonly capacity: number }>;',
+    );
+    expect(gpuFeatureSource).toContain('readonly topology: ParticleRendererKind;');
+    expect(gpuFeatureSource).toContain('topology: ParticleTopologyKind,');
+    expect(particleResourcesSource).toContain('readonly topology: ParticleTopologyKind;');
+    expect(particleResourcesSource).toContain('kind: ParticleRendererKind,');
+  });
+});

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

@@ -0,0 +1,148 @@
+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');
+
+describe('VFX managed stage execution seam', () => {
+  it('owns readiness and validated-plan execution in the RenderFeature package', () => {
+    const source = readFileSync(stagePlanPath, 'utf8');
+    expect(source).toContain('validatedStagePlan');
+    expect(source).toContain('stageReadiness');
+    expect(source).toContain('stageOutput');
+    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' }),
+            }),
+          ],
+        }),
+      ]),
+    );
+  });
+});

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

@@ -0,0 +1,24 @@
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { describe, expect, it } from 'vitest';
+
+const stagePlanPath = resolve(import.meta.dirname, '../feature/stage-plan.ts');
+
+describe('VFX stage generation recovery', () => {
+  it('keeps candidate failure and device recovery observable without stale resources', () => {
+    const source = readFileSync(stagePlanPath, 'utf8');
+    expect(source).toContain('candidate');
+    expect(source).toContain('lastKnownGood');
+    expect(source).toContain('generation');
+    expect(source).toContain('retryable');
+    expect(source).toContain('device-loss');
+    expect(source).toContain('stale');
+  });
+
+  it('does not introduce a second VFX RPC or a CPU fallback recovery path', () => {
+    const source = readFileSync(stagePlanPath, 'utf8');
+    expect(source).not.toContain('readback');
+    expect(source).not.toContain('cpuFallback');
+    expect(source).not.toContain('new VFX RPC');
+  });
+});

package/src/__tests__/stage-resource-access-owner.test-d.ts

@@ -0,0 +1,26 @@
+import { readFileSync } from 'node:fs';
+import type { ParticleStageResourceAccess, VfxGpuStageReflection } from '@forgeax/engine-vfx';
+import { describe, expect, expectTypeOf, it } from 'vitest';
+import type { VfxValidatedStage } from '../index.js';
+
+type ReflectedAccess = VfxGpuStageReflection['resources'][number]['access'];
+type ValidatedAccess = VfxValidatedStage['resources'][number]['access'];
+
+const stagePlanSource = readFileSync(new URL('../feature/stage-plan.ts', import.meta.url), 'utf8');
+
+describe('VFX validated stage resource access owner', () => {
+  it('keeps reflected and final validated access equal to the authored owner', () => {
+    expectTypeOf<ReflectedAccess>().toEqualTypeOf<ParticleStageResourceAccess>();
+    expectTypeOf<ParticleStageResourceAccess>().toEqualTypeOf<ReflectedAccess>();
+    expectTypeOf<ValidatedAccess>().toEqualTypeOf<ParticleStageResourceAccess>();
+    expectTypeOf<ParticleStageResourceAccess>().toEqualTypeOf<ValidatedAccess>();
+  });
+
+  it('keeps the final projection derived from reflection without a second vocabulary', () => {
+    expect(stagePlanSource).toContain(
+      "readonly access: VfxGpuStageReflection['resources'][number]['access'];",
+    );
+    expect(stagePlanSource).not.toContain("readonly access: 'read' | 'write' | 'read-write';");
+    expectTypeOf<'unknown-access'>().not.toExtend<ValidatedAccess>();
+  });
+});

package/src/__tests__/stage-resource-layout.unit.test.ts

@@ -0,0 +1,40 @@
+import { describe, expect, it } from 'vitest';
+import { stageDispatches, validatedStagePlan } from '../feature/stage-plan.js';
+
+const reflection = {
+  id: 'turbulence',
+  entry: 'vfx_turbulence',
+  entryPoint: 'forgeax_vfx_stage_turbulence_main',
+  domain: 'particle' as const,
+  resources: [
+    { name: 'particles', access: 'read-write' as const },
+    { name: 'runtime', access: 'read' as const },
+  ],
+  dependsOn: ['update'],
+  iterationBudget: 4,
+};
+
+describe('managed stage resource layout', () => {
+  it('preserves compiler reflection fields and normalizes particle dispatch', () => {
+    const result = validatedStagePlan([reflection], 7);
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    expect(result.value).toMatchObject({
+      generation: 7,
+      stages: [reflection],
+    });
+    expect(result.value.stages[0]?.domain).toBe('particle');
+    expect(result.value.stages[0]?.resources).toEqual(reflection.resources);
+    expect(result.value.stages[0]?.iterationBudget).toBe(4);
+
+    const dispatches = stageDispatches(result.value, 3, undefined as never);
+    expect(dispatches).toEqual([
+      {
+        entryPoint: 'forgeax_vfx_stage_turbulence_main',
+        workgroups: [3],
+        bindings: undefined,
+      },
+    ]);
+  });
+});

package/src/__tests__/topology-capacity.unit.test.ts

@@ -0,0 +1,59 @@
+import { describe, expect, it } from 'vitest';
+import {
+  createTopologyResourcePlan,
+  topologyCapacitySnapshot,
+} from '../feature/particle-resources.js';
+
+describe('topology capacity and degeneracy contract', () => {
+  it('reports ribbon overflow without changing its topology identity', () => {
+    const plan = createTopologyResourcePlan({
+      kind: 'ribbon',
+      material: 'vfx',
+      stripKey: 'alive-index',
+      capacity: 2,
+    });
+
+    expect(plan.ok).toBe(true);
+    if (plan.ok) {
+      expect(topologyCapacitySnapshot(plan.value, { requested: 3, produced: 2 })).toEqual({
+        topology: 'ribbon',
+        capacity: 2,
+        produced: 2,
+        dropped: 1,
+        overflow: 1,
+        degenerate: 0,
+      });
+    }
+  });
+
+  it('distinguishes a broken trail and a degenerate beam from overflow', () => {
+    const trail = createTopologyResourcePlan({
+      kind: 'trail',
+      material: 'vfx',
+      historyLength: 4,
+      capacity: 8,
+    });
+    const beam = createTopologyResourcePlan({
+      kind: 'beam',
+      material: 'vfx',
+      endpointField: 'velocity',
+      capacity: 8,
+    });
+
+    expect(
+      trail.ok &&
+        topologyCapacitySnapshot(trail.value, { requested: 1, produced: 0, degenerate: 1 }),
+    ).toMatchObject({
+      topology: 'trail',
+      degenerate: 1,
+      overflow: 0,
+    });
+    expect(
+      beam.ok && topologyCapacitySnapshot(beam.value, { requested: 1, produced: 0, degenerate: 1 }),
+    ).toMatchObject({
+      topology: 'beam',
+      degenerate: 1,
+      overflow: 0,
+    });
+  });
+});

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

@@ -0,0 +1,29 @@
+import { describe, expect, it } from 'vitest';
+import { createTopologyResourcePlan } from '../feature/particle-resources.js';
+
+describe('independent topology resources', () => {
+  it.each([
+    ['ribbon', { kind: 'ribbon', material: 'vfx', stripKey: 'alive-index', capacity: 4 }],
+    ['trail', { kind: 'trail', material: 'vfx', historyLength: 3, capacity: 5 }],
+    ['beam', { kind: 'beam', material: 'vfx', endpointField: 'velocity', capacity: 2 }],
+  ])('allocates a distinct %s vertex/index/indirect plan', (_kind, renderer) => {
+    const result = createTopologyResourcePlan(renderer);
+
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value.vertexBytes).toBeGreaterThan(0);
+      expect(result.value.indexBytes).toBe(0);
+      expect(result.value.indirectBytes).toBeGreaterThan(0);
+      expect(result.value.resourceKey).not.toMatch(/billboard|mesh|particle/);
+    }
+  });
+
+  it('rejects topology field names that the managed WGSL shell cannot execute', () => {
+    expect(
+      createTopologyResourcePlan({ kind: 'ribbon', stripKey: 'custom', capacity: 4 }),
+    ).toMatchObject({ ok: false, error: { detail: { path: 'renderer.stripKey' } } });
+    expect(
+      createTopologyResourcePlan({ kind: 'beam', endpointField: 'custom', capacity: 4 }),
+    ).toMatchObject({ ok: false, error: { detail: { path: 'renderer.endpointField' } } });
+  });
+});

package/src/feature/camera.ts

@@ -0,0 +1,12 @@
+import type { World } from '@forgeax/engine-ecs';
+
+export interface ParticleRenderCamera {
+  readonly position: Float32Array;
+  readonly right: Float32Array;
+  readonly up: Float32Array;
+  readonly viewProjection: Float32Array;
+}
+
+export interface ParticleRenderCameraSource {
+  readonly read: (world: World) => ParticleRenderCamera | undefined;
+}

package/src/feature/event-resources.ts

@@ -0,0 +1,62 @@
+import type { VfxGpuEmitterProgram, VfxGpuTickIntent } from '@forgeax/engine-vfx';
+
+export const VFX_EVENT_INPUT_BYTES = 32;
+export const VFX_EVENT_BYTES = 32;
+export const VFX_EVENT_COUNTER_BYTES = 16;
+
+function channelFanOut(emitter: VfxGpuEmitterProgram, channel: string): number {
+  return Math.max(
+    1,
+    ...(emitter.events ?? [])
+      .filter((event) => event.channel === channel)
+      .map((event) => event.fanOut),
+  );
+}
+
+export function eventInputCapacity(emitter: VfxGpuEmitterProgram): number {
+  return Math.max(
+    1,
+    (emitter.channels ?? []).reduce((total, channel) => total + channel.capacity, 0),
+  );
+}
+
+export function eventCapacity(emitter: VfxGpuEmitterProgram): number {
+  const capacity = (emitter.channels ?? []).reduce(
+    (total, channel) => total + channel.capacity * channelFanOut(emitter, channel.id),
+    0,
+  );
+  return Math.max(1, Math.min(emitter.capacity, capacity));
+}
+
+function channelKey(channel: string): number {
+  let hash = 2166136261;
+  for (const code of channel) {
+    hash ^= code.codePointAt(0) ?? 0;
+    hash = Math.imul(hash, 16777619);
+  }
+  return hash >>> 0;
+}
+
+export function encodeEventInputs(intent: VfxGpuTickIntent): Uint8Array {
+  const capacity = eventInputCapacity(intent.emitter);
+  const data = new ArrayBuffer(capacity * VFX_EVENT_INPUT_BYTES);
+  const bytes = new Uint8Array(data);
+  bytes.fill(0xff);
+  const view = new DataView(data);
+  for (const [index, input] of intent.channelInputs.entries()) {
+    if (index >= capacity) break;
+    const offset = index * VFX_EVENT_INPUT_BYTES;
+    view.setFloat32(offset, input.payload.position[0], true);
+    view.setFloat32(offset + 4, input.payload.position[1], true);
+    view.setFloat32(offset + 8, input.payload.position[2], true);
+    view.setFloat32(offset + 16, input.payload.strength, true);
+    view.setUint32(offset + 20, input.sequence, true);
+    view.setUint32(offset + 24, channelKey(input.channel), true);
+    view.setUint32(offset + 28, channelFanOut(intent.emitter, input.channel), true);
+  }
+  return bytes;
+}
+
+export function eventCounterData(): Uint8Array {
+  return new Uint8Array(VFX_EVENT_COUNTER_BYTES);
+}