@forgeax/engine-vfx-render 0.1.28 → 0.1.29

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

@@ -2,10 +2,12 @@ import type { MaterialAsset, MeshAsset } from '@forgeax/engine-types';
 import { describe, expect, it } from 'vitest';
 import {
   canonicalMeshVertices,
+  canonicalMeshVerticesCached,
   particleMaterialPass,
   particleMaterialSceneDepthBinding,
   particleMaterialUsesBindings,
   particleRendererRenderState,
+  prepareParticleMaterialInputs,
 } from '../feature/particle-resources.js';
 
 describe('particle mesh resources', () => {
@@ -22,6 +24,37 @@ describe('particle mesh resources', () => {
 
     expect(canonicalMeshVertices(mesh)).toBe(vertices);
   });
+
+  it('reuses derived vertices only for frozen asset publications', () => {
+    const mesh = Object.freeze({
+      kind: 'mesh' as const,
+      vertices: new Float32Array(),
+      attributes: { position: new Float32Array([0, 1, 2]) },
+      indices: new Uint16Array([0]),
+      submeshes: [],
+      materialSlots: [],
+    }) as unknown as MeshAsset;
+    const first = canonicalMeshVerticesCached(mesh);
+    const second = canonicalMeshVerticesCached(mesh);
+    expect(second).toBe(first);
+    expect(Array.from(second)).toEqual([0, 1, 2, 0, 0, 1, 0, 0, 1, 0, 0, 1]);
+  });
+
+  it('does not hide mutations on unfrozen authoring meshes', () => {
+    const mesh = {
+      kind: 'mesh' as const,
+      vertices: new Float32Array(),
+      attributes: { position: new Float32Array([0, 1, 2]) },
+      indices: new Uint16Array([0]),
+      submeshes: [],
+      materialSlots: [],
+    } as unknown as MeshAsset;
+    const first = canonicalMeshVerticesCached(mesh);
+    (mesh.attributes.position as Float32Array)[0] = 7;
+    const second = canonicalMeshVerticesCached(mesh);
+    expect(second).not.toBe(first);
+    expect(second[0]).toBe(7);
+  });
 });
 
 describe('particle material pass', () => {
@@ -36,6 +69,7 @@ describe('particle material pass', () => {
       }),
     ).toBe(true);
   });
