AdvancementTab

AdvancementTab objects represent a tab in the minecraft advancement GUI. They are used to register advancements in order to be sent to the players.
An instance can be obtained using

UltimateAdvancementAPI api = UltimateAdvancementAPI.getInstance(plugin);
AdvancementTab tab = api.createAdvancementTab("tabnamespace")`.

Every tab must have a different namespace (it can be thought as an identifier, so it must be unique).

As can be noticed, no advancement is required to create an AdvancementTab. This is because Advancements require an AdvancementTab in their constructor, so they cannot be already present in the tab.
Thus, a newly created tab cannot be shown to any player, since it doesn't contain any advancement yet.
The AdvancementTab in this state is not initialised and almost every method cannot be called without resulting in an IllegalStateException.
It is initialised by calling the AdvancementTab#registerAdvancements(RootAdvancement root, BaseAdvancement... advancements) method, providing the advancements of the tab. After this call, no advancement can be registered or unregistered from the tab and its methods can be used.

Example Usage

UltimateAdvancementAPI api = UltimateAdvancementAPI.getInstance(plugin);

// Create a tab with namespace "mynamespace"
AdvancementTab tab = api.createAdvancementTab("mynamespace")`.

// Create two advancement to be registered in the tab
RootAdvancement root = new RootAdvancement(tab, "root", new AdvancementDisplay(/*display settings*/), "backgroundTexture");
BaseAdvancement adv = new BaseAdvancement(tab, "an-adv", new AdvancementDisplay(/*display settings*/), root);

// Initialise the tab with two advancements
tab.registerAdvancements(root, adv);

// Now methods can be called
Player aPlayer = Bukkit.getPlayer("fren_gor");
tab.updateEveryAdvancement(aPlayer); // Send the tab and its advancements to the player aPlayer

// This throws an IllegalStateException since the tab has already been initialised
tab.registerAdvancements(root, adv);

Every AdvancementTab is hidden to any player by default (meaning that players doesn't see any advancement by default). An AdvancementTab can be shown to a player by calling AdvancementTab#showTab(Player player).
It is always prefereable to show every tab to every player as soon as possible, that is when the API has finished loading their information from the database. The API provides two events to handle that: PlayerLoadingCompletedEvent and PlayerLoadingFailedEvent:

• The first runs when a player has been successfully loaded and they is ready to receive advancements (some other libraries suggest to wait for some ticks before sending the advancements, this event already considers this minecraft problem and you shouldn't wait those ticks).
• The second is executed in case the loading was unsuccessful, and it is useful to handle this occasion (no advancement can be sent to they).

Getting a registered AdvancementTab

The API always keeps a reference to registered AdvancementTabs, so any tab can be retrieved using the UltimateAdvancementAPI#getAdvancementTab(String namespace) method.

Unregistering an AdvancementTab

An AdvancementTab can be unregistered and disposed using the UltimateAdvancementAPI#unregisterAdvancementTab(String namespace) method.
After being unregistered, the tab and its advancements will be removed from the players, but they will not be removed from the database. Furthermore, events registered inside the AdvancementTab's EventManager will be unregistered too, avoiding calls to disposed tabs. More on this in the next section.

EventManager