# 物品贴图

`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 里建议把它固定下来并缓存该目录：

```bash
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`。

## 组件用法

```markdown
{{< 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` 先画好形状，再为每个字符别名指定物品：

```markdown
{{< 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` 两者通用）。