Scoreboard Sidebar API 3.0

Tested Minecraft Versions:

• 1.9

Source Code:

https://github.com/ColoredCarrot/scoreboard-sidebar-api

Hey guys!
This is the second version of my Sidebar API.

With this API, you can create individual sidebars for each player very easily.

NOTE:
The PlaceholderAPI is a soft dependency of this API, which means it is recommended, but not needed. You can download it here: https://www.spigotmc.org/resources/placeholderapi.6245/

NEWS:
- Added anti-flicker
- Added "steps" function
- Added auto-updater
- Added support for PlaceholderAPI

Installation Instructions:
1. Download this resource
2. Place the downloaded jar file in your server's directory /plugins/
3. (Optional) Download the PlaceholderAPI here
4. (Optional) Place the downloaded jar file in your server's directory /plugins/
5. Restart the server and you're done! (If you've followed steps 3 and 4, you should see the message "[SidebarAPI] Hooked PlaceholderAPI vx.x.x")

Spoiler: API Usage

To create a new Sidebar, you first have to create the lines of texts to go in it.
To do that, use

Code (Java):

SidebarString line1 = new SidebarString(ChatColor.RED + "Line 1!");

To create animated text, use

Code (Java):

SidebarString line2 = new SidebarString(ChatColor.RED + "Line 2 Variation 1", ChatColor.BLUE + "Line 2 Variation 2", ChatColor.GREEN + "Line 2 Variation 3");

Since version 2.3, you can also generate a scrolling animation:

Spoiler: Animation Generation

To generate a scrolling animation, use

Code (Java):

SidebarString mySidebarString = SidebarString.generateScrollingAnimation("You are awasome", 6);

The "You are awasome" String represents the text that is going to be animated.
The 6 represents the displayWidth of the String (see the example).
The code above will generate a SidebarString with the following variations:

Code (Text):

"You ar",
"ou are",
"u are ",
" are a",
"are aw",
"re awa",
"e awas",
" awaso",
"awasom",
"wasome"

Note that all the Strings are 6 characters long; that length is defined by 'displayWidth'.

To now create the actual Sidebar, use

Code (Java):

Sidebar mySidebar = new Sidebar("My Title", plugin, 60, line1, line2);

Note that plugin is an instance of your class that extends JavaPlugin and 60 represents how many ticks to wait between each animation change. Btw, the animation works by cycling through the different variations in the SidebarString Objects

Keep in mind that you can also always add and remove entries from the sidebar using

Code (Java):

SidebarString line3 = new SidebarString("Hello", "World");

// Add the entry
mySidebar.addEntry(line3);

// Remove the entry
mySidebar.removeEntry(line3);

To show/ hide the sidebar to/from a player, use

Code (Java):

mySidebar.showTo(player);
mySidebar.hideFrom(player);

Let's now get into the PlaceholderAPI support:

Spoiler: PlaceholderAPI

NOTE:
All of the following methods will throw a SidebarOptionalException if PlaceholderAPI isn't hooked.

To set the placeholders for a specific Player in a SidebarString Object, use

Code (Java):

mySidebarString.setPlaceholders(player);

You can also directly add variations with placeholders:

Code (Java):

mySidebarString.addVariation(player, "What is uuup!");

Also, you can construct a SidebarString with placeholders:

Code (Java):

SidebarString mySIdebarString = new SidebarString(player, "Variation 1", "Variation 2", "etc.");

The Sidebar class also supports setting the placeholders of all SidebarStrings (and all their variations):

Code (Java):

mySidebar.setAllPlaceholders(player);

You can get the hooked PlaceholderAPIPlugin instance using:

Code (Java):

// Returns null if no PlaceholderAPI is hooked
PlaceholderAPIPlugin instance = SidebarAPI.getPlaceholderAPI();

Note that there are many more methods like getters and setters, and also ones which add and remove entries. The javadocs are included in the download.

Since version 2.8, there is a step function which I will briefly introduce right here:

Spoiler: How steps work

Since version 2.8, the SidebarString class now has a property named "step". It defines how many times the method SidebarString#getNext() needs to be run before the actual new variation will be returned. By default, step will be set to 1 so always when SidebarString#getNext() is called, the next variation is returned.

This system allows for different "animation rates" of individual SidebarStrings. What I mean by that is e.g. one SidebarString returns the next variation every second while the other SidebarString returns the next variation every other second.

Now that you're done reading that, here are the methods and constructors dealing with steps:

Code (Java):

// Construct a new SidebarString with step set to 2
SidebarString line1 = new SidebarString(2, "variation 1", "variation 2", "etc.");

// Construct a new SidebarString with step set to 2 and the placeholder player set to player1
SidebarString line2 = new SidebarString(player1, 2, "var 1", "var 2");

// Get the step of line1
int step = line1.getStep();

// Set the step of line2 to 4
// This method is also chainable (returns it's SidebarString Object)
line2.setStep(4);

Also one last thing to mention; the step data IS handled by configuration stuff.

Spoiler: Sidebar Placeholders

Since version 2.5, this SidebarAPI has defined 3 placeholders.

Spoiler: %sidebar_title%

This placeholder will return the title of the Sidebar shown to the specified player, and "" if no Sidebar was found.

Spoiler: %sidebar_linenextvar_n%

Replace 'n' with any integer above or equal to 0.
This placeholder will return the next variation of the SidebarString line n of the Sidebar shown to the specified player, and "" if any errors occur (for example invalid syntax).

Spoiler: %sidebar_line_n_var_n%

Replace n with any integer above or equal to 0.
This placeholder will return the variation 2nd n of the SidebarString line 1st n of the Sidebar shown to the specified player, and "" if any errors occur (for example invalid syntax).

Since version 2.6, Sidebar#update() now also calls Sidebar#setAllPlaceholders(player) if Sidebar#getPlaceholderPlayerForUpdate() is not null.
You can set the placeholder player using

Code (Java):

mySidebar.setPlaceholderPlayerForUpdate(player);

and remove it (to stop Sidebar#setAllPlaceholders(Player) from being called) using

Code (Java):

mySidebar.setPlaceholderPlayerForUpdate(null);

If you find a bug, please report it in the discussion tab or on GitHub.

Source Code:
https://github.com/ColoredCarrot/scoreboard-sidebar-api

Javadocs:
http://coloredcarrot.com/code/api/sidebar/javadocs/index.html

Original version:
https://www.spigotmc.org/threads/api-scoreboard-sidebar-api.136026/

LOL, I just realized that I released the first version on April 1. Trust me though, it's no april fools.