Minecraft 材料表工具集 — 完整指南

目录

1. 项目概述
2. 功能特性
3. 项目结构
4. 技术架构
5. 使用指南
6. 文件格式说明
7. 翻译映射表维护
8. Python 参考实现
9. 部署说明
10. 常见问题

---

1. 项目概述

Minecraft 材料表工具集是一个纯前端 Web 应用，专为中大型 Minecraft 建筑工程设计。核心功能：

• 从投影文件提取材料清单：直接解析 Litematica 的 .litematic 文件，统计所有方块数量
• 英文方块名自动翻译：内置 1000+ 条 Minecraft 中英文翻译映射表，覆盖至 1.21.5
• 材料智能分组：后缀/前缀匹配 → 二级拼音排序 → 小组自动合并到语义父类
• 导出功能：支持 CSV 和 XLSX 格式导出

项目采用冰蓝霜白玻璃质感 UI 设计，支持亮色/暗色双模式，移动端完全适配。

---

2. 功能特性

Tab 1 — 投影转换

功能	说明
拖拽上传	拖拽或点击选择 .litematic 文件
NBT 解析	完整 NBT 二进制解析器（纯 JavaScript）
GZip 解压	浏览器原生 DecompressionStream API
方块解码	连续位流解码，支持跨 long 边界
文件信息	版本、尺寸、方块总数、实体数等
翻译缺失警告	自动检测未翻译方块名，可下载日志
CSV 导出	序号/英文名/中文名/总数/组数/盒数
桥接到分配	一键发送数据到材料分配标签页

Tab 2 — 材料分配

功能	说明
CSV 导入	自动识别新旧两种 CSV 格式
智能分组	后缀/前缀匹配 → 二级拼音排序 → 小组父类合并
搜索过滤	按名称、组号、数量实时过滤
二级排序	同组内材料按拼音排序（橡木→白桦→云杉…）
XLSX 导出	含材料组、收集者列、分组合并行、汇总行、数字千位格式
分组统计	每组显示材料种类数徽章

---

3. 项目结构

材料表工具/
├── index.html                          ★ 主入口（合并版，推荐使用）
├── 爱弥斯.jpg                          网站图标
├── README.md                          本文档
├── parse_litematic.py                  Python 参考实现（调试/验证）
│
├── assets/                             ★ 核心资源
│   ├── script.js                      合并版 JavaScript（~1100 行）
│   └── style.css                      冰蓝霜白玻璃质感样式（~1600 行）
│
├── block-csv-tool/                    旧版独立 — 投影转换（不再维护）
│   ├── minecraft-translations.js      ★ 翻译映射表（仍被合并版引用）
│   └── ...
│
└── csv-assign-tool/                   旧版独立 — 材料分配（不再维护）
    └── ...

---

4. 技术架构

纯前端 / 零依赖

• 无框架、无构建工具、原生 HTML + CSS + JavaScript
• 外部依赖仅 SheetJS CDN（XLSX 导出），加载失败有降级提示

UI 设计：冰蓝霜白玻璃质感

背景：冰蓝渐变 #e6eef6 → #f5f6f9
面板：rgba(255,255,255,0.68) + backdrop-filter: blur(18px)
强调色：#5b8cac（冰蓝）
圆角：12-16px
阴影：蓝灰调多层漂浮感
暗色模式：@media (prefers-color-scheme: dark) 自动切换

核心技术点

NBT 解析 + 方块解码

.litematic → GZip解压 → NBT解析 → 提取调色板 + BlockStates
  → 连续位流解码（BigInt，跨 long 边界）
  → 统计每种方块数量

材料智能分组（三级处理）

第一级：后缀/前缀匹配 → 提取材料基类（如「楼梯」「木板」）
第二级：同组内按中文拼音排序（localeCompare zh-CN）
第三级：≤2 种的碎片组自动合并到语义父类（如按钮+压力板→红石元件）

18 个语义父类：红石元件、围栏类、砖石类、功能方块、容器类、矿车铁轨、光源类、玻璃类、植物类、珊瑚类、锁链格栅、特殊方块、粘性方块、告示装饰、矿石原矿、紫水晶类、树脂泥砖等。

