FAQ

Frequently Asked Questions

• I'm having some troubles, where can I ask for help?
• What's the best way to use UltimateAdvancementAPI?
• A new Minecraft version just come out, when will UltimateAdvancementAPI be ready for the new version?
• Why does I get a APINotInstantiatedException?
• Why can't I see my advancements?
• Can I customize or translate the announce message of an advancement?
• Can I use custom textures for advancement icons?
• How much can I customize toast messages? Can I remove the "Advancement Made!" message?
• Is Adventure compatible with UltimateAdvancementAPI?
• Can I open the advancement GUI to the players?
• Can I remove the vanilla advancements?
• How can I hide a root advancement?
• How can I customize advancement tab titles or icons?
• Can I choose the order in which advancement tabs are displayed?
• Why does I get a UserNotLoadedException?
• Why does I get a PacketTooLargeException?

---

I'm having some troubles, where can I ask for help?

If you're having troubles using the API feel free to open a post in the help-developing forum channel on Discord. You can also open an issue here on GitHub.

What's the best way to use UltimateAdvancementAPI?

Note

This answer reflects the creators personal opinion about using the API. This is NOT the only possible way to use it!

The best way to start a new project should be using the official generator to create your advancement through a graphical GUI. This often helps choosing the graphical aspects (like the positioning) of the advancements and speeds up the process of creating the classes for the different advancements.
If you don't want to use the generator, we recommend creating a different class per advancement. This usually helps keeping code more readable and clear.

Always listen to both PlayerLoadingCompletedEvent and PlayerLoadingFailedEvent. Loading a player from the database can always fail (even though it's rare) and this situation should be handled correctly.
Also, NEVER use PlayerJoinEvent to show an advancement tab to a player, always use the PlayerLoadingCompletedEvent.

Events should be registered using the Advancement#registerEvent method. This registers the event(s) using the EventManagerAPI library, which facilitates the handle of events and allows listeners to be automatically unregistered when the advancement tab is disposed. You can read more about it on this wiki page.

A new Minecraft version just come out, when will UltimateAdvancementAPI be ready for the new version?

We try to publish the update as soon as possible, however it could happen that a release gets delayed a bit. We are currently attending university and we're working on the API in our free time.

Also, UltimateAdvancementAPI can't be updated until:

• Spigot and Paper release.
• All of our dependencies are updated too (mainly CommandAPI, they are usually quick with the updates though).

We may additionally wait a bit to update to see if Mojang releases an hotfix version, since it is happening so much lately.

Why does I get a APINotInstantiatedException?

This happens when you're trying to access the API before it gets enabled.

Please check the following 3 things:

• You have depend: [UltimateAdvancementAPI] or softdepend: [UltimateAdvancementAPI] in your plugin.yml.
• If you have JitPack declared in your repositories, make sure to declare the https://nexus.frengor.com/repository/public/ repository before it!
• Make sure you've followed every step present in the Installation and Start-Guide if you're using the plugin version of the API; Shadeable-Version if you're shading.

Why can't I see my advancements?

This problem had happened mainly in two cases:

• The advancement tabs are showed on PlayerJoinEvent instead of PlayerLoadingCompletedEvent. Always use the latter to show tabs, since the player might not be loaded yet.
• You're using a fork of Spigot or Paper (like Purpur). The only supported server softwares are Spigot and Paper. Other server softwares have not been tested, so the API may work, but it's not guaranteed.

Can I customize or translate the announce message of an advancement?

Yes, overriding the method getAnnounceMessage in your advancement class:

@Override
public BaseComponent[] getAnnounceMessage(@NotNull Player player) {
    Preconditions.checkNotNull(player, "Player is null.");
    ChatColor color = display.getFrame().getColor();
    return new ComponentBuilder(player.getName() + " ha completato l'obiettivo ")
            .color(ChatColor.WHITE)
            .append(new ComponentBuilder("[")
                            .color(color)
                            .event(new HoverEvent(Action.SHOW_TEXT, display.getChatDescription()))
                            .create()
                    , FormatRetention.NONE)
            .append(display.getChatTitle(), FormatRetention.EVENTS)
            .append(new ComponentBuilder("]")
                            .color(color)
                            .create()
                    , FormatRetention.EVENTS)
            .create();
}

Can I use custom textures for advancement icons?

Yes, by providing an ItemStack with custom model data to the AdvancementDisplay builder or constructor.

Custom model data is a resource pack feature that allows the creation of custom models for items, for more information see this guide.

How much can I customize toast messages? Can I remove the "Advancement Made!" message?

Toast are, sadly, not very customizable. This is a client-side limitation, so we can do nothing about that! The only customizable things are the title, the icon and the frame. The "Advancement Made!", "Goal Reached!" and "Challenge Complete!" messages are NOT removable/editable since they are hardcoded into the client. They are only customizable using a resource pack, which is out of the scope of UltimateAdvancementAPI.

Is Adventure compatible with UltimateAdvancementAPI?

UltimateAdvancementAPI uses the Chat Component API (where implemented) to let developers be able to make messages colorable, clickable and hoverable. Methods which supports the Chat Component API either takes or returns a BaseComponent[].
Since Adventure messages are serializable into a BaseComponent[] using the BungeeComponentSerializer#serialize method, they are supported everywhere the Chat Component API is supported.

Can I open the advancement GUI to the players?

No, this is not possible.

Can I remove the vanilla advancements?

Yes, you can do it by setting disable-vanilla-advancements: false in the config.yml or using UltimateAdvancementAPI#disableVanillaAdvancements in your plugin.

How can I hide a root advancement?

Root advancements cannot be hidden. The reason is that if they get hidden, then the entire tab is hidden in the advancement GUI and you won't be able to see it at all.

How can I customize advancement tab titles or icons?

Note

Changing the title and icon of advancement tabs (independently from the root advancement) is supported in the 3.0.0 version (currently in beta). See the main-3.0.0 branch for more information.

The title and icon of advancement tabs are the same as the ones of the tab's root advancement, so in order to change them you need to modify the root's display.

Can I choose the order in which advancement tabs are displayed?

Currently there is no way to control the order of the tabs.

Why does I get a UserNotLoadedException?

This happens when the API tries to do operations on a player that has not been loaded yet.
It usually happens after doing /reload. We advise against using that command and to stop and restart the server each time instead. (Read more at https://madelinemiller.dev/blog/problem-with-reload/)

Why does I get a PacketTooLargeException?

This happens when a very large packet is sent. The size of a packet depends on many factors, for example the number of advancements to be sent, their titles, descriptions, progressions, etc. Currently, the API tries to reduce the packet size by sending a different packet per tab.
Check that you haven't used a very big maxProgression and, if possible, decrease it or create more tabs with fewer advancements.