Logo
UltimateSouls
PluginLicenseRef-All-Rights-Reserved

UltimateSouls

When you kill your enemies you capture their souls and become strong ......

32
Downloads
0
Followers
3 months ago
Updated
📦
1
Versions
game-mechanicsmobsutilitypaperpurpur
Download Latestv1.0.0View on Modrinth

📖About 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

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
  1. Curse System (Durability Penalty)

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
  1. Mending Restriction

How It Works
At a configurable soul threshold, the mending enchantment stops working. The curse is too powerful for mending to repair.

Options

  • BLOCK: Mending stops working but stays on the item
  • REMOVE: Mending is forcibly removed from the item

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
  1. Soul Tiers & Abilities

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)

  • Heals player for percentage of damage dealt
  • Works on every hit
  • Configurable percentage

Speed on Kill (Tier 2)

  • Grants Speed potion effect after kills
  • Configurable level and duration
  • Stacks refresh duration

AOE Damage (Tier 3)

  • Deals damage to nearby enemies on kill
  • Creates particle explosion
  • Configurable radius and damage

Lightning Strike (Tier 4)

  • Chance to strike lightning on hit
  • Can deal real damage or just visual
  • Configurable chance
  1. Soul Decay

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

  • Kill enemies regularly to reset the timer
  • Players with ultimatesouls.bypass.decay never decay
  • Weapons below threshold don't decay
  1. Soul Whispers

How 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:

  • "Yes... YES!"
  • "Another offering..."
  • "Their soul is MINE!"
  1. Soul Shatter

How It Works
When a high-soul weapon breaks, it doesn't go quietly. It explodes!

Shatter Effects

  1. Explosion: Visual explosion at weapon location
  2. Wielder Damage: Player takes damage (configurable)
  3. Soul Scatter: Souls drop as collectible fragments
  4. Nearby Alert: Players nearby see a message

Soul Fragments

  • Drop as glowing items
  • Can be picked up by anyone
  • Used with Soul Infusion system
  • Despawn after configurable time
  1. Corruption Effects

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.

  1. Soul Instability

How It Works
At 50+ souls, weapons become unstable. Each hit has a chance to "lash out" against the wielder.

Lashout Effects

  • Damage: Player takes 3 damage
  • Lightning: Visual lightning effect
  • Particles: Soul fire burst
  • Sound: Thunder crack

Chance Calculation

Chance = Base (2%) + (Souls × 0.1%)

At 50 souls: 2% + 5% = 7%
At 100 souls: 2% + 10% = 12%
  1. Bounty System

How It Works
Players wielding weapons with 30+ souls become "bounty targets". Other players are notified and rewarded for hunting them.

Features

  • Announcement: Server-wide broadcast when someone becomes bounty
  • Glowing Effect: Bounty targets glow red
  • Particle Trail: Flame particles follow bounty targets
  • Rewards: 2x souls + 5 bonus for killing bounties

Compass Tracking
Players can use a compass to track the nearest bounty target (optional feature).

  1. Soul Stealing

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
  1. Revenge Mark System

How It Works
When killed by someone, you receive a "revenge mark" giving you bonus damage against them.

Features

  • Damage Bonus: +20% damage against your killer
  • Duration: 30 minutes
  • Stacking: Up to 3 stacks (+30% total with stacking)
  • Satisfaction: Special message when you get revenge
  1. Nemesis System

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.

  1. Cursed Visual Effects

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
  1. Dynamic Weapon Naming

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

  • Eternal Reaper
  • Voidbringer
  • Bloodmoon's Edge
  • Shadowfang
  • Damnation
  • Soulrender
  • Oblivion
  1. Kill Announcements

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
  1. Soul Extraction

How It Works
Extract souls from your weapon into portable "Soul Fragments" that can be traded or saved.

Process

  1. Hold your soul weapon
  2. Use /us extract command
  3. Pay entropy tax (30% souls lost)
  4. Receive Soul Fragment item

Fragment Item

  • Material: Echo Shard
  • Glowing effect
  • Shows soul count in lore
  • Can be infused into other weapons
  1. Soul Infusion

