从源码构建

只有一条构建路线：项目根的 build.bat，先 vcvars64.bat，再用 Visual Studio 自带的 CMake + Ninja 生成 Release。Windows 上让 CMake 直接选 Visual Studio 生成器可能找不到编译器，项目只维护 vcvars64 + Ninja 这条路线。

需要什么

Windows 10 / 11 x64。
Visual Studio，安装「使用 C++ 的桌面开发」工作负载，带 CMake 和 Ninja。
Git（首次配置要拉 GLFW 和 glm）。
支持 Vulkan 1.3 的显卡驱动；构建本身不需要 Vulkan SDK。
只有改着色器时才需要带 SPIR-V 后端的 dxc。

build.bat 默认写的是 C:\Program Files\Microsoft Visual Studio\18\Community。装在别处就改文件开头的 VSBASE。

构建

终端 / 项目根 / build.bat
build.bat

脚本会调用 vcvars64.bat，用 VS 自带的 CMake 配置 build/，再调 Ninja 并行编译。产物是 build\CaelCraft.exe，shaders\ 会自动复制到 exe 旁边。

第一次配置会通过 FetchContent 拉 GLFW 3.4 和 glm 1.0.1。网络慢时先设代理，不要改依赖来源：

终端 / 代理
set HTTP_PROXY=http://127.0.0.1:7897
set HTTPS_PROXY=http://127.0.0.1:7897

端口换成你自己的代理。构建目录是输出目录：build/ 里的截图、imgui.ini、saves/ 都不是源码；加版本控制时忽略。

着色器

源码是 shaders/ 下的 HLSL：block.hlsl（场景，VSMain / PSMain）、shadow.hlsl（阴影，VSMain）和 post.hlsl（全屏后处理，多个入口）。编译产物 .spv 已经提交，只跑游戏不需要 dxc。build.bat 不会编译着色器，只拷贝现成的 .spv。

改了 HLSL 后运行：

终端 / 项目根 / 编译着色器
tools\compile_shaders.bat

脚本会找一个带 SPIR-V 后端的 dxc，也可以用环境变量 CAELCRAFT_DXC 指定完整路径。Windows SDK 自带的 dxc 没有 SPIR-V 后端，别用它。

顶点布局是 pos / uv / shade / layer（src/core/Mesh.h）。改 Vertex 必须同时改 HLSL 的 VSInput 和 VulkanRenderer 的 pipeline attribute 描述。push constants 正好 128 字节，改布局要 HLSL 和 C++ 两边一起改。

每帧的 pass 顺序是：3 次阴影级联 → 场景到 HDR 离屏目标 → SSAO → Bloom 链 → 自动曝光 → 合成 → FXAA 到交换链 → HUD。场景阶段用 set 0（纹理数组、VisualParams、FrameParams、阴影图），后处理阶段用自己那套 set 0 和 4 个 float4 push constants。改这些接口要同步改 shaders/post.hlsl 和 VulkanRenderer.cpp 的创建代码。

自检与测试

命令行测试
参数	作用
`--selftest`	无窗口自检：网格数量、碰撞、落地、起跳、生物落地、村庄 / 村民生成、背包堆叠 / 消耗、掉落物合并 / 落地 / 拾取、存档文件夹往返、网络改动捕获、方块修改存档。
`--nettest`	本机起一对主机 / 客户端，验证握手、可靠传输、12000 条修改（跨可靠窗口）、客户端应用编辑和 `EditRequest`。
`--modtest`	生成临时 `.mod.caelc`，验证加载、方块注册、命令、取消破坏、数据读写和死循环预算，跑完自动删除。
`--hosttest`	在中文界面下走真实开服流程（建临时世界再删），防翻译格式串崩。
`--benchmark`	隐藏窗口跑 240 帧，打印 fps。
`--screenshot <文件> [模式]`	隐藏窗口渲染 3 帧后写 PNG；不写模式就是出生点视角。

自检会在 saves/ 下写临时存档文件夹再删掉。跑分和截图都是隐藏窗口 + 关 vsync，别拿它们的 fps 当实际游戏帧率。

截图是 PNG（8 位 RGB）。文件名不带目录时写进 exe 目录的 screenshots/，带目录就按给定路径写；目录不存在会自动创建。PNG 里带 EXIF 和文本块，记录版本、世界名、种子、坐标、游戏内时间、天气、游戏模式和拍摄时间，用 exiftool 或 Pillow 能直接读出来。输出前会渲染 3 帧，隐藏窗口第一帧拿不到正确尺寸，抓早了会得到被裁掉的图。

截图模式

截图模式
模式	内容
`menu`	世界里的暂停菜单。
`main` / `worlds` / `multiplayer`	主菜单、多存档列表、联机页。
`players`	远端玩家模型和名字标签。
`mob` / `pig` / `villager`	史莱姆、猪、村民特写。
`cmd`	命令输入行示例。
`survival` / `inventory` / `dead`	生存 HUD、背包、死亡界面。
`village` / `rain` / `drops`	村庄俯视、下雨、掉落物特写。
`mod`	最后注册的模组方块特写（需装模组）。
`spectator` / `fill`	旁观视角、填充示例。

用法：

终端 / 项目根 / 截图
build\CaelCraft.exe --screenshot out.png
build\CaelCraft.exe --screenshot out.png village
build\CaelCraft.exe --screenshot out.png inventory

打包发布

构建完成后，项目根运行：

终端 / 项目根 / 打包
python tools\package_release.py

脚本从 build\build.ninja 读版本号，把 exe、着色器、VC++ 运行库和示例模组 / 材质包放到 dist\stage\，生成便携版 zip 和 Inno Setup 安装包，并把产物、SHA-256 和 release.json 复制到 website\downloads\。安装包用 Inno Setup 6 编译，脚本默认找 C:\Program Files (x86)\Inno Setup 6\ISCC.exe。

改完文案后分别构建两边：文档在 docs-site 里运行 npm run build（Docusaurus 输出到 website/docs）；主站运行 python website\build.py 重新生成首页、下载页、搜索索引和 sitemap。两边互不覆盖。

文档与主站
cd docs-site
npm run build
cd ..
python website\build.py

项目结构

项目结构
路径	职责
`src/main.cpp`	主循环、模式切换、输入、UI、自检和截图入口。
`src/core/`	世界存储、地形 / 村庄生成、区块、方块、网格、存档、语言、版本。
`src/game/`	玩家、生物、背包、掉落物、区块流式加载、Lua 模组。
`src/net/`	UDP、可靠通道、地址解析（含 SRV）、联机协议。
`src/render/`	Vulkan 渲染器、程序化方块纹理、资源包。
`shaders/`	HLSL 源码和编译好的 SPIR-V。
`third_party/`	ImGui、volk、VMA、Vulkan 头、Lua 5.4.7、stb_image、miniz。
`tools/`	着色器编译和发布打包脚本。
`website/`	官网源（`_src/`）和生成后的静态站。

构建常见问题

找不到编译器：确认 VSBASE 指向正确的 VS 安装，且安装了 C++ 桌面工作负载。不要换 Visual Studio 生成器。
FetchContent 卡住：设置 HTTP_PROXY / HTTPS_PROXY，不要改 GLFW / glm 的来源。
dxc 报错：确认是带 SPIR-V 后端的 dxc；Windows SDK 自带的不行。
运行时画面黑 / 退出：先确认显卡驱动支持 Vulkan 1.3 或 VK_KHR_dynamic_rendering，见故障排查 / 启动。

需要什么​

构建​

着色器​

自检与测试​

截图模式​

打包发布​

项目结构​

构建常见问题​