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 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
```yaml
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
```

---

3. 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
```yaml
mending:
enabled: true
disable-threshold: 25 Souls needed to block mending
action: "BLOCK" "BLOCK" or "REMOVE"
prevent-application: true Prevent adding mending via anvil
```

---

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

---

5. Soul Decay

How It Works
Weapons "hunger" for souls. If you don't feed them with kills, they lose souls over time.

Configuration
```yaml
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

---

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

---

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

---

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

---

9. 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%
```

---

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

---

11. Soul Stealing

How It Works
When you kill a player who has a soul weapon equipped, you steal some of their souls!

Configuration
```yaml
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
```

---

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

---

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

---

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

---

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

---

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

---

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

---

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

---

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

---

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

---

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

---

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

---

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

---

24. 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)
```yaml
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
```yaml
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
```yaml
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
```yaml
prefix: "&8[&9B59B6UltimateSouls&8] "
debug: false
```

Soul Settings
```yaml
souls:
max-souls: 100
damage-per-soul: 0.5
player-kills-only: false
require-pvp: false
blocked-gamemodes:
- CREATIVE
- SPECTATOR
```

Weapon Settings
```yaml
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`:
```yaml
soul-tiers:
enabled: true

soul-decay:
enabled: true

soul-whispers:
enabled: true

Set to false to disable any feature
```

Storage Settings
```yaml
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
- **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**

[![Discord](https://img.shields.io/badge/Discord-Join Us-7289DA?style=for-the-badge&logo=discord)](https://discord.gg/xctckUQukB)