资源包

资源包放在 exe 旁边的 resourcepacks\。支持原生布局和 Minecraft 材质包，也支持用 visual.json 调画面、用 SPIR-V 替换着色器阶段。装完要重启游戏。

放哪里、怎么加载

resourcepacks\ 下每个文件夹、每个 .rp.caelc（本质是 zip）或 .zip 都是一个包。按文件名排序，后面的覆盖前面的；所以可以用 01_base.rp.caelc、02_tweak.rp.caelc 控制顺序。

扫描时只看这一层：文件夹里的子目录不会单独成为一个包。压缩包的内容必须直接在 zip 根目录，不要套一层 MyPack\。

资源包是稀疏覆盖：包里有什么换什么，缺的层回退到模组贴图，最后回退到程序化纹理。基础游戏不依赖任何资源包文件。

没有热重载。装完、改了图片或 visual.json 都要重启游戏；主菜单和暂停菜单里的「打开材质包文件夹」会先建目录再打开资源管理器。

原生包结构

原生资源包 / 文件夹或 zip
my_pack\
  visual.json                  可选
  textures\
    stone.png                  覆盖石头
    grass_top.png              覆盖草顶
    water.png                  水面（可放动画条带）
  shaders\                     可选，高级用法
    block_vs.spv               场景顶点（必须）
    block_fs.spv               场景片元（必须）
    shadow_vs.spv              阴影投射（可选）
    composite_fs.spv           合成与调色（可选）
    final_fs.spv               FXAA / 最终输出（可选）

纹理也可以放在 textures\block\<layer>.png，或者直接放在包根目录的 <layer>.png。查找顺序是 textures/<layer>.png、textures/<layer>.jpg、textures/block/<layer>.png、<layer>.png。所以 PNG 优先，JPG 也能读。

可覆盖的纹理层

内置纹理层 0–27 的顺序是冻结的；资源包用层名匹配，不用记数字。模组注册的纹理层会追加在后面，名字是 <模组 id>_<文件名>。

纹理层列表
分组	层名
地形	`grass_top` `grass_side` `dirt` `stone` `sand` `wood_side` `wood_top` `leaves` `snow` `planks` `cobblestone` `bricks` `bookshelf` `gravel`
流体	`water` `lava`
生物	`slime_body` `slime_face` `pig_body` `pig_face` `villager_face` `villager_coat` `villager_skin`
玩家	`player_face` `player_shirt` `player_pants`
HUD	`heart_full` `heart_empty`

水面和岩浆走半透明 / 不透明管线；水材质的 alpha 会参与混合，做半透明水时别把 alpha 写死成 255。生物脸和红心是 16×16 像素画，脸只画在模型的 +X 面。

模组方块的纹理层名来自注册时的图片文件名。例如模组 ruby 注册 textures/ruby_block.png，层名是 ruby_ruby_block；资源包里写 textures/ruby_ruby_block.png 就能覆盖它。

尺寸

纹理数组的统一尺寸从 16 开始，取包内最大层的尺寸，向上取到 2 的幂，上限 256。小于目标尺寸的层会被缩放。建议直接用 16×16、32×32 或 64×64 的方块纹理；超过 256 会被压到 256。

水面 / 岩浆可以放竖条动画，但当前只取第一帧；每帧宽度等于图片宽度，高度是宽度的整数倍。想要动画效果，目前只能靠着色器。

visual.json

包根目录放一个 visual.json，可以调雾、曝光、阴影和整条后处理链。所有字段都是可选的，缺的用默认值；后面的包覆盖前面的包。

visual.json / 示例
{
  "fog_start": 72,
  "exposure": 1.04,
  "saturation": 1.05,
  "ambient": 0.24,
  "water": 1.0,
  "shadow_strength": 0.8,
  "shadow_distance": 0,
  "bloom": 0.3,
  "bloom_threshold": 1.1,
  "ssao": 0.6,
  "auto_exposure": 1,
  "exposure_bias": 1.0,
  "fxaa": 1
}

visual.json 字段
字段	默认	作用
`fog_start`	雾终点 − 50	雾开始的距离；不给就按渲染距离自动算。
`exposure`	1.0	整体曝光，在合成阶段应用。
`saturation`	1.0	色彩饱和度。
`ambient`	0.22	环境光强度。
`water`	1.0	水面色调 / 强度参数。
`shadow_strength`	0.75	阴影强度，0 等于关掉；夜间按日照自动减弱。
`shadow_distance`	0（自动）	阴影覆盖距离；0 表示按渲染距离算（64–192 格）。
`bloom`	0.35	泛光强度，0 关闭。
`bloom_threshold`	1.0	泛光提取阈值，越高只有越亮的部分发光。
`ssao`	0.6	环境光遮蔽强度，0 关闭。
`auto_exposure`	1	1 开启自动曝光，0 只用固定 `exposure`。
`exposure_bias`	1.0	自动曝光之外的额外倍率。
`fxaa`	1	1 开启 FXAA，0 关闭。

读取逻辑很简单：找键名，取后面的数字，不做严格 JSON 解析，也不做范围校验。保持数值合理，别写 NaN 或极端值。

