diff --git a/paper-api/src/main/java/io/papermc/paper/advancement/AdvancementDisplay.java b/paper-api/src/main/java/io/papermc/paper/advancement/AdvancementDisplay.java new file mode 100644 index 000000000..59228f2e6 --- /dev/null +++ b/paper-api/src/main/java/io/papermc/paper/advancement/AdvancementDisplay.java @@ -0,0 +1,160 @@ +package io.papermc.paper.advancement; + +import net.kyori.adventure.text.Component; +import net.kyori.adventure.text.format.NamedTextColor; +import net.kyori.adventure.text.format.TextColor; +import net.kyori.adventure.translation.Translatable; +import net.kyori.adventure.util.Index; +import org.bukkit.NamespacedKey; +import org.bukkit.inventory.ItemStack; +import org.jspecify.annotations.NullMarked; +import org.jspecify.annotations.Nullable; + +/** + * Describes the display of an advancement. + *
+ * The display is used in the chat, in the toast messages and the advancements + * screen. + */ +@NullMarked +public interface AdvancementDisplay { + + /** + * Gets the {@link Frame}. + *
+ * This defines the appearance of the tile in the advancements screen and + * the text when it's completed. + * + * @return the frame type + */ + Frame frame(); + + /** + * Gets the advancement title. + * + * @return the title + */ + Component title(); + + /** + * Gets the description. + * + * @return the description + */ + Component description(); + + /** + * Gets the icon shown in the frame in the advancements screen. + * + * @return a copy of the icon + */ + ItemStack icon(); + + /** + * Gets whether a toast should be displayed. + *
+ * A toast is a notification that will be displayed in the top right corner + * of the screen. + * + * @return {@code true} if a toast should be shown + */ + boolean doesShowToast(); + + /** + * Gets whether a message should be sent in the chat. + * + * @return {@code true} if a message should be sent + * @see org.bukkit.event.player.PlayerAdvancementDoneEvent#message() to edit + * the message + */ + boolean doesAnnounceToChat(); + + /** + * Gets whether this advancement is hidden. + *
+ * Hidden advancements cannot be viewed by the player until they have been + * unlocked. + * + * @return {@code true} if hidden + */ + boolean isHidden(); + + /** + * Gets the texture displayed behind the advancement tree when selected. + *
+ * This only affects root advancements without any parent. If the background + * is not specified or doesn't exist, the tab background will be the missing + * texture. + * + * @return the background texture path + */ + @Nullable NamespacedKey backgroundPath(); + + /** + * Gets the formatted display name for this display. This + * is a part of the component that would be shown in chat when a player + * completes the advancement. + * + * @return the display name + * @see org.bukkit.advancement.Advancement#displayName() + */ + Component displayName(); + + /** + * Defines how the {@link #icon()} appears in the advancements screen and + * the color used with the {@link #title() advancement name}. + */ + enum Frame implements Translatable { + + /** + * "Challenge complete" advancement. + *
+ * The client will play the {@code ui.toast.challenge_complete} sound
+ * when the challenge is completed and the toast is shown.
+ */
+ CHALLENGE("challenge", NamedTextColor.DARK_PURPLE),
+
+ /**
+ * "Goal reached" advancement.
+ */
+ GOAL("goal", NamedTextColor.GREEN),
+
+ /**
+ * "Advancement made" advancement.
+ */
+ TASK("task", NamedTextColor.GREEN);
+
+ /**
+ * The name map.
+ */
+ public static final Index
+ * This is the first line of the toast displayed by the client.
+ *
+ * @return the toast message key
+ */
+ @Override
+ public String translationKey() {
+ return "advancements.toast." + this.name;
+ }
+ }
+}
diff --git a/paper-api/src/main/java/org/bukkit/advancement/Advancement.java b/paper-api/src/main/java/org/bukkit/advancement/Advancement.java
index e683af5eb..5d7ab518d 100644
--- a/paper-api/src/main/java/org/bukkit/advancement/Advancement.java
+++ b/paper-api/src/main/java/org/bukkit/advancement/Advancement.java
@@ -27,13 +27,53 @@ public interface Advancement extends Keyed {
@NotNull
AdvancementRequirements getRequirements();
+ // Paper start
/**
- * Returns the display information for this advancement.
+ * Get the display info of this advancement.
+ *
+ * Will be {@code null} when totally hidden, for example with crafting
+ * recipes.
*
- * This includes it's name, description and other visible tags.
- *
- * @return a AdvancementDisplay object, or null if not set.
+ * @return the display info
*/
@Nullable
- AdvancementDisplay getDisplay();
+ io.papermc.paper.advancement.AdvancementDisplay getDisplay();
+
+ /**
+ * Gets the formatted display name for this display. This
+ * is part of the component that would be shown in chat when a player
+ * completes the advancement. Will return the same as
+ * {@link io.papermc.paper.advancement.AdvancementDisplay#displayName()} when an
+ * {@link io.papermc.paper.advancement.AdvancementDisplay} is present.
+ *
+ * @return the display name
+ * @see io.papermc.paper.advancement.AdvancementDisplay#displayName()
+ */
+ @NotNull net.kyori.adventure.text.Component displayName();
+
+ /**
+ * Gets the parent advancement, if any.
+ *
+ * @return the parent advancement
+ */
+ @Nullable
+ Advancement getParent();
+
+ /**
+ * Gets all the direct children advancements.
+ *
+ * @return the children advancements
+ */
+ @NotNull
+ @org.jetbrains.annotations.Unmodifiable
+ Collection