Overview

Awaiting approval v1.3.0

Platforms

Paper, Spigot, Folia

Minecraft

1.21 or newer

Java

21

Required

None

Optional

Vault, PlaceholderAPI, HeadDB

ReferralTrack shows which server list, video, Discord invite or friend brought each player to your server. Players tell the server where they came from with /referral or enter a friend's permanent invite code, and can earn a reward for it. Everything is stored in your own database (SQLite or MySQL/MariaDB). Nothing leaves the server except the Discord webhook you configure.

Requirements #

• Minecraft 1.21 or newer, Java 21.
• Paper, Spigot or Folia.
• Vault and a Vault-compatible economy plugin are optional and needed only for money rewards.
• PlaceholderAPI is optional.
• HeadDB and Head Database are optional and add custom heads to the menus. Without them a normal Bukkit material is used.

The database libraries are inside the jar, so the first start does not download anything.

Install #

1. Put ReferralTrack.jar in plugins/ and start the server.
2. Edit plugins/ReferralTrack/config.yml: your sources, rewards and the Discord webhook.
3. Run /referraltrack validate, then /referraltrack reload.
4. Run /referraltrack doctor to check the database, rewards and integrations.

What it does #

• Source codes. Players type /referral youtube (or any code you define). A mistyped known code, such as yotube, is matched to the closest one.
• Permanent personal codes. Every player gets a collision-safe invite code (for example RT-AB12CD3) bound to their UUID, so it survives a name change. Friend names and source codes keep working.
• Rewards. Money through Vault and/or console commands, with a limit per IP address, a same-IP check on friend invites, reward caps and invite milestones.
• Verified referrals (optional). Rewards and leaderboard credit can be held until the new player reaches a playtime and join threshold. Off by default.
• Fraud review (optional). Explainable risk signals can hold a referral for staff to approve or reject.
• Campaigns (optional). Time-boxed campaigns with their own dates, codes, multipliers, rewards and milestones.
• Player hub. /referral opens a personal menu with the player's code, source, validation state and rewards. On servers that support it the hub can open as a native Java dialog.
• Staff tools. Dashboard, analytics, growth ranking, Reward Rescue, configuration validation and a health report.
• Discord. Instant cards, daily and weekly reports and a live stats message, each routable to its own channel.
• Presets and themes. Seven starting presets and three visual themes, applied only with a confirmation and a backup.
• Languages. English, Turkish, Spanish, German and Brazilian Portuguese.

Networks #

On a network, set settings.join-tracking-enabled to true on one entry server (for example the lobby) and false on the others, and point every server at the same MySQL/MariaDB database. Set settings.reward-delivery-enabled to true only on the server where your real economy lives. Rewards claimed elsewhere are stored as pending and delivered at the next login there. Each reward row has one active delivery owner across servers.

Behind BungeeCord or Velocity, enable IP forwarding on the proxy. Without it every player shows the proxy's address and the per-IP checks would block everyone. SQLite is not shared storage; a network needs MySQL/MariaDB.

Upgrading #

ReferralTrack never silently replaces a customized config.yml. When the config version changes it keeps the original as config.yml.bak-v<old>, writes the complete new reference to config.new-v<new>.yml, changes only the version marker in your file and lists missing paths at startup. Bundled defaults keep new options working until you copy them over. Language files you have edited are not overwritten; missing keys fall back to the bundled English text.