204 lines
6.2 KiB
Markdown
204 lines
6.2 KiB
Markdown
# [HamsterBall](https://git.airgame.net/MiniDay/hamster-ball)
|
||
|
||
基于 Redis 的 Minecraft 服务端通用消息中间件
|
||
|
||
该插件依赖于 [仓鼠核心](https://git.airgame.net/MiniDay/hamster-core)
|
||
|
||
# 手动构建
|
||
|
||
1. 将源代码下载或克隆至本地
|
||
2. 在源代码根目录中打开命令行窗口
|
||
3. 命令行窗口中执行`./gradlew clean build`
|
||
4. 构建成品在 `build` 文件夹
|
||
|
||
# 安装步骤
|
||
|
||
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.8.0")
|
||
// 对于 BungeeCord 插件
|
||
compileOnly("cn.hamster3.mc.plugin:ball-bungee:1.8.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.8.0</version>
|
||
</dependency>
|
||
<!--对于 BungeeCord 插件-->
|
||
<dependency>
|
||
<groupId>cn.hamster3.mc.plugin</groupId>
|
||
<artifactId>ball-bungee</artifactId>
|
||
<version>1.8.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> |