Hookshot Builder 故障排查：构建、启动与 Vulkan 错误

Builder 无法打开

Windows 应使用官方 EXE 并保持首次下载所需网络，安全警报应核实而非全局关闭保护。Linux 核查 x86-64、glibc 2.35+、AVX2 与执行权限，可从终端读取报错。旧 Windows ZIP 才需要自行保留 EXE 旁的 tools。

构建失败

1. 1

   记录失败阶段与完整错误文本。

2. 2

   检查约 60 GB 可用空间、可写输出目录与完整官方软件包。

3. 3

   确认游戏标识及完整 .nup 或匹配的 romfs/exefs。

4. 4

   对照最新发布并搜索同样错误，仍失败时报告构建输出。

版本不受支持

按支持版本页核对三项标识。若提示 Hookshot supports build e0f3ccfa，先核查游戏更新；改名或切换 Builder 不会改变游戏内容。

黑屏、崩溃或几何缺失

更新实际使用显卡的驱动，确认 Vulkan 1.3 与 Mesh Shaders。无 Mesh Shaders 的硬件没有受支持回退。

游戏目录的 hookshot_log.txt 记录最近运行，前四次是 hookshot_log.1.txt 至 hookshot_log.4.txt；终端启动则输出到终端。部分 AMD 配置有 device lost 报告，但不能只凭消息认定所有机器都同一原因。

最近核对版本修复了黑脸、着色器准备和 AMD 地面网格，仍有漂浮树木和 Gerudo Valley 地形孔洞。先读当前说明再套用旧方法。

首次卡顿与着色器

首次启动准备着色器可能需要几分钟；最近核对版本更新后会重新准备。新区域首访仍可能卡顿，再次经过通常改善。可为小显存选较低画质，一次改一项；插帧不能保证解决低原生帧率。

Linux Vulkan 检查

安装 vulkaninfo 工具后，下方命令应显示 VK_EXT_mesh_shader；还要在完整输出确认相应设备支持 Vulkan 1.3。缺少扩展时核查驱动和 GPU 能力。

vulkaninfo | grep mesh

提交有效报告

• 先备份存档，尝试最新官方版本，并搜索现有 Issues 是否已有相同问题。
• 记录版本、操作系统、显卡及驱动、CPU、内存、游戏中的准确位置和复现步骤。
• 附上相关日志；必要时附截图或录像，不要附游戏数据、密钥或构建产物。
• 按项目贡献指南用英文提交报告；本站不是官方支持团队。