Multi Server

Multi-Server Support

uxmDiscordSync is designed to work across multiple Minecraft servers sharing a single Discord guild and database. This page explains how to configure a multi-server setup.

---

Overview

Each server runs its own instance of uxmDiscordSync but all instances point to the same shared MySQL or PostgreSQL database. This allows:

• A player who links on Server A is automatically linked on Server B
• Rank sync reads the same linked account regardless of which server the player is on
• Boost cooldowns and level data are shared (if configured)
• Each server can still have its own name for identification in logs and messages

---

Requirements

• A shared MySQL, MariaDB, or PostgreSQL database (Flatfile and SQLite are single-server only)
• All server instances must use the same database credentials and database name
• Each server must have its own Discord bot token, OR you can reuse the same bot token

---

Configuration

Step 1 — Shared Database

In config.yml on every server:

database:
  type: mysql
  mysql:
    host: "shared-db-host.example.com"
    port: 3306
    database: "uxmdiscordsync"
    username: "uxmds"
    password: "yourpassword"

All servers must point to the same database and host.

Step 2 — Unique Server Names

Give each server a distinct name in config.yml. This name appears in audit logs, messages, and is used for per-server cooldown tracking.

server:
  name: "Survival"      # On Server A

server:
  name: "Skyblock"      # On Server B

Step 3 — Link Mode

server:
  link-mode: shared     # or "separate"

Mode	Behaviour
shared	One link works across all servers. Player links once on any server.
separate	Players must link independently on each server. Separate linked_accounts records per server.

shared is recommended for networks where players move between servers freely.

Step 4 — Cooldown Mode (Boost Rewards)

boost-rewards:
  cooldown-mode: global     # or "per-server"

Mode	Behaviour
global	One shared cooldown. Player can claim on any server, but only once per period.
per-server	Separate cooldown per server. Player can claim once per server per period.

---

Per-Server vs Shared Features

Feature	Shared (recommended)	Per-Server
Account linking	link-mode: shared	link-mode: separate
Boost cooldowns	cooldown-mode: global	cooldown-mode: per-server
Level data	Always shared (same Discord ID)	N/A
Rank sync	Runs per-server (each server has own LuckPerms)	—
Chat bridge	Per-server (each has own channel ID)	—
Server stats	Per-server (each has own embed)	—
Logging	Per-server (each has own webhooks)	—

---

Identification in Logs

When a player links or performs an action, the server_name (from config) is recorded in the database and shown in audit log embeds. This lets you trace which server an event originated from.

Example audit embed field:

Server: Survival

---

Discord Bot Sharing

You can share one bot application across all servers — just use the same token in every server's config.yml. The bot only needs to be in the Discord server once.

Alternatively, use separate bots per Minecraft server if you want each bot to have a distinct Discord presence/username.

---

Startup Notes

• All servers will attempt to create the database tables on first start. This is safe — the tables use CREATE TABLE IF NOT EXISTS.
• Only the first server to start creates the tables. Subsequent servers detect existing tables and proceed normally.
• There is no "primary" server concept — all servers are equal peers sharing the same data.

---

Proxy / BungeeCord / Velocity

uxmDiscordSync runs on individual Paper backend servers. It is not a proxy plugin. Each backend server runs its own instance.

For BungeeCord / Velocity networks, the recommended setup is:

1. Install uxmDiscordSync on each backend that needs it.
2. Use a shared MySQL/PostgreSQL database.
3. Set link-mode: shared so players only need to link once.
4. Disable features like server-stats or chat-bridge on servers where they are not needed.