> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rpg-leveling.zuxaw.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Chat placeholders (Essentials & more)

> Use %rpglevelling_*% tokens in server chat formats (e.g. Essentials) - level, XP, class.

# Chat placeholders (Essentials & more)

RPG Leveling fills **chat format strings** with **level**, **XP**, and **class** via **`%rpglevelling_*%`** or **`{rpglevelling_*}`** (curly form matches Essentials **`{player}`** / **`{message}`** style).

**Recommended for Essentials Plus–style configs:** install **[Placeholder API](https://www.curseforge.com/hytale/mods/placeholder-api)** (optional dependency; mod id **`HelpChat:PlaceholderAPI`**). RPG Leveling registers identifier **`rpglevelling`** so **`%rpglevelling_level%`** and similar tokens are resolved when your chat mod runs placeholders on the **format string**. Without it, RPG Leveling still patches built **`Message`** trees and reflects some **`PlayerChatEvent`** fields as a fallback-enough in many setups, but not a full substitute for string-level PAPI.

Use this when you configure **Essentials Plus** or any mod with **global / per-group** chat format text.

**Step-by-step (Essentials Plus):** [Level display in chat formatting (Essentials Plus)](level-display-chat-formatting) - enable **`chat.enabled`**, edit **`mods/fof1092_EssentialsPlus/config.json`** → **`chat.groups`**, put **Lv** and **class** next to **`{player}`** (RPG tokens stay **`%rpglevelling_*%`**).

***

## Supported tokens

Spell the prefix with **two `l`** characters: **`rpglevelling`** (not `rpgleveling`). Matching is **case-insensitive** (`%RPGLEVELLING_LEVEL%` and `{RpgLevelling_Level}` work the same).

Each token works as **`%rpglevelling_…%`** or **`{rpglevelling_…}`** (no `%` inside braces).

| Token (percent or `{…}` form) | Replaced with                                          |
| ----------------------------- | ------------------------------------------------------ |
| `level`                       | Current level (number)                                 |
| `xp`                          | Current XP (number)                                    |
| `xp_to_next`                  | XP needed for next level (same as below)               |
| `xp_to_level`                 | XP needed for next level                               |
| `max_level`                   | Configured max level                                   |
| `is_max_level`                | `true` or `false`                                      |
| `class`                       | Localized class display name (same as `class_display`) |
| `class_display`               | Localized display name                                 |
| `class_name`                  | Raw class display name from class config               |
| `class_id`                    | Internal class id (e.g. `Heavy`, `Archery`)            |
| `class_tier`                  | Tier for the selected class (0–4)                      |

**Examples:** `%rpglevelling_level%` or `{rpglevelling_level}`; `%rpglevelling_class%` or `{rpglevelling_class}`.

If the player has **no class selected**, class-related tokens resolve to **empty** (or `0` for tier where applicable).

***

## Example: Essentials Plus–style chat format

A common goal is a line similar to:

```text theme={null}
[Player] Lv.%rpglevelling_level% %rpglevelling_class% {player}: {message}
```

* **`%rpglevelling_*%`** - resolved by **PlaceholderAPI** (when installed) on the format string, and/or patched on the final **`Message`** by RPG Leveling.
* **`{player}`**, **`{message}`**, etc. - defined by **Essentials Plus** (or whatever chat mod you use). Use the **exact placeholders your chat mod documents** for display name and message body.

**Where to edit:** for **Essentials Plus**, open **`mods/fof1092_EssentialsPlus/config.json`** and the **`chat.groups`** object (see [Level display in chat formatting (Essentials Plus)](level-display-chat-formatting)). Other mods may use **`config.toml`** or different keys.

**Minimal JSON fragment** (Essentials Plus shape - your **`groups`** keys must match permission groups):

```json theme={null}
"chat": {
  "enabled": true,
  "groups": {
    "Default": "<#00AA00><bold>Lv.%rpglevelling_level% %rpglevelling_class% {player}: </bold></#00AA00><#AAAAAA>{message}</#AAAAAA>"
  }
}
```

Run **`/essentialsplus reload`** (or restart the server) after saving.

***

## Other placeholders in the same string

RPG Leveling **only** supplies **`rpglevelling_*`** values. Other **`%...%`** tokens come from **PlaceholderAPI** and your chat mod. If **`%rpglevelling_*%`** stays literal, add **[Placeholder API](https://www.curseforge.com/hytale/mods/placeholder-api)** and confirm **RPG Leveling** is loaded (expansion **`rpglevelling`**).

***

## Troubleshooting

| Issue                                                                | What to check                                                                                                                                                                                                        |
| -------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **`%rpglevelling_level%` or `{rpglevelling_level}` shows literally** | Typo: **`rpglevelling`** (two `l`). Install **[Placeholder API](https://www.curseforge.com/hytale/mods/placeholder-api)** if your chat mod only expands placeholders on strings. Confirm **RPG Leveling** is loaded. |
| **Level always `1`**                                                 | Usually means the player’s data was read before the world/store was ready; report with game version and other mods if it persists.                                                                                   |
| **Class token empty**                                                | Player may have **no class selected** in the Stats GUI.                                                                                                                                                              |
| **Another placeholder shows literally**                              | Confirm the token name in your **chat mod’s** docs; RPG Leveling only expands `%rpglevelling_*%`.                                                                                                                    |

***

## For mod developers

Other plugins can read the same data from **`RPGLevelingAPI`** (see [API](api)); the chat tokens above are a **convenience for config strings**, not a second API surface.