sfcraft-docs/assets/items

物品贴图

crafting 合成组件里的物品贴图不需要手工准备：构建时由 Hugo 自己解析、下载并缓存。 写 a1="diamond" 就会显示钻石，不用先把 diamond.png 放进仓库，也不用跑任何同步脚本。

直接 hugo / hugo server 即可。

解析顺序

每个物品 id 依次尝试，命中即止（实现见 layouts/_partials/sfcraft/item-texture.html）：

1. 本目录 assets/items/<id>.png —— 手动放入的贴图，优先级最高；
2. sfcraft 仓库 textures/item/<id>.png —— 自定义物品，版本由 hugo.yaml 中 params.itemTextures.repo.baseURL 的 ref 决定；
3. Minecraft wiki —— 原版物品，按 <英文名>_JE<版本>[_BE<版本>].png 的命名 列出候选并自动挑选最新版本渲染。

无论来自哪一层，贴图最终都发布到 /sfc/items/<id>.png， 所以把某个物品从 wiki 换成手动贴图不会改变页面里的 URL。

缓存

抓取结果写进 Hugo 的 getresource 文件缓存，hugo.yaml 里设为永不过期， 因此每个 URL 全局只下载一次：

• 首次构建需要联网（本仓库当前的配方约需数秒）；
• 之后的构建全部命中缓存，离线也能完整构建；
• 需要拉取上游更新（sfcraft 换了贴图、wiki 出了新版本渲染）时执行 hugo --ignoreCache。

缓存默认在 hugo config | grep cachedir 指向的目录。CI 里建议把它固定下来并缓存该目录：

hugo --cacheDir "$PWD/.hugo-cache"

这样只有第一次构建需要访问 raw.githubusercontent.com 与 zh.minecraft.wiki。 若 CI 完全不允许联网，把需要的贴图提交到本目录即可（第 1 层优先级最高）。

手动放入贴图

需要覆盖上游贴图，或某个物品自动解析不到时，把文件放到 assets/items/<id>.png， 文件名（不含 .png）就是引用时的 id。这些文件会提交进仓库。

推荐 16×16 或 32×32 的像素风贴图，image-rendering: pixelated 会保证放大后依然锐利。

解析不到怎么办

构建会报错并指出页面与物品 id：

ERROR /vanilla/items/xxx 引用的物品 "diamnod" 没有对应贴图。请检查 id 拼写, 或把贴图放进 assets/items/diamnod.png

常见原因与处理：

• id 拼错 —— 改正 id；
• wiki 上的英文名不符合自动推导规则（如 TNT、Dragon's_Breath） —— 在 data/sfcraft/wiki_aliases.yaml 里补一条 id → 英文名的映射；
• 确实没有现成贴图 —— 手动放进 assets/items/。

网络故障、被限流或上游异常时不会被当成「id 写错」：这类情况只告警并显示 ? 占位符， 不阻断构建，方便离线时继续写文档。

想让缺失贴图也不阻断构建，可把 hugo.yaml 中 params.itemTextures.onMissing 从 error 改成 warn 或 ignore。

组件用法

{{< crafting
  a1="diamond" a2="diamond" a3="diamond"
  b1=""        b2="stick"   b3=""
  c1=""        c2="stick"   c3=""
  out="diamond_pickaxe"
  caption="钻石镐（可选）"
>}}

• a1~c3：3×3 合成格的九个格子，out：输出格；
• 值 = 物品 id，留空 / 省略 / . = 空格子；
• 需要显示堆叠数量时写 名称:数量，例如 b2="stick:2"；
• caption 可选，显示在组件下方居中说明文字。

pattern 别名模式（另一种写法）

不想数格子时，可以用 pattern 先画好形状，再为每个字符别名指定物品：

{{< crafting
  pattern="a a a\nb b b\nc c c"
  a="diamond"
  b="stick"
  c=""
  out="diamond_pickaxe"
  caption="钻石镐"
>}}

• pattern 共 9 个 token（3 行 × 3 列），必须写在一行内，行间用 \n 表示；
• 每个 token 对应一个同名参数（a、b、c…），参数值就是物品 id；
• token 也可以直接写物品 id：pattern="diamond stick ."；
• . 表示空格子（写在 pattern 里，或作为别名的值，都算空格子）；
• 同时给出 pattern 和 a1~c3 时，以 pattern 为准（out 两者通用）。