+
   it('uses the renderer-specific authored shader and render state', () => {
     const material: MaterialAsset = {
       kind: 'material',
@@ -73,6 +107,47 @@ describe('particle material pass', () => {
       shader: 'forgeax::vfx-render.particles.mesh',
     });
   });
+
+  it('returns a structured missing-input error instead of dereferencing an absent declaration', () => {
+    expect(
+      prepareParticleMaterialInputs(
+        {
+          kind: 'billboard',
+          material: '019e9c00-0000-7000-8000-000000000003',
+          materialInputs: ['heat'],
+        },
+        { kind: 'material', particleInputs: [] },
+        [],
+      ),
+    ).toMatchObject({
+      ok: false,
+      error: { code: 'vfx-material-input-missing', detail: { name: 'heat' } },
+    });
+  });
+});
+
+describe('VFX Mesh world-space projection', () => {
+  it('adapts Standard geometry without discarding the ordinary material render state', () => {
+    const renderState = {
+      depthCompare: 'less-equal',
+      depthWriteEnabled: true,
+      queue: 2000,
+    } as const;
+    const material = {
+      kind: 'material',
+      passes: [
+        {
+          name: 'forward',
+          program: { module: 'forgeax::default-standard-pbr' },
+          renderState,
+        },
+      ],
+    } as MaterialAsset;
+    expect(particleMaterialPass('mesh', material)).toEqual({
+      shader: 'forgeax::vfx-render.particles.mesh',
+      renderState,
+    });
+  });
 });
 
 describe('particle renderer blend defaults', () => {

package/src/__tests__/persistent-ticks.integration.test.ts

@@ -0,0 +1,162 @@
+import { createWorldContext, World } from '@forgeax/engine-ecs';
+import type { ParticleEffectAsset } from '@forgeax/engine-types';
+import {
+  ParticleEffectPlayer,
+  VFX_GPU_RUNTIME_RESOURCE_KEY,
+  type VfxGpuRuntime,
+  vfxGpuRuntimePlugin,
+} from '@forgeax/engine-vfx';
+import { cookParticleCodeProgram } from '@forgeax/engine-vfx-compiler';
+import { expect, it } from 'vitest';
+import { freezeRenderFeaturePlan } from '../../../render/src/features/plan.js';
+import { gpuParticleRenderFeature } from '../feature/gpu-particle-feature.js';
+
+it.each([
+  false,
+  true,
+])('retains particles and acknowledges ordered work only after submission (events=%s)', async (events) => {
+  const result = await cookParticleCodeProgram(
+    {
+      schemaVersion: 3,
+      emitters: [
+        {
+          id: 'persistent',
+          capacity: 4,
+          backend: { required: 'gpu' },
+          space: 'world',
+          bounds: { kind: 'sphere', center: [0, 0, 0], radius: 10 },
+          schedule: { rate: 0, bursts: [{ time: 0, count: 1 }] },
+          program: { module: 'persistent.wgsl' },
+          renderers: [{ kind: 'billboard', material: 'material' }],
+          ...(events
+            ? {
+                channels: [{ id: 'hit', capacity: 2, overflow: 'drop-newest' }],
+                events: [
+                  {
+                    id: 'hit',
+                    channel: 'hit',
+                    subEmitter: 'persistent',
+                    fanOut: 2,
+                    recursionDepth: 1,
+                  },
+                ],
+              }
+            : {}),
+        },
+      ],
+    },
+    {
+      'persistent.wgsl': {
+        entry: `#import forgeax_vfx::prelude::{VfxParticle, VfxSpawnContext, VfxUpdateContext}
+fn vfx_spawn(ctx: VfxSpawnContext, particle: ptr<function, VfxParticle>) { (*particle).lifetime = 86400.0; }
+fn vfx_update(ctx: VfxUpdateContext, particle: ptr<function, VfxParticle>) { (*particle).position.x += ctx.delta; }`,
+      },
+    },
+  );
+  if (!result.ok) throw result.error;
+  const asset: ParticleEffectAsset = {
+    kind: 'particle-effect',
+    schemaVersion: 3,
+    programFingerprint: result.value.fingerprint,
+    emitters: [{ id: 'persistent', capacity: 4 }],
+    program: { ...result.value.program, fingerprint: result.value.fingerprint },
+  };
+  const world = new World();
+  const handle = world.allocSharedRef('ParticleEffectAsset', { ...asset, guid: 'effect' });
+  const player = world
+    .spawn({
+      component: ParticleEffectPlayer,
+      data: { effect: handle, playing: true, seed: 1, timeScale: 1 },
+    })
+    .unwrap();
+  const context = await createWorldContext(world, [vfxGpuRuntimePlugin()]);
+  const runtime = world.getResource<VfxGpuRuntime>(VFX_GPU_RUNTIME_RESOURCE_KEY);
+  const 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]),
+  };
+  const feature = gpuParticleRenderFeature({ camera: { read: () => camera } });
+  const targets = [
+    {
+      name: 'color',
+      kind: 'color' as const,
+      format: 'rgba8unorm' as const,
+      sampleCount: 1 as const,
+    },
+  ];
+  let frameNumber = 0;
+  const frame = (worlds = [world]) => {
+    const extracted = feature.extract({ worlds, owner: 0, frameNumber: ++frameNumber }).unwrap();
+    const plan = feature
+      .plan(extracted, {
+        targets,
+        caps: {} as never,
+        frame: { frameNumber },
+        generation: 0,
+        sceneData: {} as never,
+      })
+      .unwrap();
+    expect(freezeRenderFeaturePlan(feature.identity, plan, targets).ok).toBe(true);
+    return { extracted, plan };
+  };
+  const particleName = (plan: ReturnType<typeof frame>['plan']) =>
+    plan.resources.find((resource) => resource.name.endsWith('.particles'))?.name;
+  try {
+    world.update(1 / 60).unwrap();
+    const first = frame();
+    const entries = first.plan.passes.flatMap((pass) =>
+      pass.kind === 'compute' ? pass.dispatches.map((dispatch) => dispatch.entryPoint) : [],
+    );
+    const eventIndex = entries.indexOf('forgeax_vfx_event_main');
+    if (events) {
+      expect(eventIndex).toBeGreaterThan(0);
+      expect(entries.slice(eventIndex + 1, eventIndex + 5)).toEqual([
+        'forgeax_vfx_scan_blocks_main',
+        'forgeax_vfx_scan_block_offsets_main',
+        'forgeax_vfx_add_offsets_main',
+        'forgeax_vfx_compact_main',
+      ]);
+    } else expect(eventIndex).toBe(-1);
+    expect(runtime.snapshot()).toHaveLength(1);
+    const retry = frame();
+    expect(particleName(retry.plan)).toBe(particleName(first.plan));
+    feature.onFrameSubmitted?.(retry.extracted);
+    expect(runtime.snapshot()).toHaveLength(0);
+    const presentation = frame([new World(), world]);
+    expect(particleName(presentation.plan)).toBe(particleName(first.plan));
+    expect(presentation.plan.passes.filter((pass) => pass.kind === 'raster')).toHaveLength(1);
+    expect(
+      presentation.plan.passes
+        .flatMap((pass) => (pass.kind === 'compute' ? pass.dispatches : []))
+        .some((dispatch) => /spawn|update|history/.test(dispatch.entryPoint)),
+    ).toBe(false);
+    expect(
+      presentation.plan.resources.find(
+        (resource) => resource.kind === 'buffer' && resource.name.endsWith('.indirect'),
+      ),
+    ).not.toHaveProperty('data');
+    world.update(1 / 60).unwrap();
+    world.update(1 / 60).unwrap();
+    const catchup = frame();
+    expect(runtime.snapshot()).toHaveLength(2);
+    expect(catchup.plan.passes.filter((pass) => pass.name.endsWith('.simulate'))).toHaveLength(2);
+    expect(catchup.plan.passes.filter((pass) => pass.kind === 'raster')).toHaveLength(1);
+    expect(particleName(catchup.plan)).toBe(particleName(first.plan));
+    expect(
+      catchup.plan.resources.find((resource) => resource.name.endsWith('.indirect')),
+    ).not.toHaveProperty('data');
+    feature.onFrameSubmitted?.(catchup.extracted);
+    expect(runtime.snapshot()).toHaveLength(0);
+    runtime.replay(player);
+    world.update(1 / 60).unwrap();
+    const replay = frame();
+    expect(particleName(replay.plan)).not.toBe(particleName(first.plan));
+    feature.onFrameSubmitted?.(replay.extracted);
+    runtime.reset(player);
+    expect(frame().plan.resources).toEqual([]);
+  } finally {
+    await context.fiber.dispose();
+  }
+});

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

