🏷️ 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 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):**
```yaml
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

---