使用说明

这是个什么工具

Live2D Param 是为 Live2D Cubism Editor 提供辅助的建模工具： 读取模型的结构（变形器 / 图层 / 参数）与参数组， 在工具内批量修改颜色、名称或运行配色脚本，确认无误后再一次性写回 Editor。

主要用途是替代 Editor 中逐个修改参数组颜色的重复操作： 先在工具里批量改好，再一次性提交。

功能一览

• 一次读取模型的三份结构：变形器 / 图层 / 参数（只读，不改动模型）；
• 参数组批量改色：预设色、自定义取色（三角调色盘 / 色相圆环 / 吸管）、精确输入 RGB；
• 参数组改名；
• 使用模型的源 PSD 为网格显示缩略图（工具条「选 PSD…」）；
• 撤回 / 前进；
• 保存 / 载入配色方案：以 JSON 保存，可跨模型复用；
• 配色脚本：以声明式 JSON 描述匹配条件与上色方式，内置 3 个官方脚本；
• 记录窗口：完整操作日志，可导出为只读 txt。

系统要求

Cubism 版本限制

• 最低 Editor 5.4 alpha1：本工具依赖的「外部应用程序集成」API 自该版本起提供，更低版本无法连接；
• 必须处于建模模式：参数读取与写入使用的是编辑类 API，仅在建模模式下有效 （否则会出现「读取成功，但一个参数组都没有」；变形器与图层不受此限制）；
• 需打开集成开关：在菜单 [文件] → [外部应用程序的集成设置] 中打开连接开关。

安装

1. 从 GitHub 下载 Live2D-Param-v0.0.1-alpha.1-Setup.exe；
2. 双击运行，点击「安装」；
3. 安装完成后，桌面与开始菜单会出现快捷方式。

安装目录中包含以下三个文件：

安装包体积很小（几百 KB）。主程序与卸载程序均由系统自带的 .NET 编译器编译， 安装过程不会附带安装运行时，也不引入其它依赖。开始菜单与桌面快捷方式使用带版本号的名称 （Live2D Param 0.0.1 alpha.1）。

卸载

两种方式均可：

• 在「设置 → 应用 → 已安装的应用」中找到 Live2D Param 0.0.1 alpha.1，点击卸载；
• 或双击安装目录中的 Uninstall.exe。

卸载会删除与保留哪些内容

卸载只删除本程序自己安装的文件，即上表中的三个文件，以及开始菜单快捷方式与卸载信息。 安装目录中的其它内容一律保留：包括你自己放入的文件，以及程序运行时生成的 配色方案\ 与 脚本\（仅当目录因此变空时，才会一并移除该空目录）。

• 保留 %APPDATA%\Live2D Param：其中保存 Editor 颁发的访问令牌与偏好设置， 因此重装后无需在 Editor 中重新授权。如需彻底清除，请手动删除该目录；
• 保留安装目录中的其它所有内容，包括 配色方案\、脚本\， 以及任何自行放入的文件。

命令行参数

（安装包文件名中包含版本号，例如 Live2D-Param-v0.0.1-alpha.1-Setup.exe，下文简写为 Setup.exe）

Setup.exe                          图形界面安装
Setup.exe /S                       静默安装
Setup.exe /S /NODESKTOP            静默安装，且不建桌面快捷方式
Setup.exe /DIR="D:\somewhere"      指定安装目录
Setup.exe /?                       显示帮助

Uninstall.exe                      图形界面卸载
Uninstall.exe /S                   静默卸载

静默模式无界面，安装过程会记录到 %TEMP%\Live2DParam-Setup.log， 退出码 0 表示安装成功。

一、在 Editor 里准备

1. 启动 Cubism Editor 5.4（或更高版本），打开模型并切换到建模模式；
2. 打开菜单 [文件] → [外部应用程序的集成设置]；
3. 打开连接开关，确认端口号（默认 22033，通常无需修改）。

二、连接

1. 在 Live2D Param 左下角的「Editor 端口」输入框中填写相同端口（默认 22033），点击「连接」；
2. 此时 Editor 会弹出链接许可对话框，请同时勾选 「权限」 与 「编辑」 两项。

三、读取

点击工具条左端的 「读取」。该按钮会一次读回四项内容：变形器、图层、 参数（包含参数组及组内的每一个参数），以及模型 UID。

