Package com.fren_gor.ultimateAdvancementAPI.advancement

Class Advancement

java.lang.Object
com.fren_gor.ultimateAdvancementAPI.advancement.Advancement
Direct Known Subclasses:
BaseAdvancement, RootAdvancement
public abstract class Advancement extends Object
The Advancement class is the parent class of every advancement. It provides the basic methods and fields to work with advancements.

It is extended only by RootAdvancement and BaseAdvancement. It cannot be extended by any other class, which should extends

  • Field Details

    • key

      @NotNull protected final @NotNull AdvancementKey key
      The namespaced key of the advancement, which identifies it univocally.

      Note that the namespace of the key is the tab's one.

    • advancementTab

      @NotNull protected final @NotNull AdvancementTab advancementTab
      The advancement tab of the advancement.

    • display

      @NotNull protected final @NotNull AdvancementDisplay display
      The advancement display of the advancement.

    • maxProgression

      protected final @Range(from=1, to=Integer.MAX_VALUE) int maxProgression
      The maximum progression of the advancement.

  • Method Details

    • getKey

      @NotNull public final @NotNull AdvancementKey getKey()
      Gets the advancement namespaced key.
      Returns:
      The advancement namespaced key.

    • getAdvancementTab

      @NotNull public final @NotNull AdvancementTab getAdvancementTab()
      Gets the advancement tab of the advancement.
      Returns:
      The advancement tab of the advancement.

    • getMaxProgression

      public final @Range(from=1, to=Integer.MAX_VALUE) int getMaxProgression()
      Gets the maximum progression of the advancement.
      Returns:
      The maximum progression of the advancement.

    • getProgression

      public @Range(from=0, to=Integer.MAX_VALUE) int getProgression(@NotNull @NotNull Player player)
      Gets the current progression of the provided player's team.
      Parameters:
      player - The player.
      Returns:
      The current progression of the provided player's team.

    • getProgression

      public @Range(from=0, to=Integer.MAX_VALUE) int getProgression(@NotNull @NotNull UUID uuid)
      Gets the current progression of the provided player's team.
      Parameters:
      uuid - The UUID of the player.
      Returns:
      The current progression of the provided player's team.

    • getProgression

      public @Range(from=0, to=Integer.MAX_VALUE) int getProgression(@NotNull @NotNull TeamProgression progression)
      Gets the current progression of the provided team.
      Parameters:
      progression - The TeamProgression of the team.
      Returns:
      The current progression of the team.

    • isGranted

      public boolean isGranted(@NotNull @NotNull Player player)
      Returns whether the advancement has been completed by the provided player's team.
      Parameters:
      player - The player.
      Returns:
      Whether the advancement has been completed by the provided player's team.

    • isGranted

      public boolean isGranted(@NotNull @NotNull UUID uuid)
      Returns whether the advancement has been completed by the provided player's team.
      Parameters:
      uuid - The UUID of the player.
      Returns:
      Whether the advancement has been completed by the provided player's team.

    • isGranted

      public boolean isGranted(@NotNull @NotNull TeamProgression progression)
      Returns whether the advancement has been completed by the provided team.
      Parameters:
      progression - The TeamProgression of the team.
      Returns:
      Whether the advancement has been completed by the provided team.

    • getAnnounceMessage

      @Nullable public @Nullable BaseComponent[] getAnnounceMessage(@NotNull @NotNull Player player)
      Gets the chat message to be sent when an advancement is completed.

      The message is sent to everybody online on the server.

      Parameters:
      player - The player who has completed the advancement.
      Returns:
      The message to be displayed, or null if no message should be displayed.

    • incrementProgression

      public @Range(from=0, to=Integer.MAX_VALUE) int incrementProgression(@NotNull @NotNull Player player)
      Increases the progression of the provided player's team by one.

      If the advancement gets completed, advancement rewards will be given.

      Parameters:
      player - The player who is responsible for the increment.
      Returns:
      The new progression. It is always less or equal to maxProgression.

    • incrementProgression

      public @Range(from=0, to=Integer.MAX_VALUE) int incrementProgression(@NotNull @NotNull Player player, boolean giveReward)
      Increases the progression of the provided player's team by one.
      Parameters:
      player - The player who is responsible for the increment.
      giveReward - Whether to give rewards if the advancement gets completed.
      Returns:
      The new progression. It is always less or equal to maxProgression.

    • incrementProgression

      public @Range(from=0, to=Integer.MAX_VALUE) int incrementProgression(@NotNull @NotNull Player player, @Range(from=1, to=Integer.MAX_VALUE) int increment)
      Increases the progression of the provided player's team.

      If the advancement gets completed, advancement rewards will be given.

      Parameters:
      player - The player who is responsible for the increment.
      increment - The progression increment. Must be greater than 0.
      Returns:
      The new progression. It is always less or equal to maxProgression.

    • incrementProgression

      public @Range(from=0, to=Integer.MAX_VALUE) int incrementProgression(@NotNull @NotNull Player player, @Range(from=1, to=Integer.MAX_VALUE) int increment, boolean giveReward)
      Increases the progression of the provided player's team.
      Parameters:
      player - The player who is responsible for the increment.
      increment - The progression increment. Must be greater than 0.
      giveReward - Whether to give rewards if the advancement gets completed.
      Returns:
      The new progression. It is always less or equal to maxProgression.

    • incrementProgression

      public @Range(from=0, to=Integer.MAX_VALUE) int incrementProgression(@NotNull @NotNull UUID uuid)
      Increases the progression of the provided player's team by one.

      If the advancement gets completed, advancement rewards will be given.

      Parameters:
      uuid - The UUID of the player responsible for the increment. If the player is not online, rewards will be given to a pseudorandom online member of the same team if there are any, or it will be set unredeemed.
      Returns:
      The new progression. It is always less or equal to maxProgression.

    • incrementProgression

      public @Range(from=0, to=Integer.MAX_VALUE) int incrementProgression(@NotNull @NotNull UUID uuid, boolean giveReward)
      Increases the progression of the provided player's team by one.
      Parameters:
      uuid - The UUID of the player responsible for the increment. If the player is not online, rewards will be given to a pseudorandom online member of the same team if there are any, or it will be set unredeemed.
      giveReward - Whether to give rewards if the advancement gets completed.
      Returns:
      The new progression. It is always less or equal to maxProgression.

    • incrementProgression

      public @Range(from=0, to=Integer.MAX_VALUE) int incrementProgression(@NotNull @NotNull UUID uuid, @Range(from=1, to=Integer.MAX_VALUE) int increment)
      Increases the progression of the provided player's team.

      If the advancement gets completed, advancement rewards will be given.

      Parameters:
      uuid - The UUID of the player responsible for the increment. If the player is not online, rewards will be given to a pseudorandom online member of the same team if there are any, or it will be set unredeemed.
      increment - The progression increment. Must be greater than 0.
      Returns:
      The new progression. It is always less or equal to maxProgression.

    • incrementProgression

      public @Range(from=0, to=Integer.MAX_VALUE) int incrementProgression(@NotNull @NotNull UUID uuid, @Range(from=1, to=Integer.MAX_VALUE) int increment, boolean giveReward)
      Increases the progression of the provided player's team.
      Parameters:
      uuid - The UUID of the player responsible for the increment. If the player is not online, rewards will be given to a pseudorandom online member of the same team if there are any, or it will be set unredeemed.
      increment - The progression increment. Must be greater than 0.
      giveReward - Whether to give rewards if the advancement gets completed.
      Returns:
      The new progression. It is always less or equal to maxProgression.

    • incrementProgression

      protected @Range(from=0, to=Integer.MAX_VALUE) int incrementProgression(@NotNull @NotNull TeamProgression pro, @Nullable @Nullable Player player, @Range(from=1, to=Integer.MAX_VALUE) int increment, boolean giveRewards)
      Increases the progression of the provided team.

      The provided player must be an online member of the team. If no members are online or no particular player is to be preferred, it can be put to null. In this case, rewards will be given to a pseudorandom online member if there are any or the advancement will be set unredeemed.

      Parameters:
      pro - The TeamProgression of the team.
      player - The team member responsible for the increment. May be null.
      increment - The progression increment. Must be greater than 0.
      giveRewards - Whether to give rewards if the advancement gets completed.
      Returns:
      The new progression. It is always less or equal to maxProgression.

    • setProgression

      public void setProgression(@NotNull @NotNull Player player, @Range(from=0, to=Integer.MAX_VALUE) int progression)
      Sets a progression for the provided player's team.

      If the advancement gets completed, advancement rewards will be given.

      Parameters:
      player - The player who is responsible for the update.
      progression - The new non-negative progression to set.

    • setProgression

      public void setProgression(@NotNull @NotNull Player player, @Range(from=0, to=Integer.MAX_VALUE) int progression, boolean giveReward)
      Sets a progression for the provided player's team.
      Parameters:
      player - The player who is responsible for the update.
      progression - The new non-negative progression to set.
      giveReward - Whether to give rewards if the advancement gets completed.

    • setProgression

      public void setProgression(@NotNull @NotNull UUID uuid, @Range(from=0, to=Integer.MAX_VALUE) int progression)
      Sets a progression for the provided player's team.

      If the advancement gets completed, advancement rewards will be given.

      Parameters:
      uuid - The UUID of the player responsible for the update. If the player is not online, rewards will be given to a pseudorandom online member of the same team if there are any, or it will be set unredeemed.
      progression - The new non-negative progression to set.

    • setProgression

      public void setProgression(@NotNull @NotNull UUID uuid, @Range(from=0, to=Integer.MAX_VALUE) int progression, boolean giveReward)
      Sets a progression for the provided player's team.
      Parameters:
      uuid - The UUID of the player responsible for the update. If the player is not online, rewards will be given to a pseudorandom online member of the same team if there are any, or it will be set unredeemed.
      progression - The new non-negative progression to set.
      giveReward - Whether to give rewards if the advancement gets completed.

    • setProgression

      protected void setProgression(@NotNull @NotNull TeamProgression pro, @Nullable @Nullable Player player, @Range(from=0, to=Integer.MAX_VALUE) int progression, boolean giveRewards)
      Sets a new progression for the provided team.

      The provided player must be an online member of the team. If no members are online or no particular player is to be preferred, it can be put to null. In this case, rewards will be given to a pseudorandom online member if there are any or the advancement will be set unredeemed.

      Parameters:
      pro - The TeamProgression that belongs to the team.
      player - The team member responsible for the update. May be null.
      progression - The new non-negative progression to set.
      giveRewards - Whether to give rewards if the advancement gets completed.

    • handlePlayer

      protected void handlePlayer(@NotNull @NotNull TeamProgression pro, @Nullable @Nullable Player player, int newProgression, int oldProgression, boolean giveRewards, @Nullable @Nullable AfterHandle afterHandle)
      Handles the reward process of the advancement.

      When the new progression is greater or equal than maxProgression and the old progression is less than maxProgression then the advancement is being completed by the provided player. If the provided player is non-null, they will receive the rewards. Otherwise, if there are online members in the team one of them will receive the advancement rewards. If no member of the team are online, the advancement will be set unredeemed for that team.

      Parameters:
      pro - The TeamProgression of the team.
      player - The team member responsible for the update. May be null.
      newProgression - The new non-negative progression that has been set.
      oldProgression - The previous progression of the team.
      giveRewards - Whether to give rewards if the advancement gets completed.
      afterHandle - The action to perform after the reward process, or null to don't do any action. The default action updates the tab's advancement to the team (see AfterHandle.UPDATE_ADVANCEMENTS_TO_TEAM).

    • displayToastToPlayer

      public void displayToastToPlayer(@NotNull @NotNull Player player)
      Display the toast of this advancement to a player.
      Parameters:
      player - The player the toast will be shown to.

    • isVisible

      public boolean isVisible(@NotNull @NotNull Player player)
      Returns whether the advancement is visible to the provided player.

      An advancement is visible to a player if and only if it is visible to all the players in the player's team. By default, every advancement is visible to every player, but this behavior can be changed overriding isVisible(TeamProgression) or implementing a suitable interface for the Advancement Visibility System (see IVisibility for more information).

      Parameters:
      player - The player.
      Returns:
      Whether the advancement is visible to the player.

    • isVisible

      public boolean isVisible(@NotNull @NotNull UUID uuid)
      Returns whether the advancement is visible to the provided player.

      An advancement is visible to a player if and only if it is visible to all the players in the player's team. By default, every advancement is visible to every player, but this behavior can be changed overriding isVisible(TeamProgression) or implementing a suitable interface for the Advancement Visibility System (see IVisibility for more information).

      Parameters:
      uuid - The UUID of the player.
      Returns:
      Whether the advancement is visible to the player.

    • isVisible

      public boolean isVisible(@NotNull @NotNull TeamProgression progression)
      Returns whether the advancement is visible to the provided team.

      An advancement is visible to a team if and only if it is visible to all the players in the team. By default, every advancement is visible to every player, but this behavior can be changed overriding this method or implementing a suitable interface for the Advancement Visibility System.

      Implementation Requirements:
      This method is the core method of the Advancement Visibility System (AVS). The return value is true if no suitable interfaces for the AVS are implemented, or the result of IVisibility.isVisible(Advancement, TeamProgression) otherwise. When overridden, this method (called via super) enables the AVS features for that method.
      Parameters:
      progression - TheTeamProgression of the team.
      Returns:
      Whether the advancement is visible to the provided team.

    • onGrant

      public void onGrant(@NotNull @NotNull Player player, boolean giveRewards)
      Called when the advancement is completed by a player. It handles the chat message, the toast notification, and the advancement rewards (see giveReward(Player) for more information).
      Parameters:
      player - The player who completed the advancement.
      giveRewards - Whether to give rewards.

    • grant

      public void grant(@NotNull @NotNull Player player)
      Grants the advancement to the player's team giving rewards.
      Parameters:
      player - The player.

    • grant

      public void grant(@NotNull @NotNull Player player, boolean giveRewards)
      Grant the advancement to the player's team.
      Parameters:
      player - The player
      giveRewards - Whether to give rewards.

    • revoke

      public void revoke(@NotNull @NotNull Player player)
      Revoke the advancement to the player's team.
      Parameters:
      player - The player.

    • onUpdate

      public void onUpdate(@NotNull @NotNull TeamProgression teamProgression, @NotNull @NotNull Map<AdvancementWrapper,Integer> addedAdvancements)
      Handles the serialisation of the advancement into the update packet.

      Advancement(s) to be sent have to be added to the provided Map, which contains the AdvancementWrappers paired with the progression of the provided team.

      Parameters:
      teamProgression - The TeamProgression of the team of the player(s).
      addedAdvancements - The Map in which the advancements to be sent are added as keys. The values are the current progressions of the team.

    • giveReward

      public void giveReward(@NotNull @NotNull Player player)
      Gives the rewards to the provided player when the advancement is completed.
      Implementation Requirements:
      This method does not do anything by default. Override it to change its behavior.
      Parameters:
      player - The player who has completed the advancement.

    • onRegister

      public void onRegister()
      Called when the advancement is registered by its AdvancementTab through AdvancementTab.registerAdvancements(RootAdvancement, Set).

      No exception should be thrown, to validate the advancement registration see validateRegister().

      Note that not every method of AdvancementTab is available, since this method is called before the tab is set initialised.

      Implementation Requirements:
      This method does not do anything by default. Override it to change its behavior.

    • validateRegister

      public void validateRegister() throws InvalidAdvancementException
      Validate the advancement after it has been registered by the advancement tab. If the validation fails, a InvalidAdvancementException should be thrown.

      For example, BaseAdvancement overrides this method to make sure it and its parent belongs to the same tab.

      Note that every method of AdvancementTab is available, since this method is called after every advancement has been registered and the tab has already been initialised.

      Implementation Requirements:
      This method does not do anything by default. Override it to change its behavior.
      Throws:
      InvalidAdvancementException - If the validation fails.

    • onDispose

      public void onDispose()
      Called when the advancement is disposed.
      Implementation Requirements:
      This method does not do anything by default. Override it to change its behavior.

    • isValid

      public boolean isValid()
      Returns whether the advancement is valid.

      An advancement is valid if and only if it belongs to its advancement tab and that tab is active.

      Returns:
      Whether the advancement is valid.

    • getNMSWrapper

      @NotNull public abstract @NotNull AdvancementWrapper getNMSWrapper()
      Returns the NMS wrapper of this advancement. Should craft the NMS wrapper once and returns it henceforth.
      Returns:
      The NMS wrapper of this advancement.

    • registerEvent

      protected final <E extends Event> void registerEvent(@NotNull @NotNull Class<E> eventClass, @NotNull @NotNull Consumer<E> consumer)
      Registers the provided event into the tab EventManager.
      Type Parameters:
      E - The class of the event to register.
      Parameters:
      eventClass - The class of the event to register.
      consumer - The code to run when the event occurs.
      Throws:
      DisposedException - If the AdvancementTab of this advancement is disposed.
      IllegalArgumentException - If any argument is null.

    • registerEvent

      protected final <E extends Event> void registerEvent(@NotNull @NotNull Class<E> eventClass, @NotNull @NotNull EventPriority priority, @NotNull @NotNull Consumer<E> consumer)
      Registers the provided event into the tab EventManager.
      Type Parameters:
      E - The class of the event to register.
      Parameters:
      eventClass - The class of the event to register.
      priority - The priority of the event. See EventPriority.
      consumer - The code to run when the event occurs.
      Throws:
      DisposedException - If the AdvancementTab of this advancement is disposed.
      IllegalArgumentException - If any argument is null.

    • toString

      public String toString()
      Returns the advancement namespaced key as String.

      Calling this method is equivalent to call getKey().toString().

      Overrides:
      toString in class Object
      Returns:
      The advancement namespaced key as String.
      See Also:

    • equals

      public boolean equals(Object o)
      Overrides:
      equals in class Object

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object

    • getDisplay

      @NotNull public @NotNull AdvancementDisplay getDisplay()
      Gets the AdvancementDisplay of this advancement.
      Returns:
      The AdvancementDisplay of this advancement.