design.md 8.6 KB
背景
上游 flow-shield-effect 的护盾效果主要集中在 src/components/ForceShield 内部：一个球体 mesh、一套自定义 shader 材质、动画 uniform，以及一个用于渲染点击命中冲击波的小型命中缓冲。仓库其他部分大多是为了 demo 展示服务的，包括 React Three Fiber 包装、Leva 调参、Orbit 辅助、场景组合和可选后期处理。这意味着它非常适合做“核心能力直接迁移”，但迁移后必须符合当前仓库的实现约束：
- 使用 Vue 3 + TresJS，而不是 React Three Fiber
- 组件逻辑放在
src/components/ - shader 文件外置到
src/shader/<component-name>/ - 通过
src/dcsConfig.ts完成注册和配置 schema - 不在
src/views/previewEntry.vue或src/views/templateComponet.vue里加入组件专属分支逻辑
另外，上游点击冲击波来自 mesh 上的 onClick，使用本地 raycast 命中点并调用 stopPropagation()。这种写法在独立 demo 中没问题，但如果后续要放到编辑器里做场景级点选、选中或拾取，它会有明显冲突风险。
目标 / 非目标
目标：
- 将护盾壳体效果本身迁移为一个可复用的 Vue 3 + TresJS 动态组件。
- 保留这个组件最有辨识度的视觉特征：球形护盾、六边形纹理、菲涅耳边缘、动态噪声破碎效果和命中冲击波。
- 将参数面收敛为护盾自身参数，避免配置面板变得臃肿。
- 让命中冲击波与内部 click 捕获解耦，兼容后续编辑器点选接管事件链。
- 通过
src/dcsConfig.ts接入默认值和调参项，并把 shader 放到组件专属目录中。
非目标：
- 不迁移上游的 React Three Fiber 场景搭建、辅助器、Leva UI 或 demo 布局。
- 不迁移 transform 控制，也不把通用的
position/rotation/scale作为组件自身配置契约的一部分。 - 不迁移 reveal/debug 或 gameplay 风格的状态控制，例如手动 reveal、护盾生命值、伤害值等，除非它们是护盾表面效果本身不可缺少的一部分。
- 不引入 bloom 或其他后期处理作为组件正确显示的前置条件。
关键决策
- 决策：不新增
radius参数，也不引入uRadiusuniform；保持上游“固定基准球体 + shader 材质”的思路，组件整体尺寸交给宿主场景或编辑器外部 Object3D 缩放处理。 - 理由：回查上游实现后可以确认，
ForceShield本身就是用固定球体和材质组合出来的：外层group通过scale控整体大小，内部sphereGeometry使用固定参数[1.8, 64, 64]，index.tsx 中也是这么接的；shader 顶点阶段直接把position写入vObjPos，片元阶段又直接使用vObjPos.y / 1.8和默认命中点vec3(0, 1.8, 0)这类固定半径假设来做计算，shaderMaterial.ts 里可以看到这一点。既然当前接入目标更接近“迁移材质表现”，就不应该平白扩展成一个额外的半径契约。 备选方案：新增
radius参数并改造为uRadius驱动的自适配 shader。这个方案技术上可以做，但它已经超出“按原组件思路迁移”的边界，而且你明确说明后续尺寸会由你自己在外层调整，因此首版不应走这条路。决策：将护盾 shader 迁移为
src/shader/superEnergyShieldComponent/下的外部顶点和片元文件。理由：当前仓库已经要求 shader 代码按组件拆分存放。上游实现把 shader 写在 TypeScript 辅助文件里，迁移成
.vert和.frag后更便于维护，也能与现有组件实现方式保持一致。备选方案：继续把 shader 字符串内联在 Vue 组件里。技术上可行，但不符合仓库约定，也不利于后续调试和维护。
决策：参数只保留护盾自身相关项。
保留参数：
- 表面：
color、opacity、showHex、hexScale、hexOpacity、edgeWidth - 菲涅耳：
fresnelPower、fresnelStrength、fadeStart - 流动与闪烁：
flashSpeed、flashIntensity、flowScale、flowSpeed、flowIntensity - 噪声边缘：
noiseScale、noiseEdgeColor、noiseEdgeWidth、noiseEdgeIntensity、noiseEdgeSmoothness - 冲击波：
hitRingSpeed、hitRingWidth、hitMaxRadius、hitDuration、hitIntensity、hitImpactRadius
- 表面：
不保留参数：
- 组件级尺寸参数，例如
radius - transform 类控制
- 外部场景、辅助器、后期处理开关
- demo 专属的 reveal/debug 控制
- gameplay 相关值，例如 shield life、damage
- 组件级尺寸参数，例如
理由：上游 demo 暴露的参数很多，是为了实验和展示，不适合作为动态组件服务里的正式参数面。这里应该只保留真正改变护盾本体表现的配置。
备选方案：一比一迁移所有上游参数。这个方案会让配置面板过于嘈杂，也会把 demo 状态和可复用组件参数混在一起。
决策：保留命中冲击波效果，但把“生成 impact”的逻辑抽成共享入口，而不是强绑定到永远开启的点击事件上。
理由：命中冲击波是护盾效果的重要组成部分，但上游 demo 的事件处理策略不适合作为长期集成契约。应通过
registerImpact(localPoint, localNormal)一类统一入口来驱动固定大小的命中缓冲，这样既能支持可选的组件自点击预览模式，也能兼容未来编辑器自己的拾取逻辑。集成规则：
- 默认渲染不依赖组件内部 click 捕获
- 可选自点击命中模式只在预览或 demo 场景下显式开启
- 即便开启自点击命中，也不能把无条件
stopPropagation()作为组件正常工作的前提
备选方案：彻底去掉命中冲击波。这样虽然能避开事件问题，但会丢掉上游组件最有辨识度的行为之一。
决策：组件接入统一通过
src/dcsConfig.ts完成，不改通用预览视图文件。理由：当前仓库已经把组件默认值和配置面板集中在
src/dcsConfig.ts中管理。超级能量盾也应该遵循同样路径。备选方案：在通用 preview 视图里为该组件加入特判逻辑。这个方案会让公共预览层和组件能力发生耦合。
决策：组件必须完全运行在 three.js canvas 渲染管线内，不依赖后期处理才能成立。
理由：上游效果本质上是 shader 驱动的，迁移后应当在不加 bloom 或 composer 的前提下也能保持有效表现，否则在动态组件服务中嵌入会变得不稳定。
备选方案：把后期处理视为组件契约的一部分。这样会增加集成复杂度，也违反你给出的迁移边界。
风险与权衡
- [风险] 透明护盾材质在某些场景中可能出现深度排序问题。
- 缓解：保持适合护盾的透明材质设置，例如合理控制 depth write 和 render order。
- [风险] 上游 shader 使用了固定基准半径假设，如果后续有人改成“直接换几何体半径”而不是外部缩放，护盾表现可能失真。
- 缓解：首版保持与上游一致的基准球体尺寸，不新增
radius/uRadius契约；如果未来确实要支持几何体半径可配，再单独发起一次 shader 半径归一化改造。
- 缓解：首版保持与上游一致的基准球体尺寸，不新增
- [风险] 如果直接照搬上游
onClick，会和未来编辑器选中逻辑冲突。- 缓解：将自点击命中模式设为可选，并把冲击波生成逻辑抽象为可复用入口。
- [风险] 暴露参数过多会让配置面板难以使用。
- 缓解：首版只保留护盾自身参数，把 demo/debug/gameplay 项全部排除在外。
迁移计划
- 第一步：先把组件边界、参数契约和交互约束在 OpenSpec 中明确下来。
- 第二步：实现 Vue/Tres 组件和外置 shader 文件，保持与上游一致的基准球体尺寸假设，并确保外部缩放可以接管整体大小。
- 第三步：在
src/dcsConfig.ts中完成组件注册、默认值和配置面板定义。 - 第四步：验证构建结果和预览表现，并单独验证“默认编辑器安全模式”和“可选自点击命中模式”。
- 回滚策略：先移除
dcsConfig注册，再回退组件和 shader 文件，最后清理相关预览资源。
待确认问题
- 首版是否需要提供一个显式的外部触发 API 来驱动冲击波，还是先保留共享内部 helper + 可选自点击预览模式就足够？ 不用。保留共享内部 helper就行，不做额外的适配。
- 是否需要在同一次实现里补齐组件预览图，还是先临时复用占位资源，等效果稳定后再截图补齐？ 不用，我会自行补齐