@fps-games/vfx 0.1.1

package/packages/manifestRuntimePackage.ts

@@ -0,0 +1,519 @@
+import { Engine } from '@babylonjs/core/Engines/engine';
+import { Color3, Color4 } from '@babylonjs/core/Maths/math.color';
+import { Vector3 } from '@babylonjs/core/Maths/math.vector';
+import { Material } from '@babylonjs/core/Materials/material';
+import { MaterialPluginBase } from '@babylonjs/core/Materials/materialPluginBase';
+import { PBRMaterial } from '@babylonjs/core/Materials/PBR/pbrMaterial';
+import { DynamicTexture } from '@babylonjs/core/Materials/Textures/dynamicTexture';
+import { Texture } from '@babylonjs/core/Materials/Textures/texture';
+import { StandardMaterial } from '@babylonjs/core/Materials/standardMaterial';
+import { CreateBox } from '@babylonjs/core/Meshes/Builders/boxBuilder';
+import { CreateCylinder } from '@babylonjs/core/Meshes/Builders/cylinderBuilder';
+import { CreateDisc } from '@babylonjs/core/Meshes/Builders/discBuilder';
+import { CreatePlane } from '@babylonjs/core/Meshes/Builders/planeBuilder';
+import { CreateTube } from '@babylonjs/core/Meshes/Builders/tubeBuilder';
+import { Mesh } from '@babylonjs/core/Meshes/mesh';
+import { VertexData } from '@babylonjs/core/Meshes/mesh.vertexData';
+import { TransformNode } from '@babylonjs/core/Meshes/transformNode';
+import { ParticleSystem } from '@babylonjs/core/Particles/particleSystem';
+import { SolidParticleSystem } from '@babylonjs/core/Particles/solidParticleSystem';
+import { SceneLoader } from '@babylonjs/core/Loading/sceneLoader';
+import type { Scene } from '@babylonjs/core/scene';
+
+import type {
+  VfxColorValue,
+  VfxDebugAnchor,
+  VfxEffectHandle,
+  VfxEffectPackage,
+  VfxEffectPackageContext,
+  VfxParamDefinition,
+  VfxParamValue,
+  VfxParamValues,
+} from './types';
+
+type LegacyTunableParamType = 'number' | 'color' | 'enum' | string;
+
+interface LegacyTunableTarget {
+  emitter: string;
+  property: string;
+  operator?: string;
+  defaultValue?: unknown;
+}
+
+interface LegacyTunableParam {
+  key: string;
+  label?: string;
+  labelEn?: string;
+  labelZh?: string;
+  type: LegacyTunableParamType;
+  default?: unknown;
+  min?: number;
+  max?: number;
+  step?: number;
+  options?: Array<{ value: string; label?: string }>;
+  target?: LegacyTunableTarget;
+  targets?: LegacyTunableTarget[];
+}
+
+interface LegacyEmitterConfig {
+  name: string;
+  enabled?: boolean;
+  runtime?: {
+    adapter?: string;
+    stopAfterSeconds?: number;
+    disposeOnComplete?: boolean;
+  };
+  [key: string]: unknown;
+}
+
+interface LegacyRuntimeAdapterConfig {
+  id: string;
+  entry: string;
+  moduleFormat?: string;
+  exports?: string[];
+}
+
+interface LegacyEffectManifest {
+  id?: string;
+  name?: {
+    en?: string;
+    zh?: string;
+  };
+  assets?: Record<string, unknown> | unknown[];
+  source?: unknown;
+  emitters?: LegacyEmitterConfig[];
+  runtime?: {
+    driver?: string;
+    adapters?: LegacyRuntimeAdapterConfig[];
+  };
+  tunableParams?: LegacyTunableParam[];
+  defaultParams?: Record<string, unknown>;
+  debug?: {
+    playAnchor?: string;
+    livePreview?: boolean;
+  };
+}
+
+type RuntimePreview = {
+  start?: () => void;
+  stop?: () => void;
+  dispose?: () => void;
+  isStarted?: () => boolean;
+  setPosition?: (position: Vector3) => void;
+  setScaling?: (scaling: Vector3) => void;
+};
+
+const BABYLON_RUNTIME_API = {
+  Color3,
+  Color4,
+  DynamicTexture,
+  Engine,
+  Material,
+  MaterialPluginBase,
+  Mesh,
+  MeshBuilder: {
+    CreateBox,
+    CreateCylinder,
+    CreateDisc,
+    CreatePlane,
+    CreateTube,
+  },
+  PBRMaterial,
+  ParticleSystem,
+  SceneLoader,
+  SolidParticleSystem,
+  StandardMaterial,
+  Texture,
+  TransformNode,
+  Vector3,
+  VertexData,
+} as const;
+
+export interface ManifestRuntimeEffectPackageOptions {
+  id: string;
+  manifest: LegacyEffectManifest;
+  assetUrls: Record<string, string>;
+}
+
+export function createManifestRuntimeEffectPackage(options: ManifestRuntimeEffectPackageOptions): VfxEffectPackage {
+  const { id, manifest, assetUrls } = options;
+  return {
+    id,
+    nameZh: manifest.name?.zh ?? manifest.name?.en ?? id,
+    manifest: {
+      id: manifest.id ?? id,
+      nameZh: manifest.name?.zh ?? manifest.name?.en ?? id,
+      assets: collectManifestAssetPaths(manifest),
+      source: readManifestSource(manifest),
+    },
+    defaultParams: buildDefaultParams(manifest),
+    debugAnchor: normalizeDebugAnchor(manifest.debug?.playAnchor),
+    debugParams: buildDebugParams(manifest),
+    create(context) {
+      return createManifestRuntimeHandle(context, manifest, assetUrls, id);
+    },
+  };
+}
+
+function createManifestRuntimeHandle(
+  context: VfxEffectPackageContext,
+  manifest: LegacyEffectManifest,
+  assetUrls: Record<string, string>,
+  effectId: string,
+): VfxEffectHandle {
+  const root = context.root;
+  const previews: RuntimePreview[] = [];
+  const cleanupCallbacks: Array<() => void> = [];
+  let disposed = false;
+
+  const ready = startRuntimePreviews().catch((error) => {
+    console.warn(`[VFX] Failed to play effect package "${effectId}".`, error);
+  });
+
+  return {
+    root,
+    ready,
+    dispose() {
+      disposed = true;
+      for (const cleanup of cleanupCallbacks.splice(0)) cleanup();
+      for (const preview of previews.splice(0)) {
+        preview.stop?.();
+        preview.dispose?.();
+      }
+      disposeRoot(root);
+    },
+  };
+
+  async function startRuntimePreviews(): Promise<void> {
+    const emitters = (manifest.emitters ?? [])
+      .filter((emitter) => emitter.enabled !== false)
+      .map(cloneEmitter);
+
+    for (const [index, emitter] of emitters.entries()) {
+      if (disposed) return;
+      applyTunableValues(emitter, manifest.tunableParams ?? [], context.params);
+      emitter.origin = {
+        x: context.position.x,
+        y: context.position.y,
+        z: context.position.z,
+      };
+      emitter.rotationY = root.rotation.y;
+      const preview = await playEmitter(manifest, emitter, assetUrls, index, effectId, context.scene);
+      if (!preview) continue;
+      if (disposed) {
+        preview.stop?.();
+        preview.dispose?.();
+        continue;
+      }
+      syncPreviewPosition(context, preview, cleanupCallbacks);
+      previews.push(preview);
+    }
+  }
+}
+
+function syncPreviewPosition(
+  context: VfxEffectPackageContext,
+  preview: RuntimePreview,
+  cleanupCallbacks: Array<() => void>,
+): void {
+  if (typeof preview.setPosition !== 'function') return;
+  preview.setPosition(context.root.getAbsolutePosition());
+  const observer = context.scene.onBeforeRenderObservable.add(() => {
+    preview.setPosition?.(context.root.getAbsolutePosition());
+    preview.setScaling?.(context.root.scaling);
+  });
+  cleanupCallbacks.push(() => {
+    context.scene.onBeforeRenderObservable.remove(observer);
+  });
+}
+
+async function playEmitter(
+  manifest: LegacyEffectManifest,
+  emitter: LegacyEmitterConfig,
+  assetUrls: Record<string, string>,
+  index: number,
+  effectId: string,
+  scene: Scene,
+): Promise<RuntimePreview | null> {
+  const adapterId = resolveEmitterAdapterId(manifest, emitter);
+  if (!adapterId) {
+    console.warn(`[VFX] Missing runtime adapter for ${effectId}/${emitter.name}`);
+    return null;
+  }
+
+  const adapter = manifest.runtime?.adapters?.find((item) => item.id === adapterId)
+    ?? manifest.runtime?.adapters?.[0];
+  if (!adapter) {
+    console.warn(`[VFX] Adapter "${adapterId}" is not registered in ${effectId}`);
+    return null;
+  }
+
+  const adapterUrl = assetUrls[adapter.entry];
+  if (!adapterUrl) {
+    console.warn(`[VFX] Missing runtime asset "${adapter.entry}" for ${effectId}`);
+    return null;
+  }
+
+  const runtimeModule = await import(/* @vite-ignore */ adapterUrl) as Record<string, unknown>;
+  const createRuntimeName = adapter.exports?.find((name) => name.startsWith('create'))
+    ?? getRuntimeFactoryName(adapter.id);
+  const createRuntime = runtimeModule[createRuntimeName];
+  if (typeof createRuntime !== 'function') {
+    console.warn(`[VFX] Runtime "${adapter.id}" does not export "${createRuntimeName}"`);
+    return null;
+  }
+
+  return await createRuntime({
+    BABYLON: BABYLON_RUNTIME_API,
+    scene,
+    emitter,
+    index,
+    shouldStart: true,
+    urlForPackagePath: (packagePath: string) => assetUrls[packagePath] ?? packagePath,
+  }) as RuntimePreview;
+}
+
+function resolveEmitterAdapterId(manifest: LegacyEffectManifest, emitter: LegacyEmitterConfig): string | undefined {
+  const runtimeAdapter = emitter.runtime?.adapter;
+  if (runtimeAdapter) return runtimeAdapter;
+  const adapters = manifest.runtime?.adapters ?? [];
+  if (adapters.length === 1) return adapters[0].id;
+  if (manifest.runtime?.driver === 'solidParticleScatter') return 'solidParticleScatter/v1';
+  if (manifest.runtime?.driver === 'particle') return 'particleEmitter/v1';
+  return adapters[0]?.id;
+}
+
+function getRuntimeFactoryName(adapterId: string): string {
+  if (adapterId === 'solidParticleScatter/v1') return 'createSolidParticleScatterRuntime';
+  if (adapterId === 'particleEmitter/v1') return 'createParticleEmitterRuntime';
+  if (adapterId === 'gearSpin/v1') return 'createGearSpinRuntime';
+  if (adapterId === 'goldFlakes/v1') return 'createGoldFlakesRuntime';
+  if (adapterId === 'upgradeAura/v1') return 'createUpgradeAuraRuntime';
+  if (adapterId === 'woodPeelMaterialTest/v1') return 'createWoodPeelMaterialTestRuntime';
+  if (adapterId === 'simpleMeshEffect/v1') return 'createSimpleMeshEffectRuntime';
+  return 'createVfxRuntime';
+}
+
+function applyTunableValues(
+  emitter: LegacyEmitterConfig,
+  params: LegacyTunableParam[],
+  values: VfxParamValues,
+): void {
+  for (const param of params) {
+    if (!(param.key in values)) continue;
+    const targets = param.targets ?? (param.target ? [param.target] : []);
+    for (const target of targets) {
+      if (target.emitter !== emitter.name) continue;
+      applyTunableTarget(emitter, target, values[param.key]);
+    }
+  }
+}
+
+function applyTunableTarget(emitter: LegacyEmitterConfig, target: LegacyTunableTarget, value: VfxParamValue): void {
+  const operator = target.operator ?? 'set';
+  if (operator === 'set') {
+    setNestedValue(emitter, target.property, normalizeTunableValue(emitter, target.property, value));
+    return;
+  }
+
+  if (operator === 'scaleDefault') {
+    const multiplier = Number(value);
+    const baseValue = Number(target.defaultValue ?? getNestedValue(emitter, target.property));
+    if (!Number.isFinite(multiplier) || !Number.isFinite(baseValue)) return;
+    setNestedValue(emitter, target.property, baseValue * multiplier);
+    return;
+  }
+
+  if (operator === 'scaleVectorDefault') {
+    const multiplier = Number(value);
+    if (!Number.isFinite(multiplier)) return;
+    setNestedValue(emitter, target.property, scaleVectorDefaultValue(target.defaultValue, multiplier));
+  }
+}
+
+function scaleVectorDefaultValue(defaultValue: unknown, multiplier: number): unknown {
+  if (!defaultValue || typeof defaultValue !== 'object' || Array.isArray(defaultValue)) return defaultValue;
+
+  const source = defaultValue as { x?: unknown; y?: unknown; z?: unknown; scaleAxes?: unknown };
+  const scaleAxes = source.scaleAxes && typeof source.scaleAxes === 'object' && !Array.isArray(source.scaleAxes)
+    ? source.scaleAxes as Record<string, unknown>
+    : { x: true, y: true, z: true };
+
+  const scaleComponent = (axis: 'x' | 'y' | 'z') => {
+    const base = Number(source[axis] ?? 0);
+    if (!Number.isFinite(base)) return 0;
+    return scaleAxes[axis] === false ? base : base * multiplier;
+  };
+
+  return {
+    x: scaleComponent('x'),
+    y: scaleComponent('y'),
+    z: scaleComponent('z'),
+  };
+}
+
+function setNestedValue(target: Record<string, unknown>, path: string, value: unknown): void {
+  const parts = path.split('.').filter(Boolean);
+  if (parts.length === 0) return;
+
+  let cursor: Record<string, unknown> = target;
+  for (const part of parts.slice(0, -1)) {
+    const next = cursor[part];
+    if (!next || typeof next !== 'object' || Array.isArray(next)) {
+      cursor[part] = {};
+    }
+    cursor = cursor[part] as Record<string, unknown>;
+  }
+
+  cursor[parts[parts.length - 1]] = value;
+}
+
+function normalizeTunableValue(emitter: LegacyEmitterConfig, path: string, value: VfxParamValue): unknown {
+  if (isColorValue(value)) {
+    return {
+      r: value.r,
+      g: value.g,
+      b: value.b,
+      a: readExistingAlpha(emitter, path),
+    };
+  }
+
+  if (typeof value !== 'string' || !/^#[0-9a-f]{6}$/i.test(value)) return value;
+
+  const alpha = readExistingAlpha(emitter, path);
+
+  return {
+    r: parseInt(value.slice(1, 3), 16) / 255,
+    g: parseInt(value.slice(3, 5), 16) / 255,
+    b: parseInt(value.slice(5, 7), 16) / 255,
+    a: alpha,
+  };
+}
+
+function readExistingAlpha(emitter: LegacyEmitterConfig, path: string): number {
+  const existing = getNestedValue(emitter, path);
+  const alpha = existing && typeof existing === 'object' && 'a' in existing
+    ? Number((existing as { a?: unknown }).a)
+    : 1;
+  return Number.isFinite(alpha) ? alpha : 1;
+}
+
+function getNestedValue(target: Record<string, unknown>, path: string): unknown {
+  let cursor: unknown = target;
+  for (const part of path.split('.').filter(Boolean)) {
+    if (!cursor || typeof cursor !== 'object' || Array.isArray(cursor)) return undefined;
+    cursor = (cursor as Record<string, unknown>)[part];
+  }
+  return cursor;
+}
+
+function buildDefaultParams(manifest: LegacyEffectManifest): VfxParamValues {
+  const params: VfxParamValues = {};
+  for (const [key, value] of Object.entries(manifest.defaultParams ?? {})) {
+    if (isVfxParamValue(value)) params[key] = value;
+  }
+  for (const param of manifest.tunableParams ?? []) {
+    if (param.default !== undefined && isVfxParamValue(param.default)) {
+      params[param.key] = param.default;
+    }
+  }
+  return params;
+}
+
+function buildDebugParams(manifest: LegacyEffectManifest): VfxParamDefinition[] {
+  const result: VfxParamDefinition[] = [];
+  for (const param of manifest.tunableParams ?? []) {
+    const label = param.labelZh ?? param.label ?? param.labelEn ?? param.key;
+    if (param.type === 'number') {
+      result.push({
+        key: param.key,
+        label,
+        kind: 'number',
+        min: param.min,
+        max: param.max,
+        step: param.step,
+      });
+      continue;
+    }
+    if (param.type === 'color') {
+      result.push({
+        key: param.key,
+        label,
+        kind: 'color',
+      });
+      continue;
+    }
+    if (param.type === 'enum' && Array.isArray(param.options)) {
+      result.push({
+        key: param.key,
+        label,
+        kind: 'enum',
+        options: param.options.map((option) => ({
+          value: option.value,
+          label: option.label ?? option.value,
+        })),
+      });
+    }
+  }
+  return result;
+}
+
+function isVfxParamValue(value: unknown): value is VfxParamValue {
+  if (typeof value === 'number') return Number.isFinite(value);
+  if (typeof value === 'string') return true;
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return false;
+  const color = value as Record<string, unknown>;
+  return typeof color.r === 'number'
+    && Number.isFinite(color.r)
+    && typeof color.g === 'number'
+    && Number.isFinite(color.g)
+    && typeof color.b === 'number'
+    && Number.isFinite(color.b);
+}
+
+function isColorValue(value: unknown): value is VfxColorValue {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return false;
+  const color = value as Record<string, unknown>;
+  return typeof color.r === 'number'
+    && Number.isFinite(color.r)
+    && typeof color.g === 'number'
+    && Number.isFinite(color.g)
+    && typeof color.b === 'number'
+    && Number.isFinite(color.b);
+}
+
+function normalizeDebugAnchor(value: string | undefined): VfxDebugAnchor | undefined {
+  return value === 'player' || value === 'playerRight' ? value : undefined;
+}
+
+function collectManifestAssetPaths(manifest: LegacyEffectManifest): string[] {
+  const paths: string[] = [];
+  const collect = (value: unknown): void => {
+    if (Array.isArray(value)) {
+      for (const item of value) collect(item);
+      return;
+    }
+    if (!value || typeof value !== 'object') return;
+    const record = value as Record<string, unknown>;
+    if (typeof record.packagePath === 'string') paths.push(record.packagePath);
+    for (const child of Object.values(record)) collect(child);
+  };
+  collect(manifest.assets);
+  return Array.from(new Set(paths));
+}
+
+function readManifestSource(manifest: LegacyEffectManifest): string | undefined {
+  if (typeof manifest.source === 'string') return manifest.source;
+  if (!manifest.source || typeof manifest.source !== 'object') return undefined;
+  const source = manifest.source as Record<string, unknown>;
+  return typeof source.sourceId === 'string' ? source.sourceId : undefined;
+}
+
+function cloneEmitter(emitter: LegacyEmitterConfig): LegacyEmitterConfig {
+  return JSON.parse(JSON.stringify(emitter)) as LegacyEmitterConfig;
+}
+
+function disposeRoot(root: TransformNode): void {
+  if (typeof root.isDisposed === 'function' && root.isDisposed()) return;
+  root.dispose(false, true);
+}

package/packages/registry.ts

@@ -0,0 +1,85 @@
+// 注册表:库提供 buildRegistry(纯函数);glob 调用在「项目侧」(Vite 编译期相对解析),
+// 项目把 glob 结果传进来 → 得到一个 VfxRegistry,注入给 EffectPackageService。
+import type { VfxEffectPackage, VfxParamValues } from './types';
+
+export interface VfxRegistry {
+  getEffectPackage(effectId: string): VfxEffectPackage | undefined;
+  getEffectPackages(): VfxEffectPackage[];
+  savedParams: Record<string, Partial<VfxParamValues>>;
+}
+
+export interface BuildRegistryInput {
+  /** import.meta.glob('./effects/*\/index.ts', { eager: true }) 的结果 */
+  modules: Record<string, Record<string, unknown>>;
+  /** import.meta.glob('./effects/*\/vfx-params.json', { eager: true }) 的结果(可选) */
+  params?: Record<string, { default: unknown } | unknown>;
+  /** 可选:判定某目录是否仅调试用(prod 构建剔除) */
+  isDebugOnly?: (dir: string) => boolean;
+  /** 可选:prod 标志,配合 isDebugOnly 过滤 */
+  prod?: boolean;
+}
+
+export function isVfxEffectPackage(value: unknown): value is VfxEffectPackage {
+  return (
+    !!value &&
+    typeof value === 'object' &&
+    typeof (value as VfxEffectPackage).id === 'string' &&
+    typeof (value as VfxEffectPackage).create === 'function'
+  );
+}
+
+function pickPackage(mod: Record<string, unknown>): VfxEffectPackage | null {
+  if (isVfxEffectPackage((mod as { default?: unknown }).default)) {
+    return (mod as { default: VfxEffectPackage }).default;
+  }
+  for (const value of Object.values(mod)) if (isVfxEffectPackage(value)) return value;
+  return null;
+}
+
+function dirOf(path: string): string {
+  const m = path.match(/\/effects\/([^/]+)\//) ?? path.match(/^\.\/effects\/([^/]+)\//);
+  return m ? m[1] : path;
+}
+
+function sanitizeParamsFile(value: unknown): Partial<VfxParamValues> {
+  const v = value && typeof value === 'object' && 'default' in (value as object)
+    ? (value as { default: unknown }).default
+    : value;
+  if (!v || typeof v !== 'object' || Array.isArray(v)) return {};
+  const params = (v as { params?: unknown }).params;
+  if (params && typeof params === 'object' && !Array.isArray(params)) return params as Partial<VfxParamValues>;
+  return v as Partial<VfxParamValues>;
+}
+
+export function buildRegistry(input: BuildRegistryInput): VfxRegistry {
+  const paramsByDir: Record<string, Partial<VfxParamValues>> = {};
+  for (const [path, mod] of Object.entries(input.params ?? {})) {
+    paramsByDir[dirOf(path)] = sanitizeParamsFile(mod);
+  }
+
+  const map = new Map<string, VfxEffectPackage>();
+  const savedParams: Record<string, Partial<VfxParamValues>> = {};
+  for (const [path, mod] of Object.entries(input.modules)) {
+    const dir = dirOf(path);
+    if (input.prod && input.isDebugOnly?.(dir)) continue;
+    const pkg = pickPackage(mod);
+    if (!pkg) {
+      console.warn('[vfx] no VfxEffectPackage export found in', path);
+      continue;
+    }
+    if (map.has(pkg.id)) {
+      throw new Error(`[vfx] duplicate effect id "${pkg.id}" (dir: ${dir})`);
+    }
+    const saved = paramsByDir[dir] ?? {};
+    pkg.savedParams = saved;
+    savedParams[pkg.id] = saved;
+    map.set(pkg.id, pkg);
+  }
+
+  const list = [...map.values()].sort((a, b) => a.id.localeCompare(b.id));
+  return {
+    getEffectPackage: (id) => map.get(id),
+    getEffectPackages: () => list,
+    savedParams,
+  };
+}

package/packages/rendering.ts

@@ -0,0 +1,13 @@
+import type { ParticleSystem } from '@babylonjs/core/Particles/particleSystem';
+import type { SpriteManager } from '@babylonjs/core/Sprites/spriteManager';
+
+export const VFX_RENDERING_GROUP_ID = 2;
+
+export function configureVfxSpriteManager(manager: SpriteManager): void {
+  manager.renderingGroupId = VFX_RENDERING_GROUP_ID;
+  manager.disableDepthWrite = true;
+}
+
+export function configureVfxParticleSystem(system: ParticleSystem): void {
+  system.renderingGroupId = VFX_RENDERING_GROUP_ID;
+}