YA的YAMI妙妙小工具

React + Vite Web 工具合集，通过 GitHub Actions 自动部署到 GitHub Pages。所有游戏工程文件都在浏览器本地读取和处理，不上传任何数据。专为 Open Yami RPG Editor（Yami RPG Maker）工程设计。

工具列表：

工具	一句话说明
素材管理器 (beta)	本地像素素材库：拼音搜索 / 标签集合 / 聚类修复 / 查重 / 一键导出
存档台	查看/编辑游戏存档（Save 目录），GUID 自动翻译成中文与图片
角色编辑器	可视化编排角色掉落表、掉落事件与人物属性
地图编辑器	10×10 地图格、通行关系、等级和刷怪池的 Excel/JSON 编辑
挂机验证台	按游戏真实数值模型模拟战斗/成长/收益，定位数值瓶颈
性能分析台	分析 Electron 真机游玩的 DevTools trace 与 Spector.js WebGL capture
脚本转换	老版 Yami JS 插件与指令一键转换为现代规范 TypeScript (TS) 代码

---

技术栈与迁移说明

• 前端：Vite 5 + React 18 + React Router（Hash 路由），零后端、零上传。
• GitHub Pages 部署：.github/workflows/deploy.yml 在 push 到 main 时自动 vite build（base 为 /yami-tools/）并发布 dist/。
• 旧 7 个工具：原本的原生 HTML/JS 工具已整体移入 public/tools/，构建时由 Vite 原样复制进 dist/tools/，功能零改动；后续再逐个移植为 React 组件。
• 素材管理器（新，React）：文件系统授权（File System Access API，记住 D:\YAHZJ\技能素材 授权句柄）→ 全量扫描 → 按「目录+文件名前缀」自动聚类动画组 → 预览/搜索/导出；不支持的浏览器降级 webkitdirectory 临时读取。

---

快速开始（第一次用，3 步）

① 打开工具（任选）

• 线上版：GitHub Pages https://bajibaji.github.io/yami-tools/（推荐，无需安装）
• 本地开发：npm install && npm run dev，浏览器打开 http://localhost:5173/yami-tools/
• 本地预览构建产物：npm run build && npm run preview

② 用 Chrome / Edge 打开（或 Yami 编辑器内置 Chromium）。这些浏览器支持「File System Access API」，可以直接读写工程目录；其他浏览器会自动降级为只读导入模式（能看、能下载修改副本，不能写回）。

③ 选择游戏工程：点「选择工程」，选中游戏工程的根目录（包含 Assets、Data、Save 的那个文件夹，例如 D:\new-game）。

工程位置是多个工具共用的：任何工具选择过的工程都会被记住（浏览器本地保存），其他工具打开时自动加载上次工程，点「加载上次工程」重新授权即可，不需要每个工具都选一遍。

---

构建与部署（开发用）

npm install      # 安装依赖
npm run dev      # 本地开发（http://localhost:5173/yami-tools/）
npm run build    # 构建到 dist/
npm run preview  # 本地预览构建产物

发布（GitHub Pages）

只有打 v*.*.* 版本标签才会触发部署，push 到 main 不部署：

git tag v0.0.0        # 打版本标签（v 开头 + 版本号）
git push origin v0.0.0  # 推送标签即触发 .github/workflows/deploy.yml 构建并发布

• 部署时 VITE_APP_VERSION=${github.ref_name} 自动注入构建，首页版本号显示为标签（如 v0.0.0）。
• 也可以到仓库 Actions 页手动 Run workflow 触发部署。
• 首次需手动配置一次：仓库 Settings → Pages → Source 选择「GitHub Actions」。

---

素材管理器（v1.4.0 · beta）

面向本地像素素材库（如 D:\YAHZJ\技能素材，约 11 万文件）：

• 选择素材库：一次授权目录，IndexedDB 记住句柄，下次自动重连（浏览器偶尔要求重新授权）；库根 .yami-manifest.json 清单可秒级恢复索引，重新索引走增量同步。
  • 素材变动后建议用本机脚本秒级更新清单：node scripts/build-manifest.mjs（7 秒扫完 11 万文件），再刷新页面即恢复最新索引；浏览器内「重新索引」需遍历 10 万+ 文件，通常要几分钟，仅建议偶尔使用。
