故障排查
先判断问题在哪一层：启动、存档、联机、模组还是资源包。大部分问题能在控制台日志、目录结构或端口上直接看出来，不用重装。
快速对照
| 现象 | 先看哪里 |
|---|---|
| 双击没反应 / 闪退 | 显卡驱动是否支持 Vulkan 1.3；从终端启动看控制台输出。 |
| 黑屏但有声音 | 交换链 / 驱动；更新显卡驱动，确认不是远程桌面或虚拟显卡。 |
| 存不了档 | 安装目录是否可写；不要装在 Program Files 或只读盘。 |
| 世界列表里没有旧世界 | 文件夹里是否有 world.dat；旧单文件存档不会被导入。 |
| 朋友连不上 | 房主是否还在游戏里；UDP 27632 防火墙 / 端口转发；两边版本和模组。 |
| 模组没加载 | mods\ 里是文件不是文件夹；main.lua 层级；重启；控制台日志。 |
| 材质包没效果 | 扩展名、zip 根目录布局、包顺序；没有热重载。 |
| 掉帧 | 渲染距离、编辑时的同步重建、笔记本电源模式。 |
启动与画面
提示 Vulkan 相关错误
CaelCraft 要求 Vulkan 1.3，或者带 VK_KHR_dynamic_rendering 扩展的 Vulkan 1.1 / 1.2；没有 render pass 回退。先更新显卡驱动，再确认不是在用微软基本显示适配器、远程桌面或虚拟机的虚拟显卡。核显和独显都可以，但驱动要新。
如果启动时弹窗或直接退出，从终端运行 exe 看控制台输出：
cd "$env:LOCALAPPDATA\Programs\CaelCraft"
.\CaelCraft.exe
启动时会有一个控制台窗口，里面会打印版本、Vulkan 设备和模组加载信息。用快捷方式启动时窗口也在；不要急着关。
黑屏 / 交换链失败
先更新驱动；确认窗口没有被最小化到 0×0；远程桌面和部分虚拟机会话没有可用的交换链。多显卡笔记本可以试着在显卡控制面板里指定独显运行。
用了资源包后画面异常
先把资源包里的 shaders\ 覆盖移走，再看 visual.json 的数值。着色器必须匹配当前顶点布局、push constants 和 binding；加载前会检查 SPIR-V 魔数，创建失败会自动回退内置着色器，但错误的参数仍可能让画面不对。
没有声音
音效是程序化 WAV，用 PlaySoundA 播；同一时间只能响一个。检查 Windows 输出设备；如果系统静音或切到别的设备，游戏不会自己恢复。
安装与存档
保存失败
游戏在 exe 旁边写 saves\，没有写权限就会失败。默认安装目录是 %LOCALAPPDATA%\Programs\CaelCraft；如果你改到了 Program Files、只读共享盘或受控文件夹，换到可写目录。OneDrive 等同步软件正在上传时也可能抢文件，先暂停同步。
世界列表里没有某个世界
主菜单只列出 saves\ 下带 world.dat 的文件夹。检查文件夹是否被改名、world.dat 是否丢失、是不是旧版单文件 saves\world.save.caelc（不会导入）。
升级后地形变了
开发版改地形生成算法后，同种子的旧世界会按新算法重新生成地形；存档只存种子和方块修改，无法恢复旧地形。升级前备份 saves\，或者留在旧版本。
中文显示成方块 / 问号
界面中文靠 C:\Windows\Fonts\msyh.ttc（微软雅黑），16px、简体常用字形。系统缺这个字体时会退回 ImGui 默认字体，而默认字体没有 CJK 字形。确认字体文件存在；不要删渲染器里加载字体的那段。
设置每次重启都回到默认
这是当前行为：鼠标灵敏度、FOV、渲染距离、语言只存在内存里，没有配置文件。需要的话每次启动后用 /fov、/render 调。
SmartScreen 提示未知发布者
安装包没有代码签名。确认来自 craft.caellab.com、SHA-256 对得上之后，再选择「更多信息 → 仍要运行」。不要从第三方网盘拿改过的包。
操作与界面
- 鼠标锁在准星上：按 Esc 暂停。打开命令 / 聊天 / 背包时鼠标会解锁，按 Enter 或 Esc 结束输入后锁回去。如果窗口失焦，点一下游戏窗口。
- E 打不开背包：背包只在生存模式有效；创造模式会提示「Inventory is only used in Survival mode」。
- F4 没反应：旁观切换要求当前在游戏中且没有打开输入或背包；先按 Esc 回到游戏。
- 命令没执行：输入框只接受可打印 ASCII；中文、全角符号会被丢掉。命令要按 Enter，不是 Esc。
- 粘贴没反应：用 Ctrl + V；GLFW 的字符回调不会送粘贴键，游戏走 ImGui 剪贴板。只保留 ASCII。
- 找不到截图：F2 写到 exe 目录的
screenshots/，文件名是<ISO时间>_CaelC.png，不是工作目录；游戏会自己建这个文件夹。
联机
- 先在同一个局域网里试：房主开服，朋友填房主的内网 IP。局域网能连，再排查公网转发。
- 房主的游戏必须还在多人游戏里；回到主菜单或退出游戏就断线。
- Windows 防火墙允许 CaelCraft 通过专用网络；路由器把 UDP 27632 转发到房主电脑的内网 IP。
- 确认不是 CGNAT：路由器 WAN 口地址和 外网看到的 IP 不一致时，端口转发不会生效。
- 两边版本和模组一致；协议版本 2，模组签名不一致会直接拒绝。
- 只写域名时，确认
_caelcraft._udp.<域名>的 SRV 记录指向正确的目标和端口；没有 SRV 就用默认 27632。
UDP 没有 TCP 握手，ping 和普通端口扫描测不准。游戏里连接失败会显示原因；先看是超时、协议版本还是模组签名。
没有密码、认证和加密，知道地址的人都能尝试加入。不要长期把端口暴露在公网。
模组
模组没加载
- 确认
mods\里是.mod.caelc或.zip文件，不是解压后的文件夹。文件夹是数据目录，不会被当模组加载。 - 包里要有
main.lua，在根目录或单个顶层文件夹里；不要套两层。 - 装完重启游戏。没有热重载。
- 看启动控制台的
[mod:名字]日志；mods\.cache\每次启动会重建。 - 包总大小不超过 256 MB、文件数不超过 4096；路径穿越会被拒绝。
命令在客户端没反应
模组命令只在单机和主机执行，客户端收到 Welcome 后关闭脚本。客户端只加载方块注册表和纹理；要在客户端执行逻辑，目前没有这个 API。
纹理不显示
路径相对于模组根目录，文件名大小写要一致；PNG / JPG 能被解码。资源包覆盖模组纹理时，层名是 <mod>_<文件名去扩展名>，例如 ruby_ruby_block。
联机被拒绝
两端模组名或 main.lua 内容不一致。签名只看名字和脚本，贴图不同不会触发；但两端都要有对应的方块注册表。
数据没保存
用 cael.data_dir() / data_read / data_write，不要往 mods\.cache\ 写；那个目录每次启动会清空。检查 data_write 的返回值，路径不能是绝对路径或含 ..。
死循环 / 卡住
每次回调约 20 万条指令预算，超了会中断并打日志，不会卡死主机。检查 while 条件和每 tick 的逻辑；用 --modtest 验证。
资源包
- 没被识别：扩展名
.rp.caelc/.zip，放在resourcepacks\第一层；重启游戏。 - zip 根目录不对：不要把内容套在
MyPack\里；textures\或pack.mcmeta必须在 zip 根目录。 - MC 包不生效：根目录要有
pack.mcmeta，路径是assets/minecraft/textures/block/...；只映射方块和两颗心，不读模型 / 音效。 - 被覆盖：按文件名排序，后面的包赢；改前缀或删掉冲突包。
- 图片读不出来：PNG / JPG，尺寸建议 16 的整数倍，最大 256；水 / 岩浆动画只取第一帧。
- 画面异常：移除
shaders\覆盖，检查visual.json数值；SPIR-V 必须匹配当前布局。
性能
默认渲染距离 8 区块，可调 4–16。拉高会同时增加区块生成、网格、内存和显存压力；编辑方块时周围 3×3×3 区块仍在主线程同步重建，连续大面积 /fill 会卡一下。
区块网格在线程池里生成，但每帧最多生成 3 列、入队 8 个、上传 8 个；刚传送到新区域时会看到逐步加载。跑分和截图用隐藏窗口 + 关 vsync，数字比实际游戏高，不要拿它当帧率结论。
笔记本先确认在用独显、电源模式不是节能；后台占 GPU 的软件（浏览器硬件加速、录屏）也会影响。
反馈时带什么
- 版本号：窗口标题、F3 面板或
/version。 - 系统版本、显卡型号和驱动版本。
- 复现步骤：在哪个模式、做了什么、能不能稳定复现。
- 控制台输出，尤其是 Vulkan 和
[mod:...]行。 - 如果是存档问题，先备份
saves\，不要直接发整个存档除非你愿意。
发到 论坛、编程社区，或邮件 admin@caellab.com。
这些不是 bug
- 没有方块光源传播，洞穴和室内没有火把照明。
- 设置不持久化，重启回到默认。
- 客户端玩家背包 / 位置不存档，远端玩家不参与碰撞。
- 联机没有密码、认证、加密、NAT 穿透和 PvP。
- 模组没有热重载、客户端执行、自定义模型和流体。
- 雨雪是屏幕特效，不会落到地面，也没有声音。
完整的功能边界见 版本说明。