• 变形器与图层使用普通接口：不需要「编辑」权限， 也不会弹出会锁定 Editor 的编辑对话框；
• 参数使用编辑接口：仅此一步需要「编辑」权限，Editor 中会短暂出现编辑对话框。

因此，若只勾选了「权限」而未勾选「编辑」：变形器与图层仍会正常显示， 仅参数栏为空，记录窗口中会写明原因，界面其余部分不受影响。

「读取」为只读操作：不会修改模型，也不会写入 Editor 的撤销历史。 模型较大时首次读取会稍慢（结构本身可能包含数百个节点）。

四、主窗口说明

工具条从左到右依次为：

读取 ｜ 视图[结构▾] ｜ 选 PSD… ｜ 设为颜色… ｜ 应用更改 ｜ ← →
保存方案… ｜ 载入方案… ｜ 记录 ｜ 脚本

「视图」下拉框决定中间区域显示的内容，两个视图占用同一位置，切换即可更换：

• 结构（默认）：三栏结构树，即变形器 / 图层 / 参数；
• 参数组配色：用于修改颜色与名称的表格。

需要改颜色时，请先将视图切换为「参数组配色」；连接或读取之后默认显示的是结构三栏。 三栏宽度约为 24% / 26% / 50%，参数栏内容最多（参数组及组内参数），因此分配得最宽。

变形器栏

• 显示完整的变形链：变形器 → 变形器 → … → 网格。 网格（ArtMesh）是变形链的最后一环，因此该栏中出现网格节点属于正常情况； 若将其过滤掉，将无法看出某个变形器作用于哪块图形；
• 变形器节点使用类型图标（弯曲变形器与旋转变形器各有专用图标），网格节点显示自身的图层缩略图；
• 节点文字仅显示名称，类型信息在鼠标提示（tooltip）中。

图层栏

• 显示模型的部件树（部件 / 网格），同样为只读；
• 部件为嵌套结构；部件与参数组使用文件夹图标，展开与收起时图标会相应切换；
• 网格缩略图的来源见 五、网格缩略图。

参数栏与滑动条

• 显示参数组及组内的每一个参数（内容最多，因此该栏最宽）；
• 每个参数右侧绘制了一条带滑块的轨道：名称在左，滑块在右；
• 该滑动条仅供显示，不能拖动；滑块位置对应参数的默认值， 不代表模型当前的值。集成接口只提供最小值 / 默认值 / 最大值，不提供当前值， 本工具也尚未实现写入参数值的功能。

状态行

• 底部状态行左侧显示模型的整体情况（三栏各自的节点数量）；
• 右侧显示树中当前选中项的信息。界面中没有独立的属性面板，选中信息统一显示在此处；
• 可显示的字段为 名称 / ID / 类型 / 层级。 倍率、角度、顶点、不透明度、标签颜色不在这些结构接口的返回内容中（需另外调用接口获取）， 因此不会显示，这是接口本身的限制。

三棵树均为只读，打开时默认全部展开。节点较多时可使用滚轮或右侧的细滚动条 （滚动条两端没有箭头，支持滚轮与拖动滑块）。

五、网格缩略图（选 PSD…）

集成接口不返回任何图像。若要让网格显示自身图形，需要指定模型的源 PSD， 由本工具自行读取。

• 点击工具条上的 「选 PSD…」选择一份 PSD。路径会被记住，下次启动自动恢复；
• 点击「读取」时若尚未选择 PSD，会询问一次是否一并选择； 选择与否都不影响后续流程，只是未选择时网格没有缩略图。不会每次读取都询问；
• 选择之后，图层栏与变形器栏中的网格节点都会显示缩略图（两栏共用同一份图，不会重复解析）。

支持的 PSD 格式

不支持的组合一律明确报错，不会静默失败。

网格名与 PSD 图层名的匹配规则

• 先按图层名进行精确匹配（忽略大小写与首尾空格）；
• 未命中时，去掉方向标记后再匹配一次：中刘海2 R → 中刘海2、 中刘海2 R-阴影 → 中刘海2-阴影。 原因是同一个 PSD 图层可能被镜像为左右两份网格（Editor 中为「中刘海2 R」「中刘海2 L」）， 而 PSD 中只有一个「中刘海2」；
• 不进行模糊匹配：名称不匹配时显示错误的图，比不显示更不可取。 通过「去掉方向标记」命中的匹配会单独记录一条日志，便于发现匹配错误；
• 方向标记仅识别两侧均为分隔符（或位于字符串两端）的单字符 R / L / 左 / 右， 因此不会误伤 Right、Left，也不会影响「左手」中的「左」。

