ApoTags

🏷️ ApoTags

<div align="center">

<!-- Replace with your actual banner URL -->

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.

Paper

Java

PlaceholderAPI

</div>

---

✨ Features

- 🎨 Zero hardcoded text — use `&#RRGGBB` hex codes and legacy `&` codes anywhere - 🖥️ Zero hardcoded text — browse and equip tags with a clean inventory menu - 🛠️ Zero hardcoded text — manage all tags in-game, toggle enable/disable with Shift+Click - 💾 Zero hardcoded text or Zero hardcoded text storage — no external database setup required - 📡 Zero hardcoded text — display active tags in chat, tab, scoreboards, and more - 🌍 Zero hardcoded text — built-in English and Spanish, easily add any language - ⚙️ Zero hardcoded text — separate `gui_user.yml` and `gui_admin.yml` config files - 🔐 Zero hardcoded text — one permission node per subcommand for maximum control - 🔄 Zero hardcoded text — apply any config or tag changes without restarting the server - 🏷️ Zero hardcoded text — 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`

```yaml

─────────────────────────────────────────────

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

```yaml 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

```yaml 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

```yaml 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): ```yaml format: '{prefix}%apotags_tag%%displayname%&r: {message}' ```

TAB plugin example: ```yaml tabprefix: '%apotags_tag%' ```

---

🌍 Language Support

ApoTags ships with Spanish (`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`: ```yaml 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`

---

<div align="center">

Made with ❤️ by ApoStudios & ApoStudios

</div>