Soul Provenance

# Soul Provenance

**Soul Provenance** is a Warlock immersion and roleplaying addon for WoW Classic that gives every Soul Shard a history.

When a Warlock creates a Soul Shard using **Drain Soul**, Soul Provenance remembers the creature whose soul was captured and permanently records its provenance.

That soul can then remain imprisoned for days, months, or years; be sacrificed to Warlock magic; power summoned demons; be reclaimed when a demon is lost; and gradually develop its own history inside the **Ledger of the Damned**.

Soul Provenance is primarily an RP, flavor, and collection addon. It does not alter combat mechanics or provide gameplay advantages.

---

# Features

## Soul Shard Provenance

Every newly harvested Soul Shard can remember:

- Soul number
- Original victim
- Harvest date and time
- Harvest location
- Creature classification
- Soul potency
- Temperament
- Current spiritual state
- Age title
- Current location
- Final disposition
- Demon summon history
- Reclamation history
- Soul biography

Hovering a tracked Soul Shard displays its provenance directly in the normal item tooltip.

---

## The Ledger of the Damned

Use the minimap button or:

`/souls`

to open the graphical Ledger.

The Ledger provides:

- Searchable soul history
- Imprisoned / Consumed filtering
- Boss / Elite / Rare / Common filtering
- Soul potency
- Harvest timestamps
- Current status
- Detailed soul inspection
- Soul biography
- Final disposition
- Reclamation history
- Soul whispers
- Earned titles
- Oldest surviving soul
- Collection statistics

---

## Permanent Soul Numbers

Every new soul receives a sequential Soul Number.

For example:

**Soul #20 — Plagued Ghoul**

That Soul Number belongs to the soul itself rather than to a particular bag slot.

Moving, sorting, banking, or withdrawing a shard does not change its identity.

---

# Demon Soul Reclamation

Some Warlock demon summons consume a Soul Shard.

Soul Provenance remembers which soul was used to summon the demon.

If WoW later refunds that shard when the minion is lost, the refunded physical shard may have a completely new item GUID.

Soul Provenance detects this and rebinds the **existing soul record** to the new physical shard.

For example:

Soul #20  
Captured from Plagued Ghoul

→ Summon Succubus  
→ Reclaimed  
→ Summon Incubus  
→ Reclaimed  
→ Summon Felhunter  
→ Reclaimed

It remains **Soul #20** throughout the entire history.

Reclamation does **not**:

- Create a new soul
- Increase Total Harvested
- Increase Unique Victims
- Allocate another Soul Number

The original victim, harvest date, temperament, age, title, and provenance remain intact.

Recognized minion summons include:

- Imp
- Voidwalker
- Succubus
- Incubus
- Felhunter
- Felguard
- Infernal
- Doomguard / Ritual of Doom

---

# Soul Temperament

Temperament represents the soul's permanent personality.

A temperament does not normally change.

Possible temperaments include:

- Defiant
- Terrified
- Furious
- Despondent
- Scheming
- Silent
- Broken
- Unrepentant

Example:

**Temperament:** Defiant

---

# Soul State

State represents the soul's current spiritual condition.

Unlike Temperament, State changes as the soul ages.

Age	State
Under 15 minutes	Freshly Bound
15 minutes – 6 hours	Agitated
6 hours – 1 day	Restless
1 – 7 days	Settling
7 – 30 days	Subdued
30 – 90 days	Dormant
90 days – 1 year	Fading
1+ year	Nearly Silent
Consumed	Spent

This allows combinations such as:

**Temperament:** Furious  
**State:** Subdued

---

# Soul Potency

Soul potency is influenced by the importance of the creature captured.

Creature	Potency
Normal	Common
Rare / Elite	Potent
Rare Elite	Greater
World Boss	Ancient

The Ledger displays potency visually using Soul Shard icons.

---

# Earned Soul Titles

Individual souls can earn titles based on what happens to them.

Examples include:

- The Twice-Reclaimed
- The Returned
- The Oft-Sacrificed
- The Indestructible
- Many-Mastered
- Demon-Bound
- The Long-Imprisoned
- The Unquiet
- The Forgotten
- The Fallen Tyrant

A completely ordinary soul can therefore eventually become one of the most notable entries in your collection.

---

# Soul Biography

Each soul maintains a chronological history.

Example:

**Soul #20 — Plagued Ghoul**  
*The Oft-Sacrificed*

- Captured by Drain Soul
- Offered to summon Succubus
- Reclaimed from lost minion
- Offered to summon Succubus
- Reclaimed from lost minion
- Offered to summon Incubus
- Reclaimed from lost minion
- Offered to summon Felhunter
- Reclaimed from lost minion

The Biography can be viewed from the soul detail panel in the Ledger.

---

# Trophy Cabinet

The **Trophies** page contains particularly notable souls.

A soul may qualify as a Trophy by meeting conditions such as:

- Rare
- Elite
- Rare Elite
- World Boss
- Reclaimed at least 3 times
- Powered at least 3 different demon types
- Remained imprisoned for at least 30 days

This means a normal creature can eventually become a Trophy through its history alone.

---

# Grimoire

The **Grimoire** page contains collection statistics such as:

- Total souls harvested
- Souls currently imprisoned
- Souls consumed
- Unique victims
- Demon summonings
- Favorite demon
- Different demon types fed
- Most reclaimed soul
- Longest imprisonment
- Trophy count
- Elite / Rare souls
- Boss souls
- Favorite hunting ground

---

# Soul Whispers

Imprisoned souls may occasionally speak when the Ledger is opened.

Whispers are influenced by:

- Temperament
- Age
- Reclamation history
- Demon history
- Current state

