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

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

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

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

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

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

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!"

Soul Shatter

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

Shatter Effects

Explosion: Visual explosion at weapon location
Wielder Damage: Player takes damage (configurable)
Soul Scatter: Souls drop as collectible fragments
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

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.

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%

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).

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

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

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.

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

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

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

Soul Extraction

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

Process

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

Fragment Item

Material: Echo Shard
Glowing effect
Shows soul count in lore
Can be infused into other weapons

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

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

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

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

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

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

Leaderboards

Types

Weapon Souls: Most souls on a single weapon
Total Souls: Total souls ever collected
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)

Install plugin
Restart server
Done! All features enabled with balanced defaults

Recommended Customization

Adjust max-souls based on server style
Set damage-per-soul for desired power level
Configure bounty-threshold for your player count
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

Get a sword or axe
Kill mobs or players
Watch souls accumulate
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

Place Enchanting Table in center
Place Crying Obsidian on N/S/E/W sides
Place Soul Campfires in corners
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

Place Netherite Block as base (below beacon)
Place Beacon on top
Surround beacon with 8 Netherite Blocks
Shift+Right-click Beacon with 100+ soul weapon
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

Discord: https://discord.gg/xctckUQukB

Special Thanks

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

🎮 Thank You for Using UltimateSouls!

Made with ❤️ by geturplugins

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

License ARR License - All Rights Reserved

Совместимость

Minecraft: Java Edition

Платформы

Поддерживаемые окружения

Ссылки

Создатели

Детали