@forgeax/engine-vfx 0.1.28 → 0.1.29

package/src/gpu-program.ts

@@ -1,23 +1,28 @@
 import type {
   BindGroupLayoutDescriptor,
-  ParticleEffectAsset,
-  ParticleEffectProgram,
+  MaterialParticleInput,
+  ParticleEffectAssetV3,
   ParticleEffectProgramEmitter,
+  ParticleEffectProgramV3,
 } from '@forgeax/engine-types';
 import type {
   ParticleChannelSource,
-  ParticleEmitterSourceV2,
   ParticleEventSource,
-  ParticleRendererOverflowPolicy,
-  ParticleRendererSorting,
-  ParticleRendererSource,
   ParticleStageDomain,
   ParticleStageResourceAccess,
 } from './code-source.js';
+import type {
+  ParticleEmitterSourceV3,
+  ParticleRendererSemanticMap,
+  ParticleRendererSortingV3,
+  ParticleRendererSourceV3,
+} from './code-source-v3.js';
 import type { VfxDataInterfaceRequirement } from './data-interface.js';
 import type { VfxEffectReflection } from './effect-contract.js';
 
-export const VFX_GPU_PROGRAM_FORMAT = 'forgeax-vfx-program-2' as const;
+/** The only cooked GPU program ABI exposed by the runtime. */
+export const VFX_GPU_PROGRAM_FORMAT = 'forgeax-vfx-program-3' as const;
+export const VFX_GPU_PROGRAM_FORMAT_V3 = VFX_GPU_PROGRAM_FORMAT;
 export const VFX_GPU_PROGRAM_ARTIFACT_KEY = 'particle-effect/program.json' as const;
 
 export interface VfxGpuStageReflection {
@@ -33,13 +38,17 @@ export interface VfxGpuStageReflection {
   readonly iterationBudget: number;
 }
 
-export interface VfxGpuRendererReflection {
-  readonly topology: ParticleRendererSource['kind'];
+/** Reflection of one executable renderer projection. */
+export interface VfxGpuRendererReflectionV3 {
+  readonly topology: ParticleRendererSourceV3['kind'];
   readonly resource: string;
   readonly capacity: number;
-  readonly overflow: ParticleRendererOverflowPolicy;
+  readonly overflow: 'drop-newest' | 'drop-oldest';
   readonly enabled: boolean;
   readonly shaderInputs: readonly string[];
+  readonly attributes: ParticleRendererSemanticMap;
+  readonly materialInputs: readonly string[];
+  readonly materialInputDefinitions?: readonly MaterialParticleInput[];
   readonly textureSheet?: {
     readonly columns: number;
     readonly rows: number;
@@ -48,54 +57,67 @@ export interface VfxGpuRendererReflection {
   };
   readonly pivot?: readonly [number, number];
   readonly softParticle?: { readonly fadeDistance: number; readonly requiresDepth: true };
-  readonly sorting?: ParticleRendererSorting;
+  readonly sorting?: ParticleRendererSortingV3;
   readonly stripKey?: 'alive-index';
   readonly historyLength?: number;
   readonly endpointField?: 'velocity';
+  readonly lighting?: 'unlit' | 'standard';
+  readonly castShadows: boolean;
+  readonly receiveShadows: boolean;
 }
 
-export interface VfxGpuProgramReflection {
+export interface VfxGpuProgramReflectionV3 {
   readonly hooks: readonly ['vfx_spawn', 'vfx_update'];
   readonly imports: readonly string[];
   readonly resources: readonly string[];
   readonly entryPoints: readonly string[];
   readonly bindings: readonly BindGroupLayoutDescriptor[];
-  readonly layout?: VfxEffectReflection;
-  readonly dataInterfaces?: readonly VfxDataInterfaceRequirement[];
-  readonly eventChannels?: readonly ParticleChannelSource[];
-  readonly events?: readonly ParticleEventSource[];
-  readonly eventEntryPoint?: 'forgeax_vfx_event_main';
-  readonly stages?: readonly VfxGpuStageReflection[];
-  readonly renderers?: readonly VfxGpuRendererReflection[];
+  readonly layout: VfxEffectReflection;
+  readonly dataInterfaces: readonly VfxDataInterfaceRequirement[];
+  readonly eventChannels: readonly ParticleChannelSource[];
+  readonly events: readonly ParticleEventSource[];
+  readonly eventEntryPoint: 'forgeax_vfx_event_main';
+  readonly stages: readonly VfxGpuStageReflection[];
+  readonly renderers: readonly VfxGpuRendererReflectionV3[];
 }
 
-export interface VfxGpuEmitterProgram
-  extends Omit<
-    ParticleEffectProgramEmitter,
-    'schedule' | 'bounds' | 'renderers' | 'reflection' | 'channels' | 'events'
-  > {
+export interface VfxGpuEmitterProgramV3
+  extends Omit<ParticleEffectProgramEmitter, 'renderers' | 'reflection'> {
   readonly id: string;
   readonly module: string;
   readonly capacity: number;
-  readonly backend: ParticleEmitterSourceV2['backend'];
-  readonly space: ParticleEmitterSourceV2['space'];
-  readonly schedule: ParticleEmitterSourceV2['schedule'];
-  readonly bounds: ParticleEmitterSourceV2['bounds'];
-  readonly renderers: ParticleEmitterSourceV2['renderers'];
+  readonly backend: ParticleEmitterSourceV3['backend'];
+  readonly space: ParticleEmitterSourceV3['space'];
+  readonly schedule: ParticleEmitterSourceV3['schedule'];
+  readonly bounds: ParticleEmitterSourceV3['bounds'];
+  readonly renderers: readonly ParticleRendererSourceV3[];
   readonly channels?: readonly ParticleChannelSource[];
   readonly events?: readonly ParticleEventSource[];
-  readonly simulationWhenCulled: NonNullable<ParticleEmitterSourceV2['simulationWhenCulled']>;
+  readonly simulationWhenCulled: NonNullable<ParticleEmitterSourceV3['simulationWhenCulled']>;
   readonly wgsl: string;
-  readonly reflection: VfxGpuProgramReflection;
+  readonly reflection: VfxGpuProgramReflectionV3;
 }
 
-export interface VfxGpuProgram extends Omit<ParticleEffectProgram, 'emitters'> {
+export interface VfxGpuProgramV3 extends Omit<ParticleEffectProgramV3, 'emitters'> {
   readonly format: typeof VFX_GPU_PROGRAM_FORMAT;
   readonly fingerprint: string;
-  readonly emitters: readonly VfxGpuEmitterProgram[];
+  readonly emitters: readonly VfxGpuEmitterProgramV3[];
 }
 
-export interface VfxGpuEffectAsset extends ParticleEffectAsset {
+export interface VfxGpuEffectAssetV3 extends Omit<ParticleEffectAssetV3, 'program'> {
   readonly guid: string;
-  readonly program: VfxGpuProgram;
+  readonly kind: 'particle-effect';
+  readonly schemaVersion: 3;
+  readonly programFingerprint: string;
+  readonly emitters: readonly { readonly id: string; readonly capacity: number }[];
+  readonly program: VfxGpuProgramV3;
 }
+
+/** Public names point at the same one-cut Program v3 shapes. */
+export type VfxGpuRendererReflection = VfxGpuRendererReflectionV3;
+export type VfxGpuProgramReflection = VfxGpuProgramReflectionV3;
+export type VfxGpuEmitterProgram = VfxGpuEmitterProgramV3;
+export type VfxGpuProgram = VfxGpuProgramV3;
+export type VfxGpuEffectAsset = VfxGpuEffectAssetV3;
+export type VfxGpuEmitterProgramAny = VfxGpuEmitterProgramV3;
+export type VfxGpuEffectAssetAny = VfxGpuEffectAssetV3;

package/src/gpu-runtime.ts

@@ -4,7 +4,7 @@ import { type Handle, toShared } from '@forgeax/engine-types';
 import type { ParticleEventSource } from './code-source.js';
 import type { VfxValueMap } from './effect-contract.js';
 import { createVfxEffectContract, type VfxEffectReflection } from './effect-contract.js';
-import type { VfxGpuEffectAsset, VfxGpuEmitterProgram } from './gpu-program.js';
+import type { VfxGpuEffectAssetAny, VfxGpuEmitterProgramAny } from './gpu-program.js';
 import {
   ParticleEffectInstance,
   type VfxChannelCounters,
@@ -49,7 +49,7 @@ export function createVfxInspectSnapshot(input: VfxInspectSnapshotInput) {
 export interface VfxGpuTickIntent {
   readonly sequence: number;
   readonly player: EntityHandle;
-  readonly emitter: VfxGpuEmitterProgram;
+  readonly emitter: VfxGpuEmitterProgramAny;
   readonly programFingerprint: string;
   readonly reset: boolean;
   readonly fixedDelta: number;
@@ -84,18 +84,24 @@ export interface VfxGpuEmitterInspectSnapshot {
   readonly spawnCount: number;
   readonly firstParticleId: number;
   readonly reset: boolean;
-  readonly schedule: VfxGpuEmitterProgram['schedule'];
-  readonly bounds: VfxGpuEmitterProgram['bounds'];
-  readonly simulationWhenCulled: VfxGpuEmitterProgram['simulationWhenCulled'];
+  readonly schedule: VfxGpuEmitterProgramAny['schedule'];
+  readonly bounds: VfxGpuEmitterProgramAny['bounds'];
+  readonly simulationWhenCulled: VfxGpuEmitterProgramAny['simulationWhenCulled'];
   readonly renderers: readonly {
     readonly index: number;
-    readonly kind: VfxGpuEmitterProgram['renderers'][number]['kind'];
+    readonly kind: VfxGpuEmitterProgramAny['renderers'][number]['kind'];
     readonly enabled: boolean;
   }[];
   readonly stages: readonly string[];
   readonly dataInterfaces: readonly string[];
 }
 
+/** Renderer-facing source view used to refresh culling without a queued tick. */
+export interface VfxGpuEmitterSource {
+  readonly player: EntityHandle;
+  readonly emitter: VfxGpuEmitterProgramAny;
+}
+
 export interface VfxGpuCommittedInspectSnapshot {
   readonly sequence: number;
   readonly tick: number;
@@ -143,7 +149,7 @@ interface PlayerState {
   effect: Handle<'ParticleEffectAsset', 'shared'>;
   assetGuid: string;
   programFingerprint: string;
-  emitters: readonly VfxGpuEmitterProgram[];
+  emitters: readonly VfxGpuEmitterProgramAny[];
   seed: number;
   playing: boolean;
   playCycle: number;
@@ -154,6 +160,7 @@ interface PlayerState {
   cameraVisible: boolean[];
   phaseTicks: number[];
   hasCommitted: boolean;
+  pendingResets: boolean[];
 }
 
 function eventCounters(
@@ -216,10 +223,30 @@ export class VfxGpuRuntime {
     return this.#diagnostics;
   }
 
+  /**
+   * Visit every live emitter source.  The renderer uses this on render frames
+   * where pause/restart culling has no pending simulation intent, so a camera
+   * move back into the bounds can refresh visibility before the next tick.
+   */
+  forEachEmitterSource(visitor: (source: VfxGpuEmitterSource) => void): void {
+    for (const [player, state] of this.#players) {
+      for (const emitter of state.emitters) visitor({ player, emitter });
+    }
+  }
+
   lastCommitted(player: EntityHandle): VfxGpuTickIntent | undefined {
     return this.#lastCommitted.get(player);
   }
 
+  /**
+   * Return the last submitted fixed-tick state for one emitter.  Renderers
+   * retain this projection between fixed ticks; simulation intents are a
+   * queue, while a drawable emitter remains live until the player is reset.
+   */
+  lastCommittedEmitter(player: EntityHandle, emitterId: string): VfxGpuTickIntent | undefined {
+    return this.#lastCommittedByEmitter.get(player)?.get(emitterId);
+  }
+
   inspectPlayers(): readonly VfxGpuPlayerInspectSnapshot[] {
     return Object.freeze(
       [...this.#players.keys()]
@@ -399,24 +426,49 @@ export class VfxGpuRuntime {
     this.#replayRequests.add(player);
   }
 
-  commit(sequence: number): void {
+  /**
+   * Acknowledge queued intents. A scalar acknowledges the contiguous prefix;
+   * an array acknowledges only those terminal sequences, which lets unrelated
+   * player/emitter streams progress while another stream is deferred. When the
+   * renderer supplies `publishedSequences`, only intents that reached GPU
+   * submission update the retained last-committed projection; skipped intents
+   * are queue acknowledgements, not new GPU state.
+   */
+  commit(sequence: number | readonly number[], publishedSequences?: readonly number[]): void {
+    const prefix = typeof sequence === 'number' ? sequence : undefined;
+    const acknowledged = typeof sequence === 'number' ? undefined : new Set(sequence);
+    const published = publishedSequences === undefined ? undefined : new Set(publishedSequences);
     const committedPlayers = new Set<EntityHandle>();
+    const retained: VfxGpuTickIntent[] = [];
     for (const intent of this.#intents) {
-      if (intent.sequence > sequence) break;
-      const state = this.#players.get(intent.player);
-      if (state !== undefined) state.hasCommitted = true;
-      this.#lastCommitted.set(intent.player, intent);
-      let emitters = this.#lastCommittedByEmitter.get(intent.player);
-      if (emitters === undefined) {
-        emitters = new Map();
-        this.#lastCommittedByEmitter.set(intent.player, emitters);
+      const shouldAcknowledge =
+        prefix === undefined
+          ? acknowledged?.has(intent.sequence) === true
+          : intent.sequence <= prefix;
+      if (!shouldAcknowledge) {
+        retained.push(intent);
+        continue;
       }
-      emitters.set(intent.emitter.id, intent);
+      const state = this.#players.get(intent.player);
       committedPlayers.add(intent.player);
+      if (published === undefined || published.has(intent.sequence)) {
+        if (state !== undefined) state.hasCommitted = true;
+        const priorCommitted = this.#lastCommitted.get(intent.player);
+        if (priorCommitted === undefined || priorCommitted.sequence < intent.sequence) {
+          this.#lastCommitted.set(intent.player, intent);
+        }
+        let emitters = this.#lastCommittedByEmitter.get(intent.player);
+        if (emitters === undefined) {
+          emitters = new Map();
+          this.#lastCommittedByEmitter.set(intent.player, emitters);
+        }
+        const priorEmitter = emitters.get(intent.emitter.id);
+        if (priorEmitter === undefined || priorEmitter.sequence < intent.sequence) {
+          emitters.set(intent.emitter.id, intent);
+        }
+      }
     }
-    const retained = this.#intents.findIndex((intent) => intent.sequence > sequence);
-    if (retained < 0) this.#intents.length = 0;
-    else if (retained > 0) this.#intents.splice(0, retained);
+    this.#intents.splice(0, this.#intents.length, ...retained);
     for (const player of committedPlayers) {
       this.#clearDiagnostics(player, 'vfx-intent-queue-overflow');
     }
@@ -519,14 +571,14 @@ export class VfxGpuRuntime {
         continue;
       }
       this.#clearDiagnostics(input.player, 'vfx-player-invalid');
-      const resolved = world.sharedRefs.resolve<'ParticleEffectAsset', VfxGpuEffectAsset>(
+      const resolved = world.sharedRefs.resolve<'ParticleEffectAsset', VfxGpuEffectAssetAny>(
         input.effect,
       );
-      if (!resolved.ok || resolved.value.schemaVersion !== 2) {
+      if (!resolved.ok || resolved.value.schemaVersion !== 3) {
         this.#report({
           code: 'vfx-effect-unavailable',
-          expected: 'a loaded schemaVersion 2 GPU particle effect',
-          hint: 'load and recook the effect before the first FixedUpdate',
+          expected: 'a loaded schemaVersion 3 GPU particle effect',
+          hint: 'cold-cook the legacy effect as Program v3 before the first FixedUpdate',
           detail: { player: input.player },
         });
         continue;
@@ -534,13 +586,14 @@ export class VfxGpuRuntime {
       this.#clearDiagnostics(input.player, 'vfx-effect-unavailable');
       const previous = this.#players.get(input.player);
       const replayRequested = this.#replayRequests.delete(input.player);
-      const restart =
+      const restartRequested =
         previous === undefined ||
         previous.effect !== input.effect ||
         previous.seed !== input.seed ||
         replayRequested ||
         (!previous.playing && input.playing);
-      const state = restart
+      const restart = restartRequested;
+      const state = restartRequested
         ? {
             effect: input.effect,
             assetGuid: resolved.value.guid,
@@ -556,6 +609,7 @@ export class VfxGpuRuntime {
             cameraVisible: resolved.value.program.emitters.map(() => true),
             phaseTicks: resolved.value.program.emitters.map(() => 0),
             hasCommitted: false,
+            pendingResets: resolved.value.program.emitters.map(() => false),
           }
         : previous;
       this.#players.set(input.player, state);
@@ -563,7 +617,10 @@ export class VfxGpuRuntime {
       // authority. Inspection always returns the authored player state after
       // the requested reset intent has been emitted.
       state.playing = input.playing;
-      if (!input.playing && !replayRequested) continue;
+      if (!input.playing && !replayRequested) {
+        if (restart) state.pendingResets.fill(true);
+        continue;
+      }
       const queuedForPlayer = this.#intents.reduce(
         (count, intent) => count + (intent.player === input.player ? 1 : 0),
         0,
@@ -572,6 +629,7 @@ export class VfxGpuRuntime {
         queuedForPlayer >=
         this.#maxQueuedTicks * Math.max(1, resolved.value.program.emitters.length)
       ) {
+        if (restart) state.pendingResets.fill(true);
         if (state.hasCommitted) {
           this.#report({
             code: 'vfx-intent-queue-overflow',
@@ -584,13 +642,17 @@ export class VfxGpuRuntime {
       }
       const instance =
         this.#instances.get(input.player) ?? this.#createInstance(input.player, resolved.value);
-      if (instance === undefined) continue;
+      if (instance === undefined) {
+        if (restart) state.pendingResets.fill(true);
+        continue;
+      }
       const hasActiveEmitter = resolved.value.program.emitters.some((emitter) => {
         if (!this.isEmitterSessionEnabled(input.player, emitter.id)) return false;
         const cameraVisible = this.#cameraVisibility.get(`${input.player}:${emitter.id}`) ?? true;
         return cameraVisible || emitter.simulationWhenCulled === 'continue';
       });
       if (!hasActiveEmitter) {
+        if (restart) state.pendingResets.fill(true);
         for (const [index, emitter] of resolved.value.program.emitters.entries()) {
           state.cameraVisible[index] =
             this.#cameraVisibility.get(`${input.player}:${emitter.id}`) ?? true;
@@ -604,6 +666,7 @@ export class VfxGpuRuntime {
           ? instance.commit({ seed: input.seed, tick })
           : instance.replay(replayInput);
       if (!committed.ok) {
+        if (restart) state.pendingResets.fill(true);
         this.#report({
           code: 'vfx-instance-commit-failed',
           expected: 'the current typed instance values to pack into the reflected GPU block',
@@ -618,8 +681,15 @@ export class VfxGpuRuntime {
         const cameraVisible = this.#cameraVisibility.get(`${input.player}:${emitter.id}`) ?? true;
         const becameVisible = cameraVisible && state.cameraVisible[index] === false;
         state.cameraVisible[index] = cameraVisible;
-        if (!this.isEmitterSessionEnabled(input.player, emitter.id)) continue;
-        if (!cameraVisible && emitter.simulationWhenCulled !== 'continue') continue;
+        const emitterRestart = restart || state.pendingResets[index] === true;
+        if (!this.isEmitterSessionEnabled(input.player, emitter.id)) {
+          if (emitterRestart) state.pendingResets[index] = true;
+          continue;
+        }
+        if (!cameraVisible && emitter.simulationWhenCulled !== 'continue') {
+          if (emitterRestart) state.pendingResets[index] = true;
+          continue;
+        }
         const visibilityRestart =
           becameVisible && emitter.simulationWhenCulled === 'restart-on-visible';
         if (visibilityRestart) {
@@ -634,7 +704,7 @@ export class VfxGpuRuntime {
           emitter,
           previousElapsed,
           previousElapsed + delta,
-          restart || visibilityRestart,
+          emitterRestart || visibilityRestart,
           state.rateRemainders[index] ?? 0,
         );
         state.rateRemainders[index] = scheduled.remainder;
@@ -655,7 +725,7 @@ export class VfxGpuRuntime {
             player: input.player,
             emitter,
             programFingerprint: resolved.value.program.fingerprint,
-            reset: restart || visibilityRestart,
+            reset: emitterRestart || visibilityRestart,
             fixedDelta: delta,
             phaseTick,
             tick,
@@ -678,6 +748,7 @@ export class VfxGpuRuntime {
         );
         state.elapsed[index] = previousElapsed + delta;
         state.phaseTicks[index] = phaseTick + 1;
+        state.pendingResets[index] = false;
       }
     }
     for (const player of this.#players.keys()) {
@@ -687,19 +758,21 @@ export class VfxGpuRuntime {
 
   #createInstance(
     player: EntityHandle,
-    effect: VfxGpuEffectAsset,
+    effect: VfxGpuEffectAssetAny,
   ): ParticleEffectInstance | undefined {
     const layout = effect.program.emitters.find(
       (emitter) => emitter.reflection.layout !== undefined,
     )?.reflection.layout;
-    const reflection: VfxEffectReflection = layout ?? {
-      version: 1,
-      parameters: { name: 'VfxParameters', fields: [], size: 0, alignment: 1 },
-      custom: { name: 'VfxCustom', fields: [], size: 0, alignment: 1 },
-      fingerprint: effect.program.fingerprint.startsWith('sha256:')
-        ? effect.program.fingerprint
-        : `sha256:${effect.program.fingerprint}`,
-    };
+    if (layout === undefined) {
+      this.#report({
+        code: 'vfx-effect-unavailable',
+        expected: 'a Program v3 emitter reflection layout',
+        hint: 'recook the effect with Program v3 reflection before starting the player',
+        detail: { player },
+      });
+      return undefined;
+    }
+    const reflection: VfxEffectReflection = layout;
     try {
       const instance = new ParticleEffectInstance(createVfxEffectContract(reflection), {
         channels: effect.program.emitters.flatMap((emitter) => emitter.channels ?? []),
@@ -730,7 +803,7 @@ export class VfxGpuRuntime {
 }
 
 function spawnCount(
-  emitter: VfxGpuEmitterProgram,
+  emitter: VfxGpuEmitterProgramAny,
   previous: number,
   next: number,
   firstTick: boolean,

package/src/index.ts

@@ -1,6 +1,11 @@
 // @forgeax/engine-vfx - runtime-safe code-first GPU VFX contract.
 
-export type { ParticleEffectAsset, ParticleEmitterDefinition } from '@forgeax/engine-types';
+export type {
+  ParticleEffectAsset,
+  ParticleEffectAssetV3,
+  ParticleEffectProgramV3,
+  ParticleEmitterDefinition,
+} from '@forgeax/engine-types';
 export { particleEffectContribution } from './assets/particle-effect-decoder';
 export type {
   VfxAuthoringCapabilityDescriptor,
@@ -20,25 +25,34 @@ export type {
   ParticleChannelSource,
   ParticleCodeSourceError,
   ParticleCodeSourceInvalidDetail,
-  ParticleEffectRootSourceV2,
-  ParticleEffectSourceV2,
-  ParticleEmitterSourceV2,
   ParticleEventSource,
   ParticleRendererOverflowPolicy,
-  ParticleRendererSorting,
-  ParticleRendererSource,
   ParticleStageDomain,
   ParticleStageResourceAccess,
   ParticleStageResourceSource,
   ParticleStageSource,
 } from './code-source.js';
 export {
-  defineParticleEffectSourceV2,
   PARTICLE_CODE_DEFAULT_MODULE_ID,
   PARTICLE_STAGE_RESOURCE_NAMES,
-  parseParticleEffectSourceV2,
   parseVfxStageDeclarations,
 } from './code-source.js';
+export type {
+  ParticleAttributeRef,
+  ParticleEffectRootSourceV3,
+  ParticleEffectSourceV3,
+  ParticleEmitterSourceV3,
+  ParticleRendererSemantic,
+  ParticleRendererSemanticMap,
+  ParticleRendererSortingV3,
+  ParticleRendererSourceV3,
+} from './code-source-v3.js';
+export {
+  defaultParticleRendererAttributes,
+  defineParticleEffectSourceV3,
+  PARTICLE_RENDERER_SEMANTICS,
+  parseParticleEffectSourceV3,
+} from './code-source-v3.js';
 export type {
   VfxDataInterfaceBindingType,
   VfxDataInterfaceError,
@@ -72,14 +86,26 @@ export {
 } from './gpu-loader.js';
 export type {
   VfxGpuEffectAsset,
+  VfxGpuEffectAssetAny,
+  VfxGpuEffectAssetV3,
   VfxGpuEmitterProgram,
+  VfxGpuEmitterProgramAny,
+  VfxGpuEmitterProgramV3,
   VfxGpuProgram,
   VfxGpuProgramReflection,
+  VfxGpuProgramReflectionV3,
+  VfxGpuProgramV3,
+  VfxGpuRendererReflectionV3,
   VfxGpuStageReflection,
 } from './gpu-program.js';
-export { VFX_GPU_PROGRAM_ARTIFACT_KEY, VFX_GPU_PROGRAM_FORMAT } from './gpu-program.js';
+export {
+  VFX_GPU_PROGRAM_ARTIFACT_KEY,
+  VFX_GPU_PROGRAM_FORMAT,
+  VFX_GPU_PROGRAM_FORMAT_V3,
+} from './gpu-program.js';
 export type {
   VfxGpuEmitterInspectSnapshot,
+  VfxGpuEmitterSource,
   VfxGpuPlayerInspectSnapshot,
   VfxGpuRuntimeDiagnostic,
   VfxGpuRuntimeOptions,
@@ -106,5 +132,23 @@ export {
   createParticleEffectInstance,
   ParticleEffectInstance,
 } from './instance.js';
+export type {
+  VfxCustomLayout,
+  VfxParametersLayout,
+  VfxParticleCoreAttribute,
+  VfxParticleCoreField,
+  VfxParticleCoreLayout,
+  VfxParticleCoreValue,
+  VfxParticleCoreValues,
+} from './particle-layout.js';
+export {
+  deriveVfxCustomLayout,
+  encodeVfxParticleCore,
+  normalizedVfxParticleAge,
+  VFX_PARTICLE_CORE_LAYOUT,
+  VFX_PARTICLE_CORE_STRIDE,
+  vfxParticleCoreField,
+  vfxParticleCoreWgsl,
+} from './particle-layout.js';
 export type { ParticleEffectPlayerData } from './player.js';
 export { ParticleEffectPlayer } from './player.js';