P_Tempo

# P_Tempo **Complete playtime, rewards, ranking, and progression plugin for Paper servers.** P_Tempo tracks how long players remain online, displays statistics in menus, builds a global ranking, and allows automatic rewards based on accumulated playtime. The plugin was developed with a focus on performance, data safety, customization, and integration with other plugins. ## General information | Information | Details | |---|---| | Version | 1.3.1 | | Platform | Paper 1.21.3 or newer | | Java | Java 21 | | Author | Pedro | | Main command | `/ptempo` | | Alias | `/tempojogado` | | Database | SQLite or MySQL | ## Main features ### Playtime tracking - Tracks only the time a player remains online. - Keeps the current session time updated without constant database queries. - Saves players in batches and asynchronously. - Allows administrators to view, add, set, remove, or reset playtime. - Supports online players and known players who have already joined the server. - Prevents accidental creation of records caused by incorrectly typed player names. - Refreshes the ranking after administrative changes. ### Database and data-loss protection - Native SQLite and MySQL support. - HikariCP connection pool included in the final plugin file. - SQLite and MySQL drivers included in the plugin. - Asynchronous saving to prevent main-thread freezes. - Batch saving for online players. - Automatic retries after temporary database failures. - Progressive delay between retry attempts. - Automatic SQLite backup before migrations when enabled. - Versioned migrations for safely upgrading older databases. - Local emergency journal for preserving data not yet confirmed by the database. - Automatic recovery of pending saves when the database becomes available again. - Reconciliation between the database and the journal during startup. - Versioned snapshots that prevent older data from overwriting newer states. - Legitimate administrative playtime reductions are also preserved. - The latest player state is protected during server shutdown. The local recovery file is named `pending-player-saves.dat`. It should not be deleted manually while data is still waiting for database confirmation. ### Main menu The main menu displays: - Player head and name. - Total accumulated playtime. - Playtime in short format. - Number of available rewards. - Remaining time until the next reward. - Current reward filter. - Current hide-delivered-rewards setting. - Data-loading status. - Access to the rewards menu. - Access to the global ranking. All titles, items, materials, names, lore, slots, fillers, and custom models can be changed in `menus.yml`. ### Rewards menu - Rewards ordered by required playtime. - Automatic pagination. - Configurable number of slots. - Filter for showing all rewards. - Filter for showing only available rewards. - Filter for showing only delivered rewards. - Filter for showing only locked rewards. - Option to hide already delivered rewards. - Filter preference saved individually for each player. - Hide-delivered preference saved individually for each player. - Different appearance for available, delivered, and locked rewards. - Optimized updates only when an item actually changes. - Protection against unauthorized item movement. ### Configurable rewards Each reward can have: - Its own identifier. - Required playtime. - Custom name. - Custom material. - Custom-texture player head. - Custom Model Data. - Custom lore. - One or multiple commands. - Commands executed by the console or by the player. - Chat message after collection. - Title and subtitle. - Custom title fade-in, stay, and fade-out durations. - Custom ActionBar message. The `{player}` marker can be used in reward commands to represent the name of the player collecting the reward. Example rewards may use economy, crate, or permission commands. These commands only work when the server has the plugins responsible for them. ### Safe reward delivery P_Tempo tracks every delivery stage to reduce the risk of duplication or loss: - The delivery is registered before command execution. - Every command has a database checkpoint. - The next command only runs after the state is updated. - A safe delivery can resume from the last confirmed point. - An ambiguous state is blocked for administrative review. - The plugin does not automatically repeat a command that may have delivered money, items, keys, or permissions. - Only rewards confirmed as delivered count as collected. - Old delivery records remain available even if the reward was removed from the configuration. Administrators can inspect the delivery state and choose whether to confirm it, retry it, or reset the record. ### Global ranking - Top 10 displayed in chat. - Visual ranking menu. - Player heads in the ranking menu. - Configurable number of positions. - Asynchronous cache to avoid repeated database queries. - Configurable maximum position for ranking placeholders. - The latest valid cache remains a