六、改颜色 / 改名

请先将工具条上的「视图」切换为 参数组配色： 改色与改名所用的表格位于该视图（默认的「结构」视图为只读的三栏结构树）。

此步骤修改的仅是工具内的列表，尚未写入 Editor。 被修改的行会显示为浅黄色底，右侧「待应用」列标明该行的改动内容。

预设色与自定义取色

• 点击 「改色」列的色块，弹出预设色窗口（3×3 色格）：点击任一色格即可选中；
• 点击该窗口右下角的 「自定义…」，打开三角取色窗口：
  • 中间为三角形调色盘（方向固定），外圈为色相圆环，拖动即可换色；
  • 下方为亮度条（白 → 当前色 → 黑），拖动可调整明暗；
  • 并提供 RGB / HSV 数值框，可直接输入精确数值；
  • 以及吸管：可到屏幕任意位置取色（左键取色，右键取消）。

批量修改

• 先在列表中选中若干行（Ctrl 单独点选，Shift 连续选择），再点击 「设为颜色…」；
• 未选中任何行时，作用于全部参数组；
• 需要一次性处理全部参数组时，也可以直接使用配色脚本。

修改名称

双击 「名称更改」列即可修改。

本版本不支持修改参数组 ID（NewId）：接口支持该操作，但界面未提供， 以避免误操作破坏模型。

撤回与前进

• Ctrl + Z 返回上一步，Ctrl + Y 前进一步；
• Ctrl + Shift + Z 放弃全部更改；
• 工具条上也有「返回上一步 / 前进一步」两个图标按钮。

一次「设为颜色…」、一次「载入方案」、运行一个完整脚本，均各计为一步。

七、应用更改

点击 「应用更改」后，此前累积的所有「待应用」改动才会写入 Editor。

• Editor 会弹出编辑对话框并临时锁定界面，处理过程中请勿操作 Editor；
• 写入完成后，工具会将列表基线更新为新值，浅黄色底恢复正常；
• 中途放弃：在 Editor 的对话框中点击「取消」，所有改动会被整体回滚， 已选择的颜色仍保留在列表中，可直接重试；
• 若中途出错，工具会自动发送一次回滚请求，同样不改动已选择的颜色； 若回滚也失败，记录窗口中会给出明确警告，请在 Editor 中按 Ctrl + Z 检查。

记录窗口

点击工具条上的 「记录」可打开独立窗口，连接、读取、应用与错误信息都会记录在其中。 窗口支持复制、清空与下载为 txt； 下载的文件会被设为只读，避免内容被误改。

反馈问题时，附上该记录最有帮助。

脚本窗口

点击工具条上的 「脚本」打开脚本窗口：

• 左侧为脚本列表，每行右侧带一枚「官方 / 我的」标签；
• 右侧显示所选脚本的说明与规则明细：逐条列出「匹配条件 → 颜色」， 每条附一个小色块，含渐变的规则会绘制渐变预览；
• 选中脚本后点击 「运行」，脚本会按规则将颜色填入列表 （同样只是「待应用」，不会直接写入 Editor）。

官方脚本与自己的脚本

脚本是 JSON 文件。两类脚本都放在同一个「脚本」文件夹中 （位于软件安装目录下，程序运行过一次后即会出现）。

脚本怎么写

脚本是一份声明式 JSON，用于描述「满足什么条件的参数组使用什么颜色」。 它不是可执行代码：本工具仅使用系统自带的 .NET 编译器，无法运行 JS / Python 等脚本语言。 这样设计的好处是，规则写错时最多是「不生效」，不会在本机执行其它内容。

{
  "version": 1,
  "name": "按名字上色",
  "description": "显示在窗口里的一句话说明",
  "rules": [
    { "name": "*眼*", "color": "blue" },
    { "id": "ParamGroup*", "depth": 0, "cycle": ["red", "green", "blue"] },
    { "minDepth": 1, "color": "#8AC1FF" },
    { "name": "*", "gradient": "ask" }
  ]
}

一条规则 = 匹配条件 + 上色方式。

匹配条件

匹配不区分大小写；中文关键词可直接书写，例如 *手* 可同时命中「手臂」与「手指」。

上色方式

