Installation Guide

This comprehensive guide covers everything you need to know to properly install and configure SSoggySouls. Whether you’re running a single server or a full Velocity proxy network with Main + Limbo, this guide has you covered.

Table of Contents

  1. Prerequisites
  2. Network Architecture
  3. Database Setup
  4. Plugin Installation
  5. Proxy Configuration
  6. Server Configuration
  7. Testing Your Setup
  8. Common Mistakes to Avoid

Prerequisites

Server Requirements

Server Setup

Single Server: Just one Minecraft server. Dead players enter spectator mode. No proxy, no Limbo server, no MySQL needed.

2-Server Setup: Two backend servers behind a Velocity proxy:

Note: If using spectator death mode on a single server, the Limbo server is not needed.

Important: Do NOT Use Hardcore Mode

CRITICAL: Do NOT enable hardcore=true in server.properties on either server.

Leave it as false. The plugin manages hardcore mechanics internally - enabling Minecraft’s built-in hardcore mode will break the plugin.

If you already have it enabled:

Network Architecture

How SSoggySouls Works


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

Database Setup

The plugin supports two database types. Your choice here determines your entire setup:

| Feature | sqlite (Local) | mysql (External) | | ——————————– | ——————————– | —————————————— |

Best For Single servers 2-Server Proxy Networks
Performance High (Lightweight / Local I/O) Maximum (Multi-threaded Dedicated Service)
Network Latency None (Zero Ping) Varies (Dependent on Host)
Setup Required None (Plug & Play) Advanced (User/Grants)
Lives & HRM Systems ✅ Works Perfectly ✅ Works Perfectly
Main + Limbo Syncing ❌ NOT SUPPORTED ✅ Supported
Plugin Sharing (CoreProtect) ❌ No ✅ Yes (Same Database)
Data Editing / Viewing Requires 3rd Party SQLite Editor PhpMyAdmin / Pterodactyl Panels
Backups Copy database.db file Requires mysqldump
Portability High (Single .db file) Low (External Server)

Option A: SQLite (Zero Setup / Local)

Ideal for a single server setup if you just want lives, HRM features, and extra-life items without worrying about setting up an external database.

Option B: MySQL (Cross-server)

REQUIRED if you are using the 2-server (Main + Limbo) functionality. You set up one MySQL database, then both servers connect to it using the same credentials.

SSoggySouls will automatically create the necessary table, but you need to create the database first.

Using MySQL command line:

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

FLUSH PRIVILEGES;

For shared hosting (Pterodactyl, etc.):

  1. Go to your hosting panel
  2. Navigate to the Databases section
  3. Create a new database
  4. Note down the host, port, database name, username, and password

Database Configuration

If using SQLite, simply set type: "sqlite" and ignore the MySQL fields — the plugin handles everything.

If using MySQL, set up one database and then copy the same connection details into both server configs:

database:
  type: "mysql"                  # Database type: "mysql" or "sqlite"

  host: "localhost"              # Database host (use panel host for Pterodactyl)

  port: 3306                     # Database port

  name: "ssoggysouls"             # Database name

  username: "ssoggysouls_user"    # Database username

  password: "your_secure_password" # Database password

  pool-size: 5                   # Connection pool size (5 is recommended)

  table-name: "hardcore_players" # Table name (default is fine)

Tip: The database can be shared with other plugins like CoreProtect. SSoggySouls uses its own table.

Connection Pool Settings (MySQL only)

The pool-size setting controls how many database connections are maintained:

Plugin Installation

Download

Get the latest version:

Download SSoggySouls-4.5.7.jar (or latest version).

Installation Steps

  1. Stop your server(s) if they are running.

  2. Place the JAR file in the plugins/ folder:

For Single Server Setups:

Server: /plugins/SSoggySouls-4.5.7.jar

For 2-Server Setups (Main + Limbo):

Main Server: /plugins/SSoggySouls-4.5.7.jar
Limbo Server: /plugins/SSoggySouls-4.5.7.jar

  1. Start your server(s) to generate config files

  2. Stop your server(s) to edit configuration

  3. Edit config.yml (see next section)

Critical Setup Rules

DO NOT install on proxy:

Note: For singleplayer, simply place the JAR in your client’s mods folder. Limbo features are disabled in singleplayer automatically.

Forge & NeoForge Mod Installation

The Forge and NeoForge versions are installed similarly to the Bukkit version, but use the mods/ folder.

Requirements

Installation Steps

  1. Place SSoggySouls-Forge-X.X.X.jar or SSoggySouls-NeoForge-X.X.X.jar into the mods/ folder.
  2. Start the server to generate config/ssoggysouls.toml (or ssoggysouls.json depending on build).
  3. Stop the server and configure as needed.

Note: Fabric, Forge, and NeoForge versions are currently in an early testing phase. Expect frequent updates and please report any bugs you find!

DO install on both backend servers (if using Limbo):

Proxy Configuration

For Velocity

Edit velocity.toml:


