🏷️ ApoTags

Logo

The complete RGB tag manager for Paper servers.
Give your players beautifully colored prefix tags — with full GUI, PlaceholderAPI support, and zero file editing required.

✨ 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

Download ApoTags.jar and drop it into your /plugins/ folder
Start or restart your server
All config files are generated automatically on first launch
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:

Copy plugins/ApoTags/lang/en.yml → plugins/ApoTags/lang/<code>.yml
Translate all values (keep all keys and {tokens} unchanged)
Set locale: '<code>' in config.yml
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

Made with ❤️ by ApoloCR & ApoStudios

ApoTags

📖About ApoTags