sfcraft-docs/layouts/_partials/sfcraft/item-texture.html

{{- /* SFCraft 物品贴图解析器

  把物品 id 解析成一个图片 Resource, 全程由 Hugo 完成, 不需要外部同步脚本。

  查找顺序 (命中即止):
    1. assets/items/<id>.png                手动放入的贴图, 优先级最高
    2. sfcraft 仓库 textures/item/<id>.png   自定义物品
    3. Minecraft wiki                        原版物品, 自动挑选最新版本渲染

  抓取结果由 Hugo 的 getresource 文件缓存持久化 (hugo.yaml 中 maxAge: -1),
  因此每个 URL 全局只下载一次; 后续构建离线也能完成。

  入参:
    id  物品 id (assets/items 下的文件名, 不含 .png)

  返回 dict:
    image   图片 Resource, 未解析出来时为 nil
    source  "local" / "sfcraft" / "wiki", 未解析出来时为 ""
    status  "ok"       已解析
            "missing"  各来源都明确不存在该贴图 (id 很可能写错了)
            "degraded" 有来源访问失败 (离线 / 限流 / 服务异常), 结论不可靠
    detail  status 非 ok 时的诊断信息

  调用方应使用 partialCached 并以 id 作为 key, 使同一 id 每次构建只解析一次。
*/ -}}

{{- $id := .id -}}
{{- $cfg := site.Params.itemTextures | default dict -}}
{{- $repo := $cfg.repo | default dict -}}
{{- $wiki := $cfg.wiki | default dict -}}
{{- $localDir := $cfg.localDir | default "items" -}}
{{- $publishDir := $cfg.publishDir | default "sfc/items" -}}
{{- $opts := dict "headers" (dict "User-Agent" ($cfg.userAgent | default "sfcraft-docs")) -}}

{{- $image := false -}}
{{- $source := "" -}}
{{- $notes := slice -}}

{{- /* 1. 本地贴图 (手动放入的永远优先, 便于覆盖上游) */ -}}
{{- with resources.Get (printf "%s/%s.png" $localDir $id) -}}
  {{- $image = . -}}
  {{- $source = "local" -}}
{{- end -}}

{{- /* 2. sfcraft 仓库的自定义物品贴图
       404 时 GetRemote 返回 nil 且不报错, 正好作为"该物品不是自定义物品"的信号,
       可以直接落到下一个来源; 其余状态码 (403/429/5xx) 与网络故障会置 .Err。 */ -}}
{{- if and (not $image) (ne $repo.enable false) $repo.baseURL -}}
  {{- $url := printf "%s%s.png" $repo.baseURL $id -}}
  {{- with try (resources.GetRemote $url $opts) -}}
    {{- with .Err -}}
      {{- $notes = $notes | append (printf "sfcraft 仓库访问失败: %s" (replaceRE `^.*error calling GetRemote: ` "" (printf "%s" .))) -}}
    {{- else with .Value -}}
      {{- $image = . -}}
      {{- $source = "sfcraft" -}}
    {{- end -}}
  {{- end -}}
{{- end -}}

{{- /* 3. Minecraft wiki 的原版物品渲染图 */ -}}
{{- if and (not $image) (ne $wiki.enable false) $wiki.api -}}
  {{- $lookup := partialCached "sfcraft/wiki-lookup.html"
        (dict "id" $id "api" $wiki.api "opts" $opts) $id -}}
  {{- with $lookup.notes -}}{{- $notes = $notes | append . -}}{{- end -}}
  {{- with $lookup.url -}}
    {{- with try (resources.GetRemote . $opts) -}}
      {{- with .Err -}}
        {{- $notes = $notes | append (printf "wiki 贴图下载失败 (%s): %s" $lookup.name (replaceRE `^.*error calling GetRemote: ` "" (printf "%s" .))) -}}
      {{- else with .Value -}}
        {{- $image = . -}}
        {{- $source = "wiki" -}}
      {{- else -}}
        {{- $notes = $notes | append (printf "wiki 贴图不存在 (%s)" $lookup.name) -}}
      {{- end -}}
    {{- end -}}
  {{- end -}}
{{- end -}}

{{- /* 统一发布路径, 使贴图来源变化 (wiki -> 手动放入) 时页面上的 URL 不变 */ -}}
{{- $status := "missing" -}}
{{- if $image -}}
  {{- $status = "ok" -}}
  {{- $image = resources.Copy (printf "%s/%s.png" $publishDir $id) $image -}}
{{- else if $notes -}}
  {{- /* 有来源没能给出确定答案, 不能断言 id 写错了 */ -}}
  {{- $status = "degraded" -}}
{{- end -}}

{{- return dict
      "image" (cond (eq $status "ok") $image nil)
      "source" $source
      "status" $status
      "detail" (delimit $notes "; ") -}}