TerrainScanner

分叉自 https://github.com/LIghtJUNction/PeakMods。由于原作者放弃并归档了原 mod 仓库，我创建了一个分叉，并将其更新以兼容最新的 The Final Ascent 更新。

地形扫描仪基于着色器，由 GPU 渲染。并采用异步帧渲染，因此速度快且不会卡顿。

它显示什么

• 坡度分类（模块使用的示例阈值）：
  • 平坦：0°–30°
  • 缓坡：30°–50°
  • 陡坡：50°–90°

这些阈值可通过 ScanConfig 进行配置（见下文）。

快速安装 / 使用

1. 将 TerrainScanner 脚本（或编译好的 DLL）添加到你的 Unity 项目的 Assets/ 文件夹中。源代码位于本仓库的 src/TerrainScanner/ 目录下。

2. 在你的场景中，将 ActiveScan 挂载到一个 GameObject 上（例如 Player 或 Camera）。默认情况下，扫描仪通过 Q 键触发（参见 ActiveScan.cs）。

3. 确保在运行时为 ScanConfig 正确填充所需的材质和粒子预制体：

   • scanMaterial（扫描波的着色器）
   • markMaterial（标记的实例化着色器）
   • markParticle1/markParticle2/markParticle3（可选的粒子预制体）

如果你使用 mod 加载器（BepInEx），插件可以在启动时为你填充这些内容。

配置（重要字段）

大多数运行时选项位于 ScanConfig（src/TerrainScanner/Config.cs）中。重要数值：

• horizontalCount、verticalCount —— 采样网格大小。数值越大，覆盖范围和精度越高，但消耗的 CPU 也更多。
• gridStep —— 采样点之间的间距（米）。
• sampling_originHeightOffset —— 射线起点在相机/玩家上方多高的位置开始。增大此值可扫描更高的地形。
• sampling_maxDistanceShort / sampling_maxDistanceLong —— 用于地面/边沿检测以及远距离检测的射线长度。
• steepSpawnProb、midSpawnProb、flatSpawnProb —— 各分类的粒子生成概率。

可通过 ScanConfigManager 调整这些数值，或在插件初始化时进行绑定。

疑难解答

• 扫描检测到了许多命中点，但我只看到部分标记被渲染出来：

  • 确保 CPU 端的 Marks 结构体布局与 HLSL 的 Marks StructuredBuffer 一致。字段顺序和大小必须匹配。
  • 确保创建 ComputeBuffer 时使用了正确的步长（使用 Marshal.SizeOf(typeof(Marks))）。
  • 检查实例化着色器没有在片元阶段写入深度（在片元中写入 SV_DEPTH 可能导致深度冲突并隐藏实例）。将深度计算移至顶点阶段，或移除手动的深度写入。

• 射线无法到达高处的悬崖：

  • 增大 sampling_originHeightOffset 和 sampling_maxDistanceShort。

• 性能方面的顾虑：

  • 采样以分片方式运行（使用 UniTask.Yield() 以避免阻塞主线程）。如果你提高分辨率，请考虑降低 horizontalCount/verticalCount 或降低采样频率。
  • 考虑限制每帧上传到 GPU 的标记数量（例如只保留最近的 N 个标记，或按坡度分类设定优先级）。

路线图 —— 更智能的地形扫描仪（下一个主要功能）

计划中：一个"智能地形扫描仪"，在保持性能的同时提升扫描质量。高层目标与设计说明：

1. 基于能量的传播模型

   • 每个被发现的采样点携带一份能量预算（动能 + 势能）。向邻居传播会因移动距离和攀爬而消耗能量。
   • 分支会降低能量（生成成本）。只有当以严格更多的剩余能量到达时，才会重新访问某个单元格（最优能量规则）。

2. 优先级驱动的探索

   • 用按剩余能量排序的优先队列替代普通的 FIFO 传播队列（优先考虑上坡、高能量的前沿），以便算法更快地找到可行的登顶路线。

3. 量化、内存高效的状态

   • 将每个单元格被探测到的高度以量化键（例如 0.1m 精度）存储在 HashSet 中，以避免浮点相等问题并减少重复。

4. 安全与终止

   • 全局处理数量上限与局部能量阈值，以防止在洞穴或密集几何体中发生失控传播。

5. 运行时调优与可视化

   • 在 ScanConfig 中暴露能量参数和传播限制，以便用户调整行为。
   • 添加一个可选的调试叠加层，用于可视化传播前沿、队列中的项目以及每个单元格的最优能量值。

为什么这有帮助：

• 它可以防止在复杂几何体（洞穴/悬崖突出部）中无限传播。
• 它优先考虑真实的上坡路线，帮助扫描找到可达的地面，而不是淹没每一个相邻单元格。
• 它使性能保持可预测且可调。

贡献

欢迎贡献、提交问题和建议。在提交 PR 时：

• 说明问题或功能，并在相关时附上截图或日志。
• 保持改动聚焦；大型重构如果拆分为更小的 PR 会更容易审查。

许可证

本项目依据 LICENSE 中的条款进行许可。