Display a Per-Player Sidebar to Individual Players

Create and display a PlayerSidebar bound to a single player, update its lines dynamically, and manage its full lifecycle using VelaBoard.

PlayerSidebar is bound to one player at a time and is the simplest way to show player-specific HUD data — things like score, level, or location that differ between players.

Complete setup flow

1. Get the scoreboard handler

   Obtain the ScoreboardHandler from the API entry point.

   ScoreboardHandler handler = ScoreboardAPI.getHandler();
   
2. Create a scoreboard

   Create a Scoreboard instance through the handler.

   Scoreboard board = handler.createScoreboard();
   
3. Register the player

   Add the player to the scoreboard before creating any sidebars for them.

   board.addPlayer(player);
   
4. Create the sidebar with a title

   Create a PlayerSidebar with a display title.

   PlayerSidebar sidebar = board.createPlayerSidebar("§6§lMy Plugin");
   
5. Set lines

   Populate the sidebar lines. Line 0 is the top line.

   sidebar.setLine(0, "§7Player: §f" + player.getName());
   sidebar.setLine(1, "§7Score: §f0");
   sidebar.setLine(2, "§7Level: §f1");
   
6. Assign the player

   Bind the sidebar to the player using setPlayer.

   sidebar.setPlayer(player);
   
7. Show the sidebar

   Call show() to display the sidebar to the player.

   sidebar.show();
   

Full example

@EventHandler
public void onJoin(PlayerJoinEvent event) {
    Player player = event.getPlayer();
    ScoreboardHandler handler = ScoreboardAPI.getHandler();
    Scoreboard board = handler.createScoreboard();
    board.addPlayer(player);

    PlayerSidebar sidebar = board.createPlayerSidebar("§6§lMy Plugin");
    sidebar.setLine(0, "§7Player: §f" + player.getName());
    sidebar.setLine(1, "§7Score: §f0");
    sidebar.setLine(2, "§7Level: §f1");
    sidebar.setPlayer(player);
    sidebar.show();
}

Updating lines dynamically

Call setLine with a new value to update a line’s content. If you need the change to be visible immediately, call show() again after updating.

// Inside a repeating task or event handler
sidebar.setLine(1, "§7Score: §f" + getScore(player));
sidebar.setLine(2, "§7Level: §f" + getLevel(player));
sidebar.show();

You only need to call show() after setLine if the sidebar is already visible and you want the update to take effect immediately. A single show() at setup time is sufficient if lines won’t change.

Hiding and removing

Use hide() to temporarily hide the sidebar without destroying it. You can call show() again later to bring it back.

sidebar.hide();

// Bring it back later
sidebar.show();

When you no longer need the sidebar, call remove() to destroy it and free its resources.

sidebar.remove();

Checking state

VelaBoard provides several methods to inspect the current state of a PlayerSidebar:

Method	Description
isBeingViewed()	Returns true if the sidebar is currently visible to the player.
isRemoved()	Returns true if the sidebar has been destroyed with remove().
hasPlayer(Player)	Returns true if the given player is assigned to this sidebar.
getPlayer()	Returns the Player currently assigned to this sidebar.

if (sidebar.isBeingViewed()) {
    // sidebar is actively visible
}

if (!sidebar.isRemoved()) {
    sidebar.setLine(0, "§7Updated value");
    sidebar.show();
}

Player assigned = sidebar.getPlayer();

A player can only have one sidebar visible at a time. Calling show() on a new sidebar automatically replaces the one they are currently viewing.