> For the complete documentation index, see [llms.txt](https://mending-dev.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://mending-dev.gitbook.io/docs/bossbarhud/admin-guide/configuration.md).

# Configuration

All options of config.yml, glyph widths and troubleshooting.

{% code title="plugins/BossbarHUD/config.yml" %}

```yaml
bossbar:
  # Use a color that no other bossbar on your server uses
  color: PURPLE
  overlay: PROGRESS

update-interval-ticks: 20

layout:
  gap: 4        # pixels between two boxes
  padding: 4    # pixels left and right of the text inside a box
  min-width: 0  # minimum box width in pixels

# Pixel width of glyphs, so the box length stays correct.
# Width = round(texture width * height / texture height) + 1
glyph-widths:
  # Nexo glyph id (as defined in Nexo)
  "nexo:player_icon": 9
  # A raw character works too
  # "\uE000": 9

# Global HUD from the config (PlaceholderAPI + MiniMessage).
# Other plugins can add their own HUDs through the API.
#   line:      row of the box (default 1). Boxes with the same line are placed next to each other.
#   order:     position inside the line, from left to right.
#   condition: optional, the box is only shown to players for whom it is true. Always put it in quotes.
#              Compare with = != > >= < <= (numbers or text), combine with && || ! and ( ),
#              "quoted text" for values with spaces, permission=<node> checks a permission.
segments:
  position:
    line: 1
    order: 20
    text: "<white>Your Position: %player_x%, %player_y%, %player_z%"
  # Second row:
  # player:
  #   line: 2
  #   order: 10
  #   text: "<white>Player: %player_name%"
  # Only in the nether, for players with a permission:
  # nether:
  #   line: 2
  #   order: 20
  #   text: "<red>Nether"
  #   condition: '%player_world% = world_nether && permission=hud.nether'
```

{% endcode %}

After changing the file, run `/bossbarhud reload`.

## Options

| Path                      | Description                                                                                               |
| ------------------------- | --------------------------------------------------------------------------------------------------------- |
| `bossbar.color`           | Bossbar color used for the HUD. Must match the transparent sprites in your resource pack.                 |
| `bossbar.overlay`         | Bossbar overlay: `PROGRESS`, `NOTCHED_6`, `NOTCHED_10`, `NOTCHED_12` or `NOTCHED_20`.                     |
| `update-interval-ticks`   | How often placeholders are re-evaluated. 20 ticks = 1 second.                                             |
| `layout.gap`              | Space in pixels between two boxes.                                                                        |
| `layout.padding`          | Space in pixels between the text and the left and right edge of a box.                                    |
| `layout.min-width`        | Minimum width of a box in pixels.                                                                         |
| `glyph-widths`            | Width in pixels of custom glyphs, see [Glyph widths](#glyph-widths).                                      |
| `segments.<id>.line`      | Row of the box. Default `1`. See [Lines](#lines).                                                         |
| `segments.<id>.order`     | Position of the box inside its line, from left to right.                                                  |
| `segments.<id>.text`      | Text of the box. MiniMessage and PlaceholderAPI placeholders are supported.                               |
| `segments.<id>.condition` | Optional. The box is only shown to players for whom the condition is true. See [Conditions](#conditions). |

## Boxes (segments)

Every entry under `segments` is one box of the global config HUD. All players see it. Boxes are sorted by `order`. The text supports [MiniMessage](https://docs.advntr.dev/minimessage/format.html) formatting and PlaceholderAPI placeholders.

Other plugins can add their own HUDs through the [API](/docs/bossbarhud/developer-guide/getting-started.md). Their boxes are rendered in addition to the boxes from the config.

## Lines

By default all boxes are placed next to each other in one row. With `line` you can put boxes below each other:

```yaml
segments:
  position:
    line: 1
    order: 20
    text: "<white>Your Position: %player_x%, %player_y%, %player_z%"
  player:
    line: 2
    order: 10
    text: "<white>Player: %player_name%"
```

* `line` is the row of the box. The default is `1`.
* Only the relative order of the lines counts. If the lines are `1` and `5`, there are two rows. A single box is always in the first row, no matter which line is configured.
* Several boxes can share a line. They are placed next to each other, sorted by `order`.
* Boxes of other plugins use the same lines. A box on line 2 from the API ends up in the same row as a config box on line 2.

Every row is its own bossbar with the configured color, so the resource pack hides all of them. The vertical distance between two rows is fixed by the Minecraft client (19 pixels with the default box height) and cannot be changed. The client only draws bossbars in the upper part of the screen (about a third of the height), so the number of rows you can use depends on the GUI scale.

## Conditions

With `condition` a box is only shown to the players for whom the condition is true. A box without a condition is shown to everyone.

```yaml
segments:
  nether:
    line: 2
    order: 10
    text: "<red>You are in the nether"
    condition: '%player_world% = world_nether'
  health:
    order: 30
    text: "<red>Low health: %player_health%"
    condition: '%player_health% < 6 && %player_gamemode% != CREATIVE'
  vip:
    order: 40
    text: "<gold>VIP"
    condition: 'permission=server.vip || %player_name% = "Notch"'
  not-in-lobby:
    order: 50
    text: "<white>Kills: %statistic_player_kills%"
    condition: '!(%player_world% = lobby || %player_world% = "lobby 2")'
```

| Syntax                                                    | Meaning                                                                           |
| --------------------------------------------------------- | --------------------------------------------------------------------------------- |
| `a = b` or `a == b`                                       | equal                                                                             |
| `a != b`                                                  | not equal                                                                         |
| `a > b`, `a >= b`, `a < b`, `a <= b`                      | greater, greater or equal, less, less or equal                                    |
| `x && y`                                                  | both are true                                                                     |
| `x \|\| y`                                                | at least one is true                                                              |
| `!x`                                                      | not                                                                               |
| `( ... )`                                                 | grouping                                                                          |
| `"text"` or `'text'`                                      | a value with spaces or special characters; `\"`, `\'` and `\\` escape a character |
| `permission=node`, `permission!=node`, `!permission=node` | checks a permission of the player (no LuckPerms needed)                           |
| `%placeholder%` alone                                     | true if the value is `true` or `yes` (any case), for example `%player_is_flying%` |

* If both sides are plain numbers (`12`, `-3`, `0.5`), they are compared as numbers: `%player_level% >= 10`. Otherwise they are compared as text. Text comparison is case-sensitive; `>` and `<` compare text alphabetically.
* `&&` binds stronger than `||`: `a || b && c` means `a || (b && c)`. `!` applies to the comparison right after it, so `!%player_world% = lobby` means "not in the world lobby".
* Always put the condition in quotes. Use single quotes outside, then you can use double quotes inside: `condition: '%server_name% = "My Server"'`. Without quotes, YAML fails on a leading `%` or `!`.
* A value without quotes ends at a space or at one of `( ) & | ! = < > " '`. A placeholder (`%...%` without spaces) is always one value, even if it contains one of these characters.
* Conditions are read on start and on `/bossbarhud reload`. A condition with a syntax error logs one warning that names the box and the position of the error, and the box is hidden until the condition is fixed.
* Conditions are checked for every player on every update (`update-interval-ticks`), before the text of the box is built. A box whose condition is false costs no text rendering.
* **Without PlaceholderAPI** placeholders are not replaced: the condition sees the literal text, so `%player_world% = world_nether` is always false and `%player_world% != world_nether` always true. BossbarHUD logs a warning on load for every box whose condition uses placeholders while PlaceholderAPI is missing. `permission=...` works without PlaceholderAPI.

## Glyph widths

The plugin knows the widths of the vanilla font. Custom glyphs, such as Nexo glyphs, have their own width, so you have to tell the plugin how wide they are. Otherwise the box is too short or too long.

Use the Nexo glyph id as the key. The `nexo:` prefix is optional:

```yaml
glyph-widths:
  "nexo:player_icon": 9
  weather_icon: 9
```

Width formula: `round(texture width * glyph height / texture height) + 1`. A glyph texture that is 8px wide and has the same height value as its texture height has a width of `9`.

Nexo glyph names are resolved when the server starts and again every time Nexo reloads. Unknown names are logged as warnings.

## Troubleshooting

| Problem                                   | Solution                                                                                                                                                                                                                                            |
| ----------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Nothing is visible                        | Check that the resource pack with the `hud:bg` font is active and that `bossbar.color` is set.                                                                                                                                                      |
| The bossbar bar itself is visible         | The transparent sprites do not match `bossbar.color`. Regenerate the pack with `--bossbar-color`.                                                                                                                                                   |
| Other plugins' bossbars are invisible     | They use the same color as the HUD. Change `bossbar.color` and the sprites.                                                                                                                                                                         |
| Box is too short or too long with an icon | Add the glyph to `glyph-widths`.                                                                                                                                                                                                                    |
| Placeholders show as `%player_x%`         | PlaceholderAPI or the expansion is missing.                                                                                                                                                                                                         |
| The HUD is below another bossbar          | BossbarHUD moves bars of the Paper API below its rows. Bars of the old Bukkit API (`Bukkit.createBossBar`) and vanilla bars (wither, ender dragon, raid, `/bossbar`) cannot be moved: they stay where they are if they were shown before a HUD row. |
| A box with a condition is never shown     | Look for "has an invalid condition" in the console. Without PlaceholderAPI, placeholders in conditions are compared as plain text.                                                                                                                  |
| Not all lines are visible                 | The client only draws bossbars in the upper part of the screen. Use fewer lines or a smaller GUI scale.                                                                                                                                             |