ApoTags

🏷️ ApoTags

✨ Features

• 🎨 Full RGB / HEX color support — use &#RRGGBB hex codes and legacy & codes anywhere
• 🖥️ Paginated player GUI — browse and equip tags with a clean inventory menu
• 🛠️ Admin GUI — manage all tags in-game, toggle enable/disable with Shift+Click
• 💾 H2 embedded database or FlatFile storage — no external database setup required
• 📡 PlaceholderAPI — display active tags in chat, tab, scoreboards, and more
• 🌍 Multi-language — built-in English and Spanish, easily add any language
• ⚙️ Fully customizable GUIs — separate gui_user.yml and gui_admin.yml config files
• 🔐 Granular permissions — one permission node per subcommand for maximum control
• 🔄 Live reload — apply any config or tag changes without restarting the server
• 🏷️ Multi-line tag lore — add rich descriptions to each tag shown in the GUI
• 💡 Zero hardcoded text — every player-facing message lives in the language file

📦 Requirements

🚀 Installation

1. Download ApoTags.jar and drop it into your /plugins/ folder
2. Start or restart your server
3. All config files are generated automatically on first launch
4. Install PlaceholderAPI if you want to display tags in chat or tab

📁 Default Configuration

config.yml

# ─────────────────────────────────────────────
#   ApoTags Configuration
#   Authors: ApoloCR & ApoStudios
#   Version: 1.0.0
# ─────────────────────────────────────────────

# Plugin locale: en / es
locale: 'en'

# Storage type: H2 / FLATFILE
storage: 'H2'

# GUI Settings
gui_settings:
  title: 'ApoTags - Select your Tag'
  rows: 6

  # Items for GUI navigation (Material names)
  next_page_item: 'ARROW'
  previous_page_item: 'ARROW'
  reset_tag_item: 'BARRIER'

  # Slot positions in row 6 (0-indexed from row start = slot 45)
  # Row 6: slots 45-53
  prev_slot: 45
  next_slot: 53
  reset_slot: 49

  # Filler item for empty slots (set to 'NONE' to disable)
  filler_item: 'GRAY_STAINED_GLASS_PANE'
  filler_name: ' '

tags.yml — Default tags

VIP:
  order: 1
  tag: '&7[&eVIP&7]'
  lore:
    - '&eAwarded to VIP members'
    - '&7Thank you for your support!'
  permission: apotags.tag.vip
  enabled: true

MVP:
  order: 2
  tag: '&7[&bMVP&7]'
  lore:
    - '&bAwarded to MVP members'
    - '&7The highest donor rank.'
  permission: apotags.tag.mvp
  enabled: true

Apolo:
  order: 3
  tag: '&#00f2ff&l[APO] '
  lore:
    - '&#00f2ffExclusive Developer Tag'
    - '&7Reserved for ApoStudios staff.'
  permission: none
  enabled: true

Staff:
  order: 4
  tag: '&7[&cStaff&7]'
  lore:
    - '&cFor server staff members'
    - '&7Helping keep the server safe.'
  permission: apotags.tag.staff
  enabled: true

Helper:
  order: 5
  tag: '&7[&aHelper&7]'
  lore:
    - '&aFor server helpers'
    - '&7Always ready to assist.'
  permission: apotags.tag.helper
  enabled: true

Builder:
  order: 6
  tag: '&#ff9900&l[Builder] '
  lore:
    - '&#ff9900For talented builders'
    - '&7Creating amazing things.'
  permission: apotags.tag.builder
  enabled: true

Tip: Tags with permission: none are available to every player for free.

gui/gui_user.yml — Player GUI appearance

title: '&#00f2ff&lApoTags &8― &7Select your Tag'
rows: 6
tag_item_material: 'NAME_TAG'
tag_item_locked_material: 'PAPER'
filler_material: 'GRAY_STAINED_GLASS_PANE'

prev_page:
  material: 'ARROW'
  slot: 45        # leftmost slot of row 6

next_page:
  material: 'ARROW'
  slot: 53        # rightmost slot of row 6

reset_tag:
  material: 'BARRIER'
  slot: 49        # center of row 6

glow_active_tag: true
custom_model_data_available: 0
custom_model_data_active: 1
custom_model_data_locked: 2

gui/gui_admin.yml — Admin GUI appearance

title_prefix: '&c&l[Admin] &r'
enabled_tag_material: 'NAME_TAG'
disabled_tag_material: 'PAPER'
glow_enabled_tags: true
filler_material: 'BLACK_STAINED_GLASS_PANE'

info_item:
  material: 'COMMAND_BLOCK'
  slot: 49

💬 Commands

All commands use /tags as the main label. Aliases: /apotags, /tag

Player Commands

Admin Commands

🔐 Permissions

Bundles

Granular Command Nodes

Per-Tag Nodes

Individual tag access follows the format apotags.tag.<TagID> where <TagID> exactly matches the key in tags.yml (case-sensitive).

These are not declared in plugin.yml — create them in your permissions plugin as needed.

apotags.tag.VIP      → access to the VIP tag
apotags.tag.Staff    → access to the Staff tag
apotags.tag.Legend   → access to a custom Legend tag

Tags with permission: none in tags.yml are free for everyone — no node needed.

LuckPerms examples:

/lp user <player> permission set apotags.tag.VIP true
/lp group vip permission set apotags.tag.all true
/lp group moderator permission set apotags.command.admin true

📡 PlaceholderAPI

Install PlaceholderAPI to display tags in chat, tab, scoreboards, and any other PAPI-compatible plugin.

Chat format example (EssentialsX):

format: '{prefix}%apotags_tag%%displayname%&r: {message}'

TAB plugin example:

tabprefix: '%apotags_tag%'

🌍 Language Support

ApoTags ships with English (en) and Spanish (es).

To add a new language:

1. Copy plugins/ApoTags/lang/en.yml → plugins/ApoTags/lang/<code>.yml
2. Translate all values (keep all keys and {tokens} unchanged)
3. Set locale: '<code>' in config.yml
4. Run /tags reload

➕ Adding a New Tag

Via command (no restart):

/tags create Legend &#FFD700&l[LEGEND]
/tags setdesc Legend &6The most legendary rank|&7Achieved through glory.
/tags setorder Legend 3

Then grant the permission apotags.tag.Legend in your permissions plugin.

Directly in tags.yml:

Legend:
  order: 3
  tag: '&#FFD700&l[LEGEND] '
  lore:
    - '&6The most legendary rank'
    - '&7Achieved through glory.'
  permission: apotags.tag.Legend
  enabled: true

Then run /tags reload.

🏗️ For Developers

ApoTags is built on Paper 1.19.4 + Adventure (Kyori) for native RGB rendering.

Color syntax supported everywhere:

&#RRGGBB      → full hex color   e.g. &#00f2ff
&a &b &c ...  → legacy codes
&l &o &n ...  → formatting codes

Storage:

• H2 embedded database (default) — playerdata.mv.db
• FlatFile YAML fallback — playerdata.yml

Package: dev.apolostudios.apotags