VortexRPG

# ⚔ VortexRPG ### A full-scale MMO engine for Paper 1. 21+ — by Eternal Realm™

VortexRPG is a production-grade MMO core framework that transforms your Paper server into a fully realized RPG world. Choose your class, master a spell arsenal, close fracture rifts tearing open across the realm, run expedition contracts with your party, and trade on a dynamic player economy — all powered by a single, zero-dependency JAR.

Drop it in your `plugins/` folder.

## ✦ Core Systems

### ⚔ Classes & Ascension - Six base classes — Knight, Mage, Ranger, Cleric, Beastmaster, Engineer - Two ascension paths per class — 12 specializations total - Custom stat profiles, XP curves, and attribute scaling per class - Skill point allocation, passive bonuses, and class-bound relics - Lock in your ascension path with `/class ascend`

### 🔮 Spells & Skill Atlas - Data-driven spell system — define everything in `spells.yml` - Built-in spells: Ember Lance (Mage — AoE fire + Bleed), Warden's Bloom (Cleric — AoE heal + Arcane Ward) - Composable mechanics: damage, heal, apply effect, spawn particles, play sound, send message - Spell Forge for crafting custom spells in-game - Per-class restrictions, level gates, cooldown management - Cast with `/cast` or bound item clicks

### ✨ Effects Engine - Fully stackable, tick-driven status effects defined in `effects.yml` - Built-in: Bleed (5-stack physical DoT with crit particles), Arcane Ward (3-stack magic barrier) - On-apply, on-tick, and on-remove hook pipelines - Harmful and beneficial categories with tag filtering

### 🌀 Fracture Rifts - Dynamic rift events that tear open across your world at runtime - Built-in profiles: Wild, Skeletal Assault, Necrotic Surge, Arcane Tempest and more - Per-profile mob tables, health/damage multipliers, and effect assignments - Named boss encounters with configurable multipliers and boss-exclusive effects - Gateway network — fast-travel nodes discovered and traversed in-world - Spiral auto-generation with `/fracture gateway generate`

### 🗺 Expeditions & Breach Finales - Expedition board with contract tiers, objectives, and time limits - Full party system — form a group, run contracts together, split rewards - Breach Finales — instanced boss arenas triggered from the expedition board - Leaderboards, reward tracks, and quartermaster NPC for loot turn-ins

### 💰 Economy & Marketplace - Dynamic market with supply/demand elasticity, price floors, and caps - Configurable decay rates keep the economy balanced over time - Vault bridge for compatibility with any external economy plugin

### 🤖 AI-Driven NPCs - Citizens integration for quest givers, merchants, and trainers - Neural NPC manager powered by Ollama or any OpenAI-compatible API - Per-NPC conversation memory, greeting templates, and timeout handling

### 🧰 Professions & Adventure Board - Profession ledger with gathering, crafting stations, and profession stats - Adventure board — seasonal objectives, reward tracks, daily/weekly missions

### 💾 Zero-Setup Persistence - Player data saved as JSON files — no external database required - Atomic file writes prevent data corruption on crash - Caffeine in-memory cache for near-zero latency on active players - Revision-based optimistic locking prevents concurrent save conflicts - All data in `plugins/VortexRPG/playerdata/`

### 🛡 Admin Toolkit - `/vortex` hub — forge editors, hot reload, registry inspection, diagnostics - 50+ granular permission nodes - Support dump generator for easy bug reports - PlaceholderAPI expansion for scoreboards, TAB, and chat - Folia-compatible — scales across multi-threaded server environments

## ✦ Requirements

| Requirement | Version | |---|---| | Paper (or fork) | 1. 21+ | | Java | 21+ |

> ⚠ Requires Paper 1. 21+ — Pufferfish, Purpur, and Folia are supported. Plain Spigot is not.

### Optional Integrations | Plugin | Purpose | |---|---| | Citizens 2. 0+ | NPC system (quest givers, merchants, AI companions) | | WorldGuard 7. 0+ | Region-based protection | | PlaceholderAPI | Expose player stats to any compatible plugin | | Vault | Economy bridge to existing server currency |

## ✦ Installation

1. Drop `VortexRPG.jar` into your `plugins/` folder 2. Start or restart your server 3. All configs are generated automatically in `plugins/VortexRPG/` 4. Edit `config.yml`, `spells.yml`, `effects.yml`, `fractures.yml`, and `items.yml` to customize 5. Use `/vortex reload` to hot-reload configs without restarting

## 💬 Support

[!(https://img.shields.io/discord/1234567890?color=5865F2&label=Discord&logo=discord&logoColor=white)](https://discord.gg/4NspeUX6tG)

Join our Discord for bug reports, feature requests, and support: **https://discord.gg/4NspeUX6tG**