@fps-games/vfx 0.1.1 → 0.3.2

package/dist/effects/treasure-attention/index.js

@@ -0,0 +1,535 @@
+import { Constants } from "@babylonjs/core/Engines/constants";
+import { GlowLayer } from "@babylonjs/core/Layers/glowLayer";
+import { Material } from "@babylonjs/core/Materials/material";
+import { StandardMaterial } from "@babylonjs/core/Materials/standardMaterial";
+import { DynamicTexture } from "@babylonjs/core/Materials/Textures/dynamicTexture";
+import { Texture } from "@babylonjs/core/Materials/Textures/texture";
+import { Color3, Color4 } from "@babylonjs/core/Maths/math.color";
+import { Vector3 } from "@babylonjs/core/Maths/math.vector";
+import { Mesh } from "@babylonjs/core/Meshes/mesh";
+import { VertexData } from "@babylonjs/core/Meshes/mesh.vertexData";
+import { MeshBuilder } from "@babylonjs/core/Meshes/meshBuilder";
+import { TransformNode } from "@babylonjs/core/Meshes/transformNode";
+import { ParticleSystem } from "@babylonjs/core/Particles/particleSystem";
+import { V as VFX_RENDERING_GROUP_ID, c as configureVfxParticleSystem } from "../../chunks/rendering-CV3nhygX.js";
+const DEFAULT_PARAMS = {
+  radius: 1.15,
+  yOffset: 0.05,
+  height: 1.35,
+  rays: 9,
+  rayWidth: 0.34,
+  spinSpeed: 0.85,
+  color: { r: 1, g: 0.9, b: 0.22 },
+  auraColor: { r: 1, g: 0.82, b: 0.18 },
+  ringColor: { r: 1, g: 0.95, b: 0.38 },
+  rayColor: { r: 1, g: 0.76, b: 0.12 },
+  beamColor: { r: 1, g: 0.92, b: 0.32 },
+  opacity: 1,
+  auraOpacity: 0.82,
+  ringOpacity: 0.95,
+  beamOpacity: 0.68,
+  particleRate: 42,
+  particleLife: 0.82,
+  sparkleMinSize: 0.045,
+  sparkleMaxSize: 0.13,
+  riseSpeed: 0.72,
+  drift: 0.12,
+  bloomIntensity: 0.55,
+  bloomKernelSize: 32
+};
+const treasureAttentionEffectPackage = {
+  id: "treasure-attention",
+  nameZh: "宝藏注意力光效",
+  placement: "socket",
+  // 附着在宝藏上的注意力标记:geometry 挂 fxRoot 子节点承 yOffset,root 交给 service(挂载/位置由 service 管)
+  defaultParams: DEFAULT_PARAMS,
+  debugAnchor: "playerRight",
+  manifest: {
+    id: "treasure-attention",
+    nameZh: "宝藏注意力光效",
+    source: "docs/treasure_attention_fx_babylonjs_guide.md"
+  },
+  debugParams: [
+    { key: "radius", label: "光效半径", kind: "scale", min: 0.35, max: 3.5, step: 0.01 },
+    { key: "yOffset", label: "离地高度", kind: "number", min: -0.1, max: 0.4, step: 5e-3 },
+    { key: "height", label: "竖光高度", kind: "scale", min: 0.2, max: 3.5, step: 0.01 },
+    { key: "rays", label: "星芒数量", kind: "number", min: 0, max: 18, step: 1 },
+    { key: "rayWidth", label: "星芒宽度", kind: "scale", min: 0.05, max: 1, step: 0.01 },
+    { key: "spinSpeed", label: "旋转速度", kind: "number", min: -3, max: 3, step: 0.01 },
+    { key: "color", label: "上浮星星颜色", kind: "color" },
+    { key: "auraColor", label: "地面柔光颜色", kind: "color" },
+    { key: "ringColor", label: "光环颜色", kind: "color" },
+    { key: "rayColor", label: "旋转星芒颜色", kind: "color" },
+    { key: "beamColor", label: "竖向光柱颜色", kind: "color" },
+    { key: "opacity", label: "整体透明度", kind: "opacity", min: 0, max: 1.5, step: 0.01 },
+    { key: "auraOpacity", label: "地面柔光", kind: "opacity", min: 0, max: 1.5, step: 0.01 },
+    { key: "ringOpacity", label: "光环亮度", kind: "opacity", min: 0, max: 1.5, step: 0.01 },
+    { key: "beamOpacity", label: "竖光亮度", kind: "opacity", min: 0, max: 1.5, step: 0.01 },
+    { key: "particleRate", label: "闪片频率", kind: "number", min: 0, max: 120, step: 1 },
+    { key: "particleLife", label: "闪片寿命", kind: "lifetime", min: 0.2, max: 2.5, step: 0.01 },
+    { key: "sparkleMinSize", label: "闪片最小", kind: "scale", min: 0.01, max: 0.5, step: 5e-3 },
+    { key: "sparkleMaxSize", label: "闪片最大", kind: "scale", min: 0.01, max: 0.8, step: 5e-3 },
+    { key: "riseSpeed", label: "上浮速度", kind: "number", min: 0, max: 2.5, step: 0.01 },
+    { key: "drift", label: "横向漂移", kind: "number", min: 0, max: 1.2, step: 0.01 },
+    { key: "bloomIntensity", label: "Bloom 强度", kind: "number", min: 0, max: 2.5, step: 0.01 },
+    { key: "bloomKernelSize", label: "Bloom 半径", kind: "number", min: 8, max: 96, step: 1 }
+  ],
+  create({ scene, root, position, renderingGroupId, params }) {
+    return createTreasureAttentionFx(scene, { root, position, renderingGroupId, params, serviceOwnedRoot: true });
+  }
+};
+function createTreasureAttentionFx(scene, options = {}) {
+  let params = mergeParams(options.params);
+  const root = options.root ?? new TransformNode("vfx_treasureAttention_root", scene);
+  const disposeRoot = options.disposeRoot ?? true;
+  const renderingGroupId = options.renderingGroupId ?? VFX_RENDERING_GROUP_ID;
+  const sharedGlowLayer = options.glowLayer ?? null;
+  let target = options.target ?? null;
+  const serviceOwnedRoot = options.serviceOwnedRoot ?? false;
+  const basePosition = (options.position ?? root.position).clone();
+  const fxRoot = new TransformNode("vfx_treasureAttention_fxRoot", scene);
+  fxRoot.parent = root;
+  let enabled = true;
+  let disposed = false;
+  let elapsed = 0;
+  let raySignature = "";
+  const textures = /* @__PURE__ */ new Set();
+  const materials = /* @__PURE__ */ new Set();
+  const meshes = /* @__PURE__ */ new Set();
+  let rayMeshes = [];
+  let glowLayer = null;
+  let ownsGlowLayer = false;
+  const raysRoot = new TransformNode("vfx_treasureAttention_raysRoot", scene);
+  raysRoot.parent = fxRoot;
+  const auraTex = makeTexture(scene, textures, "vfx_treasureAttention_auraTex", 256, (ctx, size) => {
+    drawAuraTexture(ctx, size, DEFAULT_PARAMS.auraColor);
+  });
+  const ringTex = makeTexture(scene, textures, "vfx_treasureAttention_ringTex", 256, (ctx, size) => {
+    drawRingTexture(ctx, size, DEFAULT_PARAMS.ringColor);
+  });
+  const rayTex = makeTexture(scene, textures, "vfx_treasureAttention_rayTex", 256, (ctx, size) => {
+    drawRayTexture(ctx, size, DEFAULT_PARAMS.rayColor);
+  });
+  const beamTex = makeTexture(scene, textures, "vfx_treasureAttention_beamTex", 256, (ctx, size) => {
+    drawBeamTexture(ctx, size, DEFAULT_PARAMS.beamColor);
+  });
+  const sparkleTex = makeTexture(scene, textures, "vfx_treasureAttention_sparkleTex", 128, drawSparkleTexture);
+  const auraMat = makeAdditiveMaterial(scene, materials, "vfx_treasureAttention_auraMat", auraTex);
+  const ringMat = makeAdditiveMaterial(scene, materials, "vfx_treasureAttention_ringMat", ringTex);
+  const rayMat = makeAdditiveMaterial(scene, materials, "vfx_treasureAttention_rayMat", rayTex);
+  const beamMat = makeAdditiveMaterial(scene, materials, "vfx_treasureAttention_beamMat", beamTex);
+  const aura = addMesh(MeshBuilder.CreatePlane("vfx_treasureAttention_aura", { size: 1 }, scene));
+  aura.rotation.x = Math.PI / 2;
+  aura.position.y = 0.025;
+  aura.material = auraMat;
+  aura.parent = fxRoot;
+  aura.alphaIndex = 0;
+  const ring = addMesh(MeshBuilder.CreatePlane("vfx_treasureAttention_ring", { size: 1 }, scene));
+  ring.rotation.x = Math.PI / 2;
+  ring.position.y = 0.04;
+  ring.material = ringMat;
+  ring.parent = fxRoot;
+  ring.alphaIndex = 1;
+  const beam = addMesh(MeshBuilder.CreatePlane("vfx_treasureAttention_beam", { size: 1 }, scene));
+  beam.position.y = params.height * 0.52;
+  beam.billboardMode = Mesh.BILLBOARDMODE_Y;
+  beam.material = beamMat;
+  beam.parent = fxRoot;
+  beam.alphaIndex = 3;
+  const particleEmitter = addMesh(new Mesh("vfx_treasureAttention_particleEmitter", scene), false);
+  particleEmitter.isVisible = false;
+  particleEmitter.parent = fxRoot;
+  const particleSystem = new ParticleSystem("vfx_treasureAttention_sparkles", 180, scene);
+  configureVfxParticleSystem(particleSystem);
+  particleSystem.particleTexture = sparkleTex;
+  particleSystem.emitter = particleEmitter;
+  particleSystem.blendMode = ParticleSystem.BLENDMODE_ADD;
+  particleSystem.updateSpeed = 1 / 60;
+  particleSystem.minAngularSpeed = -4;
+  particleSystem.maxAngularSpeed = 4;
+  particleSystem.gravity = new Vector3(0, -0.04, 0);
+  particleSystem.start();
+  applyParams();
+  syncRoot();
+  const observer = scene.onBeforeRenderObservable.add(() => {
+    if (disposed || !enabled) return;
+    const dt = Math.min(scene.getEngine().getDeltaTime() / 1e3, 0.05);
+    elapsed += dt;
+    syncRoot();
+    animate(dt);
+  });
+  return {
+    root,
+    particleSystem,
+    update(partial) {
+      if (disposed) return;
+      params = mergeParams(partial, params);
+      applyParams();
+      syncRoot();
+    },
+    setEnabled(nextEnabled) {
+      enabled = nextEnabled;
+      root.setEnabled(nextEnabled);
+      if (nextEnabled) {
+        particleSystem.start();
+      } else {
+        particleSystem.stop();
+      }
+    },
+    setTarget(nextTarget) {
+      target = nextTarget;
+      syncRoot();
+    },
+    setPosition(position) {
+      basePosition.copyFrom(position);
+      syncRoot();
+    },
+    dispose() {
+      disposeAll();
+    }
+  };
+  function addMesh(mesh, includeInGlow = true) {
+    mesh.isPickable = false;
+    mesh.alwaysSelectAsActiveMesh = true;
+    mesh.renderingGroupId = renderingGroupId;
+    meshes.add(mesh);
+    if (includeInGlow) addGlowMesh(mesh);
+    return mesh;
+  }
+  function addGlowMesh(mesh) {
+    if (!glowLayer || !mesh.material) return;
+    glowLayer.addIncludedOnlyMesh(mesh);
+    glowLayer.referenceMeshToUseItsOwnMaterial(mesh);
+  }
+  function removeGlowMesh(mesh) {
+    glowLayer?.removeIncludedOnlyMesh(mesh);
+  }
+  function applyParams() {
+    redrawTexture(auraTex, 256, (ctx, size) => drawAuraTexture(ctx, size, params.auraColor));
+    redrawTexture(ringTex, 256, (ctx, size) => drawRingTexture(ctx, size, params.ringColor));
+    redrawTexture(rayTex, 256, (ctx, size) => drawRayTexture(ctx, size, params.rayColor));
+    redrawTexture(beamTex, 256, (ctx, size) => drawBeamTexture(ctx, size, params.beamColor));
+    auraMat.alpha = clamp(params.opacity * params.auraOpacity, 0, 1);
+    ringMat.alpha = clamp(params.opacity * params.ringOpacity, 0, 1);
+    rayMat.alpha = clamp(params.opacity * 0.9, 0, 1);
+    beamMat.alpha = clamp(params.opacity * params.beamOpacity, 0, 1);
+    fxRoot.position.y = params.yOffset;
+    aura.position.y = 0.015;
+    ring.position.y = aura.position.y + 0.018;
+    beam.position.y = params.height * 0.52;
+    beam.scaling.set(Math.max(0.02, params.radius * 1.05), Math.max(0.02, params.height), 1);
+    const particleLife = Math.max(0.04, params.particleLife);
+    const minSize = Math.max(1e-3, Math.min(params.sparkleMinSize, params.sparkleMaxSize));
+    const maxSize = Math.max(minSize, Math.max(params.sparkleMinSize, params.sparkleMaxSize));
+    particleSystem.emitRate = Math.max(0, params.particleRate);
+    particleSystem.minLifeTime = particleLife * 0.75;
+    particleSystem.maxLifeTime = particleLife * 1.2;
+    particleSystem.minSize = minSize;
+    particleSystem.maxSize = maxSize;
+    particleSystem.minEmitBox = new Vector3(-params.radius * 0.45, 0.15, -params.radius * 0.45);
+    particleSystem.maxEmitBox = new Vector3(params.radius * 0.45, 0.55, params.radius * 0.45);
+    particleSystem.direction1 = new Vector3(-params.drift, params.riseSpeed * 0.76, -params.drift);
+    particleSystem.direction2 = new Vector3(params.drift, params.riseSpeed * 1.24, params.drift);
+    particleSystem.minEmitPower = Math.max(0.01, params.riseSpeed * 0.28);
+    particleSystem.maxEmitPower = Math.max(particleSystem.minEmitPower, params.riseSpeed * 0.58);
+    particleSystem.color1 = tintColor(params.color, 1.15, 0.9 * params.opacity);
+    particleSystem.color2 = tintColor(params.color, 1.55, 0.76 * params.opacity);
+    particleSystem.colorDead = tintColor(params.color, 0.8, 0);
+    rebuildRaysIfNeeded();
+    syncGlowLayer();
+  }
+  function rebuildRaysIfNeeded() {
+    const rayCount = clamp(Math.round(params.rays), 0, 32);
+    const signature = `${rayCount}:${params.radius.toFixed(3)}:${params.rayWidth.toFixed(3)}`;
+    if (signature === raySignature) return;
+    raySignature = signature;
+    for (const ray of rayMeshes) {
+      removeGlowMesh(ray);
+      meshes.delete(ray);
+      ray.dispose(false, false);
+    }
+    rayMeshes = [];
+    for (let i = 0; i < rayCount; i += 1) {
+      const angle = i / Math.max(1, rayCount) * Math.PI * 2;
+      const length = params.radius * (0.95 + i % 3 * 0.13);
+      const width = params.rayWidth * (0.8 + i % 2 * 0.22);
+      const ray = createRayMesh(scene, `vfx_treasureAttention_ray_${i}`, length, width);
+      ray.parent = raysRoot;
+      ray.rotation.y = angle;
+      ray.position.y = ring.position.y + 0.014 + i * 1e-3;
+      ray.material = rayMat;
+      ray.alphaIndex = 2;
+      addMesh(ray);
+      rayMeshes.push(ray);
+    }
+  }
+  function syncGlowLayer() {
+    const shouldGlow = params.bloomIntensity > 0;
+    if (!shouldGlow) {
+      if (glowLayer) {
+        for (const mesh of meshes) removeGlowMesh(mesh);
+      }
+      if (ownsGlowLayer) glowLayer?.dispose();
+      glowLayer = null;
+      ownsGlowLayer = false;
+      return;
+    }
+    if (!glowLayer) {
+      if (sharedGlowLayer) {
+        glowLayer = sharedGlowLayer;
+      } else {
+        glowLayer = new GlowLayer(`vfx_treasureAttention_glow_${root.uniqueId}`, scene, {
+          blurKernelSize: params.bloomKernelSize,
+          mainTextureRatio: 0.4
+        });
+        ownsGlowLayer = true;
+      }
+      for (const mesh of meshes) addGlowMesh(mesh);
+    }
+    if (ownsGlowLayer && glowLayer) {
+      glowLayer.intensity = params.bloomIntensity;
+      glowLayer.blurKernelSize = params.bloomKernelSize;
+    }
+  }
+  function syncRoot() {
+    if (serviceOwnedRoot) return;
+    if (target) {
+      root.position.copyFrom(target.getAbsolutePosition());
+      return;
+    }
+    root.position.copyFrom(basePosition);
+  }
+  function animate(dt) {
+    const pulse = 0.5 + 0.5 * Math.sin(elapsed * 5.2);
+    const auraSize = params.radius * 2.55 * (0.96 + pulse * 0.11);
+    const ringSize = params.radius * 2.15 * (0.94 + pulse * 0.08);
+    aura.scaling.set(auraSize, auraSize, 1);
+    aura.visibility = clamp((0.72 + pulse * 0.24) * params.opacity * params.auraOpacity, 0, 1);
+    ring.rotation.z += dt * 0.65;
+    ring.scaling.set(ringSize, ringSize, 1);
+    ring.visibility = clamp((0.55 + pulse * 0.36) * params.opacity * params.ringOpacity, 0, 1);
+    beam.scaling.x = Math.max(0.02, params.radius * 1.05) * (0.85 + pulse * 0.28);
+    beam.scaling.y = Math.max(0.02, params.height);
+    beam.visibility = clamp((0.35 + pulse * 0.28) * params.opacity * params.beamOpacity, 0, 1);
+    raysRoot.rotation.y += dt * params.spinSpeed;
+    for (let i = 0; i < rayMeshes.length; i += 1) {
+      const q = 0.5 + 0.5 * Math.sin(elapsed * 4.4 + i * 0.9);
+      const ray = rayMeshes[i];
+      ray.visibility = clamp((0.42 + q * 0.42) * params.opacity, 0, 1);
+      ray.scaling.x = 0.92 + q * 0.18;
+      ray.scaling.z = 0.82 + q * 0.35;
+    }
+    if (ownsGlowLayer && glowLayer) {
+      glowLayer.intensity = params.bloomIntensity * (0.75 + pulse * 0.35);
+    }
+  }
+  function disposeAll() {
+    if (disposed) return;
+    disposed = true;
+    scene.onBeforeRenderObservable.remove(observer);
+    particleSystem.stop();
+    particleSystem.dispose(false);
+    if (glowLayer) {
+      for (const mesh of meshes) removeGlowMesh(mesh);
+    }
+    if (ownsGlowLayer) glowLayer?.dispose();
+    for (const mesh of meshes) {
+      mesh.dispose(false, false);
+    }
+    raysRoot.dispose();
+    for (const material of materials) material.dispose();
+    for (const texture of textures) texture.dispose();
+    if (disposeRoot) root.dispose();
+  }
+}
+function makeTexture(scene, textures, name, size, draw) {
+  const texture = new DynamicTexture(name, { width: size, height: size }, scene, false);
+  texture.hasAlpha = true;
+  texture.wrapU = Texture.CLAMP_ADDRESSMODE;
+  texture.wrapV = Texture.CLAMP_ADDRESSMODE;
+  const context = texture.getContext();
+  context.clearRect(0, 0, size, size);
+  draw(context, size);
+  texture.update(false);
+  textures.add(texture);
+  return texture;
+}
+function makeAdditiveMaterial(scene, materials, name, texture) {
+  const material = new StandardMaterial(name, scene);
+  material.diffuseTexture = texture;
+  material.emissiveTexture = texture;
+  material.diffuseColor = Color3.White();
+  material.emissiveColor = Color3.White();
+  material.specularColor = Color3.Black();
+  material.disableLighting = true;
+  material.backFaceCulling = false;
+  material.useAlphaFromDiffuseTexture = true;
+  material.transparencyMode = Material.MATERIAL_ALPHABLEND;
+  material.alphaMode = Constants.ALPHA_ADD;
+  material.disableDepthWrite = true;
+  materials.add(material);
+  return material;
+}
+function createRayMesh(scene, name, length, width) {
+  const mesh = new Mesh(name, scene);
+  const positions = [
+    0,
+    0,
+    -width * 0.5,
+    length,
+    0,
+    -width * 0.12,
+    length,
+    0,
+    width * 0.12,
+    0,
+    0,
+    width * 0.5
+  ];
+  const vertexData = new VertexData();
+  vertexData.positions = positions;
+  vertexData.indices = [0, 1, 2, 0, 2, 3];
+  vertexData.normals = [
+    0,
+    1,
+    0,
+    0,
+    1,
+    0,
+    0,
+    1,
+    0,
+    0,
+    1,
+    0
+  ];
+  vertexData.uvs = [0, 0, 1, 0, 1, 1, 0, 1];
+  vertexData.applyToMesh(mesh, false);
+  return mesh;
+}
+function redrawTexture(texture, size, draw) {
+  const context = texture.getContext();
+  context.clearRect(0, 0, size, size);
+  draw(context, size);
+  texture.update(false);
+}
+function drawAuraTexture(ctx, size, color) {
+  const center = size / 2;
+  const gradient = ctx.createRadialGradient(center, center, 0, center, center, center);
+  gradient.addColorStop(0, colorRgba(color, 0.86));
+  gradient.addColorStop(0.25, colorRgba(color, 0.46));
+  gradient.addColorStop(0.55, colorRgba(color, 0.16));
+  gradient.addColorStop(1, colorRgba(color, 0));
+  ctx.fillStyle = gradient;
+  ctx.fillRect(0, 0, size, size);
+}
+function drawRingTexture(ctx, size, color) {
+  const center = size / 2;
+  ctx.shadowColor = colorRgba(color, 0.9);
+  ctx.shadowBlur = size * 0.05;
+  ctx.strokeStyle = colorRgba(color, 0.78);
+  ctx.lineWidth = size * 0.035;
+  ctx.beginPath();
+  ctx.arc(center, center, size * 0.31, 0, Math.PI * 2);
+  ctx.stroke();
+  ctx.lineWidth = size * 0.012;
+  ctx.strokeStyle = colorRgba(lightenColor(color, 0.58), 0.85);
+  ctx.beginPath();
+  ctx.arc(center, center, size * 0.42, 0, Math.PI * 2);
+  ctx.stroke();
+}
+function drawRayTexture(ctx, size, color) {
+  const gradient = ctx.createLinearGradient(0, 0, size, 0);
+  gradient.addColorStop(0, colorRgba(color, 0));
+  gradient.addColorStop(0.18, colorRgba(lightenColor(color, 0.35), 0.72));
+  gradient.addColorStop(0.55, colorRgba(color, 0.34));
+  gradient.addColorStop(1, colorRgba(color, 0));
+  ctx.fillStyle = gradient;
+  ctx.beginPath();
+  ctx.moveTo(0, size * 0.5);
+  ctx.quadraticCurveTo(size * 0.45, size * 0.1, size, size * 0.18);
+  ctx.lineTo(size, size * 0.82);
+  ctx.quadraticCurveTo(size * 0.45, size * 0.9, 0, size * 0.5);
+  ctx.closePath();
+  ctx.fill();
+}
+function drawBeamTexture(ctx, size, color) {
+  const center = size / 2;
+  const radial = ctx.createRadialGradient(center, center, 0, center, center, center * 0.55);
+  radial.addColorStop(0, colorRgba(lightenColor(color, 0.65), 0.75));
+  radial.addColorStop(0.28, colorRgba(color, 0.35));
+  radial.addColorStop(1, colorRgba(color, 0));
+  ctx.fillStyle = radial;
+  ctx.fillRect(0, 0, size, size);
+  const vertical = ctx.createLinearGradient(0, 0, 0, size);
+  vertical.addColorStop(0, colorRgba(color, 0));
+  vertical.addColorStop(0.42, colorRgba(lightenColor(color, 0.42), 0.42));
+  vertical.addColorStop(0.62, colorRgba(lightenColor(color, 0.42), 0.42));
+  vertical.addColorStop(1, colorRgba(color, 0));
+  ctx.fillStyle = vertical;
+  ctx.fillRect(size * 0.43, 0, size * 0.14, size);
+}
+function drawSparkleTexture(ctx, size) {
+  const center = size / 2;
+  ctx.save();
+  ctx.translate(center, center);
+  ctx.shadowColor = "rgba(255,255,255,1)";
+  ctx.shadowBlur = size * 0.12;
+  ctx.fillStyle = "rgba(255,255,255,0.95)";
+  ctx.beginPath();
+  for (let i = 0; i < 8; i += 1) {
+    const angle = i * Math.PI / 4;
+    const radius = i % 2 === 0 ? size * 0.42 : size * 0.12;
+    const x = Math.cos(angle) * radius;
+    const y = Math.sin(angle) * radius;
+    if (i === 0) ctx.moveTo(x, y);
+    else ctx.lineTo(x, y);
+  }
+  ctx.closePath();
+  ctx.fill();
+  ctx.restore();
+}
+function mergeParams(patch, base = DEFAULT_PARAMS) {
+  return {
+    ...base,
+    ...patch,
+    color: copyColor(patch?.color, base.color),
+    auraColor: copyColor(patch?.auraColor, base.auraColor),
+    ringColor: copyColor(patch?.ringColor, base.ringColor),
+    rayColor: copyColor(patch?.rayColor, base.rayColor),
+    beamColor: copyColor(patch?.beamColor, base.beamColor)
+  };
+}
+function copyColor(value, fallback) {
+  return value ? { ...value } : { ...fallback };
+}
+function tintColor(color, brightness, alpha) {
+  return new Color4(
+    Math.max(0, color.r * brightness),
+    Math.max(0, color.g * brightness),
+    Math.max(0, color.b * brightness),
+    clamp(alpha, 0, 1)
+  );
+}
+function colorRgba(color, alpha) {
+  const r = Math.round(clamp(color.r, 0, 1) * 255);
+  const g = Math.round(clamp(color.g, 0, 1) * 255);
+  const b = Math.round(clamp(color.b, 0, 1) * 255);
+  return `rgba(${r},${g},${b},${clamp(alpha, 0, 1)})`;
+}
+function lightenColor(color, amount) {
+  const t = clamp(amount, 0, 1);
+  return {
+    r: color.r + (1 - color.r) * t,
+    g: color.g + (1 - color.g) * t,
+    b: color.b + (1 - color.b) * t
+  };
+}
+function clamp(value, min, max) {
+  return Math.min(max, Math.max(min, value));
+}
+export {
+  createTreasureAttentionFx,
+  treasureAttentionEffectPackage as default,
+  treasureAttentionEffectPackage
+};