# Enable modern forwarding

player-info-forwarding-mode = "modern"

[servers]
main = "localhost:25566"   # Your Main server

limbo = "localhost:25567"  # Your Limbo server

try = [
"main"  # Players join Main by default

]

For BungeeCord/Waterfall

Note: BungeeCord/Waterfall support is untested. Please report if you test it!

In BungeeCord config.yml:

ip_forward: true

On both backend servers in spigot.yml:

settings:
  bungeecord: true

If using Paper, also configure paper.yml:

settings:
  velocity-support:
    enabled: false  # Disable for BungeeCord

Server Configuration

Note for Single Servers (SQLite): If you are running a single server with SQLite, you can safely skip the “Server Role” sections below. Just leave is-limbo-server and the server names at their defaults — the plugin ignores them when using SQLite.

Main Server Configuration

Edit /plugins/SSoggySouls/config.yml on the Main server:


# SERVER IDENTIFICATION

is-limbo-server: false           # This is the Main server

# SERVER NAMES (must match velocity.toml)

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

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

# DATABASE (set up one MySQL database, then use the same details here and on Limbo)

database:
  type: "mysql"
  host: "localhost"
  port: 3306
  name: "ssoggysouls"
  username: "ssoggysouls_user"
  password: "your_secure_password"
  pool-size: 5
  table-name: "hardcore_players"

# LIVES SYSTEM

lives:
  default: 2                     # Starting lives for new players

  max-lives: 5                   # Maximum lives cap

  on-revive: 1                   # Lives restored on revival

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

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

# DEATH HANDLING

main:
  death-mode: "spectator"        # SQLite uses spectator; MySQL can use hybrid | spectator | limbo

  hybrid-timeout-seconds: 300    # 5 minutes for hybrid mode

  spectator-on-death: false
  detect-hrm-revive: true        # Enable ritual structure detection

  send-to-limbo-delay-ticks: 20  # 1 second delay before transfer

Limbo Server Configuration

Edit /plugins/SSoggySouls/config.yml on the Limbo server:


# SERVER IDENTIFICATION

is-limbo-server: true            # This is the Limbo server

# SERVER NAMES (must match velocity.toml and Main server config)

main-server-name: "main"
limbo-server-name: "limbo"

# DATABASE (must be identical to Main server)

database:
  type: "mysql"
  host: "localhost"
  port: 3306
  name: "ssoggysouls"
  username: "ssoggysouls_user"
  password: "your_secure_password"
  pool-size: 5
  table-name: "hardcore_players"

# LIMBO SETTINGS

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

  spawn:
    world: "world"               # Set with /setlimbospawn command

    x: 0.5
    y: 65.0
    z: 0.5
    yaw: 0.0
    pitch: 0.0

Setting Limbo Spawn

  1. Start the Limbo server
  2. Join the server in-game
  3. Stand at the desired spawn location
  4. Run /setlimbospawn
  5. Confirm the coordinates were saved

The spawn location is saved to config and will be used for all dead players.

Testing Your Setup

Pre-Flight Checklist

Before testing, verify:

Test Procedure

  1. Join Main Server
  1. Check Initial Status

/pstatus

Should show: “Lives: 2 - Status: Alive”

  1. Test Death Mechanic
  1. Test Limbo Transfer
  1. Test Revival
  1. Test Grace Period

Verification

If all tests pass, your installation is complete!

Check console logs for:

Common Mistakes to Avoid

Mistake 1: Installing on Proxy

Wrong: Installing SSoggySouls on Velocity/BungeeCord

Right: Install only on backend servers (Main and Limbo)

Mistake 2: Different Database Credentials

Wrong: Using different database credentials on each server

Right: Set up one MySQL database and copy the same credentials to both configs

Mistake 3: Server Names Don’t Match

Wrong: Config says “main” but velocity.toml says “survival”

Right: Server names must exactly match proxy configuration

Mistake 4: Wrong is-limbo-server Setting

Wrong: Both servers have is-limbo-server: false

Right: Main = false, Limbo = true

Mistake 5: Enabling Hardcore Mode

Wrong: Setting hardcore=true in server.properties

Right: Keep hardcore=false - plugin manages hardcore mechanics

Mistake 6: Different Plugin Versions

Wrong: Main server has v3.2.6, Limbo has v4.5.7

Right: Both servers must use the exact same version

Mistake 7: Not Setting Limbo Spawn

Wrong: Forgetting to run /setlimbospawn

Right: Set spawn point before testing

Mistake 8: Firewall Blocking Database

Wrong: Servers can’t reach database due to firewall

Right: Ensure firewall allows backend → database connections

Next Steps

Now that SSoggySouls is installed:

  1. Customize Settings - Review the Configuration Reference

  2. Learn Commands - Check out the Commands Guide

  3. Understand Revival System - Read the Revival System Guide

  4. Prepare for Issues - Familiarize yourself with Troubleshooting

Need Help?

← Quick Start Back to Home Configuration →