SpiritLinks

SpiritLinks

MMO-style "ghost run" death flow for Minecraft. Die, become a ghost, follow a clear death marker back, revive safely.

---

Why SpiritLinks?

I wanted a death system that feels closer to an MMO:

• Death should be a recoverable journey, not a permanent gear/XP loss
• No more losing your run to lava, despawn timers, or chaotic recovery
• A consistent way for players to return to safety when revived and keep death/revive behavior centralized and predictable

SpiritLinks turns death into a guided "ghost run" where the player is clearly directed back to their death location and can recover without the usual Minecraft death frustration.

---

What It Does

When you die:

• You respawn as a ghost (visual effects + ghost-like movement)
• A death marker shows you where you died (readable from far away)
• You follow the marker back and revive once you reach the correct location
• Your full inventory, armor, offhand, and XP are snapshot-restored exactly as they were

The goal is simple: death becomes a guided recovery loop, not a punishment spiral.

---

How to Play

After Death

• You enter ghost mode — you can fly, you're invisible with a glowing outline, and mobs ignore you
• A HUD death marker and breadcrumb particle trail guide you back to where you died

Revival Options

• Near your corpse (within 10 blocks): left or right click anywhere to revive on the spot
• Spirit Healer NPC: right-click a marked healer entity to revive at their location (optional XP/durability cost)
• Cemetery command: /spirit res to revive at the server's set cemetery point (optional XP cost)

After Revival

• Your inventory, armor, offhand, and XP are fully restored from the death snapshot
• You get a brief invulnerability period (default 10 seconds)
• Nearby mob aggro is cleared so you don't immediately die again

---

Ghost State

Feature	Detail
Movement	Flight enabled, fall damage suppressed
Visuals	Invisibility + glowing outline + night vision
Audio	Optional ambient ghost music loop
Protection	Can't take damage, can't pick up items, can't break/place blocks
Mode	Adventure mode (prevents griefing while ghost)

If a ghost player somehow switches to Creative mode (via commands), they're forced back to Adventure. No escaping ghost state.

---

Wayfinding

• HUD Death Marker — on-screen indicator showing your death location, distance, and dimension. Configurable label, icon, and offset.
• Breadcrumb Trail — END_ROD particles stepping toward the nearest Spirit Healer. Spacing, distance, and sync interval are configurable.
• Rescue Prompt — when you're close enough to your death point, a title message appears: "You can revive here — click anywhere."

---

Spirit Healers

Spirit Healers are admin-placed NPC entities that ghosts can interact with to revive.

Creating a Healer

• Mark an existing entity: Sneak + right-click any living entity with the configured item (default: wooden shovel)
• Spawn a new one: /spirit spawnhealer <type> [Name...] — supports giant, golem, guardian, elder_guardian, villager, polar_bear
• Remove: Sneak + right-click again, or /spirit removehealer

Healers are invulnerable, persistent, and marked with a custom name. When a ghost right-clicks a healer, they get a confirmation prompt with the cost breakdown. Type /spirit healaccept or /spirit healdeny to respond.

---

Costs & Scaling

All costs are optional and configurable:

• Flat revive cost — XP levels deducted from your death snapshot (default: 5 levels)
• Scaling costs — each additional resurrection within a time window (default: 15 minutes) increases the cost (base 5, +3 per death, max 30)
• Durability damage — items in your snapshot take a configurable percentage of durability loss when using a Spirit Healer
• RPG XP penalty (with LucsemporiumRPG) — corpse revive costs 2-10% of your level's RPG XP, Spirit Healer costs 5-20%. XP never drops below your current level floor.

Set cost.type to "none" to disable all costs.

---

Revive Protection

After reviving, players get a configurable invulnerability period (default: 10 seconds):

• No damage from any source
• Can't break or place blocks
• Can't attack entities
• Can eat food, drink potions, and use milk (so you're not helpless)
• Nearby mob aggro is cleared in a 32-block radius
• Persists through logout/restart (saved to disk)

---

Quick Start (Admin)

1. Set a Cemetery

Stand where you want the revive point:

/spirit setcemetery

Control behavior with config:

• respawnPolicy: same_world — cemetery used only if death was in the same dimension
• respawnPolicy: always_cemetery — always teleport to cemetery

2. Create a Spirit Healer

/spirit spawnhealer villager Spirit Healer

Or mark any existing entity: Sneak + right-click with a wooden shovel.

3. Test the Flow

• Die somewhere
• Respawn as a ghost
• Follow the death marker / breadcrumb trail
• Revive near your corpse (click) or at the healer (right-click)
• Check that your inventory is fully restored

---

Commands

Command	Description
/spirit setcemetery	Set cemetery at your location (OP)
/spirit clearcemetery	Remove cemetery (OP)
/spirit res	Revive at cemetery (costs XP if configured)
/spirit status	Show your ghost status and death location
/spirit spawnhealer <type> [Name]	Spawn a Spirit Healer (OP)
/spirit removehealer	Remove nearest healer (OP)
/spirit healaccept	Accept healer revive offer
/spirit healdeny	Decline healer revive offer

Aliases: /ghost, /reclaim

---

Persistence

Everything survives server restarts:

• Ghost state and inventory snapshots are saved to world data
• Revive protection timers are persisted immediately when set
• Spirit Healer registrations are stored by UUID
• Cemetery location is saved per-server
• Auto-save runs periodically (crash-safe)

---

Compatibility

Minecraft	1.20.1
Forge	47.2.20 or newer
Java	17 or newer
Mohist / Arclight	Fully supported
Curios API	Curio items included in death snapshots (via reflection)
LucsemporiumRPG	Optional RPG XP death penalties on resurrection
CustomNPCs	Spirit Healers can be CustomNPC entities

SpiritLinks works standalone with zero dependencies beyond Forge.

---

Installation

Client (singleplayer or joining a modded server)

1. Install Minecraft Forge 1.20.1
2. Download spiritlinks-1.20.1-2.0.0.jar
3. Put it in your mods/ folder
4. Launch Minecraft

Dedicated Server

1. Set up a Forge 1.20.1 server (or Mohist/Arclight)
2. Put spiritlinks-1.20.1-2.0.0.jar in your mods/ folder
3. Restart the server
4. Players need the same mod version on their clients

Config generates on first run at spiritlinks-common.toml.

---

License & Credit

• License: All Rights Reserved
• Author: Luc Bellefeuille