Whispers are intentionally rate-limited so they remain unusual rather than becoming chat spam.

---

# Achievements

Soul Provenance includes its own addon-only achievements.

These are purely for collection and RP purposes.

## The First of Many

**Requirement:** Harvest your first recorded soul.

---

## A Hundred Screams

**Requirement:** Harvest 100 total souls.

Consumed souls still count toward the historical total.

Reclaimed demon shards do not count as additional harvests.

---

## A Thousand Screams

**Requirement:** Harvest 1,000 total souls.

---

## Collector of the Damned

**Requirement:** Capture souls from 100 unique victim names.

Multiple souls from the same creature name count as one unique victim type.

---

## Know Your Place

**Requirement:** Successfully capture a soul classified as a World Boss.

---

## Soul Hoarder

**Requirement:** Have 20 souls simultaneously imprisoned.

Consumed souls do not count toward this achievement.

---

## You Live Here Now

**Requirement:** Keep one soul imprisoned for at least 30 days.

The soul must still be imprisoned to qualify.

---

## Forgotten Prisoner

**Requirement:** Keep one soul imprisoned for at least 365 days.

The soul must still survive in the collection.

---

# Achievement Notifications

When an achievement is unlocked, Soul Provenance displays:

- A chat notification
- A short Warlock-themed banner near the top of the screen

For example:

**ACHIEVEMENT UNLOCKED — THE FIRST OF MANY**

Achievement notifications do not modify gameplay.

---

# Minimap Button

Soul Provenance adds a circular Soul Shard button around the minimap.

### Left-click

Open the **Ledger**.

### Right-click

Open the **Grimoire**.

### Shift + Left-click

Open **Trophies**.

### Drag

Move the button around the minimap.

The minimap position is saved between sessions.

---

# Slash Commands

## `/souls`

Opens or closes the graphical **Ledger of the Damned**.

---

## `/spv stats`

Displays a summary of the Soul Provenance collection in chat.

Useful for quickly checking total harvested, imprisoned, consumed, and other statistics.

---

## `/spv ledger 25`

Displays a text-based version of recent Ledger entries.

The number controls how many entries are displayed.

Example:

`/spv ledger 10`

---

## `/spv achievements`

Displays Soul Provenance achievements and their current locked/unlocked status.

---

## `/spv lastuse`

Displays the most recently detected Soul Shard-consuming Warlock spell.

This is primarily a diagnostic command.

Example output may identify:

- Create Healthstone
- Create Soulstone
- Summon Succubus
- Summon Incubus
- Soul Fire
- Shadowburn

---

## `/spv minimap`

Shows or hides the Soul Provenance minimap button.

This is also useful if the minimap button is accidentally hidden.

---

## `/spv reclaim`

Attempts to manually repair a reclaimed demon shard.

This is normally unnecessary because reclamation is automatic.

The command is useful when an older addon version failed to recognize a refunded shard.

If exactly one untracked Soul Shard is in your bags, Soul Provenance can attempt to bind the most appropriate consumed demon soul to it.

---

## `/spv reclaim <SoulNumber>`

Explicitly binds an untracked refunded shard back to a particular consumed soul.

Example:

`/spv reclaim 20`

For safety, the addon will refuse to guess if multiple untracked Soul Shards are present.

---

## `/spv notices`

Enables or disables Warlock-themed ritual notifications.

These include messages such as:

**SOUL #20 RECLAIMED**

or:

**SOUL #20 OFFERED — SUMMON INCUBUS**

---

## `/spv testnotice`

Displays a harmless test notification.

This allows you to verify that chat messages and the top-center notification banner are functioning without changing any soul or achievement state.

---

## `/spv backup`

Creates a manual safety snapshot of the Soul Provenance database.

This is useful before addon updates or major testing.

---

## `/spv backupinfo`

Displays information about the currently stored Soul Provenance backup.

---

## `/spv rescan`

Immediately rescans the player's bags for Soul Shards.

Normally the addon does this automatically.

This command is primarily intended for troubleshooting.

---

## `/spv diag`

Displays diagnostic information about the shard tracking system.

This can include:

- Physical Soul Shards currently carried
- Shards matched to known provenance
- Untracked candidate shards
- Pending Drain Soul deaths
- Demon reclamation state

If you are reporting a tracking problem, the output of `/spv diag` is particularly useful.

---

## `/spv debug`

Enables or disables verbose debugging information.

This is primarily intended for troubleshooting and addon development.

Normal users generally do not need it enabled.

---

# Persistent Data

Soul Provenance stores its collection using WoW SavedVariables.

The primary database is:

`SoulProvenanceDB`

Soul history is stored separately from the addon installation folder.

This means updating or replacing the files inside:

`Interface/AddOns/SoulProvenance`

does **not** erase your Ledger.

Your collection remains in WoW's WTF / SavedVariables data.

Soul Provenance also maintains an additional backup database:

`SoulProvenanceBackupDB`

For additional safety, periodically use:

`/spv backup`

---

# Updating the Addon

Replacing the Soul Provenance addon folder with a newer version will not normally remove your collection.

Do **not** delete your WoW SavedVariables / WTF data if you want to retain your Ledger.

For particularly valuable collections, making an occasional backup of the Soul Provenance SavedVariables file is recommended.

---

# Important Notes

Soul Provenance is designed for immersion, roleplaying, and collection.

The addon does not:

- Change Soul Shard mechanics
- Create additional Soul Shards
- Alter Drain Soul
- Modify Warlock spells
- Provide combat automation
- Affect loot or rewards

It simply remembers the stories of the souls your Warlock has already taken.

---

*"Death changes nothing. The Ledger remembers."*