@fps-games/vfx 0.3.2 → 0.3.3

package/docs/hit-flash-red-method.md

@@ -1,155 +0,0 @@
-# 方法:物体受击闪红(Hit Flash)
-
-> 给「**被击中的那个物体**」加一个受击瞬间染红 / 保持 / 淡回的反馈。供 coding agent 直接套用。
-> 移植自 axe_and_bear 的 `HitFlashService`(熊被斧子打到时整只变红)。
-
-## 它和普通特效的本质区别 —— 先读这段
-
-- 普通 VFX(爆炸、拖尾、命中爆闪)是 **在某个位置 spawn 一团东西**(粒子/网格),和被打的物体无关。
-- 受击闪红是 **修改被打物体自己的材质颜色**(`emissiveColor`)。它没有"自己的网格",寄生在目标身上。
-
-所以它**不是 `@fps/vfx` 的 `VfxEffectPackage`**(那个契约是 `create({position}) → 在该点生成`)。
-不要试图 `vfx add hit-flash`。正确做法是把下面这个工具类放进**宿主工程**,在你能拿到目标 mesh 的地方用它。
-
-## 原理(一句话)
-
-每个目标 mesh:**克隆一份材质**(防止污染共享材质)→ 存下原始 `emissiveColor` → 受击时把 emissive 插值到红色,`holdTime` 秒保持全红,`fadeTime` 秒线性淡回原色。
-
-```
-play()  ┌─ holdTime ─┐┌──── fadeTime ────┐
-红度 1.0 ████████████░░░░░░░░░░░░░░░░░░░░  → 回到原 emissive
-       命中                              结束
-```
-红度 `t` → `emissive = Lerp(原色, Lerp(原色, 红, flashStrength), t)`
-
-## 完整实现(复制即用)
-
-```ts
-// hit-flash.ts —— 放进宿主工程(不是 @fps/vfx)
-import { Color3 } from '@babylonjs/core/Maths/math.color';
-import type { AbstractMesh } from '@babylonjs/core/Meshes/abstractMesh';
-import type { Material } from '@babylonjs/core/Materials/material';
-import type { Scene } from '@babylonjs/core/scene';
-import type { Observer } from '@babylonjs/core/Misc/observable';
-
-export interface HitFlashOptions {
-  flashColor?: Color3;     // 闪光色,默认红 (1,0,0)
-  flashStrength?: number;  // 0..1,红色混入强度(1=完全替换),默认 1
-  holdTime?: number;       // 全红保持秒,默认 0.2
-  fadeTime?: number;       // 淡回原色秒,默认 0.1
-  emissiveBoost?: number;  // HDR 倍率:有 bloom/tonemapping 时调大(默认 3.4);无后处理用 1
-}
-
-interface FlashEntry { mat: Material & { emissiveColor?: Color3 }; original: Color3; }
-
-export class HitFlash {
-  private entries: FlashEntry[] = [];
-  private readonly flashColor: Color3;
-  private readonly flashStrength: number;
-  private readonly holdTime: number;
-  private readonly fadeTime: number;
-  private elapsed = 0;
-  private total = 0;
-  private observer: Observer<Scene> | null = null;
-
-  /** meshes:目标物体的所有可见 mesh(通常 root.getChildMeshes())。一个目标建一次,反复 play()。 */
-  constructor(meshes: AbstractMesh[], private readonly scene: Scene, opts: HitFlashOptions = {}) {
-    this.flashColor = (opts.flashColor ?? new Color3(1, 0, 0)).scale(opts.emissiveBoost ?? 3.4);
-    this.flashStrength = opts.flashStrength ?? 1;
-    this.holdTime = opts.holdTime ?? 0.2;
-    this.fadeTime = opts.fadeTime ?? 0.1;
-    for (const mesh of meshes) {
-      const src = mesh.material;
-      if (!src || !('emissiveColor' in src)) continue;
-      // 关键:克隆材质,否则会染红所有共用此材质的物体
-      const cloned = (src.clone(`${src.name}_hitflash`) ?? src) as FlashEntry['mat'];
-      mesh.material = cloned;
-      this.entries.push({ mat: cloned, original: (cloned.emissiveColor ?? Color3.Black()).clone() });
-    }
-  }
-
-  /** 每次受击调用。连续受击会刷新到峰值(不叠加爆掉)。 */
-  play(): void {
-    this.elapsed = 0;
-    this.total = this.holdTime + this.fadeTime;
-    if (!this.observer) {
-      this.observer = this.scene.onBeforeRenderObservable.add(() => this.update());
-    }
-    this.apply(1);
-  }
-
-  private update(): void {
-    this.elapsed += this.scene.getEngine().getDeltaTime() / 1000;
-    if (this.elapsed <= this.holdTime) {
-      this.apply(1);
-    } else if (this.elapsed < this.total) {
-      this.apply(Math.max(0, 1 - (this.elapsed - this.holdTime) / this.fadeTime));
-    } else {
-      this.apply(0);
-      this.detach();
-    }
-  }
-
-  private apply(t: number): void {
-    for (const e of this.entries) {
-      const target = Color3.Lerp(e.original, this.flashColor, this.flashStrength);
-      e.mat.emissiveColor = Color3.Lerp(e.original, target, t);
-    }
-  }
-
-  private detach(): void {
-    if (this.observer) { this.scene.onBeforeRenderObservable.remove(this.observer); this.observer = null; }
-  }
-
-  /** 目标销毁前调用:恢复原始 emissive + 移除 observer。 */
-  dispose(): void {
-    this.detach();
-    for (const e of this.entries) e.mat.emissiveColor = e.original;
-  }
-}
-```
-
-## 用法
-
-```ts
-// 1) 目标出生时建一次(传它所有可见 mesh)
-const flash = new HitFlash(bear.getChildMeshes(), scene, {
-  flashColor: new Color3(1, 0, 0),  // 红
-  holdTime: 0.2, fadeTime: 0.1,
-});
-
-// 2) 每次被打调用
-function onBearHit() {
-  bear.subHp(dmg);
-  flash.play();          // ← 闪红
-}
-
-// 3) 目标死亡/移除前
-flash.dispose();
-```
-
-## 参数怎么调影响什么
-
-| 参数 | 影响 |
-|---|---|
-| `flashColor` | 闪光颜色。红=受伤;白=普通受击;绿=治疗/buff |
-| `flashStrength` | 红色混入比例。1=峰值完全红;0.5=半红(保留原色感) |
-| `holdTime` | 全红保持时长。越大越"顿挫"/越重 |
-| `fadeTime` | 淡回时长。越大余韵越长越软 |
-| `emissiveBoost` | HDR 倍率。有 bloom/tonemapping 时调大让红更亮更艳(线性空间);无后处理设 1 |
-
-## 必须注意的坑(coding agent 重点看)
-
-1. **一定要克隆材质**。直接改 `mesh.material.emissiveColor` 会染红**所有共用这份材质的物体**(整片同模型一起变红)。上面构造里已 `clone()`。
-2. **用 `emissiveColor` 不是 `diffuseColor`/`albedoColor`**。自发光不受光照影响、像"发光"般醒目,且能吃 bloom;`StandardMaterial` 和 `PBRMaterial` 都有 `emissiveColor`。
-3. **存原色 + dispose 恢复**。目标原本可能就有 emissive(发光怪),必须存原值并在 dispose 时还原,否则残留。
-4. **重复受击**。`play()` 重置计时到峰值 → 连击是"刷新红光"而非叠加,不会爆白。
-5. **observer 生命周期**。淡出结束自动 `detach()`;目标销毁前务必 `dispose()` 移除残留 observer,避免泄漏与"对着已销毁材质写值"。
-6. **PBR + emissiveTexture**:若目标材质带自发光贴图,纯色 emissive 会与贴图相加;受击闪红一般可接受,介意的话可在 play 时临时把 `emissiveTexture` 置 null、dispose 时还原。
-7. **蒙皮/多子网格**:用 `root.getChildMeshes()` 把所有子网格都纳入,漏掉的部位不会变红。
-
-## 可选增强
-
-- **配合受击粒子**:闪红是"染目标",再在命中点叠一个 `@fps/vfx` 的 `monster-hit`(闪光+血)burst,就是完整受击反馈——两者正交,各管一层。
-- **击退/缩放抖动**:`play()` 时顺带给 root 一个轻微 scale punch(1.1→1.0)或位移,手感更冲。
-- **死亡白闪**:把 `flashColor` 设白、`holdTime/fadeTime` 拉长,即死亡瞬间的泛白。