TSBot Mod — Minecraft × TeamSpeak 3 跨平台点歌联动

如果这个项目对你有帮助，欢迎前往 GitHub 仓库点亮 Star 支持我✨：

https://github.com/CharyeahOwO/TSBot-Mod

English Version: README_EN.md

TSBot Mod 是一个基于 Minecraft Forge 的服务端模组。它致力于打破游戏与语音软件的壁垒，让玩家在 MC 游戏内即可通过聊天指令，直接搜索、播放和控制 TeamSpeak 3 频道中的音乐机器人，实现「MC 点歌 → TS3 播放」的丝滑体验。

⚠️ 免责提醒：本项目最初为满足作者个人服务器需求而开发，内部架构较为复杂且功能仍在迭代中。部分极端场景下可能存在 Bug，欢迎通过 Issues 提交反馈或 PR 协助完善。

📸 运行效果展示

Minecraft 游戏内交互 (点歌/切歌)	TeamSpeak 3 机器人响应
玩家在聊天栏搜索并点击播放	机器人同步播放音乐，显示封面与信息

🔔 核心前置依赖 (部署前必看)

重要提示：本模组本质上是作为以下项目的“MC 侧扩展控制端”而存在的，仅仅是指令的“搬运工”。在使用本模组前，请务必确保你已经完全满足以下条件，否则本模组将没有任何实际作用。

🚫 避坑警告：关于 TS3 服务器的硬性要求

本模组强依赖 TeamSpeak 3 的 ServerQuery 端口（默认 10011） 以及具有相应执行权限的账号（如 serveradmin）。
如果你使用的是从淘宝等渠道购买的廉价合租服、频道服，通常商家不会开放 ServerQuery 权限，这种情况下本模组绝对无法使用！
请确保你拥有 TS3 服务器的完整底层控制权（推荐使用独立 VPS 自行搭建 TS3 服务端）。

🛠️ 必须部署的前置服务

核心播放引擎：TS3AudioBot-Plugin-Netease-QQ
- 由 @RayQuantum 开发的优秀 TS3 音乐插件。支持网易云/QQ音乐双平台播放、VIP 歌曲登录、歌词与多种播放模式。
- TSBot Mod 发送的所有播放指令（如 !wyy play 等），最终均由该插件在 TeamSpeak 3 端负责实际执行。
- 部署建议：推荐使用 Docker 部署，详见其官方 README。
底层机器人框架：TS3AudioBot
- TeamSpeak 3 音频机器人底层运行载体。
音乐 API 服务（双端共用）
- 网易云音乐 API (默认端口 3000)
- QQ 音乐 API (默认端口 3300)

💡 项目背景与原理

许多硬核游戏社区习惯同时使用 Minecraft 服务器与 TeamSpeak 3 进行语音沟通。借助上述的 TS3 插件，频道本身已具备强大的点歌能力。

痛点在于：玩家每次点歌、切歌都必须 Alt + Tab 切换到 TS3 客户端，严重打断游戏沉浸感。

解决方案：TSBot Mod 作为桥梁，将玩家在 MC 聊天栏内的交互，精准分发给音乐 API（获取数据）或 TS3 ServerQuery（执行播放），玩家完全无需离开游戏界面。

核心工作流

⚠️ 使用该模组前必须完全理解以下架构逻辑：

本模组在底层将指令分为“搜索点歌”与“基础控制”两条独立的数据链路：


sequenceDiagram
    actor Player as MC 玩家
    participant Mod as TSBot Mod (服务端)
    participant API as 音乐 API (网易云/QQ)
    participant TS3 as TS3AudioBot

    Note over Player, TS3: 链路一：搜索与点歌流程
    Player->>Mod: 输入 /ts qq/wyy search xxx
    Mod->>API: [异步] 调用 HTTP 接口搜索
    API-->>Mod: 返回 JSON 搜索结果
    Mod-->>Player: 游戏内展示搜索结果列表
    Player->>Mod: 点击聊天栏的 [播放] 按钮
    Mod->>TS3: 通过 ServerQuery 转换为 !wyy/qq play xxx 指令

    Note over Player, TS3: 链路二：控制流程 (完全不经过音乐 API)
    Player->>Mod: 输入 /ts pause 或 /ts next
    Mod->>TS3: 通过 ServerQuery 直接发送 !pause / !next 指令

🏗️ 技术架构与设计要点

💡 核心设计亮点

