星火 2.0 开发文档

主题

模型 LOD 选择与配置 ​

LOD（Level of Detail）用于让模型在离相机较远、画面中占比较小时切换到更低面数的网格，从而降低顶点处理、蒙皮和绘制成本。

星火 2.0 已提供三层调节方式：

  1. 模型资源配置：决定有几级 LOD、每一级的减面结果和基础切换位置。
  2. 项目画质偏移：为节能、中、高画质统一追加若干级降档。
  3. 运行时代码偏置：通过相机或单个模型的 LodBias，动态调整高精度模型保持的距离。

大多数项目只需要在美术工作台配置模型 LOD，并在真机上调整项目画质偏移。只有相机类型特殊、模型尺寸差异很大，或者需要动态性能策略时，才需要修改 LodBias。

运行时怎样选择 LOD ​

运行时不会只按“距离相机多少米”切换，也不会每帧读取模型实际覆盖了多少屏幕像素。它会综合以下因素得到一个归一化的 LOD 距离：

  • 相机到模型包围盒中心的距离；
  • 模型包围盒尺寸；
  • 相机 LodBias；
  • 模型组件 LodBias；
  • 相机 Zoom。

透视相机下可以近似理解为：

text
归一化 LOD 距离
  = 相机到模型的距离
  /（模型尺寸 × 相机 LodBias × 模型 LodBias × 相机 Zoom）

模型越远或越小，归一化距离越大，越容易进入低精度 LOD；模型越大，即使实际距离相同，也会更晚降级。

模型资源为各级 LOD 保存了递增的切换阈值。假设资源包含 LOD0、LOD1、LOD2，阈值为 T1、T2：

归一化距离使用的模型
距离 <= T1LOD0，最高精度
T1 < 距离 <= T2LOD1
距离 > T2LOD2，最低精度

当前切换是直接切换，没有自动淡入淡出或滞回区间。若阈值过于接近，镜头在临界位置移动时可能看到模型来回跳变。

正交相机使用正交视图尺寸参与计算，而不是按模型与相机的前后距离切换。因此正交项目需要单独检查缩放镜头时的表现。

在美术工作台配置模型 LOD ​

在美术工作台选择可编辑的模型或预制体后，使用“LOD 模式配置”生成和调整 LOD。

可以配置：

  • LOD 数量；
  • 每一级保留的三角面比例；
  • 硬边角度、基于哪一级继续减面；
  • 骨骼或模型局部的减面权重；
  • 自动计算或手动填写“屏幕尺寸”。

使用预设 ​

编辑器提供大尺寸、中尺寸、小尺寸和极小尺寸等预设。预设会一次性填入 LOD 数量、减面比例和切换参数，适合先获得可用结果，再根据真机效果微调。

不要只按模型资源文件的尺寸选择预设。应按模型在实际游戏镜头中的视觉占比选择：大型建筑、Boss 和近景展示模型通常需要更晚降级；远景装饰、碎石和小道具可以更早降级。

自动计算屏幕尺寸 ​

开启自动计算后，编辑器会根据减面后的几何误差估算切换距离。这个模式适合：

  • 模型比例和包围盒正确；
  • 自动减面的误差能够代表实际视觉损失；
  • 希望同一批资源使用一致规则。

自动结果仍应在游戏实际相机和目标设备上检查。透明边缘、轮廓明显的模型、带细长结构的模型，以及依赖特定骨骼轮廓的角色，单靠几何误差可能无法给出理想阈值。

手动配置屏幕尺寸 ​

关闭自动计算后，可以为每一级 LOD 手动填写“屏幕尺寸”。它是编辑器用于换算切换距离的归一化参数，不是运行时精确测量的像素百分比。

  • 数值越大：越早切到该级 LOD，对象还比较大时就会降级。
  • 数值越小：越晚切到该级 LOD，上一精度会保持得更远。
  • 后续低精度 LOD 的数值应逐级减小。

如果某一级在近处就出现，降低该级的屏幕尺寸；如果模型已经很小却仍使用高面数 LOD，提高该级的屏幕尺寸。

配置不同画质的 LOD 偏移 ​

在编辑器菜单打开：

text
设置 → LOD偏移等级

可以分别配置节能、中、高画质的整数偏移。静态模型先按距离选择基础 LOD，再追加当前画质的偏移：

