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对于所有命令都是通用的。

元素类型要求说明
VersionString任意指定API、命令的版本。
您可以固定要交换的版本并保持兼容性。
如果设置未支持的版本,则会出现错误。可省略。(*1)
TimestampNumber任意Epoch毫秒,可省略。
RequestIdString任意返回服务器响应时发送的ID。
如果省略,则在服务器响应中也会被省略。
TypeString必须项API类型
MethodString必须项命令
DataAny必须项根据操作追加的数据。
Data{}(相当于参数)的内容因命令而异。

(*1)这是0.9.0版本中的必需元素。

API类型

类型说明
Request要求:
主要是在从客户端(外部应用程序)向服务器(Editor)发送命令时设置。
Response响应: 
主要是在服务器响应客户端命令时设置。
EventEvent: 
主要是在任意时刻(没有收到客户端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列表”。

请问这篇文章对您有帮助吗?
关于本报道,敬请提出您的意见及要求。