[MD]# LivePlatformCore
## 📋 项目简介
LivePlatformCore 是一个功能强大的 Paper 插件，专为直播平台与 Minecraft 服务器的深度互动而设计。它提供了稳定的直播事件处理机制和灵活的 API 接口，让开发者能够轻松构建各种直播互动插件，实现观众与游戏的实时联动。
## ✨ 核心功能
| 功能 | 详细描述 |
|------|----------|
| 🔌 **多平台支持** | 支持 TikTok 直播平台（后续将扩展更多平台） |
| 📡 **全面事件支持** | 支持弹幕、礼物、点赞、观众加入/离开、关注、房间信息更新等多种直播事件 |
| ⚡ **高效异步处理** | 所有事件处理均在独立线程池执行，完全不阻塞游戏主线程，确保服务器流畅运行 |
| 🔄 **智能重连机制** | 实现带指数退避和抖动的自动重连算法，确保直播连接稳定可靠 |
| 🎯 **灵活事件系统** | 支持事件过滤、优先级管理和批量处理，满足不同场景需求 |
| 📊 **实时统计监控** | 提供事件统计、性能监控和连接状态查询，便于服务器管理员监控和优化 |
| 🛠️ **易用 API 设计** | 简洁明了的 API 接口，配合详细的文档和示例，降低开发者集成难度 |
| 📝 **强大调试功能** | 支持多级调试日志，便于开发排查问题和服务器管理员监控运行状态 |
| 🔧 **可配置性强** | 提供丰富的配置选项，允许根据服务器需求调整插件行为 |
## 📋 安装要求
| 依赖项 | 版本要求 | 说明 |
|--------|----------|------|
| 服务器 | Paper 1.20.1+ | 推荐使用 Paper 服务器以获得最佳性能 |
| Java | Java 17+ | 必须使用 Java 17 或更高版本 |
| 网络 | 可访问直播平台 API | 服务器需要能够访问直播平台的 API 服务 |
## 📦 快速安装
1. **下载插件**
- 从 Releases 下载最新版本的 `LivePlatformCore.jar`
2. **安装插件**
- 将下载的 `LivePlatformCore.jar` 放入服务器的 `plugins` 目录
3. **启动服务器**
- 启动服务器，插件会自动生成配置文件
- 首次启动后，服务器会自动尝试连接到直播平台
4. **配置插件**
- 停止服务器
- 修改 `plugins/LivePlatformCore/config.yml` 配置文件
- 根据需求调整直播平台设置、事件配置等
5. **重启服务器或重载配置**
- 重启服务器，或使用 `/livecore reload` 命令重新加载配置
## ⚙️ 配置详解
### 主要配置文件：`config.yml`
LivePlatformCore 使用 YAML 格式的配置文件，支持丰富的配置选项，以下是完整的配置文件示例及详细说明：
```yaml
# LivePlatformCore 配置文件
# 版本: 1.0.0
# 语言设置
# 支持: zh_cn (简体中文), en_us (英语)
language: zh_cn
# 调试模式
# 设置为 true 可输出详细日志，便于开发和调试
# 默认值: false
debug: false
# 直播平台设置
live:
# 直播平台类型 (目前仅支持 tiktok)
# 默认值: tiktok
platform: tiktok
# TikTok 平台配置
tiktok:
# TikTok 用户名 (必填，用于连接到直播间)
# 默认值: ""
username: your_username
# TikTok 房间 ID (可选，自动获取)
# 默认值: ""
room_id: ""
# TikTok 区域设置 (us, cn, jp, kr 等)
# 默认值: "us"
region: "us"
# 重连机制配置
reconnect:
# 初始重连延迟 (毫秒，必须大于0)
# 默认值: 5000
delay: 5000
# 最大重连次数 (-1 表示无限重连)
# 默认值: -1
max_attempts: -1
# 最大重连延迟 (毫秒)
# 默认值: 300000 (5分钟)
max_delay: 300000
# 是否启用指数退避算法 (自动调整重连间隔)
# 默认值: true
enable_exponential_backoff: true
# 事件处理配置
events:
# 是否启用事件统计
# 默认值: true
enable_stats: true
# 事件处理线程池大小 (根据服务器性能调整)
# 默认值: 4
thread_pool_size: 4
# 启用的事件类型
enable:
comments: true # 弹幕事件
gifts: true # 礼物事件
joins: true # 观众加入事件
likes: true # 点赞事件
follows: true # 关注事件
unfollows: true # 取消关注事件
room:
info: true # 房间信息更新事件
stats: true # 房间统计更新事件
# 事件过滤配置
filters:
# 弹幕内容过滤 (正则表达式，匹配的弹幕才会触发事件)
# 为空表示不过滤
# 默认值: ""
comment_pattern: ""
# 最小礼物价值 (仅处理价值大于此值的礼物事件，TikTok 礼物价值单位)
# 默认值: 0.0
min_gift_value: 0.0
# 性能优化配置
performance:
# 事件处理超时时间 (毫秒，超过此时间的事件处理会被中断)
# 默认值: 5000
event_timeout: 5000
# 事件队列大小 (防止事件堆积导致内存溢出)
# 默认值: 1000
queue_size: 1000
# 是否定期清理未使用的监听器
# 默认值: true
clean_unused_listeners: true
# 清理间隔时间 (分钟)
# 默认值: 30
cleanup_interval: 30
```
### 配置验证规则
LivePlatformCore 包含自动配置验证机制，确保配置文件的合法性：
| 配置项 | 验证规则 | 修复措施 |
|--------|----------|----------|
| `live.reconnect.delay` | 必须大于0 | 重置为默认值5000毫秒 |
| `live.reconnect.max_attempts` | 必须≥-1 (-1表示无限次) | 重置为默认值-1 |
| `live.platform` | 必须是支持的平台 | 当前仅支持tiktok，否则重置为默认值 |
| `events.thread_pool_size` | 必须≥1 | 重置为默认值4 |
| `performance.queue_size` | 必须≥100 | 重置为默认值1000 |
### 配置最佳实践
1. **调试模式**：
- 开发和测试阶段：设置为 `true`，获取详细日志信息
- 生产环境：设置为 `false`，减少日志开销
2. **重连机制**：
- 建议保持 `enable_exponential_backoff: true`，提高重连成功率
- 对于不稳定的网络环境，可适当增加 `max_attempts` 值
3. **事件处理**：
- 根据服务器性能调整 `thread_pool_size`，建议值：
- 小型服务器：2-4
- 中型服务器：4-8
- 大型服务器：8-16
- 仅启用实际需要的事件类型，减少不必要的处理
4. **事件过滤**：
- 使用 `comment_pattern` 过滤无效弹幕，减少事件处理量
- 对于高流量直播间，可适当提高 `min_gift_value`，只处理有价值的礼物
5. **性能优化**：
- 对于高流量直播间，可适当增加 `queue_size`
- 保持 `clean_unused_listeners: true`，自动清理不再使用的监听器
### 配置重载
修改配置文件后，可以通过以下方式重载配置：
1. **命令重载**：使用 `/livecore reload` 命令（需要 `liveplatformcore.reload` 权限）
2. **重启服务器**：完全重启服务器，重新加载所有配置
配置重载后，新的配置会立即生效，无需重启插件。
## 🎮 命令与权限
### 命令列表
| 命令 | 描述 | 所需权限 |
|------|------|----------|
| `/livecore help` | 显示命令帮助信息 | `liveplatformcore.help` |
| `/livecore connect` | 手动连接到直播平台 | `liveplatformcore.connect` |
| `/livecore disconnect` | 手动断开直播连接 | `liveplatformcore.disconnect` |
| `/livecore reload` | 重新加载配置文件 | `liveplatformcore.reload` |
| `/livecore status` | 查看直播连接状态 | `liveplatformcore.status` |
| `/livecore stats` | 查看总体统计信息 | `liveplatformcore.stats` |
| `/livecore stats events` | 查看事件统计详情 | `liveplatformcore.stats` |
| `/livecore stats performance` | 查看性能统计数据 | `liveplatformcore.stats` |
| `/livecore debug on` | 启用调试模式 | `liveplatformcore.debug` |
| `/livecore debug off` | 禁用调试模式 | `liveplatformcore.debug` |
### 权限节点
| 权限节点 | 描述 | 默认权限 |
|----------|------|----------|
| `liveplatformcore.*` | 所有 LivePlatformCore 权限（管理员权限） | OP |
| `liveplatformcore.help` | 允许使用帮助命令 | 所有人 |
| `liveplatformcore.status` | 允许查看连接状态 | 所有人 |
| `liveplatformcore.connect` | 允许手动连接直播平台 | OP |
| `liveplatformcore.disconnect` | 允许手动断开直播连接 | OP |
| `liveplatformcore.reload` | 允许重新加载配置 | OP |
| `liveplatformcore.stats` | 允许查看统计信息 | OP |
| `liveplatformcore.debug` | 允许修改调试模式 | OP |
## 🔧 开发者 API
### 1. 依赖管理
将以下依赖添加到你的 `pom.xml` 文件中：
```xml
<dependency>
<groupId>com.liveinteractive</groupId>
<artifactId>live-platform-core</artifactId>
<version>1.0.0</version>
<scope>provided</scope>
</dependency>
```
### 2. 获取 API 实例
```java
import com.liveinteractive.liveplatformcore.LivePlatformAPI;
import com.liveinteractive.liveplatformcore.LivePlatformCore;
import org.bukkit.plugin.java.JavaPlugin;
public class YourPlugin extends JavaPlugin {
private LivePlatformAPI livePlatformAPI;
@Override
public void onEnable() {
// 尝试获取 LivePlatformCore 插件实例
org.bukkit.plugin.Plugin plugin = getServer().getPluginManager().getPlugin("LivePlatformCore");
if (plugin != null) {
try {
// 兼容两种获取方式，确保 API 连接稳定
if (plugin instanceof LivePlatformAPI) {
this.livePlatformAPI = (LivePlatformAPI) plugin;
} else {
LivePlatformCore core = (LivePlatformCore) plugin;
this.livePlatformAPI = core;
}
getLogger().info("成功连接到 LivePlatformCore API!");
} catch (ClassCastException e) {
getLogger().severe("无法连接到 LivePlatformCore API: " + e.getMessage());
}
} else {
getLogger().severe("未找到 LivePlatformCore 插件！请确保已正确安装。");
}
}
// 提供获取 API 实例的方法
public LivePlatformAPI getLivePlatformAPI() {
return livePlatformAPI;
}
}
```
### 3. 监听直播事件
```java
import com.liveinteractive.liveplatformcore.event.LiveCommentEvent;
import com.liveinteractive.liveplatformcore.event.LiveGiftEvent;
import com.liveinteractive.liveplatformcore.event.LiveJoinEvent;
import com.liveinteractive.liveplatformcore.event.LiveLikeEvent;
import com.liveinteractive.liveplatformcore.event.LiveEventListener;
// 注册弹幕事件监听器
livePlatformAPI.registerListener(LiveCommentEvent.class, new LiveEventListener<LiveCommentEvent>() {
@Override
public void onEvent(LiveCommentEvent event) {
String username = event.getUsername();
String content = event.getContent();
long timestamp = event.getTimestamp();
// 注意：Bukkit API 操作必须在主线程执行
getServer().getScheduler().runTask(this, () -> {
// 示例：在游戏中广播弹幕
getServer().broadcastMessage("§b[直播弹幕] §f" + username + ": §r" + content);
});
}
});
// 使用Lambda表达式注册礼物事件监听器（推荐）
livePlatformAPI.registerListener(LiveGiftEvent.class, event -> {
String username = event.getUsername();
String giftName = event.getGiftName();
int amount = event.getAmount();
double value = event.getValue();
getLogger().info("收到直播礼物: " + username + " 送了 " + amount + " 个 " + giftName + " (价值: " + value + ")");
// 在主线程中执行游戏内操作
getServer().getScheduler().runTask(this, () -> {
// 示例：根据礼物价值给予玩家奖励
// 你的礼物处理逻辑
});
});
// 注册观众加入事件监听器
livePlatformAPI.registerListener(LiveJoinEvent.class, event -> {
String username = event.getUsername();
getServer().getScheduler().runTask(this, () -> {
getServer().broadcastMessage("§a欢迎直播观众 §f" + username + " §a加入直播间！");
});
});
```
### 4. 事件过滤示例
```java
import com.liveinteractive.liveplatformcore.event.LiveCommentEvent;
import com.liveinteractive.liveplatformcore.event.LiveGiftEvent;
import com.liveinteractive.liveplatformcore.event.LiveEventFilter;
// 示例 1: 只监听包含命令前缀 "!" 的弹幕
livePlatformAPI.registerListener(
LiveCommentEvent.class,
event -> {
// 处理命令弹幕
String command = event.getContent().substring(1);
getLogger().info("收到直播命令: " + command + " (来自: " + event.getUsername() + ")");
},
new LiveEventFilter<LiveCommentEvent>() {
@Override
public boolean filter(LiveCommentEvent event) {
return event.getContent().startsWith("!");
}
}
);
// 示例 2: 只处理价值大于 10.0 的礼物
livePlatformAPI.registerListener(
LiveGiftEvent.class,
event -> {
// 处理高价值礼物，例如生成稀有物品或强大生物
getServer().getScheduler().runTask(this, () -> {
// 高价值礼物处理逻辑
});
},
event -> event.getValue() > 10.0 // 使用Lambda表达式作为过滤器
);
// 示例 3: 组合过滤条件
livePlatformAPI.registerListener(
LiveCommentEvent.class,
event -> {
// 处理符合条件的弹幕
},
event -> {
String content = event.getContent();
// 只处理长度大于 5 且包含 "#" 标签的弹幕
return content.length() > 5 && content.contains("#");
}
);
```
### 5. API 核心方法
| 方法名 | 描述 |
|--------|------|
| `connect()` | 手动连接到直播平台，返回连接是否成功 |
| `disconnect()` | 手动断开直播连接，返回断开是否成功 |
| `isConnected()` | 检查是否已连接到直播平台 |
| `getCurrentPlatform()` | 获取当前直播平台类型（如 "tiktok"） |
| `getCurrentUsername()` | 获取当前监听的用户名 |
| `registerListener(Class<T>, LiveEventListener<T>)` | 注册事件监听器 |
| `registerListener(Class<T>, LiveEventListener<T>, LiveEventFilter<T>)` | 注册带过滤条件的事件监听器 |
| `registerListener(Class<T>, LiveEventListener<T>, LiveEventFilter<T>, int)` | 注册带过滤条件和优先级的事件监听器 |
| `unregisterListener(Class<T>, LiveEventListener<T>)` | 注销指定事件类型的监听器 |
| `getConfigManager()` | 获取配置管理器，用于访问配置信息 |
| `getStatsManager()` | 获取统计管理器，用于获取事件和性能统计 |
| `enableDebugMode(boolean)` | 启用或禁用调试模式 |
| `isDebugMode()` | 检查是否处于调试模式 |
## 📚 开发最佳实践
### 1. 线程安全处理
- **务必记住**：所有涉及 Bukkit API 的操作（如发送消息、生成实体、修改方块等）**必须**在**主线程**执行
- 使用 `BukkitScheduler.runTask()` 切换到主线程执行Bukkit API操作
- 事件监听器本身在异步线程执行，切勿直接调用 Bukkit API
### 2. 事件处理优化
- 合理使用事件过滤器，减少不必要的处理开销
- 避免在事件监听器中执行耗时操作，如网络请求、复杂计算等
- 对于批量事件（如大量点赞），考虑使用批量处理机制
- 及时注销不再使用的监听器，避免内存泄漏
### 3. 错误处理
- 为事件监听器添加适当的异常处理，防止单个监听器故障影响整个事件系统
- 记录关键操作日志，便于调试和监控
- 考虑添加降级机制，在直播连接异常时保证插件基本功能可用
### 4. 配置管理
- 为你的插件添加 LivePlatformCore 依赖检查
- 提供清晰的错误信息，帮助服务器管理员排查配置问题
- 考虑添加自动更新检查功能，及时通知用户插件新版本
## 📊 统计与监控
### 查看统计信息
LivePlatformCore 提供了丰富的统计命令，帮助服务器管理员监控插件运行状态：
```bash
# 查看总体统计信息
/livecore stats
# 查看详细事件统计
/livecore stats events
# 查看性能统计数据
/livecore stats performance
```
### 统计信息说明
| 统计项 | 说明 |
|--------|------|
| 连接状态 | 显示当前直播连接状态和累计连接时长 |
| 事件总数 | 各种类型事件的总处理数量 |
| 事件速率 | 最近一分钟的事件处理速率 |
| 平均处理时间 | 各类事件的平均处理时间 |
| 队列状态 | 事件队列的当前大小和峰值 |
| 线程池状态 | 线程池的活跃线程数和任务执行情况 |
| 重连统计 | 重连尝试次数和成功率 |
## 🐛 常见问题与解决方案
### Q1: 无法连接到 TikTok 直播
**可能原因：**
- 配置文件中 `username` 填写错误
- 服务器网络无法访问 TikTok API
- TikTok 直播间未开播
- 区域设置不正确
**解决方案：**
1. 仔细检查 `config.yml` 中的 `username` 配置，确保与直播间用户名完全一致
2. 测试服务器网络连接，确保可以访问 TikTok 相关域名
3. 确认 TikTok 直播间正在直播状态
4. 尝试修改 `region` 配置为合适的区域（如 `us`, `cn`, `jp` 等）
5. 启用调试模式 (`debug: true`)，查看详细错误日志
### Q2: 事件监听器不工作
**可能原因：**
- API 实例获取失败
- 对应事件类型未在配置中启用
- 事件过滤器条件过于严格
- 监听器注册代码存在问题
**解决方案：**
1. 检查插件日志，确认 API 连接成功
2. 检查 `config.yml` 中对应事件类型的 `enable` 配置是否为 `true`
3. 调试事件过滤器，尝试放宽条件或暂时移除过滤器
4. 检查监听器注册代码，确保没有语法错误或逻辑问题
5. 查看服务器日志，确认监听器是否成功注册
### Q3: 服务器性能下降
**可能原因：**
- 事件处理逻辑耗时过长
- 事件监听器过多
- 事件队列堆积
- 线程池配置不合理
**解决方案：**
1. 优化事件监听器的处理逻辑，减少耗时操作
2. 减少不必要的监听器，合并相似功能
3. 调整 `config.yml` 中的性能参数：
- 增加 `thread_pool_size` 以提高并发处理能力
- 增大 `queue_size` 以应对突发大量事件
- 调整 `event_timeout` 以防止长时间阻塞
4. 使用统计命令 `/livecore stats performance` 分析性能瓶颈
### Q4: 礼物事件价值不准确
**可能原因：**
- TikTok 礼物价值计算方式与预期不符
- 礼物价值单位理解错误
**解决方案：**
1. 注意：TikTok 礼物价值单位并非实际货币，而是平台内部价值
2. 建议通过实际测试确认不同礼物的价值范围
3. 调整 `min_gift_value` 配置以适应实际需求
## 📝 更新日志
### v1.0.0 (2025-12-15)
- 初始版本正式发布
- 支持 TikTok 直播平台
- 实现完整的事件体系：弹幕、礼物、点赞、观众加入/离开、关注等
- 提供稳定的 API 接口，支持事件监听和过滤
- 实现智能重连机制，确保直播连接稳定
- 提供丰富的统计和监控功能
- 支持详细的调试日志
- 提供完整的配置选项
## 🤝 贡献指南
我们非常欢迎社区开发者参与 LivePlatformCore 的开发和改进！
### 贡献流程
1. Fork 本项目仓库到你的 GitHub 账号
2. 创建一个新的功能分支：`git checkout -b feature/YourFeatureName`
3. 实现你的功能或修复，确保代码符合项目的代码风格
4. 编写或更新相关文档
5. 提交你的修改：`git commit -m "Add: 你的功能描述"`
6. 推送到你的分支：`git push origin feature/YourFeatureName`
7. 开启 Pull Request，描述你的修改内容和目的
### 开发规范
- 代码风格遵循 Java 标准规范
- 所有公共方法和类必须添加 Javadoc 注释
- 新增功能必须包含相应的测试用例
- 遵循最小化修改原则，避免不必要的代码变动
- 确保代码兼容 Paper 1.20.1+ 版本
## 📄 许可证
LivePlatformCore 采用 MIT 许可证开源。
## 📞 联系方式与支持
- **问题反馈**: 请在 Issues 中提交
- **讨论交流**: 作者QQ：2919089965，申请好友记得标注其来意
## 📦 相关项目
- **LiveBattlePlugin** - 基于 LivePlatformCore 开发的直播阵营对战插件，实现观众通过直播互动生成游戏内生物进行对战
## 🙏 致谢
感谢以下项目和开发者对 LivePlatformCore 的贡献和启发：
- [TikTokLiveJava](https://github.com/jwdeveloper/TikTokLiveJava) - 提供 TikTok 直播连接支持
- 所有参与测试和提供反馈的用户
---
**LivePlatformCore** - 连接直播与游戏的桥梁 🎮📡
*如果这个项目对你有帮助，请给我们一个 ⭐ 支持一下！*[/MD]
