P_Tempo v1.0

# P_Tempo

P_Tempo is a Paper plugin that tracks player playtime, builds a time ranking, provides a visual menu, and unlocks configurable rewards based on accumulated time.

## What the plugin does

• Automatically tracks each player's playtime while they are online.
• Saves player progress with support for SQLite and MySQL.
• Provides a main menu with quick access to profile, rewards, and ranking.
• Includes a rewards menu with pagination, filters, and an option to hide already claimed rewards.
• Allows players to claim rewards automatically once the required time has been reached.
• Executes reward commands as console or as player.
• Sends a chat notification when a player has a reward ready to claim.
• Maintains a top players ranking by total playtime.
• Can display the ranking in a hologram through DecentHolograms.
• Can expose placeholders for other plugins through PlaceholderAPI.
• Includes a simple API to read a player's tracked time and the top 10 leaderboard.

## Requirements

• Paper 1.21+
• Java 21

## Menus

• Main menu: shows the player's profile, current time, ready rewards, next reward, active filter, and quick access to rewards and top ranking.
• Rewards menu: shows configured rewards, each reward status, current page, filters, and the option to hide claimed rewards.
• Top menu: shows the players with the highest accumulated playtime using heads and formatted time.

## Commands

• /ptempo: opens the plugin main menu.
• /ptempo reload: reloads the plugin configuration.
• /ptempo top: sends the top 10 players by playtime in chat.
• /ptempo open <player>: opens the main menu for the target player.
• /ptempo holograma set: saves the player's current location as the top hologram location.
• /ptempo holograma update: manually refreshes the configured hologram.
• /ptempo tempo add <player> <time>: adds time to a player.
• /ptempo tempo set <player> <time>: sets the player's total tracked time.
• /ptempo tempo reset <player>: resets the player's accumulated time.

## Accepted time format for admin commands

• Minutes, hours, and days can be used in time operations.
• Examples accepted by the plugin: 30m, 2h, 1d.

## Permissions

• ptempo.use: allows usage of the main plugin command.
• ptempo.admin: allows reload, time management, opening the menu for another player, and hologram control.

## Rewards

• Rewards are loaded from the configuration file.
• Each reward can define a name, item, lore, required time, executed commands, claim message, title, and actionbar.
• The plugin prevents the same reward from being claimed more than once.
• Claim state is saved per player.
• Players can browse rewards through four filters:
• All
• Ready to claim
• Claimed
• Waiting for time

## PlaceholderAPI placeholders

• %ptempo_seconds%
• %ptempo_time%
• %ptempo_time_full%
• %ptempo_time_formatted%
• %ptempo_time_short%
• %ptempo_ready_rewards%
• %ptempo_next_reward%

## Top placeholders

• %ptempo_top_1_name%
• %ptempo_top1_name%
• %ptempo_top_2_time%
• %ptempo_top10_time%
• %ptempo_top_20_time_full%
• %ptempo_top50_seconds%

## Internal placeholders for menus and texts

• {player}
• {time}
• {time_short}
• {seconds}
• {ready_rewards}
• {next_reward_time}
• {filter}
• {hide_collected}
• {top_1_name}
• {top1_name}
• {top_2_time}
• {top10_time}
• {top_20_time_short}
• {top50_time_full}
• {top100_seconds}

## Integrations

• PlaceholderAPI: enables the plugin placeholders for menus, scoreboards, holograms, and other compatible plugins.
• DecentHolograms: allows automatic creation and refresh of a hologram showing the playtime ranking.

## Storage

• SQLite: default option, recommended for smaller servers or simpler setups.
• MySQL: recommended for environments that need an external or shared database.

## Configuration files

• config.yml: controls database, save interval, notifications, skins, messages, and hologram integration.
• menus.yml: controls menu structure, items, slots, navigation, and displayed texts.
• recompensas.yml: defines the reward list, required times, and commands executed on claim.

## API

• The plugin includes an API to query a player's accumulated seconds.
• It also provides access to the top 10 players with the highest tracked time.

## Summary

P_Tempo is focused on playtime-based progression, with menu-based navigation, ranking, configurable rewards, persistent storage, and ready-to-use integrations for Paper servers.