Mizuki Framework

面向 Minecraft 小游戏服的多房间竞技框架 — 模板方法 + 状态机，业务侧只需实现钩子即可接入新玩法。

作者：Misoryan
开发周期：2023.06 – 2024.10
落地项目：BedWarsReload（起床战争 · 分布式竞技）

---

简介

Mizuki 是我在游戏服务端兼职期间独立设计并实现的 Java 框架，用于支撑「单服多房间、同玩法并发对局」类小游戏。框架将地图加载、房间生命周期、玩家状态机、倒计时、观战、记分板、跨节点匹配等通用逻辑抽象为可复用层，下游玩法（如起床战争）只需继承三个抽象类并实现业务钩子。

线上曾运行于网易代理 PC 端第三方游戏服，与 Redis/Netty 集群配合完成跨节点房间同步。

核心能力

模块	说明
四层状态机	LOADING → WAITING → PLAYING → ENDING，房间全生命周期由框架托管
模板方法	AbstractGame 定义 startGame / endGame / addGamePlayer 等扩展点
多房间池	AbstractGameController 维护房间列表，人数不足时自动 loadNewGame()
玩家状态	WAITING / PLAYING / SPECTATING / DEATH_SPECTATING / AFK / DEATH 及可见性隔离
地图热加载	异步复制地图模板 → 动态 createWorld，对局结束自动卸载并清理 mizuki#<uuid> 目录
倒计时引擎	CountdownRunnable 统一处理开局倒计时、满员加速、结束转场
配置系统	注解驱动 GenericGameConfig，支持 Location 等自定义序列化
分布式集成	可选对接平台 Netty Packet（组队进房、跨服传送、Redis 房间状态同步）

架构一览

AbstractGameController          ← 房间池、匹配、记分板、命令注册
    │
    ├── AbstractGame            ← 状态机、地图、倒计时、广播
    │       └── AbstractGamePlayer ← 玩家状态、观战、重连、退出
    │
    ├── GenericGameConfig       ← YAML 配置
    ├── CountdownRunnable       ← 开局/结束倒计时
    ├── DefaultGameListener     ← Bukkit 事件桥接
    └── NetworkListener         ← 跨服 Packet（可选，需平台运行时）

快速接入（伪代码）

// 1. 实现 Controller
public class MyGameController extends AbstractGameController {
    @Override
    public AbstractGame addNewGame() {
        Game game = new Game(this);
        games.add(game);
        return game;
    }
}

// 2. 实现 Game
public class Game extends AbstractGame {
    public Game(AbstractGameController controller) { super(controller); }

    @Override public AbstractGamePlayer addGamePlayer(Player player) { ... }
    @Override public void startGame() { /* 玩法开始逻辑 */ }
    @Override public void endGame()   { /* 玩法结束逻辑 */ }
    @Override public void rejoin(Player player) { ... }
    @Override public List<String> getScoreboard(Player player) { ... }
    @Override public void onCountdown(int seconds) { ... }
}

// 3. 实现 GamePlayer
public class GamePlayer extends AbstractGamePlayer {
    public GamePlayer(AbstractGame game, Player player) { super(game, player); }
    @Override public void quitGame(boolean disconnected) { ... }
}

完整业务示例见 BedWarsReload 的 Game / GameController / GamePlayer。

项目结构

MizukiFramework/
├── common/                          # 框架核心模块
│   └── src/main/java/me/misoryan/mizuki/
│       ├── game/
│       │   ├── abstracts/             # AbstractGame / Controller / GamePlayer
│       │   ├── enums/               # GameState, GamePlayerStatus
│       │   └── listener/              # 默认事件 & Netty 桥接
│       ├── config/                    # GenericGameConfig
│       ├── events/                    # 自定义 Bukkit 事件
│       ├── runnable/                  # 倒计时 & Netty 定时任务
│       ├── command/                   # /mizuki, /spec 等
│       ├── menu/                      # 观战菜单
│       ├── scoreboard/                # 动态记分板
│       └── util/                      # 配置、聊天、玩家工具
├── libs/                              # 运行时依赖（见下方说明，不含在公开仓库）
└── pom.xml

构建说明

环境要求

• JDK 8+
• Maven 3.6+
• 运行时需 Spigot/Paper 服务端

关于 libs/ 依赖

本框架在原始生产环境中依赖所在游戏平台的私有运行时（CoreSpigot、spigot 定制包）。这些二进制文件属于原雇主/平台资产，不会包含在本公开仓库中。

本地编译前，请将以下 JAR 放入 libs/ 目录（需自行从原平台环境获取，或使用兼容的 Spigot API 进行适配）：

文件	说明
CoreSpigot-2.1.jar	平台核心（命令、记分板、Netty、缓存等）
spigot-1.0.jar	定制 Spigot 服务端 API

若仅阅读/学习框架设计，可直接浏览 common/src 下的抽象类与接口；分布式相关类（NetworkListener、NettyRunnable）在缺少平台依赖时不会加载。

mvn clean package -pl common

技术栈

• 语言：Java 8
• 构建：Maven 多模块
• 服务端：Spigot/Bukkit API
• 分布式：Redis / Redisson、Netty 自定义 Packet（平台集成层）
• 工具：Lombok、Apache Commons IO

与简历项目的对应关系

简历描述	代码位置
四层状态机 + 模板方法	AbstractGame, GameState
多房间并发对局	AbstractGameController.games, loadNewGame()
Event + Listener 解耦	EventBasic, DefaultGameListener
跨节点房间同步	NettyRunnable, NetworkListener, NettyListener
130+ 文件独立维护	下游 BedWarsReload Kotlin 业务层

许可与声明

• 本仓库公开的是 Misoryan 个人编写的框架源码，用于作品集与面试展示。
• 原公司私有仓库地址不在此公开；libs/ 中的第三方/平台 JAR 未随仓库分发。
• 框架中与 cn.omg.* 相关的集成为原平台运行时耦合，开源阅读时请关注 me.misoryan.mizuki 包下的抽象与设计。

联系

• GitHub：Misoryan
• Email：misoryan@qq.com