MysticalReferral

MysticalReferral

A feature-rich referral and invite reward system plugin for Minecraft Paper servers.

Players can generate invite codes, share them with friends, and both parties receive configurable rewards when a code is used.

---

Features

- Fully configurable - short, unique, easy-to-share codes with click-to-copy - Fully configurable - fully configurable console commands for both inviter and invited player - Fully configurable - bonus rewards at configurable invite thresholds (5, 10, 25, 50, etc.) - Fully configurable - rewards are queued and delivered when offline inviters come back online - Fully configurable - configurable sounds and title screens on successful referrals - Fully configurable - players can view who they've referred and when - Fully configurable - server-wide top referrers ranking - Fully configurable - personal referral statistics - Fully configurable - info, reset, and setcode commands for server administrators - Fully configurable - optional time-limited referral codes - Fully configurable - expose referral data to scoreboards, chat, etc. - Fully configurable - notifies admins of new versions on login - Fully configurable - Self-referral prevention - One-time use per player - Configurable minimum playtime requirement - Optional IP address check to block alt-account abuse - Fully configurable with HikariCP connection pooling - Fully configurable - players with permission can set their own vanity codes - Fully configurable - automatically rewards top N referrers on a daily/weekly schedule - Fully configurable - automatic config migration when new settings are added (no manual deletion needed) - Fully configurable messages, rewards, effects, and settings

---

Requirements

- Minecraft MySQL 8.0+ - MySQL 8.0+ server (or forks like Purpur) - MySQL 8.0+ - MySQL 8.0+ database

Optional Dependencies

- PlaceholderAPI - for placeholder support in chat, scoreboards, etc.

---

Installation

1. Download `MysticalReferral-1.0.0.jar` 2. Place the JAR in your server's `plugins/` folder 3. Start the server once to generate `config.yml` 4. Edit `plugins/MysticalReferral/config.yml` with your MySQL credentials 5. Restart the server or run `/referral reload`

---

Building from Source

```bash git clone https://github.com/your-org/MysticalReferral.git cd MysticalReferral mvn clean package ```

The compiled JAR will be at `target/MysticalReferral-1.0.0.jar`.

Build requirements: Java 21, Maven 3.9+

---

Configuration

Database

```yaml database: host: localhost port: 3306 name: mysticalreferral username: root password: password pool: maximum-pool-size: 10 minimum-idle: 2 connection-timeout: 30000 idle-timeout: 600000 max-lifetime: 1800000 ```

Create the database beforehand:

``` CREATE DATABASE mysticalreferral; ```

Settings

```yaml settings: code-length: 5 min-playtime-minutes: 10 allow-ip-referrals: false leaderboard-size: 10 code-expiration-days: 0 language: en update-checker: true ```

Rewards

Rewards are executed as console commands. Use `%player%` as a placeholder for the player's name.

```yaml rewards: inviter: commands: - "give %player% diamond 2" - "eco give %player% 500" invited: commands: - "give %player% diamond 1" - "eco give %player% 100" ```

Milestone Rewards

```yaml milestones: 5: commands: - "give %player% emerald 5" message: "&a&lMilestone! &eYou reached &b5 &einvites!" 10: commands: - "give %player% emerald 16" - "eco give %player% 2000" message: "&a&lMilestone! &eYou reached &b10 &einvites!" ```

Effects

```yaml effects: sound: enabled: true type: ENTITY_PLAYER_LEVELUP volume: 1.0 pitch: 1.0 title: enabled: true title: "&a&lReferral Used!" subtitle: "&7You and &e%player% &7received rewards!" inviter-title: enabled: true title: "&a&lNew Referral!" subtitle: "&e%player% &7used your code!" ```

Custom Referral Codes

```yaml custom-codes: enabled: true min-length: 3 max-length: 16 allowed-pattern: "^[A-Za-z0-9_]+$" force-uppercase: true ```

Top Referrer Scheduled Rewards

```yaml top-rewards: enabled: false interval-minutes: 1440 top-count: 3 broadcast: true positions: 1: commands: - "give %player% netherite_ingot 3" message: "#1 Top Referrer! Congrats %player%!" ```

---

Commands

| Command | Description | Permission | |---|---|---| | `/invite` | Generate or view your referral code (click-to-copy) | `mysticalref.invite` | | `/invite set <code>` | Set a custom vanity referral code | `mysticalref.customcode` | | `/ref <code>` | Use a referral code | `mysticalref.use` | | `/referral stats` | View your referral stats | `mysticalref.referral` | | `/referral top` | View the leaderboard | `mysticalref.referral` | | `/referral history` | View who you've referred | `mysticalref.referral` | | `/referral reload` | Reload configuration | `mysticalref.reload` | | `/referral admin info <player>` | View a player's referral info | `mysticalref.admin` | | `/referral admin reset <player> [confirm]` | Reset a player's referral data | `mysticalref.admin` | | `/referral admin setcode <player> <code>` | Set a custom referral code | `mysticalref.admin` |

---

License

This project is provided as-is for use on Minecraft servers.