@fps-games/vfx 0.1.1 → 0.3.2

package/packages/effects/treasure-attention/index.ts

@@ -0,0 +1,630 @@
+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 type { AbstractMesh } from '@babylonjs/core/Meshes/abstractMesh';
+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 type { Scene } from '@babylonjs/core/scene';
+import { configureVfxParticleSystem, VFX_RENDERING_GROUP_ID } from '../../rendering';
+import type { VfxColorValue, VfxEffectHandle, VfxEffectPackage, VfxParamValues } from '../../types';
+
+export interface TreasureAttentionParams extends VfxParamValues {
+  radius: number;
+  yOffset: number;
+  height: number;
+  rays: number;
+  rayWidth: number;
+  spinSpeed: number;
+  color: VfxColorValue;
+  auraColor: VfxColorValue;
+  ringColor: VfxColorValue;
+  rayColor: VfxColorValue;
+  beamColor: VfxColorValue;
+  opacity: number;
+  auraOpacity: number;
+  ringOpacity: number;
+  beamOpacity: number;
+  particleRate: number;
+  particleLife: number;
+  sparkleMinSize: number;
+  sparkleMaxSize: number;
+  riseSpeed: number;
+  drift: number;
+  bloomIntensity: number;
+  bloomKernelSize: number;
+}
+
+export interface CreateTreasureAttentionOptions {
+  root?: TransformNode;
+  target?: TransformNode | AbstractMesh | null;
+  position?: Vector3;
+  params?: Partial<TreasureAttentionParams>;
+  renderingGroupId?: number;
+  glowLayer?: GlowLayer | null;
+  disposeRoot?: boolean;
+  /** 经 @fps/vfx 包播放时为 true:root 的 transform 归 service 独占(placement/挂载由 service 管),特效不写 root.position(G6)。 */
+  serviceOwnedRoot?: boolean;
+}
+
+export interface TreasureAttentionHandle extends VfxEffectHandle {
+  root: TransformNode;
+  particleSystem: ParticleSystem;
+  update(params: Partial<TreasureAttentionParams>): void;
+  setEnabled(enabled: boolean): void;
+  setTarget(target: TransformNode | AbstractMesh | null): void;
+  setPosition(position: Vector3): void;
+}
+
+const DEFAULT_PARAMS: TreasureAttentionParams = {
+  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,
+};
+
+export const treasureAttentionEffectPackage: VfxEffectPackage<TreasureAttentionParams> = {
+  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: 0.005 },
+    { 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: 0.005 },
+    { key: 'sparkleMaxSize', label: '闪片最大', kind: 'scale', min: 0.01, max: 0.8, step: 0.005 },
+    { 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 });
+  },
+};
+
+export default treasureAttentionEffectPackage;
+
+export function createTreasureAttentionFx(scene: Scene, options: CreateTreasureAttentionOptions = {}): TreasureAttentionHandle {
+  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();
+  // 内部锚:承载所有 geometry + yOffset 悬浮。root 留给 service(placement/挂载);standalone 才自管 root.position。
+  const fxRoot = new TransformNode('vfx_treasureAttention_fxRoot', scene);
+  fxRoot.parent = root;
+  let enabled = true;
+  let disposed = false;
+  let elapsed = 0;
+  let raySignature = '';
+
+  const textures = new Set<DynamicTexture>();
+  const materials = new Set<StandardMaterial>();
+  const meshes = new Set<Mesh>();
+  let rayMeshes: Mesh[] = [];
+  let glowLayer: GlowLayer | null = 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() / 1000, 0.05);
+    elapsed += dt;
+    syncRoot();
+    animate(dt);
+  });
+
+  return {
+    root,
+    particleSystem,
+    update(partial: Partial<TreasureAttentionParams>) {
+      if (disposed) return;
+      params = mergeParams(partial, params);
+      applyParams();
+      syncRoot();
+    },
+    setEnabled(nextEnabled: boolean) {
+      enabled = nextEnabled;
+      root.setEnabled(nextEnabled);
+      if (nextEnabled) {
+        particleSystem.start();
+      } else {
+        particleSystem.stop();
+      }
+    },
+    setTarget(nextTarget: TransformNode | AbstractMesh | null) {
+      target = nextTarget;
+      syncRoot();
+    },
+    setPosition(position: Vector3) {
+      basePosition.copyFrom(position);
+      syncRoot();
+    },
+    dispose() {
+      disposeAll();
+    },
+  };
+
+  function addMesh<T extends Mesh>(mesh: T, includeInGlow = true): T {
+    mesh.isPickable = false;
+    mesh.alwaysSelectAsActiveMesh = true;
+    mesh.renderingGroupId = renderingGroupId;
+    meshes.add(mesh);
+    if (includeInGlow) addGlowMesh(mesh);
+    return mesh;
+  }
+
+  function addGlowMesh(mesh: Mesh): void {
+    if (!glowLayer || !mesh.material) return;
+    glowLayer.addIncludedOnlyMesh(mesh);
+    glowLayer.referenceMeshToUseItsOwnMaterial(mesh);
+  }
+
+  function removeGlowMesh(mesh: Mesh): void {
+    glowLayer?.removeIncludedOnlyMesh(mesh);
+  }
+
+  function applyParams(): void {
+    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;   // 悬浮高度统一在内部锚上(不写 root,root 归 service)
+    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(0.001, 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(): void {
+    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 * 0.001;
+      ray.material = rayMat;
+      ray.alphaIndex = 2;
+      addMesh(ray);
+      rayMeshes.push(ray);
+    }
+  }
+
+  function syncGlowLayer(): void {
+    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(): void {
+    // service 路径:root 的位置/挂载由 service 独占(placement socket),特效不碰 root(G6)。yOffset 已在 fxRoot 上。
+    if (serviceOwnedRoot) return;
+    // standalone 路径(直接调 createTreasureAttentionFx):自管 root 位置;target 给了就跟随,否则停在 basePosition。
+    if (target) { root.position.copyFrom(target.getAbsolutePosition()); return; }
+    root.position.copyFrom(basePosition);
+  }
+
+  function animate(dt: number): void {
+    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(): void {
+    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: Scene,
+  textures: Set<DynamicTexture>,
+  name: string,
+  size: number,
+  draw: (ctx: CanvasRenderingContext2D, size: number) => void,
+): DynamicTexture {
+  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() as unknown as CanvasRenderingContext2D;
+  context.clearRect(0, 0, size, size);
+  draw(context, size);
+  texture.update(false);
+  textures.add(texture);
+  return texture;
+}
+
+function makeAdditiveMaterial(
+  scene: Scene,
+  materials: Set<StandardMaterial>,
+  name: string,
+  texture: DynamicTexture,
+): StandardMaterial {
+  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: Scene, name: string, length: number, width: number): Mesh {
+  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: DynamicTexture,
+  size: number,
+  draw: (ctx: CanvasRenderingContext2D, size: number) => void,
+): void {
+  const context = texture.getContext() as unknown as CanvasRenderingContext2D;
+  context.clearRect(0, 0, size, size);
+  draw(context, size);
+  texture.update(false);
+}
+
+function drawAuraTexture(ctx: CanvasRenderingContext2D, size: number, color: VfxColorValue): void {
+  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: CanvasRenderingContext2D, size: number, color: VfxColorValue): void {
+  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: CanvasRenderingContext2D, size: number, color: VfxColorValue): void {
+  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: CanvasRenderingContext2D, size: number, color: VfxColorValue): void {
+  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: CanvasRenderingContext2D, size: number): void {
+  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: Partial<TreasureAttentionParams> | undefined,
+  base: TreasureAttentionParams = DEFAULT_PARAMS,
+): TreasureAttentionParams {
+  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: VfxColorValue | undefined, fallback: VfxColorValue): VfxColorValue {
+  return value ? { ...value } : { ...fallback };
+}
+
+function tintColor(color: VfxColorValue, brightness: number, alpha: number): Color4 {
+  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: VfxColorValue, alpha: number): string {
+  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: VfxColorValue, amount: number): VfxColorValue {
+  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: number, min: number, max: number): number {
+  return Math.min(max, Math.max(min, value));
+}

package/packages/effects/treasure-attention/vfx-params.json

@@ -0,0 +1,49 @@
+{
+  "schemaVersion": "vfx-params/1.0",
+  "effectId": "treasure-attention",
+  "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
+  }
+}

package/packages/effects/ufo-thread-flame/index.ts

@@ -51,6 +51,7 @@ function excludeFromGlow(scene: Scene, mesh: AbstractMesh): void {
 export const ufoThreadFlameEffectPackage: VfxEffectPackage<UfoThreadFlameParams> = {
   id: 'ufo-thread-flame',
   nameZh: 'UFO丝束尾焰',
+  placement: 'socket',
   debugAnchor: 'player',
   defaultParams: DEFAULT_PARAMS,
   debugParams: [