💀 SoulLock Plugin

A thrilling Minecraft Paper plugin where death has consequences! Lock players' souls and challenge others to rescue them.

---

🎮 What is SoulLock?

SoulLock is an immersive Paper plugin that transforms death mechanics in Minecraft. When a player dies, their soul is locked—frozen until another player places their player head on the ground to revive them. It's perfect for:

• 🏰 Survival servers with high stakes
• 👥 Multiplayer co-op adventures
• 🎪 Creative minigames and roleplay servers
• ⚔️ PvP challenges with soul mechanics

---

✨ Features

💀 Soul Lock System

• 🪦 When a player dies, their soul is automatically locked
• 👤 Each player can only have ONE active soul lock at a time
• 🔐 Locked souls are stored by UUID (unique per player)
• 💾 All data is persisted to disk and survives server restarts

👻 Spectator Mode (or Kick)

When a locked player joins the server:

• 👁️ SPECTATOR MODE (default): Player enters spectator mode but can still move around and explore
• 🚫 KICK MODE (optional): Player is immediately kicked from the server
• ⚙️ Choose which mode in config.yml

💔 Restrictions for Locked Players

Locked players cannot:

• 🚶 Move (if not in SPECTATOR mode)
• 🪓 Break blocks
• 🧱 Place blocks
• 🤝 Interact with entities or objects
• 🎮 Use items

⚡ Revival System

When a player head is placed on the ground:

1. 🔍 The plugin detects if it belongs to a locked player
2. ✨ If yes:
   • 🆓 Soul unlocked! Player is immediately freed
   • 📧 The player receives a message: "Your soul has been restored! ✨"
   • 🎯 If player is online:
     • Teleported to head location
     • Restored to SURVIVAL mode
     • Spawn point set to revival location
   • ⚡ Lightning strike effect (optional, non-damaging)
   • 🌟 Colorful particles spawn (optional)
3. 🗑️ Head disappears after placement

🎨 Visual Effects

• ⚡ Lightning Strike (configurable) - Dramatic effect when soul is restored
• 🌟 Particle Effects (configurable) - Beautiful visual feedback
• 💬 Colored Messages - Professional, colored console & player messages

📊 Real Player Heads

• 😊 When dropped, heads display the player's actual Minecraft skin
• 🎭 Uses Bukkit/Paper API (setOwningPlayer) for authentic rendering

---

🛠️ Installation & Setup

Prerequisites

• 📦 Java 21+ installed
• 📋 Maven (for building from source)
• 🖥️ Paper Server (v1.21+)

Step 1: Build the Plugin

cd "D:\Slimeey Studios\SoulLock"
mvn clean package

The compiled jar will be created at: target/SoulLock-1.0.jar

Step 2: Install the Plugin

1. Copy target/SoulLock-1.0.jar → paper-test/plugins/SoulLock-1.0.jar
2. Start the server (first run creates config files)
3. Configure settings in plugins/SoulLock/config.yml

Step 3: Start the Server

cd "D:\Slimeey Studios\SoulLock\paper-test"
.\start.ps1

💡 Tip: The server runs in offline mode by default for testing

---

⚙️ Configuration

Edit plugins/SoulLock/config.yml:

# 👻 How to treat locked players when they join
# SPECTATOR: Player enters spectator mode (can move & explore)
# KICK: Player is kicked from server
revive-mode: SPECTATOR

# ⚡ Show lightning strike when soul is restored
lightning-effect: true

# 🌟 Spawn particles when soul is restored
particle-effect: true

# 🪦 Keep player heads from despawning
prevent-head-despawn: true

Configuration Options Explained:

Option	Values	Description
revive-mode	SPECTATOR / KICK	How locked players behave on join
lightning-effect	true / false	Show lightning when soul is restored ⚡
particle-effect	true / false	Show particle effects on revival 🌟
prevent-head-despawn	true / false	Prevent player heads from disappearing naturally 🪦

---

🎮 Gameplay Guide

What Happens When You Die?

1. ☠️  You die → Soul is locked
2. 👻 You join server → Enter SPECTATOR mode (can move around)
3. 💀 Your head drops at death location (with your skin)
4. 📢 Message appears: "Your soul is locked!"

How to Revive a Locked Player?

1. 🔍 Find the player's head at their death location
2. 👆 Place the player head on the ground (like a block)
3. ✨ Magic happens:
   - ⚡ Lightning strikes!
   - 🌟 Particles burst!
   - 📢 Message: "Your soul has been restored! ✨"
4. 🆓 Player is instantly:
   - Switched to SURVIVAL mode
   - Teleported to head location
   - Unlock notification sent

---

💬 Commands

For Admins 👑

Unlock a Locked Player

