** 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:
Players must balance their hunger for power against the very real possibility of their prized weapon shattering in their hands.
Target Audience
✨ 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
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
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
How It Works Each soul on your weapon increases durability consumption. At high soul counts, your weapon breaks extremely fast.
Durability Formula
Durability Lost = Base Damage × (1 + (Souls × Multiplier))
Example with 50 souls and 0.15 multiplier:
Durability Lost = 1 × (1 + (50 × 0.15)) = 8.5x normal
Configuration Options
curse:
enabled: true
durability-multiplier-per-soul: 0.15
instant-break-at-max: true
Alternative: Custom thresholds
custom-durability:
enabled: false
thresholds:
10: 2 2x at 10 souls
25: 4 4x at 25 souls
50: 8 8x at 50 souls
100: 9999 Instant break
How It Works At a configurable soul threshold, the mending enchantment stops working. The curse is too powerful for mending to repair.
Options
Configuration
mending:
enabled: true
disable-threshold: 25 Souls needed to block mending
action: "BLOCK" "BLOCK" or "REMOVE"
prevent-application: true Prevent adding mending via anvil
Tier Progression
| Tier | Souls Required | Name | Ability |
|---|---|---|---|
| 1 | 10 | Awakened | Lifesteal (15% heal) |
| 2 | 25 | Empowered | Speed II on kill (5s) |
| 3 | 50 | Ascended | AOE damage on kill (4 damage, 3.5 radius) |
| 4 | 100 | LEGENDARY | 20% lightning strike chance |
Ability Details
Lifesteal (Tier 1)
Speed on Kill (Tier 2)
AOE Damage (Tier 3)
Lightning Strike (Tier 4)
How It Works Weapons "hunger" for souls. If you don't feed them with kills, they lose souls over time.
Configuration
soul-decay:
enabled: true
check-interval: 60 Check every 60 minutes
decay-amount: 1 Lose 1 soul per check
only-while-online: true Only decay when holding player is online
decay-threshold: 5 Don't decay below 5 souls
grace-period: 120 2 hour grace after last kill
Decay Prevention
ultimatesouls.bypass.decay never decayHow It Works Your weapon develops personality! It sends you messages based on how many souls it contains.
Message Examples
| Soul Count | Example Messages |
|---|---|
| 5+ | "I hunger for more...", "Feed me..." |
| 10+ | "We grow stronger together..." |
| 25+ | "Their screams fuel me...", "I taste their fear..." |
| 50+ | "We are becoming one...", "Your hand, my blade..." |
| 75+ | "BLOOD. SOULS. POWER." |
| 100+ | "I AM ETERNAL", "THEY WILL ALL FALL" |
Kill Whispers 50% chance on kill to receive messages like:
How It Works When a high-soul weapon breaks, it doesn't go quietly. It explodes!
Shatter Effects
Soul Fragments
Effect Progression
| Effect | Souls Required | Description |
|---|---|---|
| Hunger Drain | 25 | Slowly lose food |
| Blindness Flicker | 50 | Brief blindness moments |
| Wither Aura | 75 | Smoke particles around you |
| Soul Sounds | 100 | Eerie ambient sounds |
| Slowness | 150 | Constant slowness effect |
| Nausea | 200 | Random nausea episodes |
Bypass
Players with ultimatesouls.bypass.corruption are immune.
How It Works At 50+ souls, weapons become unstable. Each hit has a chance to "lash out" against the wielder.
Lashout Effects
Chance Calculation
Chance = Base (2%) + (Souls × 0.1%)
At 50 souls: 2% + 5% = 7%
At 100 souls: 2% + 10% = 12%
How It Works Players wielding weapons with 30+ souls become "bounty targets". Other players are notified and rewarded for hunting them.
Features
Compass Tracking Players can use a compass to track the nearest bounty target (optional feature).
How It Works When you kill a player who has a soul weapon equipped, you steal some of their souls!
Configuration
soul-stealing:
enabled: true
steal-percentage: 0.25 Steal 25% of their souls
minimum-victim-souls: 5 Victim needs at least 5 souls
max-steal-per-kill: 10 Maximum 10 souls per kill
require-weapon-equipped: true Victim must hold weapon
How It Works When killed by someone, you receive a "revenge mark" giving you bonus damage against them.
Features
How It Works Your weapon remembers victims. Kill the same player repeatedly for increasing damage bonuses!
Damage Scaling
Bonus = Kills × 5% (capped at 50%)
Kill count 1: +5%
Kill count 5: +25%
Kill count 10+: +50% (max)
Lore Display Weapons show "Blood-Sworn Enemies" in lore with kill counts.
Effect Progression
| Souls | Effects |
|---|---|
| 10 | Red dust particles |
| 25 | Flame particles, glowing |
| 50 | Soul fire, enchant glow |
| 75 | Soul particles, smoke, player aura |
| 100 | Intense particles, lightning crackles |
Name Progression
| Souls | Name Format |
|---|---|
| 0 | Original name |
| 10 | Bloodied {name} |
| 25 | Crimson {name} |
| 50 | Soulbound {name} |
| 75 | {name} of Slaughter |
| 100 | Soulreaver |
| 150+ | Random legendary name |
Legendary Names Pool
Milestone Broadcasts
| Souls | Announcement | Effects |
|---|---|---|
| 10 | "{player}'s weapon has claimed its 10th victim!" | Broadcast |
| 25 | "{player}'s weapon bathes in 25 souls!" | Broadcast + Sound |
| 50 | "{player}'s weapon ascends with 50 souls!" | Broadcast + Title |
| 100 | "LEGENDARY WEAPON FORGED! {player} reaches 100 SOULS!" | Everything + Firework |
How It Works Extract souls from your weapon into portable "Soul Fragments" that can be traded or saved.
Process
/us extract commandFragment Item
How It Works Right-click a soul fragment on a weapon to transfer souls.
Mechanics
How It Works Build a multiblock altar to remove the curse from your weapon while keeping some power.
Structure
[S] [S]
\ | /
[C]--[E]--[C]
/ | \
[S] [S]
E = Enchanting Table (center, interact here)
C = Crying Obsidian (4 pieces)
S = Soul Campfire (4 pieces)
Requirements
Results
Streak Multipliers
| Streak | Multiplier | Message |
|---|---|---|
| 3 | 1.5x | KILLING SPREE! |
| 5 | 2.0x | RAMPAGE! |
| 7 | 2.5x | UNSTOPPABLE! |
| 10 | 3.0x | GODLIKE! |
Mechanics
Mob Soul Effects
| Mob | Drop Rate | Max | Effect |
|---|---|---|---|
| Player | 100% | ∞ | +0.5 damage per soul |
| Zombie | 5% | 20 | +2% lifesteal per soul |
| Skeleton | 4% | 15 | +10% projectile damage per soul |
| Creeper | 3% | 10 | +5% explosion resistance per soul |
| Enderman | 6% | 12 | +1% teleport chance per soul |
| Blaze | 5% | 15 | +1s fire aspect per soul |
| Wither Skeleton | 2% | 10 | +2% wither chance per soul |
| Warden | 80% | 3 | +5% sonic boom chance per soul |
| Ender Dragon | 100% | 1 | Dragon breath AOE ability |
| Wither | 100% | 1 | Wither aura ability |
Requirements
Altar Structure
[N] [N] [N]
[N] [B] [N]
[N] [N] [N]
|
[N] (below)
B = Beacon (center)
N = Netherite Block (9 total)
Sacrifices Required
Available Legendaries
Shadowfang
Bloodmoon's Edge
Voidbringer
Modes
BUFF Mode (Default)
CONFLICT Mode
DYNAMIC Mode
Types
Weekly Rewards (Optional)
rewards:
1st: 64 Diamonds, 16 Netherite
2nd: 32 Diamonds, 8 Netherite
3rd: 16 Diamonds, 4 Netherite
📥 Installation Guide
Requirements
| Requirement | Version |
|---|---|
| Server | Paper 1.21 - 1.21.11 |
| Java | 21 or higher |
| RAM | 512MB+ recommended |
Optional Dependencies
| Plugin | Purpose |
|---|---|
| Vault | Economy for extraction costs |
| PlaceholderAPI | Placeholder support |
| WorldGuard | Region protection |
Installation Steps
Step 1: Download
Download UltimateSouls-1.0.0.jar from the releases page.
Step 2: Install
Place the JAR file in your server's plugins folder.
Step 3: Restart Restart your server (not reload).
Step 4: Configure
Edit plugins/UltimateSouls/config.yml to your preferences.
Step 5: Reload
Use /us reload to apply configuration changes.
🚀 Quick Start Guide
For Server Owners
Minimal Setup (Use Defaults)
Recommended Customization
max-souls based on server styledamage-per-soul for desired power levelbounty-threshold for your player countPvP Server Settings
souls:
player-kills-only: true
max-souls: 150
soul-stealing:
enabled: true
steal-percentage: 0.30
soul-bounty:
enabled: true
bounty-threshold: 25
PvE Server Settings
souls:
player-kills-only: false
max-souls: 100
soul-types:
enabled: true
soul-decay:
enabled: false Less punishing for casual play
For Players
Getting Started
Tips
💻 Complete Command Reference
Player Commands
| Command | Description | Permission |
|---|---|---|
/us help | Display help menu | ultimatesouls.use |
/us info | View held weapon's soul info | ultimatesouls.info |
/us stats | View your statistics | ultimatesouls.stats |
/us stats <player> | View another player's stats | ultimatesouls.stats.others |
/us top | View weapon souls leaderboard | ultimatesouls.leaderboard |
/us top total | View total souls leaderboard | ultimatesouls.leaderboard |
/us top streak | View kill streak leaderboard | ultimatesouls.leaderboard |
/us extract | Extract souls from held weapon | ultimatesouls.extract |
Admin Commands
| Command | Description | Permission |
|---|---|---|
/us reload | Reload configuration | ultimatesouls.reload |
/us set <souls> | Set souls on held weapon | ultimatesouls.set |
/us set <souls> <player> | Set souls on player's weapon | ultimatesouls.set |
/us give <souls> | Add souls to held weapon | ultimatesouls.give |
/us give <souls> <player> | Add souls to player's weapon | ultimatesouls.give |
/us clear | Clear souls from held weapon | ultimatesouls.clear |
/us clear <player> | Clear souls from player's weapon | ultimatesouls.clear |
Command Aliases
/ultimatesouls/us/souls/soulbound/soul🔐 Permission Reference
Basic Permissions
| Permission | Description | Default |
|---|---|---|
ultimatesouls.use | Basic plugin usage, soul collection | true |
ultimatesouls.info | View weapon information | true |
ultimatesouls.stats | View personal statistics | true |
ultimatesouls.stats.others | View other players' stats | op |
ultimatesouls.leaderboard | View leaderboards | true |
ultimatesouls.extract | Extract souls from weapons | true |
ultimatesouls.legendary | Awaken legendary weapons | true |
ultimatesouls.purify | Use purification altars | true |
ultimatesouls.infuse | Infuse soul fragments | true |
Admin Permissions
| Permission | Description | Default |
|---|---|---|
ultimatesouls.admin | All admin commands | op |
ultimatesouls.reload | Reload configuration | op |
ultimatesouls.set | Set weapon souls | op |
ultimatesouls.give | Give souls to weapons | op |
ultimatesouls.clear | Clear weapon souls | op |
ultimatesouls.extract.others | Extract from others' weapons | op |
Bypass Permissions
| Permission | Description | Default |
|---|---|---|
ultimatesouls.bypass | All bypass permissions | false |
ultimatesouls.bypass.gain | Others can't gain souls from killing you | false |
ultimatesouls.bypass.curse | Immune to durability curse | false |
ultimatesouls.bypass.mending | Mending always works | false |
ultimatesouls.bypass.corruption | No corruption effects | false |
ultimatesouls.bypass.decay | Souls never decay | false |
ultimatesouls.bypass.bounty | Never become bounty target | false |
ultimatesouls.bypass.instability | No weapon instability | false |
⚙️ Configuration Guide
Configuration File Location
plugins/UltimateSouls/config.yml
Configuration Sections
Core Settings
prefix: "&8[&9B59B6UltimateSouls&8] "
debug: false
Soul Settings
souls:
max-souls: 100
damage-per-soul: 0.5
player-kills-only: false
require-pvp: false
blocked-gamemodes:
- CREATIVE
- SPECTATOR
Weapon Settings
weapons:
enabled-materials:
- DIAMOND_SWORD
- NETHERITE_SWORD
... etc
overrides:
NETHERITE_SWORD:
max-souls: 150
damage-per-soul: 0.75
Feature Toggles
Every extended feature has enabled: true/false:
soul-tiers:
enabled: true
soul-decay:
enabled: true
soul-whispers:
enabled: true
Set to false to disable any feature
Storage Settings
storage:
type: "PDC" PDC, SQLITE, or MYSQL
sqlite:
file: "ultimatesouls_data.db"
mysql:
host: "localhost"
port: 3306
database: "ultimatesouls"
username: "root"
password: ""
🏗️ Multiblock Structures
Purification Altar
Visual Layout
Top View:
[S] [S]
\ | /
[C]--[E]--[C]
/ | \
[S] [S]
Materials
| Block | Material | Count |
|---|---|---|
| E | Enchanting Table | 1 |
| C | Crying Obsidian | 4 |
| S | Soul Campfire | 4 |
Building Instructions
Legendary Awakening Altar
Visual Layout
Top View:
[N] [N] [N]
[N] [B] [N]
[N] [N] [N]
Side View:
[B]
[N]
Materials
| Block | Material | Count |
|---|---|---|
| B | Beacon | 1 |
| N | Netherite Block | 9 |
Building Instructions
PlaceholderAPI Placeholders
| Placeholder | Description |
|---|---|
%ultimatesouls_souls% | Souls on held weapon |
%ultimatesouls_max_souls% | Max souls for weapon |
%ultimatesouls_tier% | Current tier name |
%ultimatesouls_tier_number% | Current tier number |
%ultimatesouls_total_collected% | Total souls collected |
%ultimatesouls_total_kills% | Total kills |
%ultimatesouls_best_streak% | Best kill streak |
%ultimatesouls_current_streak% | Current streak |
%ultimatesouls_is_bounty% | "true" or "false" |
%ultimatesouls_is_legendary% | "true" or "false" |
%ultimatesouls_legendary_type% | Legendary name or empty |
%ultimatesouls_rank_souls% | Leaderboard rank |
%ultimatesouls_rank_streak% | Streak rank |
%ultimatesouls_damage_bonus% | Bonus damage value |
❓ Frequently Asked Questions
General Questions
Q: Does this work on Spigot? A: No, UltimateSouls requires Paper or a Paper fork (Purpur, Pufferfish).
Q: Will my weapons lose data on server restart? A: No, all data is stored persistently using PDC (on the item itself).
Q: Can I disable specific features?
A: Yes, every feature has enabled: true/false in config.
Q: Does this work in creative mode? A: By default, creative mode is blocked. You can change this in config.
Technical Questions
Q: How is data stored? A: Weapon data uses PersistentDataContainer (PDC), stored on the item. Player statistics use SQLite/MySQL.
Q: Is it async? A: Database operations are async. Event handling is sync for safety.
Q: Will it lag my server? A: No, the plugin is optimized. Visual effects can be disabled if needed.
Q: Can I use MySQL? A: Yes, configure the mysql section in config.yml.
Gameplay Questions
Q: Can I transfer souls between weapons? A: Yes, use extraction then infusion.
Q: How do I remove the curse? A: Build and use the Purification Altar.
Q: Why does my mending not work? A: At 25+ souls, mending is blocked by the curse.
Q: How do I become legendary? A: Reach 100 souls, build the altar, and complete the awakening ritual.
Troubleshooting
Q: Souls aren't being collected! A: Check: valid weapon, correct world, correct gamemode, has permission.
Q: Config changes don't apply!
A: Use /us reload after editing config.yml.
🙏 Credits & Support
Author geturplugins
Support
Special Thanks
🎮 Thank You for Using UltimateSouls!
Made with ❤️ by geturplugins
**