Configuration Reference

Complete guide to configuring SSoggySouls to match your server’s needs.

Table of Contents

  1. Overview
  2. Server Role
  3. Security Settings
  4. Database Configuration
  5. Lives System
  6. Death Modes
  7. Limbo Settings
  8. HRM Features
  9. Extra Life Item
  10. Messages & Colors
  11. Advanced Options

Overview

SSoggySouls uses a config.yml file that is automatically generated when you first run the plugin. This file is highly customizable and includes detailed comments explaining each setting.

Location: plugins/SSoggySouls/config.yml on both servers

Important: After editing the config file, either:

  • Restart both servers, or

  • Run /psadmin reload to reload without restart (some changes may require restart)

Server Role

These settings identify what role each server plays in your network.

Main Server Configuration


# CRITICAL: Set this correctly!

is-limbo-server: false    # This is the Main server (survival)

# Must match your Velocity/proxy configuration

main-server-name: "main"     # Name of Main server in proxy config

limbo-server-name: "limbo"   # Name of Limbo server in proxy config

Limbo Server Configuration


# CRITICAL: Set this correctly!

is-limbo-server: true     # This is the Limbo server (purgatory)

# Must match your Velocity/proxy configuration

main-server-name: "main"     # Name of Main server in proxy config

limbo-server-name: "limbo"   # Name of Limbo server in proxy config

Tip: The server names must exactly match the server names in your velocity.toml file.

Security Settings

Limbo OP Security Check

limbo-op-security-check: true  # Prevent Limbo-only OPs from using admin commands

Important Security Feature: This setting prevents a critical security vulnerability where users with OP status only on the Limbo server could execute privileged commands like /revive and /psadmin.

Why This Matters

If you give someone OP on the Limbo server (for example, to manage the Limbo world), they could potentially:

How It Works

When enabled (recommended), this security check will:

  1. Block all OP users on the Limbo server from executing admin/revive commands

  2. Allow OP users with the bypass permission ssoggysouls.bypass-limbo-op-security

  3. Allow non-OP users with explicit permission nodes

  4. Allow commands on the Main server regardless of how permissions are granted

  5. Allow console to always execute commands

Granting Proper Permissions

To allow a user to execute admin commands on the Limbo server, you have three options:

Option 1: Use the Whitelist (Easiest - No permissions plugin required)


# In config.yml

limbo-trusted-admins:
  - "069a79f4-44e9-4726-a5be-fca90e38aaf5"  # UUID format (recommended)

  - "YourUsername"                          # Username format also works

Option 2: Grant bypass permission (requires LuckPerms or similar)


# Allows OP users to execute commands on Limbo server

/lp user <player> permission set ssoggysouls.bypass-limbo-op-security true

Option 3: Grant explicit permissions without OP


# Remove OP status first, then grant explicit permissions

/deop <player>

# For revival commands:

/lp user <player> permission set ssoggysouls.revive true

# For all admin commands:

/lp user <player> permission set ssoggysouls.admin true

Tip: Use Option 1 (whitelist) if you don’t have a permissions plugin installed. It’s the simplest and works out-of-the-box.

Disabling the Security Check

limbo-op-security-check: false  # NOT RECOMMENDED

Set to false only if:

Security Recommendation: Keep this enabled (true) in production environments.

Database Configuration

This plugin supports two types of databases:

1. SQLite (Local - Single Server)

Ideal for standard, single-server setups. No extra setup required. Data is stored locally.

database:
  type: "sqlite"

2. MySQL (Network - 2-Server Setup)

REQUIRED if you are using the true 2-server (Main + Limbo) functionality. Both servers must use identical database credentials or player records will be split!

database:
  type: "mysql"
  host: "localhost"              # Database host
  port: 3306                     # Database port (default: 3306)
  name: "ssoggysouls"             # Database name
  username: "root"               # MySQL username
  password: "changeme"           # MySQL password - CHANGE THIS!
  pool-size: 5                   # Connection pool size
  table-name: "hardcore_players" # Table name (default is fine)

Pool Size Recommendations

For Pterodactyl Hosting

Use the database host provided by your hosting panel, not “localhost”:

database:
  host: "db-pterodactyl.c9akciq32cpl.us-east-1.rds.amazonaws.com"
  port: 3306
  name: "s123_ssoggysouls"
  username: "u123_admin"
  password: "your_secure_password"

Lives System

Configure how the lives mechanic works.