How It Works
Right-click a soul fragment on a weapon to transfer souls.

Mechanics

  • Efficiency: Only 75% of fragment souls transfer
  • Limit: Maximum 50 infused souls per weapon
  • Stacking: Can infuse multiple times up to limit
  1. Purification Altar

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

  • 16 Diamonds
  • 1 Nether Star
  • 1 Totem of Undying
  • 30 seconds ritual time

Results

  • Soul Retention: Keep 50% of damage bonus
  • Curse Removal: No more durability penalty
  • Corruption Clear: No more negative effects
  • Legendary Lost: Removes legendary status
  1. Kill Streaks

Streak Multipliers

Streak Multiplier Message
3 1.5x KILLING SPREE!
5 2.0x RAMPAGE!
7 2.5x UNSTOPPABLE!
10 3.0x GODLIKE!

Mechanics

  • Timeout: 60 seconds between kills
  • Reset: Death resets streak
  • Action Bar: Shows current streak and multiplier
  1. Soul Types

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
  1. Legendary Awakening

Requirements

  • 100+ souls on weapon
  • Beacon altar structure
  • Sacrifice materials

Altar Structure

    [N] [N] [N]
    [N] [B] [N]
    [N] [N] [N]
        |
       [N] (below)

B = Beacon (center)
N = Netherite Block (9 total)

Sacrifices Required

  • 3 Nether Stars
  • 1 Dragon Egg
  • 2 Totems of Undying

Available Legendaries

Shadowfang

  • Ability: Shadow Step
  • Effect: 3 seconds invisibility on kill
  • Damage Multiplier: 1.5x

Bloodmoon's Edge

  • Ability: Blood Frenzy
  • Effect: +10% damage per kill (stacks 5x, 10s)
  • Damage Multiplier: 1.3x

Voidbringer

  • Ability: Void Rift
  • Effect: 20% chance AOE void damage on kill
  • Damage Multiplier: 1.4x
  1. Soul Resonance

Modes

BUFF Mode (Default)

  • Nearby soul weapons strengthen each other
  • +5% damage per nearby weapon (max +25%)

CONFLICT Mode

  • Nearby soul weapons weaken each other
  • -10% damage per nearby weapon (max -40%)

DYNAMIC Mode

  • Higher-soul weapon drains from lower
  • Dominant weapon: +15% buff
  • Submissive weapon: -10% debuff
  1. Leaderboards

Types

  1. Weapon Souls: Most souls on a single weapon
  2. Total Souls: Total souls ever collected
  3. Kill Streaks: Best kill streak achieved

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)

  1. Install plugin
  2. Restart server
  3. Done! All features enabled with balanced defaults

Recommended Customization

  1. Adjust max-souls based on server style
  2. Set damage-per-soul for desired power level
  3. Configure bounty-threshold for your player count
  4. Customize announcement messages

PvP 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

  1. Get a sword or axe
  2. Kill mobs or players
  3. Watch souls accumulate
  4. Enjoy increased damage!

Tips

  • Extract souls before weapon breaks to save them
  • Purify when you reach max souls
  • Watch durability - high souls = fast breaking
  • Hunt bounties for massive soul gains

💻 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

  1. Place Enchanting Table in center
  2. Place Crying Obsidian on N/S/E/W sides
  3. Place Soul Campfires in corners
  4. Shift+Right-click Enchanting Table with soul weapon

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

  1. Place Netherite Block as base (below beacon)
  2. Place Beacon on top
  3. Surround beacon with 8 Netherite Blocks
  4. Shift+Right-click Beacon with 100+ soul weapon
  5. Wait 60 seconds for awakening

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.

Q: Getting errors in console!
A: Enable debug mode, check the error, report on Discord.

🙏 Credits & Support

Author
geturplugins

Support

Special Thanks

  • Paper team for the amazing API
  • Community members for feedback and suggestions

License
ARR License - All Rights Reserved

🎮 Thank You for Using UltimateSouls!

Made with ❤️ by geturplugins

Discord
**