/soullockadmin unlock <player|uuid>

Examples:

/soullockadmin unlock Steve
/soullockadmin unlock 550e8400-e29b-41d4-a716-446655440000

Message Output:

✓ [SoulLock] Soul unlocked for Steve!

Permissions:

• soullock.admin - Required for admin commands (default: OP only)

---

📊 Data Storage

How Data is Saved

• 💾 Locked player UUIDs stored in plugins/SoulLock/data.yml
• 🔄 Auto-saved when:
  • Player dies
  • Soul is unlocked/restored
  • Server shuts down
• 📂 Data persists across server restarts

Example data.yml:

locked_players:
  550e8400-e29b-41d4-a716-446655440000:
    username: Steve
    death_location:
      world: world
      x: 100.5
      y: 64.0
      z: 200.5

---

🎯 Events & Triggers

Implemented Events

Event	What Happens
PlayerDeathEvent	💀 Soul is locked, head drops
PlayerJoinEvent	👻 Locked players enter SPECTATOR mode
BlockPlaceEvent	💀 Check if placed block is a player head → Revive!
PlayerQuitEvent	📊 Optional: Update player data

---

🔧 Technical Details

Code Architecture

SoulLock Plugin/
├── 📄 SoulLockPlugin.java          (Main class, event manager)
├── 🎧 DeathListener.java           (Handles death events)
├── 🎧 JoinListener.java            (Handles player joins)
├── 🎧 BlockListener.java           (Handles head placement)
├── 💾 DataManager.java             (Save/load data)
├── 🛠️ HeadUtility.java             (Create player heads)
└── 📧 MessageUtil.java             (Colored messages)

Thread Safety

• ✅ Uses Paper's modern scheduler
• ✅ Async file I/O where possible
• ✅ No blocking API calls on main thread

Paper API Features Used

• 🎯 Adventure API for colored messages
• 📅 Modern Paper scheduler
• 🎧 Optimized event system
• 💻 Paper-specific optimizations

---

🚀 Quick Start Guide

1️⃣ Build

mvn clean package

2️⃣ Copy Plugin

Copy-Item "target/SoulLock-1.0.jar" "paper-test/plugins/"

3️⃣ Start Server

cd paper-test
.\start.ps1

4️⃣ Join Server

• Open Minecraft launcher
• Add server: localhost (offline mode)
• Join and test!

---

📝 Example Scenario

Multiplayer Gameplay

[Game Start]
🎮 Alice & Bob explore together

[Alice Dies]
☠️  Alice dies at coordinates (100, 64, 200)
💀 Soul locked! Head drops with Alice's skin
📢 Message: "Your soul is locked! ⚠️"

[Alice Joins]
👻 Alice enters SPECTATOR mode (can still move)
📢 Message: "You are in spectator mode!"

[Bob Searches]
🔍 Bob finds Alice's head at (100, 64, 200)
👆 Bob places the head on the ground

[Revival!]
✨ Magical effect triggers:
  - ⚡ Lightning strikes!
  - 🌟 Particles burst!
  - 📢 "Your soul has been restored! ✨"
  - 🆓 Alice switches to SURVIVAL mode
  - 🎯 Alice teleported to head location
  - 💀 Alice's head disappears

[Alice Continues]
🎮 Alice & Bob continue playing together!

---

🐛 Troubleshooting

Plugin won't load?

• ✅ Check Java version (21+ required)
• ✅ Verify plugin.yml syntax
• ✅ Check server logs for errors

Head not disappearing?

• ✅ Check prevent-head-despawn: true in config
• ✅ Verify head placement detection

Player not reviving?

• ✅ Ensure head is from a locked player
• ✅ Check if player is online
• ✅ Verify spawn location is safe

Commands not working?

• ✅ Check player has soullock.admin permission
• ✅ Verify correct command syntax
• ✅ Check player UUID format

---

📖 Commands Reference

Command	Permission	Description
/soullockadmin unlock <player|uuid>	soullock.admin	Unlock a locked player's soul

---

🎨 Customization

Modify Colors

Edit color codes in MessageUtil.java class

Particle Effects

Customize particle types in revival event handler

Lightning Effects

Toggle or modify lightning in BlockListener.java

---

✅ Version Info

• Plugin Name: SoulLock
• Version: 1.0
• API Version: 1.21+
• Required: Paper Server, Java 21+

---

📞 Support

For issues, questions, or suggestions:

1. 📋 Check the troubleshooting section
2. 📂 Review server logs in logs/
3. 🔍 Verify config.yml syntax
4. 👤 Check permissions and commands

---

📄 License

SoulLock © 2026 Slimeey Studios. All rights reserved.

---

Enjoy the thrilling soul-locking experience! 💀✨