MMORPG-Grade Minecraft Server Framework
Built for the next generation of massively multiplayer online games, supporting hundreds of thousands of concurrent players
English | 简体中文
Imagine building a true MMORPG within Minecraft—epic dungeons, guild wars, real-time economy systems, with hundreds of thousands of players adventuring in the same universe simultaneously.
Azathoth makes this possible.
We're not just another server framework. Azathoth is a complete game infrastructure solution, from low-level protocols to cloud deployment, from plugin development to operations management, providing everything developers need to build massive online games.
┌─────────────────────────────────────────────────────────────────┐
│ Players (Fabric Client) │
└─────────────────────────┬───────────────────────────────────────┘
│ MC Protocol
┌─────────────────────────▼───────────────────────────────────────┐
│ Gateway Service │
│ Connection Mgmt · Smart Routing · Seamless Transfer │
└─────────────────────────┬───────────────────────────────────────┘
│ gRPC
┌─────────────────────────▼───────────────────────────────────────┐
│ Game Instance Layer │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ Hub │ │ Dungeon │ │Battlegrnd│ │ ... │ │
│ │(Minestom)│ │(Minestom)│ │(Minestom)│ │ │ │
│ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │
│ Managed by Agones Fleet │
└──────────────────────┬──────────────────────────────────────────┘
│
┌─────────────┴─────────────┐
│ gRPC (Sync) Kafka (Async)│
▼ ▼
┌─────────────────┐ ┌──────────────────────────────────────────┐
│ Backend Services│ │ Message Bus │
│ ├─ Player │ │ Cross-server Broadcast · Event-Driven │
│ ├─ Dungeon │ └──────────────────────────────────────────┘
│ ├─ Guild │
│ └─ ... │
└─────────────────┘
|
Designed with microservices architecture where each component scales independently. Gateway handles connections, Game Instance runs game logic, Backend Services manage business data—three-layer decoupling with linear scalability. |
Leaving behind Bukkit's legacy, built from scratch with Minestom. No tick limitations, pure async design, single instance supports thousands of players. Coroutine-first API makes concurrent programming feel like writing synchronous code. |
|
Game instances orchestrated by Kubernetes + Agones. Auto-scale up when players flood in, scale down when idle. Buffer pools ensure new instances are instantly available—goodbye manual ops. |
Three plugin types for different needs: Core (cold-load fundamentals), Game (hot-load game content), Extension (hot-load services). Modify skill parameters? Update dungeon config? No restart needed, instant effect. |
|
Use gRPC for sync calls—low latency, strong typing, bidirectional streaming. Use Kafka for async messages—high throughput, persistence, perfect decoupling. Choose the optimal approach per scenario. |
Modern management system built with Vue 3 + Ktor. Real-time server monitoring, one-click player management, visual game content configuration. RBAC permission model for secure control. |
|
More than a framework—it's an ecosystem. Official marketplace supports plugin publishing, trading, and reviews. Free open-source or paid licensing, developers choose freely. Comprehensive SDK and bilingual documentation lower the entry barrier. |
|
| Category | Technology | Version | Description |
|---|---|---|---|
| Language | Kotlin | 2.3.0 | Primary language, coroutine-first |
| Language | Java | 25 | Underlying compatibility |
| Build | Gradle (Kotlin DSL) | 9.2.1 | Multi-module builds |
| Game Core | Minestom | latest | High-performance MC server library |
| Communication | gRPC-Kotlin | 1.5.0 | Inter-service sync calls |
| Message Queue | Kafka | 4.1+ | Async messaging |
| Backend Framework | Ktor | 3.3.3 | Admin API |
| Frontend Framework | Vue 3 | 3.5+ | Admin UI |
| Orchestration | Kubernetes + Agones | - | Container orchestration & game server management |
| Database | PostgreSQL | 17+ | Structured data storage |
| Database | MongoDB | 8+ | Document data storage |
| Database | ClickHouse | 24.8+ | Player snapshot & rollback time-series data |
| Cache | Redis | 7+ | Sessions, cache, leaderboards |
| Build Tool | Rspack / Rsbuild | latest | Frontend build |
- JDK 21+ (recommended: Eclipse Temurin, JDK 25 for production)
- Docker & Docker Compose
- Node.js 20+ (admin frontend)
- Gradle 9.2.1+ (Wrapper included, no manual install needed)
# 1. Clone the repository
git clone https://github.com/MinecraftAzathoth/azathoth.git
cd azathoth
# 2. Start infrastructure (PostgreSQL, MongoDB, Redis, Kafka)
docker-compose -f deploy/docker/docker-compose.yml up -d
# 3. Build the project
./gradlew build
# 4. Run Gateway service
./gradlew :gateway:run
# 5. Run Game Instance (new terminal)
./gradlew :game-instance:run
# 6. Run admin frontend (new terminal)
cd admin-frontend
npm install
npm run dev./gradlew build # Build entire project
./gradlew :gateway:build # Build single module
./gradlew test # Run all tests
./gradlew :game-instance:test # Run single module tests
./gradlew :gateway:shadowJar # Generate executable JAR// 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. Configure Kubernetes cluster (Agones required)
kubectl apply -f deploy/agones/
# 2. Deploy game services
helm install azathoth deploy/helm/azathoth/
# 3. Check status
kubectl get fleet -n azathothSee Deployment Guide for detailed instructions.
@Skill(id = "fireball", name = "Fireball")
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))
}
}
// Play sounds and particles
context.playSound(Sound.ENTITY_BLAZE_SHOOT)
context.spawnParticles(Particle.FLAME, count = 20)
return SkillResult.success()
}
}@Dungeon(id = "dragon_lair", name = "Dragon's Lair")
class DragonLairDungeon : AbstractDungeon() {
override val minPlayers = 5
override val maxPlayers = 10
override val timeLimit = 30.minutes
override suspend fun onSetup(context: DungeonContext) {
// Load map
context.loadSchematic("dungeons/dragon_lair.schem")
// Register phases
registerPhase(TrashMobPhase())
registerPhase(MiniBossPhase())
registerPhase(FinalBossPhase())
}
inner class FinalBossPhase : DungeonPhase("final_boss") {
override suspend fun onStart(context: PhaseContext) {
context.announce("The dragon awakens!")
val boss = context.spawnBoss<DragonBoss>(bossSpawnLocation) {
level = context.difficulty.bossLevel
lootTable = "dragon_lair_final"
}
boss.onDeath {
context.complete(generateRewards())
}
}
}
}// Build behavior trees with DSL
val dragonAI = behaviorTree("dragon_ai") {
selector("root") {
// Flee and heal when low health
sequence("fleeAndHeal") {
node(IsHealthBelow(0.2))
node(Flee(speed = 0.25, safeDistance = 20.0))
node(Heal(amount = 50.0, cooldownTicks = 100))
}
// Ranged attack (fire when in range)
sequence("rangedCombat") {
node(HasTarget())
node(IsTargetAlive())
node(IsTargetInRange(16.0))
node(RangedAttack(damage = 15.0, range = 16.0))
}
// Melee attack
sequence("meleeCombat") {
node(HasTarget())
node(IsTargetAlive())
node(IsTargetInRange(3.0))
node(MeleeAttack(damage = 25.0, range = 3.0))
}
// Chase target
sequence("chase") {
node(FindTarget(perception, range = 24.0))
node(ChaseTarget(speed = 0.3, arrivalDistance = 3.0))
}
}
}
// Or use prebuilt templates for quick setup
val zombieAI = BehaviorTemplates.aggressiveMelee(perception)
val skeletonAI = BehaviorTemplates.aggressiveRanged(perception)
val sheepAI = BehaviorTemplates.passiveWanderer(patrolWaypoints)@Extension(id = "payment-stripe")
class StripePaymentPlugin : AzathothPlugin() {
override suspend fun onLoad() {
registerService(PaymentProvider::class, StripePaymentProvider())
}
}
class StripePaymentProvider : PaymentProvider {
override val providerId = "stripe"
override val displayName = "Stripe"
override suspend fun createOrder(request: PaymentRequest): PaymentOrder {
// Call Stripe API
val session = stripeClient.checkout.sessions.create(
SessionCreateParams.builder()
.setMode(SessionCreateParams.Mode.PAYMENT)
.addLineItem(...)
.build()
)
return PaymentOrder(
orderId = request.orderId,
payUrl = session.url
)
}
}azathoth/
├── core/ # Core modules
│ ├── protocol/ # MC protocol definitions
│ ├── common/ # Common utilities
│ ├── grpc-api/ # gRPC Proto definitions
│ └── kafka-events/ # Kafka event definitions
│
├── gateway/ # Gateway service
│ └── src/ # Connection mgmt, auth, routing
│
├── game-instance/ # Game instance
│ ├── engine/ # Minestom extensions
│ ├── mechanics/ # Combat, skills, AI behavior trees, perception, threat, pathfinding
│ └── dungeons/ # Dungeon logic
│
├── services/ # Backend microservices
│ ├── player-service/ # Player data service
│ ├── chat-service/ # Chat service
│ ├── dungeon-service/ # Dungeon matching & management
│ ├── activity-service/ # Activities & quests
│ ├── guild-service/ # Guild system
│ ├── trade-service/ # Trading system
│ ├── mail-service/ # Mail system
│ ├── rollback-service/ # Player data snapshot & rollback (ClickHouse)
│ └── admin-service/ # Admin API
│
├── sdk/ # Developer SDK
│ ├── azathoth-api/ # Core API
│ ├── azathoth-plugin-api/ # Plugin development API
│ ├── azathoth-testing/ # Testing utilities
│ └── azathoth-gradle-plugin/ # Gradle build plugin
│
├── admin-frontend/ # Admin frontend (Vue 3)
├── client-mod/ # Fabric client mod
├── website/ # Website (Nuxt 3)
│
└── deploy/ # Deployment configs
├── docker/ # Docker Compose & Dockerfiles
├── kubernetes/ # K8s manifests
├── agones/ # Agones Fleet configs
└── helm/ # Helm Charts
| Document | Description |
|---|---|
| Quick Start | Get started with Azathoth in 15 minutes |
| Architecture | Deep dive into system architecture |
| Plugin Development | Create game plugins from scratch |
| API Reference | Complete API documentation |
| Deployment Guide | Production deployment |
| Best Practices | Performance optimization & design patterns |
We welcome all forms of contributions! Whether it's reporting bugs, suggesting features, improving documentation, or contributing code.
# 1. Fork and clone the repository
git clone https://github.com/YOUR_USERNAME/azathoth.git
cd azathoth
# 2. Add upstream remote
git remote add upstream https://github.com/MinecraftAzathoth/azathoth.git
# 3. Create a feature branch
git checkout -b feature/amazing-feature
# 4. Develop...
# 5. Run tests to ensure they pass
./gradlew test
# 6. Commit changes (follow Conventional Commits)
git commit -m "feat(skills): add fireball skill implementation"
# 7. Push and create Pull Request
git push origin feature/amazing-featureWe use Conventional Commits:
| Type | Description |
|---|---|
feat |
New feature |
fix |
Bug fix |
docs |
Documentation update |
style |
Code formatting |
refactor |
Refactoring |
perf |
Performance improvement |
test |
Testing related |
chore |
Build/tooling |
Examples:
feat(dungeon): add dragon lair dungeon template
fix(gateway): resolve connection timeout issue
docs(readme): update installation instructions
- Follow Kotlin Official Coding Conventions
- Public APIs must have KDoc comments
- New features must include unit tests
- Never abuse
!!— prefer Kotlin null safety, explicit null checks, and result objects - Database and Redis I/O must be handled asynchronously
# Run all tests
./gradlew test
# Run specific module tests
./gradlew :game-instance:test
./gradlew :gateway:test
./gradlew :services:player-service:test| Branch | Purpose |
|---|---|
main |
Stable release, protected |
develop |
Development branch, PR target |
feature/* |
New feature development |
fix/* |
Bug fixes |
release/* |
Release preparation |
- Bug Reports: GitHub Issues
- Feature Requests: GitHub Discussions
- Security Vulnerabilities: Please email security@mcwar.cn
- Project structure setup
- Core API design
- Gateway basic functionality
- Game Instance basic functionality
- Plugin system framework
- Combat system
- Skill system
- Dungeon system
- AI behavior trees
- Guild system
- Trading system
- Chat system
- Mail system
- Admin dashboard
- Data analytics
- Activity system
- Client mod
- Player data snapshot & rollback system (ClickHouse)
- Complete documentation
- Performance optimization
- Security audit
- Developer marketplace
This project is licensed under the Azathoth Non-Commercial License (ANCL).
- Personal learning, research, and educational use
- Non-commercial modification and use
- Non-commercial redistribution (must retain same license)
- Any form of commercial use
- Operating profit-generating servers using this project
- Selling products or services based on this project
For commercial use, please contact us for a commercial license:
- Email: business@mcwar.cn
- Website: https://www.mcwar.cn/license
See the full license text in the LICENSE file.
- Website: www.mcwar.cn
- Documentation: docs.mcwar.cn
- Issue Tracker: GitHub Issues
- Discussions: GitHub Discussions
Thanks to these open-source projects, without which Azathoth wouldn't exist:
- Minestom - High-performance Minecraft server library
- Kotlin - Modern programming language
- Agones - Game server orchestration
- gRPC - High-performance RPC framework
Azathoth - Built for the Next Generation of Minecraft MMORPGs
Made with passion by the Azathoth Team