API Usage

Index

• Creating lines and scoreboards
• Scoreboard Groups
• UltimateScoreboards Events

---

The API is accessible from the UltimateScoreboardsAPI class, which is the core class. From it you can create lines, scoreboards, manage scoreboard viewers, create scoreboard groups, ect.

Creating lines and scoreboards

The UltimateScoreboardsAPI class contains methods for creating every kind of lines and scoreboards.

Example:

UltimateScoreboardsAPI api = UltimateScoreboardsAPI.getAPI();

// Let's create a long scoreboard with 3 lines

Line title = api.craftStepLine(Arrays.asList("&eTitle", "&5Title", "&cTitle"));
Line firstLine = api.craftTextLine("&6Player: &f%player_name%"); // Making use of PAPI Player expansion
Line secondLine = api.craftTextLine(""); // An empty line
Line thirdLine = api.craftTextLine("&aJust a very long green random line at the bottom");

// We need to enable firstLine's placeholder parsing
// This is done encapsulating the line with a PlaceholderLine line
firstLine = api.addPlaceholdersReplacing(firstLine);

// Let's say we want to update our title every 5 scoreboards updates
// This is done encapsulating the line with an UpdateFrequencyLine line
title = api.addUpdateFrequency(title, 5);

// Eventually, create the scoreboard
// The scoreboard will update every 2 ticks, so the title will update every 10 ticks (0.5 seconds)
// Ensure uniqueness is set to true
Scoreboard scoreboard = api.craftLongScoreboard(title, Arrays.asList(firstLine, secondLine, thirdLine), 2, true);

// Remember to dispose the scoreboard when it's no longer in use.
scoreboard.dispose();

Scoreboard Groups

UltimateScoreboards has built-in code for handling per-player scoreboards. This feature is available in the API using the craftScoreboardGroup method.

public ScoreboardGroup craftScoreboardGroup(boolean perPlayerScoreboard, Supplier<Scoreboard> scoreboardCrafter);

The method requires a Supplier<Scoreboard>, which creates the scoreboard to be displayed. IMPORTANT: It musn't return the instance of a pre-created scoreboard or per-player scoreboard won't work. It must call a UltimateScoreboardsAPI#createScoreboard method.

Example:

ScoreboardGroup group = api.craftScoreboardGroup(true, () -> {

    // Same scoreboard as the example above
    Line title = api.craftStepLine(Arrays.asList("&eTitle", "&5Title", "&cTitle"));
    Line firstLine = api.craftTextLine("&6Player: &f%player_name%");
    Line secondLine = api.craftTextLine("");
    Line thirdLine = api.craftTextLine("&aJust a very long green random line at the bottom");
    firstLine = api.addPlaceholdersReplacing(firstLine);
    title = api.addUpdateFrequency(title, 5);

    // The Supplier must return a NEW scoreboard
    Scoreboard scoreboard = api.craftLongScoreboard(title, Arrays.asList(firstLine, secondLine, thirdLine), 2, true);
    return scoreboard;
});

// If per-player-scoreboard is set to true, ScoreboardGroup#craftScoreboard returns a new scoreboard
// every time, otherwise the same scoreboard. The scoreboards are crafted using the Supplier above.
Scoreboard scoreboard = group.craftScoreboard();
scoreboard.addViewer(aplayer);

N.B. Scoreboards crafted by ScoreboardGroups doesn't dispose themselves automatically, even if they are per-player-scoreboards.

UltimateScoreboards Events

UltimateScoreboards comes with a lot of events for every situation. Note that it's not guaranteed that events won't be called asynchronously.

For existing events check out the events package of the API.