docs: 完善文档

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`)
+## 添加依赖
+
+<details>
+  <summary>Gradle(build.gradle)</summary>
 
 ```groovy
 // 添加仓库
@@ -35,7 +57,31 @@ dependencies {
 }
 ```
 
-## Maven (`pom.xml`)
+</details>
+
+<details>
+  <summary>Gradle(build.gradle.kts)</summary>
+
+```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")
+}
+```
+
+</details>
+
+<details>
+  <summary>Gradle(pom.xml)</summary>
 
 ```xml
 
@@ -65,3 +111,111 @@ dependencies {
     </dependencies>
 </project>
 ```
+
+</details>
+
+## 使用 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");
+    }
+}
+
+```