package/dist/effects/ufo-thread-flame/index.js

@@ -39,6 +39,7 @@ function excludeFromGlow(scene, mesh) {
 const ufoThreadFlameEffectPackage = {
   id: "ufo-thread-flame",
   nameZh: "UFO丝束尾焰",
+  placement: "socket",
   debugAnchor: "player",
   defaultParams: DEFAULT_PARAMS,
   debugParams: [

package/dist/effects/vehicle-upgrade/index.js

@@ -38,8 +38,11 @@ const DEFAULT_PARAMS = {
 const vehicleUpgradeEffectPackage = {
   id: "vehicle-upgrade",
   nameZh: "建筑&地块&设备升级",
+  placement: "socket",
   manifest,
   defaultParams: DEFAULT_PARAMS,
+  // initialHeight 走 service 存活的 Y 偏移通道(G6/M12)。
+  spawnParams: { offsetY: "initialHeight" },
   debugAnchor: "playerRight",
   debugParams: [
     { key: "lifetime", label: "生命周期", kind: "lifetime", min: 0.2, max: 6, step: 0.01 },
@@ -59,7 +62,7 @@ const vehicleUpgradeEffectPackage = {
     { key: "glowOpacity", label: "光幕强度", kind: "opacity", min: 0, max: 1, step: 0.01 }
   ],
   create({ scene, root, position, params }) {
-    root.position.copyFrom(position).addInPlace(new Vector3(0, params.initialHeight, 0));
+    root.position.copyFrom(position);
     const centerStrands = createStrandSystem(scene, root, params, "center");
     const outlineStrands = createStrandSystem(scene, root, params, "outline");
     const glow = createOutlineGlow(scene, root, params);

package/dist/effects/weapon-trail/index.js

@@ -14,9 +14,10 @@ const trailTextureUrl = "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAP4AAABNC
 const DEFAULT_PARAMS = {
   ...LIFETIME_DEFAULTS,
   orientation: "horizontal",
-  orbitRadius: 1.6,
+  orbitRadius: 0,
   orbitSpeed: 7,
   height: 0,
+  // 默认 0:真实跟随挂点(orbit>0 是演示用的幻影圆周轨道)
   trailLength: 16,
   worldLength: 4,
   width: 1.01,
@@ -90,6 +91,8 @@ function lerpSample(a, b, t, dst) {
 const weaponTrailEffectPackage = {
   id: "weapon-trail",
   nameZh: "武器拖尾",
+  placement: "socket",
+  geometrySpace: "world",
   debugAnchor: "player",
   defaultParams: DEFAULT_PARAMS,
   debugParams: [
@@ -120,8 +123,9 @@ const weaponTrailEffectPackage = {
     { key: "sparkRate", label: "刃头火花/秒", kind: "number", min: 0, max: 80, step: 1 },
     { key: "tint", label: "颜色", kind: "color" }
   ],
-  create({ scene, root, position, params }) {
+  create({ scene, root, position, params, renderingGroupId }) {
     root.position.copyFrom(position);
+    const rgid = renderingGroupId ?? 0;
     registerShaders();
     const blend = params.blendMode === "combine" ? Constants.ALPHA_COMBINE : Constants.ALPHA_ADD;
     const tex = new Texture(trailTextureUrl, scene, true, false);
@@ -162,7 +166,7 @@ const weaponTrailEffectPackage = {
       m.alwaysSelectAsActiveMesh = true;
       m.useVertexColors = true;
       m.hasVertexAlpha = true;
-      m.renderingGroupId = 0;
+      m.renderingGroupId = rgid;
       m.alphaIndex = ai;
       return m;
     }
@@ -185,6 +189,7 @@ const weaponTrailEffectPackage = {
       const c255 = `${Math.round(params.tint.r * 255)},${Math.round(params.tint.g * 255)},${Math.round(params.tint.b * 255)}`;
       const flare = makeFlareTexture(scene, "vfx_weaponTrail_sparkTex", "255,255,255", c255);
       sparkPs = new ParticleSystem("vfx_weaponTrail_sparks", 160, scene);
+      sparkPs.renderingGroupId = rgid;
       sparkPs.particleTexture = flare;
       sparkPs.emitter = sparkEmitter;
       sparkPs.minSize = 0.07;

package/dist/effects/wood_crusher_sawdust/index.d.ts

@@ -12,5 +12,9 @@ export declare const woodCrusherSawdustEffectPackage: {
     spawnParams?: import('../..').VfxSpawnParamKeys;
     savedParams?: Partial<import('../..').VfxParamValues>;
     debugParams: import('../..').VfxParamDefinition[];
+    placement?: import('../..').VfxPlacement;
+    requiredInputs?: import('../..').VfxInputKey[];
+    optionalInputs?: import('../..').VfxInputKey[];
+    geometrySpace?: "local" | "world";
     create(context: import('../..').VfxEffectPackageContext<import('../..').VfxParamValues>): import('../..').VfxEffectHandle;
 };

package/dist/effects/wood_cutter_sawdust/index.d.ts

@@ -12,5 +12,9 @@ export declare const woodCutterSawdustEffectPackage: {
     spawnParams?: import('../..').VfxSpawnParamKeys;
     savedParams?: Partial<import('../..').VfxParamValues>;
     debugParams: import('../..').VfxParamDefinition[];
+    placement?: import('../..').VfxPlacement;
+    requiredInputs?: import('../..').VfxInputKey[];
+    optionalInputs?: import('../..').VfxInputKey[];
+    geometrySpace?: "local" | "world";
     create(context: import('../..').VfxEffectPackageContext<import('../..').VfxParamValues>): import('../..').VfxEffectHandle;
 };