Leaderboard NPCs with player skins, custom holograms, PlaceholderAPI integration and full Folia support, works with FancyNpcs, Citizens or ZNPCsPlus. Paper and Folia 1.21 - 26.x
Support
Report bugs and get support here: https://discord.gg/VvM6k2eBDa
Features
• Folia support – fully region-thread safe, schedulers used everywhere
• Multiple NPC backends – FancyNpcs, Citizens, ZNPCsPlus, or simple player-head mode (no NPC plugin required)
• Player skins on NPCs – uses real Mojang skins, with SkinsRestorer integration for cracked / offline-mode servers
• Smart skin fallback – SkinsRestorer → cached OfflinePlayer profile → Mojang name lookup, no default-Steve fallback
• 10 metrics – kills, deaths, playtime, money, mob_kills, fish_caught, damage_dealt, damage_taken, kill_streak, K/D ratio
• 3 time periods – alltime, weekly, daily (UTC, automatic rollover)
• Per-rank hologram styling – distinct templates for #1, #2, #3 (crown / silver / bronze defaults) with overrides for any rank
• PlaceholderAPI integration – embed any %placeholder% inside hologram lines (resolves against the ranked player)
• Custom PAPI placeholders – expose top entries to scoreboards, tab plugins, chat formatters, etc.
• Hologram customization – MiniMessage support, scale, billboard, alignment, shadow, opacity, background, line spacing, view range
• Number formatting – raw / 1,300 / 1.300 / 1 300 / compact (1.3k, 1.5M) styles, configurable per metric type
• Playtime formatting – hours_minutes, days_hours, humanized, short, raw seconds
• Lazy proximity rendering – NPCs only render for players within configurable radius (zero CPU when no one's nearby)
• NPC protection – cancels damage to NPCs and optional player-damage suppression near boards
• Network mode – aggregate stats across multiple servers via MySQL + optional Redis pub/sub
• Auto-refresh – configurable interval (default 12h) plus on-demand /perfranknpcs refresh
• Live config reload – /perfranknpcs reload picks up everything without restart
• bStats metrics – opt-in usage statistics
Placeholders
%perfranknpcs_<metric><period><rank>_name% – player name at that rank
%perfranknpcs_<metric><period><rank>_value% – formatted value (e.g. 1.234 or 12h 5m)
%perfranknpcs_<metric><period><rank>_raw% – raw numeric value
%perfranknpcs_<metric><period><rank>_uuid% – player UUID
Examples: %perfranknpcs_money_alltime_1_name%, %perfranknpcs_kills_today_3_value%, %perfranknpcs_playtime_week_5_raw%
Commands
/ranknpc – Show usage hint (perfranknpcs.use)
/perfranknpcs create (name) (metric) (period) (rank) – Spawn a new leaderboard NPC at your location (perfranknpcs.admin)
/perfranknpcs setpos (name) – Move a board to your current position (perfranknpcs.admin)
/perfranknpcs remove (name) – Delete a board and its NPC (perfranknpcs.admin)
/perfranknpcs list – List all configured boards (perfranknpcs.admin)
/perfranknpcs refresh [name] – Force a refresh of all boards or one specific board (perfranknpcs.admin)
/perfranknpcs reload – Reload config, messages, backend selection (perfranknpcs.admin)
/perfranknpcs cleanup [radius] – Remove leftover plugin entities globally or near you (perfranknpcs.admin)
/perfranknpcs stats – Show plugin stats and active boards (perfranknpcs.admin)
/perfranknpcs edit (name) near – Pick the closest board to edit (perfranknpcs.admin)
/perfranknpcs edit (name) list – Show full board details (perfranknpcs.admin)
/perfranknpcs edit (name) tp – Teleport to a board (perfranknpcs.admin)
/perfranknpcs edit (name) movehere – Move a board to your current position (perfranknpcs.admin)
/perfranknpcs edit (name) look (mode) – Set look behavior (perfranknpcs.admin)
/perfranknpcs edit (name) period (period) – Change the time period (perfranknpcs.admin)
/perfranknpcs edit (name) spacing (value) – Change line spacing (perfranknpcs.admin)
/perfranknpcs edit (name) metric (metric) – Change the tracked metric (perfranknpcs.admin)
/perfranknpcs edit (name) size (rank) – Change which rank position the board displays (perfranknpcs.admin)
/perfranknpcs help – Show admin help (perfranknpcs.admin)
Database
• SQLite (default)
• MySQL (configurable, required for network mode)
