Documentation

Why using this plugin?

WARNING: In order to use the plugin, you must connect it to a database! (MySQL, MariaDB, PostegreSQL & SQLite supported)

Installation

This plugin requires Java 17+ and is compatible with Paper or Spigot servers version 1.21.x.

To install:

• Download the latest XPlayersTokens.jar file.

• Place it in your server’s plugins folder.

• Start the server to generate the default configuration files.

• Configure your database connection in the config.yml file.

• Restart your server.

---

Configuration

The main configuration file config.yml allows you to customize the plugin’s behavior, including database settings, token defaults, and command permissions.

Here, the config.yml file :

config.yml

#     ____  _____________.__                                   ___________     __
#    \   \/  /\______   \  | _____  ___.__. ___________  _____\__    ___/___ |  | __ ____   ____   ______
#    \     /  |     ___/  | \__  \<   |  |/ __ \_  __ \/  ___/ |    | /  _ \|  |/ // __ \ /    \ /  ___/
#    /     \  |    |   |  |__/ __ \\___  \  ___/|  | \/\___ \  |    |(  <_> )    <\  ___/|   |  \\___ \
#    /___/\  \ |____|   |____(____  / ____|\___  >__|  /____  > |____| \____/|__|_ \\___  >___|  /____  >
#    \_/                    \/\/         \/           \/                    \/    \/     \/     \/
# ╔═══════════════════════════════════════════════════════════╗
# ║           XPlayersTokens - Configuration                  ║
# ║                  by Alexandr3_                            ║
# ╚═══════════════════════════════════════════════════════════╝

config-version: 1 #Do not modify

# ┌─────────────────────────────────────────────────────────┐
# │                  DATABASE SETTINGS                      │
# └─────────────────────────────────────────────────────────┘

#IMPORTANT : You must link the plugin to a database!
#            Availables: mysql, sqlite, postgresql or mariadb
database:
  type: mysql
  host: "host"
  port: 3306
  database: "database"
  username: "root"
  password: "P@ssW0rD"
  hikari:
    maximum-pool-size: 20
    minimum-idle: 5
    connection-timeout: 30000 #(30s)
    idle-timeout: 600000 #(10min)
    max-lifetime: 1800000 #(30min)

# ┌─────────────────────────────────────────────────────────┐
# │                  TOKENS SETTINGS                        │
# └─────────────────────────────────────────────────────────┘

tokens:
  default: 25 # Starting tokens for new players
  set-default-when-reset: true # Reset to default tokens or 0 when command /tokens reset
  max: -1 # Maximum tokens a player can have (-1 = unlimited)

  # Command configuration
  # If chanched, need to restart server!
  command: "tokens" # Main command (without /)
  commands-alias-enable: true
  commands-alias:
    - "token"
    - "coins"

# ┌─────────────────────────────────────────────────────────┐
# │                  MESSAGES                               │
# └─────────────────────────────────────────────────────────┘

lang:
  # Availables : "fr", "en", "es", "de", "it", "pt", "ja", "zh", "ru"
  default: "en"

# ┌─────────────────────────────────────────────────────────┐
# │                  PERMISSIONS                            │
# └─────────────────────────────────────────────────────────┘

permissions:
  view: "xplayerstokens.view"
  view-others: "xplayerstokens.view.others"
  pay: "xplayerstokens.pay"
  top: "xplayerstokens.top"
  admin:
    add: "xplayerstokens.admin.add"
    set: "xplayerstokens.admin.set"
    remove: "xplayerstokens.admin.remove"
    reset: "xplayerstokens.admin.reset"
    clear: "xplayerstokens.admin.clear"
    view: "xplayerstokens.admin.view"
    reload: "xplayerstokens.admin.reload"
    maintenance: "xplayerstokens.admin.maintenance"

# ┌─────────────────────────────────────────────────────────┐
# │                  PLACEHOLDERS                           │
# └─────────────────────────────────────────────────────────┘

placeholders:
  # Cache duration for top players (in seconds)
  cache-duration: 60

  # Text displayed when data is not available
  not-available: "N/A"

# ┌─────────────────────────────────────────────────────────┐
# │                   PLAYERS TOP                           │
# └─────────────────────────────────────────────────────────┘

top: #Command /tokens top (nomber)
  default-limit: 10
  max-limit: 50

# ┌─────────────────────────────────────────────────────────┐
# │                   MAINTENANCE                           │
# └─────────────────────────────────────────────────────────┘

maintenance:
  enabled: false
  bypass-permission: true
  permission: "xplayerstokens.maintenance.bypass"

You can also manage language files in the lang/ folder to translate or customize all messages displayed by the plugin.

Languages already translated: EN, FR, IT, DE, ES, PT, JA, ZH & RU

Here, the lang/en.yml file :

lang/en.yml

