@fps-games/vfx 0.1.1

package/packages/SceneVfxService.ts

@@ -0,0 +1,96 @@
+/**
+ * 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();
+  }
+}

package/packages/build.mesh.yellow_build_upgrade_indicator/assets/runtime/simpleMeshEffect.v1.js

@@ -0,0 +1,333 @@
+export const runtimeId = "simpleMeshEffect/v1";
+
+export const runtimeContract = {
+  runtimeId,
+  kind: "meshEffect",
+  meshEffectFields: {
+    shape: "Mesh primitive to create. Supported values: box, cylinder.",
+    size: "Absolute mesh dimensions in Babylon local x/y/z units.",
+    offset: "Babylon TransformNode position offset in x/y/z units.",
+    tintColor: "Base shader tint color in 0-1 RGBA space. RGB is multiplied by tintColorIntensity; alpha is not.",
+    tintColorIntensity: "Brightness multiplier applied only to shader tintColor.rgb.",
+    fadeSoftness: "Softness of the upward reveal edge in normalized local-Y space.",
+    boundsAxis: "Axis used by the shader for height fade and reveal. simpleMeshEffect/v1 uses localY.",
+  },
+  shaderUniforms: {
+    diffuseSampler: "Emitter texture sampled by UV.",
+    tintColor: "Final vec4 tint passed to shader after runtime keyframe sampling.",
+    globalAlpha: "Final alpha multiplier sampled from emitter.alphaKeys.",
+    revealY: "Normalized upward reveal progress from 0 to 1.",
+    fadeSoftness: "Soft reveal edge width.",
+    meshMinY: "Minimum local mesh Y used to normalize vertical gradients.",
+    meshMaxY: "Maximum local mesh Y used to normalize vertical gradients.",
+  },
+  runtimeBindings: {
+    "shader.tintColor.rgb": "meshEffect.tintColor.rgb * meshEffect.tintColorIntensity * sample(colorKeys, t).rgb",
+    "shader.tintColor.a": "meshEffect.tintColor.a * sample(colorKeys, t).a",
+    "shader.globalAlpha": "sample(alphaKeys, t).alpha",
+    "root.scaling.y": "sample(meshScaleKeys.y, t) / finalMeshScaleKeysY",
+    "shader.revealY": "elapsed / duration",
+  },
+};
+
+function num(value, fallback = 0) {
+  const next = Number(value);
+  return Number.isFinite(next) ? next : fallback;
+}
+
+function readColor(BABYLON, value, fallback = new BABYLON.Color4(1, 1, 1, 1)) {
+  if (!value) return fallback;
+  return new BABYLON.Color4(num(value.r, fallback.r), num(value.g, fallback.g), num(value.b, fallback.b), num(value.a, fallback.a));
+}
+
+function sampleKeyframes(keys, valueKey, t, fallback = 1) {
+  if (!Array.isArray(keys) || keys.length === 0) return fallback;
+  const points = keys
+    .map((key) => ({ time: Math.min(1, Math.max(0, num(key.time, 0))), value: num(key[valueKey], fallback) }))
+    .sort((a, b) => a.time - b.time);
+  if (t <= points[0].time) return points[0].value;
+  for (let index = 1; index < points.length; index += 1) {
+    const prev = points[index - 1];
+    const next = points[index];
+    if (t <= next.time) {
+      const span = Math.max(0.0001, next.time - prev.time);
+      const local = (t - prev.time) / span;
+      return prev.value + (next.value - prev.value) * local;
+    }
+  }
+  return points.at(-1).value;
+}
+
+function sampleColorKeyframes(BABYLON, keys, t, fallback = new BABYLON.Color4(1, 1, 1, 1)) {
+  if (!Array.isArray(keys) || keys.length === 0) return fallback;
+  const points = keys
+    .map((key) => ({
+      time: Math.min(1, Math.max(0, num(key.time, 0))),
+      color: readColor(BABYLON, key.color, fallback),
+    }))
+    .sort((a, b) => a.time - b.time);
+  if (t <= points[0].time) return points[0].color;
+  for (let index = 1; index < points.length; index += 1) {
+    const prev = points[index - 1];
+    const next = points[index];
+    if (t <= next.time) {
+      const span = Math.max(0.0001, next.time - prev.time);
+      const local = (t - prev.time) / span;
+      return new BABYLON.Color4(
+        prev.color.r + (next.color.r - prev.color.r) * local,
+        prev.color.g + (next.color.g - prev.color.g) * local,
+        prev.color.b + (next.color.b - prev.color.b) * local,
+        prev.color.a + (next.color.a - prev.color.a) * local,
+      );
+    }
+  }
+  return points.at(-1).color;
+}
+
+function shaderMaterialAlphaMode(BABYLON, value) {
+  if (value === "STANDARD") return BABYLON.Engine.ALPHA_COMBINE;
+  if (value === "MULTIPLY") return BABYLON.Engine.ALPHA_MULTIPLY ?? BABYLON.Engine.ALPHA_COMBINE;
+  return BABYLON.Engine.ALPHA_ADD;
+}
+
+function shaderStoreName(emitter, index) {
+  const id = String(emitter?.shader?.id || emitter?.meshEffect?.shaderId || `simpleMeshEffectV1_${index}`)
+    .replace(/[^a-zA-Z0-9_]/g, "_")
+    .replace(/^([^a-zA-Z_])/, "_$1");
+  return id || `simpleMeshEffectV1_${index}`;
+}
+
+async function fetchShaderSource({ packagePath, label, urlForPackagePath }) {
+  if (!packagePath) throw new Error(`Missing ${label} shader path.`);
+  const url = urlForPackagePath ? urlForPackagePath(packagePath) : packagePath;
+  const response = await fetch(url, { cache: "no-store" });
+  if (!response.ok) throw new Error(`Failed to load ${label} shader ${packagePath}: HTTP ${response.status}.`);
+  const source = await response.text();
+  if (!source.trim()) throw new Error(`Loaded empty ${label} shader ${packagePath}.`);
+  return source;
+}
+
+async function loadShaders({ BABYLON, emitter, index, urlForPackagePath }) {
+  const name = shaderStoreName(emitter, index);
+  const vertexSource = await fetchShaderSource({
+    packagePath: emitter?.shader?.vertexShaderPath,
+    label: "vertex",
+    urlForPackagePath,
+  });
+  const fragmentSource = await fetchShaderSource({
+    packagePath: emitter?.shader?.fragmentShaderPath,
+    label: "fragment",
+    urlForPackagePath,
+  });
+  BABYLON.Effect.ShadersStore[`${name}VertexShader`] = vertexSource;
+  BABYLON.Effect.ShadersStore[`${name}FragmentShader`] = fragmentSource;
+  return name;
+}
+
+function createMaterial({ BABYLON, scene, name, texture, alphaMode, shaderName }) {
+  const material = new BABYLON.ShaderMaterial(name, scene, {
+    vertex: shaderName,
+    fragment: shaderName,
+  }, {
+    attributes: ["position", "uv"],
+    uniforms: ["worldViewProjection", "tintColor", "meshMinY", "meshMaxY", "revealY", "fadeSoftness", "globalAlpha"],
+    samplers: ["diffuseSampler"],
+    needAlphaBlending: true,
+  });
+  material.setTexture("diffuseSampler", texture);
+  material.setFloat("meshMinY", -1);
+  material.setFloat("meshMaxY", 1);
+  material.setFloat("revealY", 0);
+  material.setFloat("fadeSoftness", 0.24);
+  material.setFloat("globalAlpha", 1);
+  material.backFaceCulling = false;
+  material.alphaMode = shaderMaterialAlphaMode(BABYLON, alphaMode);
+  return material;
+}
+
+function meshLocalYBounds(BABYLON, meshes) {
+  let minY = Number.POSITIVE_INFINITY;
+  let maxY = Number.NEGATIVE_INFINITY;
+  for (const mesh of meshes) {
+    const positions = mesh.getVerticesData?.(BABYLON.VertexBuffer.PositionKind) || [];
+    for (let index = 1; index < positions.length; index += 3) {
+      minY = Math.min(minY, positions[index]);
+      maxY = Math.max(maxY, positions[index]);
+    }
+  }
+  if (!Number.isFinite(minY) || !Number.isFinite(maxY)) return { minY: -1, maxY: 1 };
+  return { minY, maxY: Math.max(maxY, minY + 0.0001) };
+}
+
+function shapeType(emitter) {
+  const shape = emitter?.meshEffect?.shape || "box";
+  return ["box", "cylinder"].includes(shape) ? shape : "box";
+}
+
+function createBoxMeshes({ BABYLON, scene, emitter, index, root, material, width, depth, height }) {
+  const sides = [
+    { name: "front", sideWidth: width, position: new BABYLON.Vector3(0, 0, depth * 0.5), rotationY: 0 },
+    { name: "back", sideWidth: width, position: new BABYLON.Vector3(0, 0, -depth * 0.5), rotationY: Math.PI },
+    { name: "right", sideWidth: depth, position: new BABYLON.Vector3(width * 0.5, 0, 0), rotationY: Math.PI * 0.5 },
+    { name: "left", sideWidth: depth, position: new BABYLON.Vector3(-width * 0.5, 0, 0), rotationY: -Math.PI * 0.5 },
+  ];
+  return sides.map((side) => {
+    const mesh = BABYLON.MeshBuilder.CreatePlane(`simple-mesh-effect-${emitter.name || index}-${side.name}`, { width: side.sideWidth, height }, scene);
+    mesh.material = material;
+    mesh.parent = root;
+    mesh.position = side.position;
+    mesh.rotation.y = side.rotationY;
+    mesh.renderingGroupId = 2;
+    mesh.metadata = { ...(mesh.metadata || {}), emitterIndex: index, meshEffectMode: "simple", meshEffectShape: "box" };
+    return mesh;
+  });
+}
+
+function createCylinderMeshes({ BABYLON, scene, emitter, index, root, material, width, depth, height }) {
+  const mesh = BABYLON.MeshBuilder.CreateCylinder(`simple-mesh-effect-${emitter.name || index}-cylinder`, {
+    height,
+    diameter: 1,
+    tessellation: 48,
+    cap: BABYLON.Mesh.NO_CAP,
+  }, scene);
+  mesh.material = material;
+  mesh.parent = root;
+  mesh.scaling.x = width;
+  mesh.scaling.z = depth;
+  mesh.renderingGroupId = 2;
+  mesh.metadata = { ...(mesh.metadata || {}), emitterIndex: index, meshEffectMode: "simple", meshEffectShape: "cylinder" };
+  return [mesh];
+}
+
+function createMeshes({ BABYLON, scene, emitter, index, root, material, size }) {
+  if (shapeType(emitter) === "cylinder") {
+    return createCylinderMeshes({ BABYLON, scene, emitter, index, root, material, width: size.x, depth: size.z, height: size.y });
+  }
+  return createBoxMeshes({ BABYLON, scene, emitter, index, root, material, width: size.x, depth: size.z, height: size.y });
+}
+
+function defaultSize(emitter) {
+  const finalMeshScaleY = Math.max(0.001, num(emitter.meshScaleKeys?.y?.at?.(-1)?.scale, 8));
+  return {
+    x: Math.max(0.1, num(emitter.meshScaleKeys?.x?.[0]?.scale, 7.125) * 1.016),
+    y: Math.max(0.1, finalMeshScaleY * 1.016),
+    z: Math.max(0.1, num(emitter.meshScaleKeys?.z?.[0]?.scale, 4.125) * 1.016),
+  };
+}
+
+function meshEffectSize(emitter) {
+  const fallback = defaultSize(emitter);
+  return {
+    x: Math.max(0.1, num(emitter.meshEffect?.size?.x, fallback.x)),
+    y: Math.max(0.1, num(emitter.meshEffect?.size?.y, fallback.y)),
+    z: Math.max(0.1, num(emitter.meshEffect?.size?.z, fallback.z)),
+  };
+}
+
+function meshEffectOffset(emitter) {
+  return {
+    x: num(emitter.meshEffect?.offset?.x, 0),
+    y: num(emitter.meshEffect?.offset?.y, 0.65),
+    z: num(emitter.meshEffect?.offset?.z, 0),
+  };
+}
+
+function playbackSpeed(emitter) {
+  return Math.max(0.001, num(emitter.updateSpeed, 0.01) / 0.01);
+}
+
+function stopAfterSeconds(emitter, fallback = 1) {
+  return num(emitter.runtime?.stopAfterSeconds, fallback);
+}
+
+export async function createSimpleMeshEffectRuntime({ BABYLON, scene, emitter, index = 0, urlForPackagePath, shouldStart = false }) {
+  if (!BABYLON) throw new Error("createSimpleMeshEffectRuntime requires BABYLON.");
+  if (!scene) throw new Error("createSimpleMeshEffectRuntime requires scene.");
+  if (!emitter) throw new Error("createSimpleMeshEffectRuntime requires emitter.");
+  const shaderName = await loadShaders({ BABYLON, emitter, index, urlForPackagePath });
+  const textureUrl = urlForPackagePath ? urlForPackagePath(emitter.particleTexturePath) : emitter.particleTexturePath;
+  const texture = new BABYLON.Texture(textureUrl, scene);
+  texture.hasAlpha = true;
+  texture.getAlphaFromRGB = true;
+
+  const material = createMaterial({
+    BABYLON,
+    scene,
+    name: `simple-mesh-effect-material-${emitter.name || index}`,
+    texture,
+    alphaMode: emitter.blendMode,
+    shaderName,
+  });
+  const size = meshEffectSize(emitter);
+  const offset = meshEffectOffset(emitter);
+  const root = new BABYLON.TransformNode(`simple-mesh-effect-${emitter.name || index}`, scene);
+  root.position = new BABYLON.Vector3(offset.x, offset.y, offset.z);
+  root.metadata = { ...(root.metadata || {}), emitterIndex: index, meshEffectMode: "simple", meshEffectShape: shapeType(emitter) };
+  const meshes = createMeshes({ BABYLON, scene, emitter, index, root, material, size });
+  root.setEnabled(false);
+
+  const bounds = meshLocalYBounds(BABYLON, meshes);
+  material.setFloat("meshMinY", bounds.minY);
+  material.setFloat("meshMaxY", bounds.maxY);
+
+  const finalMeshScaleY = Math.max(0.001, num(emitter.meshScaleKeys?.y?.at?.(-1)?.scale, 1));
+  const duration = Math.max(0.1, stopAfterSeconds(emitter) / playbackSpeed(emitter));
+  const baseTint = readColor(BABYLON, emitter.meshEffect?.tintColor, new BABYLON.Color4(1, 1, 1, 1));
+  const tintColorIntensity = Math.max(0, num(emitter.meshEffect?.tintColorIntensity, 1));
+  const fadeSoftness = Math.max(0.03, num(emitter.meshEffect?.fadeSoftness, 0.24));
+  const colorKeys = emitter.colorKeys || [];
+  const meshScaleKeys = emitter.meshScaleKeys || null;
+  let startedAt = 0;
+  let observer = null;
+  let running = false;
+
+  const update = () => {
+    const elapsed = (performance.now() - startedAt) / 1000;
+    const t = Math.min(1, elapsed / duration);
+    const sizeFactor = Math.max(0.001, sampleKeyframes(emitter.sizeKeys, "size", t, 1));
+    const alphaFactor = Math.min(1, Math.max(0, sampleKeyframes(emitter.alphaKeys, "alpha", t, 1)));
+    const colorFactor = sampleColorKeyframes(BABYLON, colorKeys, t);
+    const rawScaleY = Math.max(0.001, sampleKeyframes(meshScaleKeys?.y, "scale", t, sizeFactor));
+    const scaleY = Math.max(0.001, rawScaleY / finalMeshScaleY);
+    root.scaling.set(1, scaleY, 1);
+    root.position.set(offset.x, offset.y - bounds.minY * scaleY, offset.z);
+    material.setFloat("revealY", Math.min(1, Math.max(0.001, t)));
+    material.setFloat("fadeSoftness", fadeSoftness);
+    material.setFloat("globalAlpha", alphaFactor);
+    material.setVector4("tintColor", new BABYLON.Vector4(
+      baseTint.r * tintColorIntensity * colorFactor.r,
+      baseTint.g * tintColorIntensity * colorFactor.g,
+      baseTint.b * tintColorIntensity * colorFactor.b,
+      baseTint.a * colorFactor.a,
+    ));
+    if (t >= 1) stop();
+  };
+
+  function start() {
+    stop();
+    running = true;
+    startedAt = performance.now();
+    root.setEnabled(true);
+    update();
+    observer = scene.onBeforeRenderObservable.add(update);
+  }
+
+  function stop() {
+    if (observer) scene.onBeforeRenderObservable.remove(observer);
+    observer = null;
+    running = false;
+    root.setEnabled(false);
+  }
+
+  function dispose() {
+    stop();
+    for (const mesh of meshes) mesh.dispose();
+    root.dispose();
+    material.dispose();
+    texture.dispose();
+  }
+
+  const preview = { start, stop, dispose, isStarted: () => running, root, meshes, material };
+  if (shouldStart) preview.start();
+  return preview;
+}

package/packages/build.mesh.yellow_build_upgrade_indicator/assets/shaders/mesh-effect-preview.frag.glsl

@@ -0,0 +1,25 @@
+precision highp float;
+varying vec2 vUV;
+varying float vLocalY;
+uniform sampler2D diffuseSampler;
+uniform vec4 tintColor;
+uniform float meshMinY;
+uniform float meshMaxY;
+uniform float revealY;
+uniform float fadeSoftness;
+uniform float globalAlpha;
+float saturate(float value) {
+  return clamp(value, 0.0, 1.0);
+}
+void main(void) {
+  vec4 tex = texture2D(diffuseSampler, vUV);
+  float height = max(meshMaxY - meshMinY, 0.0001);
+  float y01 = saturate((vLocalY - meshMinY) / height);
+  float revealMask = saturate((revealY - y01) / max(fadeSoftness, 0.0001));
+  float bottomSoft = smoothstep(0.0, 0.06, y01);
+  float verticalFade = pow(saturate(1.0 - y01), 1.35);
+  float textureGlow = mix(0.65, 1.15, max(max(tex.r, tex.g), tex.b));
+  float alpha = tintColor.a * globalAlpha * revealMask * bottomSoft * verticalFade * textureGlow;
+  vec3 color = tintColor.rgb * mix(vec3(0.72), vec3(1.18), tex.rgb);
+  gl_FragColor = vec4(color, alpha);
+}

package/packages/build.mesh.yellow_build_upgrade_indicator/assets/shaders/mesh-effect-preview.vert.glsl

@@ -0,0 +1,11 @@
+precision highp float;
+attribute vec3 position;
+attribute vec2 uv;
+uniform mat4 worldViewProjection;
+varying vec2 vUV;
+varying float vLocalY;
+void main(void) {
+  vUV = uv;
+  vLocalY = position.y;
+  gl_Position = worldViewProjection * vec4(position, 1.0);
+}