构建 / 开发脚本

用途

sync-items.ps1 会在构建和开发前自动保证物品贴图齐全:

下载 sfcraft 仓库的全部自定义贴图到 assets/items/;
扫描 content/ 中所有 crafting 组件用到的物品 id;
本地缺失的原版物品从 Minecraft wiki 自动获取(自动挑选最新版本渲染);
有任何物品无法找到时, 打印缺失清单并以非零码退出, 阻断构建 / 开发启动。

使用

.\scripts\build.ps1            # 同步贴图 + hugo 构建
.\scripts\dev.ps1              # 同步贴图 + hugo server
.\scripts\dev.ps1 -NoSync      # 仅启动开发服务器, 不重新同步

若 PowerShell 执行策略阻止脚本, 请用:

powershell -ExecutionPolicy Bypass -File scripts\dev.ps1

脚本通过 $env:HUGO 或 PATH 查找 hugo, 找不到时也会探测 winget 安装位置。

Linux / macOS 使用

Unix 环境下使用同名的 bash 脚本(同步逻辑为 Python 3 实现, 需要 python3 与 hugo):

./scripts/build.sh            # 同步贴图 + hugo 构建
./scripts/dev.sh              # 同步贴图 + hugo server
./scripts/dev.sh -NoSync      # 仅启动开发服务器

也可以使用 Makefile(Windows / Unix 通用, 自动选择对应脚本):

make build                    # 同步贴图 + hugo 构建
make dev                      # 同步贴图 + hugo server
make sync                     # 仅同步贴图
make dev HUGO_ARGS="--port 1314"

首次使用前请确认脚本有执行权限: chmod +x scripts/*.sh。

组件写法

crafting 组件支持两种设置方式, 详见 assets/items/README.md:

九格直填: a1="diamond" a2="stick" ... out="diamond_pickaxe";
pattern 别名: pattern="a a a\nb b b\nc c c" + a="diamond" b="stick"。

贴图同步扫描器对两种写法都会收集物品 id。

规则细节

sfcraft 自定义贴图: 每次构建比对远端文件大小, 缺失或变化时更新;
原版贴图: 只在本地缺失时下载, 不会覆盖手动放入 assets/items/ 的贴图;
物品 id 即 assets/items/ 下的文件名(不含 .png);
wiki 命名规则: <英文名>_JE<版本>[_BE<版本>].png, 特殊命名(如 TNT、Flint_and_Steel) 由 sync-items.ps1 / sync-items.py 中的变体生成与别名表处理。

网络要求

需要能访问 api.github.com、raw.githubusercontent.com 与 zh.minecraft.wiki。若 CI 或离线环境不允许联网, 建议把 assets/items/ 下的贴图提交进仓库。