> For the complete documentation index, see [llms.txt](https://axiomemu.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://axiomemu.gitbook.io/docs/data/plugins/tooltipexpansion.md).

# TooltipExpansion

Add custom text labels to item tooltips, a secondary info panel, and colored tooltip borders — filtered per item, level, luck, skill, +option, excellent and ancient state.

Injects custom text into item tooltips without touching any game logic. Labels can appear inside the main tooltip (above the name, above the option list, above the class requirements, or at the end), or in a **secondary panel** rendered beside the main tooltip. Border rules tint the tooltip frame. Everything is display-only: use it to advertise set bonuses, per-level unlock tables, Jewel of Life ladders, server rules — anything you want players to read on hover.

All data is synced from the server at login, so tweaks reach every player without a client patch (after relog).

## File Location

`GameServer/Data/Plugins/Items/TooltipExpansion.xml`

## Dependencies

* Purely cosmetic — pair labels with real bonuses configured in [ItemOption](/docs/data/item/itemoption.md), [SetItemOption](/docs/data/item/setitemoption.md), etc. Labels do **not** grant stats.
* Reloadable via the in-game reload command; players must **relog** to receive updated data.

## Configuration Sections

### Root

```xml
<TooltipExpansion Enabled="1">
```

`Enabled="0"` turns the whole feature off (nothing is synced to clients).

### `<Colors>`

A palette of reusable color indices referenced by labels.

| Attribute           | Range   | Meaning                                                                 |
| ------------------- | ------- | ----------------------------------------------------------------------- |
| `Index`             | 0–999   | Palette slot referenced by `<Label Color="...">`                        |
| `TextR/TextG/TextB` | 0.0–1.0 | Text color                                                              |
| `BgR/BgG/BgB/BgA`   | 0.0–1.0 | Background pill behind the line. `BgA="0"` (or omitted) = no background |

{% hint style="info" %}
Background pills are how you build MSPro-style section headers — e.g. white-on-orange "Jewel Of Life Options".
{% endhint %}

### `<Labels>`

One `<Label>` per text line. **Filters** decide which items show it; omit an attribute (or set `-1`) to skip that check.

| Filter attribute                | Range  | Matches when                                                                                                    |
| ------------------------------- | ------ | --------------------------------------------------------------------------------------------------------------- |
| `ItemMinIndex` / `ItemMaxIndex` | 0–8191 | Item's absolute index (Group × 512 + Id) is inside the range. Example: all weapons (groups 0–5) = `0` to `3071` |
| `ItemLvlMin` / `ItemLvlMax`     | 0–15   | Item plus-level inside the range                                                                                |
| `SkillSwitch`                   | 0/1    | 1 = item has Skill, 0 = item must NOT have Skill                                                                |
| `LuckSwitch`                    | 0/1    | 1 = has Luck, 0 = no Luck                                                                                       |
| `AditionalMin` / `AditionalMax` | 0–15   | +Option (Jewel of Life) level inside the range                                                                  |
| `ExcMin` / `ExcMax`             | 0–63   | Excellent bitmask inside the range. `1`/`63` = any excellent item, `0`/`0` = not excellent                      |
| `Ancient`                       | 0–3    | 0 = not ancient, 1 = ancient tier 1, 2 = tier 2, 3 = any ancient                                                |

Rendering attributes:

| Attribute   | Range      | Meaning                                                                                                                        |
| ----------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `Position`  | 0–4        | 0 = before item name, 1 = before the option block, 2 = before class requirements, 3 = end of tooltip, 4 = secondary side panel |
| `BreakLine` | 0–10       | Blank lines rendered before this label                                                                                         |
| `Color`     | 0–999      | Palette index from `<Colors>` (unknown index = plain white)                                                                    |
| `Bold`      | 0/1        | Bold font                                                                                                                      |
| `Text`      | ≤159 chars | The line itself. Empty text = spacer row (only `BreakLine` applies)                                                            |

Labels render in **file order** within each position.

### `<Borders>`

Same filter attributes as labels, plus `R/G/B/A` (0.0–1.0) for the tooltip frame color. The **first matching rule wins**.

## Important Behavior

* The secondary panel (Position 4) renders to the **left** of the main tooltip. When the ancient-set list panel is visible it stacks further left of that panel, and clamps at the screen edge.
* Labels longer than \~99 characters are truncated by the client's tooltip line buffer.
* The tooltip has a hard cap of \~48 lines total (native lines + injected ones); overflowing labels are dropped silently.
* Filters match the **live item state** — a label gated on `AditionalMin="3"` appears the moment the item reaches +Option 3.

## Examples

{% tabs %}
{% tab title="JoL ladder (side panel)" %}

```xml
<Labels>
  <Label ItemMinIndex="0" ItemMaxIndex="3071" Position="4" BreakLine="1" Color="17" Bold="1" Text="Jewel Of Life Options" />
  <!-- next step grey, reached step green -->
  <Label ItemMinIndex="0" ItemMaxIndex="3071" AditionalMin="0" AditionalMax="0" Position="4" Color="10" Text="|Level:1| Double damage rate +2%" />
  <Label ItemMinIndex="0" ItemMaxIndex="3071" AditionalMin="1" AditionalMax="1" Position="4" Color="4"  Text="|Level:1| Double damage rate +2%" />
  <Label ItemMinIndex="0" ItemMaxIndex="3071" AditionalMin="1" AditionalMax="1" Position="4" Color="10" Text="|Level:2| Double damage rate +4%" />
</Labels>
```

{% endtab %}

{% tab title="Ancient note (in tooltip)" %}

```xml
<Labels>
  <Label ItemMinIndex="0" ItemMaxIndex="6143" Ancient="3" Position="3" BreakLine="1" Color="13" Text="Full set bonuses listed in the wiki" />
</Labels>
```

{% endtab %}

{% tab title="Borders" %}

```xml
<Borders>
  <Border ItemMinIndex="0" ItemMaxIndex="6143" Ancient="3" R="1.0" G="0.8" B="0.5" A="0.8" />
  <Border ItemMinIndex="0" ItemMaxIndex="6143" ExcMin="1" ExcMax="63" R="0.0" G="1.0" B="0.6" A="0.8" />
</Borders>
```

{% endtab %}
{% endtabs %}

## Common Issues

* **Labels don't appear**: check the GameServer log for `[TooltipExpansion]` skip warnings (bad `Position`, out-of-range `Index`), confirm `Enabled="1"`, and relog — data is only sent at login.
* **Wrong items match**: remember `ItemMinIndex`/`ItemMaxIndex` are absolute indices (Group × 512 + Id), not group/id pairs.
* **Header has no colored background**: the referenced `<Color>` needs `BgA` above 0.