UltimateSouls

** UltimateSouls - Complete Documentation Package --- 📖 Plugin Description Overview **UltimateSouls** is a premium-quality, feature-rich Minecraft Paper plugin that introduces a revolutionary soul-based weapon progression system. Transform ordinary weapons into living entities that grow stronger with each kill, unlock devastating abilities, and eventually awaken into legendary artifacts with unique powers. The Concept In UltimateSouls, every kill matters. When you slay an enemy with a compatible weapon, their soul is absorbed into your blade. Each soul increases your weapon's power, but comes with a terrible price - the curse grows stronger. Your weapon becomes increasingly unstable, consuming durability at alarming rates, blocking mending, and afflicting you with corruption effects. This creates a compelling **risk vs. reward** dynamic: - **More souls = More power** (increased damage, abilities, legendary potential) - **More souls = More risk** (faster breaking, corruption effects, instability) Players must balance their hunger for power against the very real possibility of their prized weapon shattering in their hands. Target Audience - **PvP Servers**: Perfect for faction, KitPvP, and survival PvP servers - **Survival Servers**: Adds depth to the PvE experience - **RPG Servers**: Integrates seamlessly with RPG-style gameplay - **Competitive Servers**: Leaderboards and bounty systems drive competition --- ✨ Feature Summary Core Features | Feature | Description | Configurable | |---------|-------------|--------------| | **Soul Collection** | Absorb souls from kills into your weapon | ✅ | | **Damage Scaling** | Each soul increases attack damage | ✅ | | **Curse System** | Souls increase durability consumption | ✅ | | **Mending Restriction** | High souls block mending enchantment | ✅ | | **Weapon Support** | Swords, axes, tridents, mace | ✅ | | **Per-Weapon Config** | Different settings per weapon type | ✅ | Extended Features (All Toggleable) | Feature | Description | Default | |---------|-------------|---------| | **Soul Tiers** | Unlock abilities at soul milestones | Enabled | | **Soul Decay** | Weapons lose souls over time without kills | Enabled | | **Soul Whispers** | Weapon "speaks" to the player | Enabled | | **Soul Shatter** | Explosive weapon break with soul scattering | Enabled | | **Corruption Effects** | Negative effects at high soul counts | Enabled | | **Soul Instability** | Random weapon lashouts | Enabled | | **Bounty System** | High-soul players become targets | Enabled | | **Soul Stealing** | Steal souls from killed players | Enabled | | **Revenge Marks** | Damage bonus against your killer | Enabled | | **Nemesis System** | Bonus damage vs repeated victims | Enabled | | **Cursed Visuals** | Particles and effects on weapons | Enabled | | **Dynamic Naming** | Weapon names change with souls | Enabled | | **Kill Announcements** | Broadcast milestone achievements | Enabled | | **Soul Extraction** | Extract souls into items | Enabled | | **Soul Infusion** | Transfer souls between weapons | Enabled | | **Purification Altar** | Remove curse, keep some power | Enabled | | **Kill Streaks** | Chain kills for multipliers | Enabled | | **Soul Types** | Different mobs give different bonuses | Enabled | | **Legendary Awakening** | Transform into unique legendaries | Enabled | | **Soul Resonance** | Nearby soul weapons interact | Enabled | | **Leaderboards** | Competitive rankings | Enabled | Technical Features | Feature | Description | |---------|-------------| | **PDC Storage** | Data stored on items (no database needed) | | **SQLite/MySQL** | Optional database for stats/leaderboards | | **Full API** | Developer API with custom events | | **PlaceholderAPI** | Full placeholder support | | **Vault Integration** | Economy support for features | | **WorldGuard** | Region protection compatibility | | **Async Operations** | Database operations are async | | **Performance Optimized** | Efficient event handling | --- 📚 Detailed Feature Documentation 1. Soul Collection System How It Works When you kill an entity while holding a valid soul weapon, you have a chance to absorb their soul. The soul is permanently bound to that weapon until extracted or lost. Configuration Options ```yaml souls: max-souls: 100 Maximum souls per weapon damage-per-soul: 0.5 Damage increase per soul player-kills-only: false Only count player kills require-pvp: false Require PvP enabled blocked-gamemodes: Gamemodes that can't gain souls - CREATIVE - SPECTATOR ``` Soul Gain Formula ``` Base Souls = 1 (per kill) Streak Multiplier = varies (1.0x - 3.0x) Bounty Multiplier = 2.0x (if target was bounty) Bounty Bonus = +5 (flat bonus for bounty kills) Stolen Souls = 25% of victim's weapon souls Total Souls = (Base × Streak × Bounty) + Bounty Bonus + Stolen ``` --- 2. Curse System (Durability Penalty) How It Works Each soul on your weapon i