# ┌─────────────────────────────────────────────────────────┐
# │                      LANG SETTINGS                      │
# │                         ENGLISH                         │
# └─────────────────────────────────────────────────────────┘

# NOTE:
# You can disable the message by leaving it blank. ("")
lang-version: 1 #Do not modify
# ───────────────────────────────────────────────────────────

prefix: "&8[&6XTokens&8]&r"

errors:
  no-permission: "%prefix% &cYou don't have permission."
  player-only: "%prefix% &cOnly players can use this command."
  player-not-found: "%prefix% &cPlayer &e%player% &cnot found."
  invalid-amount: "%prefix% &cAmount must be an integer >= 1."
  db-error: "%prefix% &cA database error occurred."
  insufficient-tokens: "%prefix% &cInsufficient balance."
  cannot-pay-self: "%prefix% &cYou cannot pay yourself."
  maintenance-mode: "%prefix% &cTransactions are currently disabled (maintenance mode)."
  invalid-limit: "%prefix% &cThe limit must be between 1 and %max%."
  no-players: "%prefix% &cNo players found in the database."

tokens:
  self-balance: "%prefix% &eYou have &6%tokens% tokens&e."
  other-balance: "%prefix% &b%player% &ahas &6%tokens% tokens&a."

  #admin
  added: "%prefix% &a+%amount% tokens &7to &e%player%&7."
  removed: "%prefix% &c-%amount% tokens &7from &e%player%&7."
  set: "%prefix% &7%player%'s tokens set to &6%amount%&7."
  cleared: "%prefix% &7%player%'s tokens cleared."
  reset: "%prefix% &7%player%'s tokens reset to &6%amount%&7."
  reloaded: "%prefix% &aConfiguration reloaded."

  #pay system
  pay-self: "%prefix% &cYou cannot pay yourself."
  pay-sent: "%prefix% &aYou sent &6%amount% tokens &ato &e%player%&a."
  pay-received: "%prefix% &aYou received &6%amount% tokens &afrom &e%player%&a."

  #notification
  balance-updated-add: "%prefix% &aYou received &6%amount% tokens &afrom &e%player%&a."
  balance-updated-set: "%prefix% &eYour balance has been set to &6%amount% tokens &eby &e%player%&e."
  balance-updated-remove: "%prefix% &c%amount% tokens &cwere removed by &e%player%&c."
  balance-updated-clear: "%prefix% &cYour balance has been cleared by &e%player%&c."
  balance-updated-reset: "%prefix% &eYour balance has been reset to &6%amount% tokens &eby &e%player%&e."

  #maintenance system
  maintenance-enabled: "%prefix% &cMaintenance mode &aenabled&c. Transactions are now blocked."
  maintenance-disabled: "%prefix% &aMaintenance mode &cdisabled&a. Transactions are now allowed."

  #player top
  top-header: "&6────── Top %limit% Players ──────"
  top-entry: "&6#%position% &f%player% &7- &e%tokens% tokens"
  top-footer: "&6──────────────────"

usage:
  admin: "%prefix% &fUsage: &6/tokens <add/set/remove/clear/view/reload> <player> [amount]"
  add: "%prefix% &fUsage: &6/tokens add <player> <amount>"
  set: "%prefix% &fUsage: &6/tokens set <player> <amount>"
  remove: "%prefix% &fUsage: &6/tokens remove <player> <amount>"
  pay: "%prefix% &fUsage: &6/tokens pay <player> <amount>"
  view: "%prefix% &fUsage: &6/tokens view <player>"
  top: "%prefix% &cUsage: /tokens top [limit]"

You can also activate the log system to view transactions between players!

Here, the logs.yml file parameter :

logs.yml

# ┌─────────────────────────────────────────────────────────┐
# │                      LOGS SETTINGS                      │
# └─────────────────────────────────────────────────────────┘

enabled: true
log-transactions: true #(transactions logs - add, remove...)
log-folder: "logs" #folder name for logs per day
date-format: "yyyy-MM-dd" #file name in folder

# Custom log message format
# Placeholders:
# %timestamp% -> 2026-01-27 14:30:45
# %executor%  -> Name of the person who ran the command
# %command%   -> The command executed
format: "[%timestamp%] (%executor%) executed: %command%"

---

Commands & Permissions

The plugin provides a set of commands to manage tokens and server economy. Each command requires specific permissions.

NOTES: You can configure your own permissions in the config.yml file seen above! You can also replace the /tokens command with whatever you want and add more with aliases!

