P_Tempo

Minecraft 版本： 1.21 1.21.1 1.21.2 1.21.3 1.21.4 1.21.5 1.21.6 1.21.7 1.21.8 1.21.9 1.21.10 1.21.11

平台： bukkit paper spigot

标签： game-mechanics utility

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

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 available if a database update fails.
• Supports registered online and offline players.

Ranking hologram

When DecentHolograms is installed, the plugin can create a global hologram containing:

• Custom title.
• Each player's position.
• Player name.
• Short or full playtime.
• Configurable number of positions.
• Custom text for empty positions.
• Location saved in the configuration.
• Automatic interval-based updates.
• Manual updates through commands.

Playtime NPC

When Citizens is installed, the plugin can create an NPC that provides access to the system:

• Configurable name.
• Persistent location.
• Creation or movement by an administrator.
• Manual updates.
• Safe removal.
• Opens the menu when clicked.
• Configurable update interval.
• Fully optional integration.

PlaceholderAPI

When PlaceholderAPI is installed, P_Tempo provides placeholders for scoreboards, TAB lists, chat, holograms, and other compatible plugins.

API for other plugins

P_Tempo registers a public service through Bukkit's service manager. Other plugins can use this integration to:

• Read the current playtime of online players.
• Read offline-player playtime asynchronously.
• Obtain cached ranking positions.
• Set a player's playtime.
• Add playtime to a player.

Operations that may access the database are handled asynchronously.

Inventory security

The menus are protected against:

• Normal clicks used to move items.
• Shift-click.
• Dragging items across multiple slots.
• Hotbar number keys.
• Offhand swapping.
• Double-click.
• Creative-mode interactions.
• Repeated clicks while the menu is updating.
• Simultaneous collection of the same reward.

A configurable minimum delay between clicks is also available.

Skin system

• The player's own head in the profile.
• Player heads in the ranking.
• Optional skin lookup through Mojang services.
• Asynchronous requests.
• Configurable timeout.
• Cache with size limit and expiration.
• Configurable fallback username.
• Custom textures for rewards.

Safe reload

The reload command:

• Validates files before applying changes.
• Reloads messages, menus, rewards, skins, and integrations.
• Restarts tasks with the new intervals.
• Prevents duplicate tasks.
• Cancels the operation when the new configuration is invalid.
• Preserves the previous configuration when the new one cannot be applied.
• Blocks database changes while the server is running.
• Blocks reload while critical snapshots are waiting for confirmation.

Changes to the database type, SQLite file, MySQL address, port, database name, username, or password require a full server restart.

Dependencies and integrations

HikariCP, Gson, and the database drivers are already included in a correctly compiled final plugin file. They do not need to be installed separately.

Installation

1. Use only the final file named P_Tempo.jar.
2. Place the file in the server's plugins folder.
3. Remove any older P_Tempo version before starting the server.
4. Never install a file named original-P_Tempo.jar, because it does not contain the bundled dependencies.
5. Start the server to generate the configuration files.
6. Configure the database, menus, rewards, and integrations.
7. Restart the server after changing any database setting.

Generated files

Player commands

Administrative commands

Reward resolutions

The retry option requires the reward to still exist in recompensas.yml. If it was removed, use delivered or reset.

Accepted time formats

Units must remain in the order of days, hours, minutes, and seconds. Incomplete entries, repeated units, incorrect order, and values above the supported limit are rejected.

Permissions

PlaceholderAPI placeholders

Player data

Ranking

Replace <position> with the desired ranking position. The maximum value is defined in config.yml.

Forms without the underscore after top are also accepted. For example, %ptempo_top1_name% and %ptempo_top_1_name% return the same result.

When a position has no player, name placeholders return No player and numeric placeholders return zero.

Internal menu placeholders

These placeholders are used inside menus.yml.

Player profile

The profile also accepts internal ranking placeholders such as {top_1_name}, {top_1_time}, {top_1_time_full}, and their position variations.

Reward items

Pagination and filters

Ranking menu and hologram

Reward configuration

The system supports as many rewards as needed. Rewards are automatically loaded and ordered by their required playtime.

You can customize:

• Reward ID.
• Required playtime.
• Name and material.
• Head texture.
• Custom Model Data.
• Lore.
• Commands executed by the console or player.
• Collection message.
• Title, subtitle, and duration.
• ActionBar.

Rewards with invalid time values are ignored. Invalid materials use a safe fallback item and produce a console warning. Duplicate IDs are also reported.

Menu configuration

The menus.yml file allows customization of:

• Inventory titles and sizes.
• Filler items.
• Individual slots.
• Materials.
• Names and lore.
• Custom Model Data.
• Reward slots.
• Ranking-position slots.
• Back buttons.
• Pagination buttons.
• Filter button.
• Button for hiding delivered rewards.
• Appearance of available, delivered, and locked rewards.
• Appearance of filled and empty ranking positions.

Slots outside the inventory size are ignored to prevent errors.

Reward notifications

The plugin can notify players in chat when they reach the required playtime for a new reward. Activation and message content are configurable.

Collection can also display at the same time:

• Chat message.
• Title.
• Subtitle.
• ActionBar.

Important notes

• Use only the validated final JAR named P_Tempo.jar.
• Do not place original-P_Tempo.jar in the plugins folder.
• Make a backup before switching from SQLite to MySQL or from MySQL to SQLite.
• Database changes require a full restart.
• Do not delete pending-player-saves.dat during database failures.
• Test reward commands before making them available to all players.
• External commands depend on their respective plugins being installed and configured.
• Use administrative reward resolution carefully to avoid manual duplication.

P_Tempo — rewarding dedication, valuing progression.