Playtime formats

⏰ Playtime Format System Tutorial

The playtime format system allows you to create custom time display formats that can be referenced throughout the plugin using various placeholder syntaxes.

⚙️ How It Works

Usage

Custom playtime formats work with both internal plugin messages and PlaceholderAPI (PAPI) placeholders. To apply a custom playtime format, append :format-name to any placeholder that displays formatted playtime, where format-name matches your custom format file (without the .yml extension).

%PLACEHOLDER:format-name%

Examples:

• Internal:

[§6PlayTime§eManager§f]§7 The playtime of §e%PLAYER_NAME%§7 is §6%PLAYTIME:test% 

• PAPI:

%PTM_playtime:test% 

Default Format

If no format name is specified, the system uses the default format:

• Internal:

[§6PlayTime§eManager§f]§7 The playtime of §e%PLAYER_NAME%§7 is §6%PLAYTIME% 

• PAPI:

%PTM_playtime% 

Both are equivalent to using %PLAYTIME:default% or %PTM_playtime:default% respectively.

🎨 Creating Custom Formats

File Structure and Fields

Custom formats are stored in the Customizations/PlaytimeFormats directory. Each format is defined in its own file with a .yml extension.

⚠️ Important: Do not modify default.yml directly! This file is automatically overwritten by the plugin on reload, and any changes will be lost. To create a custom format, copy default.yml to a new file with a different name (e.g., custom.yml, short.yml, etc.) and make your modifications there.

Each format file contains the following configuration options:

Time Unit Labels

Define both singular and plural forms for each time unit:

years-singular: "year"
years-plural: "years"
months-singular: "month"
months-plural: "months"
weeks-singular: "week"
weeks-plural: "weeks"
days-singular: "day"
days-plural: "days"
hours-singular: "hour"
hours-plural: "hours"
minutes-singular: "minute"
minutes-plural: "minutes"
seconds-singular: "second"
seconds-plural: "seconds"

Formatting String

The formatting field defines how the time components are arranged and displayed:

formatting: "%y%{years}, %d%{days}, %h%{hours}, %m%{minutes}, %s%{seconds}"

Time Redistribution

The distribute-removed-time field controls how omitted time units are handled (enabled by default):

distribute-removed-time: true

This setting determines whether time from units not included in your formatting string gets redistributed:

• true: Omitted larger time units are converted and added to the next smallest displayed unit

  • Example: With 1d 12h 1m and formatting "%h%{hours}, %m%{minutes}" → displays "36h, 1m"
  • The 1 day is converted to 24 hours and added to the existing 12 hours (24 + 12 = 36)

• false: Omitted time units are simply hidden without redistribution

  • Example: With 1d 12h 1m and formatting "%h%{hours}, %m%{minutes}" → displays "12h, 1m"
  • The 1 day is completely hidden, only the original 12 hours are shown

🔤 Formatting System

Time Value Placeholders

Use these fixed placeholders to insert time values (these cannot be modified and are managed by the plugin):

• %y% - Years value
• %mo% - Months value
• %w% - Weeks value
• %d% - Days value
• %h% - Hours value
• %m% - Minutes value
• %s% - Seconds value

Unit Label Placeholders

Use these placeholders to insert the appropriate unit labels:

• {years} - Years unit label
• {months} - Months unit label
• {weeks} - Weeks unit label
• {days} - Days unit label
• {hours} - Hours unit label
• {minutes} - Minutes unit label
• {seconds} - Seconds unit label

Automatic Features

The system includes several automatic behaviors:

• Zero Value Hiding: Time units with zero values are automatically hidden from display
• Singular/Plural Selection: The system automatically chooses between singular and plural unit labels based on the time value