绘动 EDO / 使用说明

绘动 edo API

本文对应 API v2，面向歌映直播、礼物互动和其他本机插件。

1. 快速选择

端口默认是 48991，服务默认只用于本机回环地址。原生控制台的“设置 → API”可启停网络接口，输入 1..65535 的整数端口后点击“应用”立即生效并保存；关闭后仍可在原生控制台重新启用。切换端口会断开已有连接，调用方须使用新地址重新连接。端口占用或保存失败会提示错误并恢复原设置。

配置保存在 config/app.json 的 api.enabled 和 api.port；旧配置缺少 enabled 时默认启用。app.getState 的 api 同时提供 enabled（配置）、running（实际监听状态）和 error（启动失败原因）。开关控制 HTTP/WebSocket 服务，不关闭只读共享内存。监听设置只允许通过原生控制台的进程内调用修改；WebSocket 不接受 app.updateApi。

推荐做法：高频状态从共享内存读取，可靠控制使用 /ws。不要用 WebSocket 每帧轮询全部参数。

2. 原生 WebSocket 基础格式

请求：

{"id":1,"method":"external.getState","params":{}}

成功响应：

{"id":1,"ok":true,"result":{}}

失败响应：

{"id":1,"ok":false,"error":{"code":"INVALID_PARAMS","message":"可读的错误说明"}}

单条消息最大 16 MiB。除订阅事件外，每个请求返回一次响应。

3. 最短可用示例

3.1 礼物砸头

{
  "id": 1,
  "method": "effect.trigger",
  "params": {
    "preset": "flinch",
    "source": "gift",
    "side": "left",
    "intensity": 1.0,
    "durationMs": 480,
    "queue": true
  }
}

3.2 注入面捕输入

{
  "id": 2,
  "method": "parameter.inject",
  "params": {
    "source": "song-live",
    "mode": "add",
    "priority": 50,
    "weight": 1.0,
    "ttlMs": 1000,
    "values": {"FaceAngleX": 8.0, "EyeOpenLeft": -0.4}
  }
}

3.3 订阅状态

{
  "id": 3,
  "method": "state.subscribe",
  "params": {
    "topics": [
      {"name": "model.state", "maxHz": 15},
      {"name": "model.parameters", "maxHz": 30}
    ]
  }
}

3.4 方法速查

4. 原生 API 方法

4.1 external.getState

返回当前模型、位置、运动扩展、表情、动作和挂件状态。无参数。

model.id 在模型已加载时始终非空。Studio 使用自有模型档案的标识；缺失时底层模型加载器可对实际加载的 .moc3 内容计算 SHA-256，格式为 sha256:<64 位小写十六进制>。原生 JSON 与共享内存使用同一个 ID。

model.geometry 字段：

modelToScene 固定使用：

x_scene = m00*x + m01*y + tx
y_scene = m10*x + m11*y + ty

两套坐标都为 X 向右、Y 向上；scene 中 1.0 等于输出画面高度。矩阵已包含 .model3.json layout 和 Studio 的 fitScale_，但不包含用户位置、缩放和旋转。

movement 字段：

4.2 external.getParameters

返回表情、动作、呼吸、物理和 Cubism Update() 完成后的最终参数。无参数。

{
  "modelLoaded": true,
  "modelName": "MO",
  "modelID": "c224...",
  "parameters": [
    {"name":"ParamAngleX","value":3.2,"min":-30.0,"max":30.0,"defaultValue":0.0}
  ]
}

min、max、defaultValue 来自当前模型，没有统一固定范围。没有模型时 parameters=[]。

4.3 external.getInputs

返回混入外部来源后的面捕输入。无参数。每个输入包含 name、value、min、max、defaultValue 和 addedBy。

4.4 external.getControlStatus

无参数。

4.5 state.subscribe

替换当前连接的订阅列表，不影响其他连接。

可以简写成 "topics":["model.state"]，此时 maxHz=30。

事件格式为 {"event":"external.state","patch":{}}。

服务端只保留每个主题的最新待发送帧。慢客户端不会无限积压，也不会阻塞渲染线程。

成功结果为 {"accepted":true,"snapshot":{...}}，其中 snapshot 与 external.getState 相同。

4.6 parameter.inject

向面捕输入层注入参数。注入发生在参数映射、表情、动作和物理之前。

values 支持两种写法：

{"FaceAngleX":8.0,"EyeOpenLeft":-0.4}

[{"id":"FaceAngleX","value":8.0},{"id":"EyeOpenLeft","value":-0.4}]

混合公式：

• add：当前值 += 注入值 × weight
• set：当前值 += (注入值 - 当前值) × weight

同一个 source 再次调用会整体替换该来源的参数、模式、优先级、权重和 TTL。

成功结果与 external.getControlStatus 相同。

4.7 parameter.clearSource

清除指定来源的注入参数，以及该来源正在执行或排队的效果。

重复清除不存在的来源也返回成功。

成功结果为 {"cleared":"来源名"}。

4.8 effect.trigger

触发语义效果。当前只支持礼物砸头 flinch。

队列规则：

• queue=false：立即执行，替换同一 source 的所有旧效果。
• queue=true：排到同一 source 最后一个效果之后；不同来源可同时执行。
• API v2 不限制显式排队数量，调用方应自行限制直播高峰队列长度。

flinch 使用二次衰减包络。intensity=1 时峰值为：

实际最终参数变化还取决于模型参数映射、表情、动作和物理。

成功结果与 external.getControlStatus 相同，可直接看到新的效果总数和排队数。

4.9 model.move

在 Utae 原生坐标中移动主模型。

坐标规则：

• x=0,y=0 是画面中心；x 向右为正，y 向下为正。
• 坐标以输出画面高度归一化；y=0.5 大约是中心到画面底边。
• scale=1 是基础大小。
• 动画使用平滑起止插值；新移动请求替换未完成的旧移动。

成功结果为 {"accepted":true}。该命令只改变运行时位置，不写入模型 .uvtb。

5. Windows 共享内存

共享内存适合每渲染帧读取。ABI 定义在 src/runtime/ExternalState.h。

5.1 标识与固定容量

超出容量的尾部数据不会写入共享内存；WebSocket JSON 查询不受固定数组容量限制。

5.2 安全读取

1. OpenFileMappingW(FILE_MAP_READ, FALSE, L"Local\\UtaeLive2D.State.v2")。
2. MapViewOfFile(..., FILE_MAP_READ, ...) 建立只读映射。
3. 校验 magic、abiVersion 和 structSize。
4. 读取 sequence；奇数表示正在写，需重试。
5. 读取数据后再次读取 sequence。
6. 只有前后相同且为偶数时，快照才有效；否则重试。
7. 仅当 catalogGeneration 变化时重读 ID、范围和默认值目录。

5.3 关键字段

parameterCatalog 的 minimum/maximum/defaultValue 来自模型。API v2 的 inputCatalog 主要用于 ID；输入允许范围使用 -1000000..1000000。

6. 外部接入边界

仅提供原生 /ws 与共享内存接口。第三方应用兼容 WebSocket、报文外壳和坐标换算已移除。模型绑定文件的手动导入不提供网络协议兼容。

7. 错误和边界行为

文档写“限制到范围”的字段会自动限制；写“必须在范围内”的字段越界会拒绝请求。

8. 独立礼物测试程序

先启动 Studio 并加载模型：

礼物砸头测试.bat --queue --count 3 --side left

程序通过 /ws 触发效果，再从共享内存打印明显变化的最终 Live2D 参数。

未加载模型时仍可连接，但最终参数列表为空。