2019-06-14 02:27:40 +00:00
From c76bce420738f306b2c47f2714099d328d1338dd Mon Sep 17 00:00:00 2001
2016-02-18 02:03:21 +00:00
From: Techcable <Techcable@outlook.com>
2016-02-29 23:09:49 +00:00
Date: Mon, 29 Feb 2016 20:02:40 -0600
2016-02-17 01:55:21 +00:00
Subject: [PATCH] Player Tab List and Title APIs
2016-02-29 23:09:49 +00:00
diff --git a/src/main/java/com/destroystokyo/paper/Title.java b/src/main/java/com/destroystokyo/paper/Title.java
2016-02-18 02:03:21 +00:00
new file mode 100644
2019-06-14 02:27:40 +00:00
index 000000000..4fe18540f
2016-02-18 02:03:21 +00:00
--- /dev/null
2016-02-29 23:09:49 +00:00
+++ b/src/main/java/com/destroystokyo/paper/Title.java
2019-03-20 00:28:15 +00:00
@@ -0,0 +1,373 @@
2016-02-29 23:09:49 +00:00
+package com.destroystokyo.paper;
2016-02-18 02:03:21 +00:00
+
+import net.md_5.bungee.api.chat.BaseComponent;
+import net.md_5.bungee.api.chat.TextComponent;
+
+import org.bukkit.entity.Player;
2019-03-20 00:28:15 +00:00
+import org.jetbrains.annotations.NotNull;
+import org.jetbrains.annotations.Nullable;
2016-02-18 02:03:21 +00:00
+
+import static com.google.common.base.Preconditions.checkArgument;
+import static com.google.common.base.Preconditions.checkNotNull;
+import static com.google.common.base.Preconditions.checkState;
+
+/**
+ * Represents a title to may be sent to a {@link Player}.
2017-06-10 22:11:10 +00:00
+ *
2016-02-18 02:03:21 +00:00
+ * <p>A title can be sent without subtitle text.</p>
+ */
+public final class Title {
+
+ /**
+ * The default number of ticks for the title to fade in.
+ */
+ public static final int DEFAULT_FADE_IN = 20;
+ /**
+ * The default number of ticks for the title to stay.
+ */
+ public static final int DEFAULT_STAY = 200;
+ /**
+ * The default number of ticks for the title to fade out.
+ */
+ public static final int DEFAULT_FADE_OUT = 20;
+
+ private final BaseComponent[] title;
+ private final BaseComponent[] subtitle;
+ private final int fadeIn;
+ private final int stay;
+ private final int fadeOut;
+
+ /**
+ * Create a title with the default time values and no subtitle.
2017-06-10 22:11:10 +00:00
+ *
2016-02-18 02:03:21 +00:00
+ * <p>Times use default values.</p>
+ *
+ * @param title the main text of the title
+ * @throws NullPointerException if the title is null
+ */
2019-03-20 00:28:15 +00:00
+ public Title(@NotNull BaseComponent title) {
2016-02-18 02:03:21 +00:00
+ this(title, null);
+ }
+
+ /**
+ * Create a title with the default time values and no subtitle.
2017-06-10 22:11:10 +00:00
+ *
2016-02-18 02:03:21 +00:00
+ * <p>Times use default values.</p>
+ *
+ * @param title the main text of the title
+ * @throws NullPointerException if the title is null
+ */
2019-03-20 00:28:15 +00:00
+ public Title(@NotNull BaseComponent[] title) {
2016-02-18 02:03:21 +00:00
+ this(title, null);
+ }
+
+ /**
+ * Create a title with the default time values and no subtitle.
2017-06-10 22:11:10 +00:00
+ *
2016-02-18 02:03:21 +00:00
+ * <p>Times use default values.</p>
+ *
+ * @param title the main text of the title
+ * @throws NullPointerException if the title is null
+ */
2019-03-20 00:28:15 +00:00
+ public Title(@NotNull String title) {
2016-02-18 02:03:21 +00:00
+ this(title, null);
+ }
+
+ /**
+ * Create a title with the default time values.
2017-06-10 22:11:10 +00:00
+ *
2016-02-18 02:03:21 +00:00
+ * <p>Times use default values.</p>
+ *
+ * @param title the main text of the title
+ * @param subtitle the secondary text of the title
+ */
2019-03-20 00:28:15 +00:00
+ public Title(@NotNull BaseComponent title, @Nullable BaseComponent subtitle) {
2016-02-18 02:03:21 +00:00
+ this(title, subtitle, DEFAULT_FADE_IN, DEFAULT_STAY, DEFAULT_FADE_OUT);
+ }
+
+ /**
+ * Create a title with the default time values.
2017-06-10 22:11:10 +00:00
+ *
2016-02-18 02:03:21 +00:00
+ * <p>Times use default values.</p>
+ *
+ * @param title the main text of the title
+ * @param subtitle the secondary text of the title
+ */
2019-03-20 00:28:15 +00:00
+ public Title(@NotNull BaseComponent[] title, @Nullable BaseComponent[] subtitle) {
2016-02-18 02:03:21 +00:00
+ this(title, subtitle, DEFAULT_FADE_IN, DEFAULT_STAY, DEFAULT_FADE_OUT);
+ }
+
+ /**
+ * Create a title with the default time values.
2017-06-10 22:11:10 +00:00
+ *
2016-02-18 02:03:21 +00:00
+ * <p>Times use default values.</p>
+ *
+ * @param title the main text of the title
+ * @param subtitle the secondary text of the title
+ */
2019-03-20 00:28:15 +00:00
+ public Title(@NotNull String title, @Nullable String subtitle) {
2016-02-18 02:03:21 +00:00
+ this(title, subtitle, DEFAULT_FADE_IN, DEFAULT_STAY, DEFAULT_FADE_OUT);
+ }
+
+ /**
+ * Creates a new title.
+ *
+ * @param title the main text of the title
+ * @param subtitle the secondary text of the title
+ * @param fadeIn the number of ticks for the title to fade in
+ * @param stay the number of ticks for the title to stay on screen
+ * @param fadeOut the number of ticks for the title to fade out
+ * @throws IllegalArgumentException if any of the times are negative
+ */
2019-03-20 00:28:15 +00:00
+ public Title(@NotNull BaseComponent title, @Nullable BaseComponent subtitle, int fadeIn, int stay, int fadeOut) {
2016-02-18 02:03:21 +00:00
+ this(
+ new BaseComponent[]{checkNotNull(title, "title")},
+ subtitle == null ? null : new BaseComponent[]{subtitle},
+ fadeIn,
+ stay,
+ fadeOut
+ );
+ }
+
+ /**
+ * Creates a new title.
+ *
+ * @param title the main text of the title
+ * @param subtitle the secondary text of the title
+ * @param fadeIn the number of ticks for the title to fade in
+ * @param stay the number of ticks for the title to stay on screen
+ * @param fadeOut the number of ticks for the title to fade out
+ * @throws IllegalArgumentException if any of the times are negative
+ */
2019-03-20 00:28:15 +00:00
+ public Title(@Nullable BaseComponent[] title, @NotNull BaseComponent[] subtitle, int fadeIn, int stay, int fadeOut) {
2016-02-18 02:03:21 +00:00
+ checkArgument(fadeIn >= 0, "Negative fadeIn: %s", fadeIn);
+ checkArgument(stay >= 0, "Negative stay: %s", stay);
+ checkArgument(fadeOut >= 0, "Negative fadeOut: %s", fadeOut);
+ this.title = checkNotNull(title, "title");
+ this.subtitle = subtitle;
+ this.fadeIn = fadeIn;
+ this.stay = stay;
+ this.fadeOut = fadeOut;
+ }
+
+ /**
+ * Creates a new title.
2017-06-10 22:11:10 +00:00
+ *
2016-02-18 02:03:21 +00:00
+ * <p>It is recommended to the {@link BaseComponent} constrctors.</p>
+ *
+ * @param title the main text of the title
+ * @param subtitle the secondary text of the title
+ * @param fadeIn the number of ticks for the title to fade in
+ * @param stay the number of ticks for the title to stay on screen
+ * @param fadeOut the number of ticks for the title to fade out
+ */
2019-03-20 00:28:15 +00:00
+ public Title(@NotNull String title, @Nullable String subtitle, int fadeIn, int stay, int fadeOut) {
2016-02-18 02:03:21 +00:00
+ this(
+ TextComponent.fromLegacyText(checkNotNull(title, "title")),
+ subtitle == null ? null : TextComponent.fromLegacyText(subtitle),
+ fadeIn,
+ stay,
+ fadeOut
+ );
+ }
+
+ /**
+ * Gets the text of this title
+ *
+ * @return the text
+ */
2019-03-20 00:28:15 +00:00
+ @NotNull
2016-02-18 02:03:21 +00:00
+ public BaseComponent[] getTitle() {
+ return this.title;
+ }
+
+ /**
+ * Gets the text of this title's subtitle
+ *
+ * @return the text
+ */
2019-03-20 00:28:15 +00:00
+ @Nullable
2016-02-18 02:03:21 +00:00
+ public BaseComponent[] getSubtitle() {
+ return this.subtitle;
+ }
+
+ /**
+ * Gets the number of ticks to fade in.
2017-06-10 22:11:10 +00:00
+ *
2016-02-18 02:03:21 +00:00
+ * <p>The returned value is never negative.</p>
+ *
+ * @return the number of ticks to fade in
+ */
+ public int getFadeIn() {
+ return this.fadeIn;
+ }
+
+ /**
+ * Gets the number of ticks to stay.
2017-06-10 22:11:10 +00:00
+ *
2016-02-18 02:03:21 +00:00
+ * <p>The returned value is never negative.</p>
+ *
+ * @return the number of ticks to stay
+ */
+ public int getStay() {
+ return this.stay;
+ }
+
+ /**
+ * Gets the number of ticks to fade out.
2017-06-10 22:11:10 +00:00
+ *
2016-02-18 02:03:21 +00:00
+ * <p>The returned value is never negative.</p>
+ *
+ * @return the number of ticks to fade out
+ */
+ public int getFadeOut() {
+ return this.fadeOut;
+ }
+
2019-03-20 00:28:15 +00:00
+ @NotNull
2016-02-18 02:03:21 +00:00
+ public static Builder builder() {
+ return new Builder();
+ }
+
+ /**
+ * A builder for creating titles
+ */
+ public static final class Builder {
+
+ private BaseComponent[] title;
+ private BaseComponent[] subtitle;
+ private int fadeIn = DEFAULT_FADE_IN;
+ private int stay = DEFAULT_STAY;
+ private int fadeOut = DEFAULT_FADE_OUT;
+
+ /**
+ * Sets the title to the given text.
+ *
+ * @param title the title text
+ * @return this builder instance
+ * @throws NullPointerException if the title is null
+ */
2019-03-20 00:28:15 +00:00
+ @NotNull
+ public Builder title(@NotNull BaseComponent title) {
2016-02-18 02:03:21 +00:00
+ return this.title(new BaseComponent[]{checkNotNull(title, "title")});
+ }
+
+ /**
+ * Sets the title to the given text.
+ *
+ * @param title the title text
+ * @return this builder instance
+ * @throws NullPointerException if the title is null
+ */
2019-03-20 00:28:15 +00:00
+ @NotNull
+ public Builder title(@NotNull BaseComponent[] title) {
2016-02-18 02:03:21 +00:00
+ this.title = checkNotNull(title, "title");
+ return this;
+ }
+
+ /**
+ * Sets the title to the given text.
2017-06-10 22:11:10 +00:00
+ *
2016-02-18 02:03:21 +00:00
+ * <p>It is recommended to the {@link BaseComponent} methods.</p>
+ *
+ * @param title the title text
+ * @return this builder instance
+ * @throws NullPointerException if the title is null
+ */
2019-03-20 00:28:15 +00:00
+ @NotNull
+ public Builder title(@NotNull String title) {
2016-02-18 02:03:21 +00:00
+ return this.title(TextComponent.fromLegacyText(checkNotNull(title, "title")));
+ }
+
+ /**
+ * Sets the subtitle to the given text.
+ *
+ * @param subtitle the title text
+ * @return this builder instance
+ */
2019-03-20 00:28:15 +00:00
+ @NotNull
+ public Builder subtitle(@Nullable BaseComponent subtitle) {
2016-02-18 02:03:21 +00:00
+ return this.subtitle(subtitle == null ? null : new BaseComponent[]{subtitle});
+ }
+
+ /**
+ * Sets the subtitle to the given text.
+ *
+ * @param subtitle the title text
+ * @return this builder instance
+ */
2019-03-20 00:28:15 +00:00
+ @NotNull
+ public Builder subtitle(@Nullable BaseComponent[] subtitle) {
2016-02-18 02:03:21 +00:00
+ this.subtitle = subtitle;
+ return this;
+ }
+
+ /**
+ * Sets the subtitle to the given text.
2017-06-10 22:11:10 +00:00
+ *
2016-02-18 02:03:21 +00:00
+ * <p>It is recommended to the {@link BaseComponent} methods.</p>
+ *
+ * @param subtitle the title text
+ * @return this builder instance
+ */
2019-03-20 00:28:15 +00:00
+ @NotNull
+ public Builder subtitle(@Nullable String subtitle) {
2016-02-18 02:03:21 +00:00
+ return this.subtitle(subtitle == null ? null : TextComponent.fromLegacyText(subtitle));
+ }
+
+ /**
+ * Sets the number of ticks for the title to fade in
+ *
+ * @param fadeIn the number of ticks to fade in
+ * @return this builder instance
+ * @throws IllegalArgumentException if it is negative
+ */
2019-03-20 00:28:15 +00:00
+ @NotNull
2016-02-18 02:03:21 +00:00
+ public Builder fadeIn(int fadeIn) {
+ checkArgument(fadeIn >= 0, "Negative fadeIn: %s", fadeIn);
+ this.fadeIn = fadeIn;
+ return this;
+ }
+
+
+ /**
+ * Sets the number of ticks for the title to stay.
+ *
+ * @param stay the number of ticks to stay
+ * @return this builder instance
+ * @throws IllegalArgumentException if it is negative
+ */
2019-03-20 00:28:15 +00:00
+ @NotNull
2016-02-18 02:03:21 +00:00
+ public Builder stay(int stay) {
+ checkArgument(stay >= 0, "Negative stay: %s", stay);
+ this.stay = stay;
+ return this;
+ }
+
+ /**
+ * Sets the number of ticks for the title to fade out.
+ *
+ * @param fadeOut the number of ticks to fade out
+ * @return this builder instance
+ * @throws IllegalArgumentException if it is negative
+ */
2019-03-20 00:28:15 +00:00
+ @NotNull
2016-02-18 02:03:21 +00:00
+ public Builder fadeOut(int fadeOut) {
+ checkArgument(fadeOut >= 0, "Negative fadeOut: %s", fadeOut);
+ this.fadeOut = fadeOut;
+ return this;
+ }
+
+ /**
+ * Create a title based on the values in the builder.
+ *
+ * @return a title from the values in this builder
+ * @throws IllegalStateException if title isn't specified
+ */
2019-03-20 00:28:15 +00:00
+ @NotNull
2016-02-18 02:03:21 +00:00
+ public Title build() {
+ checkState(title != null, "Title not specified");
+ return new Title(this.title, this.subtitle, this.fadeIn, this.stay, this.fadeOut);
+ }
+ }
+}
2016-02-29 23:09:49 +00:00
diff --git a/src/main/java/org/bukkit/entity/Player.java b/src/main/java/org/bukkit/entity/Player.java
2019-06-14 02:27:40 +00:00
index de1b1512f..40246fb99 100644
2016-02-29 23:09:49 +00:00
--- a/src/main/java/org/bukkit/entity/Player.java
+++ b/src/main/java/org/bukkit/entity/Player.java
2019-04-23 04:47:07 +00:00
@@ -1,6 +1,8 @@
package org.bukkit.entity;
2016-02-29 23:09:49 +00:00
import java.net.InetSocketAddress;
2019-04-23 04:47:07 +00:00
+
2016-02-29 23:09:49 +00:00
+import com.destroystokyo.paper.Title;
import org.bukkit.Achievement;
import org.bukkit.Effect;
2019-03-20 00:28:15 +00:00
import org.bukkit.GameMode;
2019-06-08 20:33:05 +00:00
@@ -452,6 +454,116 @@ public interface Player extends HumanEntity, Conversable, OfflinePlayer, PluginM
2016-12-20 22:34:27 +00:00
public default void sendMessage(net.md_5.bungee.api.ChatMessageType position, net.md_5.bungee.api.chat.BaseComponent... components) {
spigot().sendMessage(position, components);
}
2016-02-29 23:09:49 +00:00
+
+ /**
+ * Set the text displayed in the player list header and footer for this player
+ *
+ * @param header content for the top of the player list
+ * @param footer content for the bottom of the player list
+ */
2019-03-20 00:28:15 +00:00
+ public void setPlayerListHeaderFooter(@Nullable net.md_5.bungee.api.chat.BaseComponent[] header, @Nullable net.md_5.bungee.api.chat.BaseComponent[] footer);
2016-02-29 23:09:49 +00:00
+
+ /**
+ * Set the text displayed in the player list header and footer for this player
+ *
+ * @param header content for the top of the player list
+ * @param footer content for the bottom of the player list
+ */
2019-03-20 00:28:15 +00:00
+ public void setPlayerListHeaderFooter(@Nullable net.md_5.bungee.api.chat.BaseComponent header, @Nullable net.md_5.bungee.api.chat.BaseComponent footer);
2016-02-29 23:09:49 +00:00
+
+ /**
+ * Update the times for titles displayed to the player
+ *
+ * @param fadeInTicks ticks to fade-in
+ * @param stayTicks ticks to stay visible
+ * @param fadeOutTicks ticks to fade-out
+ * @deprecated Use {@link #updateTitle(Title)}
+ */
+ @Deprecated
+ public void setTitleTimes(int fadeInTicks, int stayTicks, int fadeOutTicks);
+
+ /**
+ * Update the subtitle of titles displayed to the player
+ *
+ * @deprecated Use {@link #updateTitle(Title)}
+ */
+ @Deprecated
+ public void setSubtitle(net.md_5.bungee.api.chat.BaseComponent[] subtitle);
+
+ /**
+ * Update the subtitle of titles displayed to the player
+ *
+ * @deprecated Use {@link #updateTitle(Title)}
+ */
+ @Deprecated
+ public void setSubtitle(net.md_5.bungee.api.chat.BaseComponent subtitle);
+
+ /**
+ * Show the given title to the player, along with the last subtitle set, using the last set times
+ *
+ * @deprecated Use {@link #sendTitle(Title)} or {@link #updateTitle(Title)}
+ */
+ @Deprecated
2019-03-20 00:28:15 +00:00
+ public void showTitle(@Nullable net.md_5.bungee.api.chat.BaseComponent[] title);
2016-02-29 23:09:49 +00:00
+
+ /**
+ * Show the given title to the player, along with the last subtitle set, using the last set times
+ *
+ * @deprecated Use {@link #sendTitle(Title)} or {@link #updateTitle(Title)}
+ */
+ @Deprecated
2019-03-20 00:28:15 +00:00
+ public void showTitle(@Nullable net.md_5.bungee.api.chat.BaseComponent title);
2016-02-29 23:09:49 +00:00
+
+ /**
+ * Show the given title and subtitle to the player using the given times
+ *
+ * @param title big text
+ * @param subtitle little text under it
+ * @param fadeInTicks ticks to fade-in
+ * @param stayTicks ticks to stay visible
+ * @param fadeOutTicks ticks to fade-out
+ * @deprecated Use {@link #sendTitle(Title)} or {@link #updateTitle(Title)}
+ */
+ @Deprecated
2019-03-20 00:28:15 +00:00
+ public void showTitle(@Nullable net.md_5.bungee.api.chat.BaseComponent[] title, @Nullable net.md_5.bungee.api.chat.BaseComponent[] subtitle, int fadeInTicks, int stayTicks, int fadeOutTicks);
2016-02-29 23:09:49 +00:00
+
+ /**
+ * Show the given title and subtitle to the player using the given times
+ *
+ * @param title big text
+ * @param subtitle little text under it
+ * @param fadeInTicks ticks to fade-in
+ * @param stayTicks ticks to stay visible
+ * @param fadeOutTicks ticks to fade-out
+ * @deprecated Use {@link #sendTitle(Title)} or {@link #updateTitle(Title)}
+ */
+ @Deprecated
2019-03-20 00:28:15 +00:00
+ public void showTitle(@Nullable net.md_5.bungee.api.chat.BaseComponent title, @Nullable net.md_5.bungee.api.chat.BaseComponent subtitle, int fadeInTicks, int stayTicks, int fadeOutTicks);
2016-02-29 23:09:49 +00:00
+
+ /**
+ * Show the title to the player, overriding any previously displayed title.
2017-06-10 22:11:10 +00:00
+ *
2016-02-29 23:09:49 +00:00
+ * <p>This method overrides any previous title, use {@link #updateTitle(Title)} to change the existing one.</p>
+ *
+ * @param title the title to send
+ * @throws NullPointerException if the title is null
+ */
2019-03-20 00:28:15 +00:00
+ void sendTitle(@NotNull Title title);
2016-02-29 23:09:49 +00:00
+
+ /**
+ * Show the title to the player, overriding any previously displayed title.
2017-06-10 22:11:10 +00:00
+ *
2016-02-29 23:09:49 +00:00
+ * <p>This method doesn't override previous titles, but changes their values.</p>
+ *
+ * @param title the title to send
+ * @throws NullPointerException if title is null
+ */
2019-03-20 00:28:15 +00:00
+ void updateTitle(@NotNull Title title);
2016-02-29 23:09:49 +00:00
+
+ /**
+ * Hide any title that is currently visible to the player
+ */
+ public void hideTitle();
// Paper end
/**
2016-02-17 01:55:21 +00:00
--
2019-03-20 00:28:15 +00:00
2.21.0
2016-02-17 01:55:21 +00:00