text
最终 LOD 等级 = 距离选择的等级 + 画质偏移

例如模型按距离本应使用 LOD1，节能画质偏移为 1，最终会使用 LOD2。结果不会超过模型已有的最低精度等级。

建议从以下配置开始：

画质建议起点
高0
中0 或 1
节能1 或 2

较低画质的偏移不应小于较高画质。最终数值应根据场景模型数量、角色数量、目标机型 GPU 和可接受画质确定。

> 当前项目画质偏移只应用于普通静态模型。骨骼动画模型仍使用资源阈值、相机 LodBias 和自身 LodBias，不会追加这里的整数偏移。

使用 GameGraph 调整 LOD ​

模型渲染和网格资源操作属于客户端表现能力，相关代码应放在 #if CLIENT 中。

调整整个相机的 LOD ​

csharp
#if CLIENT
camera.LodBias = 1.25f;
#endif

调整单个模型的 LOD ​

StaticMeshComponent 和 AnimatedModelComponent 都继承了 Drawable.LodBias：

csharp
#if CLIENT
model.LodBias = 0.8f;
#endif

LodBias 的方向如下：

设置效果
大于 1高精度 LOD 保持得更远，画质更高、开销更大
等于 1使用资源的基础规则
小于 1更早切换到低精度 LOD，开销更低

相机和模型的偏置会相乘。若两处同时修改，应记录各自用途，避免调整一个值时被另一个值抵消。

修改具体几何体的切换阈值 ​

高级工具或运行时生成网格可以直接访问 LOD 几何体：

csharp
#if CLIENT
Geometry? lod1 = mesh.GetGeometry(geometryIndex: 0, lodLevel: 1);
if (lod1 != null)
{
    lod1.LodDistance = 120f;
}
#endif

普通项目不建议运行时修改已加载模型资源的 LodDistance：Mesh 和其中的 Geometry 通常是共享资源，修改后可能同时影响所有引用该模型的实例。优先使用实例级 model.LodBias。

AnimationLodBias 不是模型 LOD ​

AnimatedModelComponent.AnimationLodBias 控制远处骨骼动画的更新频率，用于减少动画计算开销；它不会选择 LOD0、LOD1 或 LOD2 网格。

角色性能优化时可以同时使用两套能力：

  • 模型 LodBias / 资源阈值：减少远处角色的网格复杂度；
  • AnimationLodBias：降低远处角色的骨骼动画更新频率。

不要把两者当成同一个参数。

应该调整哪一层 ​

需求推荐调整
某个模型所有实例都切换得不合理美术工作台中的模型 LOD 屏幕尺寸
某类大型或重点模型需要保持高精度该模型实例的 LodBias，或单独调整资源阈值
整个镜头下所有模型都降级过早/过晚相机 LodBias
低配设备希望静态场景统一再降一级“设置 → LOD偏移等级”
角色网格已经降低，但骨骼动画仍然耗时AnimationLodBias
需要完全自定义条件、渐变或滞回项目代码自行管理模型切换；现有配置不能替换内置选择算法

常见问题 ​

模型始终不切换 ​

  • 确认资源确实生成了多个 LOD，而不只是填写了配置。
  • 检查各级屏幕尺寸或切换阈值是否有效且顺序正确。
  • 检查相机或模型 LodBias 是否设置得过大。
  • 检查模型包围盒是否异常大。

模型离相机很近就降级 ​

  • 降低对应 LOD 的手动屏幕尺寸。
  • 增大模型 LodBias。
  • 检查模型比例、节点缩放和包围盒是否正确。

镜头移动时 LOD 来回跳 ​

当前为硬阈值切换。应拉开相邻级别的屏幕尺寸，避免多个阈值过近；特别敏感的重点模型可以保留更少但差异更明确的 LOD 级别。

修改画质偏移后角色没有变化 ​

项目画质的整数 LOD 偏移当前只影响静态模型。骨骼模型应调整资源阈值、相机 LodBias 或模型自身 LodBias。

与 Urho3D 的关系 ​

星火沿用了 Urho3D 的归一化距离、LOD 阈值和 LodBias 心智模型，并在此基础上增加了美术工作台的 LOD 生成与屏幕尺寸配置、项目级画质偏移，以及 GameGraph/WASM API。开发时以本文和当前 SDK 公共 API 为准，不需要依赖原生 Urho3D 的编辑器流程。