#745: Expose more information about advancements

By: MartenM <marten.struijk@gmail.com>

paper-api/src/main/java/org/bukkit/advancement/Advancement.java

@@ -3,6 +3,7 @@ package org.bukkit.advancement;
 import java.util.Collection;
 import org.bukkit.Keyed;
 import org.jetbrains.annotations.NotNull;
+import org.jetbrains.annotations.Nullable;
 
 /**
  * Represents an advancement that may be awarded to a player. This class is not
@@ -17,4 +18,14 @@ public interface Advancement extends Keyed {
      */
     @NotNull
     Collection<String> getCriteria();
+
+    /**
+     * Returns the display information for this advancement.
+     *
+     * This includes it's name, description and other visible tags.
+     *
+     * @return a AdvancementDisplay object, or null if not set.
+     */
+    @Nullable
+    AdvancementDisplay getDisplay();
 }

paper-api/src/main/java/org/bukkit/advancement/AdvancementDisplay.java

@@ -0,0 +1,82 @@
+package org.bukkit.advancement;
+
+import org.bukkit.inventory.ItemStack;
+import org.jetbrains.annotations.NotNull;
+
+/**
+ * Holds information about how the advancement is displayed by the game.
+ */
+public interface AdvancementDisplay {
+
+    /**
+     * Gets the title of the advancement.
+     *
+     * @return The advancement title without colour codes.
+     */
+    @NotNull
+    String getTitle();
+
+    /**
+     * Gets the visible description of the advancement.
+     *
+     * @return The advancement description without colour codes.
+     */
+    @NotNull
+    String getDescription();
+
+    /**
+     * The icon that is used for this advancement.
+     *
+     * @return an ItemStack that represents the advancement.
+     */
+    @NotNull
+    ItemStack getIcon();
+
+    /**
+     * Whether to show a toast to the player when this advancement has been
+     * completed.
+     *
+     * @return true if a toast is shown.
+     */
+    boolean shouldShowToast();
+
+    /**
+     * Whether to announce in the chat when this advancement has been completed.
+     *
+     * @return true if announced in chat.
+     */
+    boolean shouldAnnounceChat();
+
+    /**
+     * Whether to hide this advancement and all its children from the
+     * advancement screen until this advancement have been completed.
+     *
+     * Has no effect on root advancements themselves, but still affects all
+     * their children.
+     *
+     * @return true if hidden.
+     */
+    boolean isHidden();
+
+    /**
+     * The X position of the advancement in the advancement screen.
+     *
+     * @return the X coordinate as float
+     */
+    float getX();
+
+    /**
+     * The Y position of the advancement in the advancement screen.
+     *
+     * @return the Y coordinate as float
+     */
+    float getY();
+
+    /**
+     * The display type of this advancement.
+     *
+     * @return an enum representing the type.
+     */
+    @NotNull
+    AdvancementDisplayType getType();
+}

paper-api/src/main/java/org/bukkit/advancement/AdvancementDisplayType.java

@@ -0,0 +1,41 @@
+package org.bukkit.advancement;
+
+import org.bukkit.ChatColor;
+import org.jetbrains.annotations.NotNull;
+
+/**
+ * Advancements are displayed in different ways depending on their display type.
+ *
+ * This enum contains information about these types and how they are
+ * represented.
+ */
+public enum AdvancementDisplayType {
+
+    /**
+     * Task or normal icons have a square icon frame.
+     */
+    TASK(ChatColor.GREEN),
+    /**
+     * Challenge icons have a stylised icon frame.
+     */
+    CHALLENGE(ChatColor.DARK_PURPLE),
+    /**
+     * Goal icons have a rounded icon frame.
+     */
+    GOAL(ChatColor.GREEN);
+    private final ChatColor color;
+
+    private AdvancementDisplayType(@NotNull ChatColor color) {
+        this.color = color;
+    }
+
+    /**
+     * The chat color used by Minecraft for this advancement.
+     *
+     * @return The chat color used by this advancement type.
+     */
+    @NotNull
+    public ChatColor getColor() {
+        return color;
+    }
+}