ReferralRewards (plugin)

Gives every player a permanent referral code. When a new player enters a friend's code, both players get store credit on the Azuriom website.

What it does

• Gives each player one 7-character code that never changes. Codes use letters and digits, with look-alike characters left out (no I, O, 0 or 1).
• Lets a new player redeem one friend's code, once, within 30 days of their first join.
• On a valid redemption, credits both players' Azuriom website accounts through the AzLink API ($5.00 each by default).
• Creates the website accounts ahead of time if they do not exist yet. When the player later signs into the website with Microsoft/Minecraft login, Azuriom finds that account and the credit is already there.
• Saves codes and redemptions in MariaDB.

Rules it enforces:

• One code per player, forever.
• A player can redeem a code only once.
• A player cannot redeem their own code.
• The code must be redeemed within eligible-days-after-first-join days of the player's first join (Bukkit's first-played time).
• If the website credit fails for any reason, the redemption is not saved and the player can try again later.

How players use it

Share your code:

/referral

You see your code, for example K7M2QXA. Click the first line to copy the code. Click the second line to copy the full command /referral K7M2QXA to send to a friend.

Use a friend's code (new players only, within 30 days of first join):

/referral K7M2QXA

Codes are not case-sensitive. You see "Checking referral data..." and then the result. On success: "Referral accepted. Steve received $5.00 and you received $5.00 in Azuriom credit."

/refer works the same as /referral. To spend the credit, sign into the website with your Minecraft account.

Staff guide

/referral status and /referral reload need referralrewards.admin (op by default).

Task	Command
See reward amounts, eligibility window, and whether the Azuriom API is on	/referral status
Re-read config.yml and reconnect to MariaDB	/referral reload

The /referral command itself has no permission node. That means CommandWhitelist is the only gate for players. referral and refer must both be in the CommandWhitelist list, or non-ops get "No such command." Ops skip the whitelist, so test as a non-op.

/referral is also a button in the /menu Profile page.

Configuration

plugins/ReferralRewards/config.yml. /referral reload re-reads it and reconnects to the database, so no restart is needed for config changes.

Section	What it is for
server-name	This server's Velocity key (for example main). Saved on each redemption.
database	MariaDB login and pool size.
referrals.code-length	Length of new codes. Existing codes do not change.
referrals.eligible-days-after-first-join	How long a new player has to redeem a code.
referrals.referrer-reward-amount	Credit for the player who shared the code.
referrals.referred-reward-amount	Credit for the new player. A value of 0 skips that credit.
azuriom.enabled	Turn the website credit on or off. If off, every redemption fails as "credit failed".
azuriom.base-url, azuriom.server-token	The website address and the AzLink server token. Keep the real token only on the server.
azuriom.server-id	Must match the Azuriom server ID used by AzLink. The /api/azlink lookup needs it.
azuriom.create-missing-users	Create website accounts for players who do not have one yet.
azuriom.uuid-format	undashed (default, matches how Azuriom stores Minecraft logins) or hyphenated.
messages	Player-facing text. & color codes. {referrer}, {referrer_amount}, {referred_amount}, {days} are filled in.

Older configs with referrals.reward-amount still work. It is used as the referrer amount when referrer-reward-amount is missing.

Data and storage

MariaDB, in the database named in database.url. The plugin creates both tables on start.

Table	Holds
referral_players	Each player's UUID, latest name, first join time, and permanent code
referral_redemptions	One row per referred player: who referred them, the code, both reward amounts, whether Azuriom was credited, the server, and when

A player row is created the first time they join with the plugin loaded (or run /referral). Do not edit codes by hand; players may have shared them. Deleting a row in referral_redemptions lets that player redeem again, and they would be paid again.

Troubleshooting

Symptom	Cause	Fix
Non-op gets "No such command."	referral/refer missing from CommandWhitelist	Add both labels and reload CommandWhitelist
"Referral was not recorded because the Azuriom credit could not be applied."	Azuriom is off, unreachable, the token or server-id is wrong, or a user id could not be found	Check /referral status, the token and server-id, then check the server log for the error
"You can only use a referral code within 30 days of your first join."	The player joined too long ago	Expected. Change eligible-days-after-first-join if the rule should change
"Could not redeem that referral code right now."	Database or network error	Check the server log for Failed to redeem referral code
Plugin disabled at boot	Could not connect to MariaDB	Check database settings. The log shows Failed to enable ReferralRewards: with the reason

Boot log line that means it loaded: [ReferralRewards] ReferralRewards enabled.

Maintainer notes

• Azuriom call order for each rewarded player:
• POST /api/azlink/register sends the player's name and UUID as game_id. If the account already exists, Azuriom updates the name and returns success.
• POST /api/azlink with one player entry and platform.key = "uid", to find the numeric Azuriom user id in the returned users[] list.
• POST /api/azlink/user/{id}/money/add adds the reward.
• If create-missing-users is off, the plugin looks up the user first and only registers them if the lookup finds nothing.
• The redemption runs in one database transaction. It is only committed after both credits succeed.
• Known gap: the referrer is credited first, then the new player. If the first credit works and the second fails, the referrer keeps the money but no redemption is saved. If the new player retries, the referrer is paid again.
• messages.code in config.yml is not used. The code message is built in Java so it can be clickable.
• A player's first join time is kept at the earliest value ever seen, so it cannot move later.
• HikariCP and the MariaDB driver are bundled in the jar. AzLink is a soft dependency only; the plugin talks to the website over HTTP.

Building

../HubCompass/gradlew -p . build

This folder has no Gradle wrapper of its own, so it borrows one from a sibling plugin. Java 21. Output: build/libs/ReferralRewards-<version>.jar.

Full command, permission and config tables: Reference.