Scoreboard API
The scoreboard API is built around one interface: ScoreboardManager. It lets you show, hide and inspect the boards that are loaded from plugins/FeatherBoard/scoreboards/.
FeatherBoardPlugin featherBoard =
(FeatherBoardPlugin) getServer().getPluginManager().getPlugin("FeatherBoard");
ScoreboardManager manager = featherBoard.getScoreboardManager();ScoreboardManager
| Method | Description |
|---|---|
Scoreboard getScoreboardByName(String name) | Find a loaded board by its file name. Returns null if it does not exist. |
Scoreboard getCurrentScoreboardByPlayer(Player player) | The board currently shown to the player, or null. |
List<Scoreboard> getScoreboardsByPlayer(Player player) | Every board assigned to the player, ordered by priority. |
void addScoreboard(Scoreboard board) | Register a custom board implementation. |
boolean isToggled(Player player) | Whether the player has the scoreboard enabled. |
void showScoreboard(Player player, String name) | Show a board and store it as the player's override. |
void showScoreboard(Player player, String name, Boolean persist) | Same, with the persist argument for compatibility. |
void hideScoreboard(Player player, String name) | Hide a board and remove its override. |
void hideScoreboard(Player player, String name, Boolean persist) | Same, with the persist argument. |
void resetDefaultScoreboard(Player player) | Clear overrides and return to automatic assignment. |
void initScoreboard(Player player) | Rebuild and show the assigned board for a player. |
void toggle(Player player) | Toggle the scoreboard on or off. |
void toggle(Player player, boolean silent) | Toggle without sending a message. |
void toggleOn(Player player) | Force the scoreboard on. |
void toggleOff(Player player) | Force the scoreboard off. |
Persist flag
The Boolean persist overloads are part of the public interface. The current implementation always stores the override when showScoreboard is called and removes it when hideScoreboard is called.
Show, hide and reset
public void enterArena(Player player) {
manager.showScoreboard(player, "arena");
}
public void leaveArena(Player player) {
manager.hideScoreboard(player, "arena");
manager.resetDefaultScoreboard(player);
}
public boolean isBoardOn(Player player) {
return manager.isToggled(player);
}showScoreboard adds the board to the player's override list. The override survives relogs until it is removed or another board is shown. resetDefaultScoreboard clears the list and lets normal assignment take over.
Inspect a board
Scoreboard board = manager.getScoreboardByName("myboard");
if (board != null) {
getLogger().info("Board: " + board.getName());
getLogger().info("Lines: " + board.getLines().size());
for (ScoreboardLine line : board.getLines()) {
getLogger().info("Line " + line.getName() + " interval=" + line.getRefreshInterval());
}
}Scoreboard exposes its title, lines and images:
| Method | Description |
|---|---|
getName() | Board name (the file name). |
getTitle() | The title line as a ScoreboardTitle. Prefer getLines().get(0) when you need the plain ScoreboardLine interface. |
getLines() | All lines, including the title. |
getImages() / getImage(String) | Images defined by the board. |
addImage(ScoreboardImage image) | Add an image at runtime. |
send(Player player) | Send this board to a player. |
pause(int ticks) | Pause the board's animation. |
Add a frame at runtime
Scoreboard board = manager.getScoreboardByName("myboard");
if (board != null && !board.getLines().isEmpty()) {
// The first line is the title.
board.getLines().get(0).addFrame("&e&lHello, " + player.getName());
}This changes the in-memory board only. A reload or restart restores the YAML file. Use it for temporary messages, not for permanent configuration.
ScoreboardLine
| Method | Description |
|---|---|
getName() | The line name from the YAML file. |
getFrames() | The frames in the line. |
addFrame(String frame) | Append a frame. |
addFrames(String[] frames) | Append several frames. |
getRefreshInterval() | Interval in ticks. |
setPaused(boolean paused) / isPaused() | Pause or resume the line. |
getFrame(Player player) | The current frame for a player. |
ScoreboardFrame
| Method | Description |
|---|---|
getText() | The frame as a BungeeCord BaseComponent[]. |
getWrappedText() | The frame as a ProtocolLib WrappedChatComponent. |
Frames are already parsed by FeatherBoard: colours, effects and placeholders are resolved.
Events
FeatherBoard fires two cancellable events:
| Event | Fired when |
|---|---|
ScoreboardShowEvent | A board is about to be shown to a player. |
ScoreboardHideEvent | A board is about to be hidden or reset. |
import org.bukkit.event.EventHandler;
import org.bukkit.event.Listener;
import org.featherboard.api.events.ScoreboardShowEvent;
public final class BoardGuard implements Listener {
@EventHandler(ignoreCancelled = true)
public void onShow(ScoreboardShowEvent event) {
if (!event.getScoreboard().getName().equals("vip-board")) {
return;
}
if (!event.getPlayer().hasPermission("myplugin.vip-board")) {
event.setCancelled(true);
}
}
}getServer().getPluginManager().registerEvents(new BoardGuard(), this);Async events
The event may be fired asynchronously. Check event.isAsynchronous() and schedule Bukkit API calls back to the main thread:
if (event.isAsynchronous()) {
getServer().getScheduler().runTask(this, () -> {
// safe to touch Bukkit here
});
}Thread safety
getScoreboardByName,getCurrentScoreboardByPlayerandgetScoreboardsByPlayerare read-only lookups. Use them from the main thread.showScoreboard,hideScoreboard,resetDefaultScoreboard,toggleandinitScoreboardschedule their work on the main thread internally.- Do not call Bukkit APIs from an async event without scheduling a task.
API version
if (featherBoard.getAPIVersion() < 1) {
getLogger().severe("This FeatherBoard version is too old for the API calls used here.");
return;
}The API version is deliberately small and increments only for breaking interface changes. The artifact version (7.0.2) changes with every plugin release.
