@forgeax/engine-vfx-render 0.1.2

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,16 @@
+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 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');
+  });
+});

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);
+}