@fps-games/vfx 0.1.1 → 0.3.2

package/docs/treasure_attention_fx_babylonjs_guide.md

@@ -0,0 +1,901 @@
+# 宝藏注意力特效实现文档
+
+目标：实现一个类似截图中“宝藏/掉落物周围发光、闪烁、旋转”的游戏特效，用来吸引玩家注意。主实现目标是 **Babylon.js**。本文档也包含 Canvas 2D 原型思路，方便本地 coding agent 先快速验证视觉节奏。
+
+---
+
+## 1. 视觉拆解
+
+这个特效可以拆成 5 层，从下到上绘制：
+
+1. **地面柔光光斑**
+   - 一个贴在地面的半透明金黄色圆/椭圆光斑。
+   - 使用径向渐变贴图。
+   - 缓慢脉冲缩放和透明度变化。
+
+2. **地面旋转星芒**
+   - 多片从中心向外发散的金黄色光束。
+   - 绕 Y 轴慢速旋转。
+   - 每片光束独立做轻微明暗变化，避免机械感。
+
+3. **脉冲光环**
+   - 一到两个贴地光环。
+   - 缩放 + 透明度脉冲。
+   - 用来强调“这里有可交互/可拾取物”。
+
+4. **竖向柔光**
+   - 宝藏中心附近有一个竖向的淡黄色 billboard 光柱。
+   - 视觉上类似“宝物在发光”。
+
+5. **上浮闪片粒子**
+   - 小星星/菱形亮片从宝物附近向上浮起、旋转、淡出。
+   - 使用 additive blending。
+   - 粒子数量不要太多，否则会抢主体。
+
+---
+
+## 2. Babylon.js 实现原则
+
+建议实现为一个可复用函数：
+
+```js
+const fx = createTreasureAttentionFx(scene, targetMesh, options);
+```
+
+其中：
+
+- `scene`：Babylon.js 场景。
+- `targetMesh`：宝藏 mesh、掉落物 mesh 或任意带 `getAbsolutePosition()` 的对象。
+- `options`：半径、粒子密度、旋转速度、发光强度等参数。
+
+核心设计：
+
+- 不依赖外部图片资源。
+- 所有光纹贴图用 `BABYLON.DynamicTexture` 现场绘制。
+- 使用 unlit/additive 材质，避免受到场景灯光影响。
+- 使用 `ParticleSystem` 做上浮闪片。
+- 使用 `GlowLayer` 增强发光，但生产环境建议复用全局 `GlowLayer`。
+- 暴露 `setEnabled()` 和 `dispose()`，方便对象池或掉落物生命周期管理。
+
+---
+
+## 3. 推荐文件结构
+
+建议 coding agent 创建：
+
+```txt
+src/
+  effects/
+    createTreasureAttentionFx.js
+```
+
+如果项目是 TypeScript，可以改成：
+
+```txt
+src/
+  effects/
+    createTreasureAttentionFx.ts
+```
+
+并给 `options` 补类型即可。
+
+---
+
+## 4. Babylon.js 完整实现代码
+
+> 下面代码可以直接作为 `createTreasureAttentionFx.js` 使用。  
+> 默认假设 Babylon.js 已经通过全局变量 `BABYLON` 可用。如果项目使用模块化导入，可以把 `BABYLON` 替换成 import 进来的命名空间。
+
+```js
+export function createTreasureAttentionFx(scene, target, options = {}) {
+  const B = BABYLON;
+
+  const o = Object.assign({
+    radius: 1.15,
+    yOffset: 0.05,
+    height: 1.35,
+    rays: 9,
+    rayWidth: 0.34,
+    spinSpeed: 0.85,
+    particleRate: 42,
+    glowIntensity: 0.7,
+    glowLayer: null
+  }, options);
+
+  const root = new B.TransformNode("treasureAttentionFx", scene);
+  const raysRoot = new B.TransformNode("treasureAttentionFx_rays", scene);
+  raysRoot.parent = root;
+
+  const textures = [];
+  const materials = [];
+  const meshes = [];
+
+  const paleGold = new B.Color3(1.0, 0.94, 0.35);
+
+  const makeTex = (name, size, draw) => {
+    const tex = new B.DynamicTexture(name, { width: size, height: size }, scene, false);
+    tex.hasAlpha = true;
+    tex.wrapU = tex.wrapV = B.Texture.CLAMP_ADDRESSMODE;
+
+    const ctx = tex.getContext();
+    ctx.clearRect(0, 0, size, size);
+    draw(ctx, size);
+    tex.update(false);
+
+    textures.push(tex);
+    return tex;
+  };
+
+  const makeAddMat = (name, tex, alpha = 1) => {
+    const mat = new B.StandardMaterial(name, scene);
+    mat.diffuseTexture = tex;
+    mat.emissiveTexture = tex;
+    mat.emissiveColor = paleGold;
+    mat.diffuseColor = B.Color3.Black();
+    mat.alpha = alpha;
+    mat.disableLighting = true;
+    mat.backFaceCulling = false;
+    mat.useAlphaFromDiffuseTexture = true;
+    mat.transparencyMode = B.Material.MATERIAL_ALPHABLEND;
+    mat.alphaMode = B.Engine.ALPHA_ADD;
+
+    // 贴地光效容易和地面深度冲突，关闭 depth write 可以减少闪烁。
+    // 如果项目有严格的透明物排序策略，可以按项目规则调整。
+    mat.disableDepthWrite = true;
+
+    materials.push(mat);
+    return mat;
+  };
+
+  const auraTex = makeTex("treasureFx_auraTex", 256, (ctx, s) => {
+    const c = s / 2;
+    const g = ctx.createRadialGradient(c, c, 0, c, c, c);
+    g.addColorStop(0.00, "rgba(255,255,190,0.85)");
+    g.addColorStop(0.25, "rgba(255,235,80,0.45)");
+    g.addColorStop(0.55, "rgba(255,210,30,0.16)");
+    g.addColorStop(1.00, "rgba(255,210,30,0.00)");
+    ctx.fillStyle = g;
+    ctx.fillRect(0, 0, s, s);
+  });
+
+  const ringTex = makeTex("treasureFx_ringTex", 256, (ctx, s) => {
+    const c = s / 2;
+
+    ctx.shadowColor = "rgba(255,245,120,0.9)";
+    ctx.shadowBlur = s * 0.05;
+
+    ctx.strokeStyle = "rgba(255,242,80,0.78)";
+    ctx.lineWidth = s * 0.035;
+    ctx.beginPath();
+    ctx.arc(c, c, s * 0.31, 0, Math.PI * 2);
+    ctx.stroke();
+
+    ctx.lineWidth = s * 0.012;
+    ctx.strokeStyle = "rgba(255,255,220,0.85)";
+    ctx.beginPath();
+    ctx.arc(c, c, s * 0.42, 0, Math.PI * 2);
+    ctx.stroke();
+  });
+
+  const rayTex = makeTex("treasureFx_rayTex", 256, (ctx, s) => {
+    const g = ctx.createLinearGradient(0, 0, s, 0);
+    g.addColorStop(0.00, "rgba(255,255,170,0.00)");
+    g.addColorStop(0.18, "rgba(255,250,110,0.70)");
+    g.addColorStop(0.55, "rgba(255,220,45,0.34)");
+    g.addColorStop(1.00, "rgba(255,210,25,0.00)");
+
+    ctx.fillStyle = g;
+    ctx.beginPath();
+    ctx.moveTo(0, s * 0.50);
+    ctx.quadraticCurveTo(s * 0.45, s * 0.10, s, s * 0.18);
+    ctx.lineTo(s, s * 0.82);
+    ctx.quadraticCurveTo(s * 0.45, s * 0.90, 0, s * 0.50);
+    ctx.closePath();
+    ctx.fill();
+  });
+
+  const beamTex = makeTex("treasureFx_beamTex", 256, (ctx, s) => {
+    const c = s / 2;
+
+    const radial = ctx.createRadialGradient(c, c, 0, c, c, c * 0.55);
+    radial.addColorStop(0.00, "rgba(255,255,220,0.75)");
+    radial.addColorStop(0.28, "rgba(255,245,100,0.35)");
+    radial.addColorStop(1.00, "rgba(255,220,40,0.00)");
+    ctx.fillStyle = radial;
+    ctx.fillRect(0, 0, s, s);
+
+    const vertical = ctx.createLinearGradient(0, 0, 0, s);
+    vertical.addColorStop(0.00, "rgba(255,255,220,0.00)");
+    vertical.addColorStop(0.42, "rgba(255,245,90,0.42)");
+    vertical.addColorStop(0.62, "rgba(255,245,90,0.42)");
+    vertical.addColorStop(1.00, "rgba(255,220,30,0.00)");
+    ctx.fillStyle = vertical;
+    ctx.fillRect(s * 0.43, 0, s * 0.14, s);
+  });
+
+  const sparkleTex = makeTex("treasureFx_sparkleTex", 128, (ctx, s) => {
+    const c = s / 2;
+
+    ctx.save();
+    ctx.translate(c, c);
+    ctx.shadowColor = "rgba(255,245,120,1)";
+    ctx.shadowBlur = s * 0.12;
+    ctx.fillStyle = "rgba(255,255,210,0.95)";
+
+    ctx.beginPath();
+    for (let i = 0; i < 8; i++) {
+      const a = i * Math.PI / 4;
+      const r = i % 2 === 0 ? s * 0.42 : s * 0.12;
+      const x = Math.cos(a) * r;
+      const y = Math.sin(a) * r;
+      i ? ctx.lineTo(x, y) : ctx.moveTo(x, y);
+    }
+    ctx.closePath();
+    ctx.fill();
+
+    ctx.restore();
+  });
+
+  const auraMat = makeAddMat("treasureFx_auraMat", auraTex, 0.85);
+  const ringMat = makeAddMat("treasureFx_ringMat", ringTex, 0.95);
+  const rayMat = makeAddMat("treasureFx_rayMat", rayTex, 0.9);
+  const beamMat = makeAddMat("treasureFx_beamMat", beamTex, 0.72);
+
+  const aura = B.MeshBuilder.CreatePlane("treasureFx_aura", { size: o.radius * 2.55 }, scene);
+  aura.rotation.x = Math.PI / 2;
+  aura.position.y = 0.025;
+  aura.material = auraMat;
+  aura.parent = root;
+  aura.renderingGroupId = 2;
+  meshes.push(aura);
+
+  const ring = B.MeshBuilder.CreatePlane("treasureFx_ring", { size: o.radius * 2.15 }, scene);
+  ring.rotation.x = Math.PI / 2;
+  ring.position.y = 0.04;
+  ring.material = ringMat;
+  ring.parent = root;
+  ring.renderingGroupId = 2;
+  meshes.push(ring);
+
+  const beam = B.MeshBuilder.CreatePlane("treasureFx_beam", {
+    width: o.radius * 1.05,
+    height: o.height
+  }, scene);
+  beam.position.y = o.height * 0.52;
+  beam.billboardMode = B.Mesh.BILLBOARDMODE_Y;
+  beam.material = beamMat;
+  beam.parent = root;
+  beam.renderingGroupId = 2;
+  meshes.push(beam);
+
+  const createRayMesh = (name, length, width) => {
+    const mesh = new B.Mesh(name, scene);
+
+    const positions = [
+      0,      0, -width * 0.50,
+      length, 0, -width * 0.12,
+      length, 0,  width * 0.12,
+      0,      0,  width * 0.50
+    ];
+
+    const indices = [0, 1, 2, 0, 2, 3];
+    const normals = [];
+    B.VertexData.ComputeNormals(positions, indices, normals);
+
+    const vd = new B.VertexData();
+    vd.positions = positions;
+    vd.indices = indices;
+    vd.normals = normals;
+    vd.uvs = [0, 0, 1, 0, 1, 1, 0, 1];
+    vd.applyToMesh(mesh, true);
+
+    return mesh;
+  };
+
+  const rays = [];
+  for (let i = 0; i < o.rays; i++) {
+    const angle = i / o.rays * Math.PI * 2;
+    const length = o.radius * (0.95 + (i % 3) * 0.13);
+    const width = o.rayWidth * (0.8 + (i % 2) * 0.22);
+
+    const ray = createRayMesh(`treasureFx_ray_${i}`, length, width);
+    ray.parent = raysRoot;
+    ray.rotation.y = angle;
+    ray.position.y = 0.055 + i * 0.001;
+    ray.material = rayMat;
+    ray.renderingGroupId = 2;
+
+    rays.push(ray);
+    meshes.push(ray);
+  }
+
+  const emitter = new B.Mesh("treasureFx_particleEmitter", scene);
+  emitter.isVisible = false;
+  emitter.parent = root;
+  meshes.push(emitter);
+
+  const ps = new B.ParticleSystem("treasureFx_sparkles", 160, scene);
+  ps.particleTexture = sparkleTex;
+  ps.emitter = emitter;
+
+  ps.minEmitBox = new B.Vector3(-o.radius * 0.45, 0.15, -o.radius * 0.45);
+  ps.maxEmitBox = new B.Vector3( o.radius * 0.45, 0.55,  o.radius * 0.45);
+
+  ps.color1 = new B.Color4(1, 0.92, 0.24, 0.95);
+  ps.color2 = new B.Color4(1, 1, 0.72, 0.75);
+  ps.colorDead = new B.Color4(1, 0.75, 0.15, 0);
+
+  ps.minSize = 0.045;
+  ps.maxSize = 0.13;
+  ps.minLifeTime = 0.45;
+  ps.maxLifeTime = 0.95;
+  ps.emitRate = o.particleRate;
+  ps.blendMode = B.ParticleSystem.BLENDMODE_ADD;
+
+  ps.gravity = new B.Vector3(0, -0.04, 0);
+  ps.direction1 = new B.Vector3(-0.12, 0.55, -0.12);
+  ps.direction2 = new B.Vector3( 0.12, 0.95,  0.12);
+  ps.minAngularSpeed = -4;
+  ps.maxAngularSpeed = 4;
+  ps.minEmitPower = 0.18;
+  ps.maxEmitPower = 0.42;
+  ps.updateSpeed = 0.016;
+
+  ps.start();
+
+  const ownsGlow = !o.glowLayer;
+  const glow = o.glowLayer || new B.GlowLayer("treasureFx_glowLayer", scene, { blurKernelSize: 32 });
+
+  if (ownsGlow) {
+    glow.intensity = o.glowIntensity;
+  }
+
+  if (glow.addIncludedOnlyMesh) {
+    meshes.filter(m => m.material).forEach(m => glow.addIncludedOnlyMesh(m));
+  }
+
+  const syncRoot = () => {
+    if (!target) {
+      root.position.set(0, o.yOffset, 0);
+      return;
+    }
+
+    if (typeof target.getAbsolutePosition === "function") {
+      const p = target.getAbsolutePosition();
+      root.position.set(p.x, p.y + o.yOffset, p.z);
+      return;
+    }
+
+    root.position.set(target.x || 0, (target.y || 0) + o.yOffset, target.z || 0);
+  };
+
+  let time = 0;
+
+  const observer = scene.onBeforeRenderObservable.add(() => {
+    const dt = scene.getEngine().getDeltaTime() * 0.001;
+    time += dt;
+    syncRoot();
+
+    const pulse = 0.5 + 0.5 * Math.sin(time * 5.2);
+
+    aura.scaling.setAll(0.96 + pulse * 0.11);
+    aura.visibility = 0.72 + pulse * 0.24;
+
+    ring.rotation.z += dt * 0.65;
+    ring.scaling.setAll(0.94 + pulse * 0.08);
+    ring.visibility = 0.55 + pulse * 0.36;
+
+    beam.scaling.x = 0.85 + pulse * 0.28;
+    beam.visibility = 0.35 + pulse * 0.28;
+
+    raysRoot.rotation.y += dt * o.spinSpeed;
+
+    for (let i = 0; i < rays.length; i++) {
+      const q = 0.5 + 0.5 * Math.sin(time * 4.4 + i * 0.9);
+      rays[i].visibility = 0.42 + q * 0.42;
+      rays[i].scaling.x = 0.92 + q * 0.18;
+      rays[i].scaling.z = 0.82 + q * 0.35;
+    }
+
+    // 不建议在复用全局 GlowLayer 时反复改全局 intensity，
+    // 因为会影响场景里其他发光对象。
+    if (ownsGlow) {
+      glow.intensity = o.glowIntensity * (0.75 + pulse * 0.35);
+    }
+  });
+
+  syncRoot();
+
+  return {
+    root,
+    particleSystem: ps,
+    meshes,
+    materials,
+    textures,
+
+    setEnabled(enabled) {
+      root.setEnabled(enabled);
+      if (enabled) {
+        ps.start();
+      } else {
+        ps.stop();
+      }
+    },
+
+    setTarget(nextTarget) {
+      target = nextTarget;
+      syncRoot();
+    },
+
+    dispose() {
+      scene.onBeforeRenderObservable.remove(observer);
+
+      ps.dispose();
+
+      meshes.forEach(m => {
+        if (m && !m.isDisposed()) {
+          m.dispose();
+        }
+      });
+
+      materials.forEach(m => {
+        if (m) {
+          m.dispose();
+        }
+      });
+
+      textures.forEach(t => {
+        if (t) {
+          t.dispose();
+        }
+      });
+
+      root.dispose();
+
+      if (ownsGlow) {
+        glow.dispose();
+      }
+    }
+  };
+}
+```
+
+---
+
+## 5. 使用示例
+
+### 5.1 普通用法
+
+```js
+import { createTreasureAttentionFx } from "./effects/createTreasureAttentionFx.js";
+
+const treasure = scene.getMeshByName("TreasureChest");
+
+const fx = createTreasureAttentionFx(scene, treasure, {
+  radius: 1.05,
+  yOffset: 0.04,
+  height: 1.25,
+  particleRate: 55,
+  glowIntensity: 0.8
+});
+```
+
+### 5.2 复用全局 GlowLayer
+
+如果一个场景里有多个宝藏/掉落物，不要每个特效都创建一个 `GlowLayer`。推荐全局复用：
+
+```js
+const sharedGlow = new BABYLON.GlowLayer("sharedGlow", scene, {
+  blurKernelSize: 32
+});
+
+sharedGlow.intensity = 0.65;
+
+const fx1 = createTreasureAttentionFx(scene, treasureA, {
+  glowLayer: sharedGlow,
+  radius: 1.1
+});
+
+const fx2 = createTreasureAttentionFx(scene, treasureB, {
+  glowLayer: sharedGlow,
+  radius: 0.9,
+  particleRate: 30
+});
+```
+
+### 5.3 跟随掉落物对象池
+
+```js
+const fx = createTreasureAttentionFx(scene, dropMesh, {
+  radius: 0.9,
+  particleRate: 35
+});
+
+dropMesh.onDisposeObservable.add(() => {
+  fx.dispose();
+});
+```
+
+如果掉落物对象池复用 mesh，可以保留 fx，切换 target：
+
+```js
+fx.setTarget(newDropMesh);
+fx.setEnabled(true);
+```
+
+---
+
+## 6. 参数说明
+
+| 参数 | 默认值 | 说明 |
+|---|---:|---|
+| `radius` | `1.15` | 地面光斑和星芒半径。宝物越大，这个值越大。 |
+| `yOffset` | `0.05` | 特效根节点相对目标位置的 Y 偏移。用于避免地面 z-fighting。 |
+| `height` | `1.35` | 竖向柔光高度。 |
+| `rays` | `9` | 星芒光束数量。建议 7～12。 |
+| `rayWidth` | `0.34` | 单片星芒宽度。 |
+| `spinSpeed` | `0.85` | 星芒旋转速度，单位大致是 rad/s。 |
+| `particleRate` | `42` | 每秒发射的闪片数量。移动端建议 20～35。 |
+| `glowIntensity` | `0.7` | 自建 GlowLayer 时使用的强度。复用全局 GlowLayer 时不主动改全局强度。 |
+| `glowLayer` | `null` | 可传入项目里的共享 GlowLayer。 |
+
+---
+
+## 7. 调参建议
+
+### 更像“稀有宝藏”
+
+```js
+createTreasureAttentionFx(scene, treasure, {
+  radius: 1.35,
+  height: 1.6,
+  rays: 11,
+  particleRate: 70,
+  spinSpeed: 1.1,
+  glowIntensity: 0.95
+});
+```
+
+### 更像“普通可拾取物”
+
+```js
+createTreasureAttentionFx(scene, drop, {
+  radius: 0.75,
+  height: 0.8,
+  rays: 7,
+  particleRate: 20,
+  spinSpeed: 0.55,
+  glowIntensity: 0.45
+});
+```
+
+### 更像“任务目标/交互点”
+
+```js
+createTreasureAttentionFx(scene, interactable, {
+  radius: 1.0,
+  height: 1.1,
+  particleRate: 15,
+  spinSpeed: 0.35
+});
+```
+
+---
+
+## 8. 需要 coding agent 注意的坑
+
+### 8.1 地面 z-fighting
+
+贴地 plane 如果和地面完全重合，可能闪烁。
+
+解决方式：
+
+- `aura.position.y = 0.025`
+- `ring.position.y = 0.04`
+- `ray.position.y = 0.055 + i * 0.001`
+- 材质设置 `disableDepthWrite = true`
+- 必要时把 `renderingGroupId` 设置到透明特效组。
+
+### 8.2 透明排序
+
+多个透明 mesh 相互叠加时可能排序异常。
+
+建议：
+
+- 所有光效材质使用 additive blending。
+- 特效 mesh 的 `renderingGroupId` 保持一致。
+- 复杂场景中可以把地面光、竖向光、粒子拆成不同 rendering group。
+
+### 8.3 GlowLayer 复用
+
+`GlowLayer.intensity` 是全局属性，会影响这个 GlowLayer 下所有发光对象。
+
+建议：
+
+- 场景只有一个宝藏特效时，可以让函数内部创建 GlowLayer。
+- 场景中有多个发光对象时，传入共享 GlowLayer。
+- 传入共享 GlowLayer 时，不要在每个特效实例里每帧修改 `glow.intensity`。
+
+### 8.4 顶视角相机
+
+如果相机几乎纯俯视，单个竖向 billboard plane 可能不明显。
+
+可选优化：
+
+- 加两片互相垂直的竖向 beam plane。
+- 或者只保留地面光斑、星芒、粒子，不使用竖向 beam。
+
+### 8.5 移动端性能
+
+如果场景中同时存在很多宝藏特效：
+
+- 粒子池数量从 `160` 降到 `80`。
+- `particleRate` 降到 `15～30`。
+- `rays` 降到 `6～8`。
+- 复用全局 `GlowLayer`。
+- 尽量只给屏幕内或玩家附近的物体开启特效。
+
+---
+
+## 9. Canvas 2D 原型做法
+
+Canvas 版不直接用于 Babylon 场景，但很适合快速调视觉节奏。绘制顺序和 Babylon 版一致：
+
+1. 画地面椭圆径向渐变。
+2. 画旋转光束。
+3. 画竖向柔光。
+4. 画脉冲光环。
+5. 更新并绘制上浮闪片。
+
+核心伪代码：
+
+```js
+class TreasureAttentionFx2D {
+  constructor() {
+    this.particles = [];
+    this.radius = 90;
+    this.particleRate = 48;
+    this.spinSpeed = 0.85;
+  }
+
+  update(dt, x, y) {
+    this.emit(dt, x, y);
+
+    for (const p of this.particles) {
+      p.age += dt;
+      p.x += p.vx * dt;
+      p.y += p.vy * dt;
+      p.rot += p.spin * dt;
+    }
+
+    this.particles = this.particles.filter(p => p.age < p.life);
+  }
+
+  emit(dt, x, y) {
+    const count = this.particleRate * dt;
+    this._carry = (this._carry || 0) + count;
+
+    while (this._carry >= 1) {
+      this._carry -= 1;
+
+      const a = Math.random() * Math.PI * 2;
+      const r = Math.random() * this.radius * 0.35;
+
+      this.particles.push({
+        x: x + Math.cos(a) * r,
+        y: y + Math.sin(a) * r * 0.35 - 12,
+        vx: (Math.random() - 0.5) * 18,
+        vy: -35 - Math.random() * 45,
+        age: 0,
+        life: 0.55 + Math.random() * 0.7,
+        size: 4 + Math.random() * 7,
+        rot: Math.random() * Math.PI * 2,
+        spin: -5 + Math.random() * 10
+      });
+    }
+  }
+
+  draw(ctx, x, y, t) {
+    const pulse = 0.5 + 0.5 * Math.sin(t * 5.2);
+
+    this.drawGroundAura(ctx, x, y, pulse);
+    this.drawRays(ctx, x, y - 8, t, pulse);
+    this.drawVerticalGlow(ctx, x, y - 32, pulse);
+    this.drawPulseRing(ctx, x, y, pulse);
+    this.drawParticles(ctx);
+  }
+
+  drawGroundAura(ctx, x, y, pulse) {
+    const r = this.radius * (0.95 + pulse * 0.12);
+
+    ctx.save();
+    ctx.translate(x, y);
+    ctx.scale(1, 0.42);
+
+    const g = ctx.createRadialGradient(0, 0, 0, 0, 0, r);
+    g.addColorStop(0.00, "rgba(255,255,180,0.78)");
+    g.addColorStop(0.35, "rgba(255,225,55,0.32)");
+    g.addColorStop(1.00, "rgba(255,210,20,0)");
+
+    ctx.fillStyle = g;
+    ctx.beginPath();
+    ctx.arc(0, 0, r, 0, Math.PI * 2);
+    ctx.fill();
+
+    ctx.restore();
+  }
+
+  drawRays(ctx, x, y, t, pulse) {
+    const rays = 9;
+    const base = t * this.spinSpeed;
+
+    ctx.save();
+    ctx.translate(x, y);
+    ctx.globalCompositeOperation = "lighter";
+
+    for (let i = 0; i < rays; i++) {
+      const a = base + i / rays * Math.PI * 2;
+      const len = this.radius * (0.75 + (i % 3) * 0.09);
+      const width = 10 + (i % 2) * 7;
+      const alpha = 0.18 + 0.18 * Math.sin(t * 4.4 + i * 0.9) + pulse * 0.08;
+
+      ctx.save();
+      ctx.rotate(a);
+      const g = ctx.createLinearGradient(0, 0, len, 0);
+      g.addColorStop(0.00, `rgba(255,255,180,${alpha})`);
+      g.addColorStop(0.38, `rgba(255,230,45,${alpha * 0.8})`);
+      g.addColorStop(1.00, "rgba(255,210,20,0)");
+
+      ctx.fillStyle = g;
+      ctx.beginPath();
+      ctx.moveTo(0, -width);
+      ctx.quadraticCurveTo(len * 0.45, -width * 1.4, len, -width * 0.25);
+      ctx.lineTo(len, width * 0.25);
+      ctx.quadraticCurveTo(len * 0.45, width * 1.4, 0, width);
+      ctx.closePath();
+      ctx.fill();
+      ctx.restore();
+    }
+
+    ctx.restore();
+  }
+
+  drawVerticalGlow(ctx, x, y, pulse) {
+    const h = this.radius * 1.25;
+    const w = this.radius * (0.65 + pulse * 0.16);
+
+    ctx.save();
+    ctx.translate(x, y - h * 0.35);
+    ctx.globalCompositeOperation = "lighter";
+
+    const g = ctx.createRadialGradient(0, 0, 0, 0, 0, h);
+    g.addColorStop(0.00, "rgba(255,255,220,0.28)");
+    g.addColorStop(0.32, "rgba(255,238,80,0.15)");
+    g.addColorStop(1.00, "rgba(255,220,20,0)");
+
+    ctx.scale(w / h, 1);
+    ctx.fillStyle = g;
+    ctx.beginPath();
+    ctx.arc(0, 0, h, 0, Math.PI * 2);
+    ctx.fill();
+
+    ctx.restore();
+  }
+
+  drawPulseRing(ctx, x, y, pulse) {
+    ctx.save();
+    ctx.translate(x, y);
+    ctx.scale(1, 0.42);
+    ctx.globalCompositeOperation = "lighter";
+
+    for (let i = 0; i < 2; i++) {
+      const k = (pulse + i * 0.5) % 1;
+      const r = this.radius * (0.42 + k * 0.36);
+      const a = 0.45 * (1 - k);
+
+      ctx.strokeStyle = `rgba(255,245,95,${a})`;
+      ctx.lineWidth = 3;
+      ctx.beginPath();
+      ctx.arc(0, 0, r, 0, Math.PI * 2);
+      ctx.stroke();
+    }
+
+    ctx.restore();
+  }
+
+  drawParticles(ctx) {
+    ctx.save();
+    ctx.globalCompositeOperation = "lighter";
+
+    for (const p of this.particles) {
+      const k = p.age / p.life;
+      const alpha = Math.sin((1 - k) * Math.PI) * 0.95;
+
+      ctx.save();
+      ctx.translate(p.x, p.y);
+      ctx.rotate(p.rot);
+      ctx.scale(1, 0.72);
+
+      ctx.fillStyle = `rgba(255,255,210,${alpha})`;
+      ctx.shadowColor = "rgba(255,235,70,0.95)";
+      ctx.shadowBlur = p.size * 1.4;
+
+      ctx.beginPath();
+      ctx.moveTo(0, -p.size);
+      ctx.lineTo(p.size * 0.28, -p.size * 0.28);
+      ctx.lineTo(p.size, 0);
+      ctx.lineTo(p.size * 0.28, p.size * 0.28);
+      ctx.lineTo(0, p.size);
+      ctx.lineTo(-p.size * 0.28, p.size * 0.28);
+      ctx.lineTo(-p.size, 0);
+      ctx.lineTo(-p.size * 0.28, -p.size * 0.28);
+      ctx.closePath();
+      ctx.fill();
+
+      ctx.restore();
+    }
+
+    ctx.restore();
+  }
+}
+```
+
+Canvas 主循环：
+
+```js
+const canvas = document.querySelector("canvas");
+const ctx = canvas.getContext("2d");
+const fx = new TreasureAttentionFx2D();
+
+let last = performance.now();
+let time = 0;
+
+function tick(now) {
+  const dt = Math.min(0.033, (now - last) / 1000);
+  last = now;
+  time += dt;
+
+  ctx.clearRect(0, 0, canvas.width, canvas.height);
+
+  const x = canvas.width * 0.5;
+  const y = canvas.height * 0.62;
+
+  fx.update(dt, x, y);
+  fx.draw(ctx, x, y, time);
+
+  requestAnimationFrame(tick);
+}
+
+requestAnimationFrame(tick);
+```
+
+---
+
+## 10. 验收标准
+
+coding agent 实现后，用下面标准检查：
+
+- 宝藏周围有明显金黄色柔光。
+- 地面有慢速旋转的星芒，能吸引注意但不刺眼。
+- 光环有脉冲感。
+- 有少量小闪片上浮并淡出。
+- 特效能跟随目标 mesh 移动。
+- `setEnabled(false)` 后粒子停止，root 隐藏。
+- `dispose()` 后没有残留 mesh、texture、material、observer、particle system。
+- 多个宝藏同时存在时帧率稳定。
+- 共享 `GlowLayer` 时不会异常改变其他发光物体强度。
+- 从斜俯视/isometric 相机看，效果仍然清楚。
+
+---
+
+## 11. 建议的实现任务拆分
+
+给本地 coding agent 的任务可以拆成：
+
+1. 新建 `src/effects/createTreasureAttentionFx.js`。
+2. 粘贴 Babylon.js 实现代码。
+3. 在宝藏/掉落物生成逻辑中调用 `createTreasureAttentionFx(scene, treasureMesh, options)`。
+4. 项目已有全局 `GlowLayer` 时，作为 `options.glowLayer` 传入。
+5. 在宝藏销毁、拾取、隐藏时调用 `fx.dispose()` 或 `fx.setEnabled(false)`。
+6. 根据实际模型尺寸调整 `radius`、`yOffset`、`height`。
+7. 在目标平台上压测多个实例，必要时降低 `particleRate`、`rays` 和粒子池数量。