lives:
  default: 2                      # Starting lives for new players

  max-lives: 5                    # Maximum lives cap

  on-revive: 1                    # Lives restored when revived

  grace-period: "24h"             # New player protection period

  revive-cooldown-seconds: 30     # Post-revival death protection

Default Lives

default: 2

Starting number of lives for newly joined players. Common values:

Maximum Lives

max-lives: 5

The highest number of lives a player can have. They cannot use extra life items or commands to exceed this cap.

Lives on Revival

on-revive: 1

How many lives a dead player gets back when revived. Options:

Grace Period

grace-period: "24h"

New player protection that prevents losing lives during the grace period. The timer counts only when the player is online (pauses when offline).

Format Options:

Example: A new player with “24h” grace who plays 3 hours, logs off, then returns will have 21 hours remaining.

Revive Cooldown

revive-cooldown-seconds: 30

After being revived, a player is protected for this duration and cannot lose lives from deaths. Gives them time to get situated.

Death Modes

Choose how your server handles player death.

main:
  death-mode: "hybrid"            # hybrid | spectator | limbo

  hybrid-timeout-seconds: 300     # Timeout for hybrid mode (5 min)

  spectator-on-death: false       # Put in spectator before Limbo

  detect-hrm-revive: true         # Auto-detect ritual structure revivals

  send-to-limbo-delay-ticks: 20   # Delay before Limbo transfer (1 sec)

Hybrid Mode (Default - Recommended)

death-mode: "hybrid"
hybrid-timeout-seconds: 300

Behavior:

Best For: Servers wanting tension and urgency - gives teams a limited rescue window.

Timeout Options:

Spectator Mode

death-mode: "spectator"
spectator-on-death: true

Behavior:

Best For: Servers preferring dead players to spectate their team constantly without forced exile.

Limbo Mode (Strict)

death-mode: "limbo"

Behavior:

Best For: Hardcore servers enforcing strict separation between living and dead.

HRM Revival Detection

detect-hrm-revive: true

When enabled, the plugin automatically detects when a ritual structure is completed and performs the revival. Leave this enabled unless troubleshooting.

Limbo Transfer Delay

send-to-limbo-delay-ticks: 20

Delay in ticks before sending a player to Limbo (20 ticks = 1 second). Gives time for other events to process. Usually no need to change.

Limbo Settings

Configure the Limbo server (only applies on Limbo server).

limbo:
  check-interval-seconds: 3       # How often to check for revivals

  spawn:
    world: "world"
    x: 0.5
    y: 65.0
    z: 0.5
    yaw: 0.0
    pitch: 0.0

Check Interval

check-interval-seconds: 3

How frequently the Limbo server checks the database for revival requests. Lower = more responsive, higher = less database load.

Spawn Location

spawn:
  world: "world"    # World name

  x: 0.5            # X coordinate

  y: 65.0           # Y coordinate

  z: 0.5            # Z coordinate

  yaw: 0.0          # Horizontal rotation (0 = north)

  pitch: 0.0        # Vertical rotation (0 = level, 90 = down)

Set the spawn location where dead players appear on Limbo. Use the /setlimbospawn command to set this automatically:

  1. Stand at desired spawn location on Limbo
  2. Run /setlimbospawn
  3. Coordinates are automatically saved

HRM Features

Configure the built-in Hardcore Revive Mode system.

hrm:
  enabled: true                   # Master HRM toggle

  drop-heads: true                # Drop player heads on death

  death-location-message: true    # Send death coords to player

  structure-revive: true          # Enable 3x3x3 ritual structures

  leave-structure-base: true      # Don't destroy structure after revive

  head-wearing-effects: true      # Speed/night vision when wearing heads

  revive-skull-recipe: true       # Enable Revive Skull crafting

Enable/Disable HRM

enabled: true

Master toggle for all HRM features. Set to false to disable everything related to HRM.

Player Head Drops

drop-heads: true

When a player loses all lives, their head drops at the death location. These heads are used in ritual structures for revival.

Death Location Messages

death-location-message: true

When a player dies, send them a message with the death coordinates to help their teammates locate their dropped head.

Example Message:


Death coordinates: X: 1234 Y: 64 Z: -5678

Structure-Based Revival

structure-revive: true

Enable the 3x3x3 ritual structure revival system. When disabled, ritual structures won’t trigger revivals.

Leave Structure Base

leave-structure-base: true

If true, the base structure remains after revival (only the player head is removed).
If false, the entire structure is destroyed upon successful revival.

Head Wearing Effects

