@fps-games/vfx 0.3.2 → 0.3.3

package/packages/EffectPackageService.ts

@@ -1,346 +0,0 @@
-import { Vector3 } from '@babylonjs/core/Maths/math.vector';
-import type { Scene } from '@babylonjs/core/scene';
-import { TransformNode } from '@babylonjs/core/Meshes/transformNode';
-import { VFX_DEFAULT_GENERATION_PARAMS, VFX_GENERATION_PARAM_KEYS } from './generation';
-import type { VfxRegistry } from './registry';
-import type {
-  VfxColorValue,
-  VfxDebugAnchor,
-  VfxEffectHandle,
-  VfxEffectInputs,
-  VfxEffectPackage,
-  VfxInputKey,
-  VfxParamValue,
-  VfxParamValues,
-  VfxResolvedInputs,
-  VfxSpawnParamKeys,
-  VfxSpawnTransform,
-} from './types';
-
-export interface EffectPackageServiceOptions {
-  /** 注入的注册表(由项目侧 glob + buildRegistry 构建);库不直接引用项目注册表 */
-  registry: VfxRegistry;
-  getDebugAnchorPosition?: (anchor: VfxDebugAnchor) => Vector3 | null;
-}
-
-const DEFAULT_SPAWN_PARAM_KEYS: Required<Pick<VfxSpawnParamKeys, 'offsetX' | 'offsetY' | 'offsetZ'>> = {
-  offsetX: VFX_GENERATION_PARAM_KEYS.offsetX,
-  offsetY: VFX_GENERATION_PARAM_KEYS.offsetY,
-  offsetZ: VFX_GENERATION_PARAM_KEYS.offsetZ,
-};
-
-export class EffectPackageService {
-  private readonly scene: Scene;
-  private readonly registry: VfxRegistry;
-  private readonly getDebugAnchorPosition?: (anchor: VfxDebugAnchor) => Vector3 | null;
-  private readonly activeHandles = new Set<VfxEffectHandle>();
-  private readonly savedParams: Record<string, Partial<VfxParamValues>>;
-
-  constructor(scene: Scene, options: EffectPackageServiceOptions) {
-    this.scene = scene;
-    this.registry = options.registry;
-    this.getDebugAnchorPosition = options.getDebugAnchorPosition;
-    this.savedParams = cloneOverrideMap(options.registry.savedParams);
-  }
-
-  getEffectPackages(): VfxEffectPackage[] {
-    return this.registry.getEffectPackages();
-  }
-
-  getEffectPackage(effectId: string): VfxEffectPackage | undefined {
-    return this.registry.getEffectPackage(effectId);
-  }
-
-  getMergedParams(effectId: string, explicitParams?: Partial<VfxParamValues>): VfxParamValues | null {
-    const effectPackage = this.getEffectPackage(effectId);
-    if (!effectPackage) return null;
-    return mergeVfxParams(
-      VFX_DEFAULT_GENERATION_PARAMS,
-      effectPackage.defaultParams,
-      effectPackage.savedParams,
-      this.savedParams[effectId],
-      explicitParams,
-    );
-  }
-
-  getDebugOverride(effectId: string): Partial<VfxParamValues> {
-    return cloneParams(this.savedParams[effectId]);
-  }
-
-  setDebugOverride(effectId: string, params: Partial<VfxParamValues>): void {
-    this.savedParams[effectId] = cloneParams(params);
-    const effectPackage = this.getEffectPackage(effectId);
-    if (effectPackage) effectPackage.savedParams = cloneParams(params);
-  }
-
-  playEffectPackage(
-    effectId: string,
-    explicitParams?: Partial<VfxParamValues>,
-    spawnTransform?: VfxSpawnTransform | Vector3,
-  ): VfxEffectHandle | null {
-    const effectPackage = this.getEffectPackage(effectId);
-    if (!effectPackage) {
-      console.warn(`[EffectPackageService] Unknown VFX effect package: ${effectId}`);
-      return null;
-    }
-
-    const params = this.getMergedParams(effectId, explicitParams);
-    if (!params) return null;
-
-    const spawn = this.resolveSpawnTransform(effectPackage, params, spawnTransform);
-    warnMissingRequiredInputs(effectId, effectPackage.requiredInputs, spawn.inputs);
-    const runtimeParams = stripSpawnParams(params, effectPackage.spawnParams);
-    const root = new TransformNode(`vfx_package_${effectId}`, this.scene);
-    applySpawnToRoot(root, spawn);
-    // 世界位置(挂到 parent 后即为绝对世界坐标):保证世界空间特效(如拖尾)起点正确。
-    const worldPosition = root.getAbsolutePosition().clone();
-    let handle: VfxEffectHandle;
-    try {
-      handle = effectPackage.create({
-        scene: this.scene,
-        root,
-        position: worldPosition,
-        rotationY: spawn.rotationY,
-        renderingGroupId: spawn.renderingGroupId,
-        params: runtimeParams,
-        scale: spawn.scale,
-        inputs: spawn.inputs,
-      });
-      // root 的摆放归 service 独占。许多特效在 create() 里会写 `root.position.copyFrom(position)`
-      // (用世界坐标),挂到 parent 时会与 local offset 冲突 → 双偏移。这里在 create() 之后
-      // 重新断言一次 root transform,覆盖回 spawn 的正确值(无 parent 时为同值,无副作用)。
-      applySpawnToRoot(root, spawn);
-    } catch (error) {
-      // 错误兜底:单个坏包不得崩掉整个场景(plan §7)
-      console.warn(`[EffectPackageService] effect "${effectId}" create() failed; skipped.`, error);
-      try { root.dispose(); } catch { /* ignore */ }
-      return null;
-    }
-    this.activeHandles.add(handle);
-    const originalDispose = handle.dispose.bind(handle);
-    handle.dispose = () => {
-      this.activeHandles.delete(handle);
-      originalDispose();
-    };
-    // G4/M4:很多特效内部用 scheduleLifetime 自销,直接 dispose root(绕过上面 wrap 的 handle.dispose),
-    // 会让 activeHandles 残留已死 handle。监听 root 销毁 → 任何路径销毁都清理(自销/手动皆覆盖)。
-    handle.root.onDisposeObservable.addOnce(() => { this.activeHandles.delete(handle); });
-    return handle;
-  }
-
-  dispose(): void {
-    for (const handle of this.activeHandles) {
-      handle.dispose();
-    }
-    this.activeHandles.clear();
-  }
-
-  private resolveDebugPosition(effectPackage: VfxEffectPackage): Vector3 {
-    const anchor = effectPackage.debugAnchor ?? 'playerRight';
-    const anchorPosition = this.getDebugAnchorPosition?.(anchor);
-    if (anchorPosition) return anchorPosition.clone();
-    const cameraTarget = (this.scene.activeCamera as any)?.target as Vector3 | undefined;
-    if (cameraTarget?.clone) return cameraTarget.clone().addInPlace(new Vector3(1.2, 0, 0));
-    return new Vector3(0, 0, 0);
-  }
-
-  private resolveSpawnTransform(
-    effectPackage: VfxEffectPackage,
-    params: VfxParamValues,
-    spawnTransform?: VfxSpawnTransform | Vector3,
-  ): ResolvedSpawnTransform {
-    const normalized = normalizeSpawnTransform(spawnTransform);
-    const parent = normalized.parent ?? null;
-    // 有 parent(挂载)时默认落在挂点 (0,0,0) local;无 parent 时才回退到 debug 锚点(预览用)。
-    const basePosition = normalized.position?.clone()
-      ?? (parent != null ? new Vector3(0, 0, 0) : this.resolveDebugPosition(effectPackage));
-    const rotation = resolveRotation(normalized.rotation, normalized.rotationY);
-    const scale = resolveScale(normalized.scale);
-    // 默认坐标系:给了 parent → local;没给 → 世界(保持现状)。
-    const offsetIsLocal = normalized.offsetIsLocal ?? parent != null;
-    const renderingGroupId = readOptionalFiniteNumber(normalized.renderingGroupId);
-    const offset = readSpawnOffset(params, effectPackage.spawnParams);
-    let position = basePosition;
-    if (offset.lengthSquared() > 0.0000001) {
-      const cos = Math.cos(rotation.y);
-      const sin = Math.sin(rotation.y);
-      position = basePosition.addInPlace(new Vector3(
-        offset.x * cos - offset.z * sin,
-        offset.y,
-        offset.x * sin + offset.z * cos,
-      ));
-    }
-    return { position, rotation, rotationY: rotation.y, scale, parent, offsetIsLocal, renderingGroupId, inputs: normalizeInputs(normalized.inputs) };
-  }
-}
-
-// 把调用方的 inputs(值 or provider)归一化为访问器:create() 里 inputs.aim() 总可调用(动态目标每帧取)。
-function normalizeInputs(inputs?: VfxEffectInputs): VfxResolvedInputs | undefined {
-  if (!inputs) return undefined;
-  const asFn = <T>(v: T | (() => T) | undefined): (() => T) | undefined =>
-    v == null ? undefined : (typeof v === 'function' ? v as () => T : () => v);
-  const out: VfxResolvedInputs = {};
-  if (inputs.aim != null) out.aim = asFn(inputs.aim);
-  if (inputs.normal != null) out.normal = asFn(inputs.normal);
-  if (inputs.endpoints) out.endpoints = inputs.endpoints.map((e) => asFn(e)!).filter(Boolean);
-  if (inputs.target) out.target = inputs.target;
-  if (inputs.scalars) {
-    out.scalars = {};
-    for (const [k, v] of Object.entries(inputs.scalars)) {
-      const fn = asFn(v);
-      if (fn) out.scalars[k] = fn;
-    }
-  }
-  return out;
-}
-
-// G2:特效声明 requiredInputs 但调用方未提供对应 inputs → 警告(漏接静默降级很难查)。optionalInputs 不在此列。
-function warnMissingRequiredInputs(effectId: string, required: VfxInputKey[] | undefined, inputs: VfxResolvedInputs | undefined): void {
-  if (!required || required.length === 0) return;
-  const missing = required.filter((k) => {
-    const v = inputs ? (inputs as Record<string, unknown>)[k] : undefined;
-    return v == null || (k === 'endpoints' && Array.isArray(v) && v.length < 2);
-  });
-  if (missing.length > 0) {
-    console.warn(`[EffectPackageService] effect "${effectId}" 声明 requiredInputs [${missing.join(', ')}] 但未提供 → 可能静默降级。`);
-  }
-}
-
-interface ResolvedSpawnTransform {
-  /** 按 offsetIsLocal 解释的位置:local(相对 parent)或世界坐标。 */
-  position: Vector3;
-  /** 完整欧拉角旋转(弧度)。 */
-  rotation: Vector3;
-  /** 有效 Y 轴旋转(弧度),透传给 create() 上下文(向后兼容)。 */
-  rotationY: number;
-  /** 三轴缩放。 */
-  scale: Vector3;
-  parent: TransformNode | null;
-  offsetIsLocal: boolean;
-  renderingGroupId?: number;
-  inputs?: VfxResolvedInputs;
-}
-
-// 把解析后的 spawn transform 落到 root 节点上。
-//  - 没给 parent:position/rotation/scale 即世界坐标(无 parent 时 local == world),与现状一致。
-//  - 给了 parent + offsetIsLocal(默认):写到 root 的 local transform(随 parent 跟随)。
-//  - 给了 parent + offsetIsLocal=false:position 按绝对世界坐标落位;rotation/scale 仍按 local 应用。
-function applySpawnToRoot(root: TransformNode, spawn: ResolvedSpawnTransform): void {
-  if (spawn.parent) root.parent = spawn.parent;
-  root.rotation.copyFrom(spawn.rotation);
-  root.scaling.copyFrom(spawn.scale);
-  if (spawn.parent && !spawn.offsetIsLocal) {
-    // 需要先有 parent 的世界矩阵,才能把世界坐标反解成 local。
-    root.computeWorldMatrix(true);
-    root.setAbsolutePosition(spawn.position);
-  } else {
-    root.position.copyFrom(spawn.position);
-  }
-  root.computeWorldMatrix(true);
-}
-
-function resolveRotation(rotation: VfxSpawnTransform['rotation'], rotationY: unknown): Vector3 {
-  if (rotation) {
-    return new Vector3(
-      readFiniteNumber(rotation.x, 0),
-      readFiniteNumber(rotation.y, 0),
-      readFiniteNumber(rotation.z, 0),
-    );
-  }
-  return new Vector3(0, readFiniteNumber(rotationY, 0), 0);
-}
-
-function resolveScale(scale: VfxSpawnTransform['scale']): Vector3 {
-  if (scale == null) return new Vector3(1, 1, 1);
-  if (typeof scale === 'number') {
-    const s = readFiniteNumber(scale, 1);
-    return new Vector3(s, s, s);
-  }
-  return new Vector3(
-    readFiniteNumber(scale.x, 1),
-    readFiniteNumber(scale.y, 1),
-    readFiniteNumber(scale.z, 1),
-  );
-}
-
-function normalizeSpawnTransform(spawnTransform?: VfxSpawnTransform | Vector3): VfxSpawnTransform {
-  if (!spawnTransform) return {};
-  if (spawnTransform instanceof Vector3) return { position: spawnTransform };
-  return spawnTransform;
-}
-
-function readSpawnOffset(params: VfxParamValues, spawnParams?: VfxSpawnParamKeys): Vector3 {
-  const keys = resolveSpawnParamKeys(spawnParams);
-  return new Vector3(
-    readParamNumber(params[keys.offsetX ?? ''], 0),
-    readParamNumber(params[keys.offsetY ?? ''], 0),
-    readParamNumber(params[keys.offsetZ ?? ''], 0),
-  );
-}
-
-function stripSpawnParams(params: VfxParamValues, spawnParams?: VfxSpawnParamKeys): VfxParamValues {
-  const result = cloneParams(params) as VfxParamValues;
-  const keys = resolveSpawnParamKeys(spawnParams);
-  for (const key of [keys.offsetX, keys.offsetY, keys.offsetZ]) {
-    if (key) delete result[key];
-  }
-  return result;
-}
-
-function resolveSpawnParamKeys(spawnParams?: VfxSpawnParamKeys): VfxSpawnParamKeys {
-  return spawnParams ?? DEFAULT_SPAWN_PARAM_KEYS;
-}
-
-function readParamNumber(value: VfxParamValue | undefined, fallback: number): number {
-  return typeof value === 'number' && Number.isFinite(value) ? value : fallback;
-}
-
-function readFiniteNumber(value: unknown, fallback: number): number {
-  return typeof value === 'number' && Number.isFinite(value) ? value : fallback;
-}
-
-function readOptionalFiniteNumber(value: unknown): number | undefined {
-  return typeof value === 'number' && Number.isFinite(value) ? value : undefined;
-}
-
-function mergeVfxParams(
-  ...sources: Array<Partial<VfxParamValues> | undefined>
-): VfxParamValues {
-  const result: Partial<VfxParamValues> = {};
-  for (const source of sources) {
-    Object.assign(result, cloneParams(source));
-  }
-  return result as VfxParamValues;
-}
-
-function cloneParams(value: Partial<VfxParamValues> | undefined): Partial<VfxParamValues> {
-  if (!value) return {};
-  const result: Partial<VfxParamValues> = {};
-  for (const [key, item] of Object.entries(value)) {
-    if (item === undefined) continue;
-    result[key] = cloneParamValue(item);
-  }
-  return result;
-}
-
-function cloneOverrideMap(value: Record<string, Partial<VfxParamValues>>): Record<string, Partial<VfxParamValues>> {
-  const result: Record<string, Partial<VfxParamValues>> = {};
-  for (const [effectId, params] of Object.entries(value)) {
-    result[effectId] = cloneParams(params);
-  }
-  return result;
-}
-
-function cloneParamValue(value: VfxParamValue): VfxParamValue {
-  if (isColorValue(value)) return { ...value };
-  return value;
-}
-
-function isColorValue(value: unknown): value is VfxColorValue {
-  return !!value
-    && typeof value === 'object'
-    && !Array.isArray(value)
-    && typeof (value as VfxColorValue).r === 'number'
-    && typeof (value as VfxColorValue).g === 'number'
-    && typeof (value as VfxColorValue).b === 'number';
-}