Minecraft 材质包

包根目录有 pack.mcmeta 时按 Minecraft 布局识别。它只映射 16 个方块层和两颗心，不读模型、音效、语言文件或 pack_format 的具体数值。

Minecraft 材质映射
CaelCraft 层	Minecraft 路径
`grass_top`	`assets/minecraft/textures/block/grass_block_top.png`（旧版 `grass_top.png`）
`grass_side`	`.../grass_block_side.png`（旧版 `grass_side.png`）
`dirt` / `stone` / `sand`	`.../dirt.png`、`stone.png`、`sand.png`
`wood_side` / `wood_top`	`.../oak_log.png`、`oak_log_top.png`（旧版 `log_oak.png`）
`leaves`	`.../oak_leaves.png`（旧版 `leaves_oak.png`）
`snow` / `water` / `lava`	`.../snow.png`、`water_still.png`、`lava_still.png`
`planks` / `cobblestone` / `bricks` / `bookshelf` / `gravel`	对应的原版方块路径。
`heart_full` / `heart_empty`	`assets/minecraft/textures/gui/sprites/hud/heart/full.png`、`.../container.png`

水 / 岩浆的动画条带只取第一帧。材质包根目录不要套文件夹；有 pack.mcmeta 就直接放在 zip 根目录。

下载页的 examples/mc_example.rp.caelc 是一个最小可用的 MC 材质包示例，可以解压看路径。

着色器覆盖

高级用法：包根目录的 shaders/ 可以替换渲染阶段。每个阶段单独回退，缺哪个用内置的：

可替换的着色器阶段
文件	入口	作用
`block_vs.spv` / `block_fs.spv`	`VSMain` / `PSMain`	场景几何（区块、生物、掉落物、粒子、水面）。
`shadow_vs.spv`	`VSMain`	阴影投射，深度-only，被调 3 次（3 级级联）。
`composite_fs.spv`	`FSComposite`	合成：AO、泛光、曝光、色调映射、饱和度。
`final_fs.spv`	`FSFxaa`	最终输出（内置版本是 FXAA），在交换链上绘制，HUD 之后画。

场景阶段用的是一套固定接口，改它必须逐字节匹配：

顶点布局仍然是 pos / uv / shade / layer。
push constants 仍然是 128 字节：viewProj、cameraPos（w = 日照）、objectPos（w = 时间）、objectParams、skyColor（w = 雾终点）。
set 0 binding 0：方块纹理数组；binding 1：VisualParams（32 字节）；binding 2：FrameParams（416 字节）；binding 3：阴影图 Texture2DArray。

FrameParams 包含 3 个级联光照矩阵、分割距离、太阳方向与强度、相机位置 / 前向、屏幕尺寸和逆 viewProj，C++ 结构在 VulkanRenderer.h，HLSL 镜像在 shaders/block.hlsl。

合成和最终阶段走另一套管线布局：set 0 的 binding 0–7 依次是场景色、场景深度、模糊后的 AO、3 张泛光图、1×1 曝光值和 LDR 结果，binding 8 是同一份 FrameParams，binding 9 是未模糊的 AO；push constants 是 4 个 float4。这些阶段的全屏顶点着色器入口是 FSQuadVS，不需要顶点缓冲。

加载前会检查 SPIR-V 魔数；某个阶段读取或创建失败只会回退该阶段，不会连坐其他阶段。写之前建议先读 shaders/block.hlsl、shaders/shadow.hlsl 和 shaders/post.hlsl。

Iris / OptiFine 的 GLSL 光影包（.vsh / .fsh、shaders.properties、gbuffers 目录）不能直接加载，引擎不解析这套格式；需要按上面的接口重写成 SPIR-V。

打包成 .rp.caelc

.rp.caelc 就是改名的 zip。把 visual.json、textures\（以及可选的 shaders\）放在 zip 根目录，然后把扩展名改成 .rp.caelc。不要套一层文件夹。

放好后重启游戏。主菜单和暂停菜单都有「打开材质包文件夹」按钮；加载日志会打印每个包应用了多少层，方便确认有没有被识别。

没生效时

包没被识别：确认扩展名是 .rp.caelc 或 .zip，且放在 resourcepacks\ 第一层。
路径不对：原生包用 textures/stone.png；MC 包必须有根目录的 pack.mcmeta 和 assets/minecraft/...。
被后面的包覆盖：按文件名排序，后面的赢；改前缀或删掉冲突的包。
图片读不出来：用 PNG / JPG，确认不是损坏文件；尺寸别超过 256 的 2 的幂。
改了没反应：没有热重载，重启游戏。
画面异常：先移除 shaders\ 覆盖，再看 visual.json 的数值。

更多见故障排查 / 资源包。

放哪里、怎么加载​

原生包结构​

可覆盖的纹理层​

尺寸​

visual.json​

Minecraft 材质包​

着色器覆盖​

打包成 .rp.caelc​

没生效时​

放哪里、怎么加载

原生包结构

可覆盖的纹理层

尺寸

visual.json

Minecraft 材质包

着色器覆盖

打包成 .rp.caelc

没生效时