🚀 完全异步 (Non-blocking)：这是本 Mod 最核心的性能保障。所有涉及调用音乐 API 的网络 I/O 操作，全部采用 CompletableFuture 异步执行，绝不阻塞 Minecraft 主线程，即使 API 响应慢也完全不会拉低服务器的 TPS。
🔌 极简的控制流：如上图所示，对于单纯的控制指令（如切歌、暂停），模组会直接通过 ServerQuery 与 TS3 通信，避免了多余的 API 请求开销。
⚙️ 轻量 ServerQuery 客户端实现：没有依赖臃肿的第三方库，而是实现了 ServerQuery 的最小闭环（转义、Welcome Banner 消耗、登录、发送文本消息、断开连接），方便定位问题与二次扩展。
🛡️ 健壮的容错机制：针对连接超时、认证失败、API 宕机或空配置等异常场景，均做了完备的异常捕获，并会在游戏内给玩家明确的报错反馈。

模块概览

核心类名	核心职责
`TSBotMod`	Forge Mod 入口，Brigadier 命令树注册，接收玩家指令
`MusicSearchService`	异步 HTTP 搜索实现，负责调用网易云 / QQ 音乐 API 并解析结果
`PlayQueue`	播放队列管理，区分“立即播放”与“入队”，并负责向全服广播通知
`TS3QueryClient`	TS3 ServerQuery 协议底层客户端实现，负责发送 `!play` / `!next` 等指令

🧵 ServerQuery 协议与实现细节

本节面向“想看清楚它到底怎么跟 TS3 说话”的服主/开发者，描述当前实现的真实行为与限制。

连接生命周期（一次指令一次连接）

当前实现是“每次发送指令都新建一次 TCP 连接”，并设置 5 秒连接超时 + 5 秒读取超时。单次指令的执行序列如下：

连接 host:port
消耗 Welcome Banner（逐行读取，最多 10 行）
login client_login_name=... client_login_password=...（强校验 error id=0，否则判定认证失败）
use 1（固定使用虚拟服务器 ID=1；失败只会记录告警）
sendtextmessage targetmode=3 msg=...（把“机器人指令”当作文本消息发出去；失败只会记录告警）
quit

指令载荷（MC 指令 → 机器人指令）

模组不会直接调用 TS3AudioBot 的 HTTP/Web API，而是把机器人能识别的原生命令拼成字符串，通过 sendtextmessage 发到 TS3：

点歌：!wyy play <songId> / !qq play <songId>
入队：!wyy add <songId> / !qq add <songId>
控制：!next、!pause

其中 targetmode=3 代表“服务器消息”。如果你的 Bot/插件只监听“频道消息”(targetmode=2) 或其它来源，可能会出现“指令发出但机器人无响应”的现象。

转义规则（ts3Escape）

为了符合 ServerQuery 参数编码规则，login 凭据与 msg= 载荷都会先做转义（常见替换如下）：

