🚀 NCode — The Ultimate Player Referral System

NCode is a lightweight, professional, and feature-packed player referral system built for modern Minecraft servers. Whether you run a single Paper server or a large multi-threaded network on Folia, NCode delivers a seamless, lag-free experience for your community.

Stop using outdated, text-only referral plugins. Upgrade to NCode for an interactive Visual Reward Editor, native NBT item support, and high-performance data caching.

---

✨ Key Features

📱 Advanced Reward System (RNG)

• True probabilities: Configure prizes with exact drop chances (e.g., 5.5% for a Mythic Sword, 100% for an economy boost).
• Native NBT support: Deliver physical items with enchantments, custom names, lore, and CustomModelData preserved exactly as created in-game.
• Command execution: Run multiple console commands automatically when a referred player meets your configured playtime requirement.

🖥️ Immersive Visual Editor

• In-game GUI: Forget complex YAML edits—manage rewards and drop chances in-game with /ncode editor.
• Live adjustments: Fine-tune probabilities with intuitive controls (Left-click: +1%, Shift+Left: +0.1%, Right-click: -1%, Q: delete).
• Top 10 leaderboard: A visual menu showing the heads of the players with the most referrals to encourage competition.

⚡ High Performance & Folia-Ready

• Smart caching: Uses Caffeine Cache to keep active player data in RAM and automatically purge it after 15 minutes of inactivity.
• Engine detection: Automatically detects Folia and uses GlobalRegionScheduler / EntityScheduler to avoid thread-related crashes.
• Dual storage: Use local YAML for smaller servers or MySQL/MariaDB (via HikariCP) for large networks.

---

🛠️ Commands & Permissions

Command	Permission	Description
/ncode	ncode.use	Open the main referral GUI.
/ncode reference <code>	ncode.use	Use the referral code of the player who invited you.
/ncode create <code>	ncode.create	Create a custom 6-character referral code.
/ncode top	ncode.top	Open the visual Top 10 referrers leaderboard.
/ncode renamecode <code>	ncode.rename	Change your existing referral code.
/ncode editor	ncode.admin	Open the Visual Reward Editor GUI.
/ncode additem <chance> <group>	ncode.admin	Add the item in your hand to the reward pool.
/ncode addcmd <chance> <group> <command>	ncode.admin	Add a console command to the reward pool.
/ncode check <player>	ncode.check	Check playtime since a player used a code.
/ncode info <player>	ncode.admin	View a user’s referral status and points.
/ncode setcode <player> <code>	ncode.admin	Force-assign a specific code to a player.
/ncode deletecode <code>	ncode.delete	Delete a specific code from storage.
/ncode reset <player>	ncode.admin	Wipe a player’s referral history and points.
/ncode reload	ncode.reload	Reload configuration and language files.

Global permission: ncode.* — Grants access to all NCode commands and features (recommended only for server administrators).

📋 Detailed Permissions

• ncode.use — Basic player commands (/ncode, /ncode reference). Assigned to all players by default.
• ncode.create — Allows /ncode create. Assigned to operators by default.
• ncode.top — Allows /ncode top. Assigned to all players by default.
• ncode.rename — Allows /ncode renamecode (ideal for VIP ranks).
• ncode.check — Allows checking referral playtime. Assigned to operators.
• ncode.delete — Allows deleting codes. Assigned to operators.
• ncode.reload — Allows reloading the plugin. Assigned to operators.
• ncode.admin — Admin tools (/ncode editor, /ncode info, /ncode reset, /ncode setcode, /ncode additem, /ncode addcmd). Assigned to operators.

---

📸 Gallery

---

⚙️ Configuration

NCode generates clean, easy-to-use configuration files. Below you can see example defaults.

📂 config.yml

#~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~#
# NCode by NovaPixel
# Main Configuration File (v1.1.0)
#~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~#

language: "en"

prefix: "color:#8652ff<b>NCODE</b></color> <dark_gray>»</dark_gray> "

storage:
  type: "YAML"
  database:
    host: "localhost"
    port: 3306
    database: "ncode_data"
    username: "user"
    password: "password"
    pool_settings:
      maximumPoolSize: 10
      connectionTimeout: 30000
      idleTimeout: 600000
      maxLifetime: 1800000
    properties:
      useSSL: true
      verifyServerCertificate: false

menu:
  items:
    create:
      material: BIRCH_SIGN
    view:
      material: PLAYER_HEAD
      texture: "eyJ0ZXh0dXJlcyI6eyJTS0lOIjp7InVybCI6Imh0dHA6Ly90ZXh0dXJlcy5taW5lY3JhZnQubmV0L3RleHR1cmUvMWMxZjljZTAwMjgyZDViZjZiYjA1ZDJkOTBiN2ZiMTI2ZmNhNTRiZGRjNTRjODc4MjIxNGNkYmFmNDA1MWI3ZSJ9fX0="

check-interval: 60

rewards:
  points-per-referral: 1
  playtime_requirement:
    amount: 5
    unit: minutes

