gc-opencommand-plugin

November 22, 2023 · View on GitHub

一个为第三方客户端开放GC命令执行接口的插件

自 1.7.0 起可以通过 | 或者换行来分隔多条命令，例如：

/a 1 | /a 2
/a 3

调用 ping 响应数据将包含插件版本号。

使用本插件的应用

GrasscutterTools —— Windows 客户端工具
JGrasscutterCommand —— Mirai 插件，在QQ里执行命令
Yunzai-GrasscutterCommand —— Yunzai-bot插件，在QQ里执行命令
待补充

服务端安装

在 Release 下载 jar
放入 grasscutter/plugins 文件夹
重启 grasscutter 即可生效

玩家使用流程

在远程工具中填写服务地址，查询插件状态
填写UID，发送验证码（需要在线）
将游戏内收到的4位整数验证码填入工具校验
享受便利！

控制台连接

首次启动时，会在 plugins 目录下生成一个 opencommand-plugin 目录，打开并编辑 config.json
设置 consoleToken 的值为你的连接秘钥，建议使用至少32字符的长随机字符串。（检测到为空时会自动生成，生成时会在控制台中输出）
重新启动服务端即可生效配置
在工具中选择控制台身份，并填写你的 consoleToken 即可以控制台身份运行指令

客户端请求流程

ping 确认是否支持 opencommand 插件
sendCode 向指定玩家发送验证码（1分钟内不允许重发），保存返回的 token
使用 token 和4位整数验证码发送 verify 校验
如果验证通过，可以使用该 token 执行 command 动作

插件构建说明

克隆仓库
在目录下新建 lib 目录
将 grasscutter.jar 放入 lib 目录
执行 gradle build

多服务器

主服务器 (Dispatch)

在 opencommand-plugin 目录下打开 config.json
修改 socketPort 值为一个未被使用的端口
设置 socketToken 多服务器通信密钥，建议使用至少32字符的长随机字符串。
重新启动服务端即可生效配置

子服务器 (Game)

在 opencommand-plugin 目录下打开 config.json
修改 socketHost 和 socketPort 值为主服务器的地址和端口
设置 socketToken 和主服务器相同的值
设置 socketDisplayName 值为你的服务器名称 (用途请见下方)
重新启动服务端即可生效配置

`config.json`

{
  // 控制台连接令牌（检测到空时会自动生成）
  "consoleToken": "",
  // 验证码过期时间（秒）
  "codeExpirationTime_S": 60,
  // 临时令牌过期时间（秒）
  "tempTokenExpirationTime_S": 300,
  // 授权令牌最后使用过期时间（小时）
  "tokenLastUseExpirationTime_H": 48,
  // 多服务器通信端口
  "socketPort": 5746,
  // 多服务器通信密钥
  "socketToken": "",
  // 多服务器Dispatch服务器地址
  "socketHost": "127.0.0.1",
  // 多服务器显示名称
  "socketDisplayName": ""
}

API `/opencommand/api`

示例

https://127.0.0.1/opencommand/api

Request 请求

public final class JsonRequest {
    public String token = "";
    public String action = "";
    public String server = "";
    public Object data = null;
}

Response 响应

public final class JsonResponse {
    public int retcode = 200;
    public String message = "Success";
    public Object data;
}

Actions 动作

`测试连接`

Request

请求参数	请求数据	类型
action	`ping`	`String`

Response

返回参数	返回数据	类型
retcode	`200`	`Int`
message	`Success`	`String`
data	`null`	`null`

`获取在线玩家`

Request

请求参数	请求数据	类型
action	`online`	`String`

Response

返回参数	返回数据	类型
retcode	`200`	`Int`
message	`Success`	`String`
data	`{"count": 0, playerList": []}`	`JsonObject`

`发送验证码`

Request

请求参数	请求数据	类型
action	`sendCode`	`String`
data	`uid`	`Int`

Response

返回参数	返回数据	类型
retcode	`200`	`Int`
message	`Success`	`String`
data	`token`	`String`

`验证验证码`

Request

请求参数	请求数据	类型
action	`verify`	`String`
token	`token`	`String`
data	`code`	`Int`

Response

成功

返回参数	返回数据	类型
retcode	`200`	`Int`
message	`Success`	`String`
data	`null`	`null`

失败

返回参数	返回数据	类型
retcode	`400`	`Int`
message	`Verification failed`	`String`
data	`null`	`null`

`执行命令`

Request

请求参数	请求数据	类型
action	`command`	`String`
token	`token`	`String`
data	`command`	`String`

Response

成功

返回参数	返回数据	类型
retcode	`200`	`Int`
message	`Success`	`String`
data	`Command return`	`String`

执行控制台命令

`获取运行模式`

Request

请求参数	请求数据	类型
action	`runmode`	`String`
token	`token`	`String`

Response

成功

返回参数	返回数据	类型
retcode	`200`	`Int`
message	`Success`	`String`
data	`1 (多服务器) / 0 (单服务器)`	`Int`

`获取多服务器列表`

Request

请求参数	请求数据	类型
action	`server`	`String`
token	`token`	`String`

Response

成功

返回参数	返回数据	类型
retcode	`200`	`Int`
message	`Success`	`String`
data	`{}`	`JsonObject`

{
  "retcode": 200,
  "message": "success",
  "data": {
    // 服务器 UUID
    "13d82d0d-c7d9-47dd-830c-76588006ef6e": "2.8.0 服务器",
    "e6b83224-a761-4023-be57-e054c5bb823a": "2.8.0 开发服务器"
  }
}

`执行命令`

Request

如果为单服务器则无需填写服务器 UUID

请求参数	请求数据	类型
action	`command`	`String`
token	`token`	`String`
server	`UUID`	`String`
data	`command`	`String`

Response

成功

返回参数	返回数据	类型
retcode	`200`	`Int`
message	`Success`	`String`
data	`Command return`	`String`