原字符	转义后
`\`	`\\`
`/`	`\/`
空格	`\s`
`\|`	`\p`
`\n`	`\n`
`\r`	`\r`
`\t`	`\t`

响应解析策略（为什么有时“只看到 warn”）

每条 ServerQuery 命令发送后，会持续读取返回行，直到遇到以 error 开头的行作为“最终结果”（最多读取 20 行）。

login：必须 error id=0，否则直接判定认证失败并终止本次发送
use 1 / sendtextmessage：非 error id=0 时只记录告警，不会抛异常中断

已知限制（工程视角的边界）

虚拟服务器固定为 use 1；如果你的 TS3 并非在 ID=1 的虚拟服务器上运行，当前实现可能会把消息发到错误的虚拟服里
文本消息固定为 targetmode=3；若 Bot/插件不处理服务器消息，需要调整 Bot 侧配置或修改实现

✨ 功能特性

🔍 双源搜索：支持网易云 / QQ 音乐关键词搜索，结果在 MC 聊天栏以交互式文本展示。
▶️ 快捷交互：搜索结果自带 [播放] 与 [入队] 悬浮按钮，点击即播。
⏭ 基础控制：支持 /ts next (切歌) 与 /ts pause (暂停/继续)。
📢 全服广播：玩家点歌、切歌时，触发全服动态通知（包含操作者与歌名），氛围感拉满。
⚙️ 开箱即用：首次启动自动生成带注释的 tsbot-config.toml。
🔓 无权限门槛：无需 OP 权限，全体在线玩家均可使用。

🚀 部署指南 (服主向)

前置确认：请确保已跑通上述【核心前置依赖】中的所有服务，并且拥有 TS3 的 ServerQuery 权限，再进行本模组的安装。

1. 安装 Mod

前往 Releases 下载最新版 tsbotmod-x.x.x.jar，放入 Minecraft 服务端的 mods/ 文件夹并启动一次服务器。

2. 修改配置

服务器启动后会生成 config/tsbot-config.toml 文件，请根据实际情况配置：


[General]
# TS3 ServerQuery 连接信息
host = "your-ts3-server.com"       # TS3 服务器 IP/域名
port = 10011                       # ServerQuery 端口 (默认 10011)
user = "serveradmin"               # 管理员账号
password = "YOUR_PASSWORD"         # ⚠️ 注意：这是 Query 密码，非频道密码！

# 默认音乐源 (wyy 或 qq)
default_source = "wyy"

# 音乐 API 地址 (需包含 http:// 且不带尾斜杠)
netease_api = "http://127.0.0.1:3000"
qq_api = "http://127.0.0.1:3300"

补充说明：

当前 ServerQuery 的虚拟服务器固定为 use 1（虚拟服务器 ID=1）
当前以服务器消息方式发送指令（sendtextmessage targetmode=3）

3. 验证连接

保存配置后重启服务端，若控制台输出以下内容，则代表连接成功：


[TSBotMod] TSBotMod V2.0 已加载，等待服务器指令。
[TSBotMod]   TS3 服务器连接就绪...
[TSBotMod]   网易云 API: 正常接入
[TSBotMod]   QQ音乐 API: 正常接入

🛠️ 从源码构建 (开发者向)

环境要求：JDK 17 (必须)


git clone https://github.com/CharyeahOwO/TSBot-Mod.git
cd TSBot-Mod
# Linux / macOS
JAVA_HOME=/path/to/jdk17 ./gradlew build
# Windows
gradlew build -Dorg.gradle.java.home="C:\path\to\jdk17"

构建产物位于 build/libs/ 目录下。

⚠️ 切勿使用 JDK 21 或更高版本进行编译，否则会导致 Forge 加载时抛出 Unsupported class file major version 65 异常。

📖 指令参考词典

指令语法	功能说明	使用示例
`/ts wyy search <关键词>`	搜索网易云音乐	`/ts wyy search 晴天`
`/ts qq search <关键词>`	搜索 QQ 音乐	`/ts qq search 七里香`
`/ts wyy play <ID>`	立即播放 (网易云)	直接点击搜索结果的 `[播放]`
`/ts wyy add <ID>`	加入队列 (网易云)	直接点击搜索结果的 `[入队]`
`/ts next`	切换下一首	`/ts next`
`/ts pause`	暂停 / 继续播放	`/ts pause`

注：上述 MC 指令在后台会被解析为 !wyy play 等原生 TS3 机器人指令，并通过 ServerQuery 发送执行。

🐛 常见排错指南

Q: 为什么控制台报错无法连接到 ServerQuery 或连不上 10011 端口？
- A: 首先检查你的 TS3 服务器防火墙/安全组是否放行了 10011 (TCP) 端口。其次，如果你用的是淘宝买的几十块钱的合租 TS3 频道服，商家是不会给你 ServerQuery 权限和端口的，此情况无解，请自行租用 VPS 搭建 TS3。
Q: 为什么 TS3 日志疯狂报错 invalid loginname or password？
- A: 配置文件里的 password 填错了。ServerQuery 密码是在 TS3 服务端首次初始化时生成在控制台的，如果你忘记了，可能需要重置 TS3 服务端的数据库或者使用相关脚本重新生成。
Q: 搜索功能正常，点击播放没反应/没声音？
- A: 本 Mod 只负责发送指令。请检查你部署的 TS3AudioBot 以及 Netease-QQ 插件是否正常工作，机器人是否在你的频道里，以及机器人本身是否有播放权限。
Q: 控制台显示“发送完成”，但机器人完全不响应？
- A: 优先排查“消息投递链路”是否匹配：当前实现用 sendtextmessage targetmode=3 发送服务器消息，并固定 use 1 选择虚拟服务器。请确认你的 Bot/插件确实监听服务器消息，并且 TS3 运行在虚拟服务器 ID=1 上。
Q: 我想看更底层的 TS3 返回行来定位问题，怎么做？
- A: 将 TS3QueryClient 的日志级别调到 DEBUG，可以看到每条 ServerQuery 命令的逐行响应（包含最终的 error id=... 行），用于判断是认证、选服还是消息发送失败。
Q: QQ 音乐搜索结果一直为空？
- A: 请检查你的 QQ 音乐 API 容器状态，可以在服务器后台用 curl http://你的IP:3300/search?key=测试 看看有没有 JSON 数据返回。