@directivegames/genesys.js 3.1.24

package/src/utils/serialization/specialization.ts

@@ -0,0 +1,224 @@
+// registry those class that can't be directly modified to add serialization support
+
+import * as THREE from 'three';
+
+import { MaterialUtils } from '../../materials.js';
+
+import { registerAsGlobalObject, registerPropertyMetadata, registerSimpleType, registerSpecialization, RegistrationFlags } from './specializationUtils.js';
+
+
+import type { PropertyMetadata } from './decorator.js';
+import type { Dumper, Loader } from './serializer.js';
+
+/**
+ * How to specialize serialization for a class if it's not directly modifiable, i.e. from an external library or built-in class
+ *
+ * Method 1: Use `registerSpecialization` to register custom serialize/deserialize functions manually
+ * arguments:
+ *   cls: the class constructor
+ *   serializeFn: function that takes an instance of the class and a Dumper, and uses the Dumper to serialize the instance
+ *   deserializeFn: optional, function that takes an instance of the class and a Loader, and uses the Loader to load data into the instance
+ *   staticDeserializeFn: optional, function that takes data and constructs and returns a new instance of the class
+ *   clsAlias: optional, a short alias string to use instead of the full class name during serialization
+ * Example:
+ *   registerSpecialization({
+ *     cls: SomeClass,
+ *     // however you want to serialize the instance
+ *     serializeFn: (obj: SomeClass, dumper: Dumper) => {
+ *       dumper.dumpValue('f1', obj.f1);
+ *       dumper.dumpValue('f23', [obj.f2, obj.f3]);
+ *     },
+ *    // however you want to deserialize into an existing instance
+ *     deserializeFn: (obj: SomeClass, loader: Loader) => {
+ *       obj.f1 = loader.loadValue('f1');
+ *       const [f2, f3] = loader.loadValue('f23');
+ *       obj.f2 = f2;
+ *       obj.f3 = f3;
+ *     },
+ *     // however you want to use `data` to construct a new instance
+ *     staticDeserializeFn: (data: any) => new SomeClass({f1: data.f1, f2: data.f23[0], f3: data.f23[1]}),
+ *     clsAlias: 'sc'
+ *   });
+ *
+ *
+ * Method 2: Use `registerSimpleType` to register classes that can be serialized/deserialized into/from a simple array of values
+ *           T() <==> [p1, p2, p3, ...], where T is a class containing properties p1, p2, p3, and T can be constructed as new `T(p1, p2, p3, ...)`
+ *           i.e. THREE.Color <==> [r, g, b],
+ *           in fact it's just a shorthand for `registerSpecialization`
+ * arguments:
+ *   cls: the class constructor
+ *   propertiesGetter: function that takes an instance of the class and returns the properties that should be serialized/deserialized as an array
+ *                     it's taking a function instead of an array of strings it allow compile time type checking of the properties,
+ *                     this is especially useful for o.params.xxx that has multiple levels
+ *   clsAlias: optional, a short alias string to use instead of the full class name during serialization
+ *   flags: optional, RegistrationFlags to control whether to register deserializer/static deserializer
+ * Example:
+ *   registerSimpleType(THREE.Color, o => [o.r, o.g, o.b], 'c');  // serialize THREE.Color to {c: [r, g, b]}
+ *
+ * Method 3: Use `registerPropertyMetadata` to register property metadata for classes manually
+ *           This is essentially the same as applying the `@property` decorator to each property,
+ *           except that you don't have direct access to the class source code to add the decorators.
+ *           This method can be used together with Method 1, as long as `dumper.dumpDefaults` and `loader.loadDefaults` are used in the
+ *           serializeFn and deserializeFn respectively.
+ * arguments:
+ *   cls: the class constructor
+ *   metadata: an object mapping property names to PropertyMetadata
+ * Example:
+ *   registerPropertyMetadata(SomeClass, {
+ *     f1: {default: 0},
+ *     f2: {ctorArg: 'ctorArgAndProperty', ctorArgIndex: 0},
+ *     f3: {ctorArg: 'ctorArgAndProperty', ctorArgIndex: 1},
+ *   });
+ *   // this is equivalent to
+ *   class SomeClass {
+ *     @property({default: 0})
+ *     public f1: number;
+ *
+ *     @property({ctorArg: 'ctorArgAndProperty', ctorArgIndex: 0})
+ *     public f2: number;
+ *
+ *     @property({ctorArg: 'ctorArgAndProperty', ctorArgIndex: 1})
+ *     public f3: number;
+ *   }
+ */
+
+
+registerSpecialization(
+  {
+    cls: Int32Array,
+    serializeFn: (obj: Int32Array, dumper: Dumper) => { dumper.dumpValue('_', Array.from(obj)); },
+    deserializeFn: (obj: Int32Array, loader: Loader) => { obj.set(loader.loadValue('_').slice(0, obj.length)); },
+    staticDeserializeFn: (data: any) => new Int32Array(data._),
+    clsAlias: 'ia'
+  }
+);
+
+registerSpecialization(
+  {
+    cls: Float32Array,
+    serializeFn: (obj: Float32Array, dumper: Dumper) => { dumper.dumpValue('_', Array.from(obj).map(v => Math.round(v * 1000000) / 1000000)); },
+    deserializeFn: (obj: Float32Array, loader: Loader) => { obj.set(loader.loadValue('_').slice(0, obj.length)); },
+    staticDeserializeFn: (data: any) => new Float32Array(data._),
+    clsAlias: 'fa'
+  }
+);
+
+// Math
+registerSimpleType(THREE.Color, o => [o.r, o.g, o.b], {clsAlias: 'c'});
+registerSimpleType(THREE.Euler, o => [o.x, o.y, o.z], {clsAlias: 'e'});
+registerSimpleType(THREE.Quaternion, o => [o.x, o.y, o.z, o.w], {clsAlias: 'q'});
+registerSimpleType(THREE.Vector2, o => [o.x, o.y], {clsAlias: 'v2'});
+registerSimpleType(THREE.Vector3, o => [o.x, o.y, o.z], {clsAlias: 'v3'});
+registerSimpleType(THREE.Vector4, o => [o.x, o.y, o.z, o.w], {clsAlias: 'v4'});
+registerSimpleType(THREE.Matrix2, o => o.elements, {clsAlias: 'm2'});
+registerSimpleType(THREE.Matrix3, o => o.elements, {clsAlias: 'm3'});
+registerSimpleType(THREE.Matrix4, o => o.elements, {clsAlias: 'm4'});
+
+// dumping/loading non-primitive types. it works, but is that a good idea
+registerSimpleType(THREE.Box2, o => [o.min, o.max], {clsAlias: 'b2'});
+registerSimpleType(THREE.Box3, o => [o.min, o.max], {clsAlias: 'b3'});
+registerSimpleType(THREE.Sphere, o => [o.center, o.radius]);
+registerSimpleType(THREE.Plane, o => [o.normal, o.constant]);
+
+
+// geometries
+registerSimpleType(THREE.BoxGeometry, o => [o.parameters.width, o.parameters.height, o.parameters.depth], {flags: RegistrationFlags.NoDeserializer});
+registerSimpleType(THREE.SphereGeometry, o => [o.parameters.radius, o.parameters.widthSegments, o.parameters.heightSegments], {flags: RegistrationFlags.NoDeserializer});
+registerSimpleType(THREE.CylinderGeometry, o => [o.parameters.radiusTop, o.parameters.radiusBottom, o.parameters.height, o.parameters.radialSegments, o.parameters.heightSegments, o.parameters.openEnded], {flags: RegistrationFlags.NoDeserializer});
+registerSimpleType(THREE.PlaneGeometry, o => [o.parameters.width, o.parameters.height], {flags: RegistrationFlags.NoDeserializer});
+registerSimpleType(THREE.CapsuleGeometry, o => [o.parameters.radius, o.parameters.height, o.parameters.capSegments, o.parameters.radialSegments], {flags: RegistrationFlags.NoDeserializer});
+registerSimpleType(THREE.ConeGeometry, o => [o.parameters.radius, o.parameters.height, o.parameters.radialSegments, o.parameters.heightSegments], {flags: RegistrationFlags.NoDeserializer});
+registerSimpleType(THREE.CircleGeometry, o => [o.parameters.radius, o.parameters.segments, o.parameters.thetaStart, o.parameters.thetaLength], {flags: RegistrationFlags.NoDeserializer});
+registerSimpleType(THREE.TorusGeometry, o => [o.parameters.radius, o.parameters.tube, o.parameters.radialSegments, o.parameters.tubularSegments], {flags: RegistrationFlags.NoDeserializer});
+registerSimpleType(THREE.TorusKnotGeometry, o => [o.parameters.radius, o.parameters.tube, o.parameters.radialSegments, o.parameters.tubularSegments, o.parameters.radialSegments, o.parameters.tubularSegments], {flags: RegistrationFlags.NoDeserializer});
+registerSimpleType(THREE.TubeGeometry, o => [o.parameters.path, o.parameters.tubularSegments, o.parameters.radius, o.parameters.radialSegments, o.parameters.closed], {flags: RegistrationFlags.NoDeserializer});
+registerSimpleType(THREE.DodecahedronGeometry, o => [o.parameters.radius, o.parameters.detail], {flags: RegistrationFlags.NoDeserializer});
+registerSimpleType(THREE.EdgesGeometry, o => [o.parameters.geometry, o.parameters.thresholdAngle], {flags: RegistrationFlags.NoDeserializer});
+registerSimpleType(THREE.ExtrudeGeometry, o => [o.parameters.shapes, o.parameters.options], {flags: RegistrationFlags.NoDeserializer});
+registerSimpleType(THREE.IcosahedronGeometry, o => [o.parameters.radius, o.parameters.detail], {flags: RegistrationFlags.NoDeserializer});
+registerSimpleType(THREE.LatheGeometry, o => [o.parameters.points, o.parameters.segments, o.parameters.phiStart, o.parameters.phiLength], {flags: RegistrationFlags.NoDeserializer});
+registerSimpleType(THREE.OctahedronGeometry, o => [o.parameters.radius, o.parameters.detail], {flags: RegistrationFlags.NoDeserializer});
+registerSimpleType(THREE.PolyhedronGeometry, o => [o.parameters.vertices, o.parameters.indices, o.parameters.radius, o.parameters.detail], {flags: RegistrationFlags.NoDeserializer});
+registerSimpleType(THREE.RingGeometry, o => [o.parameters.innerRadius, o.parameters.outerRadius, o.parameters.thetaSegments, o.parameters.phiSegments], {flags: RegistrationFlags.NoDeserializer});
+registerSimpleType(THREE.ShapeGeometry, o => [o.parameters.shapes, o.parameters.curveSegments], {flags: RegistrationFlags.NoDeserializer});
+registerSimpleType(THREE.TetrahedronGeometry, o => [o.parameters.radius, o.parameters.detail], {flags: RegistrationFlags.NoDeserializer});
+registerSimpleType(THREE.WireframeGeometry, o => [o.parameters.geometry], {flags: RegistrationFlags.NoDeserializer});
+
+
+// lights
+registerSimpleType(THREE.AmbientLight, o => [o.color, o.intensity]);
+registerSimpleType(THREE.DirectionalLight, o => [o.color, o.intensity]);
+registerSimpleType(THREE.HemisphereLight, o => [o.color, o.intensity]);
+registerSimpleType(THREE.PointLight, o => [o.color, o.intensity, o.distance, o.decay]);
+registerSimpleType(THREE.LightProbe, o => [o.sh, o.intensity]);
+registerSimpleType(THREE.RectAreaLight, o => [o.color, o.intensity, o.width, o.height]);
+registerSimpleType(THREE.SpotLight, o => [o.color, o.intensity, o.distance, o.angle, o.penumbra, o.decay]);
+
+// fog
+registerSimpleType(THREE.Fog, o => [o.color, o.near, o.far]);
+registerSimpleType(THREE.FogExp2, o => [o.color, o.density]);
+
+// material classes
+function registerMaterial<T>(cls: (new () => T) & Function) {
+  const proto = new cls() as Record<keyof T, any>;
+  const metadata: Partial<Record<keyof T, PropertyMetadata>> = {};
+
+  for (const [k, v] of Object.entries(proto)) {
+    if (v instanceof THREE.Texture) {
+      // skip texture properties
+      continue;
+    }
+
+    const meta: PropertyMetadata = {};
+    if (k === 'uuid') {
+      // uuid is not supposed to be serialized or have a default value
+      meta.transientOnPrefab = true;
+    }
+    else if (v === null || typeof v !== 'object') {
+      meta.default = v as number | string | boolean | null | undefined;
+    }
+    metadata[k as keyof T] = meta;
+  }
+
+  registerPropertyMetadata(cls, metadata);
+}
+
+registerMaterial(THREE.MeshStandardMaterial);
+registerMaterial(THREE.LineBasicMaterial);
+registerMaterial(THREE.LineDashedMaterial);
+registerMaterial(THREE.MeshBasicMaterial);
+registerMaterial(THREE.MeshDepthMaterial);
+registerMaterial(THREE.MeshDistanceMaterial);
+registerMaterial(THREE.MeshLambertMaterial);
+registerMaterial(THREE.MeshMatcapMaterial);
+registerMaterial(THREE.MeshNormalMaterial);
+registerMaterial(THREE.MeshPhongMaterial);
+registerMaterial(THREE.MeshPhysicalMaterial);
+registerMaterial(THREE.MeshToonMaterial);
+registerMaterial(THREE.RawShaderMaterial);
+registerMaterial(THREE.ShaderMaterial);
+registerMaterial(THREE.ShadowMaterial);
+registerMaterial(THREE.PointsMaterial);
+registerMaterial(THREE.SpriteMaterial);
+
+
+registerPropertyMetadata(THREE.Object3D, {
+  uuid: { transientOnPrefab: true, readonly: true, order: -20 },
+  name: { order: -19, hidden: true },
+  position: { order: -10 },
+  rotation: { order: -10 },
+  scale: { order: -10 },
+  visible: { default: true, order: -5 },
+  castShadow: { default: false, order: 0 },
+  receiveShadow: { default: false, order: 0 },
+  frustumCulled: { default: true, order: 0 },
+  renderOrder: { default: 0, order: 0 },
+  up: { order: 50 },
+  userData: { hidden: true },
+});
+
+
+// external objects that should be globally shared (lazy registration to defer THREE.js object creation)
+registerAsGlobalObject('DefaultTexture', () => MaterialUtils.DefaultTexture);
+registerAsGlobalObject('DefaultMaterial', () => MaterialUtils.DefaultMaterial);
+registerAsGlobalObject('MeshWorldSpaceNormalMaterial', () => MaterialUtils.MeshWorldSpaceNormalMaterial);

