Feature guide: Bossbar
Bars with text on top of the screen originally designed to display health of ender dragon & wither, but plugins found another use for it. In 1.9 mojang added a packet dedicated to displaying text without requiring an entity and allowing customizable color and style as well.
This feature can be configured in config.yml under bossbar section.
bossbar:
bars:
MyBossbar:
style: "PROGRESS"
color: "%animation:barcolors%"
progress: "100"
text: "&fWebsite: &bwww.domain.com"
Every bossbar line has 4 properties:
Type of bossbar division. Only visible on 1.9+ clients.
You can choose from 5 styles: PROGRESS, NOTCHED_6, NOTCHED_10, NOTCHED_12 and NOTCHED_20
These were defined by mojang, no other options are available. Other plugins may be using different names, but it's the same result in the end.
Color of bossbar. Only visible on 1.9+ clients. Old clients will see it purple.
You can choose from 7 colors: BLUE, GREEN, PINK, PURPLE, RED, WHITE and YELLOW
These were defined by mojang, no other options are available.
A number from 0 to 100. Accepts decimals.
If you want to show the progress of a placeholder's value relative to a maximum one, you can use the Math Expansion from PlaceholderAPI and use a placeholder like this one: %math_{placeholder_current_value}/{placeholder_max_value}*100% or %math_{placeholder_current_value}/<max_value>*100% if your max value is fixed.
Notes:
Replace the text in between the {} with the actual placeholder you want to use and <max_value> with a valid number (i.e. 20).
You cannot use the %placeholder% format inside the math placeholder.
Example for showing a player's health: %math_{player_health}/20*100% or %math_{player_health}/{player_max_health}*100%
Text of the bossbar. Length is not limited, supports RGB codes on 1.16+. Does not support newlines.
When set to true, the bossbar will not appear by default, only when used in announce command.
bossbar:
bars:
MyBossbar:
style: "PROGRESS"
color: "BLUE"
progress: "100"
text: "Text"
announcement-bar: true #false or undefined means it will be visible all the time
Condition that must be met for player to see the bossbar. Even when using announce command on a bossbar with display condition, players must meet it to see the bossbar. When condition is not defined, bossbar has no requirement to be displayed.
Example:
bossbar:
bars:
MyBossbar:
style: "PROGRESS"
color: "BLUE"
progress: "100"
text: "This bossbar is only visible in world 'world'"
display-condition: "%world%=world"
/tab announce bar <name> <time>
name is name of bossbar defined in bossbar.yml, time is length of display time in seconds.
When using a bossbar announcement, you have a new placeholder available: %countdown% that shows remaining time of the announce in seconds. You can further use this placeholder in progress for example, using Math expansion from PlaceholderAPI, such as %math_{tab_placeholder_countdown}/<total time>*100%.
| Option name | Default value | Description |
|---|---|---|
| enabled | false | Enables / Disables the feature |
| toggle-command | /bossbar | A command to toggle bossbar visibility for player running the command. This command requires tab.bossbar.toggle permission. Note: This command will not appear in command auto-complete, because it's not a real registered command. Registered commands must be defined in plugin jar directly and cannot be dynamic. If you want to solve this, you can try getting a dummy private plugin made which registers that command. |
| remember-toggle-choice | false | When enabled, disabling bossbar using bossbar-toggle-command is remembered between reloads and restarts. |
| hidden-by-default | false | When enabled, bossbar will automatically be hidden until toggle command is used. |
| disable-in-worlds | List | List of worlds where the feature should be disabled. See Disabling features in worlds / servers for more info. |
| disable-in-servers | List | List of servers where the feature should be disabled. See Disabling features in worlds / servers for more info. |
- Will not display at all if TAB is installed on bungeecord (bungeecord is missing entity packets needed to make it work)
- Doesn't offer color and style features.
- Only one line can be displayed at a time.
- You can see the fog if you don't disable particles in options.
- Text length is limited to 64 characters on <1.7
- May not be visible when looking at blocks
If you want to hide the bossbar itself and only show text, this is possible, but not from the plugin's side. You'll need to create a custom resource pack where the bar doesn't show up and only text does. Then, you need to force your players to get the resource pack.
To get started with the API, see Developer API page.
To access this feature, you'll need to obtain BossBarManager instance. Get it using TabAPI.getInstance().getBossBarManager(). If this feature is disabled, the method will return null.
A boss bar is made up of a few things:
- A name. This is either the name given in the config, if the bar was loaded from the config, or a random UUID string when created with API.
- A title. This is the display message of the boss bar. If placeholders are used, this will contain their raw identifiers, without replacement.
- The progress from 0 to 100.
- The color. This determines what colour the boss bar will appear when it is shown to clients.
- The style. This determines how many segments, if any, the boss bar will be split in to.
To create a boss bar, you can use BossBarManager#createBossBar.
The first variant of this (BossBarManager#createBossBar(String, floar, BarColor, BarStyle) accepts direct values.
The second variant accepts all of the previous as strings, to allow for placeholders, though the given placeholders must adhere to the following requirements:
- Progress placeholders MUST return something that can be converted to a float with
Float.valueOf(String). - Colour and style placeholders MUST return something that can be converted to a
BarColororBarStylerespectively, usingEnum#valueOf(String).
To retrieve a boss bar, you can either get by name (for boss bars defined in the configuration), or by unique ID (for boss bars defined by the API and you lost the reference), using BossBarManager#getBossBar.
To toggle a player's boss bar, you can use BossBarManager#toggleBossBar, which accepts a TabPlayer, the target player to toggle the boss bar for, and a boolean, whether to send a message to the player indicating that their boss bar has been toggled.
To determine whether a given player can see their boss bar, use BossBarManager#hasBossBarVisible, and to set whether they have their boss bar visible, use BossBarManager#setBossBarVisible.
To send a boss bar to a player, use BossBarManager#sendBossBarTemporarily, which accepts a TabPlayer, the target player to send the boss bar to, a String, the name of the boss bar to send, and an int, the duration that the boss bar will be shown for in milliseconds.
To send a boss bar to all players on the server using BossBarManager#announceBossBar, which accepts a String, the name of the boss bar, and an int, the duration that the boss bar will be displayed for before it disappears.
To retrieve the list of currently announced boss bars, use BossBarManager#getAnnouncedBossBars.
The way of displaying information in bossbar is completely different on 1.8 and 1.9+. Here you can find out why.
Server owners have always been looking for ways to display information. Another way they discovered is by spawning a fake ender dragon / wither, making it invisible, giving it custom name and teleporting it near player. This way, however, has several flaws as you can see above. As of 1.9, mojang decided to add a packet purely for displaying text without requiring an entity. They also added options to set color and style of the bossbar.
With introduction of 1.9 bossbar which is much easier to use, plugins have switched over to that method. However, this feature cannot be used for <1.9 clients as the feature did not exist back then. For this reason you can see some bossbar plugins saying "supports 1.9 and higher", as they don't want to mess with entities.
TAB will attempt to display 1.9 bossbar whenever possible, entity otherwise. 1.9+ clients will always see 1.9 bossbar (even on a 1.8 server thanks to viaversion api). <1.9 clients will see an invisible entity. On bungeecord, however, <1.9 clients won't see anything as bungeecord did not implement entity packets required to make it work.
You can animate color of a bossbar using animations.
First, create an animation in animations.yml, such as
BossColor:
change-interval: 1000
texts:
- "BLUE"
- "YELLOW"
Then, use the animation in bossbar configuration
bars:
ServerInfo:
style: "PROGRESS"
color: "%animation:BossColor%"
progress: "100"
text: "&fWebsite: &bwww.domain.com"
This bossbar will change color every second between blue and yellow colors.
You can do the same with progress, style and text as well.
If you want the plugin to switch between bossbars based on a condition, first consider using condition for text itself (or some other property). If this is not an option (you want text, color, style and progress to be different, which would result in 4 conditions), create 2 bars and give them the same condition, except negate it. If your original condition uses =, make second condition use !=. For number comparisons, negate < using >= and so on.
Example:
bars:
full:
style: "PROGRESS"
color: "YELLOW"
progress: "100"
text: "&aYour health is full"
display-condition: "%health%=20"
notfull:
style: "PROGRESS"
color: "RED"
progress: "0"
text: "&cYou took damage"
display-condition: "%health%!=20"