# [HamsterBall](https://git.airgame.net/MiniDay/hamster-ball)

仓鼠球：一个基于 Redis 的 Minecraft 服务端通用消息中间件（原HamsterService）

该插件依赖于 [仓鼠核心](https://git.airgame.net/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` 中配置服务器信息以外，还支持从环境变量中读取

| 环境变量             | 描述                 | 对应 config 值      |
|:-----------------|:-------------------|:-----------------|
| BALL_SERVER_ID   | 本服务器唯一识别码，最长 32 字符 | server-info.id   |
| BALL_SERVER_NAME | 本服务端名称，用于展示给玩家看    | server-info.name |

# 开发

## 添加依赖

<details>
  <summary>Gradle</summary>

```groovy
// 添加仓库
repositories {
    maven {
        url = uri("https://maven.airgame.net/maven-public/")
    }
}

dependencies {
    // 对于 Bukkit 插件
    compileOnly("cn.hamster3.mc.plugin:ball-bukkit:1.6.0")
    // 对于 BungeeCord 插件
    compileOnly("cn.hamster3.mc.plugin:ball-bungee:1.6.0")
}
```

</details>

<details>
  <summary>Maven</summary>

```xml

<project>
    <!--添加仓库-->
    <repositories>
        <repository>
            <id>airgame-repo</id>
            <name>AirGame Maven仓库</name>
            <url>https://maven.airgame.net/maven-public</url>
        </repository>
    </repositories>

    <dependencies>
        <!--对于 Bukkit 插件-->
        <dependency>
            <groupId>cn.hamster3.mc.plugin</groupId>
            <artifactId>ball-bukkit</artifactId>
            <version>1.6.0</version>
        </dependency>
        <!--对于 BungeeCord 插件-->
        <dependency>
            <groupId>cn.hamster3.mc.plugin</groupId>
            <artifactId>ball-bungee</artifactId>
            <version>1.6.0</version>
        </dependency>
    </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`

<details>
  <summary>第一步：监听 Bukkit 的聊天事件（省略通过BukkitAPI注册该监听器的代码）</summary>

```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);
    }
}
```

</details>

<details>
<summary>第二步：监听 MessageReceivedEvent 事件完成业务代码</summary>

```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;
        }
        String action = event.getAction();
        switch (action) {
            case "onPlayerChat": {
                JsonObject object = event.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;
            }
        }
    }
}
```

</details>

<details>
<summary>第三步：在插件启动时注册上述两个监听器，并订阅 `GlobalChat` 频道</summary>

```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");
    }
}
```

</details>