From 44732ba48043ec4a6aa05351047bde1f26bbb701 Mon Sep 17 00:00:00 2001
From: MiniDay <372403923@qq.com>
Date: Thu, 4 Jan 2024 13:46:20 +0800
Subject: [PATCH] =?UTF-8?q?docs:=20=E5=AE=8C=E5=96=84=E6=96=87=E6=A1=A3?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
---
README.md | 162 ++++++++++++++++++++++++++++++++++++++++++++++++++++--
1 file changed, 158 insertions(+), 4 deletions(-)
diff --git a/README.md b/README.md
index dc9781c..a02e347 100644
--- a/README.md
+++ b/README.md
@@ -1,9 +1,28 @@
-# [HamsterBall](https://gitee.com/MiniDay/hamster-ball)
+# [HamsterBall](https://git.airgame.net/MiniDay/hamster-ball)
仓鼠球：一个基于 Redis 的 Minecraft 服务端通用消息中间件（原HamsterService）
该插件依赖于 [仓鼠核心](https://gitee.com/MiniDay/hamster-core)
+# 手动构建
+
+1. 将源代码下载或克隆至本地
+2. 在源代码根目录中打开命令行窗口
+3. 命令行窗口中执行`./gradlew clean build`
+4. 构建成品在 `build` 文件夹
+
+也可访问我的[Jenkins网站](https://jenkins.airgame.net/job/opensource/job/hamster-ball/)获取最新版
+
+# 安装步骤
+
+1. 关闭服务器
+2. 安装前置插件 [HamsterCore](https://git.airgame.net/MiniDay/hamster-core)
+3. 将 HamsterBall 放入 plugins 文件夹
+4. 启动服务器并生成默认配置文件
+5. 修改配置文件以符合预期
+6. 重启服务器
+7. 完成
+
# 环境变量
为了适配 docker 环境，本插件除了从 `config.yml` 中配置服务器信息以外，还支持从环境变量中读取
@@ -15,9 +34,12 @@
| BALL_LOCAL_SERVER_INFO_ID | 本服务器唯一识别码，最长 32 字符 | server-info.id |
| BALL_LOCAL_SERVER_INFO_NAME | 本服务端名称，用于展示给玩家看 | server-info.name |
-# 添加依赖
+# 开发
-## Gradle (`build.gradle`)
+## 添加依赖
+
+
+ Gradle(build.gradle)
```groovy
// 添加仓库
@@ -35,7 +57,31 @@ dependencies {
}
```
-## Maven (`pom.xml`)
+
+
+
+ Gradle(build.gradle.kts)
+
+```kotlin
+// 添加仓库
+repositories {
+ maven {
+ url = uri("https://maven.airgame.net/maven-public/")
+ }
+}
+
+dependencies {
+ // 对于 Bukkit 插件
+ compileOnly("cn.hamster3.mc.plugin:ball-bukkit:1.4.1")
+ // 对于 BungeeCord 插件
+ compileOnly("cn.hamster3.mc.plugin:ball-bungee:1.4.1")
+}
+```
+
+
+
+
+ Gradle(pom.xml)
```xml
@@ -65,3 +111,111 @@ dependencies {
```
+
+
+
+## 使用 API
+
+所有 API 相关的方法都位于 `cn.hamster3.mc.plugin.ball.common.api.BallAPI` 类中
+使用方法为：`BallAPI.getInstance().xxx`
+
+## 收发消息
+
+若想要消息能够在不同的服务器之间互相正常收发，你必须按照以下步骤来做：
+
+1. 使用 `BallAPI.getInstance().subscribe()` 订阅一个消息频道（频道名称通常是你的插件名）
+2. 使用 `BallAPI.getInstance().getEventBus().register()` 注册一个消息监听器
+3. 在消息监听器中对业务代码使用 `@com.google.common.eventbus.Subscribe` 注解
+
+所有事件都位于 `cn.hamster3.mc.plugin.ball.common.event` 包中
+
+### 示例
+
+在下面这个例子中我将实现一个业务功能：**跨服聊天**
+插件名称为：`GlobalChat`
+
+第一步：监听 Bukkit 的聊天事件（省略通过BukkitAPI注册该监听器的代码）
+
+```java
+import cn.hamster3.mc.plugin.ball.common.api.BallAPI;
+import com.google.gson.JsonObject;
+import org.bukkit.entity.Player;
+import org.bukkit.event.EventHandler;
+import org.bukkit.event.Listener;
+import org.bukkit.event.player.AsyncPlayerChatEvent;
+
+public class ChatListener implements Listener {
+ @EventHandler(ignoreCancelled = true)
+ public void onAsyncPlayerChat(AsyncPlayerChatEvent event) {
+ Player player = event.getPlayer();
+ String message = event.getMessage();
+ JsonObject object = new JsonObject();
+ object.addProperty("name", player.getName());
+ object.addProperty("world", player.getWorld().getName());
+ object.addProperty("message", message);
+ BallAPI.getInstance().sendBallMessage("Chat", "playerChat", object);
+ event.setCancelled(true);
+ }
+}
+
+```
+
+第二步：监听 MessageReceivedEvent 事件完成业务代码
+
+```java
+import cn.hamster3.mc.plugin.ball.common.data.BallMessage;
+import cn.hamster3.mc.plugin.ball.common.event.message.MessageReceivedEvent;
+import com.google.common.eventbus.Subscribe;
+import com.google.gson.JsonObject;
+import org.bukkit.Bukkit;
+import org.bukkit.entity.Player;
+
+public class BallListener {
+ @Subscribe
+ public void onMessageReceived(MessageReceivedEvent event) {
+ if (!"GlobalChat".equals(event.getChannel())) {
+ return;
+ }
+ BallMessage ballMessage = event.getMessage();
+ String action = ballMessage.getAction();
+ switch (action) {
+ case "onPlayerChat": {
+ JsonObject object = ballMessage.getContentAsJsonObject();
+ String name = object.get("name").getAsString();
+ String message = object.get("message").getAsString();
+ String world = object.get("world").getAsString();
+ String format = String.format("[%s][%s]: %s", world, name, message);
+ for (Player player : Bukkit.getOnlinePlayers()) {
+ player.sendMessage(format);
+ }
+ break;
+ }
+ case "othersAction": {
+ // 处理其他业务代码
+ break;
+ }
+ }
+ }
+}
+```
+
+第三步：在插件启动时注册上述两个监听器，并订阅 `GlobalChat` 频道
+
+```java
+import cn.hamster3.mc.plugin.ball.common.api.BallAPI;
+import org.bukkit.Bukkit;
+import org.bukkit.plugin.java.JavaPlugin;
+
+public class GlobalChatPlugin extends JavaPlugin {
+ @Override
+ public void onEnable() {
+ // 注册 ChatListener 事件监听器
+ Bukkit.getPluginManager().registerEvents(new ChatListener(), this);
+ // 注册 BallListener 事件监听器
+ BallAPI.getInstance().getEventBus().register(new BallListener());
+ // 订阅 GlobalChat 频道
+ BallAPI.getInstance().subscribe("GlobalChat");
+ }
+}
+
+```
\ No newline at end of file