• color / cycle / gradient 三选一；
• 规则自上而下匹配，以第一条命中的规则为准；未被任何规则命中的组保持原样；
• 脚本名称默认取文件名（不含扩展名）；若写了 name，以 name 为准。

关于 "gradient": "ask"

选定颜色后，工具会从白依次渐变到该颜色，最后一组正好是所选的颜色； 色带仅取「白 → 本色」的前半段，不会过渡到黑。 选色窗口在选择完成后即关闭，取消则等同于未运行该脚本。

运行脚本会发生什么

• 运行结果只是填入列表并标记为「待应用」（与「载入方案」的路径相同）， 不会直接写入 Editor；确认无误后再点击「应用更改」；
• 作用于全部参数组：脚本是批量规则，不同于「设为颜色…」仅作用于选中行的行为；
• 整个脚本计为一步撤回：使用 Ctrl + Z 可一次性撤销；
• 运行结束后脚本窗口会自动关闭，由窗口中的「运行后关掉窗口」勾选框控制 （默认勾选；取消勾选后可连续运行多个脚本）。该勾选框状态会被记住，下次打开保持一致；
• 脚本无法打开（JSON 格式错误）时，列表中会将其标为红色并显示具体错误，不影响其它脚本；
• 未能运行成功时（尚未读取、无规则命中、或取消了选色），窗口不会关闭，并给出提示说明。

保存与载入

• 调整好颜色后点击 「保存方案」，可将当前配色保存为一份 JSON （默认保存在安装目录的 配色方案\ 中）；
• 之后或更换模型时，点击 「载入方案」读回：颜色会填入列表并标记为「待应用」， 确认后再点击「应用更改」；
• 一份方案记录的是「参数组 → 颜色 / 名称」的对应关系，因此可反复作为模板使用。

跨模型复用

支持。载入时先按参数组 ID 匹配，ID 无法对应时再按名称匹配。

未匹配到的条目会被忽略，界面会提示未匹配的条目数量，便于判断是否需要手动补充。

常见问题

netstat -ano | Select-String "LISTENING" | Select-String ":22033"

已知限制

1. 仅支持 Cubism Editor 5.4 alpha1 及以上，且必须处于建模模式。
2. 仅提供 Windows 版本。核心逻辑与界面无强绑定，但界面使用 WinForms。
3. 预设色的色块按 Editor 取色界面的截图采样绘制：预设色的实际 RGB 由 Editor 内部决定， 接口不返回。写回时仅发送预设的名称，最终颜色仍以 Editor 为准； 仅当 LabelColorType = "Custom" 时，颜色才由 #RRGGBB 精确决定。
4. 应用期间 Editor 会被锁定，这是 Editor 侧的设计（弹出模态编辑对话框），并非本工具造成。
5. 本版本不支持修改参数组 ID（NewId），也不支持修改参数值。
6. 参数部分的读取需要「编辑」权限（变形器与图层不需要）； 仅勾选「权限」时参数栏为空，界面其余部分不受影响。
7. 参数栏的滑动条为只读，显示的是默认值而非模型当前值： 集成接口只提供最小值 / 默认值 / 最大值，不提供当前值。
8. 网格缩略图需要自行指定源 PSD：集成接口不返回任何图像， 本工具也不解析 .cmo3（私有二进制格式）。 PSD 仅支持 8 位的 PSD / PSB，颜色模式仅支持 RGB 与灰度； 16 / 32 位、CMYK / 索引 / Lab 均不支持。
9. 结构树为只读，三栏默认将节点全部展开；模型较大时 （实测某真实模型：变形器 204 个节点、图层 253 个节点）首次读取与展开会稍慢。
10. 令牌以明文保存在 %APPDATA%\Live2D Param\token.txt （与官方 Python 示例的做法一致）。该令牌仅用于连接本机 Editor，但在共享电脑上使用时请注意。
11. 端口可能被其它程序占用：Editor 默认使用 22033，被占用时 Editor 无法监听， 工具也无法连接。将两侧改为同一个新端口即可。

反馈与联系

• 如遇到问题或有任何建议，欢迎在 GitHub 提交 issue，或发送邮件至 abcd_9866@qq.com；
• 请尽量附上截图（尤其是出错时「记录」窗口中的内容），便于排查；
• 本工具目前以自用为主，仍有较多功能尚在计划中。 如你擅长 UI 设计，欢迎参与改进；
• 需要安装体验时，安装包可在 GitHub 下载。