> For the complete documentation index, see [llms.txt](https://edseries-plugins.gitbook.io/p/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://edseries-plugins.gitbook.io/p/codexmomentum/momentum/bossbar.md).

# Boss Bar

A boss bar shows the player's live momentum: level, progress towards the next level and the active boost. It is sent packet-based where the server version supports it (zero main-thread cost) with an automatic fallback otherwise, and every player can hide or show it with `/momentum toggle` (persisted).

## Configuration

```yaml
bossbar:
  enabled: true
  # How often (in ticks) the async boss bar ticker refreshes titles/progress.
  update-interval-ticks: 10
  # Show the bar while still at level 0 building towards level 1.
  show-while-building: true
  # Default name/color — every level can override both (see 'levels').
  name: '&#FFD75A&l⛏ MOMENTUM &8[&#FFE7A3{level_roman}&8] &f{progress}&7/&f{required} &8│ {multiplier}'
  color: YELLOW    # PINK, BLUE, RED, GREEN, YELLOW, PURPLE, WHITE
  # Style while momentum is draining (any level).
  decaying:
    name: '&#FF6B6B&l⚠ MOMENTUM DRAINING &8[&#FFA8A8&l{level_roman}&8] &7{reason} &8│ &#FF6B6B-{rate}&7/s'
    color: RED
```

Every level can override `name` and `color` under its own `bossbar:` key — the default ladder uses this for its green-to-red heat ramp (see [Levels](/p/codexmomentum/momentum/levels.md)).

## Bar placeholders

These work in the bar `name` (default, per-level and decaying), and PlaceholderAPI placeholders work too:

| Placeholder          | Value                                                      |
| -------------------- | ---------------------------------------------------------- |
| `{level}` / `{tier}` | Current momentum level                                     |
| `{level_roman}`      | Current level as a Roman numeral                           |
| `{next_level}`       | The next level number                                      |
| `{max_level}`        | Highest configured level                                   |
| `{progress}`         | Progress blocks within the current level                   |
| `{required}`         | Blocks required for the next level                         |
| `{remaining}`        | Blocks still missing for the next level                    |
| `{percent}`          | Progress percentage                                        |
| `{time}`             | Current streak duration                                    |
| `{blocks}`           | Total blocks this streak                                   |
| `{multiplier}`       | The level's `multiplier-display`                           |
| `{reason}`           | Why momentum is draining (from `messages.yml` → `reasons`) |
| `{rate}`             | Current drain speed in blocks per second                   |

{% hint style="info" %}
The bar's fill always reflects progress towards the next level; while draining you watch it empty in real time at `update-interval-ticks` resolution.
{% endhint %}