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.

In fact, 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);
AdvancementTab tab = api.createAdvancementTab("tabnamespace")`.
RootAdvancement root = new RootAdvancement(tab, "root", new AdvancementDisplay(/*display settings*/), "backgroundTexture");
tab.registerAdvancements(root); // Create a tab with only an advancement

Every AdvancementTab is not shown to any player by default. There are two ways an AdvancementTab can be shown to a player:

• Calling AdvancementTab#showTab(Player player); or
• Updating an advancement (owned by the tab) for a player or a team a player is part of (for more information about teams, see Teams page).

It is always prefereable to show every tab to every player as soon as possible, that is when the API has finished loading its 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).

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

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