Of course, here is the complete documentation for the TimeTags plugin in English, based on the file you provided.


TimeTags Plugin Documentation

This document provides a comprehensive guide to the TimeTags plugin. It explains how to set up, use, and understand all of its features.


1. GENERAL PLUGIN INFORMATION

• Description: Adds customizable tags based on playtime and special criteria, featuring interactive GUIs and full PlaceholderAPI support.
• API Version: 1.20
• Dependencies:
• PlaceholderAPI (Required for placeholder support)

2. INSTALLATION

1. Download the TimeTags.jar plugin and PlaceholderAPI.jar (if you don't already have it).
2. 
   
3. Place both files in the plugins/ folder of your Minecraft server (Spigot/Paper 1.20.1+).
   
   
4. Start or restart your server.
   
   
5. The configuration files (config.yml, playerdata.yml, specialsdatabase.yml) and the lang/ folder will be generated automatically.

3. PLUGIN COMMANDS

/playtime

• Description: Checks your own playtime or that of another player.
  
  
• Usage: /playtime [player]
  
  
• Permission: timetags.playtime
  
  
• Alias: /pt

/tags

• Description: Opens the main GUI to select your playtime tag or access other GUIs.
  
  
• Usage: /tags
  
  
• Permission: timetags.tags

/timetags

• Description: Main administration command for TimeTags.
  
  
• Usage: /timetags <subcommand>
  
  
• Permission: timetags.admin (Default: OPs only)
  
  
• Alias: /tt
  
  
• Subcommands:
  • reload
    • Description: Reloads all configuration files (config.yml, messages_xx.yml), tags, special tags, and the top players cache.
      
      
    • Usage: /timetags reload
  • bypass
    • Description: Toggles administrator bypass mode. In bypass mode, you can select any tag, even those locked by time requirements.
      
      
    • Usage: /timetags bypass
  • addspecialtag
    • Description: Gives a special tag to a player. The tag must be configured in the special-tags section of config.yml.
      
      
    • Usage: /timetags addspecialtag <tag_id> <player>
      
      
    • Example: /timetags addspecialtag admin Notch
  • language
    • Description: Changes the plugin's language. The language is saved to config.yml and all settings are reloaded.
      
      
    • Usage: /timetags language <lang_code>
      
      
    • Example: /timetags language en
      
      
    • Available Languages: en, pt_br, es, de, fr, zh, ru (and any custom messages_*.yml file in the lang/ folder).

4. FILE STRUCTURE

• Plugin Folder: plugins/TimeTags/
  
  
• Files:
  • config.yml: The main plugin configuration file. Contains settings for GUIs, playtime tags, special tags, and effects.
    
    
  • playerdata.yml: Stores each player's selected tag and display mode. Do not edit this file manually.
    
    
  • specialsdatabase.yml: Stores which special tags each player owns. Do not edit this file manually.
• Folders:
  • lang/: Contains the message files for different languages (e.g., messages_en.yml, messages_pt_br.yml).

5. CONFIGURATION (config.yml)

settings

• language
  • Description: Sets the default language for the plugin. Must match the suffix of a file in the lang/ folder (e.g., 'en' for messages_en.yml).
    
    
  • Default: pt_br

gui_settings

• size
  • Description: Size of the main GUI. Must be a multiple of 9 (9, 18, 27, 36, 45, 54).
    
    
  • Default: 54
• close_on_select
  • Description: If true, the GUI will close automatically after a player selects a tag or display mode. If false, the GUI will refresh instead.
  • Default: false
• border
  • enabled: Enables/disables the decorative border in the GUI.
  • item: Item material used for the border (e.g., GRAY_STAINED_GLASS_PANE).
• locked_tag_item
  • material: Item material used for tags that the player has not yet unlocked (e.g., BARRIER, EGG).
• buttons
  • remove_tag: Settings for the 'Remove Tag' button.
  • display_mode_selector: Settings for the display mode buttons (Chat, Tab, Both).
  • special_tags
    • Description: Settings for the button that opens the Special Tags GUI from the main menu.
    • item: Button material (e.g., GOLD_NUGGET).
    • slot: Button slot in the main GUI (0-53). Use -1 for automatic calculation (2 slots to the left of the 'Display in Chat' button).
  • top_playtime_button
    • Description: Settings for the button that opens the Top Playtime GUI from the main menu.
    • item: Button material (e.g., CLOCK).
    • slot: Button slot in the main GUI (0-53). Default: 4 (middle of the first row).

top_playtime

• Description: Specific settings for the Top Playtime GUI.
  
  
• size: Size of the Top Playtime GUI (must be a multiple of 9).
  
  
• pagination_cooldown_seconds: Time in seconds a player must wait between clicking pagination buttons.
  
  
• border: Border settings for this GUI.
  
  
• top_player_item: Item material representing each player in the ranking (e.g., PLAYER_HEAD).
  
  
• back_button: Settings for the 'Back' button in this GUI.
  
  
• next_page_button: Settings for the 'Next Page' button.
  
  
• previous_page_button: Settings for the 'Previous Page' button.
  
  
• page_info_item: Settings for the item that displays the current/total page number.

special_tags

• Description: Specific settings for the Special Tags GUI.
  
  
• size: Size of the Special Tags GUI (must be a multiple of 9).
  
  
• border: Border settings for this GUI.
  
  
• back_button: Settings for the 'Back' button in this GUI.
  
  
• back_button.slot: Slot for the back button in the Special Tags GUI. Use -5 for automatic calculation (middle of the last row).

effects

• Description: Configure sound and particle effects for various plugin actions.
  
  
• Actions:
  • select_tag: Effects when selecting a tag (regular or special).
    
    
  • click_locked_tag: Effects when clicking a locked tag.
    
    
  • change_display_mode: Effects when changing the display mode.
    
    
  • remove_tag: Effects when removing a tag.
    
    
  • open_main_gui: Effects when opening the main GUI.
    
    
  • close_main_gui: Effects when closing the main GUI.
    
    
  • open_special_tags_gui: Effects when opening the Special Tags GUI.
• Effect Properties:
  • sound: Name of the Bukkit sound (e.g., ENTITY_PLAYER_LEVELUP). Use null to disable.
    
    
  • volume: Sound volume (0.0 to 1.0).
    
    
  • pitch: Sound pitch (0.0 to 2.0).
    
    
  • particle: Name of the Bukkit particle (e.g., VILLAGER_HAPPY). Use null to disable.
    
    
  • count: Number of particles to spawn.
    
    
  • offset: Particle spread (0.0 for no spread).

tags

• Description: Section for configuring playtime tags. Use numbers as keys to define the order in the GUI.
  
  
• Tag Entry Example:
  
  YAML
  tags:
  '1':
  display: "&8[&7Rookie&8]"
  time_required_hours: 1
  gui_item: "NAME_TAG"
  gui_name: "&aRookie Tag"
  gui_lore_unlocked:
  - "&7Click to select this tag."
  gui_lore_locked:
  - "&cLocked!"
  - "&7Required Playtime: {required_time}"

special-tags

• Description: Section for configuring special tags. These tags have no time requirement and are assigned via the admin command (/timetags addspecialtag).
  
  
• Special Tag Entry Example:
  
  YAML
  special-tags:
  'admin':
  display: "&c&l[ADMIN]"
  gui_item: "COMMAND_BLOCK"
  gui_name: "&c&lAdmin Tag"
  gui_lore:
  - "&7A special tag for server staff."

6. MESSAGE CONFIGURATION (messages_xx.yml)

• Description: All in-game text is configured in the messages_xx.yml files inside the lang/ folder. You can create your own language file (e.g., messages_custom.yml) and set settings.language: custom in config.yml.
  
  
• Placeholders in Messages:
  • {player}: Player's name.
    
    
  • {time}: Formatted time (hours, minutes, seconds).
    
    
  • {tag}: The formatted tag.
    
    
  • {remaining_seconds}: Seconds remaining for pagination cooldown.
    
    
  • {current_page}: Current GUI page.
    
    
  • {total_pages}: Total GUI pages.
    
    
  • %tag_id%: Special tag ID (for admin commands).
    
    
  • %player%: Player name (for admin commands).
    
    
  • %lang_code%: Language code (for admin commands).
    
    
  • {tag_name}: Tag name (for locked tag items).
    
    
  • {required_time}: Time required to unlock a tag (for locked tag lore).
• GUI Titles and Names:
  • Description: GUI titles and the names of border/button items have been moved to the message files for easier translation.
    
    
  • Examples: gui_title, gui_border_name, locked_tag_item_name, remove_tag_button_name, top_playtime_gui_title, special_tags_gui_title, and so on for all GUI button/item names and lores.
• Admin Command Messages:
  • Description: Specific messages for admin commands, including help and feedback.
    
    
  • Examples: admin-commands.addspecialtag.help, admin-commands.addspecialtag.usage, admin-commands.language.success.
• Placeholder Messages:
  • Description: Fallback messages for PlaceholderAPI when a player has no tag selected or visible.
    
    
  • no_tag_placeholder_chat: Placeholder for chat when no tag is visible. Supports placeholders from other plugins (e.g., %luckperms_prefix%).
    
    
  • no_tag_placeholder_tab: Placeholder for the tab list when no tag is visible. Supports placeholders from other plugins (e.g., %luckperms_prefix%).

7. PLACEHOLDERAPI INTEGRATION

• Description: The TimeTags plugin integrates with PlaceholderAPI to display tags in chat and the player list (tab).
  
  
• Placeholders:
  • %timetags_chat%: Displays the player's selected tag in chat if their display mode is CHAT or BOTH. Otherwise, it displays the configured no_tag_placeholder_chat message.
    
    
  • %timetags_tab%: Displays the player's selected tag in the player list (tab) if their display mode is TAB or BOTH. Otherwise, it displays the configured no_tag_placeholder_tab message.
• How to Use:
  1. Ensure you have PlaceholderAPI installed on your server.
  2. Reload PlaceholderAPI with /papi reload after installing TimeTags.
  3. Use the placeholders above in chat, tablist, or other plugins that support PlaceholderAPI.

8. TIPS & TROUBLESHOOTING

• Always run /timetags reload after making changes to config.yml or messages_xx.yml files.
  
  
• If an item material is not recognized, the plugin will use a default material (BARRIER, STONE, etc.) and log a warning in the console.
  
  
• Check the server console for error messages or warnings from TimeTags if something is not working as expected.
  
  
• For playtime tags, the keys in the tags section of config.yml must be integers to ensure the correct order in the GUI.
  
  
• For special tags, the keys in the special-tags section can be any unique string.
  
  
• The admin bypass mode is useful for testing tags without having to meet the time requirements.
  
  
• If the special tags button does not appear in the main GUI, ensure the player has been granted at least one special tag via /timetags addspecialtag.