@@ -1,5 +1,5 @@
 import { readFileSync } from 'node:fs';
-import type { ParticleRendererSource } from '@forgeax/engine-vfx';
+import type { ParticleRendererSourceV3 } from '@forgeax/engine-vfx';
 import { describe, expect, expectTypeOf, it } from 'vitest';
 import type {
   createVfxRenderInspectSnapshot,
@@ -13,8 +13,8 @@ import type {
 } 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 RendererKind = ParticleRendererSourceV3['kind'];
+type TopologyRenderer = Extract<ParticleRendererSourceV3, { readonly capacity: number }>;
 type TopologyKind = TopologyRenderer['kind'];
 type StageOutput = VfxStagePlanObservation['stageOutput'];
 
@@ -62,16 +62,16 @@ describe('VFX render vocabulary owners', () => {
 
   it('keeps both production projections derived from the source owner', () => {
     expect(normalizedGpuFeatureSource).toContain(
-      "type ParticleRendererKind = ParticleRendererSource['kind'];",
+      "type ParticleRendererKind = ParticleRendererSourceV3['kind'];",
     );
     expect(normalizedParticleResourcesSource).toContain(
-      "type ParticleRendererKind = ParticleRendererSource['kind'];",
+      "type ParticleRendererKind = ParticleRendererSourceV3['kind'];",
     );
     expect(normalizedGpuFeatureSource).toContain(
-      'type ParticleTopologyRenderer = Extract<ParticleRendererSource, { readonly capacity: number }>;',
+      'type ParticleTopologyRenderer = Extract<ParticleRendererSourceV3, { readonly capacity: number }>;',
     );
     expect(normalizedParticleResourcesSource).toContain(
-      'type ParticleTopologyRenderer = Extract<ParticleRendererSource, { readonly capacity: number }>;',
+      'type ParticleTopologyRenderer = Extract<ParticleRendererSourceV3, { readonly capacity: number }>;',
     );
     expect(gpuFeatureSource).toContain('readonly topology: ParticleRendererKind;');
     expect(gpuFeatureSource).toContain('topology: ParticleTopologyKind,');

package/src/feature/event-resources.ts

@@ -1,10 +1,10 @@
-import type { VfxGpuEmitterProgram, VfxGpuTickIntent } from '@forgeax/engine-vfx';
+import type { VfxGpuEmitterProgramAny, 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 {
+function channelFanOut(emitter: VfxGpuEmitterProgramAny, channel: string): number {
   return Math.max(
     1,
     ...(emitter.events ?? [])
@@ -13,14 +13,14 @@ function channelFanOut(emitter: VfxGpuEmitterProgram, channel: string): number {
   );
 }
 
-export function eventInputCapacity(emitter: VfxGpuEmitterProgram): number {
+export function eventInputCapacity(emitter: VfxGpuEmitterProgramAny): number {
   return Math.max(
     1,
     (emitter.channels ?? []).reduce((total, channel) => total + channel.capacity, 0),
   );
 }
 
-export function eventCapacity(emitter: VfxGpuEmitterProgram): number {
+export function eventCapacity(emitter: VfxGpuEmitterProgramAny): number {
   const capacity = (emitter.channels ?? []).reduce(
     (total, channel) => total + channel.capacity * channelFanOut(emitter, channel.id),
     0,
@@ -57,6 +57,20 @@ export function encodeEventInputs(intent: VfxGpuTickIntent): Uint8Array {
   return bytes;
 }
 
+/**
+ * Pack the fixed-tick inputs and GPU-produced events into one typed storage
+ * resource. The managed event kernel uses the reflected input capacity as the
+ * split point; this keeps channel/sub-emitter semantics while leaving one
+ * storage binding available for Custom-enabled emitters.
+ */
+export function encodeEventBuffer(intent: VfxGpuTickIntent): Uint8Array {
+  const inputBytes = encodeEventInputs(intent);
+  const outputBytes = eventCapacity(intent.emitter) * VFX_EVENT_BYTES;
+  const data = new Uint8Array(inputBytes.byteLength + outputBytes);
+  data.set(inputBytes);
+  return data;
+}
+
 export function eventCounterData(): Uint8Array {
   return new Uint8Array(VFX_EVENT_COUNTER_BYTES);
 }