package/packages/SceneVfxService.ts

@@ -1,96 +0,0 @@
-/**
- * SceneVfxService —— 特效播放门面(库纯净版)
- *
- * 只委托 EffectPackageService:播放 / 预热 / 销毁。注册表经 options.registry 注入。
- * 注:旧版的 `initFromConfig`/`createParticleSystem`(读 scene.json + UIImages 的常驻场景粒子路径)
- * 属项目耦合,已从库剥离(契约 §17)。场景常驻粒子应建模为普通特效包,由项目在 init 时触发。
- */
-import { Scene } from '@babylonjs/core/scene';
-import { Vector3 } from '@babylonjs/core/Maths/math.vector';
-
-import type { VfxRegistry } from './registry';
-import type {
-  VfxDebugAnchor,
-  VfxEffectHandle,
-  VfxEffectPackage,
-  VfxParamValues,
-  VfxSpawnTransform,
-} from './types';
-import { EffectPackageService } from './EffectPackageService';
-
-export interface SceneVfxWarmupEntry {
-  effectId: string;
-  params?: Partial<VfxParamValues>;
-  spawnTransform?: VfxSpawnTransform | Vector3;
-}
-
-export interface SceneVfxServiceOptions {
-  /** 注入的注册表(项目侧 glob + buildRegistry 构建) */
-  registry: VfxRegistry;
-  getDebugAnchorPosition?: (anchor: VfxDebugAnchor) => Vector3 | null;
-}
-
-export class SceneVfxService {
-  private effectPackageService: EffectPackageService;
-
-  constructor(scene: Scene, options: SceneVfxServiceOptions) {
-    this.effectPackageService = new EffectPackageService(scene, {
-      registry: options.registry,
-      getDebugAnchorPosition: options.getDebugAnchorPosition,
-    });
-  }
-
-  getEffectPackageService(): EffectPackageService {
-    return this.effectPackageService;
-  }
-
-  getEffectPackages(): VfxEffectPackage[] {
-    return this.effectPackageService.getEffectPackages();
-  }
-
-  getMergedParams(effectId: string, explicitParams?: Partial<VfxParamValues>): VfxParamValues | null {
-    return this.effectPackageService.getMergedParams(effectId, explicitParams);
-  }
-
-  playEffectPackage(
-    effectId: string,
-    params: Partial<VfxParamValues> = {},
-    spawnTransform?: VfxSpawnTransform | Vector3,
-  ): VfxEffectHandle | null {
-    return this.effectPackageService.playEffectPackage(effectId, params, spawnTransform);
-  }
-
-  async warmupEffectPackages(entries: SceneVfxWarmupEntry[]): Promise<void> {
-    await Promise.all(entries.map((entry) => this.warmupEffectPackage(entry)));
-  }
-
-  private async warmupEffectPackage(entry: SceneVfxWarmupEntry): Promise<void> {
-    let handle: VfxEffectHandle | null = null;
-    try {
-      handle = this.playEffectPackage(entry.effectId, entry.params ?? {}, entry.spawnTransform);
-      if (!handle) return;
-      await handle.ready;
-      await this.waitForAnimationFrames(2);
-    } catch (error) {
-      console.warn(`[SceneVfxService] Failed to warm up effect package "${entry.effectId}".`, error);
-    } finally {
-      handle?.dispose();
-    }
-  }
-
-  private async waitForAnimationFrames(frameCount: number): Promise<void> {
-    for (let i = 0; i < frameCount; i += 1) {
-      await new Promise<void>((resolve) => {
-        if (typeof requestAnimationFrame === 'function') {
-          requestAnimationFrame(() => resolve());
-          return;
-        }
-        window.setTimeout(resolve, 0);
-      });
-    }
-  }
-
-  dispose(): void {
-    this.effectPackageService.dispose();
-  }
-}