PolarSouls

Overview

PolarSouls is a sophisticated hardcore lives system plugin for Minecraft 1.21.X running on Spigot, Paper, or Purpur, designed for Velocity proxy networks. Players are exiled to a Limbo server upon losing all lives, with multiple revival methods to bring them back — creating high-stakes teamwork and memorable moments.

Quick Start

Get PolarSouls running in 8 steps. For full details, see the Installation section.

1. Download the latest PolarSouls-1.3.6.jar from GitHub Releases or Modrinth.
2. Install the JAR in the plugins/ folder of both backend servers (Main and Limbo). Do NOT install on the Velocity proxy.
3. Start both servers to generate default plugins/PolarSouls/config.yml files, then stop both servers.
4. Configure database — edit config.yml on both servers with identical MySQL credentials.
5. Set server roles — set is-limbo-server: false on Main and is-limbo-server: true on Limbo. Make sure main-server-name and limbo-server-name match your velocity.toml.
6. Set Limbo spawn — start the Limbo server, join it, stand at the desired spawn point, and run /setlimbospawn.
7. Configure Velocity — set player-info-forwarding-mode = "modern" in velocity.toml.
8. Restart both servers and test: check /pstatus, lose all lives, verify Limbo transfer, then revive with /psadmin revive <player>.

Death Mode Quick Reference

Installation

Network Architecture

PolarSouls requires two backend servers connected through a Velocity proxy, sharing a single MySQL database:

                ┌─────────────────┐
                │  Velocity Proxy │
                └────────┬────────┘
                         │
          ┌──────────────┴──────────────┐
          │                             │
    ┌─────▼─────┐                 ┌─────▼─────┐
    │   Main    │◄───────────────►│   Limbo   │
    │  Server   │    MySQL/MariaDB │  Server   │
    └───────────┘                 └───────────┘

Database Setup

PolarSouls creates the necessary table automatically, but you must create the database first.

CREATE DATABASE polarsouls CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'polarsouls_user'@'localhost' IDENTIFIED BY 'your_secure_password';
GRANT SELECT, INSERT, UPDATE, DELETE, CREATE, ALTER ON polarsouls.* TO 'polarsouls_user'@'localhost';
FLUSH PRIVILEGES;

For Pterodactyl or shared hosting, create the database from your hosting panel and note the provided credentials.

Plugin Installation

1. Stop both servers if running.
2. Place PolarSouls-1.3.6.jar in the plugins/ folder on both servers.
3. Start both servers to generate config files, then stop them again.
4. Edit config.yml on both servers (see Configuration section).
5. Start both servers and verify database connection messages in the console.

Velocity Configuration

player-info-forwarding-mode = "modern"

[servers]
  main = "localhost:25566"
  limbo = "localhost:25567"

try = ["main"]

Main Server Config

is-limbo-server: false
main-server-name: "main"
limbo-server-name: "limbo"

database:
  host: "localhost"
  port: 3306
  name: "polarsouls"
  username: "polarsouls_user"
  password: "your_secure_password"
  pool-size: 5
  table-name: "hardcore_players"

lives:
  default: 2
  max-lives: 5
  on-revive: 1
  grace-period: "24h"
  revive-cooldown-seconds: 30

main:
  death-mode: "hybrid"
  hybrid-timeout-seconds: 300
  detect-hrm-revive: true
  send-to-limbo-delay-ticks: 20

Limbo Server Config

is-limbo-server: true
main-server-name: "main"
limbo-server-name: "limbo"

database:
  host: "localhost"
  port: 3306
  name: "polarsouls"
  username: "polarsouls_user"
  password: "your_secure_password"
  pool-size: 5
  table-name: "hardcore_players"

limbo:
  check-interval-seconds: 3
  spawn:
    world: "world"
    x: 0.5
    y: 65.0
    z: 0.5

Common Mistakes to Avoid

Configuration

All settings live in plugins/PolarSouls/config.yml on each server. After editing, run /psadmin reload (from console or an already-authorized account) or restart the server.

Lives System

Death Modes

main:
  death-mode: "hybrid"          # hybrid | spectator | limbo
  hybrid-timeout-seconds: 300   # 5 minutes for hybrid mode

HRM (Hardcore Revive Mode)

hrm:
  enabled: true               # Master on/off for all HRM features
  drop-heads: true            # Drop player heads on death
  structure-revive: true      # Enable ritual structure detection
  revive-skull-recipe: true   # Enable Revive Skull crafting
  head-wearing-effects: true  # Speed II + Night Vision when wearing dead player's head
  detect-hrm-revive: true     # Auto-detect completed ritual structures
  leave-structure-base: true  # Keep base structure after revival

Limbo OP Security

This prevents players who are OP only on the Limbo server from executing admin/revive commands.

limbo-op-security-check: true   # Recommended: keep enabled

limbo-trusted-admins:
  - "069a79f4-44e9-4726-a5be-fca90e38aaf5"  # UUID (recommended)
  - "YourUsername"                            # Username also works

Extra Life Item

extra-life:
  enabled: true
  item-material: "NETHER_STAR"
  recipe:
    row1: "DED"   # D=Diamond Block, E=Emerald Block
    row2: "INI"   # I=Netherite Ingot, N=Nether Star
    row3: "GEG"   # G=Gold Block
    ingredients:
      G: "GOLD_BLOCK"
      E: "EMERALD_BLOCK"
      N: "NETHER_STAR"
      D: "DIAMOND_BLOCK"
      I: "NETHERITE_INGOT"

Commands

Player Commands

Admin Commands

All /psadmin commands require polarsouls.admin (op by default). Alias: /psa

Permissions

Revival System

PolarSouls supports four revival methods that can be used in combination:

Ritual Structure

Build a 3×3×3 structure and place the dead player's head on top to automatically revive them.

Soul Sand  |  Stair     |  Soul Sand
Stair      |  Ore Block |  Stair
Soul Sand  |  Stair     |  Soul Sand

Wither Rose  |  (empty)  |  Wither Rose
(empty)      |  Fence    |  (empty)
Wither Rose  |  (empty)  |  Wither Rose

(empty)  |  (empty)  |  (empty)
(empty)  |  Head     |  (empty)
(empty)  |  (empty)  |  (empty)

Revive Skull Item

A craftable item that opens a GUI showing all dead players. Click a player's name to receive their head without needing the original dropped head.

Default Recipe (Shapeless)

Extra Life Item

Craft this item and right-click it to gain +1 life (up to your max). Cannot be used while dead.

Default Recipe

Diamond Block  | Emerald Block | Diamond Block
Netherite Ingot|  Nether Star  | Netherite Ingot
Gold Block     | Emerald Block | Gold Block

The recipe is fully customizable in config.yml — see the Configuration section.

Head Mechanics

Troubleshooting

Enable Debug Logging

1. Open config.yml and set debug: true.
2. Run /psadmin reload from console.
3. Reproduce the issue and review console output for detailed information.
4. Disable debug logging after investigation to reduce log noise.

FAQ

Support & Contributing

Need help or found a bug? Here's how to get support:

1. Check the Troubleshooting section above for common issues.
2. Review the FAQ for quick answers.
3. Search existing issues on GitHub.
4. Open a new issue with your server version, plugin version, and console logs.

License

PolarSouls is licensed under the GNU General Public License v3.0 (GPL-3.0). You are free to use, modify, and distribute this plugin according to the terms of the license. See the LICENSE file for details.