@forgeax/engine-vfx 0.1.27 → 0.1.29

package/src/code-source.ts

@@ -16,7 +16,8 @@ export type ParticleBoundsSource =
     };
 
 export type ParticleRendererOverflowPolicy = 'drop-newest' | 'drop-oldest';
-export type ParticleRendererSorting = 'none' | 'emitter' | 'back-to-front';
+/** Internal structural projection used while validating the v3 source. */
+export type ParticleRendererSortingStructure = 'none' | 'emitter' | 'back-to-front';
 
 export interface ParticleTextureSheetSource {
   readonly columns: number;
@@ -29,7 +30,7 @@ export interface ParticleSoftParticleSource {
   readonly fadeDistance: number;
 }
 
-export type ParticleRendererSource =
+export type ParticleRendererSourceStructure =
   | {
       readonly kind: 'billboard';
       readonly material: string;
@@ -40,7 +41,7 @@ export type ParticleRendererSource =
       readonly textureSheet?: ParticleTextureSheetSource;
       readonly pivot?: readonly [number, number];
       readonly softParticle?: ParticleSoftParticleSource;
-      readonly sorting?: ParticleRendererSorting;
+      readonly sorting?: ParticleRendererSortingStructure;
     }
   | {
       readonly kind: 'mesh';
@@ -124,7 +125,7 @@ export interface ParticleEventSource {
   readonly recursionDepth: number;
 }
 
-export interface ParticleEmitterSourceV2 {
+export interface ParticleEmitterSourceStructure {
   readonly id: string;
   readonly capacity: number;
   readonly backend: { readonly required: 'gpu' };
@@ -136,18 +137,18 @@ export interface ParticleEmitterSourceV2 {
     readonly loopDuration?: number;
   };
   readonly program: { readonly module: string };
-  readonly renderers: readonly ParticleRendererSource[];
+  readonly renderers: readonly ParticleRendererSourceStructure[];
   readonly channels?: readonly ParticleChannelSource[];
   readonly events?: readonly ParticleEventSource[];
   readonly simulationWhenCulled?: 'continue' | 'pause' | 'restart-on-visible';
 }
 
-export interface ParticleEffectRootSourceV2 {
-  readonly schemaVersion: 2;
-  readonly emitters: readonly ParticleEmitterSourceV2[];
+export interface ParticleEffectRootSourceStructure {
+  readonly schemaVersion: 3;
+  readonly emitters: readonly ParticleEmitterSourceStructure[];
 }
 
-export type ParticleEffectSourceV2 = ParticleEffectRootSourceV2;
+export type ParticleEffectSourceStructure = ParticleEffectRootSourceStructure;
 
 export interface ParticleCodeSourceInvalidDetail {
   readonly path: string;
@@ -364,9 +365,9 @@ function parseEmitter(
   value: unknown,
   index: number,
   ids: Set<string>,
-): Result<ParticleEmitterSourceV2, ParticleCodeSourceError> {
+): Result<ParticleEmitterSourceStructure, ParticleCodeSourceError> {
   const path = `emitters[${index}]`;
-  if (!record(value)) return invalid(path, 'a v2 emitter object');
+  if (!record(value)) return invalid(path, 'a Program v3 emitter object');
   const extra = allowed(value, [
     'id',
     'capacity',
@@ -380,7 +381,7 @@ function parseEmitter(
     'events',
     'simulationWhenCulled',
   ]);
-  if (extra !== undefined) return invalid(`${path}.${extra}`, 'a v2 emitter field');
+  if (extra !== undefined) return invalid(`${path}.${extra}`, 'a Program v3 emitter field');
   if (!text(value.id) || ids.has(value.id)) return invalid(`${path}.id`, 'a unique non-empty id');
   const id = value.id;
   ids.add(id);
@@ -763,28 +764,29 @@ function parseEmitter(
   ) {
     return invalid(`${path}.simulationWhenCulled`, 'continue, pause, or restart-on-visible', id);
   }
-  return ok(value as unknown as ParticleEmitterSourceV2);
+  return ok(value as unknown as ParticleEmitterSourceStructure);
 }
 
-export function parseParticleEffectSourceV2(
+/** Validate the fields shared by the canonical Program v3 source parser. */
+export function parseParticleEffectSourceStructure(
   value: unknown,
-): Result<ParticleEffectSourceV2, ParticleCodeSourceError> {
+): Result<ParticleEffectSourceStructure, ParticleCodeSourceError> {
   if (!record(value)) return invalid('$', 'a particle effect source object');
-  if (value.schemaVersion !== 2) {
+  if (value.schemaVersion !== 3) {
     return err({
       code: 'vfx-source-version-unsupported',
-      expected: 'ParticleEffectSource schemaVersion 2',
-      hint: 'migrate code behavior to WGSL and recook; v1 is not interpreted at runtime',
+      expected: 'ParticleEffectSource schemaVersion 3',
+      hint: 'cold-cook the source with the Program v3 compiler; older versions are not executable',
       detail: { path: 'schemaVersion' },
     });
   }
   const extra = allowed(value, ['schemaVersion', 'emitters']);
   if (extra !== undefined) return invalid(extra, 'a root field: emitters');
   if (!Array.isArray(value.emitters) || value.emitters.length === 0) {
-    return invalid('emitters', 'at least one v2 emitter');
+    return invalid('emitters', 'at least one Program v3 emitter');
   }
   const ids = new Set<string>();
-  const emitters: ParticleEmitterSourceV2[] = [];
+  const emitters: ParticleEmitterSourceStructure[] = [];
   for (const [index, emitter] of value.emitters.entries()) {
     const parsed = parseEmitter(emitter, index, ids);
     if (!parsed.ok) return parsed;
@@ -814,14 +816,8 @@ export function parseParticleEffectSourceV2(
   }
   return ok(
     Object.freeze({
-      schemaVersion: 2,
+      schemaVersion: 3,
       emitters: Object.freeze(emitters),
     }),
   );
 }
-
-export function defineParticleEffectSourceV2<T extends ParticleEffectSourceV2>(source: T): T {
-  const parsed = parseParticleEffectSourceV2(source);
-  if (!parsed.ok) throw new TypeError(`${parsed.error.code}: ${parsed.error.expected}`);
-  return source;
-}

package/src/data-interface.ts

@@ -6,11 +6,12 @@ export type VfxDataInterfaceToken = `vfx:${VfxDataInterfaceKind}`;
 
 export type VfxDataInterfaceBindingType = VfxDataInterfaceBindingTypeByKind[VfxDataInterfaceKind];
 
+export type VfxDataInterfaceResourceKind = 'buffer' | 'texture-view' | 'sampler';
+
 type VfxDataInterfaceBindingTypeByKind = {
   readonly camera: 'uniform';
   readonly 'scene-depth': 'sampled-depth';
   readonly noise: 'sampled-float';
-  readonly channel: 'storage-read';
 };
 
 export type VfxDataInterfaceLifetime = 'generation';
@@ -21,6 +22,8 @@ export interface VfxDataInterfaceRequirement {
   readonly binding: number;
   readonly bindingType: VfxDataInterfaceBindingType;
   readonly lifetime: VfxDataInterfaceLifetime;
+  /** Scene-depth composition is intentionally proven only for single-sample targets. */
+  readonly sampleCount?: 1;
 }
 
 export interface VfxDataInterfaceResource {
@@ -28,6 +31,18 @@ export interface VfxDataInterfaceResource {
   readonly kind: VfxDataInterfaceKind;
   readonly bindingType: VfxDataInterfaceBindingType;
   readonly generation: number;
+  readonly sampleCount?: number;
+  /**
+   * Provider-owned opaque resource. Render owners refine this to their typed
+   * prepared-resource reference; VFX never inspects a backend handle.
+   */
+  readonly resource?: {
+    readonly kind: 'buffer' | 'texture-view' | 'sampler';
+    readonly value: unknown;
+    /** Required when a provider supplies an external buffer to a compute bind group. */
+    readonly size?: number;
+    readonly usage?: 'uniform' | 'storage';
+  };
 }
 
 export interface VfxDataInterfaceErrorDetail {
@@ -37,6 +52,8 @@ export interface VfxDataInterfaceErrorDetail {
   readonly actualGeneration?: number;
   readonly expectedBindingType?: VfxDataInterfaceBindingType;
   readonly actualBindingType?: VfxDataInterfaceBindingType;
+  readonly expectedResourceKind?: VfxDataInterfaceResourceKind;
+  readonly actualResourceKind?: VfxDataInterfaceResourceKind;
 }
 
 export interface VfxDataInterfaceError {
@@ -64,6 +81,16 @@ export interface VfxDataInterfaceResolution {
   readonly resources: readonly VfxDataInterfaceResource[];
 }
 
+function expectedResourceKind(kind: VfxDataInterfaceKind): VfxDataInterfaceResourceKind {
+  switch (kind) {
+    case 'camera':
+      return 'buffer';
+    case 'scene-depth':
+    case 'noise':
+      return 'texture-view';
+  }
+}
+
 function failure(
   code: VfxDataInterfaceError['code'],
   requirement: VfxDataInterfaceRequirement,
@@ -160,6 +187,44 @@ export function resolveVfxDataInterfaces(
         ),
       );
     }
+    const expectedKind = expectedResourceKind(requirement.kind);
+    if (resource.resource === undefined) {
+      return err(
+        failure(
+          'vfx-data-interface-missing',
+          requirement,
+          `${requirement.kind} backed by a resident ${expectedKind} resource`,
+          `refresh provider ${provider.id} with a generation-owned resource before dispatch`,
+          { providerId: provider.id, expectedResourceKind: expectedKind },
+        ),
+      );
+    }
+    if (resource.resource.kind !== expectedKind) {
+      return err(
+        failure(
+          'vfx-data-interface-wrong-type',
+          requirement,
+          `${requirement.kind} backed by a ${expectedKind} resource`,
+          `repair provider ${provider.id} so its opaque resource matches the reflected binding kind`,
+          {
+            providerId: provider.id,
+            expectedResourceKind: expectedKind,
+            actualResourceKind: resource.resource.kind,
+          },
+        ),
+      );
+    }
+    if (requirement.sampleCount !== undefined && resource.sampleCount !== requirement.sampleCount) {
+      return err(
+        failure(
+          'vfx-data-interface-wrong-type',
+          requirement,
+          `a scene-depth resource with sampleCount=${requirement.sampleCount}`,
+          `provide a single-sample scene depth target for ${provider.id}; MSAA resolve is not implicit`,
+          { providerId: provider.id },
+        ),
+      );
+    }
     if (resource.generation !== generation) {
       return err(
         failure(

package/src/effect-contract.ts

@@ -1,5 +1,6 @@
 import { err, ok, type Result } from '@forgeax/engine-types';
 import type { VfxDataInterfaceRequirement } from './data-interface.js';
+import type { VfxCustomLayout, VfxParticleCoreLayout } from './particle-layout.js';
 
 export type VfxValue = number | readonly number[];
 export type VfxValueMap = Readonly<Record<string, VfxValue>>;
@@ -21,9 +22,12 @@ export interface VfxReflectedStruct {
 }
 
 export interface VfxEffectReflection {
-  readonly version: 1;
+  /** The single executable particle data ABI. */
+  readonly version: 3;
   readonly parameters: VfxReflectedStruct;
   readonly custom: VfxReflectedStruct;
+  readonly core: VfxParticleCoreLayout;
+  readonly customLayout: VfxCustomLayout;
   readonly dataInterfaces?: readonly VfxDataInterfaceRequirement[];
   readonly fingerprint: string;
 }
@@ -48,10 +52,16 @@ export interface VfxEffectContract<Values extends VfxValueMap = VfxValueMap> {
   readonly reflection: VfxEffectReflection;
   readonly fingerprint: string;
   readonly packedSize: number;
+  /** Bytes in the effect-instance Parameters uniform. */
+  readonly parameterSize: number;
+  /** Bytes in one persistent per-particle Custom record. */
+  readonly customStride: number;
   readonly defaults: Values;
   createValues(initial?: Partial<Values>): Result<Values, VfxEffectContractError>;
   validateValues(values: VfxValueMap): Result<Values, VfxEffectContractError>;
   pack(values: Values): Result<Uint8Array, VfxEffectContractError>;
+  packParameters(values: Values): Result<Uint8Array, VfxEffectContractError>;
+  packCustom(values: VfxValueMap): Result<Uint8Array, VfxEffectContractError>;
 }
 
 const VECTOR_LENGTH = {
@@ -65,8 +75,13 @@ const VECTOR_LENGTH = {
 
 export type VfxValueType = keyof typeof VECTOR_LENGTH;
 
-function fieldList(reflection: VfxEffectReflection): readonly VfxReflectedField[] {
-  return [...reflection.parameters.fields, ...reflection.custom.fields];
+function fieldList(
+  reflection: VfxEffectReflection,
+  includeCustom = false,
+): readonly VfxReflectedField[] {
+  return includeCustom
+    ? [...reflection.parameters.fields, ...reflection.custom.fields]
+    : reflection.parameters.fields;
 }
 
 function zeroValue(type: VfxValueType): VfxValue {
@@ -101,14 +116,29 @@ function fail(
 
 function validateReflection(reflection: VfxEffectReflection): Result<true, VfxEffectContractError> {
   if (
-    reflection.version !== 1 ||
+    reflection.version !== 3 ||
     typeof reflection.fingerprint !== 'string' ||
     !reflection.fingerprint.startsWith('sha256:')
   ) {
     return fail(
       'vfx-reflection-invalid',
       'reflection',
-      'a version 1 reflection with a sha256 fingerprint',
+      'a version 3 reflection with a sha256 fingerprint',
+      'recook the effect with the current VFX compiler',
+    );
+  }
+  if (
+    reflection.core.name !== 'VfxParticle' ||
+    reflection.core.stride !== 112 ||
+    reflection.core.fields.length === 0 ||
+    reflection.customLayout.name !== 'VfxCustom' ||
+    reflection.customLayout.stride < 0 ||
+    reflection.customLayout.lanes < 0
+  ) {
+    return fail(
+      'vfx-reflection-invalid',
+      'reflection.core',
+      'Program v3 Core and Custom layouts derived from the particle schema',
       'recook the effect with the current VFX compiler',
     );
   }
@@ -140,14 +170,21 @@ function validateMap<Values extends VfxValueMap>(
   reflection: VfxEffectReflection,
   values: VfxValueMap,
 ): Result<Values, VfxEffectContractError> {
-  const fields = new Map(fieldList(reflection).map((field) => [field.name, field]));
+  return validateMapAgainstFields<Values>(fieldList(reflection), values);
+}
+
+function validateMapAgainstFields<Values extends VfxValueMap>(
+  reflectedFields: readonly VfxReflectedField[],
+  values: VfxValueMap,
+): Result<Values, VfxEffectContractError> {
+  const fields = new Map(reflectedFields.map((field) => [field.name, field]));
   for (const name of Object.keys(values)) {
     const field = fields.get(name);
     if (field === undefined) {
       return fail(
         'vfx-value-unknown-field',
         name,
-        'a field declared by VfxParameters or VfxCustom',
+        'a field declared by the selected VFX data scope',
         `remove ${name} or declare it in the authored WGSL struct`,
         values[name],
       );
@@ -181,13 +218,33 @@ export function createVfxEffectContract<Values extends VfxValueMap = VfxValueMap
   const checked = validateReflection(reflection);
   if (!checked.ok) throw new TypeError(checked.error.hint);
   const defaults = defaultsFor<Values>(reflection);
-  const fields = fieldList(reflection);
   const customBase = reflection.parameters.size;
-  const packedSize = customBase + reflection.custom.size;
+  const parameterSize = reflection.parameters.size;
+  const customStride = reflection.customLayout.stride;
+  const packedSize = customBase;
+  const packFields = (
+    values: VfxValueMap,
+    selected: readonly VfxReflectedField[],
+    size: number,
+    baseOffset: number,
+  ): Result<Uint8Array, VfxEffectContractError> => {
+    const checkedValues = validateMapAgainstFields<Values>(selected, values);
+    if (!checkedValues.ok) return checkedValues;
+    const bytes = new Uint8Array(size);
+    const view = new DataView(bytes.buffer);
+    for (const field of selected) {
+      const value = checkedValues.value[field.name];
+      if (value === undefined) continue;
+      writeValue(view, baseOffset + field.offset, field.type, value);
+    }
+    return ok(bytes);
+  };
   return {
     reflection,
     fingerprint: reflection.fingerprint,
     packedSize,
+    parameterSize: reflection.parameters.size,
+    customStride,
     defaults,
     createValues(initial = {} as Partial<Values>) {
       const merged = { ...defaults, ...initial };
@@ -197,17 +254,13 @@ export function createVfxEffectContract<Values extends VfxValueMap = VfxValueMap
       return validateMap<Values>(reflection, values);
     },
     pack(values) {
-      const checkedValues = validateMap<Values>(reflection, values);
-      if (!checkedValues.ok) return checkedValues;
-      const bytes = new Uint8Array(packedSize);
-      const view = new DataView(bytes.buffer);
-      for (const field of fields) {
-        const value = checkedValues.value[field.name];
-        if (value === undefined) continue;
-        const base = reflection.parameters.fields.includes(field) ? 0 : customBase;
-        writeValue(view, base + field.offset, field.type, value);
-      }
-      return ok(bytes);
+      return packFields(values, reflection.parameters.fields, parameterSize, 0);
+    },
+    packParameters(values) {
+      return packFields(values, reflection.parameters.fields, parameterSize, 0);
+    },
+    packCustom(values) {
+      return packFields(values, reflection.custom.fields, customStride, 0);
     },
   };
 }

package/src/gpu-loader.ts

@@ -12,16 +12,17 @@ import type {
 import { err, ok } from '@forgeax/engine-types';
 import {
   VFX_GPU_PROGRAM_ARTIFACT_KEY,
-  VFX_GPU_PROGRAM_FORMAT,
-  type VfxGpuEffectAsset,
-  type VfxGpuEmitterProgram,
+  VFX_GPU_PROGRAM_FORMAT_V3,
+  type VfxGpuEffectAssetAny,
+  type VfxGpuEmitterProgramV3,
 } from './gpu-program.js';
 
 export interface VfxGpuAssetError {
   readonly code:
-    | 'vfx-asset-v2-invalid'
-    | 'vfx-asset-v2-program-missing'
-    | 'vfx-asset-v2-fingerprint-mismatch';
+    | 'vfx-asset-version-unsupported'
+    | 'vfx-asset-v3-invalid'
+    | 'vfx-asset-v3-program-missing'
+    | 'vfx-asset-v3-fingerprint-mismatch';
   readonly expected: string;
   readonly hint: string;
   readonly detail: { readonly guid: string; readonly path: string };
@@ -70,20 +71,26 @@ async function fingerprint(bytes: Uint8Array): Promise<string> {
 
 function validReflectionLayout(value: unknown): boolean {
   if (value === undefined) return true;
-  if (!record(value) || value.version !== 1) return false;
+  if (!record(value) || value.version !== 3) return false;
   if (!record(value.parameters) || !Array.isArray(value.parameters.fields)) return false;
   if (!record(value.custom) || !Array.isArray(value.custom.fields)) return false;
+  if (value.version === 3) {
+    if (!record(value.core) || value.core.name !== 'VfxParticle' || value.core.stride !== 112) {
+      return false;
+    }
+    if (!record(value.customLayout) || value.customLayout.name !== 'VfxCustom') return false;
+  }
   return typeof value.fingerprint === 'string' && value.fingerprint.startsWith('sha256:');
 }
 
-function stableLayouts(emitters: readonly VfxGpuEmitterProgram[]): boolean {
+function stableLayouts(emitters: readonly VfxGpuEmitterProgramV3[]): boolean {
   const fingerprints = emitters
     .map((emitter) => emitter.reflection.layout?.fingerprint)
     .filter((fingerprint): fingerprint is string => fingerprint !== undefined);
   return fingerprints.every((fingerprint) => fingerprint === fingerprints[0]);
 }
 
-function validEmitter(value: unknown): value is VfxGpuEmitterProgram {
+function validEmitter(value: unknown): boolean {
   const reflection = record(value) && record(value.reflection) ? value.reflection : undefined;
   const layout = reflection !== undefined ? reflection.layout : undefined;
   return (
@@ -107,7 +114,13 @@ function validEmitter(value: unknown): value is VfxGpuEmitterProgram {
     value.reflection.entryPoints.includes('forgeax_vfx_mesh_main') &&
     value.reflection.entryPoints.includes('forgeax_vfx_ribbon_main') &&
     value.reflection.entryPoints.includes('forgeax_vfx_trail_main') &&
-    value.reflection.entryPoints.includes('forgeax_vfx_beam_main')
+    value.reflection.entryPoints.includes('forgeax_vfx_beam_main') &&
+    layout !== undefined &&
+    record(layout) &&
+    Array.isArray(reflection?.bindings) &&
+    Array.isArray(reflection?.dataInterfaces) &&
+    Array.isArray(reflection?.renderers) &&
+    Array.isArray(reflection?.resources)
   );
 }
 
@@ -116,26 +129,39 @@ export const vfxGpuEffectPackLoader = {
   async load(
     input: PackLoaderInput,
     _context: LoadContext,
-  ): Promise<Result<VfxGpuEffectAsset, VfxGpuAssetError>> {
+  ): Promise<Result<VfxGpuEffectAssetAny, VfxGpuAssetError>> {
+    const schemaVersion = input.payload.schemaVersion;
+    if (schemaVersion !== 3) {
+      return failure(
+        'vfx-asset-version-unsupported',
+        input.guid,
+        'schemaVersion',
+        'schemaVersion 3 / forgeax-vfx-program-3',
+        'cold-cook the older source and publish a Program v3 payload; older versions are not executable',
+      );
+    }
+    const invalidCode = 'vfx-asset-v3-invalid' as const;
+    const missingCode = 'vfx-asset-v3-program-missing' as const;
+    const fingerprintCode = 'vfx-asset-v3-fingerprint-mismatch' as const;
+    const expectedFormat = VFX_GPU_PROGRAM_FORMAT_V3;
     if (
       input.payload.kind !== 'particle-effect' ||
-      input.payload.schemaVersion !== 2 ||
       !Array.isArray(input.payload.emitters) ||
       typeof input.payload.programFingerprint !== 'string' ||
       !record(input.payload.program)
     ) {
       return failure(
-        'vfx-asset-v2-invalid',
+        invalidCode,
         input.guid,
         'payload',
-        'a schemaVersion 2 particle payload with its complete program and fingerprint',
-        'migrate behavior to WGSL and recook; the runtime does not interpret v1',
+        'a schemaVersion 3 particle payload with its complete Program v3 and fingerprint',
+        'cold-cook the source with the current VFX compiler and retry the load',
       );
     }
     const artifact = input.artifacts[VFX_GPU_PROGRAM_ARTIFACT_KEY];
     if (artifact === undefined) {
       return failure(
-        'vfx-asset-v2-program-missing',
+        missingCode,
         input.guid,
         VFX_GPU_PROGRAM_ARTIFACT_KEY,
         'the asset-local cooked VFX program',
@@ -147,7 +173,7 @@ export const vfxGpuEffectPackLoader = {
       decoded = JSON.parse(new TextDecoder().decode(artifact.bytes));
     } catch {
       return failure(
-        'vfx-asset-v2-invalid',
+        invalidCode,
         input.guid,
         VFX_GPU_PROGRAM_ARTIFACT_KEY,
         'canonical JSON program bytes',
@@ -156,27 +182,27 @@ export const vfxGpuEffectPackLoader = {
     }
     if (
       !record(decoded) ||
-      decoded.format !== VFX_GPU_PROGRAM_FORMAT ||
+      decoded.format !== expectedFormat ||
       !Array.isArray(decoded.emitters) ||
-      !decoded.emitters.every(validEmitter) ||
-      !stableLayouts(decoded.emitters as VfxGpuEmitterProgram[])
+      !decoded.emitters.every((emitter) => validEmitter(emitter)) ||
+      !stableLayouts(decoded.emitters as VfxGpuEmitterProgramV3[])
     ) {
       return failure(
-        'vfx-asset-v2-invalid',
+        invalidCode,
         input.guid,
         VFX_GPU_PROGRAM_ARTIFACT_KEY,
-        `a ${VFX_GPU_PROGRAM_FORMAT} managed GPU program`,
+        `a ${expectedFormat} managed GPU program`,
         'recook with the current VFX compiler ABI',
       );
     }
-    const decodedEmitters = decoded.emitters as VfxGpuEmitterProgram[];
+    const decodedEmitters = decoded.emitters as VfxGpuEmitterProgramV3[];
     if (
-      input.payload.program.format !== VFX_GPU_PROGRAM_FORMAT ||
+      input.payload.program.format !== expectedFormat ||
       input.payload.program.fingerprint !== input.payload.programFingerprint ||
       !Array.isArray(input.payload.program.emitters)
     ) {
       return failure(
-        'vfx-asset-v2-invalid',
+        invalidCode,
         input.guid,
         'payload.program',
         'the complete canonical program matching payload.programFingerprint',
@@ -186,7 +212,7 @@ export const vfxGpuEffectPackLoader = {
     const actualFingerprint = await fingerprint(artifact.bytes);
     if (actualFingerprint !== input.payload.programFingerprint) {
       return failure(
-        'vfx-asset-v2-fingerprint-mismatch',
+        fingerprintCode,
         input.guid,
         'payload.programFingerprint',
         'payload and program artifact fingerprints to match',
@@ -209,7 +235,7 @@ export const vfxGpuEffectPackLoader = {
       )
     ) {
       return failure(
-        'vfx-asset-v2-invalid',
+        invalidCode,
         input.guid,
         'payload.emitters',
         'payload emitter identities and capacities to match the program',
@@ -219,26 +245,26 @@ export const vfxGpuEffectPackLoader = {
     return ok(
       Object.freeze({
         guid: input.guid,
-        kind: 'particle-effect',
-        schemaVersion: 2,
+        kind: 'particle-effect' as const,
+        schemaVersion: 3,
         programFingerprint: actualFingerprint,
         emitters: Object.freeze(emitters as { id: string; capacity: number }[]),
         program: Object.freeze({
-          format: VFX_GPU_PROGRAM_FORMAT,
+          format: expectedFormat,
           fingerprint: actualFingerprint,
           emitters: Object.freeze(decodedEmitters),
         }),
-      }),
+      }) as VfxGpuEffectAssetAny,
     );
   },
 };
 
 /** VFX owner decoder contribution for the core registry's typed map. */
 export const vfxGpuEffectContribution: AssetDecoderContribution<
-  VfxGpuEffectAsset,
+  VfxGpuEffectAssetAny,
   'particle-effect'
 > = {
-  kind: { kind: 'particle-effect' } as AssetKind<VfxGpuEffectAsset, 'particle-effect'>,
+  kind: { kind: 'particle-effect' } as AssetKind<VfxGpuEffectAssetAny, 'particle-effect'>,
   consumer: 'VfxGpuRuntime',
   decoder: {
     async decode({ envelope, artifacts }) {
@@ -277,7 +303,7 @@ export const vfxGpuEffectContribution: AssetDecoderContribution<
 export async function loadVfxGpuEffect(
   registry: LegacyAssetRegistry | RuntimeAssetRegistry,
   guid: string,
-): Promise<Result<VfxGpuEffectAsset, unknown>> {
+): Promise<Result<VfxGpuEffectAssetAny, unknown>> {
   if ('load' in registry) {
     return registry.load(guid, vfxGpuEffectContribution.kind);
   }
@@ -287,5 +313,5 @@ export async function loadVfxGpuEffect(
   } catch (error) {
     return err(error);
   }
-  return registry.loadByGuid<VfxGpuEffectAsset>(parsed);
+  return registry.loadByGuid<VfxGpuEffectAssetAny>(parsed);
 }