# Overview

<p align="center"><br>A premium solution for advanced stacked name tags (featuring plain text, items, and blocks) above player heads on Paper servers.</p>

<p align="center"><a href="https://discord.gg/W4Fu8fqCKs"><img src="https://img.shields.io/discord/1263414013040263249?label=Discord&#x26;logo=discord&#x26;color=5865F2" alt="Discord"></a> <a href="https://github.com/alexdev03/UnlimitedNameTags/releases/latest"><img src="https://img.shields.io/github/v/release/alexdev03/UnlimitedNametags?color=blue" alt="Release"></a></p>

> \[!NOTE] This is the documentation for **UnlimitedNameTags v2.x (current)**. If you are using the legacy version 1.x, please refer to the [v1 Wiki](/unlimitednametags/v1.md).

This wiki is the official documentation for [**UnlimitedNameTags**](https://github.com/alexdev03/UnlimitedNameTags) on GitHub.

| Requirement             | Details                                                                                               |
| ----------------------- | ----------------------------------------------------------------------------------------------------- |
| **Server Software**     | **Paper 1.21.4+** (Paper or its forks are highly recommended)                                         |
| **Required Dependency** | [**PacketEvents**](https://modrinth.com/plugin/packetevents) (must be installed as a standard plugin) |
| **Main Configuration**  | `plugins/UnlimitedNameTags/settings.yml` (automatically generated on first run)                       |
| **Advanced Tweaks**     | `plugins/UnlimitedNameTags/advanced.yml` (optional configuration file for helmet height adjustment)   |

***

## 📂 Documentation Directory

Our documentation is structured according to the **Divio System** to help you find the exact information you need, whether you are installing the plugin for the first time or writing custom integrations.

### 🏁 Tutorials & Getting Started

* [**What's New in v2**](/unlimitednametags/whats-new-v2.md): Highlights of the major new features and improvements from v1 to v2.
* [**Getting Started**](/unlimitednametags/getting-started.md): Installation process, requirements, and basic setup.
* [**Migration Guide**](/unlimitednametags/migration.md): Upgrading from legacy configuration structures (v1.x) to v2.x.

### 🛠️ How-To Guides

* [**Display Groups**](/unlimitednametags/features/display-groups.md): Learn how to stack lines, adjust layouts, and use custom text, items, or blocks.
* [**Animations**](/unlimitednametags/features/animations.md): Add physical movement, colors, and dynamic gradients to name tags.
* [**Show While Looking**](/unlimitednametags/features/show-while-looking.md): Display name tags dynamically based on viewer crosshair target.
* [**Advanced Configuration**](/unlimitednametags/features/advanced-yml.md): Fine-tune custom name tag height offsets using `advanced.yml`.
* [**Placeholder Replacements**](/unlimitednametags/features/placeholders-replacements.md): Clean and map raw PlaceholderAPI (PAPI) outputs.

### 📚 Reference Manuals

* [**Configuration Reference**](/unlimitednametags/configuration.md): A detailed breakdown of every main `settings.yml` option.
* [**Commands & Permissions**](/unlimitednametags/commands-permissions.md): Full list of `/unt` command usage and permission nodes.
* [**Developer API**](/unlimitednametags/api.md): Java API (Application Programming Interface) integration documentation for custom developers.
* [**Integrations**](/unlimitednametags/integrations.md): External plugin compatibility details (Nexo, Oraxen, Geyser, etc.).

### 💡 Explanations & Troubleshooting

* [**Performance Tuning**](/unlimitednametags/performance.md): Best practices for running the plugin on active or large servers.
* [**FAQ**](/unlimitednametags/faq.md): Answers to common setup questions and troubleshooting steps.

***

## 📋 Compatibility & Requirements

### Server Platform

* **Paper 1.21.4+** is required. Paper provides optimized packet handling and API support necessary for rendering custom displays.

### Java Clients

> \[!WARNING] Custom displays require **Minecraft Java 1.19.4 or newer**. Older clients (pre-1.19.4) do not support the game engine rendering features required by this plugin. Using protocol support plugins like **ViaVersion** will not bypass this native client-side rendering limitation.

### Bedrock Edition (Geyser)

* **Geyser/Bedrock** players are partially supported. However, visual features (e.g., custom colors, custom backgrounds, multi-line alignments) may render differently compared to Java Edition clients due to Bedrock rendering engine limitations.

***

## 🚀 Support

Need assistance? Join the community on our [**Discord Server**](https://discord.gg/W4Fu8fqCKs).

* To receive support, please open a ticket in the designated channel and verify your license when prompted.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://alexdev-s-organization.gitbook.io/unlimitednametags/readme.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.