Storage Backend

Storage Backend & Data Management

BeaconPlus handles two types of data: Player Data (discovered effects, personal settings) and Beacon Data (location, power level, tiers). You must choose where to save this information based on your server size and need for cross-server synchronization.

---

1. Storage Types Explained

WORLD (Beacon Storage Only)

This saves beacon data directly inside your Minecraft world folder (in data/beacons).

Best For:

• Single Servers: It keeps the beacon data physically with the map. If you download the world and move it to singleplayer or another server, the beacons stay working perfectly.

The Catch:

• No Sync: You cannot share this data across multiple servers (Bungee/Velocity).
• Resets: If you reset your world folder, you lose all beacon data.

---

FILE (Flat-File / YAML)

This saves data as simple .yml files in the plugins/BeaconPlus/ folder.

Best For:

• Small/Medium Servers: Easy to edit manually. Easy to backup.
• Debugging: You can open a player's file and read exactly what effects they have unlocked.

The Catch:

• Performance: If you have 10,000+ folders, your operating system will struggle to open the folder quickly.
• IO Lag: Saving thousands of files at once during a shutdown can take a few seconds.

---

SQLITE (Local Database - Beacon Storage Only)

This uses a single high-performance .db file on your disk.

Best For:

• Large Single Servers: Much faster than FILE storage for reading/writing thousands of beacons.
• Stability: Prevents file corruption issues that can happen with thousands of tiny YAML files.

The Catch:

• Not Human Readable: You cannot just open the file to edit a beacon. You must use a database viewer (like DB Browser for SQLite).

---

MYSQL (Remote Database)

This connects to an external database server (like MariaDB or MySQL).

Best For:

• Networks (Bungee/Velocity): Required if you want a player's unlocked effects to follow them from Survival-1 to Survival-2.
• Massive Scale: Can handle millions of rows without slowing down the Minecraft server.

The Catch:

• Complexity: Requires you to set up and pay for a database host.
• Dependency: If your SQL database crashes, BeaconPlus stops working entirely.

---

2. Recommended Setups

Server Type	Player Count	Player Storage	Beacon Storage	Why?
SMP / Private	1 - 30	FILE	WORLD	simplest backup. Beacons move with the world map.
Towny / Factions	50 - 200	FILE	SQLITE	Fast performance for beacons, but keeps player data editable.
Bungee Network	500+	MYSQL	MYSQL	Full synchronization across all sub-servers.

---

3. Safe Migration Guide

Changing your storage backend does not automatically move your old data. If you switch from FILE to MYSQL, the plugin will start empty.

How to migrate safely:

1. Stop the Server. Never change storage settings while running.
2. Backup: Copy your BeaconPlus folder.
3. Configure: Edit storage.yml to the new type.
4. Manual Import:
   • There is no automatic converter. If you are moving to MySQL, you usually start fresh or need a developer to export your YAML data to SQL.
   • Tip: Only switch backends during a "Season Reset" or maintenance window.

---

4. Troubleshooting MySQL

If you see "Failed to connect" errors, check these common issues:

• Firewall: Is port 3306 open on the database host?
• Timeout: Set Auto Reconnect: true in your storage.yml to prevent the connection from dying overnight.
• SSL: Try toggling Use SSL to false if your host uses a self-signed certificate.

---

5. Configuration Blueprint

Copy this template to your storage.yml.

# ==========================================
# STORAGE CONFIGURATION BLUEPRINT
# ==========================================

Storage:
  # Choose specific storage for Beacons data
  # Options: WORLD, JSON, SQLITE, MYSQL
  Beacon Storage Type: SQLITE
  
  # Choose specific storage for Player data
  # Options: JSON, MYSQL
  Player Storage Type: JSON

  # ----------------------------------------
  # MYSQL SETTINGS (If used)
  # ----------------------------------------
  MySQL:
    Host: "127.0.0.1"
    Port: 3306
    Database Name: "beaconplus"
    Username: "root"
    Password: "password"
    
    # Table Names (Change if conflicts exist)
    Players Table: "beaconplus_players"
    Beacons Table: "beaconplus_beacons"
    
    # Connection Properties
    Use SSL: false
    Auto Reconnect: true
    Pool Size: 10       # Max concurrent connections

  # ----------------------------------------
  # CACHE SETTINGS
  # ----------------------------------------
  # How long to keep player data in memory after they quit?
  # Helps if players rejoin quickly.
  Cache Duration: 5m