• 动画自动聚类：按「目录 + 文件名前缀数字」识别单帧序列（如 frame0000.png、Effect (1)1.png）；spritesheet.png + spritesheet.txt 直接读取元数据；*_sheet.png 走 alpha 间隙自动切分；GIF 原生播放；POZAC 包自动关联兄弟 Aseprite/ 源目录并跳过 Preview 封面。
• 搜索：内存索引 11 万条，空格分词多关键词（AND），支持拼音/首字母（搜 huoyan 命中「火焰」）；按类型/尺寸/帧数筛选，名称/帧数/最近查看排序。
• 标签与集合：卡片一键打标签、左侧标签栏点击即筛选；集合可把常用素材收纳成组，批量加入/移出，数据可随 JSON 备份导出导入。
• 聚类修复：聚类不理想时手动纠正——拆分动画（按帧勾选）、合并到同目录动画、重命名、调整帧率、重切精灵表、隐藏卡片；全部修复可撤销（顶部「修复」按钮管理），重新索引后依然生效。
• 查重视图：按「文件名 + 文件大小」全库查重，一键复制重复文件路径。
• 尺寸索引：一次性读取 PNG/GIF 文件头解析像素尺寸（后台并发、可中断、结果持久化），用于按 16/32/48/64/…px 筛选。
• 预览：canvas 像素风放大、fps/缩放/循环可调、逐帧胶片带；GIF 导出结果持久化缓存（同配置不重复编码）。
• 导出：单帧序列 ZIP、Spritesheet（PNG+坐标）、GIF 动图、批量打包 ZIP；用户数据（收藏/标签/集合/修复/预设）一键 JSON 备份与导入。
• 定位：一键复制相对/绝对路径（浏览器安全限制，无法直接打开资源管理器——这是纯网页方案的硬边界，复制后到文件管理器地址栏 Ctrl+L 粘贴即达）。
• 已知限制：P0 不含 .aseprite 源文件预览（仅可下载原工程）；Firefox/Safari 无 File System Access API，降级为一次性目录读取，每次需重新选择。

---

存档台（v0.1.1）

这个工具解决什么问题（用在哪）

游戏存档 Save/saveNN.save 是给引擎读的 JSON，直接打开是一大串没有意义的 GUID 和英文键：

{"playTime":3045,"actors":[{"fileId":"1ab20a44c47972b7","teamId":"2a6ee1684ef7dfa0","attributes":{"level-EX":5}}]}

存档台把这一串翻译成人话：

{"playTime": 3045, "actors": [{"fileId": "@1 通用英雄角色", "teamId": "NPC 队伍", "attributes": {"level-EX": "等级加成(5)"}}]}

典型使用场景：

• 调试存档：玩家报错/进度丢失时，打开存档看角色、背包、变量到底存了什么。
• 改数值：给角色改金币/等级/属性、改变量、改背包——保存前自动备份，改坏了能还原。
• 验证存档格式：检查 version 是否为 2（v2 稀疏格式）、属性是否只存了变化值、meta 截图是否正常。
• 排查坏档：主档损坏时引擎会自动读 .bak；存档台可以单独打开 .bak 对比内容。
• 对照测试：游戏里改了什么 → 存档里对应哪个字段（中文映射一开就看懂）。

怎么用（操作步骤）

1. 主页点「存档台」→ 选工程（或自动加载上次工程）。

2. 左侧是 Save 目录文件列表，按用途分组：

   分组	文件	说明
   进度存档	save00.save、global.save	游戏进度 / 全局设置+共享变量
   元数据	save00.meta	保存时间 + 截图
   旁路数据	save00.json	插件（Excel操作改2）额外写的自定义数据，与引擎存档无关
   备份文件	*.bak	引擎自动保留的上一份存档
   其他文件	zip / vdf 等	与存档无关的杂物

3. 点文件名 → 右侧显示 JSON 树（默认展开第一层，深层点击 ▸ 才展开，大存档也不卡）：

   • 文件信息栏：版本（v2=稀疏格式）、游玩时间、角色数、槽位、修改时间。
   • .meta 文件顶部直接显示截图预览和保存时间；JSON 树里的 data:image 值也内嵌缩略图。

4. 「显示中文/GUID 映射」开关（默认开）：把存档里的键和值注解成游戏内内容，注解是蓝色小标签，不改变 JSON 本身的颜色。覆盖范围：

   存档里的东西	会显示成
   fileId / 技能 / 状态 / 装备 / 物品 / 事件 / 场景 ID	对应资产的中文名（角色「史莱姆」、技能「900 - 攻击」…）
   teamId	队伍名（NPC / 玩家 / 魔物）
   属性键（STR、level-EX…）	属性中文名（力量、等级加成…）
   变量 ID（含 global.save 的共享变量）	变量中文名（夜晚、地下城目标…）
   plugins 里的 GUID	插件名
   portrait / icon	按 clip 裁剪的头像/图标图片
   timestamp / playTime	保存时间 / 游玩时长
   screenshot	截图缩略图

