Integrations & systems

💳 Vault Economy Integration

RankForge hooks into Vault to read economy balances. Any Vault-compatible economy plugin works automatically.

Common compatible plugins: EssentialsX Economy, CMI Economy, iConomy, BOSEconomy, TheNewEconomy.

What RankForge does with Vault:

• Reads the player's balance to evaluate required-money
• Saves the live balance snapshot to the cache on player logout for accurate offline reads
• Exposes the balance via %rankforge_money% and related PAPI placeholders

What RankForge does NOT do:

• Automatically deduct money — add a command reward for withdrawals

# Example: deduct money on rankup via EssentialsX command
commands:
  - "eco take %player% 10000"

🔒 LuckPerms Integration

With LuckPerms installed, RankForge manages permissions entries via the LuckPerms API instead of Bukkit PermissionAttachment, providing more reliable session-based permission handling.

What happens on login:

• RankForge reads the player's stored rank
• Calls luckPermsHook.applyPermissions(player, rankModel) with the rank's permissions list
• Without LuckPerms, a Bukkit PermissionAttachment is used as fallback

What happens on rankup:

• Old rank's permissions are removed via removeRankPermissions(player, oldRankId)
• New rank's permissions are applied via applyRankPermissions(player, newRankId)

For permanent group membership, use commands:

commands:
  - "lp user %player% group set veteran"
  - "lp user %player% group remove member"

🌍 Crossplay Support (Geyser / Floodgate)

RankForge automatically detects Floodgate and handles Bedrock player names gracefully.

Configuration:

crossplay:
  bedrock-prefix: "."    # Floodgate's default prefix for Bedrock usernames

What this affects:

• RankForgeAPI.getCleanName(player) strips the prefix for display purposes
• The %rankforge_player% placeholder returns the clean name
• Rank checks and storage still use the full UUID, so Bedrock players are handled identically to Java players internally

🌐 Multi-Language Support

RankForge ships with four bundled languages and supports unlimited custom ones.

Bundled Languages

Per-Player Language

Players change their language with:

/rank lang list             ← see available codes
/rank lang set es           ← switch to Spanish
/rank lang reset            ← revert to server default

The preference is saved to the player's data record and persists across sessions. The %rankforge_lang% placeholder shows a player's current language code.

Adding a Language

1. Copy plugins/RankForge/lang/en.yml to plugins/RankForge/lang/de.yml
2. Translate the messages section
3. Run /rank reload
4. The new language is available immediately

The prefix key at the top of each language file sets the message prefix for that language.

🗄️ Data Storage

YAML (Default)

When storage.type: yaml is set (or MySQL connection fails), player data is stored in memory and periodically flushed to YAML files. This is suitable for single-server setups.

storage:
  type: yaml
  enabled: true
  file: "ranks.yml"

sync:
  interval-ticks: 200    # Flush every 200 ticks (10 seconds)

On shutdown, a final synchronous flush is always performed. Writes are batched and debounced so that rapid rank, XP, or playtime changes don't trigger a disk write per change.

MySQL

For networks or servers that need persistent, relational storage:

storage:
  type: mysql
  mysql:
    host: "localhost"
    port: 3306
    database: "rankforge"
    username: "rankforge_user"
    password: "your_secure_password"
    pool-size: 10

RankForge uses HikariCP for connection pooling. Tables are created automatically on first connection. Reads and writes go through the same debounced batching as YAML storage, keeping MySQL round-trips low even under heavy rankup/XP activity.

Fallback Behavior

If the MySQL connection fails at startup, RankForge automatically falls back to YAML storage and logs a warning. This prevents the plugin from failing to load due to database unavailability.

Cache

An in-memory CacheManager holds data for all online players plus recently-offline players. Entries expire and are purged on a schedule (every 6 000 ticks by default). On player logout, data is saved asynchronously and the cache entry is scheduled for cleanup.

Orphan Repair: If a player's stored rank ID no longer exists in ranks.yml (e.g., after a rank was deleted), the rank is automatically repaired to the default-rank both on join and after every reload.

⚡ Performance System

RankForge monitors server TPS and automatically adjusts behavior to protect server performance.

TPS Modes

Thresholds are configurable:

performance:
  modes:
    high-tps-threshold: 18.0
    medium-tps-threshold: 14.0

Mode transitions are logged to console:

[RankForge] [Perf] Mode switched HIGH → MEDIUM (TPS: 16.4)

The TPS monitor runs as a repeating server task and evaluates every 200 ticks (10 seconds).

Storage & Sync Efficiency

The YAML and MySQL storage backends batch writes and use debounced, asynchronous flushes so that frequent rank, XP, and playtime updates don't translate into constant disk or database I/O. Combined with the TPS-aware cosmetic throttling above, this keeps RankForge's overhead low even on busy servers with hundreds of concurrent players — reload, rankup, and GUI operations stay responsive under load.

🛡️ Anti-Abuse & Security

AntiAbuseManager provides three layers of exploit protection.

1. Macro Detection

GUI clicks are timestamped per player. If two consecutive clicks arrive within 20 ms of each other, the second click is blocked and a warning is logged. This prevents automated macro clicking in the rank GUI.

2. Command Rate Limiting

/rank up and similar commands are subject to a 1 000 ms (1 second) per-player cooldown. Attempts within the cooldown window are silently ignored.

3. Admin Rollback Tracking

Admin rank changes (via /rank set, /rank force, /rank reset) are logged in AntiAbuseManager as pending rollback actions. This creates an audit trail that can be reviewed with /rank security.

Anti-Bypass Manager

AntiBypassManager provides additional protection against players finding exploits to bypass rank requirements. Configuration is in config.yml.

Rankup Queue

RankupQueue prevents concurrent rankup processing for the same player — if a rankup is already being processed for a player, subsequent attempts are queued or rejected until the first completes. This prevents double-rankup race conditions.