SuperAPI AI 工具集

terrain3d

编程与开发

查看项目

更新于 11-07 04:01

技能介绍

用途

本技能仅用于 TokisanGames/Terrain3D 及其 Terrain3D/Terrain3DData API,提供按模式执行的操作指引,模式包括:版本适配(version-fit)、插件安装(addon-install)、源码构建(source-build)、地形集成(terrain-integration)、升级(upgrade)、故障排查(failure-triage)。通用 Godot 设计不属于本技能范围;体素/洞穴/体积地形也不是该高度图 clipmap 插件的既定能力。

主要能力

  • 版本适配:对比发行说明、实际源码 SConstruct 和 .gdextension 与项目的引擎/渲染器/平台,形成兼容/受阻/未知矩阵。
  • 插件安装:预览官方 AssetLib/发行包选择及目标位置,经批准后复制 addons/terrain_3d、启用插件、打开 demo/Demo.tscn 并按需运行。
  • 源码构建:固定主源码与 godot-cpp 子模块,盘点 Python/SCons/编译器,读取准确 api_version 与 debug/release 配置,分别批准下载/构建。
  • 地形集成:添加 Terrain3D 节点、指定专用空 Data Directory、检查 region_size 与 vertex_spacing、使用绝对全局坐标与 region-location 键、在已安装版本上核对目标方法签名。
  • 升级:先盘点场景/数据/资源与当前版本,要求独立备份或一次性副本并记录恢复流程,在批准副本中移除旧插件并安装完整替代,不覆盖或删除源数据。
  • 故障排查:记录控制台输出、引擎/插件版本与渲染器,区分缺失 godot-cpp、API/ABI 不匹配、发行二进制缺失、数据路径错误、不支持的渲染器及 macOS 信任失败等。

使用方式

从已安装技能目录可运行离线预检脚本:

python3 scripts/preflight.py --json python3 scripts/preflight.py --json --repo <approved-absolute-source-root>

该脚本加载同目录的 references/source.json,离线、有界并拒绝符号链接/敏感路径;不带 --repo 时不检查上游文件。匹配只涉及 README/LICENSE,不代表 HEAD、子模块、二进制 ABI、引擎/运行时或安全就绪。不匹配时应停止而非修改哈希。运行辅助脚本前需使用支持 os.O_NOFOLLOW 与 os.open 的 dir_fd 的 POSIX Python 环境;原生 Windows 可能以 secure_posix_traversal_unavailable 失败关闭。

适用场景

  • 在指定 Godot 版本项目中安装 Terrain3D 插件。
  • 从源码构建并验证产物与导出配置。
  • 集成区域/高度图并进行小范围测试、持久化与碰撞检查。
  • 升级旧 Terrain3D 数据目录并做分阶段转换。
  • 定位 Terrain3DData 查询落在错误区域等问题。

限制

Clipmap GPU 顶点位移不会在区域外分配碰撞;区域网格限制 1024/32x32、区域尺寸 64-2048 和当前 32 纹理限制属于设计约束而非实测速度;这是顶点绘制而非像素级精确绘制。下载、项目修改、转换、构建/编辑器执行、签名与隔离更改均需相应权限;优先使用已签名/自建二进制而非关闭安全控制。发布为独立事项。所有检查结果需按证据分别报告,缺少运行时批准时检查保持未执行状态。