Home › AjdnikovRewards++ › Documentation

📚 AjdnikovRewards++ Documentation

Version: 1.0.0 | Platform: Paper 1.21+ | Author: Ajdnikov

Overview

AjdnikovRewards++ is a comprehensive staff management and playtime reward plugin for Paper/Spigot Minecraft servers. It tracks player playtime, monitors staff moderation actions, automatically grants configurable rewards, and integrates deeply with Discord for account linking, role syncing, and automated weekly reports.

Features

  • Playtime Tracking — Accurate per-second tracking with AFK detection
  • Reward System — Playtime-based, moderation-based, and combined reward triggers
  • Staff Moderation Tracking — Automatically tracks bans, warns, mutes, and kicks
  • Staff Rewards — Reward staff members for performing moderation actions
  • Staff Streaks & Promotions — Automatic role promotions for consistent staff activity
  • Discord Bot — Full JDA-based Discord bot with slash commands
  • Account Linking — Minecraft ↔ Discord account linking with code-based verification
  • Role Sync — Automatic LuckPerms → Discord role synchronization
  • Weekly Reports — Automated Discord reports summarizing server activity
  • Admin GUI — In-game chest GUI for managing rewards, config, and player lookups
  • Database Support — SQLite (default) or MySQL/MariaDB via HikariCP
  • Vault & LuckPerms — Economy payouts and permission-based roles
  • MiniMessage — Full MiniMessage formatting support for all messages

Installation

  1. Place AjdnikovRewards.jar in your server's plugins/ folder
  2. Start the server — the plugin will generate default config files
  3. Stop the server and edit plugins/AjdnikovRewards/config.yml:
  • Set your Discord bot-token
  • Set your Discord guild-id
  • Configure database settings if using MySQL
  1. Customize rewards in rewards.yml and staff-rewards.yml
  2. Start the server

Configuration Files

config.yml

The main configuration file. Located at plugins/AjdnikovRewards/config.yml.

Section Key Default Description
Discord bot-token YOUR_BOT_TOKEN_HERE Discord bot token
guild-id YOUR_GUILD_ID Discord server ID
Linking linking.require-link false Force players to link Discord to play
linking.link-code-expiry 600 Link code validity in seconds
linking.limbo-world limbo World for unlinked players (if require-link)
linking.tab-suffix true Show [Linked]/[Unlinked] in tab list
Playtime playtime.afk-detection true Enable AFK detection
playtime.afk-threshold 300 Seconds of inactivity to mark as AFK
playtime.exclude-afk true Exclude AFK time from playtime
playtime.autosave-interval 5 Minutes between auto-saves
playtime.check-interval 60 Seconds between reward eligibility checks
Database database.type sqlite sqlite or mysql
database.host localhost MySQL host
database.port 3306 MySQL port
database.name playtimerewards MySQL database name
database.username root MySQL username
database.password (empty) MySQL password
database.pool.* — HikariCP connection pool settings
Discord Settings discord.staff-role-id YOUR_STAFF_ROLE_ID Discord role for staff commands
discord.announcement-channel (empty) Default announcement channel ID
discord.bot-status Watching {online} players online Bot activity status
Moderation moderation-tracking.enabled true Track staff moderation actions
moderation-tracking.track-commands [ban, tempban, mute, tempmute, warn, kick] Commands to intercept
Staff Streaks staff-streaks.enabled true Enable staff streak system
staff-streaks.interval-days 7 Streak evaluation interval
staff-streaks.playtime-goal-seconds 72000 Playtime goal per interval
staff-streaks.promotions — Streak → command mappings
Weekly Report weekly-report.enabled true Enable automated weekly reports
weekly-report.day SUNDAY Day of week to send report
weekly-report.time 00:00 Time (24h HH:MM) to send report
weekly-report.channel (empty) Override channel ID
Messages messages.* — All plugin messages (MiniMessage format)
Debug debug false Enable verbose debug logging

rewards.yml

Defines player playtime rewards. Located at plugins/AjdnikovRewards/rewards.yml.

Full reward structure:

rewards:
  example_reward:
    enabled: true                    # Whether this reward is active
    type: PLAYTIME                   # PLAYTIME, MODERATION, or COMBINED
    one-time: true                   # true = grant once, false = repeating
    playtime-required: 3600          # Seconds of playtime needed
    repeat-interval: 86400           # (Repeating only) Seconds between re-grants
    cooldown: 0                      # Minimum seconds between claims
    display-name: "Example Reward"   # Display name in GUIs and messages
    description: "An example"        # Description text
    value: 10                        # Staff point value (for staff streaks)
    requires: "other_reward_id"      # Prerequisite reward ID

    # Moderation requirements (for MODERATION/COMBINED types)
    moderation:
      bans: 0
      warns: 0
      mutes: 0
      kicks: 0
      period: WEEKLY                 # DAILY, WEEKLY, or MONTHLY

    # Minecraft payouts
    minecraft:
      money: 1000                    # Vault economy amount
      roles:                         # LuckPerms groups to add
        - "example_role"
      commands:                      # Console commands ({player} placeholder)
        - "give {player} diamond 5"
      items:                         # Native Bukkit ItemStack serialization
        - ==: org.bukkit.inventory.ItemStack
          v: 3465
          type: DIAMOND
          amount: 5

    # Discord payouts
    discord:
      roles:                         # Discord role names to add
        - "Veteran"
      dm-message: "Congrats!"        # DM to send on claim
      announcement-channel: ""       # Channel ID for public announcement
      announcement-message: ""       # Public announcement text