referrer_rewards:
  basic_money:
    chance: 100.0
    type: COMMAND
    command: "eco give {player} 1000"

  extra_diamonds:
    chance: 50.0
    type: ITEM
    item:
      material: DIAMOND
      amount: 3
      name: "<aqua><bold>Reward Diamonds</bold></aqua>"
      lore:
        - "<gray>Granted for inviting an active friend."

referred_rewards:
  starter_kit:
    chance: 100.0
    type: COMMAND
    command: "give {player} iron_ingot 10"

💬 messages_en.yml

# GUI Menu Texts
menu_text:
  title: "<bold>gradient:#8A2BE2:#4169E1Referral Menu</gradient></bold>"

create:
  name: "<!i><bold>gradient:#50C878:#98FB98Create My Code</gradient></bold>"
  lore:
    - ""
    - "<!i><white>▪ <gray>Generate your unique 6-digit code."
    - "<!i><white>▪ <gray>Share it with your friends to earn"
    - "<!i><gray>  rewards when they play."
    - ""
    - "<!i>color:#DDFF00► Click to Generate!</color>"

view:
  name: "<!i><bold><aqua>My Information</aqua></bold>"
  lore:
    - ""
    - "<!i><white>▪ <gray>Your Code: {code}"
    - "<!i><white>▪ <gray>Referred by: color:#E643FF{referrer}</color>"
    - ""
    - "<!i><white>▪ <gray>Use <yellow>/ncode reference <code></yellow>"
    - "<!i><gray>  to be referred by someone."

top_title: "<gold><bold>Top 10 Referrers</bold></gold>"
top_item:
  lore:
    - ""
    - "<!i><gray>Players invited:"
    - "<!i><green>⭐ {points} friends</green>"
    - ""

editor_title: "<dark_red><bold>Reward Editor</bold></dark_red>"

# Chat Messages
messages:
  welcome: "click:run_command:/ncode<hover:show_text:'<gray>Click here to get your code!'>gradient:#00ff00:#00ff72CLICK HERE TO CREATE YOUR REFERRAL CODE! [✨]</gradient></hover></click>"
  your-code: "<gray>Your current referral code is: <gold><hover:show_text:'<gray>Click to copy'>click:copy_to_clipboard:{code}{code}</click></hover></gold></gray>"
  no-code: "<yellow>You haven't generated a code yet. Use color:#A781FF/ncode</color> to create one.</yellow>"
  notify-referrer: "<green>Congratulations! <aqua>{player}</aqua> has used your referral code.</green>"
  notify-reward-processed: "<green>Reward Unlocked! <aqua>{invited_player}</aqua> completed the playtime requirement. You earned <gold>{points}</gold> point(s).</green>"
  notify-reward-received: "<green>Congratulations! You have played enough time after using a referral code. You received your reward!</green>"

  code-created: "<green>Success! Your code <gold><hover:show_text:'<gray>Click to copy'>click:copy_to_clipboard:{code}{code}</click></hover></gold> has been created.</green>"
  code-used: "<green>Code applied! You were referred by <aqua>{player}</aqua>.</green>"
  reload-success: "<green>NCode configuration and language have been reloaded!</green>"
  code-deleted: "<green>The code <yellow>{code}</yellow> has been deleted from storage.</green>"
  check-time: "<green>Player <aqua>{player}</aqua> has been using a code for <yellow>{minutes}</yellow> minutes.</green>"
  setcode-success: "<green><yellow>{player}</yellow>'s code has been forced to: <aqua>{code}</aqua></green>"
  reset-success: "<red><yellow>{player}</yellow>'s history and codes have been reset.</red>"
  rename-success: "<green>You have successfully renamed your code to <yellow>{code}</yellow>!</green>"
  reward-deleted: "<green>Reward deleted successfully.</green>"

  already-created: "<red>You already have an assigned referral code!</red>"
  already-used: "<red>You have already used a referral code before!</red>"
  code-in-use: "<red>That code is already registered or in use by another player!</red>"
  invalid-code: "<red>The entered code is invalid or does not exist.</red>"
  no-self-reference: "<red>You cannot use your own referral code!</red>"
  no-permission: "<red>You don't have permission to perform this action.</red>"

misc:
  no-code-value: "<white>None</white>"
  no-referrer-value: "<white>Nobody</white>"
  unknown-player: "<white>Unknown</white>"
  group-referrer: "<gold>Referrer</gold>"
  group-referred: "<aqua>Referred</aqua>"
  editor-group: "Group"
  editor-chance: "Chance"
  editor-controls:
    - "<yellow>L-Click: <white>+1%</white> | <yellow>Shift+L: <white>+0.1%</white>"
    - "<yellow>R-Click: <white>-1%</white> | <yellow>Q Key: <red>Delete</red>"

---

📥 Installation

• Download NCode.jar.
• Drop it into your server’s plugins/ folder.
• Restart the server.
• (Optional) Install PlaceholderAPI to use NCode placeholders (e.g., %ncode_my_code%, %ncode_invite_players%) in chat/scoreboards.