想象一下，在 Minecraft 的世界中构建一个真正的 MMORPG——拥有史诗级副本、公会战争、实时经济系统，同时容纳数十万玩家在同一个宇宙中冒险。
Azathoth 让这一切成为可能。
我们不仅仅是另一个服务器框架。Azathoth 是一套完整的游戏基础设施解决方案，从底层协议到云端部署，从插件开发到运营管理，为开发者提供构建大规模在线游戏所需的一切。
┌─────────────────────────────────────────────────────────────────┐
│ Players (Fabric Client) │
└─────────────────────────┬───────────────────────────────────────┘
│ MC Protocol
┌─────────────────────────▼───────────────────────────────────────┐
│ Gateway Service │
│ 连接管理 · 智能路由 · 无缝传送 · 负载均衡 │
└─────────────────────────┬───────────────────────────────────────┘
│ gRPC
┌─────────────────────────▼───────────────────────────────────────┐
│ Game Instance Layer │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ 主城实例 │ │ 副本实例 │ │ 战场实例 │ │ ... │ │
│ │(Minestom)│ │(Minestom)│ │(Minestom)│ │ │ │
│ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │
│ Managed by Agones Fleet │
└──────────────────────┬──────────────────────────────────────────┘
│
┌─────────────┴─────────────┐
│ gRPC (同步) Kafka (异步) │
▼ ▼
┌─────────────────┐ ┌──────────────────────────────────────────┐
│ Backend Services│ │ Message Bus │
│ ├─ Player │ │ 跨服广播 · 事件驱动 · 数据同步 │
│ ├─ Dungeon │ └──────────────────────────────────────────┘
│ ├─ Guild │
│ └─ ... │
└─────────────────┘
|
基于微服务架构设计，每个组件独立扩展。Gateway 处理连接，Game Instance 运行游戏逻辑，Backend Services 管理业务数据——三层解耦，线性扩展。 |
抛弃 Bukkit 的历史包袱，使用 Minestom 从零构建。无 Tick 限制，纯异步设计，单实例可承载数千玩家。协程优先的 API 让高并发编程如同写同步代码。 |
|
游戏实例由 Kubernetes + Agones 编排。玩家涌入时自动扩容，空闲时自动缩减。Buffer 池确保新实例即时可用，告别手动运维。 |
三类插件满足不同需求：Core（冷加载核心）、Game（热加载游戏内容）、Extension（热加载扩展服务）。修改技能参数？更新副本配置？无需重启，即时生效。 |
|
同步调用用 gRPC——低延迟、强类型、双向流。异步消息用 Kafka——高吞吐、持久化、完美解耦。根据场景选择最优方案。 |
Vue 3 + Ktor 构建的现代化管理系统。实时监控服务器状态，一键管理玩家数据，可视化配置游戏内容。RBAC 权限模型，安全可控。 |
|
不止是框架，更是生态。官方市场支持插件发布、交易、评价。免费开源或付费授权，开发者自由选择。完善的 SDK 和中英双语文档降低上手门槛。 |
|
| 类别 | 技术 | 版本 | 说明 |
|---|---|---|---|
| 语言 | Kotlin | 2.3.0 | 主要开发语言，协程优先 |
| 语言 | Java | 25 | 底层兼容 |
| 构建 | Gradle (Kotlin DSL) | 9.2.1 | 多模块构建 |
| 游戏核心 | Minestom | latest | 高性能 MC 服务器库 |
| 通信 | gRPC-Kotlin | 1.5.0 | 服务间同步调用 |
| 消息队列 | Kafka | 3.6+ | 异步消息传递 |
| 后端框架 | Ktor | 3.3.3 | 管理后台 API |
| 前端框架 | Vue 3 | 3.5+ | 管理后台 UI |
| 编排 | Kubernetes + Agones | - | 容器编排与游戏服务器管理 |
| 数据库 | PostgreSQL | 16+ | 结构化数据存储 |
| 数据库 | MongoDB | 7+ | 文档数据存储 |
| 缓存 | Redis | 7+ | 会话、缓存、排行榜 |
| 分析 | ClickHouse | - | 行为日志与统计分析 |
- JDK 25+ (推荐 Eclipse Temurin)
- Kotlin 2.3.0+
- Docker & Docker Compose
- Gradle 9.2.1+ (项目自带 Wrapper)
# 1. 克隆项目
git clone https://github.com/zhibeigg/azathoth.git
cd azathoth
# 2. 启动基础设施服务
docker-compose -f deploy/docker-compose.dev.yml up -d
# 3. 构建项目
./gradlew build
# 4. 运行网关服务
./gradlew :gateway:run
# 5. 运行游戏实例 (新终端)
./gradlew :game-instance:run# 使用项目生成器创建插件项目 (即将上线)
# 访问 https://www.mcwar.cn/generator
# 或手动创建
mkdir my-plugin && cd my-plugin
./gradlew init --type kotlin-library// build.gradle.kts
plugins {
id("com.azathoth.plugin") version "1.0.0"
}
dependencies {
compileOnly("com.azathoth:azathoth-api:1.0.0")
compileOnly("com.azathoth:azathoth-plugin-api:1.0.0")
}# 1. 配置 Kubernetes 集群 (需要预先安装 Agones)
kubectl apply -f deploy/agones/
# 2. 部署基础设施
helm install azathoth-infra deploy/helm/infrastructure/
# 3. 部署游戏服务
helm install azathoth deploy/helm/azathoth/
# 4. 查看状态
kubectl get fleet -n azathoth详细部署指南请参阅 部署文档。
@Skill(id = "fireball", name = "火球术")
class FireballSkill : AbstractSkill() {
@SkillConfig
var damage: Double = 50.0
@SkillConfig
var cooldown: Duration = 3.seconds
override val manaCost: Int = 30
override suspend fun onCast(context: SkillContext): SkillResult {
val projectile = context.spawnProjectile<FireballProjectile> {
speed = 2.0
onHit { target ->
context.dealDamage(target, damage, DamageType.FIRE)
context.applyEffect(target, BurningEffect(3.seconds))
}
}
// 播放音效和粒子
context.playSound(Sound.ENTITY_BLAZE_SHOOT)
context.spawnParticles(Particle.FLAME, count = 20)
return SkillResult.success()
}
}@Dungeon(id = "dragon_lair", name = "龙穴")
class DragonLairDungeon : AbstractDungeon() {
override val minPlayers = 5
override val maxPlayers = 10
override val timeLimit = 30.minutes
override suspend fun onSetup(context: DungeonContext) {
// 加载地图
context.loadSchematic("dungeons/dragon_lair.schem")
// 注册阶段
registerPhase(TrashMobPhase())
registerPhase(MiniBossPhase())
registerPhase(FinalBossPhase())
}
inner class FinalBossPhase : DungeonPhase("final_boss") {
override suspend fun onStart(context: PhaseContext) {
context.announce("巨龙苏醒了！")
val boss = context.spawnBoss<DragonBoss>(bossSpawnLocation) {
level = context.difficulty.bossLevel
lootTable = "dragon_lair_final"
}
boss.onDeath {
context.complete(generateRewards())
}
}
}
}@BehaviorTree(id = "dragon_ai")
class DragonAI : AbstractBehaviorTree() {
override fun build(): BehaviorNode = selector {
// 低血量时逃跑
sequence {
condition { entity.healthPercent < 0.2 }
action { flee(duration = 5.seconds) }
action { castSkill("heal") }
}
// 远程攻击
sequence {
condition { distanceToTarget > 10 }
action { castSkill("fire_breath") }
}
// 近战攻击
sequence {
condition { distanceToTarget <= 3 }
action { meleeAttack() }
}
// 接近目标
action { moveTo(target.position) }
}
}@Extension(id = "payment-wechat")
class WechatPaymentPlugin : AzathothPlugin() {
override suspend fun onLoad() {
registerService(PaymentProvider::class, WechatPaymentProvider())
}
}
class WechatPaymentProvider : PaymentProvider {
override val providerId = "wechat"
override val displayName = "微信支付"
override suspend fun createOrder(request: PaymentRequest): PaymentOrder {
// 调用微信支付 API
val result = wechatClient.unifiedOrder(
outTradeNo = request.orderId,
totalFee = request.amount.toCents(),
body = request.description
)
return PaymentOrder(
orderId = request.orderId,
payUrl = result.codeUrl
)
}
}azathoth/
├── core/ # 核心模块
│ ├── protocol/ # MC 协议定义
│ ├── common/ # 公共工具库
│ ├── grpc-api/ # gRPC Proto 定义
│ └── kafka-events/ # Kafka 事件定义
│
├── gateway/ # 网关服务
│ └── src/ # 连接管理、认证、路由
│
├── game-instance/ # 游戏实例
│ ├── engine/ # Minestom 扩展引擎
│ ├── mechanics/ # 战斗、技能、AI 系统
│ └── dungeons/ # 副本逻辑
│
├── services/ # 后端微服务
│ ├── player-service/ # 玩家数据服务
│ ├── chat-service/ # 聊天服务
│ ├── dungeon-service/ # 副本匹配与管理
│ ├── activity-service/ # 活动与任务
│ ├── guild-service/ # 公会系统
│ ├── trade-service/ # 交易系统
│ └── admin-service/ # 管理后台 API
│
├── sdk/ # 开发者 SDK
│ ├── azathoth-api/ # 核心 API
│ ├── azathoth-plugin-api/ # 插件开发 API
│ └── azathoth-testing/ # 测试工具
│
├── admin-frontend/ # 管理后台前端 (Vue 3)
├── client-mod/ # Fabric 客户端模组
├── website/ # 官网 (Nuxt 3)
│
└── deploy/ # 部署配置
├── kubernetes/ # K8s 清单
├── agones/ # Agones Fleet 配置
└── helm/ # Helm Charts
| 文档 | 说明 |
|---|---|
| 快速入门 | 15 分钟上手 Azathoth |
| 架构设计 | 深入理解系统架构 |
| 插件开发 | 从零创建游戏插件 |
| API 参考 | 完整 API 文档 |
| 部署指南 | 生产环境部署 |
| 最佳实践 | 性能优化与设计模式 |
我们欢迎所有形式的贡献！无论是报告 Bug、提出建议、改进文档还是贡献代码。
# 1. Fork 并克隆仓库
git clone https://github.com/YOUR_USERNAME/azathoth.git
cd azathoth
# 2. 添加上游仓库
git remote add upstream https://github.com/zhibeigg/azathoth.git
# 3. 创建特性分支
git checkout -b feature/amazing-feature
# 4. 进行开发...
# 5. 运行测试确保通过
./gradlew test
./gradlew ktlintCheck
# 6. 提交更改 (遵循 Conventional Commits)
git commit -m "feat(skills): add fireball skill implementation"
# 7. 推送并创建 Pull Request
git push origin feature/amazing-feature我们使用 Conventional Commits 规范：
| 类型 | 说明 |
|---|---|
feat |
新功能 |
fix |
Bug 修复 |
docs |
文档更新 |
style |
代码格式调整 |
refactor |
重构 |
perf |
性能优化 |
test |
测试相关 |
chore |
构建/工具链 |
示例：
feat(dungeon): add dragon lair dungeon template
fix(gateway): resolve connection timeout issue
docs(readme): update installation instructions
- 遵循 Kotlin 官方编码规范
- 使用
ktlint进行代码格式化：./gradlew ktlintFormat - 公共 API 必须编写 KDoc 注释
- 新功能必须包含单元测试
- 测试覆盖率不低于 80%
# 运行全部测试
./gradlew test
# 运行特定模块测试
./gradlew :game-instance:test
# 运行集成测试 (需要 Docker)
./gradlew integrationTest
# 生成测试覆盖率报告
./gradlew jacocoTestReport| 分支 | 用途 |
|---|---|
main |
稳定版本，受保护 |
develop |
开发分支，PR 目标分支 |
feature/* |
新功能开发 |
fix/* |
Bug 修复 |
release/* |
版本发布准备 |
- Bug 报告: GitHub Issues
- 功能建议: GitHub Discussions
- 安全漏洞: 请发送邮件至 security@mcwar.cn
- 项目结构搭建
- 核心 API 设计
- Gateway 基础功能
- Game Instance 基础功能
- 插件系统框架
- 战斗系统
- 技能系统
- 副本系统
- AI 行为树
- 公会系统
- 交易系统
- 聊天系统
- 邮件系统
- 管理后台
- 数据分析
- 活动系统
- 客户端模组
- 完整文档
- 性能优化
- 安全审计
- 开发者市场
本项目采用 Azathoth Non-Commercial License (ANCL) 许可证。
- 个人学习、研究、教育用途
- 非商业目的的修改和使用
- 非商业目的的再分发（必须保留相同许可证）
- 任何形式的商业用途
- 使用本项目运营盈利性服务器
- 销售基于本项目的产品或服务
如需商业使用，请联系我们获取商业授权：
完整许可证文本请查看 LICENSE 文件。
- 官方网站: www.mcwar.cn
- 开发文档: docs.mcwar.cn
- 问题反馈: GitHub Issues
- 功能讨论: GitHub Discussions
感谢以下开源项目，没有它们就没有 Azathoth：
Azathoth - 为下一代 Minecraft MMORPG 而生
Made with passion by the Azathoth Team