5. 「源码」按钮切换成纯文本视图；搜索框在源码里定位内容（即时计数 n/m、↑↓ 跳转、回车下一个）——5MB 大档也能秒搜。

6. 编辑存档：点「编辑」→ 在文本框中改 JSON（格式化显示）→ 点「保存修改」：

   • 先做语法校验（写错会提示，不会保存）；
   • 弹窗确认（建议先关闭游戏，否则游戏下次存档会覆盖你的修改）；
   • 自动把原文件备份到工程根目录 Lootsmith Backups/<时间戳>/；
   • 以紧凑 JSON 写回（与引擎格式一致，不动引擎自己的 .bak）。

举个实际例子：给玩家改钱

1. 存档台 → 选择工程 → 点 save00.save。
2. 展开 actors，找到玩家角色（fileId 注解会显示中文名）。
3. 展开该角色 → inventory → money，看到当前金币数。
4. 点「编辑」，把 money 改成目标值，点「保存修改」→ 确认 → 自动备份完成。
5. 进游戏读档即可（注意：如果游戏还开着，先关掉再改，或改完不要触发游戏内保存）。

注意事项与限制

• 游戏运行时编辑会被覆盖：游戏进程可能在你修改后保存存档，覆盖工具写回的内容。修改前请关闭游戏，或修改后不要再在游戏里存档。
• 只读导入模式：浏览器不支持直接写文件夹时（Firefox/Safari 等），只能查看和下载修改副本。
• 浏览器模式存档不可见：网页版游戏（IndexedDB 存档）不在工程 Save 目录里，本工具只支持桌面版工程的存档。
• 映射需要工程数据：GUID 翻译依赖工程的 Data/manifest.json、attribute.json、variables.json、teams.json 等文件；资产文件被删或 manifest 未更新时，个别 GUID 会没有注解（属正常）。

---

角色编辑器

可视化编排角色掉落表（两种写入方式）与人物属性，保存前自动备份。

• 掉落编辑：扫描角色/物品/装备，拖拽或点选添加掉落物，支持固定数量/数量范围/掉落几率（小数百分比）、物品价格与掉落总价值、继承事件、事件模式逐条禁用；保存写入 loopList 属性或「掉落物品」角色事件（保留未知指令）。
• 人物属性编辑：本地属性可编辑、继承属性只读可覆盖；支持 number/boolean/string/enum 四种类型；未知属性原样保留。
• 使用步骤：选工程 → 选角色 → 配置掉落 → 保存（自动备份 + 失败回滚）。

地图编辑器

支持导入 Excel / JSON，可视化编辑 10×10 地图格、通行关系、等级区间、刷怪池，一键导出 Yami 标准地图 JSON（地图JSON读取 指令配套格式）。

挂机验证台

读取真实工程的角色/地图/掉落数据，按游戏实际数值模型模拟单关战斗、全图节奏、长期成长与 A/B 数值方案：可调玩家属性与模拟假设、逐关覆盖怪物权重与倍率、固定随机种子重复模拟、10×10 热力图、全图体检、时间线推演、A/B 快照对比。验证参数不会写回游戏工程。

数值模型已对齐游戏源码（怪物每级 +1 线性成长、攻击间隔公式、阈值命中骰子 80 等）；用于快速筛查节奏与数量级，最终以游戏内实测为准。

快速本地化

只扫描游戏里被引用的资产（复刻引擎打包算法），找未本地化的硬编码文本、缺翻译条目、孤儿引用与疑似占位翻译。两种工作流：

• 界面直改：候选文本点「本地化」立即建条目；已本地化/缺翻译/疑似占位直接编辑原文/译文，自动备份写回。
• Excel 流程：导出七 sheet（首表为引擎同算法 open-yami 格式），翻译填好后导入回工程，幂等安全。

富文本标签（<color>、<global>、<ref>、<image>）解析成实际内容显示；语言列由 Data/config.json 驱动，扩展语言无需改工具。

---

性能分析台

只分析打包游戏或 Open Yami 试玩窗口在 Electron 真机环境中产生的报告，不再在网页 iframe 中模拟运行游戏：

