71 lines
2.5 KiB
Markdown
71 lines
2.5 KiB
Markdown
# 构建 / 开发脚本
|
||
|
||
## 用途
|
||
|
||
`scripts/` 下全部为 Python 3 脚本（无其他语言）:
|
||
|
||
- `sync-items.py` —— 物品贴图自动同步（核心）;
|
||
- `build.py` —— 同步贴图 + hugo 构建;
|
||
- `dev.py` —— 同步贴图 + hugo 开发服务器。
|
||
|
||
同步流程:
|
||
|
||
1. 下载 [sfcraft 仓库](https://github.com/saltedfishclub/sfcraft/tree/rev/26.2/src/main/resources/assets/sfcraft/textures/item) 的
|
||
全部自定义贴图到 `assets/items/`;
|
||
2. 扫描 `content/` 中所有 `crafting` 组件用到的物品 id（支持九格直填与 pattern 别名两种写法）;
|
||
3. 本地缺失的原版物品从 Minecraft wiki 自动获取（自动挑选最新版本渲染）;
|
||
4. 有任何物品无法找到时, 打印缺失清单并以非零码退出, 阻断构建 / 开发启动。
|
||
|
||
## 使用
|
||
|
||
Windows:
|
||
|
||
```powershell
|
||
python scripts\build.py # 同步贴图 + hugo 构建
|
||
python scripts\dev.py # 同步贴图 + hugo server
|
||
python scripts\dev.py --no-sync # 仅启动开发服务器, 不重新同步
|
||
python scripts\sync-items.py -f # 仅同步贴图(强制刷新 sfcraft 贴图)
|
||
```
|
||
|
||
Linux / macOS:
|
||
|
||
```bash
|
||
python3 scripts/build.py
|
||
python3 scripts/dev.py
|
||
python3 scripts/dev.py --no-sync
|
||
```
|
||
|
||
也可以用 Makefile（Windows / Unix 通用）:
|
||
|
||
```bash
|
||
make build # 同步贴图 + hugo 构建
|
||
make dev # 同步贴图 + hugo server
|
||
make sync # 仅同步贴图
|
||
make dev HUGO_ARGS="--port 1314"
|
||
make PY=python build # 指定 Python 解释器
|
||
```
|
||
|
||
脚本按 `$HUGO` 环境变量、PATH、winget 安装目录的顺序查找 hugo。
|
||
|
||
## 组件写法
|
||
|
||
`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.py` 中的变体生成与别名表处理。
|
||
|
||
## 网络要求
|
||
|
||
需要能访问 `api.github.com`、`raw.githubusercontent.com` 与 `zh.minecraft.wiki`。
|
||
若 CI 或离线环境不允许联网, 建议把 `assets/items/` 下的贴图提交进仓库。
|