Scoreboard Sidebar API 3.0

Create individual scoreboard sidebars for each player.

  1. Voidev
    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")

    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:
    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:
    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:
    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.

    Since version 2.5, this SidebarAPI has defined 3 placeholders.
    This placeholder will return the title of the Sidebar shown to the specified player, and "" if no Sidebar was found.
    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).
    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. :D Trust me though, it's no april fools.

Recent Reviews

  1. Onlinerz
    Onlinerz
    5/5,
    Version: 3.0
    Gave 5 stars, because it almost works perfectly.
    But the scoreboard don't update after loading once at me!
    So I've to load a Runnable() to create the Scoreboard every second new.

    Would be very thankful for every kind of help!
  2. CreeperCry04
    CreeperCry04
    5/5,
    Version: 3.0
    ...and I thought TigerHix's ScoreboardLib was good! This thing is amazing, and it perfectly fits my needs!
  3. IMinIILLuZionZ
    IMinIILLuZionZ
    5/5,
    Version: 3.0
    Great API to use for creating scoreboards, simple to use and works like a charm, keep up the great work :D
  4. Eth
    Eth
    5/5,
    Version: 3.0
    BEST API EVER! has anything a developer would ever need, animations, variations, everything! and it is incredibly lightweight, and easy to use. Thanks so much for making this plugin!
  5. Comezzomix
    Comezzomix
    4/5,
    Version: 2.9
    Great API, but i think there is no way to give a line a value. Also maven support would be grat.
  6. Steinente
    Steinente
    5/5,
    Version: 2.9
    Hey,

    I discovered a bug.
    If you use this string, nothing is output in the scoreboard: "┬žaGoldSpawner: ┬ž6"
    You can replace "Gold" with any word and it's not working.
  7. RobinMC
    RobinMC
    5/5,
    Version: 2.8
    Great plugin. Has everything any developer will ever need. Ignore those complaining about not being able to refresh the sidebar, they do not know anything about Java at all. Solution: 1) Create a method e.g. getScoreboard(), which returns a scoreboard object. 2) Create a task that runs e.g. every second. For every online player, call getScoreboard().showTo(player);
    1. Voidev
      Author's Response
      Thank you for the review! :)
  8. stevensilvergood
    stevensilvergood
    3/5,
    Version: 2.8
    It's alright. Currently you can't update the scoreboards which means lets say you want the player's health on it but guess what you can't so that kinda sucks but if you don't need anything to update this is a great plugin.
  9. tomsturgeon9
    tomsturgeon9
    5/5,
    Version: 2.8
    Used this API in my first plugin. Thank you, it will be indispensable in my next ones. Big respect.

    Very customisable and gives a professional feel to the server.
  10. CarmineKing
    CarmineKing
    5/5,
    Version: 2.8
    Giving a 5-star because I do not want to affect your rating avg.

    BUT, I didnt know this was for developers, I thought I could plug-&-play this into my server and edit some configs.. done.
    :(
    1. Voidev
      Author's Response
      Thanks for 5 stars, first of all :)

      I guess that by plug-&-play, you mean that you want to set a default scoreboard for every player in a config, also with some variables (like player namer etc.).
      If so, I think that's a great idea for another plugin I'll make using this API.
      I cannot do that in this API directly though, since then it wouldn't really be just an API... :D