🏷️ 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

Dependency	Type	Version
Paper	Required	1.19.4
Java	Required	17+
PlaceholderAPI	Optional	2.11.6+

---

🚀 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

Command	Description
/tags	Open the tag selector GUI
/tags list	List your available tags and active tag
/tags select <id>	Equip a tag
/tags version	Show plugin version
/tags help	Show all commands you have access to

Admin Commands

Command	Description
/tags admin	Open the admin management GUI
/tags list all	List every loaded tag
/tags list <player>	List a specific player's available tags
/tags set <player> <id>	Assign a tag to a player
/tags clear <player>	Remove a player's active tag
/tags create <id> <tag>	Create a new tag
/tags delete <id>	Permanently delete a tag
/tags enable <id>	Enable a disabled tag
/tags disable <id>	Disable a tag (hides it from all players)
/tags setorder <id> <n>	Change a tag's display order
/tags setdisplay <id> <tag>	Change a tag's display string
/tags setdesc <id> <desc>	Change a tag's lore (| for multiple lines)
/tags reload	Reload all config files without restart

---

🔐 Permissions

Bundles

Permission	Default	Description
apotags.*	false	Grants every ApoTags permission
apotags.use	true	Grants all player commands
apotags.admin	op	Grants all admin commands (inherits apotags.use)
apotags.reload	op	Grants /tags reload
apotags.tag.all	op	Bypasses all per-tag permission checks

Granular Command Nodes

Permission	Default	Command
apotags.command.tags	true	/tags
apotags.command.list	true	/tags list
apotags.command.select	true	/tags select
apotags.command.version	true	/tags version
apotags.command.help	true	/tags help
apotags.command.admin	op	/tags admin
apotags.command.list.all	op	/tags list all
apotags.command.list.player	op	/tags list <player>
apotags.command.set	op	/tags set
apotags.command.clear	op	/tags clear
apotags.command.create	op	/tags create
apotags.command.delete	op	/tags delete
apotags.command.enable	op	/tags enable
apotags.command.disable	op	/tags disable
apotags.command.setorder	op	/tags setorder
apotags.command.setdisplay	op	/tags setdisplay
apotags.command.setdesc	op	/tags setdesc
apotags.command.reload	op	/tags reload

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.

Placeholder	Returns
%apotags_tag%	Active tag with color codes (legacy §-format). Returns "" if none or disabled.
%apotags_tag_plain%	Active tag with all color codes stripped
%apotags_tag_id%	The raw Tag ID (e.g. VIP). Returns "" if none.

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

---