Default rewards included:

ID Type Trigger Payout
playtime_1h One-time 1h playtime $1,000 + 5 Diamonds
playtime_10h One-time 10h playtime $10,000 + 10 Emeralds
playtime_24h One-time 24h playtime $25,000 + 1 Diamond Block
playtime_50h One-time 50h playtime $50,000 + 2 Netherite Ingots
veteran_player One-time 500h playtime $500,000 + Veteran rank + Discord role
daily_playtime Repeating (24h) 1h/day $500
weekly_playtime Repeating (7d) 10h/week $10,000

staff-rewards.yml

Defines staff moderation rewards. Located at plugins/AjdnikovRewards/staff-rewards.yml.

Default staff rewards included:

ID Type Trigger Payout Points
active_moderator MODERATION 3 bans/week $5,000 50
warning_duty MODERATION 5 warns/week $2,000 20
mute_master MODERATION 10 mutes/week $3,000 30
swift_justice MODERATION 15 kicks/week $2,500 25
ban_hammer_monthly MODERATION 20 bans/month $20,000 150
dedicated_staff COMBINED 10h playtime + 5 bans/month $15,000 100
staff_of_the_month COMBINED 50h playtime + 15 bans/month $50,000 300

Commands

Player Commands (Minecraft)

Command Permission Description
/link ptr.link Generate a 6-digit code to link your Discord account
/unlink ptr.link Unlink your Discord account
/playtime [player] ptr.playtime View your or another player's playtime
/playtimetop [page] ptr.playtime View the playtime leaderboard
/rewards [player] ptr.rewards View earned rewards

Admin Commands (Minecraft)

Command Permission Description
/ptr or /ptr admin ptr.admin Open the admin GUI
/ptr reload ptr.admin.reload Reload all config files
/ptr forcepayout ptr.admin.forcepayout Force-grant a reward to a player
/ptr linkrole ptr.admin.linkrole Link a LuckPerms group to a Discord role
`/stafflink unlink>` ptr.admin.link Force-link/unlink a player's Discord
/rewardgive ptr.admin.reward Manually grant a reward
/rewardrevoke ptr.admin.reward Revoke a reward from a player
/weeklyreport ptr.admin.report Manually trigger the weekly Discord report

Aliases: /ptr can also be used as /ptrconfig or /playtimerewards.

Discord Slash Commands (Player)

Command Description
/link Link your Minecraft account using a 6-digit code
/unlink Unlink your Minecraft account
/playtime [username] Check your or someone's playtime
/rewards [username] View earned and pending rewards
/leaderboard View the playtime leaderboard
/profile View your linked profile

Discord Slash Commands (Staff)

These require the configured staff-role-id Discord role.

Command Description
/stafflink Force-link a Minecraft account to a Discord user
/rewardgive Manually grant a reward to a player
/rewardrevoke Revoke a reward from a player
/setplaytime Set a player's playtime (e.g. 2d 5h 30m)
/playerinfo View detailed player info
/ptrreload Reload plugin configuration
/syncall Re-check all online players for rewards
/weeklyreport Manually trigger the weekly Discord report
/linkrole Link a Discord role to a LuckPerms group

Permissions

Permission Default Description
ptr.link true Link/unlink Discord account
ptr.playtime true View playtime
ptr.playtime.others true View other players' playtime
ptr.rewards true View earned rewards
ptr.admin op Access admin commands and GUI
ptr.admin.link op Force link/unlink players
ptr.admin.reward op Manually give/revoke rewards
ptr.admin.reload op Reload plugin configuration
ptr.admin.setplaytime op Override player playtime
ptr.admin.report op Trigger weekly report
ptr.* op All PTR permissions

Reward System

Reward Types

Type Trigger Config File
PLAYTIME Accumulated playtime reaches the threshold rewards.yml
MODERATION Staff moderation action counts meet requirements staff-rewards.yml
COMBINED Both playtime AND moderation thresholds must be met staff-rewards.yml

Reward Payouts

Each reward can grant any combination of:

One-Time vs Repeating

Prerequisites

Any reward can require another reward to be earned first:

advanced_reward:
  requires: "basic_reward"  # Player must have basic_reward first

Staff Moderation Tracking

The plugin automatically intercepts moderation commands from supported punishment plugins and tracks them per-staff-member.