package/src/utils/serialization/specializationUtils.ts

@@ -0,0 +1,185 @@
+// registry those class that can't be directly modified to add serialization support
+
+
+import { getClassDefaultObject } from './cdo.js';
+import { getClassForDeserialization, GlobalObjectRegistry, registerClassAlias } from './clsAlias.js';
+import {property} from './decorator.js';
+import { ISerializableObjectTag } from './serializable.js';
+
+import type { PropertyMetadata } from './decorator.js';
+import type { ISerializableObject } from './serializable.js';
+import type { Loader } from './serializer.js';
+import type { Dumper } from './serializer.js';
+
+interface SerializationEntry<T extends object> {
+	serializeFn?: (obj: T, dumper: Dumper) => any;
+	deserializeFn?: (obj: T, loader: Loader) => void;  // load data into existing instance
+  staticDeserializeFn?: (data: any) => any;  // load data and return new instance
+}
+const serializationRegistry = new Map<Function, SerializationEntry<any>>();
+
+export function getSerializeFn<T extends object>(obj: T): ((obj: T | undefined, dumper: Dumper) => any) | undefined {
+  if (!obj) return undefined;
+
+  const entry = serializationRegistry.get(obj.constructor);
+  return entry?.serializeFn;
+}
+
+export function getDeserializeFn<T extends object>(obj: T): ((obj: T | undefined, loader: Loader) => void) | undefined {
+  if (!obj) return undefined;
+
+  const entry = serializationRegistry.get(obj.constructor);
+  return entry?.deserializeFn;
+}
+
+export function getStaticDeserializeFn(cls: string | undefined): ((data: any) => any) | undefined {
+  const constructor = cls ? getClassForDeserialization(cls) : undefined;
+  if (!constructor) return undefined;
+
+  const entry = serializationRegistry.get(constructor);
+  return entry?.staticDeserializeFn;
+}
+
+interface SpecializationOptions<T> {
+  cls: new (...args: any[]) => T;
+  serializeFn: (obj: T, dumper: Dumper) => void;
+  deserializeFn?: (obj: T, loader: Loader) => void;
+  staticDeserializeFn?: (data: any) => T;
+  clsAlias?: string;
+}
+
+export function registerSpecialization<T>(
+  options: SpecializationOptions<T>
+): void {
+  const { cls, serializeFn, deserializeFn, staticDeserializeFn, clsAlias } = options;
+  serializationRegistry.set(cls, { serializeFn, deserializeFn, staticDeserializeFn });
+
+  if (clsAlias) {
+    registerClassAlias(cls, clsAlias);
+  }
+}
+
+export const enum RegistrationFlags {
+  None = 0,
+  NoConstructor = 1 << 0,
+  NoDeserializer = 1 << 1,
+}
+
+interface RegisterSimpleTypeOptions<T> {
+  clsAlias?: string;
+  flags?: RegistrationFlags;
+}
+
+export function registerSimpleType<T>(
+  cls: new (...args: any[]) => T,
+  propertiesGetter: (o: T | Record<string, any>) => any[],
+  options?: RegisterSimpleTypeOptions<T>
+) {
+  const { clsAlias, flags } = options ?? {};
+  // this is just a cooler way to get property paths and set values
+  // asking user to pass in `o.x, o.y, o.z` instead of `['x', 'y', 'z']`, or `o.params.foo` instead of `['params.foo']` to avoid typos
+  const makePropertiesWriter = (obj: any) => {
+    const paths: (string | number | Symbol)[][] = [];
+    const createProxy = (target: any, currentPath: (string | number | Symbol)[] = []): any => {
+      return new Proxy(target, {
+        get(t, prop) {
+          const nextPath = [...currentPath, prop];
+          if (nextPath.length === 1) {
+            paths.push(nextPath);
+          }
+          const val = t[prop];
+          if (val !== null && typeof val === 'object') {
+            return createProxy(val, nextPath);
+          } else {
+            return val;
+          }
+        }
+      });
+    };
+
+    const proxy = createProxy(obj);
+    // get the values to populate the properties paths
+    const currentValues = propertiesGetter(proxy);
+
+    return (newValues: any[]) => {
+      paths.forEach((p, i) => {
+        let target = obj;
+        for (let j = 0; j < p.length - 1; j++) {
+          target = target[p[j] as string | number];
+        }
+        target[p[p.length - 1] as string | number] = newValues[i];
+      });
+    };
+  };
+
+  const effectiveFlags = flags ?? RegistrationFlags.None;
+  const defaultObject = getClassDefaultObject(cls);
+  registerSpecialization(
+    {
+      cls,
+      serializeFn: (obj: T, dumper: Dumper) => {
+        const dumpValues = propertiesGetter(obj);
+        if (defaultObject) {
+          const dumpDefaultValues = propertiesGetter(defaultObject);
+          if (JSON.stringify(dumpValues) === JSON.stringify(dumpDefaultValues)) {
+            // CAUTION: skip serializing default values by checking JSON.stringify equality
+            // This could cause issues if object properties are shared references
+            return;
+          }
+        }
+        dumper.dumpValue('_', dumpValues);
+      },
+      deserializeFn: (effectiveFlags & RegistrationFlags.NoDeserializer) ? undefined :
+        (obj: T, loader: Loader) => {
+          const values = loader.loadValue('_');
+          if (defaultObject && values === undefined) {
+            makePropertiesWriter(obj)(propertiesGetter(defaultObject));
+          } else {
+            makePropertiesWriter(obj)(values);
+          }
+        },
+      staticDeserializeFn: (effectiveFlags & RegistrationFlags.NoConstructor) ? undefined :
+        (data: any) => {
+          if (data._ === undefined) {
+            // suppose it can be constructed with no arguments
+            return new cls();
+          }
+          return new cls(...data._);
+        },
+      clsAlias
+    }
+  );
+}
+
+
+export function registerPropertyMetadata<T>(cls: new (...args: any[]) => T, metadata: Partial<Record<keyof T, PropertyMetadata>>): void {
+  Object.entries(metadata).forEach(
+    ([key, meta]) => property(meta as PropertyMetadata)(cls.prototype, key)
+  );
+}
+
+
+registerSpecialization({
+  cls: GlobalObjectRegistry,
+  serializeFn: (obj: GlobalObjectRegistry, dumper: Dumper) => {},  // unused, but serializer is not optional
+  staticDeserializeFn: (data: any) => {
+    const name = data['name'];
+    return GlobalObjectRegistry.getObjectByName(name);
+  },
+  clsAlias: GlobalObjectRegistry.NAME,
+});
+
+
+export function registerAsGlobalObject<T extends object>(name: string, factory: () => T): void {
+  GlobalObjectRegistry.registerFactory(name, () => {
+    const obj = factory();
+    if (obj && typeof obj === 'object' && !Array.isArray(obj)) {
+      // mark it as serializable
+      (obj as any)[ISerializableObjectTag] = true;
+      (obj as ISerializableObject).serialize = (dumper: Dumper) => {
+        dumper.dumpValue('name', name);
+      };
+    }
+    return obj;
+  });
+}

