diff --git a/api/src/main/java/com/velocitypowered/api/proxy/Player.java b/api/src/main/java/com/velocitypowered/api/proxy/Player.java index 4621f500b..9650c0f36 100644 --- a/api/src/main/java/com/velocitypowered/api/proxy/Player.java +++ b/api/src/main/java/com/velocitypowered/api/proxy/Player.java @@ -100,7 +100,11 @@ public interface Player extends CommandSource, InboundConnection, ChannelMessage */ @Deprecated void clearHeaderAndFooter(); - + + /** + * Returns {@link this} {@link Player}'s tab list. + * @return this player's tab list + */ TabList getTabList(); /** diff --git a/api/src/main/java/com/velocitypowered/api/proxy/player/TabList.java b/api/src/main/java/com/velocitypowered/api/proxy/player/TabList.java index 6de6f007a..fcf49fe66 100644 --- a/api/src/main/java/com/velocitypowered/api/proxy/player/TabList.java +++ b/api/src/main/java/com/velocitypowered/api/proxy/player/TabList.java @@ -10,7 +10,6 @@ import java.util.UUID; /** * Represents the tab list of a {@link Player}. - * TODO: Desetude */ public interface TabList { /** @@ -24,14 +23,29 @@ public interface TabList { * Clears the tab list header and footer for the player. */ void clearHeaderAndFooter(); - + + /** + * Adds a {@link TabListEntry} to the {@link Player}'s tab list. + * @param entry to add to the tab list + */ void addEntry(TabListEntry entry); - + + /** + * Removes the {@link TabListEntry} from the tab list with the {@link GameProfile} + * identified with the specified {@link UUID}. + * @param uuid of the + * @return {@link Optional} containing the removed {@link TabListEntry} if present, + * otherwise {@link Optional#empty()} + */ Optional removeEntry(UUID uuid); - + + /** + * Returns an immutable {@link Collection} of the {@link TabListEntry}s in the tab list. + * @return immutable {@link Collection} of tab list entries + */ Collection getEntries(); - //Necessary because the TabListEntry implementation isn't in the api + // Necessary because the TabListEntry implementation isn't in the api @Deprecated TabListEntry buildEntry(GameProfile profile, Component displayName, int latency, int gameMode); } diff --git a/api/src/main/java/com/velocitypowered/api/proxy/player/TabListEntry.java b/api/src/main/java/com/velocitypowered/api/proxy/player/TabListEntry.java index b6d567c12..4e25b1ec5 100644 --- a/api/src/main/java/com/velocitypowered/api/proxy/player/TabListEntry.java +++ b/api/src/main/java/com/velocitypowered/api/proxy/player/TabListEntry.java @@ -3,34 +3,101 @@ package com.velocitypowered.api.proxy.player; import com.google.common.base.Preconditions; import com.velocitypowered.api.util.GameProfile; import net.kyori.text.Component; +import org.checkerframework.checker.nullness.qual.NonNull; import org.checkerframework.checker.nullness.qual.Nullable; import java.util.Optional; /** - * TODO: Desetude + * Represents a single entry in a {@link TabList}. */ public interface TabListEntry { - TabList getTabList(); - - GameProfile getProfile(); - - Optional getDisplayName(); - - TabListEntry setDisplayName(@Nullable Component displayName); - + /** + * Returns the parent {@link TabList} of this {@code this} {@link TabListEntry}. + * @return parent {@link TabList} + */ + @NonNull TabList getTabList(); + + /** + * Returns the {@link GameProfile} of the entry, which uniquely identifies the entry + * with the containing {@link java.util.UUID}, as well as deciding what is shown + * as the player head in the tab list. + * @return {@link GameProfile} of the entry + */ + @NonNull GameProfile getProfile(); + + /** + * Returns {@link Optional} text {@link Component}, which if present is the text displayed for + * {@code this} entry in the {@link TabList}, otherwise {@link GameProfile#getName()} is shown. + * @return {@link Optional} text {@link Component} of name displayed in the tab list + */ + @NonNull Optional getDisplayName(); + + /** + * Sets the text {@link Component} to be displayed for {@code this} {@link TabListEntry}. + * If {@code null}, {@link GameProfile#getName()} will be shown. + * @param displayName to show in the {@link TabList} for {@code this} entry + * @return {@code this}, for chaining + */ + @NonNull TabListEntry setDisplayName(@Nullable Component displayName); + + /** + * Returns the latency for {@code this} entry. + *

The icon shown in the tab list is calculated by the latency in the following way:

+ *

    + *
  • A negative latency will display the no connection icon
    • + *
  • 0-150 will display 5 bars
    • + *
  • 150-300 will display 4 bars
    • + *
  • 300-600 will display 3 bars
    • + *
  • 600-1000 will display 2 bars
    • + *
  • A latency move than 1 second will display 1 bar
    • + *
  • + *
+ * @return latency set for {@code this} entry + */ int getLatency(); - - TabListEntry setLatency(int latency); - + + /** + * Sets the latency for {@code this} entry to the specified value + * @see this#getLatency() + * @param latency to changed to + * @return {@code this}, for chaining + */ + @NonNull TabListEntry setLatency(int latency); + + /** + * Gets the game mode {@code this} entry has been set to. + *

The number corresponds to the game mode in the following way:

+ *
    + *
  1. Survival
    2. + *
  2. Creative
    3. + *
  3. Adventure
    4. + *
  4. Spectator
    5. + *
+ * @return + */ int getGameMode(); - + + /** + * Sets the game mode for {@code this} entry to the specified value + * @see this#getGameMode() + * @param gameMode to change to + * @return {@code this}, for chaining + */ TabListEntry setGameMode(int gameMode); - + + /** + * Returns a {@link Builder} to create a {@link TabListEntry}. + * @return {@link TabListEntry} builder + */ static Builder builder() { return new Builder(); } - + + /** + * Represents a builder which creates {@link TabListEntry}s. + * @see TabListEntry + */ class Builder { private TabList tabList; private GameProfile profile; @@ -39,32 +106,66 @@ public interface TabListEntry { private int gameMode = 0; private Builder() {} - + + /** + * Sets the parent {@link TabList} for this entry, + * the entry will only be able to be added to that specific {@link TabList}. + * @param tabList to set + * @return {@code this}, for chaining + */ public Builder tabList(TabList tabList) { this.tabList = tabList; return this; } - + + /** + * Sets the {@link GameProfile} of the {@link TabListEntry}. + * @see TabListEntry#getProfile() + * @param profile to set + * @return {@code this}, for chaining + */ public Builder profile(GameProfile profile) { this.profile = profile; return this; } - + + /** + * Sets the displayed name of the {@link TabListEntry} + * @see TabListEntry#getDisplayName() + * @param displayName to set + * @return {@code this}, for chaining + */ public Builder displayName(@Nullable Component displayName) { this.displayName = displayName; return this; } - + + /** + * Sets the latency of the {@link TabListEntry} + * @see TabListEntry#getLatency() + * @param latency to set + * @return {@code this}, for chaining + */ public Builder latency(int latency) { this.latency = latency; return this; } - + + /** + * Sets the game mode of the {@link TabListEntry} + * @see TabListEntry#getGameMode() + * @param gameMode to set + * @return {@code this}, for chaining + */ public Builder gameMode(int gameMode) { this.gameMode = gameMode; return this; } - + + /** + * Constructs the {@link TabListEntry} specified by {@code this} {@link Builder}. + * @return the constructed {@link TabListEntry} + */ public TabListEntry build() { Preconditions.checkState(tabList != null, "The Tablist must be set when building a TabListEntry"); Preconditions.checkState(profile != null, "The GameProfile must be set when building a TabListEntry");