Supported plugins:

  • Essentials
  • LiteBans
  • AdvancedBan
  • LibertyBans

Tracked action types:

  • BAN / TEMPBAN
  • WARN
  • MUTE / TEMPMUTE
  • KICK
  • UNBAN
  • UNMUTE

You can add custom command aliases in config.yml under moderation-tracking.track-commands.

Staff Streaks & Promotions

The streak system evaluates staff activity on a configurable interval (default: weekly) and tracks consecutive periods of meeting goals.

staff-streaks:
  enabled: true
  interval-days: 7              # Evaluation interval
  playtime-goal-seconds: 72000  # 20 hours per interval
  promotions:
    2:                           # After 2 consecutive streaks
      - "lp user {player} parent add sr_mod"
    4:                           # After 4 consecutive streaks
      - "lp user {player} parent add admin"

Streaks reset to 0 if the goal is not met in a given period.

Discord Integration

Bot Setup

  1. Create a Discord application at discord.com/developers
  2. Create a Bot user and copy the token
  3. Enable the following Gateway Intents:
  • GUILD_MEMBERS
  • GUILD_MESSAGES
  • DIRECT_MESSAGES
  1. Invite the bot to your server with applications.commands and bot scopes
  2. Set the token and guild ID in config.yml

Account Linking

  1. Player runs /link in Minecraft → receives a 6-digit code
  2. Player runs /link in Discord → accounts are linked
  3. Staff can force-link with /stafflink

Role Sync

LuckPerms groups can be synced to Discord roles:

  1. In-game: /ptr linkrole
  2. Discord: /linkrole

This stores the mapping as LuckPerms group metadata (discord_role_id). When a player's LuckPerms group changes, their Discord roles are automatically updated.

Weekly Reports

An automated summary is posted to Discord every week containing:

  • Top players by playtime
  • Total moderation actions
  • Rewards granted during the period
  • Staff activity summary

Configure the day, time, and channel in config.yml under weekly-report.

Admin GUI

Access with /ptr or /ptr admin. The GUI provides:

Button Description
⭐ Server Statistics Tracked players, linked accounts, rewards given today
💎 Manage Rewards View, toggle, and delete playtime rewards
⚡ Staff Rewards View, toggle, and delete staff moderation rewards
⚙️ Configuration Edit plugin settings
👤 Player Lookup View player stats and manage links
🔴 Reload Plugin Reload all config files from disk

Reward Editor actions:

  • Left-Click — Edit reward settings
  • Shift-Click — Toggle enabled/disabled
  • Right-Click — Delete the reward

Database

Tables

Table Purpose
ptr_players Player UUID, username, playtime, last seen
ptr_reward_history Reward claim history per player
ptr_staff_actions Moderation action log (who, what, when)
ptr_staff_streaks Staff streak tracking

SQLite

Default. The database file is located at plugins/AjdnikovRewards/data.db. No additional setup required.

MySQL / MariaDB

Set database.type: mysql in config.yml and configure host, port, credentials, and pool settings. Uses HikariCP for connection pooling.

Dependencies

Dependency Required Purpose
Paper 1.21+ ✅ Yes Server platform
Vault ⚠️ Soft Economy payouts
LuckPerms ⚠️ Soft Permission groups and role sync
PlaceholderAPI ⚠️ Soft Placeholder integration
Essentials ⚠️ Soft Moderation command interception
LiteBans ⚠️ Soft Moderation command interception
AdvancedBan ⚠️ Soft Moderation command interception
LibertyBans ⚠️ Soft Moderation command interception

The plugin will work without soft dependencies but the corresponding features will be disabled.

Placeholders

If PlaceholderAPI is installed, the following placeholders are available:

Placeholder Description
%ptr_playtime% Formatted playtime
%ptr_playtime_raw% Raw playtime in seconds
%ptr_linked% true or false
%ptr_rewards_earned% Number of rewards earned
%ptr_afk% true or false

Troubleshooting

"No enum constant ... STAFF_ACTION"

The staff-rewards.yml on your server still has type: STAFF_ACTION from an older version. Delete the file from plugins/AjdnikovRewards/ and restart — the plugin will regenerate it with the correct type: MODERATION values.

Discord bot not starting

  • Verify bot-token is correct (not YOUR_BOT_TOKEN_HERE)
  • Ensure the bot has the required Gateway Intents enabled in the Discord Developer Portal
  • Check that guild-id matches your Discord server

Rewards not granting

  • Check that the reward is enabled: true
  • Verify check-interval in config — rewards are checked periodically, not instantly
  • For staff rewards, ensure moderation-tracking.enabled: true
  • Use /ptr forcepayout to test manually

Database connection issues (MySQL)

  • Verify credentials and that the database exists
  • Check firewall rules for port 3306
  • Review HikariCP pool settings if seeing timeout errors

AjdnikovRewards++ v1.0.0 — Built by Ajdnikov