翻译映射

block-csv-tool/minecraft-translations.js — 1000+ 条目，覆盖至 Minecraft 1.21.5。

---

5. 使用指南

5.1 Tab 1：投影转换

1. 打开 index.html，默认显示「投影转换」
2. 拖拽或点击上传 .litematic 文件
3. 等待进度条完成（GZip解压 → NBT解析 → 方块解码 → 渲染）
4. 查看文件信息、翻译警告（如有）、材料清单表格
5. 导出 CSV 或「发送到材料分配」

5.2 Tab 2：材料分配

数据来源：从 Tab 1 桥接，或手动导入 CSV。

界面：

• 上传区：导入后自动折叠为紧凑条（可点击重新导入）
• 搜索框：按名称、组号、数量实时过滤
• 统计栏：显示材料种类数 · 材料组数
• 材料表格：按组排列，组内拼音排序
• 导出 XLSX：含分组合并行、汇总行

分组显示：

材料组 #1  [楼梯]  8 种          ← 冰蓝胶囊标签 + 数量徽章
  橡木楼梯      64     1组    0盒
  白桦木楼梯   128     2组    0盒
  ...

材料组 #5  [红石元件]  12 种     ← 自动合并的小组
  按钮         32     0组    0盒
  压力板       16     0组    0盒
  ...

---

6. 文件格式说明

输入：.litematic

GZip 压缩的 NBT 格式文件，结构见 README 旧版（保持不变）。

导出：CSV

序号,英文名称,中文名称,总数,组数,盒数
1,white_concrete,白色混凝土,1637,26,1
...

UTF-8 with BOM，兼容 Excel。

导出：XLSX

序号	中文名称	总数	组数	盒数	材料组	材料收集者
1	白色混凝土	1,637	26	1	材料组1
═══ 材料组 1 ═══
1	石砖	892	14	1	材料组2
	合计 256 种材料	6,733	319	12	18 个材料组

• 分组合并行：═══ 材料组 N ═══ 跨列合并
• 数字列千位分隔格式
• 末尾汇总行

---

7. 翻译映射表维护

位置：block-csv-tool/minecraft-translations.js

添加新条目后在 MINECRAFT_BLOCK_TRANSLATIONS 对象中新增即可。验证：

python block-csv-tool/_verify_translations.py

---

8. Python 参考实现

parse_litematic.py — 独立 Python 脚本，用于调试和验证。修复了连续位流解码（跨 long 边界）的问题，与 JS 版本保持一致。

python parse_litematic.py path/to/file.litematic

---

9. 部署说明

本地使用

双击 index.html 即可。

Web 服务器

放到任意静态服务器即可（Python HTTP、Nginx、Vercel 等）。

离线使用

下载 xlsx.full.min.js 到本地，修改 index.html 中的 CDN 引用。

浏览器兼容性

功能	最低版本
GZip 解压	Chrome 80+, Safari 16.4+
BigInt	Chrome 67+, Safari 14+
backdrop-filter	Chrome 76+, Safari 9+
:has() 选择器	Chrome 105+, Safari 15.4+

---

10. 常见问题

Q: 材料分组不准确？

A: 分组分三级处理：

1. 后缀/前缀匹配（MATERIAL_SUFFIXES / MATERIAL_PREFIXES）
2. 组内拼音排序
3. 小组自动合并（PARENT_CATEGORIES 映射表）

可编辑 assets/script.js 中对应的数组和映射表进行调整。

Q: 导出的 CSV 在 Excel 中乱码？

A: CSV 使用 UTF-8 with BOM。如仍乱码，使用 Excel「数据 → 从文本/CSV 导入」，选择 UTF-8。

Q: 移动端使用体验？

A: 已完整适配：

• 毛玻璃 sticky 标签导航
• 左右滑动手势切换标签
• 表格水平滚动 + 手机端自动隐藏次要列
• iOS Safari 文件选择兼容
• 安全区域适配（刘海屏）
• 暗色模式自动跟随系统

---

© 2026 材料表工具集 — Minecraft 社区建筑材料管理工具