[MD]
# MC 地图画生成器 · 更新手册
把任意图片转换为 Minecraft 地图画：自动选色、抖动、生成平面或立体方块布局，并导出为游戏可直接使用的结构文件、命令、数据包或物料清单。
## 一、快速上手（5 步）
1. **打开图片**：标题栏彩色「文档小部件」点击打开，或菜单 文件 → 打开图片（Ctrl+O）；也可从「帮助 → 加载示例工程」开始。
2. **选择方块**：左侧竖向工具栏「方块库」（Ctrl+B）勾选参与配色的方块；默认已勾选 16 种羊毛 + 16 种混凝土共 32 种。
3. **设置参数**：左侧「画面参数」面板设置画面模式（平面/立体）、抖动算法与强度、地图张数、填充方块、输出类型；必要时在上方「图像处理」面板直接调亮/调色（或 Ctrl+P 打开完整对话框）。
4. **生成预览**：点右侧蓝色「生成预览」（Ctrl+R），在 MC 预览区右上角切换方块纹理、地图配色、立体模型、色域预警四种视图。
5. **导出**：右侧工具栏「导出」（Ctrl+E）。
## 二、界面布局
- **标题栏**：左侧汉堡按钮（Alt+\\ 切换紧凑/主菜单）、文档小部件、方块库小部件；右侧为警告铃铛、预处理齿轮与窗口按钮（生成/搜索已移到两侧工具栏）。
- **标签页**：位于查看器列上方（图像处理区右侧），可同时打开多个工程，点击切换、× 关闭；未保存带 ● 标记。
- **左侧竖向工具栏**（纯图标，悬停显示名称与快捷键）：方块库（四宫格）、搜索方块（放大镜）、物料清单（清单）、批量处理（图层堆叠）。
- **左侧控制面板**（分隔条可拖拽调宽、上下可调高，随窗口自适应）：
- 上「图像处理」：预处理全部滑块内嵌（亮度/对比度/伽马/RGB/饱和度/色调分离/去色/背景），下方为「裁剪」「像素编辑」两个按钮一左一右。
- 下「画面参数」：地图画类型、抖动方式、强度、地图张数、方块库、填充方块、输出类型。
- **中央双查看器**：左为原图、右为 MC 预览（预览方式下拉在预览区右上角，标题栏含缩放比例与「复位」按钮），中间分隔条可拖动；视图菜单可切换「完整布局 / 仅预览 / 仅原图」。
- **右侧竖向工具栏**（纯图标）：生成预览（蓝色旋涡主按钮）、导出（托盘上箭头）、保存工程（软盘）、物料清单（清单）。
- **底部状态栏**：当前尺寸、方块种类、模式/抖动与操作提示；警告数量显示在标题栏铃铛上。
[ATTACH]148372[/ATTACH]
## 三、工程体系（.mcpx）
### 1. 工程文件
- **保存工程 Ctrl+S**：打包为 `.mcpx`（ZIP 格式，内含源图片与全部参数：预处理、方块选择、抖动、张数、ROI 选区、支撑方块、方案快照等）。
- **工程另存为 Ctrl+Shift+S**、**存为工程模板 .mcpt**（只存参数不含图片，可套用到其他图片）。
- **打开工程 Ctrl+Shift+O**：打开 `.mcpx` 或 `.mcpt`，打开后自动重新生成预览。
- 最近打开的工程 / 图片在文档小部件与「文件 → 最近打开」中。
### 2. 标签多工程
- 工具栏「工程 → 新建」（Ctrl+N）新建空白工程；打开新图片时若当前工程已有图片，会自动新建标签。
- 关闭标签时若工程未保存，会提示保存。
### 3. 撤销 / 重做
- **撤销 Ctrl+Z、重做 Ctrl+Y**：覆盖画面模式、抖动、强度、张数、支撑方块、方块勾选、预处理、裁剪选区等全部参数操作。
- 像素级纹理编辑的结果在「重新生成」时还原；编辑中点「放弃修改」也可还原。
### 4. 会话恢复
- 正常退出或崩溃后，下次启动自动恢复上次打开的全部工程与标签（可在「工具 → 设置」中关闭）。
### 5. 方案快照与 A/B 对比
- 「工具 → 方案快照与 A/B 对比」：保存当前整套参数为命名快照（带缩略图），可随时恢复。
- 选中两个快照分别「设为 A / 设为 B」后点「并排对比」，左右并排查看两种方案效果与参数。
## 四、画面参数
### 1. 画面模式
- **平面（FLAT）**：所有方块同一高度，地图恒显示标准色（shade 1）。
- **立体（RELIEF）**：严格按 MC 地图物品的明暗机制，由图像内容生成阶梯高度，地图上靠方块高度差呈现明暗；顶层为显示方块，下方为「填充」支撑方块（地图不可见）。
### 2. 抖动算法（9 种）
- **无抖动**：每格取最近色，色块最干净。
- **蓝噪声混合**（默认推荐）：OKLab 双色混合 + 误差扩散 + 边缘保护，照片与渐变表现好。
- **Floyd-Steinberg / Burkes / Atkinson / Stucki / Jarvis / Sierra**：经典误差扩散，风格各异。
- **有序抖动**：规则 Bayer 点阵，复古感强。
- **抖动强度（0~100%）**：控制误差扩散 / 抖动幅度；0% 等同无抖动，100% 为完整算法。
### 3. 尺寸（地图张数）
- 每张地图为 **128×128** 格；宽/高张数 1~8。输出严格按张数比例，原图会拉伸填满，比例不一致时建议先用「裁剪」适配。
### 4. 填充方块（仅立体）
- 石头 / 圆石 / 泥土 / 深板岩 / 安山岩 / **同色方块**（每列用与顶层相同的方块做支撑，最省料且不会透出异色）。
## 五、图像预处理（Ctrl+P）
量化（缩放到目标格数）之前对图像做调整，默认关闭、不改变原图：
- **亮度 / 对比度 / 伽马**：伽马 < 100 提亮暗部、> 100 压暗。
- **R / G / B 通道增益**：独立调整三通道。
- **饱和度 / 去色**：饱和度 0 等同灰度；去色直接转灰度。
- **色调分离**：把颜色压缩为 2~32 个色阶，适合做海报化、卡通化效果。
- **背景处理**：透明 PNG 可铺底色——「抖动」直接铺所选颜色再量化；「平滑」铺最接近的可选方块纯色。
所有滑块拖动时实时刷新预览；「取消」还原打开前状态，「完成」保留。
## 六、裁剪与选区（ROI，Ctrl+J）
- 在原图上**拖拽矩形**只转换局部区域；也可用 X/Y/宽/高百分比精确输入。
- 「适配张数比例」自动把选区调整为与目标地图张数相同的宽高比，避免拉伸。
- 「清除选区」恢复整图转换。
## 七、像素级纹理编辑（Ctrl+Shift+E）
- 生成后逐格涂抹顶层方块：左侧选择笔刷方块（来自当前勾选的方块），支持 1/3/5 笔刷、右键在画面上**取色**。
- 平面模式支持**擦除**（立体模式仅支持改色）。
- 「放弃修改」还原本次编辑；任何时候重新「生成预览」都会按参数重算。
## 八、方块库（Ctrl+B）
### 1. 浏览与搜索
- 按类别分区（羊毛 / 混凝土 / 陶瓦 / 带釉陶瓦 / 染色玻璃 / 自然 / 矿物 / 特殊），每张卡片为真实 16×16 纹理 + 中文名，点卡片任意位置勾选。
- 搜索框支持中文名、英文 ID；双击 Shift 全局唤起并聚焦搜索。
### 2. 标签过滤
- 透明、发光、需合成、矿物资源、下界、末地、创造专属、液体；多个标签为「且」关系。
### 3. 预设
- 内置：默认（羊毛+混凝土）、生存易得、建筑常用、仅自然方块。
- 「存为预设」把当前勾选保存为 JSON；「管理」可删除 / 导入 / 导出，方便在团队间分享（文件位于用户目录 presets/）。
### 4. 自定义方块
- 「+ 自定义方块」：填写方块 ID（如 `mymod:ruby_block`）、显示名、地图颜色 RGB。
- 自定义方块写入 `custom-blocks.json`；也可把多个定义放入插件目录 `plugins/blocks/*.json` 批量加载。
- 注意：自定义方块只影响生成结果与导出，游戏中需要同名方块（模组 / 资源包）真实存在。
## 九、导出体系
工具栏「输出」下拉选择格式，点「导出」。导出前自动质量校验：错误阻断、警告需确认。
- **.litematic**：Litematica 投影模组格式，游戏内一键粘贴（最常用）。
- **.schem**：Sponge schematic，WorldEdit 7+ / FAWE 使用。
- **.schematic**：经典 MCEdit 格式，兼容旧工具链。
- **.nbt**：原版结构方块文件，用结构方块直接加载。
- **.mcfunction**：setblock 命令序列，函数中按相对坐标逐格放置。
- **数据包 .zip**：含 pack.mcmeta 与 `mcpixel:build` 函数，解压进存档 datapacks 目录，进游戏执行 `/function mcpixel:build` 自动建造。
- **物料清单 .csv**：每种方块的需求量与合计（UTF-8 BOM，Excel 直接打开不乱码），供采购与团队分工；也可在「工具 → 物料清单」中查看表格、复制。
- **预览图 .png**：导出 4 倍放大的地图配色预览图。
### 批量处理（工具 → 批量处理）
- 选择图片文件夹与输出文件夹、勾选若干格式，按**当前工程的参数**（方块选择 / 预处理 / 张数 / 抖动）批量转换整个文件夹，带进度与日志。
## 十、质量警告中心（🔔）
铃铛出现红色数字时，表示当前工程存在需要注意的问题，点击查看详情：
- 色域覆盖不足：超过 15% 的像素与最近方块色差过大（ΔE>12），建议调整预处理或增加方块种类；可在预览中切换「色域预警」视图，红色越不透明越难复现。
- 使用了创造专属 / 难以生存获取的方块。
- 使用了自定义方块（需要模组 / 资源包）。
- 尺寸过大（超过 4×4 地图，约 26 万格），工作量提醒。
- 未选方块、未生成等阻断性错误。
## 十一、视图、布局、主题、语言
- **四种预览**：方块纹理俯视、地图配色俯视（游戏内地图实际效果）、可交互立体模型（左键旋转 / 右键平移 / 滚轮缩放 / 双击复位）、色域预警。
- **布局**（视图菜单或设置）：完整双栏 / 仅预览大图 / 仅原图。
- **主题**：深色（默认）/ 浅色 / 高对比度（无障碍），切换后界面自动重建。
- **语言**：中文 / English。
## 十二、命令行（CLI / 无头模式）
不打开界面，适合服务器流水线与脚本批处理：
```
java -jar main.jar --cli \
--input cat.png --output out.litematic \
--mode flat --dither BLUE_NOISE --strength 80 \
--maps 2x2 --blocks survival --support stone
```
参数：
- `--input/-i` 输入图片；`--output/-o` 输出文件（格式按扩展名推断，也可用 `--format` 指定）。
- `--mode flat|relief`；`--dither` 算法名（NONE/BLUE_NOISE/FLOYD_STEINBERG/BURKES/ATKINSON/STUCKI/JARVIS/SIERRA/ORDERED）。
- `--strength 0~100`；`--maps 2x2` 或 `--maps-w/--maps-h`。
- `--blocks default|survival|building|natural|all`，也可传逗号分隔的 blockId 列表或预设 JSON 文件。
- `--support stone|cobblestone|dirt|deepslate|andesite|same`。
- `--format litematic|schem|schematic|nbt|mcfunction|datapack|csv|png`。
- `--help` 查看全部参数。退出码：0 成功、1 转换失败、2 参数错误。
## 十三、用户数据目录
所有用户数据与程序本体分离，位于 **`~/.mc-pixel-art/`**（可用 `-Dmcart.home=目录` 覆盖）：
- `config.properties`：主题、语言、布局、最近文件、会话恢复开关。
- `palette.properties`：标题栏文档色块主题色。
- `custom-blocks.json`：自定义方块。
- `presets/*.json`：用户方块预设。
- `plugins/blocks/*.json`、`plugins/presets/*.json`：插件式方块与预设扩展。
- `projects/session/`：崩溃 / 退出时的会话自动保存。
- `logs/`：运行日志与崩溃报告（崩溃时弹窗提示日志位置，方便反馈）。
插件方块 JSON 示例：
```
{ "blocks": [
{ "id": "mymod:ruby_block", "name": "红宝石块", "r": 220, "g": 40, "b": 90 }
] }
```
## 十四、常见问题
- **导出后进游戏颜色不对？** 请确认游戏版本与方块一致；立体地图画的明暗来自方块高度差，地图物品必须对准方向查看（地图上方朝北）。
- **想要更接近原图的颜色？** 增加方块种类（陶瓦、带釉陶瓦、自然方块）、尝试蓝噪声抖动、在预处理中微调对比度与伽马，并用「色域预警」查看难复现区域。
- **立体模式很费方块？** 填充方块选「同色方块」或便宜方块；减小高度张数；平面模式最省料。
- **CSV 打开乱码？** 已内置 UTF-8 BOM，用 Excel 直接打开即可；若仍异常请在 Excel「数据 → 自文本」中选 UTF-8。
- **透明图片背景发黑？** 在预处理中把背景设为「抖动」或「平滑」并选择底色。
## 十五、快捷键一览
- Ctrl+N 新建工程；Ctrl+O 打开图片；Ctrl+Shift+O 打开工程；Ctrl+S 保存工程；Ctrl+Shift+S 另存；Ctrl+E 导出。
- Ctrl+Z / Ctrl+Y 撤销 / 重做。
- Ctrl+R 生成预览；Ctrl+B 方块库；双击 Shift 搜索方块。
- Ctrl+P 预处理；Ctrl+J 裁剪；Ctrl+Shift+E 像素编辑。
- Alt+\\ 切换紧凑 / 主菜单；F1 打开手册。
[/MD]
