P_TopJogadores v1.0

# P_TopJogadores

Ranking plugin for Paper servers that organizes top players by category and can display the result through placeholders, NPCs, and holograms.

## What the plugin does

• Builds rankings from placeholders provided by other plugins.
• Supports categories such as kills, money, online time, or any other value that can be read through a placeholder.
• Exposes ranking data through PlaceholderAPI for scoreboards, menus, chat, holograms, and other compatible plugins.
• Updates Citizens NPCs based on ranking positions.
• Updates DecentHolograms holograms using the lines configured for each category.
• Can show an automatic hologram above the NPC with title, position, player name, and value.
• Allows commands to run when players click ranking NPCs.
• Supports regular numeric values, compact values, and time-based categories.

## Requirements

• Paper 1.21 or newer.
• PlaceholderAPI for ranking calculation and placeholder output.
• Citizens if you want NPC support.
• DecentHolograms if you want hologram support.

## How the plugin works

Each category uses a placeholder as its data source. The plugin reads that value from the players known by the server, sorts the result according to the category settings, and builds the ranking from there.

After the calculation, the result can be used in three main ways:

• In other plugins or interfaces through the plugin's own PlaceholderAPI expansion.
• In NPCs that represent specific ranking positions.
• In holograms that display visual top lists.

## How to use it

1. Place the plugin in your server's plugins folder and start the server once to generate the files.
2. Open the configuration files and define the categories you want to use.
3. For each category, set the placeholder that represents the value used in the ranking.
4. Adjust the title, ranking size, value format, sorting direction, and visual lines to match your server.
5. If you want visual features, create NPCs and holograms in game where you want them to appear.
6. Reload or recalculate the plugin after changing the configuration so the data is updated.

## Main files

• categorias.yml: defines ranking categories, value sources, appearance, and category behavior.
• config.yml: controls automatic updates, performance, integrations, and general plugin settings.
• npcs.yml: stores the NPCs created on the server.
• hologramas.yml: stores the holograms created on the server.
• mensagens.yml: stores the plugin messages.

## Category usage

Each category can define:

• Internal identifier.
• Title.
• Placeholder used to build the ranking.
• Ranking size limit.
• Ascending or descending order.
• Numeric or time value type.
• Display value formatting.
• World restriction.
• Hologram lines and internal placeholders.
• Commands that run when players click NPCs for that category.

When a category uses time values, the plugin compares the data numerically and displays it using the configured time format. This allows you to build online-time leaderboards and similar rankings.

## PlaceholderAPI integration

The plugin registers the p_topjogadores expansion.

With this expansion, you can display:

• Name, value, UUID, and position for any ranking entry.
• The player's own position and value in a category.
• Category metadata such as title, configured placeholder, and ranking limit.

This makes it easy to reuse ranking data in scoreboards, tablists, menus, messages, and other server interfaces.

## NPCs and holograms

NPCs are created per category and per ranking position. When the ranking changes, the plugin updates the NPC name, skin, and automatic hologram as long as the required integrations are available.

Ranking holograms are created at the administrator's chosen location and display the lines configured for the category. The plugin also saves those locations so everything can be restored after server restarts.

## Administrative usage

The plugin uses ptop as its main command. From there, administrators can open the help output, reload the configuration with ptop reload, recalculate rankings with ptop recalcular, and create or remove NPCs and holograms at their in-game location.

## Permissions

• ptop.admin
• ptop.reload
• ptop.recalcular
• ptop.npc
• ptop.holograma

## Important notes

• If the configuration requires PlaceholderAPI for rankings, the plugin will not recalculate data while that dependency is missing.
• Rankings can be updated automatically on server startup, when players join, and on scheduled intervals defined in the configuration.
• The plugin tries to use the skin of the player currently holding a ranking position for the matching NPC.
• NPCs and holograms created manually are saved for continued use on the server.