• CPU / GC / 长帧：导入 Electron 内置 Chromium DevTools 的 Performance trace JSON；
• WebGL：导入现成开源扩展 Spector.js 的 capture JSON；
• 逐帧定位：粘贴工具页提供的「真机探针」到 Electron DevTools 控制台，游玩后导出 JSON，分析哪段更新器/渲染器/事件最常把帧顶超 16.7ms；
• 分析：主线程长任务、帧间隔 P95、GC 占用、CPU 热点、Draw Call、GL 命令、冗余状态和帧资源内存；
• 回归：保存当前摘要为本机基线，后续报告自动显示差值；
• 安全：报告全程在浏览器本地解析，不上传、不运行游戏、不读写工程。

Spector.js 使用上游原版扩展（MIT），本仓库不维护自研采集插件。详细采集步骤见 public/tools/perf-lab/README.md。

---

脚本转换（v0.1.0）

将老旧的 Yami RPG JS 插件与自定义指令代码一键转换为现代 TypeScript (TS) 规范脚本，专为迁移到新游戏工程设计：

• 自动解析元数据与推导接口属性：解析 /* @plugin */ 注释，自动将 @number、@string、@option、@variable-setter、@actor-getter 等标签转换为标准 TS 接口属性并自动注入类中；
• 自动推断泛型形态：根据类方法与特征自动识别实现 Script<Command>（自定义指令）、Script<Plugin>（全局插件）、Script<Trigger>（触发器脚本）、Script<SceneLight>（光源脚本）、Script<ImageElement>（图像组件）等；
• 运行时 API 现代化升级：将老旧过时的 Event.attributes / Event.triggerActor / Event.casterActor 自动替换为 CurrentEvent.*；
• 智能纠正与去重：自动将 getter 参数的函数调用（如 this.actor()）修复为预求值属性读取（this.actor），并智能规范化老旧 JS 伪类型注释（如 caster //:object）；
• 改动点代码高亮：右侧 TS 代码视图中直接高亮显示自动生成的接口属性、升级的泛型类与修改的 API，直观清晰；
• 批量转换与极速导出：支持选择文件夹批量载入多个 .js 脚本并一键打包下载全部对应的 .ts 文件。

---

安全机制（所有写回工具通用）

• 工程目录句柄保存在浏览器本地（IndexedDB），下次打开自动加载或一键重新授权。
• 所有写回前自动备份到工程根目录 Lootsmith Backups/<时间戳>/：
  • 角色编辑器/快速本地化：备份 + 回读校验 + 失败回滚，顶栏「备份与还原」面板可查看/还原/删除。
  • 存档台：写回前备份原存档文件，不触碰引擎自己的 .bak。
• 备份目录名不会被 Yami 引擎当成游戏资源扫描。
• 不支持 File System Access API 的浏览器自动进入只读导入模式，保存只下载修改副本，绝不覆盖工程文件。

工程自动同步

角色编辑器、地图编辑器、挂机验证台、快速本地化、存档台都会监听工程文件变化：

• 优先 FileSystemObserver（Chrome 133+）即时触发；不支持时回退 5 秒轮询（页面切后台暂停）。
• 角色编辑器有未保存草稿时不自动刷新；快速本地化检测到变化只提示、不打断编辑；存档台在游戏内存档后自动重新读取（编辑模式暂停）。

常见问题（FAQ）

Q：为什么我的存档列表是空的？ 检查选择的文件夹是不是工程根目录（要有 Data 和 Save 子目录）；老工程可能没有 Save 目录（没存过档）。

Q：改了存档，游戏里没变化？ ① 游戏还开着——它的下次保存会覆盖你的修改，先关游戏再改；② 改完没读档——需要重新读档/重启游戏；③ 改坏了 JSON——保存前有语法校验，读档失败时引擎会自动回退 .bak。

Q：为什么有些 GUID 没有翻译成中文？ 翻译数据来自工程自己的文件（manifest/attribute/variables 等）。资产文件被删、或者 manifest 还没更新（编辑器没重扫）时就会缺；不影响查看。

Q：存档里 save00.json 是什么？ 插件（Excel操作改2「保存json到存档」）写的旁路数据，与引擎存档（.save/.meta）无关。

Q：怎么让新电脑/别人也能用这些工具？ 工具本体在浏览器跑，把仓库 clone 下来开个静态服务器即可；工程位置只存在你本机浏览器里，别人需要自己选一次工程。

Q：工具会修改我的游戏文件吗？ 只有你主动点「保存」才会写回，且写回前一定备份。查看、映射、搜索都是纯读取。