bevy_mod_outline: Bevy 最成熟的网格描边插件

bevy_mod_outline

bevy_mod_outline 是 Bevy 生态中最成熟、下载量最高的网格描边插件，提供了从简单顶点挤出到高级跳跃洪水距离场（JFA）的多种描边渲染方式。

---

相关页面

• bevy — Bevy 引擎主页
• hover-highlighting-techniques — 游戏物体悬停高亮技术谱系

基本信息

属性	值
仓库	github.com/komadori/bevy_mod_outline
作者	komadori (Robin Kay)
协议	MIT + Apache-2.0
最新版本	0.12.x
对应 Bevy 版本	0.18.x
总下载量	87,953+
版本数量	39
文档覆盖率	83.93%

---

核心架构

双组件设计（Volume + Stencil）

插件采用了独特的双组件架构来处理描边中最困难的问题：填充与遮挡。

组件	作用	可选性
OutlineVolume	渲染描边的体积/宽度/颜色	必须
OutlineStencil	在描边渲染时刻掉物体本体，避免填充	必须

commands.spawn((
    Mesh3d(mesh),
    OutlineVolume {
        visible: true,
        colour: Color::srgb(1.0, 0.0, 0.0),
        width: 2.0,
    },
    OutlineStencil {
        enabled: OutlineStencilEnabled::Always,
    },
))

工作流程：

1. 先渲染 OutlineVolume — 会在物体周围生成一个完整的色块
2. 然后渲染 OutlineStencil — 把物体本体的部分”挖掉”，只留边缘
3. 最终结果是一个空心的立体边缘

独立深度缓冲

插件在主 3D Pass 之后使用单独的深度缓冲来渲染描边，这意味着：

• 其他不带描边的几何体不会剪辑描边
• 可以正确处理物体交叉时的描边遮挡

---

渲染模式

RealSpace 模式

默认模式。描边在 3D 空间中存在，会随着物体的旋转和距离变化。

• 适合大多数场景
• 对于面朝相机的平面物体，可能会出现穿模

Flattened 模式

描边被压平到一个平面，避免穿模问题。

• 可以通过 OutlinePlaneDepth 控制平面的深度
• 适合从上方看下去的策略/角色选择圈

FloodFlat 模式（实验性）

基于跳跃洪水算法（JFA）的距离场驱动描边。

• 线宽在屏幕空间中保持一致
• 不再依赖模型的几何形状
• 需要开启 flood feature

---

组件传承与动画支持

组件传承

• InheritOutline — 子实体可以继承父实体的描边属性
• AsyncSceneInheritOutline — 当从 glTF/GLB 场景加载时，自动继承描边

动画支持

• 完全支持骨骼动画（Skeletal Animation）
• 支持 Morph Targets（形态变形）
• 支持脚本带动的动画
• 不需要手动同步两个网格——插件在渲染阶段处理

---

法线生成与硬边处理

问题

顶点挤出依赖法线方向。如果模型有硬边（比如立方体的棱），同一个顶点在不同面上会有不同法线，导致挤出后裂纹。

解决方案

1. 手动生成平滑法线：在加载时调用 OutlineMeshExt::generate_outline_normals(mesh)
2. 自动插件：添加 AutoGenerateOutlineNormalsPlugin，会在程序运行时自动处理每个网格
3. 预烧法线：在建模时就为边缘生成平滑法线（这是最好的方案）

---

版本对应表

bevy_mod_outline	Bevy 版本
0.12.x	0.18.x
0.11.x	0.17.x
0.10.x	0.16.x
0.9.x	0.15.x
0.8.x	0.14.x
0.7.x	0.13.x
0.6.x	0.12.x
0.5.x	0.11.x
0.4.x	0.10.x
0.3.x	0.9.x
0.2.x	0.8.x
0.1.x	0.7.x

---

与 bevy_mesh_outline 的对比

特性	bevy_mod_outline	bevy_mesh_outline
核心算法	Vertex Extrusion + 可选 JFA	纯 JFA
线宽一致性	3D 空间变化	像素级一致
MSAA 支持	支持	不支持
骨骼动画	支持	支持
下载量	87K+	327
成熟度	生产就绪	实验性
设置复杂度	中（组件多）	低（单一组件）

---

Related files

• wiki/concepts/hover-highlighting-techniques.md — 游戏高亮技术的深度解析
• wiki/comparisons/hover-highlighting-comparison.md — 五种技术的完整对比
• wiki/concepts/bevy-rendering.md — Bevy 渲染管线概览