@vgai/engine 0.2.0

package/src/scene/particles-factory.ts

@@ -0,0 +1,383 @@
+// biome-ignore-all lint/suspicious/noExplicitAny: quarks' API uses untyped FunctionJSON internally; our Zod types are structurally compatible but TS can't unify them
+/**
+ * Converts SceneParticles JSON → three.quarks ParticleSystem.
+ *
+ * Shared between the editor entity-factory and the runtime scene-loader.
+ * The schema mirrors quarks' native JSON format, so most fields pass through
+ * directly to quarks' fromJSON or constructor methods.
+ */
+
+import {
+  ApplyForce,
+  ChangeEmitDirection,
+  CircleEmitter,
+  ColorGeneratorFromJSON,
+  ColorOverLife,
+  ConeEmitter,
+  DonutEmitter,
+  ForceOverLife,
+  FrameOverLife,
+  GravityForce,
+  GridEmitter,
+  HemisphereEmitter,
+  LimitSpeedOverLife,
+  Noise,
+  OrbitOverLife,
+  PointEmitter,
+  Vector3 as QVector3,
+  RectangleEmitter,
+  RotationOverLife,
+  SizeOverLife,
+  SpeedOverLife,
+  SphereEmitter,
+  TurbulenceField,
+  ValueGeneratorFromJSON,
+  WidthOverLength,
+} from 'quarks.core';
+import * as THREE from 'three';
+import { type BatchedRenderer, ParticleSystem, RenderMode } from 'three.quarks';
+import type { SceneParticles } from './scene-types';
+import type {
+  BehaviorJSON,
+  ColorGeneratorJSON,
+  EmitterShapeJSON,
+  ValueGeneratorJSON,
+} from './schema/particles';
+
+// --- Render mode mapping ---
+
+const RENDER_MODE_MAP: Record<string, RenderMode> = {
+  billboard: RenderMode.BillBoard,
+  stretchedBillboard: RenderMode.StretchedBillBoard,
+  mesh: RenderMode.Mesh,
+  trail: RenderMode.Trail,
+  horizontalBillboard: RenderMode.HorizontalBillBoard,
+  verticalBillboard: RenderMode.VerticalBillBoard,
+};
+
+// --- Texture loader (shared cache) ---
+
+import { textureLoader } from '../loader';
+
+const particleTexCache = new Map<string, THREE.Texture>();
+
+function loadParticleTexture(url: string): THREE.Texture {
+  const cached = particleTexCache.get(url);
+  if (cached) return cached;
+  const tex = textureLoader.load(url);
+  particleTexCache.set(url, tex);
+  return tex;
+}
+
+// --- Helpers ---
+
+/** Strip keys with undefined values so exactOptionalPropertyTypes is satisfied. */
+function defined(obj: Record<string, any>): any {
+  const result: Record<string, unknown> = {};
+  for (const [k, v] of Object.entries(obj)) {
+    if (v !== undefined) result[k] = v;
+  }
+  return result;
+}
+
+// --- Emitter shape ---
+
+function createEmitterShape(json: EmitterShapeJSON) {
+  switch (json.type) {
+    case 'point':
+      return new PointEmitter();
+    case 'sphere':
+      return new SphereEmitter(
+        defined({ radius: json.radius, arc: json.arc, thickness: json.thickness }),
+      );
+    case 'hemisphere':
+      return new HemisphereEmitter(
+        defined({ radius: json.radius, arc: json.arc, thickness: json.thickness }),
+      );
+    case 'cone':
+      return new ConeEmitter(
+        defined({
+          radius: json.radius,
+          arc: json.arc,
+          thickness: json.thickness,
+          angle: json.angle,
+        }),
+      );
+    case 'circle':
+      return new CircleEmitter(
+        defined({ radius: json.radius, arc: json.arc, thickness: json.thickness }),
+      );
+    case 'donut':
+      return new DonutEmitter(
+        defined({
+          radius: json.radius,
+          arc: json.arc,
+          thickness: json.thickness,
+          donutRadius: json.donutRadius,
+        }),
+      );
+    case 'rectangle':
+      return new RectangleEmitter(
+        defined({ width: json.width, height: json.height, thickness: json.thickness }),
+      );
+    case 'grid':
+      return new GridEmitter(
+        defined({ width: json.width, height: json.height, column: json.column, row: json.row }),
+      );
+  }
+}
+
+// --- Value / Color generators ---
+// Our Zod-inferred types are structurally identical to quarks' FunctionJSON
+// but TypeScript can't unify them, so we cast through the untyped bridge.
+
+function valueGen(json: ValueGeneratorJSON) {
+  return ValueGeneratorFromJSON(json as any);
+}
+
+function colorGen(json: ColorGeneratorJSON) {
+  return ColorGeneratorFromJSON(json as any);
+}
+
+// --- Behaviors ---
+
+function createBehavior(json: BehaviorJSON): any {
+  switch (json.type) {
+    case 'ApplyForce':
+      return new ApplyForce(
+        new QVector3(json.direction[0], json.direction[1], json.direction[2]),
+        valueGen(json.magnitude) as any,
+      );
+    case 'ColorOverLife':
+      return new ColorOverLife(colorGen(json.color) as any);
+    case 'SizeOverLife':
+      return new SizeOverLife(valueGen(json.size) as any);
+    case 'SpeedOverLife':
+      return new SpeedOverLife(valueGen(json.speed) as any);
+    case 'RotationOverLife':
+      return new RotationOverLife(valueGen(json.angularVelocity) as any);
+    case 'ForceOverLife':
+      return new ForceOverLife(
+        valueGen(json.x) as any,
+        valueGen(json.y) as any,
+        valueGen(json.z) as any,
+      );
+    case 'OrbitOverLife':
+      return new OrbitOverLife(
+        valueGen(json.orbitSpeed) as any,
+        json.axis ? new QVector3(json.axis[0], json.axis[1], json.axis[2]) : undefined,
+      );
+    case 'Noise':
+      return new Noise(
+        valueGen(json.frequency) as any,
+        valueGen(json.power) as any,
+        json.positionAmount ? (valueGen(json.positionAmount) as any) : undefined,
+        json.rotationAmount ? (valueGen(json.rotationAmount) as any) : undefined,
+      );
+    case 'TurbulenceField':
+      return new TurbulenceField(
+        new QVector3(json.scale[0], json.scale[1], json.scale[2]),
+        json.octaves,
+        new QVector3(
+          json.velocityMultiplier[0],
+          json.velocityMultiplier[1],
+          json.velocityMultiplier[2],
+        ),
+        new QVector3(json.timeScale[0], json.timeScale[1], json.timeScale[2]),
+      );
+    case 'FrameOverLife':
+      return new FrameOverLife(valueGen(json.frame) as any);
+    case 'LimitSpeedOverLife':
+      return new LimitSpeedOverLife(valueGen(json.speed) as any, json.dampen);
+    case 'ChangeEmitDirection':
+      return new ChangeEmitDirection(valueGen(json.angle) as any);
+    case 'GravityForce':
+      return new GravityForce(
+        new QVector3(json.center[0], json.center[1], json.center[2]),
+        json.magnitude,
+      );
+    case 'WidthOverLength':
+      return new WidthOverLength(valueGen(json.width) as any);
+  }
+}
+
+// --- Material ---
+
+function createParticleMaterial(mat: SceneParticles['material']): THREE.Material {
+  const textures: Record<string, THREE.Texture> = {};
+  if (mat.map) textures['map'] = loadParticleTexture(mat.map);
+
+  const blending = mat.blending === 'normal' ? THREE.NormalBlending : THREE.AdditiveBlending;
+  const transparent = mat.transparent !== false;
+  const depthWrite = mat.depthWrite ?? false;
+  const side =
+    mat.side === 'back'
+      ? THREE.BackSide
+      : mat.side === 'double'
+        ? THREE.DoubleSide
+        : THREE.FrontSide;
+
+  if (mat.type === 'standard') {
+    return new THREE.MeshStandardMaterial({
+      color: mat.color ?? '#ffffff',
+      ...textures,
+      blending,
+      transparent,
+      depthWrite,
+      side,
+    });
+  }
+
+  return new THREE.MeshBasicMaterial({
+    color: mat.color ?? '#ffffff',
+    ...textures,
+    blending,
+    transparent,
+    depthWrite,
+    side,
+  });
+}
+
+// --- Default sprite texture (soft radial gradient) ---
+
+let _defaultSpriteTex: THREE.Texture | null = null;
+
+function getDefaultSpriteTex(): THREE.Texture {
+  if (_defaultSpriteTex) return _defaultSpriteTex;
+  const canvas = document.createElement('canvas');
+  canvas.width = 16;
+  canvas.height = 16;
+  const c2d = canvas.getContext('2d')!;
+  const grad = c2d.createRadialGradient(8, 8, 0, 8, 8, 8);
+  grad.addColorStop(0, 'rgba(255,255,255,1)');
+  grad.addColorStop(1, 'rgba(255,255,255,0)');
+  c2d.fillStyle = grad;
+  c2d.fillRect(0, 0, 16, 16);
+  _defaultSpriteTex = new THREE.CanvasTexture(canvas);
+  return _defaultSpriteTex;
+}
+
+// --- Public API ---
+
+export interface ParticleSystemResult {
+  /** The emitter Object3D (add to scene for transform) */
+  emitter: THREE.Object3D;
+  /** The ParticleSystem instance (register with BatchedRenderer) */
+  system: ParticleSystem;
+}
+
+/**
+ * Create a three.quarks ParticleSystem from SceneParticles JSON data.
+ */
+// biome-ignore lint/complexity/noExcessiveCognitiveComplexity: straightforward field-by-field mapping
+export function createParticleSystemFromData(data: SceneParticles): ParticleSystemResult {
+  const material = createParticleMaterial(data.material);
+
+  // Apply default sprite if no texture specified
+  if (!data.material.map && 'map' in material) {
+    (material as THREE.MeshBasicMaterial).map = getDefaultSpriteTex();
+  }
+
+  // Build params, strip undefined keys for exactOptionalPropertyTypes compat
+  const params: Record<string, unknown> = { material };
+
+  if (data.autoDestroy != null) params['autoDestroy'] = data.autoDestroy;
+  if (data.looping != null) params['looping'] = data.looping;
+  if (data.prewarm != null) params['prewarm'] = data.prewarm;
+  if (data.duration != null) params['duration'] = data.duration;
+  if (data.shape) params['shape'] = createEmitterShape(data.shape);
+
+  if (data.startLife) params['startLife'] = valueGen(data.startLife);
+  if (data.startSpeed) params['startSpeed'] = valueGen(data.startSpeed);
+  if (data.startSize) params['startSize'] = valueGen(data.startSize);
+  if (data.startRotation) params['startRotation'] = valueGen(data.startRotation);
+  if (data.startColor) params['startColor'] = colorGen(data.startColor);
+  if (data.startTileIndex) params['startTileIndex'] = valueGen(data.startTileIndex);
+
+  // Trail mode requires startLength inside rendererEmitterSettings, not as a top-level param
+  if (data.renderMode === 'trail' && data.startLength) {
+    params['rendererEmitterSettings'] = { startLength: valueGen(data.startLength) };
+  }
+
+  if (data.emissionOverTime) params['emissionOverTime'] = valueGen(data.emissionOverTime);
+  if (data.emissionOverDistance)
+    params['emissionOverDistance'] = valueGen(data.emissionOverDistance);
+  if (data.emissionBursts) {
+    params['emissionBursts'] = data.emissionBursts.map((b) => ({
+      time: b.time,
+      count: valueGen(b.count),
+      cycle: b.cycle ?? 1,
+      interval: b.interval ?? 0,
+      probability: b.probability ?? 1,
+    }));
+  }
+
+  if (data.behaviors) params['behaviors'] = data.behaviors.map(createBehavior);
+  if (data.renderMode != null) params['renderMode'] = RENDER_MODE_MAP[data.renderMode];
+  if (data.worldSpace != null) params['worldSpace'] = data.worldSpace;
+  if (data.renderOrder != null) params['renderOrder'] = data.renderOrder;
+  if (data.uTileCount != null) params['uTileCount'] = data.uTileCount;
+  if (data.vTileCount != null) params['vTileCount'] = data.vTileCount;
+  if (data.blendTiles != null) params['blendTiles'] = data.blendTiles;
+  if (data.softParticles != null) params['softParticles'] = data.softParticles;
+  if (data.softFarFade != null) params['softFarFade'] = data.softFarFade;
+  if (data.softNearFade != null) params['softNearFade'] = data.softNearFade;
+
+  const ps = new ParticleSystem(params as any);
+
+  return { emitter: ps.emitter, system: ps };
+}
+
+/**
+ * Register a particle system with a BatchedRenderer.
+ */
+export function registerParticleSystem(
+  batchedRenderer: BatchedRenderer,
+  system: ParticleSystem,
+): void {
+  batchedRenderer.addSystem(system);
+}
+
+/**
+ * Unregister a particle system from a BatchedRenderer.
+ */
+export function unregisterParticleSystem(
+  batchedRenderer: BatchedRenderer,
+  system: ParticleSystem,
+): void {
+  batchedRenderer.deleteSystem(system);
+}
+
+/**
+ * Default particle data for creating a new particle emitter via AddSectionMenu.
+ */
+export function defaultParticlesData(): SceneParticles {
+  return {
+    looping: true,
+    duration: 2,
+    shape: { type: 'cone', radius: 0.1, angle: 0.3 },
+    startLife: { type: 'IntervalValue', a: 0.5, b: 1.5 },
+    startSpeed: { type: 'IntervalValue', a: 1, b: 3 },
+    startSize: { type: 'IntervalValue', a: 0.05, b: 0.15 },
+    startColor: {
+      type: 'ConstantColor',
+      color: { r: 1, g: 0.8, b: 0.2, a: 1 },
+    },
+    emissionOverTime: { type: 'ConstantValue', value: 30 },
+    behaviors: [
+      {
+        type: 'SizeOverLife',
+        size: {
+          type: 'PiecewiseBezier',
+          functions: [{ function: { p0: 1, p1: 0.67, p2: 0.33, p3: 0 }, start: 0 }],
+        },
+      },
+    ],
+    material: {
+      type: 'basic',
+      blending: 'additive',
+      transparent: true,
+      depthWrite: false,
+    },
+  };
+}