# 🏷️ 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 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: '�f2ff&l[APO] ' lore: - '�f2ffExclusive 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: '�f2ff&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 ` | 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 ` | List a specific player's available tags | | `/tags set ` | Assign a tag to a player | | `/tags clear ` | Remove a player's active tag | | `/tags create ` | Create a new tag | | `/tags delete ` | Permanently delete a tag | | `/tags enable ` | Enable a disabled tag | | `/tags disable ` | Disable a tag (hides it from all players) | | `/tags setorder ` | Change a tag's display order | | `/tags setdisplay ` | Change a tag's display string | | `/tags setdesc ` | 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 ` | | `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.` where `` 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:** ```yaml 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/

.yml`
2. Translate all values (keep all keys and `{tokens}` unchanged)
3. Set `locale: ''` 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. �f2ff
&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**

ApoloStudios

ApoTags

Информация