package/src/vfx/VFXComponent.ts

@@ -0,0 +1,206 @@
+/**
+ * VFXComponent wraps wawa-vfx-vanilla's VFXEmitter for use in the Genesys engine.
+ *
+ * This component loads VFX definitions from JSON and creates particle emitters.
+ * The VFXParticles system is managed globally, and emitters are attached to actors.
+ */
+import * as WawaVFX from 'wawa-vfx-vanilla';
+
+import { SceneComponent } from '../components/SceneComponent.js';
+import { AssetPath } from '../storage/storageProvider.js';
+import { EngineClass } from '../systems/ClassRegistry.js';
+import { AsyncTaskWorker, IAsyncLoadableTag } from '../utils/IAsyncLoadable.js';
+import { resourceManager } from '../utils/ResourceManager.js';
+
+import { VFXDefinition } from './types.js';
+
+type VFXEmitter = InstanceType<typeof WawaVFX.VFXEmitter>;
+
+import type { SceneComponentOptions } from '../components/SceneComponent.js';
+import type { EditorClassMeta } from '../utils/EditorClassMeta.js';
+import type { IAsyncLoadable } from '../utils/IAsyncLoadable.js';
+import type * as THREE from 'three';
+
+export interface VFXComponentOptions extends SceneComponentOptions {
+  /** Path to VFX JSON definition file */
+  vfxPath?: string;
+  /** Inline VFX definition (overrides vfxPath) */
+  vfxDefinition?: VFXDefinition;
+  /** Whether to start emitting automatically on begin play */
+  autoStart?: boolean;
+}
+
+@EngineClass('VFXComponent')
+export class VFXComponent extends SceneComponent<VFXComponentOptions> implements IAsyncLoadable {
+  readonly [IAsyncLoadableTag] = true;
+
+  private vfxEmitters: VFXEmitter[] = [];
+  private vfxDefinition: VFXDefinition | null = null;
+  private isPlaying: boolean = false;
+
+  private _asyncTaskWorker: AsyncTaskWorker = new AsyncTaskWorker();
+
+  static override readonly EDITOR_CLASS_META: EditorClassMeta = {
+    ...SceneComponent.EDITOR_CLASS_META,
+    vfxPath: { type: ['vfx'] },
+    vfxDefinition: { hidden: true }, //TODO: Make this editable in the editor
+  } as const;
+
+  static override get DEFAULT_OPTIONS(): VFXComponentOptions {
+    return {
+      ...SceneComponent.DEFAULT_OPTIONS,
+      vfxPath: '',
+      vfxDefinition: undefined,
+      autoStart: true,
+    };
+  }
+
+  constructor(options: VFXComponentOptions = {}) {
+    super(options);
+
+    if (options.vfxPath) {
+      this.loadVFXDefinition(options.vfxPath);
+    } else if (options.vfxDefinition) {
+      this.vfxDefinition = options.vfxDefinition;
+      // Create emitter async (will be ready by beginPlay)
+      this.createVFXEmitter();
+    }
+  }
+
+  // start IAsyncLoadable implementation
+  public async waitForLoad(): Promise<void> {
+    await this._asyncTaskWorker.waitUntilComplete();
+  }
+
+  public isLoading(): boolean {
+    return this._asyncTaskWorker.isRunning();
+  }
+  // end IAsyncLoadable implementation
+
+  private async loadVFXDefinition(path: string): Promise<void> {
+    try {
+      const json = await resourceManager.loadJsonObject(new AssetPath(path));
+      this.vfxDefinition = VFXDefinition.fromJSON(json);
+      await this.createVFXEmitter();
+    } catch (error) {
+      console.error(`Failed to load VFX definition from ${path}:`, error);
+    }
+  }
+
+  private async createVFXEmitter(): Promise<void> {
+    this._asyncTaskWorker.runTask(async () => {
+      if (!this.vfxDefinition) return;
+
+      const world = this.getWorld();
+      if (!world) {
+        console.warn('VFXComponent: Cannot create emitter without world');
+        return;
+      }
+
+      const particleManager = world.globalParticleManager;
+
+      // Create all particle systems
+      for (let i = 0; i < this.vfxDefinition.particles.length; i++) {
+        const particleSettings = this.vfxDefinition.particles[i];
+        const particleName = `${this.vfxDefinition.name}_particles_${i}`;
+        await particleManager.getOrCreateVFXParticles(particleName, particleSettings);
+      }
+
+      // Create all emitters
+      this.vfxEmitters = [];
+      for (let i = 0; i < this.vfxDefinition.emitters.length; i++) {
+        const emitterSettings = this.vfxDefinition.emitters[i];
+        const particlesIndex = emitterSettings.particlesIndex ?? 0;
+        const particleName = `${this.vfxDefinition.name}_particles_${particlesIndex}`;
+
+        const emitter = new WawaVFX.VFXEmitter(
+          particleName,
+          emitterSettings,
+          particleManager.getVFXStore()
+        );
+
+        this.add(emitter);
+        this.vfxEmitters.push(emitter);
+      }
+    });
+  }
+
+  public override beginPlay(): void {
+    super.beginPlay();
+
+    if (this.options.autoStart) {
+      this._asyncTaskWorker.waitUntilComplete().then(() => {
+        this.startEmitting();
+      });
+    }
+  }
+
+  public override tickPrePhysics(deltaTime: number): void {
+    super.tickPrePhysics(deltaTime);
+
+    if (this.isPlaying) {
+      const elapsedTime = this.getWorld()?.getGameTime() ?? 0;
+      for (const emitter of this.vfxEmitters) {
+        emitter.update(elapsedTime, deltaTime);
+      }
+    }
+  }
+
+  public override endPlay(): void {
+    this.stopEmitting();
+    super.endPlay();
+  }
+
+  /**
+   * Start emitting particles
+   */
+  public startEmitting(reset: boolean = true): void {
+    for (const emitter of this.vfxEmitters) {
+      emitter.startEmitting(reset);
+    }
+    this.isPlaying = true;
+  }
+
+  /**
+   * Stop emitting particles
+   */
+  public stopEmitting(): void {
+    for (const emitter of this.vfxEmitters) {
+      emitter.stopEmitting();
+    }
+    this.isPlaying = false;
+  }
+
+  /**
+   * Emit particles at a specific position (all emitters)
+   */
+  public emitAtPosition(position: THREE.Vector3, reset: boolean = false): void {
+    for (const emitter of this.vfxEmitters) {
+      emitter.emitAtPos(position, reset);
+    }
+  }
+
+  /**
+   * Get all VFXEmitter instances
+   */
+  public getVFXEmitters(): VFXEmitter[] {
+    return this.vfxEmitters;
+  }
+
+  /**
+   * Get a specific VFXEmitter by index
+   */
+  public getVFXEmitter(index: number): VFXEmitter | null {
+    return this.vfxEmitters[index] ?? null;
+  }
+
+  /**
+   * Get the VFX definition
+   */
+  public getVFXDefinition(): VFXDefinition | null {
+    return this.vfxDefinition;
+  }
+
+}
+
+

package/src/vfx/index.ts

@@ -0,0 +1,17 @@
+/**
+ * VFX module exports for wawa-vfx-vanilla integration.
+ */
+import * as WawaVFX from 'wawa-vfx-vanilla';
+
+export * from './types.js';
+export * from './VFXComponent.js';
+
+// Re-export wawa-vfx-vanilla values for convenience
+export const VFXParticles = WawaVFX.VFXParticles;
+export const VFXEmitter = WawaVFX.VFXEmitter;
+export const AppearanceMode = WawaVFX.AppearanceMode;
+
+// Type exports derived from the runtime values
+export type VFXParticlesType = InstanceType<typeof WawaVFX.VFXParticles>;
+export type VFXEmitterType = InstanceType<typeof WawaVFX.VFXEmitter>;
+