mirror of
https://github.com/jie65535/gc-opencommand-plugin.git
synced 2025-06-02 17:49:12 +08:00
300 lines
8.2 KiB
Markdown
300 lines
8.2 KiB
Markdown
# gc-opencommand-plugin
|
||
|
||
中文 | [English](README_en-US.md)
|
||
|
||
一个为第三方客户端开放GC命令执行接口的插件
|
||
|
||
## 分支说明
|
||
|
||
本分支目的在于兼容 GC 的 `unstable` 分支
|
||
|
||
## 使用本插件的应用
|
||
- [GrasscutterTools](https://github.com/jie65535/GrasscutterCommandGenerator) —— Windows 客户端工具
|
||
- [JGrasscutterCommand](https://github.com/jie65535/JGrasscutterCommand) —— [Mirai](https://github.com/mamoe/mirai) 插件，在QQ里执行命令
|
||
- [Yunzai-GrasscutterCommand](https://github.com/Zyy-boop/Yunzai-GrasscutterCommand) —— Yunzai-bot插件，在QQ里执行命令
|
||
- 待补充
|
||
|
||
## 服务端安装
|
||
|
||
1. 在 [Release](https://github.com/jie65535/gc-opencommand-plugin/releases) 下载 `jar`
|
||
2. 放入 `plugins` 文件夹即可
|
||
|
||
> 注意，如果出现以下错误：
|
||
> ```log
|
||
> INFO:PluginManager Enabling plugin: opencommand-plugin
|
||
> Exception in thread "main" java.lang.NoSuchMethodError: 'void emu.grasscutter.server.event.EventHandler.register(emu.grasscutter.plugin.Plugin)'
|
||
> at com.github.jie65535.opencommand.OpenCommandPlugin.onEnable(OpenCommandPlugin.java:49)
|
||
> at emu.grasscutter.plugin.PluginManager.lambda$enablePlugins$3(PluginManager.java:131)
|
||
> ```
|
||
> 请使用v1.2.1版本插件，因为该报错表示你的服务端是旧版！
|
||
|
||
## 控制台连接
|
||
|
||
1. 首次启动时，会在 `plugins` 目录下生成一个 `opencommand-plugin` 目录，打开并编辑 `config.json`
|
||
2. 设置 `consoleToken` 的值为你的连接秘钥，建议使用至少32字符的长随机字符串。
|
||
3. 重新启动服务端即可生效配置
|
||
4. 在客户端中选择控制台身份，并填写你的 `consoleToken` 即可以控制台身份运行指令
|
||
|
||
## 多服务器
|
||
### 主服务器 (Dispatch)
|
||
1. 在 `opencommand-plugin` 目录下打开 `config.json`
|
||
2. 修改 `socketPort` 值为一个未被使用的端口
|
||
3. 设置 `socketToken` 多服务器通信密钥，建议使用至少32字符的长随机字符串。
|
||
4. 重新启动服务端即可生效配置
|
||
|
||
### 子服务器 (Game)
|
||
1. 在 `opencommand-plugin` 目录下打开 `config.json`
|
||
2. 修改 `socketHost` 和 `socketPort` 值为主服务器的地址和端口
|
||
3. 设置 `socketToken` 和主服务器相同的值
|
||
4. 设置 `socketDisplayName` 值为你的服务器名称 (用途请见[下方](https://github.com/jie65535/gc-opencommand-plugin#%E8%8E%B7%E5%8F%96%E5%A4%9A%E6%9C%8D%E5%8A%A1%E5%99%A8%E5%88%97%E8%A1%A8))
|
||
5. 重新启动服务端即可生效配置
|
||
|
||
## 构建说明
|
||
|
||
1. 克隆仓库
|
||
2. 在目录下新建 `lib` 目录
|
||
3. 将 `grasscutter-1.1.x-dev.jar` 放入 `lib` 目录
|
||
4. `gradle build`
|
||
|
||
## 玩家使用流程
|
||
|
||
1. 在客户端中填写服务地址，确认是否支持
|
||
2. 填写UID，发送验证码
|
||
3. 将游戏内收到的**4位整数验证码**填入客户端校验
|
||
4. 享受便利！
|
||
|
||
## 客户端请求流程
|
||
|
||
1. `ping` 确认是否支持 `opencommand` 插件
|
||
2. `sendCode` 向指定玩家发送验证码（1分钟内不允许重发），保存返回的 `token`
|
||
3. 使用 `token` 和**4位整数验证码**发送 `verify` 校验
|
||
4. 如果验证通过，可以使用该 `token` 执行 `command` 动作
|
||
|
||
---
|
||
|
||
## `config.json`
|
||
|
||
```json5
|
||
{
|
||
// 控制台连接令牌
|
||
"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 请求
|
||
|
||
```java
|
||
public final class JsonRequest {
|
||
public String token = "";
|
||
public String action = "";
|
||
public String server = "";
|
||
public Object data = null;
|
||
}
|
||
```
|
||
|
||
### Response 响应
|
||
|
||
```java
|
||
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` |
|
||
|
||
```json5
|
||
{
|
||
"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` |
|