Command main by default	Permission by default	Description
/tokens	xplayerstokens.view	View your own token balance
/tokens <player>	xplayerstokens.view.others	View another player’s token balance
/tokens pay <player> <amount>	xplayerstokens.pay	Send tokens to another player
/tokens top [limit]	xplayerstokens.top	Show the leaderboard of top token holders
/tokens add <player> <amount>	xplayerstokens.admin.add	Add tokens to a player (admin only)
/tokens set <player> <amount>	xplayerstokens.admin.set	Set a player’s token balance (admin only)
/tokens remove <player> <amount>	xplayerstokens.admin.remove	Remove tokens from a player (admin only)
/tokens clear <player>	xplayerstokens.admin.clear	Clear a player’s tokens (admin only)
/tokens reset <player>	xplayerstokens.admin.reset	Reset a player’s tokens to default (admin only)
/tokens reload	xplayerstokens.admin.reload	Reload plugin configuration and language files
/tokens maintenance	xplayerstokens.admin.maintenance	Toggle maintenance mode

---

PlaceholderAPI

Need PlaceholderAPI plugin installed in your server!

Here is a complete, ready-to-copy list of all PlaceholderAPI placeholders implemented by your PlaceholdersInteract class, plus usage notes, config options, and examples.

Placeholder	Description	Example output
%xplayerstokens_tokens%	Player's raw token balance (integer).	1250
%xplayerstokens_tokens_formatted%	Player balance formatted with thousands separator (,).	1,250
%xplayerstokens_tokens_rounded%	Player balance abbreviated (k / M / B).	1.2k
%xplayerstokens_rank%	Player rank in the leaderboard (1 = top). Returns N/A (configurable) if rank not available.	4
%xplayerstokens_top_<pos>_name%	Player name at leaderboard position <pos> (pos starts at 1). Returns configured not-available if out of range.	%xplayerstokens_top_1_name% → Notch
%xplayerstokens_top_tokens_<pos>%	Raw tokens of the player at position <pos>. Returns 0 if out of range.	%xplayerstokens_top_tokens_1% → 12500
%xplayerstokens_top_tokens_<pos>_formatted%	Formatted tokens (with thousands separator) for position <pos>.	%xplayerstokens_top_tokens_2_formatted% → 12,500
%xplayerstokens_top_tokens_<pos>_rounded%	Rounded/abbreviated tokens for position <pos> (k/M/B).	%xplayerstokens_top_tokens_3_rounded% → 12.5k
%xplayerstokens_total_tokens%	Total tokens across all players (cached value).	1,234,567
%xplayerstokens_average_tokens%	Average tokens across players (cached, 2 decimals).	123.45

Behavior & notes

• Top placeholders use 1-based indexing: %xplayerstokens_top_1_name% is the top player.

• When a requested top position is out of range:

  • Name placeholders return the configured not-available text (default: N/A).

  • Token placeholders return 0.

• Rank returns -1 as not-available internally; the placeholder returns the not-available text when rank is not available.

• tokens_formatted uses String.format("%,d", value) — separators depend on server locale.

• tokens_rounded uses k, M, B suffixes and one decimal when applicable (e.g., 1.2k, 3.4M).

---

Caching & performance

• Placeholders that require global stats (top list, total, average) are cached.

• Cache duration is configurable in config.yml (seconds). Default from your code: placeholders.cache-duration: 60.

• Current code caches the top 100 players in updateCache() (the number 100 is hardcoded in database.getTopPlayers(100)). If you want a different limit, change that call or make it configurable.

• Cached values are updated asynchronously on a repeated task to avoid blocking the main thread.

---

Configuration keys (from your code)

• placeholders.cache-duration (seconds) — how often the cached stats update. Example: placeholders.cache-duration: 60

• placeholders.not-available — text returned when a value is not available (default: N/A). Example: placeholders.not-available: "N/A"

(These live in config.yml per your current implementation.)

---

Practical examples

• Scoreboard line showing player tokens:

  • Tokens: %xplayerstokens_tokens_formatted%

• Chat or GUI showing rounded tokens:

  • You have %xplayerstokens_tokens_rounded% tokens.

• Show top 3 on a sidebar/GUI:

  • 1. %xplayerstokens_top_1_name% - %xplayerstokens_top_tokens_1_formatted%

  • 2. %xplayerstokens_top_2_name% - %xplayerstokens_top_tokens_2_formatted%

  • 3. %xplayerstokens_top_3_name% - %xplayerstokens_top_tokens_3_formatted%

• Display total and average:

  • Total tokens: %xplayerstokens_total_tokens%

  • Average tokens: %xplayerstokens_average_tokens%

---

Requirements & troubleshooting

• PlaceholderAPI must be installed and active for these placeholders to work.

• The expansion is persistent (your persist() returns true), so placeholders remain registered across reloads/restarts as long as PAPI is present.

• If a placeholder returns N/A or 0, check:

  • That your database has the expected columns (player_uuid, player_name, tokens).

  • Cache duration and whether the async cache task has run (restart or wait cache-duration seconds).

  • Console logs for SQL errors from placeholder methods.