Network Sync

Network Sync (MySQL)

CelestialCosmetics can store everything in a shared MySQL / MariaDB database so a player's cosmetics follow them across every server on your network: owned cosmetics, equipped looks, the vault, the Auction House, crate stock, pity counters and daily claims all become network-wide.

Single server? Leave it on SQLite (the default) — no setup needed.

Configuration (config.yml)

storage:
  # sqlite = local file (single server) | mysql = shared (network)
  type: mysql
  file: cosmetics.db          # sqlite only
  mysql:
    host: 127.0.0.1
    port: 3306
    database: celestialcosmetics
    username: celestial
    password: 'your-password'
    properties: '?useSSL=false&characterEncoding=utf8&serverTimezone=UTC'
    pool-size: 10

mariadb is accepted as an alias of mysql.

Setup steps

1. Create a database and a user with access to it:

   CREATE DATABASE celestialcosmetics CHARACTER SET utf8mb4;
   CREATE USER 'celestial'@'%' IDENTIFIED BY 'your-password';
   GRANT ALL PRIVILEGES ON celestialcosmetics.* TO 'celestial'@'%';
   FLUSH PRIVILEGES;

2. On every server, set storage.type: mysql and point it at the same database.
3. Keep the cosmetic config files identical across servers (the database stores who owns what; the YAML files define what the cosmetics are).
4. Start the servers — the tables are created automatically.

How it works

• The plugin uses a HikariCP connection pool. The MySQL driver and the pool are downloaded automatically by Paper's library loader on first start (needs internet once; cached afterwards).
• A player's data is flushed on quit and loaded on join, so switching servers loads the latest from the shared database.
• Global crate stock is claimed with an atomic query, so a stock-limited reward can't be won more times than allowed even if two servers open a crate at the same instant.

Notes & limits

• First start needs internet on the server to fetch the driver/pool libraries. Air-gapped servers won't be able to load them.
• Currency isn't synced by this plugin — that's the job of your economy plugin. For a network economy, make sure your currency plugin (Vault economy, EdDungeons, PlayerPoints…) is itself network-aware.
• No live cross-server broadcasts: a unique crate win is announced on the server where it happened, not network-wide (data is still shared through the DB).
• On very fast BungeeCord server switches there is a small theoretical window between the flush on one server and the load on the next; in practice this is rarely noticeable.

Consistent configs across the network

Because the cosmetic definitions live in the YAML files (not the DB), every server must ship the same tags.yml, rankcolors.yml, crates.yml, etc. Easiest options:

• Copy the config folder to each server, or
• Use a synced/templated deployment so all servers share one config set.

---

Next: Economy Integration