> For the complete documentation index, see [llms.txt](https://simple.superiormc.cn/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://simple.superiormc.cn/arcmenu-wiki/feature-configuration/tooltips.md).

# Tooltips

Tooltips show explanatory text when a player points at a hit region, without requiring a click. Use them for button descriptions, control hints and dynamic player information.

This feature is available on Paper, Folia, Leaf and similar servers. Spigot does not display tooltips. Content belongs in the menu's `backend`; shared appearance settings belong in `plugins/ArcMenu/tooltip.yml`.

## Region tooltip content

The hierarchy is **`backend` → region name → `tooltip` and `update`**.

```yaml
backend:
  information-area:
    x: 0
    y: 0
    width: 80
    height: 24
    tooltip:
      - '&fServer information'
      - '&7Player: %player_name%'
      - '&eRight-click to view details.'
    update: 20
    actions:
      right:
        - 'tell: &aDetails requested.'
```

Merge this fragment into an existing menu. Configure the corresponding button's visible content in `frontend`.

| Field     | Purpose                                                                                                              |
| --------- | -------------------------------------------------------------------------------------------------------------------- |
| `tooltip` | One string or a list of lines, supporting color codes and placeholders.                                              |
| `update`  | Periodic text refresh interval in game ticks: `-1` disables periodic refresh; positive integers specify an interval. |

`update` defaults to `-1` and does not accept `0`. At normal server speed, `20` ticks are approximately `1` second. Pointing at a new region updates its tooltip. For changing data while hovering, use an interval or `refresh: region-name` to refresh the currently pointed region.

Tooltips hide when the pointer leaves a region or enters one without tooltip text. Overlapping regions show only the selected region's tooltip. A selected region without text does not fall back to a lower region.

A region's `condition` controls click actions and does not hide its tooltip. Tooltip text does not establish permission to perform the operation. See [Conditions](/arcmenu-wiki/menu-configuration/menus/conditions.md).

## Appearance file structure

The top-level `touch` and `mouse` sections in `tooltip.yml` configure each input mode. They can use different sizes, positions and backgrounds. Settings apply to all menus in that mode.

When the entire `mouse` section is omitted, mouse mode inherits the complete touch style. If `mouse` exists, edit its fields directly.

This example uses a plain color background without an image skin:

```yaml
touch:
  offset: {x: 6, y: 4.27, z: 5}
  anchor: top-left
  wrap: false
  size: 2.989
  line-width: 180
  background: '#D0101010'

mouse:
  offset: {x: 6, y: 4.27, z: 5}
  anchor: top-left
  wrap: false
  size: 4.375
  line-width: 180
  background: '#D0101010'
```

The bundled configuration includes an image `skin`. To use the plain background above, remove the entire `skin` section for the corresponding mode. Changing only `background` does not disable the skin.

### Mode properties

These fields belong directly under `touch` or `mouse` at the same level.

| Field        | Purpose                                                                |
| ------------ | ---------------------------------------------------------------------- |
| `offset`     | Tooltip offset from the pointer position, with `x`, `y` and `z`.       |
| `anchor`     | Which tooltip corner aligns with the pointer position plus the offset. |
| `wrap`       | Whether text wraps at `line-width`: `true` or `false`.                 |
| `size`       | Tooltip text size, greater than `0`.                                   |
| `line-width` | Automatic wrapping width, a positive integer in text pixels.           |
| `background` | Plain background color including opacity, as `'#AARRGGBB'`.            |
| `skin`       | Optional image background, described below.                            |

### Placement and alignment

Touch mode uses the crosshair target position; mouse mode uses the cursor tip. Positive `offset.x` moves right, positive `offset.y` moves up and positive `offset.z` moves toward the player. Horizontal and vertical offsets use menu coordinate units.

| `anchor`       | Fixed corner  | Expansion direction |
| -------------- | ------------- | ------------------- |
| `top-left`     | Top left.     | Right and down.     |
| `top-right`    | Top right.    | Left and down.      |
| `bottom-left`  | Bottom left.  | Right and up.       |
| `bottom-right` | Bottom right. | Left and up.        |

Choose a direction suited to the button's position so long tooltips do not cover it or extend beyond the screen. The chosen corner remains the alignment reference when text length changes.

### Text and plain backgrounds

With `wrap: false`, each list entry occupies one line without automatic wrapping at `line-width`. Use a `tooltip` list to control multiple lines. With `wrap: true`, long lines can wrap at the specified width.

`line-width` uses text pixels, unlike a region's `width`. Changing `size` changes displayed text size. Check long text and different fonts on actual clients.

`background` requires an eight-digit hexadecimal color in quotes. The first two digits, `AA`, specify opacity: `00` is transparent and `FF` is opaque. `'#D0101010'` gives a translucent dark background. The six-digit format used for frontend rectangles does not apply here.

## Image backgrounds: `skin`

Image skins resize around the text. Corners retain their shape while edges and the center extend with the tooltip. Image paths follow the same rules as menu images; see [Images and resource packs](/arcmenu-wiki/feature-configuration/resource-packs.md).

Merge this fragment into `touch` in `tooltip.yml`. Configure the same structure under `mouse` for mouse mode:

```yaml
touch:
  skin:
    background: /ce/topaz_background.png
    frame: /ce/topaz_frame.png
    border: 8
    padding: {left: 8, right: 8, top: 8, bottom: 8}
    min-size: {width: 24, height: 24}
    size-adjust: {width: 0, height: 0}
    offset: {x: 0, y: 0, z: -0.25}
    scale: {x: 1.0, y: 1.0}
    text-offset: {x: 0, y: 0, z: 0}
```

These bundled images do not require CraftEngine. They live in `images/ce/`, and players still need a pack containing them.

When `skin` is configured, its images replace the mode's plain `background` color. Remove the entire `skin` section to restore the plain color background.

### Images and dimensions

These properties belong under `skin`.

| Field         | Purpose and requirements                                                                                                 |
| ------------- | ------------------------------------------------------------------------------------------------------------------------ |
| `background`  | Required background PNG path; the image must exist.                                                                      |
| `frame`       | Optional frame PNG. It must exist and match the background image's dimensions.                                           |
| `border`      | Edge width retained from the original image, a positive integer in pixels, less than half both image dimensions.         |
| `padding`     | Space between text and background edges: nonnegative integer `left`, `right`, `top` and `bottom`.                        |
| `min-size`    | Minimum tooltip dimensions: integer `width` and `height`, each at least `2 × border + 1`.                                |
| `size-adjust` | Integer `width` and `height` adjustments to the calculated size. The adjusted minimum must still accommodate the border. |

`border` uses original PNG pixels. `padding`, `min-size` and `size-adjust` use tooltip text pixels; text size and skin scaling affect their displayed dimensions.

The example's `border: 8` requires an original image wider and taller than `16` pixels and minimum tooltip dimensions of at least `17`. The example uses `24` to leave room for text and edges.

A missing skin background or frame fails the resource build. It does not merely hide an element as a missing ordinary menu image would.

### Background and text placement

| Field         | Child fields  | Purpose                                                                                              |
| ------------- | ------------- | ---------------------------------------------------------------------------------------------------- |
| `offset`      | `x`, `y`, `z` | Moves the image background from its original position without moving text with it.                   |
| `scale`       | `x`, `y`      | Positive horizontal and vertical skin scales; also affect text layout spacing inside the background. |
| `text-offset` | `x`, `y`, `z` | Adjusts text position without moving the background.                                                 |

`skin.offset` and `skin.text-offset` use menu coordinates and depth ordering. The mode-level `offset` moves the whole tooltip, while `skin.offset` moves only the image background.

Skin scaling does not change text size in place of the mode's `size`. To enlarge the complete tooltip, adjust `size` first and check spacing and edges afterward.

### Image alignment adjustments

The bundled configuration also offers these optional fields under `skin`. Keep them at `0` for ordinary use; adjust them when custom artwork has visible seams or alignment issues.

| Field           | Child fields              | Purpose                                                          |
| --------------- | ------------------------- | ---------------------------------------------------------------- |
| `seam-overlap`  | `x`, `y`                  | Nonnegative overlap between adjacent image parts to reduce gaps. |
| `glyph-offset`  | `x`, `y`                  | Adjusts all image parts together.                                |
| `column-offset` | `left`, `center`, `right` | Adjusts the left, center and right columns separately.           |
| `row-offset`    | `top`, `center`, `bottom` | Adjusts the top, center and bottom rows separately.              |

These adjustments use tooltip text pixels and scale with `size` and `skin.scale`. They do not change hit regions or move tooltip text.

## Loading and checking

For changes only to menu tooltip content, refresh intervals or placement of existing backgrounds, run `/arcmenu validate` and `/arcmenu reload`, then reopen the menu.

For new or replacement skins, changes to `skin.background`, `skin.frame` or `skin.border`, or edited PNG files, use `/arcmenu reload all` and have players load the updated pack. See [Images and resource packs](/arcmenu-wiki/feature-configuration/resource-packs.md) for CraftEngine rebuilding and distribution.

Check both modes with a normally opened menu:

* Tooltips appear when pointing at regions and hide when leaving.
* Multiple lines, placeholders and periodic updates behave as expected.
* The anchor and offsets leave important controls visible.
* Image edges, text padding and long tooltips display correctly.

Preview mode is unsuitable for checking complete tooltip interactions. If a tooltip is missing, check whether another region covers it, whether `tooltip` is configured and whether the server is Spigot. Check the resource pack when image appearance is incorrect.