@forgeax/engine-vfx 0.1.27 → 0.1.29

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

@@ -10,16 +10,26 @@ import {
   vfxGpuRuntimePlugin,
 } from '../gpu-runtime.js';
 import { ParticleEffectInstance } from '../instance.js';
+import { VFX_PARTICLE_CORE_LAYOUT } from '../particle-layout.js';
 import { ParticleEffectPlayer } from '../player.js';
 
+function commitSnapshot(runtime: VfxGpuRuntime, count = Number.POSITIVE_INFINITY): void {
+  runtime.commit(
+    runtime
+      .snapshot()
+      .slice(0, count)
+      .map((intent) => intent.sequence),
+  );
+}
+
 const effect: VfxGpuEffectAsset = {
   guid: 'effect-guid',
   kind: 'particle-effect',
-  schemaVersion: 2,
+  schemaVersion: 3,
   programFingerprint: 'sha256:test',
   emitters: [{ id: 'sparks', capacity: 100_000 }],
   program: {
-    format: 'forgeax-vfx-program-2',
+    format: 'forgeax-vfx-program-3',
     fingerprint: 'sha256:test',
     emitters: [
       {
@@ -39,6 +49,40 @@ const effect: VfxGpuEffectAsset = {
           resources: [],
           entryPoints: [],
           bindings: [],
+          layout: {
+            version: 3,
+            parameters: { name: 'VfxParameters', fields: [], size: 0, alignment: 1 },
+            custom: { name: 'VfxCustom', fields: [], size: 0, alignment: 1 },
+            core: VFX_PARTICLE_CORE_LAYOUT,
+            customLayout: {
+              name: 'VfxCustom',
+              fields: [],
+              size: 0,
+              alignment: 1,
+              stride: 0,
+              lanes: 0,
+            },
+            fingerprint: 'sha256:test-layout',
+          },
+          dataInterfaces: [],
+          eventChannels: [],
+          events: [],
+          eventEntryPoint: 'forgeax_vfx_event_main',
+          stages: [],
+          renderers: [
+            {
+              topology: 'billboard',
+              resource: 'billboardInstances',
+              capacity: 100_000,
+              overflow: 'drop-newest',
+              enabled: true,
+              shaderInputs: [],
+              attributes: {},
+              materialInputs: [],
+              castShadows: false,
+              receiveShadows: false,
+            },
+          ],
         },
       },
     ],
@@ -52,6 +96,148 @@ describe('GPU VFX fixed-tick intents', () => {
     expect(asset.program.emitters).toHaveLength(1);
   });
 
+  it('keeps skipped queue acknowledgements out of the retained GPU state', async () => {
+    const world = new World();
+    const handle = world.allocSharedRef('ParticleEffectAsset', effect);
+    const player = world
+      .spawn({
+        component: ParticleEffectPlayer,
+        data: { effect: handle, playing: true, seed: 9, timeScale: 1 },
+      })
+      .unwrap();
+    await createWorldContext(world, [vfxGpuRuntimePlugin()]);
+    const runtime = world.getResource<VfxGpuRuntime>(VFX_GPU_RUNTIME_RESOURCE_KEY);
+
+    world.update(1 / 60).unwrap();
+    const first = runtime.snapshot()[0];
+    expect(first).toBeDefined();
+    if (first === undefined) return;
+    runtime.commit(first.sequence);
+    expect(runtime.lastCommittedEmitter(player, 'sparks')?.sequence).toBe(first.sequence);
+
+    world.update(1 / 60).unwrap();
+    const skipped = runtime.snapshot()[0];
+    expect(skipped).toBeDefined();
+    if (skipped === undefined) return;
+    // Queue acknowledgement alone must not publish a state whose GPU
+    // simulation/history was never submitted.
+    runtime.commit(skipped.sequence, []);
+    expect(runtime.lastCommittedEmitter(player, 'sparks')?.sequence).toBe(first.sequence);
+
+    world.update(1 / 60).unwrap();
+    const dispatched = runtime.snapshot()[0];
+    expect(dispatched).toBeDefined();
+    if (dispatched === undefined) return;
+    runtime.commit(dispatched.sequence, [dispatched.sequence]);
+    expect(runtime.lastCommittedEmitter(player, 'sparks')?.sequence).toBe(dispatched.sequence);
+  });
+
+  it('defers a seed reset until a session-disabled emitter can submit', async () => {
+    const world = new World();
+    const handle = world.allocSharedRef('ParticleEffectAsset', effect);
+    const player = world
+      .spawn({
+        component: ParticleEffectPlayer,
+        data: { effect: handle, playing: true, seed: 1, timeScale: 1 },
+      })
+      .unwrap();
+    await createWorldContext(world, [vfxGpuRuntimePlugin()]);
+    const runtime = world.getResource<VfxGpuRuntime>(VFX_GPU_RUNTIME_RESOURCE_KEY);
+
+    world.update(1 / 30).unwrap();
+    const firstIntents = [...runtime.snapshot()];
+    const first = firstIntents.find((intent) => intent.reset);
+    expect(first).toMatchObject({ reset: true, seed: 1, phaseTick: 0 });
+    if (first === undefined) return;
+    const firstTerminal = firstIntents.at(-1);
+    if (firstTerminal === undefined) return;
+    runtime.commit(
+      firstTerminal.sequence,
+      firstIntents.map((intent) => intent.sequence),
+    );
+    expect(runtime.lastCommittedEmitter(player, 'sparks')).toMatchObject({ seed: 1 });
+
+    runtime.setEmitterSessionEnabled(player, 'sparks', false);
+    world.set(player, ParticleEffectPlayer, { seed: 2 }).unwrap();
+    world.update(0).unwrap();
+    world.update(1 / 30).unwrap();
+    world.update(1 / 30).unwrap();
+    expect(runtime.snapshot()).toHaveLength(0);
+    expect(runtime.inspectPlayer(player)?.lastCommitted?.sequence).toBe(firstTerminal.sequence);
+    expect(runtime.lastCommittedEmitter(player, 'sparks')?.seed).toBe(1);
+
+    runtime.setEmitterSessionEnabled(player, 'sparks', true);
+    world.update(1 / 30).unwrap();
+    const resumed = runtime.snapshot().find((intent) => intent.reset);
+    expect(resumed).toMatchObject({ reset: true, seed: 2, phaseTick: 0 });
+    if (resumed === undefined) return;
+    const resumedIntents = [...runtime.snapshot()];
+    const resumedTerminal = resumedIntents.at(-1);
+    if (resumedTerminal === undefined) return;
+    runtime.commit(
+      resumedTerminal.sequence,
+      resumedIntents.map((intent) => intent.sequence),
+    );
+    expect(runtime.lastCommittedEmitter(player, 'sparks')).toMatchObject({ seed: 2 });
+  });
+
+  it('keeps a disabled emitter reset pending when a sibling emitter stays active', async () => {
+    const world = new World();
+    const multiEmitterEffect = structuredClone(effect) as VfxGpuEffectAsset;
+    const primary = multiEmitterEffect.program.emitters[0];
+    if (primary === undefined) return;
+    const emitters = multiEmitterEffect.program
+      .emitters as unknown as VfxGpuEffectAsset['program']['emitters'][number][];
+    emitters.splice(0, 1, primary, {
+      ...primary,
+      id: 'healthy',
+      module: 'healthy.vfx.wgsl',
+    });
+    const handle = world.allocSharedRef('ParticleEffectAsset', multiEmitterEffect);
+    const player = world
+      .spawn({
+        component: ParticleEffectPlayer,
+        data: { effect: handle, playing: true, seed: 1, timeScale: 1 },
+      })
+      .unwrap();
+    await createWorldContext(world, [vfxGpuRuntimePlugin()]);
+    const runtime = world.getResource<VfxGpuRuntime>(VFX_GPU_RUNTIME_RESOURCE_KEY);
+
+    world.update(1 / 30).unwrap();
+    const firstIntents = [...runtime.snapshot()];
+    const firstTerminal = firstIntents.at(-1);
+    if (firstTerminal === undefined) return;
+    runtime.commit(
+      firstTerminal.sequence,
+      firstIntents.map((intent) => intent.sequence),
+    );
+    expect(runtime.lastCommittedEmitter(player, 'sparks')?.seed).toBe(1);
+    expect(runtime.lastCommittedEmitter(player, 'healthy')?.seed).toBe(1);
+
+    runtime.setEmitterSessionEnabled(player, 'sparks', false);
+    world.set(player, ParticleEffectPlayer, { seed: 2 }).unwrap();
+    world.update(0).unwrap();
+    world.update(1 / 30).unwrap();
+    const healthyDuringPause = runtime
+      .snapshot()
+      .filter((intent) => intent.emitter.id === 'healthy');
+    expect(healthyDuringPause.some((intent) => intent.reset && intent.seed === 2)).toBe(true);
+    expect(runtime.snapshot().some((intent) => intent.emitter.id === 'sparks')).toBe(false);
+    const healthyTerminal = runtime.snapshot().at(-1);
+    if (healthyTerminal === undefined) return;
+    runtime.commit(
+      healthyTerminal.sequence,
+      runtime.snapshot().map((intent) => intent.sequence),
+    );
+
+    runtime.setEmitterSessionEnabled(player, 'sparks', true);
+    world.update(1 / 30).unwrap();
+    const resumed = runtime
+      .snapshot()
+      .find((intent) => intent.emitter.id === 'sparks' && intent.reset);
+    expect(resumed).toMatchObject({ seed: 2, reset: true, phaseTick: 0, spawnCount: 8 });
+  });
+
   it('keeps stage recovery scoped to the cooked generation', () => {
     const source = readFileSync(new URL('../gpu-runtime.ts', import.meta.url), 'utf8');
     expect(source).toContain('instanceGeneration');
@@ -118,9 +304,11 @@ describe('GPU VFX fixed-tick intents', () => {
       })
       .unwrap();
     const contract = createVfxEffectContract({
-      version: 1,
+      version: 3,
       parameters: { name: 'VfxParameters', fields: [], size: 0, alignment: 1 },
       custom: { name: 'VfxCustom', fields: [], size: 0, alignment: 1 },
+      core: VFX_PARTICLE_CORE_LAYOUT,
+      customLayout: { name: 'VfxCustom', fields: [], size: 0, alignment: 1, stride: 0, lanes: 0 },
       fingerprint: 'sha256:atomic-patch',
     });
     const instance = new ParticleEffectInstance(contract);
@@ -192,7 +380,7 @@ describe('GPU VFX fixed-tick intents', () => {
     const runtime = world.getResource<VfxGpuRuntime>(VFX_GPU_RUNTIME_RESOURCE_KEY);
     expect(runtime.snapshot()).toHaveLength(1);
     expect(runtime.snapshot()[0]).toMatchObject({ reset: true, spawnCount: 8, firstParticleId: 0 });
-    runtime.commit(runtime.snapshot().at(0)?.sequence ?? -1);
+    commitSnapshot(runtime, 1);
 
     expect(world.update(1 / 60).ok).toBe(true);
     expect(runtime.snapshot()).toHaveLength(1);
@@ -203,6 +391,51 @@ describe('GPU VFX fixed-tick intents', () => {
     });
   });
 
+  it('replays an emitter time-zero schedule when a session mask enables it later', async () => {
+    const delayedEffect = structuredClone(effect) as VfxGpuEffectAsset;
+    const firstEmitter = delayedEffect.program.emitters[0];
+    expect(firstEmitter).toBeDefined();
+    if (firstEmitter === undefined) return;
+    const delayedEmitter = {
+      ...firstEmitter,
+      id: 'delayed',
+      capacity: 16,
+      schedule: { rate: 0, bursts: [{ time: 0, count: 3 }] },
+    };
+    (delayedEffect.program.emitters as VfxGpuEffectAsset['program']['emitters'][number][]).push(
+      delayedEmitter,
+    );
+    (delayedEffect.emitters as { id: string; capacity: number }[]).push({
+      id: 'delayed',
+      capacity: delayedEmitter.capacity,
+    });
+
+    const world = new World();
+    const handle = world.allocSharedRef('ParticleEffectAsset', delayedEffect);
+    const player = world
+      .spawn({
+        component: ParticleEffectPlayer,
+        data: { effect: handle, playing: true, seed: 9, timeScale: 1 },
+      })
+      .unwrap();
+    await createWorldContext(world, [vfxGpuRuntimePlugin()]);
+    const runtime = world.getResource<VfxGpuRuntime>(VFX_GPU_RUNTIME_RESOURCE_KEY);
+    runtime.setEmitterSessionEnabled(player, 'delayed', false);
+
+    world.update(1 / 60).unwrap();
+    expect(runtime.snapshot().some((intent) => intent.emitter.id === 'delayed')).toBe(false);
+    commitSnapshot(runtime);
+
+    runtime.setEmitterSessionEnabled(player, 'delayed', true);
+    world.update(1 / 60).unwrap();
+    expect(runtime.snapshot().find((intent) => intent.emitter.id === 'delayed')).toMatchObject({
+      reset: true,
+      phaseTick: 0,
+      spawnCount: 3,
+      firstParticleId: 0,
+    });
+  });
+
   it('replays an authored stopped player without mutating author intent', async () => {
     const world = new World();
     const handle = world.allocSharedRef('ParticleEffectAsset', effect);
@@ -229,7 +462,7 @@ describe('GPU VFX fixed-tick intents', () => {
     });
     expect(world.get(player, ParticleEffectPlayer).unwrap().playing).toBe(false);
 
-    runtime.commit(runtime.snapshot().at(0)?.sequence ?? -1);
+    commitSnapshot(runtime, 1);
     world.update(1 / 60).unwrap();
 
     expect(runtime.snapshot()).toHaveLength(0);
@@ -251,12 +484,12 @@ describe('GPU VFX fixed-tick intents', () => {
     const runtime = world.getResource<VfxGpuRuntime>(VFX_GPU_RUNTIME_RESOURCE_KEY);
     expect(runtime.snapshot()).toHaveLength(1);
     expect(runtime.diagnostics()).toHaveLength(0);
-    runtime.commit(runtime.snapshot().at(0)?.sequence ?? -1);
+    commitSnapshot(runtime, 1);
     world.update(1 / 60).unwrap();
     world.update(1 / 60).unwrap();
     expect(runtime.snapshot()).toHaveLength(1);
     expect(runtime.diagnostics().at(-1)?.code).toBe('vfx-intent-queue-overflow');
-    runtime.commit(runtime.snapshot().at(-1)?.sequence ?? -1);
+    commitSnapshot(runtime);
     expect(runtime.diagnostics()).toEqual([]);
   });
 
@@ -273,7 +506,7 @@ describe('GPU VFX fixed-tick intents', () => {
     const runtime = world.getResource<VfxGpuRuntime>(VFX_GPU_RUNTIME_RESOURCE_KEY);
 
     world.update(1 / 60).unwrap();
-    runtime.commit(runtime.snapshot()[0]?.sequence ?? -1);
+    commitSnapshot(runtime, 1);
     world.update(1 / 60).unwrap();
     world.update(1 / 60).unwrap();
     expect(runtime.diagnostics()).toHaveLength(1);
@@ -330,7 +563,7 @@ describe('GPU VFX fixed-tick intents', () => {
     const runtime = world.getResource<VfxGpuRuntime>(VFX_GPU_RUNTIME_RESOURCE_KEY);
 
     world.update(1 / 60).unwrap();
-    runtime.commit(runtime.snapshot()[0]?.sequence ?? -1);
+    commitSnapshot(runtime, 1);
     world.update(1 / 60).unwrap();
     world.update(1 / 60).unwrap();
     expect(runtime.diagnostics()).toHaveLength(1);
@@ -496,7 +729,7 @@ describe('GPU VFX fixed-tick intents', () => {
     await createWorldContext(world, [vfxGpuRuntimePlugin()]);
     world.update(1 / 60).unwrap();
     const runtime = world.getResource<VfxGpuRuntime>(VFX_GPU_RUNTIME_RESOURCE_KEY);
-    runtime.commit(runtime.snapshot().at(0)?.sequence ?? -1);
+    commitSnapshot(runtime, 1);
 
     runtime.setEmitterCameraVisibility(player, 'sparks', false);
     world.update(1 / 60).unwrap();
@@ -523,7 +756,7 @@ describe('GPU VFX fixed-tick intents', () => {
     await createWorldContext(world, [vfxGpuRuntimePlugin()]);
     world.update(1 / 60).unwrap();
     const runtime = world.getResource<VfxGpuRuntime>(VFX_GPU_RUNTIME_RESOURCE_KEY);
-    runtime.commit(runtime.snapshot().at(0)?.sequence ?? -1);
+    commitSnapshot(runtime, 1);
 
     runtime.setEmitterSessionEnabled(player, 'sparks', false);
     world.update(1 / 60).unwrap();

package/src/__tests__/instance-public-api.unit.test.ts

@@ -1,9 +1,10 @@
 import { describe, expect, it } from 'vitest';
 import { createVfxEffectContract } from '../effect-contract.js';
 import { ParticleEffectInstance } from '../instance.js';
+import { VFX_PARTICLE_CORE_LAYOUT } from '../particle-layout.js';
 
 const reflection = {
-  version: 1,
+  version: 3,
   parameters: {
     name: 'VfxParameters',
     fields: [{ name: 'intensity', type: 'f32', offset: 0, size: 4, alignment: 4 }],
@@ -11,6 +12,8 @@ const reflection = {
     alignment: 16,
   },
   custom: { name: 'VfxCustom', fields: [], size: 0, alignment: 1 },
+  core: VFX_PARTICLE_CORE_LAYOUT,
+  customLayout: { name: 'VfxCustom', fields: [], size: 0, alignment: 1, stride: 0, lanes: 0 },
   fingerprint: 'sha256:public-runtime',
 } as const;
 

package/src/__tests__/instance.unit.test.ts

@@ -1,6 +1,7 @@
 import { describe, expect, it } from 'vitest';
 import { createVfxEffectContract } from '../effect-contract.js';
 import { ParticleEffectInstance, type VfxInstanceParent } from '../instance.js';
+import { VFX_PARTICLE_CORE_LAYOUT } from '../particle-layout.js';
 
 type Values = {
   readonly direction: readonly [number, number, number];
@@ -8,7 +9,7 @@ type Values = {
 };
 
 const reflection = {
-  version: 1,
+  version: 3,
   parameters: {
     name: 'VfxParameters',
     fields: [
@@ -19,6 +20,8 @@ const reflection = {
     alignment: 16,
   },
   custom: { name: 'VfxCustom', fields: [], size: 0, alignment: 1 },
+  core: VFX_PARTICLE_CORE_LAYOUT,
+  customLayout: { name: 'VfxCustom', fields: [], size: 0, alignment: 1, stride: 0, lanes: 0 },
   fingerprint: 'sha256:instance-test',
 } as const;
 

package/src/__tests__/loader-v1-rejection.unit.test.ts

@@ -30,16 +30,16 @@ function input(
   };
 }
 
-const validPayload = {
+const invalidPayload = {
   kind: 'particle-effect',
   schemaVersion: 1,
   emitters: [{ id: 'spark', capacity: 32 }],
 };
 
-describe('vfxGpuEffectPackLoader v2 boundary', () => {
-  it('keeps legacy artifact keys outside the v2 asset-local program contract', async () => {
+describe('vfxGpuEffectPackLoader version boundary', () => {
+  it('rejects older payloads before reading an artifact', async () => {
     const result = await vfxGpuEffectPackLoader.load(
-      input(validPayload, {
+      input(invalidPayload, {
         'effect/program.json': {
           descriptor: { path: 'program.json', mediaType: 'application/json' },
           bytes: new TextEncoder().encode('{}'),
@@ -51,13 +51,13 @@ describe('vfxGpuEffectPackLoader v2 boundary', () => {
     expect(result.ok).toBe(false);
     if (!result.ok) {
       expect(result.error).toMatchObject({
-        code: 'vfx-asset-v2-invalid',
-        detail: { path: 'payload' },
+        code: 'vfx-asset-version-unsupported',
+        detail: { path: 'schemaVersion' },
       });
     }
   });
 
-  it('rejects a summary-only v2 payload before reading a program artifact', async () => {
+  it('rejects a summary-only older payload before reading a program artifact', async () => {
     const result = await vfxGpuEffectPackLoader.load(
       input({
         kind: 'particle-effect',
@@ -69,12 +69,12 @@ describe('vfxGpuEffectPackLoader v2 boundary', () => {
     );
 
     expect(result.ok).toBe(false);
-    if (!result.ok) expect(result.error.detail.path).toBe('payload');
+    if (!result.ok) expect(result.error.detail.path).toBe('schemaVersion');
   });
 
   it('rejects a v1 package-global artifact shape', async () => {
     const result = await vfxGpuEffectPackLoader.load(
-      input(validPayload, {
+      input(invalidPayload, {
         'effect/program.json': {
           descriptor: { path: 'program.json', mediaType: 'application/json' },
           bytes: new TextEncoder().encode('{}'),
@@ -85,21 +85,21 @@ describe('vfxGpuEffectPackLoader v2 boundary', () => {
 
     expect(result.ok).toBe(false);
     if (!result.ok) {
-      expect(result.error.code).toBe('vfx-asset-v2-invalid');
-      expect(result.error.detail.path).toBe('payload');
+      expect(result.error.code).toBe('vfx-asset-version-unsupported');
+      expect(result.error.detail.path).toBe('schemaVersion');
     }
   });
 
   it('rejects raw source fallback when the cooked program is absent', async () => {
     const result = await vfxGpuEffectPackLoader.load(
-      input({ ...validPayload, source: { emitters: [] }, sourcePath: 'effect.vfx.json' }),
+      input({ ...invalidPayload, source: { emitters: [] }, sourcePath: 'effect.vfx.json' }),
       context(),
     );
 
     expect(result.ok).toBe(false);
     if (!result.ok) {
-      expect(result.error.code).toBe('vfx-asset-v2-invalid');
-      expect(result.error.detail.path).toBe('payload');
+      expect(result.error.code).toBe('vfx-asset-version-unsupported');
+      expect(result.error.detail.path).toBe('schemaVersion');
     }
   });
 });

package/src/__tests__/player-reflection.unit.test.ts

@@ -6,10 +6,10 @@ import { ParticleEffectPlayer, type ParticleEffectPlayerData } from '../index.js
 
 const asset: ParticleEffectAsset = {
   kind: 'particle-effect',
-  schemaVersion: 2,
+  schemaVersion: 3,
   programFingerprint: 'sha256:test',
   emitters: [],
-  program: { format: 'forgeax-vfx-program-2', fingerprint: 'sha256:test', emitters: [] },
+  program: { format: 'forgeax-vfx-program-3', fingerprint: 'sha256:test', emitters: [] },
 };
 
 describe('ParticleEffectPlayer ECS contract', () => {

package/src/__tests__/player-type.test-d.ts

@@ -7,6 +7,7 @@ import {
   type ParticleEffectPlayer,
   type VfxEffectReflection,
 } from '../index.js';
+import { VFX_PARTICLE_CORE_LAYOUT } from '../particle-layout.js';
 
 type Values = {
   readonly direction: readonly [number, number, number];
@@ -14,9 +15,11 @@ type Values = {
 };
 
 const reflection: VfxEffectReflection = {
-  version: 1,
+  version: 3,
   parameters: { name: 'VfxParameters', fields: [], size: 0, alignment: 1 },
   custom: { name: 'VfxCustom', fields: [], size: 0, alignment: 1 },
+  core: VFX_PARTICLE_CORE_LAYOUT,
+  customLayout: { name: 'VfxCustom', fields: [], size: 0, alignment: 1, stride: 0, lanes: 0 },
   fingerprint: 'sha256:player-type',
 };
 

package/src/__tests__/renderer-source.unit.test.ts

@@ -1,8 +1,8 @@
 import { describe, expect, it } from 'vitest';
-import { parseParticleEffectSourceV2 } from '../code-source.js';
+import { parseParticleEffectSourceV3 } from '../code-source-v3.js';
 
 const rendererSource = (renderer: unknown) => ({
-  schemaVersion: 2,
+  schemaVersion: 3,
   emitters: [
     {
       id: 'showcase',
@@ -19,19 +19,19 @@ const rendererSource = (renderer: unknown) => ({
 
 describe('Batch B renderer source contract', () => {
   it.each([
-    ['billboard', { kind: 'billboard', material: 'vfx', sorting: 'emitter' }],
+    ['billboard', { kind: 'billboard', material: 'vfx', sorting: 'view-depth' }],
     ['ribbon', { kind: 'ribbon', material: 'vfx', stripKey: 'alive-index', capacity: 32 }],
     ['trail', { kind: 'trail', material: 'vfx', historyLength: 8, capacity: 32 }],
     ['beam', { kind: 'beam', material: 'vfx', endpointField: 'velocity', capacity: 16 }],
   ])('parses the independent %s topology', (_kind, renderer) => {
-    const parsed = parseParticleEffectSourceV2(rendererSource(renderer));
+    const parsed = parseParticleEffectSourceV3(rendererSource(renderer));
 
     expect(parsed.ok).toBe(true);
     if (parsed.ok) expect(parsed.value.emitters[0]?.renderers[0]).toMatchObject(renderer);
   });
 
   it('rejects zero topology capacity instead of silently disabling output', () => {
-    const parsed = parseParticleEffectSourceV2(
+    const parsed = parseParticleEffectSourceV3(
       rendererSource({ kind: 'trail', material: 'vfx', historyLength: 8, capacity: 0 }),
     );
 
@@ -42,7 +42,7 @@ describe('Batch B renderer source contract', () => {
   });
 
   it('keeps an explicitly disabled renderer distinguishable from an empty list', () => {
-    const parsed = parseParticleEffectSourceV2(
+    const parsed = parseParticleEffectSourceV3(
       rendererSource({
         kind: 'ribbon',
         material: 'vfx',

package/src/__tests__/replay-canonical.unit.test.ts

@@ -1,6 +1,7 @@
 import { describe, expect, it } from 'vitest';
 import { createVfxEffectContract } from '../effect-contract.js';
 import { ParticleEffectInstance } from '../instance.js';
+import { VFX_PARTICLE_CORE_LAYOUT } from '../particle-layout.js';
 
 type Values = {
   readonly zeta: number;
@@ -8,7 +9,7 @@ type Values = {
 };
 
 const reflection = {
-  version: 1,
+  version: 3,
   parameters: {
     name: 'VfxParameters',
     fields: [
@@ -19,6 +20,8 @@ const reflection = {
     alignment: 16,
   },
   custom: { name: 'VfxCustom', fields: [], size: 0, alignment: 1 },
+  core: VFX_PARTICLE_CORE_LAYOUT,
+  customLayout: { name: 'VfxCustom', fields: [], size: 0, alignment: 1, stride: 0, lanes: 0 },
   fingerprint: 'sha256:canonical-test',
 } as const;
 

package/src/__tests__/vfx-data-interface-vocabulary-owner.test-d.ts

@@ -8,14 +8,12 @@ import type {
 
 describe('VFX Data Interface vocabulary owner', () => {
   it('preserves the exact kinds, binding types, and tokens', () => {
-    expectTypeOf<VfxDataInterfaceKind>().toEqualTypeOf<
-      'camera' | 'scene-depth' | 'noise' | 'channel'
-    >();
+    expectTypeOf<VfxDataInterfaceKind>().toEqualTypeOf<'camera' | 'scene-depth' | 'noise'>();
     expectTypeOf<VfxDataInterfaceBindingType>().toEqualTypeOf<
-      'uniform' | 'sampled-depth' | 'sampled-float' | 'storage-read'
+      'uniform' | 'sampled-depth' | 'sampled-float'
     >();
     expectTypeOf<VfxDataInterfaceToken>().toEqualTypeOf<
-      'vfx:camera' | 'vfx:scene-depth' | 'vfx:noise' | 'vfx:channel'
+      'vfx:camera' | 'vfx:scene-depth' | 'vfx:noise'
     >();
   });
 
@@ -27,8 +25,5 @@ describe('VFX Data Interface vocabulary owner', () => {
     expectTypeOf<
       VfxDataInterfaceProvider<'noise'>['bindingType']
     >().toEqualTypeOf<'sampled-float'>();
-    expectTypeOf<
-      VfxDataInterfaceProvider<'channel'>['bindingType']
-    >().toEqualTypeOf<'storage-read'>();
   });
 });

package/src/assets/particle-effect-decoder.ts

@@ -17,7 +17,8 @@ export const particleEffectContribution: AssetDecoderContribution<
       const payload = envelope.payload;
       if (
         payload.kind === 'particle-effect' &&
-        payload.schemaVersion === 2 &&
+        payload.schemaVersion === 3 &&
+        payload.program.format === 'forgeax-vfx-program-3' &&
         payload.emitters.length === payload.program.emitters.length &&
         payload.programFingerprint === payload.program.fingerprint
       ) {
@@ -25,8 +26,8 @@ export const particleEffectContribution: AssetDecoderContribution<
       }
       return err({
         code: 'asset-package-invalid',
-        expected: 'a schema v2 particle payload matching its cooked program',
-        hint: 'recook the particle effect atomically with its GPU program',
+        expected: 'a schemaVersion 3 particle payload matching its cooked Program v3',
+        hint: 'cold-cook the legacy payload with the Program v3 compiler and publish atomically',
         detail: { guid: envelope.guid, reason: 'particle owner validation failed' },
       });
     },