Installation Guide

This comprehensive guide covers everything you need to know to properly install and configure SSoggySouls on your Velocity proxy network.

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

You need two backend servers:

Note: If using spectator death mode, the Limbo server is optional.

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 depending on your setup. You must choose one based on your network architecture:

| 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 true 2-server (Main + Limbo) functionality.

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". If using MySQL, both servers must use identical database credentials:

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-3.2.6.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-3.2.6.jar

For 2-Server Setups (Main + Limbo):

Main Server: /plugins/SSoggySouls-3.2.6.jar
Limbo Server: /plugins/SSoggySouls-3.2.6.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:

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 ignore is-limbo-server and the server names. Just leave them as default and scroll down!

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 (must be identical on both servers)

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: "hybrid"           # 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: Both servers must use identical database settings

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.5, Limbo has v3.2.6

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 →