Live2D Cubism Editor 外部集成 API
最終更新: 2024年10月24日
Editor和外部应用程序可以通过API进行集成。
外部应用程序范例
Live2D Garage的范例已发布在GitHub上。
通信方式
Editor是服务器,外部应用程序是客户端。
通信标准 | WebSocket |
格式 | JSON(UTF-8 文本) |
端口 | 22033 *默认端口号 可以任意变更。 |
缩写
带有“?”标记的元素可以省略指定。
Token ?: String,
数据形式
{ "Version": "1.0.0", "Timestamp": 1696233943287, "RequestId": "13", "Type": "Request", "Method": "GetCurrentModelUID", "Data": {} }
发送和接收均采用以下JSON格式进行。
Version~Type对于所有命令都是通用的。
元素 | 类型 | 要求 | 说明 |
---|---|---|---|
Version | String | 任意 | 指定API、命令的版本。 您可以固定要交换的版本并保持兼容性。 如果设置未支持的版本,则会出现错误。可省略。(*1) |
Timestamp | Number | 任意 | Epoch毫秒,可省略。 |
RequestId | String | 任意 | 返回服务器响应时发送的ID。 如果省略,则在服务器响应中也会被省略。 |
Type | String | 必须项 | API类型 |
Method | String | 必须项 | 命令 |
Data | Any | 必须项 | 根据操作追加的数据。 Data{}(相当于参数)的内容因命令而异。 |
(*1)这是0.9.0版本中的必需元素。
API类型
类型 | 说明 |
---|---|
Request | 要求: 主要是在从客户端(外部应用程序)向服务器(Editor)发送命令时设置。 |
Response | 响应: 主要是在服务器响应客户端命令时设置。 |
Event | Event: 主要是在任意时刻(没有收到客户端Request时)服务器自发响应客户端时设置的。 |
Error | 错误: 如果Request无效,则将设置了该值的API返回给客户端。 |
错误处理
Type返回Error的JSON。在ErrorType中填写错误内容的类型。
有关详细信息,请参考“错误类型”。
{ (省略) "Type": "Error", "Method": "SetParameterValues", "Data": { "ErrorType" : "InvalidParameter" } }
规则
对于所有命令,请尽可能在命令完成(响应)后再执行下一个命令。
令牌认证
为了保护Editor免受意外外部应用程序的影响,它有一个内置的认证系统,该系统会阻止来自外部应用程序的通信,除非用户授予许可。
首次连接
连接后,首先使用RegisterPlugin获取新的令牌。
即使获得了令牌,也不意味着可以自由通信。
仅当用户从设置对话框中启用“权限”复选框时才能使用API。
因此,外部应用程序将不得不等到那时。
第二次起的连接
从第二次开始,您可以跳过用户权限。
请在RegisterPlugin中指定先前连接中使用的令牌。
如果用户允许,RegisterPlugin将按原样返回指定的令牌,并使API立即可用。
如果令牌未经授权,则通信将被阻止,直到用户通过返回新令牌再次授权为止。
处理流程
参数的应用时机
API基本上是立即执行的,但是由于物理模拟和随机姿势,参数的应用时机存在延迟。
实际上,它是通过临时缓冲区应用的,如下所示。
临时缓冲区保留期限
临时缓冲区使用超过0.5秒后会自动放弃。
此机制可防止锁定Editor中的操作。
请注意,例如在以下情况中,无法获取预期参数。
UID和参数ID
{ "Data": { "ModelUID" : "8456858123561231456" // UID } } { "Data": { "Parameters" : [{"Id":"ParamAngleY","Value":"0.0"}] // ParameterID } }
参数ID是一个不可变的值(仅限不对模型进行变更),而UID是一个临时ID,其值可以根据连接的不同而变化。
通过外部集成API从这些UID和参数ID在Editor中设置和获取信息。
有关详细信息,请参考“外部集成API列表”。