head-wearing-effects: true

When a player wears a dead player’s head, they receive:

Tactical advantage while carrying heads to revival structures.

Revive Skull Recipe

revive-skull-recipe: true

Enable crafting of Revive Skull items. The recipe is:

| | | | | — | — | — |

Obsidian Ghast Tear Obsidian
Totem of Undying Any Skull/Head Totem of Undying
Obsidian Ghast Tear Obsidian

Extra Life Item

Configure the craftable item that grants additional lives.

extra-life:
  enabled: true
  item-material: "NETHER_STAR"    # Icon displayed in menus

  recipe:
    row1: "DED"    # Row 1: Diamond, Emerald, Diamond

    row2: "INI"    # Row 2: Netherite Ingot, Nether Star, Netherite Ingot

    row3: "GEG"    # Row 3: Gold Block, Emerald Block, Gold Block

    ingredients:
      G: "GOLD_BLOCK"
      E: "EMERALD_BLOCK"
      N: "NETHER_STAR"
      D: "DIAMOND_BLOCK"
      I: "NETHERITE_INGOT"

Enable/Disable

enabled: true

Set to false to disable extra life crafting entirely.

Item Icon

item-material: "NETHER_STAR"

The item used as the icon in menus and crafting results. Any valid Minecraft material works (common choices: NETHER_STAR, GOLDEN_APPLE, DIAMOND, EMERALD).

Custom Recipe

To create a custom recipe:

  1. Define the layout in row1, row2, row3 using letters
  2. Map each letter to a material in ingredients

Example: Simple Diamond Recipe

recipe:
  row1: "DDD"
  row2: "DED"
  row3: "DDD"
  ingredients:
    D: "DIAMOND_BLOCK"
    E: "EMERALD_BLOCK"

Result: 9 Diamond Blocks with 1 Emerald Block in the center.

Valid Material Names:

Any Minecraft material name in SCREAMING_SNAKE_CASE:

Finding Material Names:

Check Minecraft Material Constants or look at org.bukkit.Material enum.

Messages & Colors

Customize all player-facing messages and notification colors.

messages:

  prefix: "&8[&4☠&8] &r"
  death-life-lost: "&cYou lost a life! &7Remaining: &e%lives%"
  death-last-life: "&c&l⚠ FINAL WARNING! &cYou are on your last life. Be careful!"
  revive-success: "&a&l✦ REVIVED! &aReturning to the world of the living..."
  # ... many more messages

Color Codes

Formatting Codes

Available Variables

Example: Custom Messages

messages:
  prefix: "&8[&cDEATH&8] &r"
  death-life-lost: "&cOh no! &7You lost a life. &eRemaining: %lives%/%max%"
  death-last-life: "&c&l💀 CRITICAL! &cThis is your LAST life!"
  revive-success: "&a&l✓ &aYou have been revived! Stay alive this time!"
  grace-remaining: "&eYou are protected for &a%time_remaining%"

Advanced Options

check-for-updates: true          # Check for new versions on Modrinth

hardcore-hearts: true            # Display hardcore hearts cosmetically

debug: false                     # Enable debug logging (dev only)

Update Checking

check-for-updates: true

When enabled, the plugin checks Modrinth on startup for newer versions and displays update notices in console.

Hardcore Hearts

hardcore-hearts: true

Display Minecraft’s hardcore-style hearts (half-hearts instead of full hearts). This is cosmetic only and doesn’t affect gameplay.

Requires client mod support or resource pack to display properly

Debug Logging

debug: false

Enable detailed debug logging to console. Only useful for troubleshooting. Turn on if you’re having issues and need more information.

Configuration Examples

Hardcore Server (One Life)

lives:
  default: 1
  max-lives: 1
  on-revive: 0  # No lives on revive (need to craft extra life)

main:
  death-mode: "limbo"  # Immediate exile

Casual Server (Three Lives)

lives:
  default: 3
  max-lives: 5
  on-revive: 2
  grace-period: "48h"  # Extended grace for new players

main:
  death-mode: "hybrid"
  hybrid-timeout-seconds: 600  # 10 minute timeout

Competitive Server (Spectator Focus)

lives:
  default: 2
  max-lives: 3
  grace-period: "0"  # No grace period

main:
  death-mode: "spectator"  # Dead players watch forever

Reloading Configuration

To reload configuration without restarting:

/psadmin reload

Note: Some changes take effect immediately, others may require:

Need Help?

← Commands Reference Back to Home Revival System →