[其他工具] 物集西游地图编辑器2.0

# 物集地图编辑器 – 详细使用说明

**作者：野马**
**版本：2.0**

—

## 目录

1. [工具简介](#工具简介)
2. [界面布局](#界面布局)
3. [顶部工具栏](#顶部工具栏)
4. [右侧控制面板](#右侧控制面板)
5. [基本操作流程](#基本操作流程)
6. [高级功能](#高级功能)
7. [快捷键说明](#快捷键说明)
8. [注意事项](#注意事项)

—

## 工具简介

物集地图编辑器是一个用于在地图文件上添加装饰性覆盖层的可视化编辑工具。它允许您：

– 在地图上添加图片元素（PNG/JPG）
– 精确控制元素的位置、大小、透明度
– 使用分组管理多个元素
– 支持模板导入/导出，批量应用
– 自动保存为自包含的 `.map` 文件

### 文件格式

– **输入文件**：`.map` 地图文件（位于 `resource/map/` 目录）
– **输出文件**：
– `.overlay` 文件：覆盖层配置文件
– `.map` 文件：自包含的嵌入包（包含所有图片资源）

—

## 界面布局

编辑器界面分为三个主要区域：

“`
┌─────────────────────────────────────────────────────────────┐
│ 顶部工具栏（文件操作、缩放、模板等） │
├─────────────────────────────────────────────────────────────┤
│ │
│ 地图画布区域 │
│ （显示地图和覆盖层元素） │
│ │
├─────────────────────────────────────────────────────────────┤
│ 右侧控制面板（元素列表、属性编辑、分组管理等） │
└─────────────────────────────────────────────────────────────┘
“`

—

## 顶部工具栏

### 文件操作区

#### 1. **打开地图** 按钮
– **功能**：打开一个 `.map` 地图文件进行编辑
– **操作**：点击后选择 `resource/map/` 目录下的 `.map` 文件
– **说明**：打开后会自动加载已存在的 `.overlay` 文件（如果有）

#### 2. **添加图片** 按钮
– **功能**：向当前地图添加单个图片元素
– **操作**：
1. 点击按钮
2. 选择 PNG 或 JPG 图片文件
3. 图片会自动复制到地图目录的 `overlays/` 子目录
4. 元素会出现在画布中心位置
– **提示**：建议使用 PNG 格式（支持透明通道）

#### 3. **批量导入** 按钮
– **功能**：一次性导入多个图片文件
– **操作**：
1. 点击按钮
2. 在文件选择对话框中按住 Ctrl 或 Shift 多选图片
3. 所有图片会按顺序排列，每个元素间距 20 像素
– **用途**：适合批量添加装饰元素

#### 4. **删除元素** 按钮
– **功能**：删除当前选中的元素
– **操作**：先选中元素（在画布上点击或从右侧列表选择），然后点击此按钮
– **快捷键**：`Delete` 键

#### 5. **适配屏幕** 按钮
– **功能**：重置视图，将地图缩放到适合窗口大小
– **操作**：点击后视图会重置到左上角，缩放比例设为 1.0

### 缩放控制区

#### 6. **缩放** 输入框
– **功能**：显示和设置当前选中元素的缩放比例
– **操作**：
– 输入数值后按 Enter 应用
– 支持小数（如 0.5、1.5、2.0）
– 范围建议：0.1 – 10.0
– **说明**：只影响选中的元素

#### 7. **放大** 按钮
– **功能**：放大画布视图（不影响元素大小）
– **操作**：点击一次放大 20%
– **快捷键**：`Ctrl + 鼠标滚轮向上`

#### 8. **缩小** 按钮
– **功能**：缩小画布视图
– **操作**：点击一次缩小约 17%
– **快捷键**：`Ctrl + 鼠标滚轮向下`

#### 9. **重置缩放** 按钮
– **功能**：将画布缩放比例重置为 100%
– **操作**：点击后视图缩放恢复为 1.0

### 属性控制区

#### 10. **透明度** 输入框
– **功能**：设置选中元素的透明度
– **操作**：
– 输入 0.0 – 1.0 之间的数值
– 0.0 = 完全透明，1.0 = 完全不透明
– 按 Enter 应用
– **说明**：只影响选中的元素

#### 11. **显示** 复选框
– **功能**：切换选中元素的显示/隐藏状态
– **操作**：勾选显示，取消勾选隐藏
– **说明**：隐藏的元素不会在画布上显示，但数据仍保留

### 网格与吸附区

#### 12. **网格** 复选框
– **功能**：在画布上显示网格线
– **操作**：勾选显示网格，取消勾选隐藏
– **用途**：帮助对齐元素位置

#### 13. **吸附** 复选框
– **功能**：启用/禁用元素位置自动吸附到网格
– **操作**：勾选启用吸附，取消勾选禁用
– **说明**：启用后，拖动元素时会自动对齐到网格点

#### 14. **步长** 输入框
– **功能**：设置网格和吸附的间距
– **操作**：输入像素值（默认 20）
– **说明**：数值越小，网格越密集，吸附越精确

### 保存操作区

#### 15. **保存覆盖层** 按钮
– **功能**：保存当前编辑的覆盖层数据
– **操作**：
1. 点击按钮
2. 系统会自动：
– 验证数据完整性
– 创建备份文件（在 `backups/` 目录）
– 保存 `.overlay` 文件
– 将数据嵌入到 `.map` 文件（自包含模式）
– **说明**：
– 保存前会自动创建备份（保留最近 10 个）
– 备份文件命名格式：`地图名.日期时间.bak`
– 保存失败会显示详细错误信息

#### 16. **写入MAP(自包含)** 按钮 （客户端源码需修改）
– **功能**：将覆盖层数据直接嵌入到 `.map` 文件中
– **操作**：点击后数据会写入 `.map` 文件末尾
– **说明**：
– 自包含模式：所有图片资源都嵌入在 `.map` 文件中
– 客户端可以直接读取，无需额外的 `.overlay` 文件

### 模板功能区

#### 17. **导出模板** 按钮
– **功能**：将当前地图的覆盖层配置导出为模板文件
– **操作**：
1. 点击按钮
2. 选择保存位置和文件名
3. 模板文件包含所有元素的位置、属性、分组信息
– **用途**：
– 备份配置
– 在其他地图上复用相同的布局
– 版本控制

#### 18. **导入模板** 按钮
– **功能**：从模板文件导入覆盖层配置
– **操作**：
1. 点击按钮
2. 选择模板文件
3. 选择导入模式：
– **替换模式**：清空当前内容，完全替换
– **追加模式**：保留当前内容，添加模板内容
– **说明**：导入时会自动加载图片资源（如果路径存在）

#### 19. **批量应用模板** 按钮
– **功能**：将一个模板应用到多个地图文件
– **操作**：
1. 点击按钮
2. 选择模板文件
3. 选择多个目标 `.map` 文件
4. 输入偏移量（dx,dy），格式：`100,50`
5. 系统会批量处理所有文件
– **用途**：批量处理多个地图，统一添加相同的装饰层

### 差异对比区

#### 20. **差异对比** 按钮
– **功能**：对比当前地图与模板文件的差异
– **操作**：
1. 点击按钮
2. 选择要对比的模板文件
3. 系统会显示统计信息：
– **新增**：当前地图有但模板没有的元素（绿色高亮）
– **删除**：模板有但当前地图没有的元素（红色高亮）
– **修改**：位置或属性发生变化的元素（黄色高亮）
– **用途**：检查地图修改情况，确保一致性

#### 21. **关闭对比** 按钮
– **功能**：清除差异对比的高亮显示
– **操作**：点击后画布恢复正常显示

### 其他功能

#### 22. **截图PNG** 按钮
– **功能**：将当前画布内容导出为 PNG 图片
– **操作**：
1. 点击按钮
2. 选择保存位置和文件名
3. 保存当前可见区域的内容
– **用途**：制作预览图、文档配图

—

## 右侧控制面板

### 元素列表区

#### 元素列表
– **功能**：显示所有元素和分组的树形列表
– **显示格式**：
– **分组**：`【组】分组名 (隐藏) (锁) ★`（★表示当前活动分组）
– **元素**：` [zIndex] 元素名 (隐藏) (锁)`
– **操作**：
– **单选**：点击单个元素/分组
– **多选**：按住 Ctrl 点击多个元素
– **框选**：按住 Shift 点击范围
– **说明**：
– 列表按 zIndex（绘制顺序）排序
– 选中的元素会在画布上用红色边框高亮

### 元素属性编辑区

#### 23. **名称** 输入框
– **功能**：设置选中元素的名称
– **操作**：输入名称后按 Enter 应用
– **说明**：名称用于标识元素，不影响显示

#### 24. **上移** 按钮
– **功能**：将选中元素的 zIndex 增加 1（向上移动一层）
– **操作**：点击后元素会显示在更上层
– **快捷键**：`Page Up`

#### 25. **下移** 按钮
– **功能**：将选中元素的 zIndex 减少 1（向下移动一层）
– **操作**：点击后元素会显示在更下层
– **快捷键**：`Page Down`

#### 26. **置顶** 按钮
– **功能**：将选中元素移到最上层
– **操作**：点击后元素的 zIndex 设为最大值+1
– **快捷键**：`Home`

#### 27. **置底** 按钮
– **功能**：将选中元素移到最下层
– **操作**：点击后元素的 zIndex 设为 0
– **快捷键**：`End`

#### 28. **锁定** 复选框
– **功能**：锁定/解锁选中元素
– **操作**：勾选锁定，取消勾选解锁
– **说明**：
– 锁定的元素无法被拖动、删除、修改
– 锁定的元素在列表中显示 `(锁)` 标记
– 分组锁定会影响组内所有元素

### 分组管理区

#### 29. **分组** 下拉框
– **功能**：显示所有分组，选择当前活动分组
– **显示格式**：
– 根分组：`分组名`
– 子分组：` └ 子分组名`（缩进表示层级）
– **操作**：
– 选择分组后，新添加的元素会自动分配到该分组
– 分组按层级排序显示

#### 30. **指派到分组** 按钮
– **功能**：将选中的元素移动到指定分组
– **操作**：
1. 选中元素
2. 在下拉框中选择目标分组
3. 点击按钮
– **说明**：元素会立即移动到新分组

#### 31. **新建分组** 按钮
– **功能**：创建一个新的分组
– **操作**：
1. 点击按钮
2. 输入分组名称
3. 新分组会成为当前活动分组
– **说明**：支持嵌套分组（通过设置 parentId）

#### 32. **重命名分组** 按钮
– **功能**：重命名选中的分组
– **操作**：
1. 在元素列表中选中分组
2. 点击按钮
3. 输入新名称
– **说明**：可以重命名任何分组（包括默认分组）

#### 33. **删除分组** 按钮
– **功能**：删除选中的分组
– **操作**：
1. 在元素列表中选中分组
2. 点击按钮
3. 确认删除
– **说明**：
– 删除分组后，组内元素会移动到默认分组
– 至少保留一个分组（无法删除最后一个）

#### 34. **显示/隐藏分组** 按钮
– **功能**：切换分组的显示/隐藏状态
– **操作**：点击后切换选中分组的可见性
– **说明**：
– 隐藏分组时，组内所有元素也会隐藏
– 隐藏的元素在列表中显示 `(隐藏)` 标记

#### 35. **锁定/解锁分组** 按钮
– **功能**：切换分组的锁定状态
– **操作**：点击后切换选中分组的锁定状态
– **说明**：
– 锁定分组时，组内所有元素也会被锁定
– 锁定的元素无法编辑

#### 36. **折叠/展开分组** 按钮
– **功能**：在列表中折叠/展开分组
– **操作**：点击后切换分组的折叠状态
– **说明**：折叠后，组内元素在列表中不显示（但仍在画布上显示）

### 位置控制区

#### 37. **X** 输入框
– **功能**：显示和设置选中元素的 X 坐标
– **操作**：
– 输入坐标值（像素）
– 点击”应用坐标”按钮应用
– 支持批量设置：选中多个元素时，设置的是它们的边界框位置

#### 38. **Y** 输入框
– **功能**：显示和设置选中元素的 Y 坐标
– **操作**：同 X 坐标

#### 39. **应用坐标** 按钮
– **功能**：将输入的坐标应用到选中元素
– **操作**：
1. 在 X、Y 输入框中输入坐标
2. 点击按钮
3. 如果只输入 X 或 Y，另一个坐标保持不变
– **说明**：多选时，所有元素会相对移动

#### 40. **定位选中** 按钮
– **功能**：将视图移动到选中元素的位置
– **操作**：点击后视图会自动居中显示选中的元素
– **用途**：快速定位到特定元素

### 对齐工具区

#### 41. **左对齐** 按钮
– **功能**：将所有选中元素对齐到最左边元素的左边缘
– **操作**：选中多个元素后点击按钮

#### 42. **水平中心** 按钮
– **功能**：将所有选中元素在水平方向上居中对齐
– **操作**：选中多个元素后点击按钮

#### 43. **右对齐** 按钮
– **功能**：将所有选中元素对齐到最右边元素的右边缘
– **操作**：选中多个元素后点击按钮

#### 44. **顶对齐** 按钮
– **功能**：将所有选中元素对齐到最上边元素的上边缘
– **操作**：选中多个元素后点击按钮

#### 45. **垂直中心** 按钮
– **功能**：将所有选中元素在垂直方向上居中对齐
– **操作**：选中多个元素后点击按钮

#### 46. **底对齐** 按钮
– **功能**：将所有选中元素对齐到最下边元素的下边缘
– **操作**：选中多个元素后点击按钮

### 其他设置区

#### 47. **显示边界提示** 复选框
– **功能**：显示选中元素是否超出视图边界的提示
– **操作**：勾选后，如果选中元素超出视图，会在边缘显示黄色箭头
– **用途**：帮助定位不在视野内的元素

### 资源库面板

#### 48. **显示资源库** 复选框
– **功能**：显示/隐藏资源库面板
– **操作**：勾选后显示资源列表

#### 49. **资源列表**
– **功能**：显示所有已使用的图片资源路径
– **操作**：
– 点击资源项会选中所有使用该资源的元素
– 自动聚焦到这些元素的位置
– **说明**：资源按路径排序显示

#### 50. **刷新资源** 按钮
– **功能**：刷新资源列表
– **操作**：点击后重新扫描所有元素，更新资源列表
– **说明**：添加或删除元素后会自动刷新

#### 51. **移除资源** 按钮
– **功能**：移除选中的资源及其所有使用该资源的元素
– **操作**：
1. 在资源列表中选中资源
2. 点击按钮
3. 确认删除
– **说明**：会删除所有使用该资源的元素，操作不可撤销

—

## 基本操作流程

### 创建新的覆盖层

1. **打开地图**
– 点击”打开地图”按钮
– 选择 `resource/map/` 目录下的 `.map` 文件

2. **添加元素**
– 点击”添加图片”或”批量导入”
– 选择图片文件
– 元素会出现在画布上

3. **调整元素**
– **移动**：直接拖动元素
– **缩放**：在”缩放”输入框中输入数值
– **透明度**：在”透明度”输入框中输入 0.0-1.0
– **位置**：在 X、Y 输入框中输入坐标

4. **管理元素**
– **分组**：创建分组，将元素分配到分组
– **排序**：使用”上移/下移/置顶/置底”调整显示顺序
– **锁定**：锁定不需要修改的元素

5. **保存**
– 点击”保存覆盖层”按钮
– 系统会自动创建备份并保存

### 编辑现有覆盖层

1. **打开地图**（会自动加载 `.overlay` 文件）
2. **选择元素**（在画布上点击或从列表选择）
3. **修改属性**（位置、大小、透明度等）
4. **保存更改**

### 使用模板

1. **导出模板**
– 编辑好一个地图的覆盖层
– 点击”导出模板”
– 保存模板文件

2. **应用模板**
– 打开另一个地图
– 点击”导入模板”
– 选择模板文件
– 选择导入模式（替换/追加）

3. **批量应用**
– 点击”批量应用模板”
– 选择模板文件
– 选择多个目标地图
– 输入偏移量（可选）

—

## 高级功能

### 多选操作

– **Ctrl + 点击**：添加/移除单个元素到选择
– **框选**：按住 Ctrl 拖动鼠标框选多个元素
– **列表多选**：在元素列表中按住 Ctrl 点击多个项

多选后可以：
– 批量修改属性（缩放、透明度、显示状态）
– 批量对齐
– 批量移动
– 批量删除

### 分组嵌套

– 支持创建嵌套分组（子分组）
– 在分组下拉框中，子分组显示为 ` └ 子分组名`
– 分组可以独立控制显示/隐藏、锁定状态

### 撤销/重做

– **撤销**：`Ctrl + Z`
– **重做**：`Ctrl + Y`
– 支持最多 100 步历史记录

### 复制/粘贴

– **复制**：`Ctrl + C`（复制选中的元素）
– **粘贴**：`Ctrl + V`（粘贴到当前位置，偏移 20 像素）
– 粘贴的元素会保持所有属性（位置、大小、透明度等）

### 键盘微调

– **方向键**：移动选中元素 1 像素
– **Shift + 方向键**：移动选中元素 10 像素（快速移动）

### 差异对比

1. 编辑地图后，点击”差异对比”
2. 选择原始模板文件
3. 查看差异统计：
– 新增的元素（绿色）
– 删除的元素（红色）
– 修改的元素（黄色）
4. 点击”关闭对比”清除高亮

### 自动备份

– 每次保存前会自动创建备份
– 备份保存在地图目录的 `backups/` 子目录
– 自动保留最近 10 个备份
– 备份文件命名：`地图名.日期时间.bak`

### 数据验证

保存时会自动验证：
– 分组 ID 唯一性
– 元素的分组引用有效性
– 自动修复无效引用

—

## 快捷键说明

### 文件操作
– 无（使用按钮操作）

### 编辑操作
– `Ctrl + Z`：撤销
– `Ctrl + Y`：重做
– `Ctrl + C`：复制选中元素
– `Ctrl + V`：粘贴元素
– `Delete`：删除选中元素

### 视图操作
– `Ctrl + 鼠标滚轮向上`：放大视图
– `Ctrl + 鼠标滚轮向下`：缩小视图
– 鼠标拖动（无元素时）：平移视图
– 鼠标拖动（有元素时）：移动元素

### 元素操作
– `方向键`：微调元素位置（1 像素）
– `Shift + 方向键`：快速移动元素（10 像素）
– `Page Up`：元素上移一层
– `Page Down`：元素下移一层
– `Home`：元素置顶
– `End`：元素置底

### 选择操作
– `Ctrl + 点击`：多选/取消选择
– `Ctrl + 拖动`：框选多个元素

—

## 注意事项

### 文件管理

1. **图片资源位置**
– 添加的图片会自动复制到 `地图目录/overlays/` 子目录
– 不要手动移动或删除这些图片文件
– 使用相对路径引用，确保 `.overlay` 文件与图片在同一目录结构下

2. **备份文件**
– 备份文件保存在 `地图目录/backups/` 子目录
– 定期清理旧备份以节省空间
– 备份文件可以手动恢复（重命名为 `.overlay`）

3. **自包含模式**
– 使用”写入MAP(自包含)”后，所有图片资源都嵌入在 `.map` 文件中
– 文件会变大，但便于分发
– 客户端可以直接读取，无需额外的 `.overlay` 文件

### 性能优化

1. **图片大小**
– 建议图片尺寸不超过 1024×1024 像素
– 使用 PNG 格式时，优化图片以减少文件大小
– 避免使用过大的图片，会影响加载速度

2. **元素数量**
– 建议单个地图的元素数量不超过 100 个
– 过多元素会影响编辑器的响应速度

3. **分组管理**
– 合理使用分组管理元素
– 隐藏不需要编辑的分组以提高性能

### 兼容性

1. **模板版本**
– 模板文件支持版本号（VERSION:2）
– 新版本支持分组嵌套（parentId）
– 旧版本模板仍然可以正常导入

2. **文件格式**
– `.overlay` 文件使用 UTF-8 编码
– 图片路径使用相对路径
– 坐标使用双精度浮点数

### 常见问题

1. **元素不显示**
– 检查元素的”显示”复选框是否勾选
– 检查元素所在分组是否可见
– 检查元素是否在视图范围内（使用”定位选中”）

2. **无法拖动元素**
– 检查元素是否被锁定
– 检查元素所在分组是否被锁定
– 确保元素被正确选中（红色边框）

3. **保存失败**
– 检查文件是否被其他程序占用
– 检查磁盘空间是否充足
– 查看错误提示信息

4. **图片加载失败**
– 检查图片路径是否正确
– 检查图片文件是否存在
– 检查图片格式是否支持（PNG/JPG）

## 技术支持

如有问题或建议，请联系作者：野马

—

**版本历史**
– v2.0：添加分组嵌套、资源库、差异对比、自动备份等功能
– v1.0：基础编辑功能

—

*最后更新：2025年*11*16