1. 安装与首次运行
安装版：双击 玖源社UPK编辑工具-Setup-0.2.15.exe，按向导选择安装位置即可，会自动创建开始菜单和桌面快捷方式。
免安装版：双击 玖源社UPK编辑工具-Portable-0.2.15.exe 直接运行，可放在 U 盘或任意目录，不写注册表。
首次打开是空状态：左侧是文件树（文件夹 / 当前打开 / 历史记录），中间是舞台区，右侧是缩略图列表。此时还没有加载任何包。
2. 打开 UPK
三种方式任选：
- 把
.upk文件拖进窗口任意位置。 - 左侧图标栏点「文件 → 打开文件」选择包。
- 点「文件夹」标签，选择一个目录，工具会列出其中的 .upk，点任意一项即加载。
打开成功后会看到标题栏显示包名与统计信息，缩略图区域开始分批出图。打开过的包会进入「历史记录」，下次一键点开。
加密包
遇到加密包会弹出密码输入框，输入正确密码即可正常解析（见 第 11 节）。
3. 界面速览
整体是「左轨 + 双行工具栏 + 三栏内容 + 底栏」的结构：
| 区域 | 内容与作用 |
|---|---|
| 左轨 | 文件 / 文件夹两个标签页，管理打开的文件与目录列表 |
| 工具栏第一行 | 每页数量、导出 PNG、导出图集、单张导入、批量导入、文件夹打包、透明底、目标尺寸 |
| 工具栏第二行 | 按名称过滤、后台预载全部、多选自动播放与播放速度、跳过空图片、已选数量、更多菜单 |
| 中间舞台 | 当前选中纹理的大图预览（含 mip 信息、尺寸、格式、缩放比例） |
| 右侧缩略图栏 | 网格浏览，单击选中、Ctrl / Shift 多选，右键出菜单 |
| 底栏 | 坐标、尺寸、缩放、选中项、格式与包内相对路径 |
4. 浏览与筛选
分页与过滤
- 每页：100 / 500 / 1000 张，包很大时建议先用较小的每页 + 过滤。
- 按名称过滤：输入即筛，支持部分匹配，不区分大小写。清空后回到全量。
- 后台预载全部：开启后提前在后台解码缩略图，滚动更顺；机器较弱或包极大时可关闭以省内存。
显示辅助
- 透明底：切换预览背景，检查带 alpha 的贴图边缘是否干净。
- 目标尺寸：32 / 64 / 128 / 原图，只影响缩略图展示，不改动数据。
- 跳过空图片：播放动画时自动跳过全透明帧。
5. 导出纹理
先选中目标纹理（可多选），再用任一方式导出：
- 工具栏「导出PNG」：按当前选中项导出 PNG。
- 工具栏「导出图集」：把选中纹理拼成一张图集，方便整批比对。
- 右键「单张导出 / 批量导出」：可选择导出格式（PNG / DDS / TGA）。
导出目录会记住上次选择的位置；文件名默认取纹理在包内的名称，重名会自动加序号。
6. 编辑与替换
推荐流程：导出原图 → 同尺寸修改 → 单张导入验证 → 批量。
尺寸与格式规则
- 替换图的宽高必须与原纹理完全一致，否则会被校验拦下（不写盘、不改包）。
- 工具会按原纹理的格式（DXT1 / DXT5 / RGBA8 / BGRA8 / P8）重新编码，并重建整条 mip 链。
- 带 P8 调色板的纹理，导入时会按原调色板做颜色量化。
替换模式（右键「单张导入」）
当前版本支持「当前替换」：用导入的 PNG 覆盖当前选中纹理的数据，并重建整条 mip 链。
「尾部添加」「当前插入」需要在包的导出表里写入全新对象，改动面大、有损坏包风险，目前尚未开放（点击会提示「暂未支持」），后续版本补齐。
备份与回退
本次会话中首次替换时会自动生成 原文件名.bak.upk。需要回退时：关闭该包 → 把 .bak.upk 改回原文件名（覆盖已改的），重新打开即可。（原文件一旦被改写，工具内无法自动撤销，所以别急着删备份。）
7. 批量导入
工具栏「批量导入」或右键「批量导入」，选择一个图片目录，工具会：
- 按文件名（不含扩展名）匹配包内同名纹理；
- 逐张校验尺寸，尺寸一致的替换，不一致的跳过并计入报告；
- 结束后汇总「成功 / 未匹配 / 尺寸不符 / 失败」四类数量。
命名技巧：先用「导出PNG」导出目标纹理，直接在导出目录里改图，再对这个目录做批量导入，文件名天然对得上。
8. 文件夹打包
这个功能不需要先打开任何 UPK：点工具栏「文件夹打包」→ 选择文件夹 → 直接生成一个新的 .upk 文件。
处理规则
- 递归扫描所选目录及子目录下的所有 PNG；
- 对象名取相对路径，子目录用下划线连接（如
ui/btn/ok.png→ui_btn_ok），重名自动加序号； - 含半透明像素用 DXT5，全不透明用 DXT1；
- 尺寸不是 4 的倍数时自动补边到 4 的倍数（复制边缘像素，不留黑边）；
- 自动生成 mip 链，输出到被选文件夹的同级目录、同名 .upk；若已存在则依次命名
xxx(2).upk，绝不覆盖。
9. 动画预览与播放速度
- 勾选「多选自动播放动画」后，中间大图区会按选中顺序循环播放帧序列。
- 「播放速度」是每帧毫秒数：直接在输入框里键入数字即时生效，也可以点两侧 ◀ ▶ 按 10 ms 步进微调，可调范围 10–2000 ms。
- 「跳过空图片」可跳过低分辨率空帧，让循环更干净。
- 右键「选中播放动画」以当前选中集立即播放。
10. 右键菜单速查
菜单里部分是当前可用功能，部分是为后续版本预留的入口（点击会明确提示「暂未支持」，不会静默失败、也不会改动你的包）。
| 菜单项 | 状态 | 说明 |
|---|---|---|
| 单张导出 | 可用 | 导出当前选中纹理（PNG / DDS / TGA） |
| 单张导入 → 当前替换 | 可用 | 用选定的 PNG 覆盖当前纹理并重建 mip |
| 批量导出 | 可用 | 导出全部选中纹理，可选格式与目录 |
| 批量导入 | 可用 | 按文件名匹配批量替换同名纹理，逐张校验尺寸 |
| 选中播放动画 | 可用 | 以当前选中集为帧序列循环播放 |
| 插入空图片 | 规划中 | 需向包内写入全新导出对象，暂未开放 |
| 单张导入 → 尾部添加 / 当前插入 | 规划中 | 需重写导出表并重排对象索引，暂未开放 |
| 单张删除 / 批量删除 | 规划中 | 删除导出对象需重写导出表，暂未开放 |
| 单张优化 / 批量优化 | 规划中 | 重新编码会改变压缩块布局，暂未开放 |
| 批量调整坐标 | 规划中 | 需修改导出对象的坐标数据，暂未开放 |
| 生成GIF动画 | 规划中 | 需内置 GIF 编码器，暂未开放 |
11. 加密包
部分资源包带有密码保护。相关操作都在「更多 → 设置密码」中：
- 打开加密包：加载时输入密码，之后正常浏览与替换。
- 给明文包加密码：输入新密码即可。
- 加密包转明文：新密码留空，输入原密码后导出为明文 UPK。
密码只在本地用于加解密，不会上传到任何服务器。
12. 错误码说明
| 错误码 | 含义 | 处理建议 |
|---|---|---|
E2001 | 魔数不匹配 / 未匹配任何格式 | 确认文件确实是 UPK；可能是其它引擎封装或二次加密 |
E2003 | 数据越界（偏移或大小超出文件） | 包可能被截断或已损坏，换一份原始文件 |
E3001 | 不支持的纹理格式 | DXT3 等暂未支持，可导出查看但不能回灌 |
E3002 | 解码失败 | 图片文件损坏，或目录内没有可用 PNG |
E4001 | 尺寸不一致 | 把图改成与原纹理完全相同的宽高 |
E4003 | mip 层数不匹配 | 多为异常包，改用单张导入逐张处理 |
E4004 | 校验未通过，已阻止写入 | 按提示修正尺寸或换用受支持的纹理 |
13. 性能与建议
- 大包（数千张纹理）建议开启「后台预载全部」，并把「每页」设为 100 配合名称过滤定位。
- 批量替换前先单张验证一次，确认游戏内显示正常再整批处理。
- 导出与替换的中间文件建议单独放一个工作目录，方便回滚。
- 同时打开多个大包会显著增加内存占用，处理完及时「关闭文件」。