mirror of
https://github.com/itHotL/PlayerStats.git
synced 2025-01-22 21:41:19 +01:00
Improved documentation
This commit is contained in:
Artemis-the-gr8
parent
5368331441
commit
b207622a24
@ -1,6 +1,7 @@
|
||||
package com.gmail.artemis.the.gr8.playerstats.api;
|
||||
|
||||
import com.gmail.artemis.the.gr8.playerstats.Main;
|
||||
import net.kyori.adventure.platform.bukkit.BukkitAudiences;
|
||||
import net.kyori.adventure.text.TextComponent;
|
||||
import net.kyori.adventure.text.serializer.plain.PlainTextComponentSerializer;
|
||||
import org.bukkit.Material;
|
||||
@ -9,19 +10,25 @@ import org.bukkit.entity.EntityType;
|
||||
import org.jetbrains.annotations.Contract;
|
||||
import org.jetbrains.annotations.NotNull;
|
||||
|
||||
/** This Interface is the outgoing API that provides access to the core functionality of PlayerStats.
|
||||
To work with it, you can call PlayerStats.{@link #getAPI()} to get an instance of {@link PlayerStatsAPI}.
|
||||
You can then use this object to get formatted statistics.
|
||||
|
||||
<p>Since calculating a top or server statistics can take some time, it is recommended to call any of the
|
||||
/** This is the outgoing API that you can use to access the core functionality of PlayerStats.
|
||||
To work with it, you need to call PlayerStats.{@link #getAPI()} to get an instance of {@link PlayerStatsAPI}.
|
||||
You can then use this object to access any of the further methods.
|
||||
<br>
|
||||
<br>Since calculating a top or server statistics can take some time, it is recommended to call all the
|
||||
getServerStat() or getTopStats() methods asynchronously. Otherwise, the main Thread will have
|
||||
to wait until all calculations are done, and this might cause lag spikes on the server.</p>
|
||||
|
||||
<p>The result of the methods in PlayerStats' API are returned in the form of a TextComponent,
|
||||
which can be sent directly to a Minecraft client with the Adventure library,
|
||||
or turned into a String with {@link #statResultComponentToString(TextComponent)}.
|
||||
Don't use the Adventure method .content() on your result instead of the method specified in here -
|
||||
because of the way the TextComponent is built by PlayerStats, you won't be able to get the full content that way. </p>*/
|
||||
to wait until all calculations are done, and this might cause some lag spikes on the server.
|
||||
<br>
|
||||
<br>The result of the methods in PlayerStats' API are returned in the form of a TextComponent,
|
||||
which can be sent directly to a Minecraft client or console with the Adventure library.
|
||||
To send a Component, you need to get a {@link BukkitAudiences} object. Normally you would
|
||||
have to add the library as a dependency, but since the library is included in PlayerStats, you can
|
||||
access it directly. Information on how to get and use the BukkitAudiences object can be found on
|
||||
<a href="https://docs.adventure.kyori.net/platform/bukkit.html">Adventure's website</a>.
|
||||
<br>
|
||||
<br>Alternatively, you can also turn your TextComponent into a plain String with
|
||||
{@link #statResultComponentToString(TextComponent)}. Don't use Adventure's method .content()
|
||||
on your statResult to do this - because of the way the TextComponent is built by PlayerStats,
|
||||
you won't be able to get the full content that way. </p>*/
|
||||
public interface PlayerStats {
|
||||
|
||||
/** Returns an instance of the {@link PlayerStatsAPI}.
|
||||
@ -33,35 +40,71 @@ public interface PlayerStats {
|
||||
|
||||
/** Turns a TextComponent into its String representation. If you don't want to work with
|
||||
Adventure's TextComponents, you can call this method to turn any stat-result into a String.
|
||||
It will lose all color and style, but it will keep line-breaks.*/
|
||||
@return a String representation of this TextComponent, without color and style, but with line-breaks*/
|
||||
default String statResultComponentToString(TextComponent statResult) {
|
||||
return PlainTextComponentSerializer.plainText().serialize(statResult);
|
||||
}
|
||||
|
||||
/** Get a formatted player-statistic of Statistic.Type UNTYPED.*/
|
||||
TextComponent getPlayerStat(@NotNull Statistic statistic, @NotNull String playerName) throws IllegalArgumentException;
|
||||
/** Get a formatted player-statistic of Statistic.Type UNTYPED.
|
||||
@return a TextComponent with the following parts:
|
||||
<br>[player-name]: [number] [stat-name]
|
||||
@throws NullPointerException if statistic or playerName is null*/
|
||||
TextComponent getPlayerStat(@NotNull Statistic statistic, @NotNull String playerName) throws NullPointerException;
|
||||
|
||||
/** Get a formatted player-statistic of Statistic.Type BLOCK or ITEM.*/
|
||||
TextComponent getPlayerStat(@NotNull Statistic statistic, @NotNull Material material, @NotNull String playerName) throws IllegalArgumentException;
|
||||
/** Get a formatted player-statistic of Statistic.Type BLOCK or ITEM.
|
||||
@return a TextComponent with the following parts:
|
||||
<br>[player-name]: [number] [stat-name] [sub-stat-name]
|
||||
@throws NullPointerException if statistic, material or playerName is null*/
|
||||
TextComponent getPlayerStat(@NotNull Statistic statistic, @NotNull Material material, @NotNull String playerName) throws NullPointerException;
|
||||
|
||||
/** Get a formatted player-statistic of Statistic.Type ENTITY.*/
|
||||
TextComponent getPlayerStat(@NotNull Statistic statistic, @NotNull EntityType entity, @NotNull String playerName) throws IllegalArgumentException;
|
||||
/** Get a formatted player-statistic of Statistic.Type ENTITY.
|
||||
@return a TextComponent with the following parts:
|
||||
<br>[player-name]: [number] [stat-name] [sub-stat-name]
|
||||
@throws NullPointerException if statistic, entity or playerName is null*/
|
||||
TextComponent getPlayerStat(@NotNull Statistic statistic, @NotNull EntityType entity, @NotNull String playerName) throws NullPointerException;
|
||||
|
||||
/** Get a formatted server-statistic of Statistic.Type UNTYPED. Not recommended to call this from the main Thread (see class description).*/
|
||||
TextComponent getServerStat(@NotNull Statistic statistic) throws IllegalArgumentException;
|
||||
/** Get a formatted server-statistic of Statistic.Type UNTYPED. Not recommended to call this from the main Thread (see class description).
|
||||
@return a TextComponent with the following parts:
|
||||
<br>[Total on] [server-name]: [number] [stat-name]
|
||||
@throws NullPointerException if statistic is null*/
|
||||
TextComponent getServerStat(@NotNull Statistic statistic) throws NullPointerException;
|
||||
|
||||
/** Get a formatted server-statistic of Statistic.Type BLOCK or ITEM. Not recommended to call this from the main Thread (see class description).*/
|
||||
TextComponent getServerStat(@NotNull Statistic statistic, @NotNull Material material) throws IllegalArgumentException;
|
||||
/** Get a formatted server-statistic of Statistic.Type BLOCK or ITEM. Not recommended to call this from the main Thread (see class description).
|
||||
@return a TextComponent with the following parts:
|
||||
<br>[Total on] [server-name]: [number] [stat-name] [sub-stat-name]
|
||||
@throws NullPointerException if statistic or material is null*/
|
||||
TextComponent getServerStat(@NotNull Statistic statistic, @NotNull Material material) throws NullPointerException;
|
||||
|
||||
/** Get a formatted server-statistic of Statistic.Type ENTITY. Not recommended to call this from the main Thread (see class description).*/
|
||||
TextComponent getServerStat(@NotNull Statistic statistic, @NotNull EntityType entity) throws IllegalArgumentException;
|
||||
/** Get a formatted server-statistic of Statistic.Type ENTITY. Not recommended to call this from the main Thread (see class description).
|
||||
@return a TextComponent with the following parts:
|
||||
<br>[Total on] [server-name]: [number] [stat-name] [sub-stat-name]
|
||||
@throws NullPointerException if statistic or entity is null*/
|
||||
TextComponent getServerStat(@NotNull Statistic statistic, @NotNull EntityType entity) throws NullPointerException;
|
||||
|
||||
/** Get a formatted top-statistic of Statistic.Type UNTYPED. Not recommended to call this from the main Thread (see class description).*/
|
||||
TextComponent getTopStats(@NotNull Statistic statistic) throws IllegalArgumentException;
|
||||
/** Get a formatted top-statistic of Statistic.Type UNTYPED. Not recommended to call this from the main Thread (see class description).
|
||||
@return a TextComponent with the following parts:
|
||||
<br>[PlayerStats] [Top 10] [stat-name]
|
||||
<br> [1.] [player-name] [number]
|
||||
<br> [2.] [player-name] [number]
|
||||
<br> [3.] etc...
|
||||
@throws NullPointerException if statistic is null*/
|
||||
TextComponent getTopStats(@NotNull Statistic statistic) throws NullPointerException;
|
||||
|
||||
/** Get a formatted top-statistic of Statistic.Type BLOCK or ITEM. Not recommended to call this from the main Thread (see class description).*/
|
||||
TextComponent getTopStats(@NotNull Statistic statistic, @NotNull Material material) throws IllegalArgumentException;
|
||||
/** Get a formatted top-statistic of Statistic.Type BLOCK or ITEM. Not recommended to call this from the main Thread (see class description).
|
||||
@return a TextComponent with the following parts:
|
||||
<br>[PlayerStats] [Top 10] [stat-name] [sub-stat-name]
|
||||
<br> [1.] [player-name] [number]
|
||||
<br> [2.] [player-name] [number]
|
||||
<br> [3.] etc...
|
||||
@throws NullPointerException if statistic or material is null*/
|
||||
TextComponent getTopStats(@NotNull Statistic statistic, @NotNull Material material) throws NullPointerException;
|
||||
|
||||
/** Get a formatted top-statistic of Statistic.Type ENTITY. Not recommended to call this from the main Thread (see class description).*/
|
||||
TextComponent getTopStats(@NotNull Statistic statistic, @NotNull EntityType entity) throws IllegalArgumentException;
|
||||
/** Get a formatted top-statistic of Statistic.Type ENTITY. Not recommended to call this from the main Thread (see class description).
|
||||
@return a TextComponent with the following parts:
|
||||
<br>[PlayerStats] [Top 10] [stat-name] [sub-stat-name]
|
||||
<br> [1.] [player-name] [number]
|
||||
<br> [2.] [player-name] [number]
|
||||
<br> [3.] etc...
|
||||
@throws NullPointerException if statistic or entity is null*/
|
||||
TextComponent getTopStats(@NotNull Statistic statistic, @NotNull EntityType entity) throws NullPointerException;
|
||||
}
|
||||
@ -31,52 +31,52 @@ public final class PlayerStatsAPI implements PlayerStats {
|
||||
}
|
||||
|
||||
@Override
|
||||
public TextComponent getPlayerStat(@NotNull Statistic statistic, @NotNull String playerName) throws IllegalArgumentException {
|
||||
public TextComponent getPlayerStat(@NotNull Statistic statistic, @NotNull String playerName) throws NullPointerException {
|
||||
return getFormattedStatistic(Target.PLAYER, statistic, null, null, playerName);
|
||||
}
|
||||
|
||||
@Override
|
||||
public TextComponent getPlayerStat(@NotNull Statistic statistic, @NotNull Material material, @NotNull String playerName) throws IllegalArgumentException {
|
||||
public TextComponent getPlayerStat(@NotNull Statistic statistic, @NotNull Material material, @NotNull String playerName) throws NullPointerException {
|
||||
return getFormattedStatistic(Target.PLAYER, statistic, material, null, playerName);
|
||||
}
|
||||
|
||||
@Override
|
||||
public TextComponent getPlayerStat(@NotNull Statistic statistic, @NotNull EntityType entity, @NotNull String playerName) throws IllegalArgumentException {
|
||||
public TextComponent getPlayerStat(@NotNull Statistic statistic, @NotNull EntityType entity, @NotNull String playerName) throws NullPointerException {
|
||||
return getFormattedStatistic(Target.PLAYER, statistic, null, entity, playerName);
|
||||
}
|
||||
|
||||
@Override
|
||||
public TextComponent getServerStat(@NotNull Statistic statistic) throws IllegalArgumentException {
|
||||
public TextComponent getServerStat(@NotNull Statistic statistic) throws NullPointerException {
|
||||
return getFormattedStatistic(Target.SERVER, statistic, null, null, null);
|
||||
}
|
||||
|
||||
@Override
|
||||
public TextComponent getServerStat(@NotNull Statistic statistic, @NotNull Material material) throws IllegalArgumentException {
|
||||
public TextComponent getServerStat(@NotNull Statistic statistic, @NotNull Material material) throws NullPointerException {
|
||||
return getFormattedStatistic(Target.SERVER, statistic, material, null, null);
|
||||
}
|
||||
|
||||
@Override
|
||||
public TextComponent getServerStat(@NotNull Statistic statistic, @NotNull EntityType entity) throws IllegalArgumentException {
|
||||
public TextComponent getServerStat(@NotNull Statistic statistic, @NotNull EntityType entity) throws NullPointerException {
|
||||
return getFormattedStatistic(Target.SERVER, statistic, null, entity, null);
|
||||
}
|
||||
|
||||
@Override
|
||||
public TextComponent getTopStats(@NotNull Statistic statistic) throws IllegalArgumentException {
|
||||
public TextComponent getTopStats(@NotNull Statistic statistic) throws NullPointerException {
|
||||
return getFormattedStatistic(Target.TOP, statistic, null, null, null);
|
||||
}
|
||||
|
||||
@Override
|
||||
public TextComponent getTopStats(@NotNull Statistic statistic, @NotNull Material material) throws IllegalArgumentException {
|
||||
public TextComponent getTopStats(@NotNull Statistic statistic, @NotNull Material material) throws NullPointerException {
|
||||
return getFormattedStatistic(Target.TOP, statistic, material, null, null);
|
||||
}
|
||||
|
||||
@Override
|
||||
public TextComponent getTopStats(@NotNull Statistic statistic, @NotNull EntityType entity) throws IllegalArgumentException {
|
||||
public TextComponent getTopStats(@NotNull Statistic statistic, @NotNull EntityType entity) throws NullPointerException {
|
||||
return getFormattedStatistic(Target.TOP, statistic, null, entity, null);
|
||||
}
|
||||
|
||||
private TextComponent getFormattedStatistic(@NotNull Target selection, @NotNull Statistic statistic,
|
||||
@Nullable Material material, @Nullable EntityType entity, @Nullable String playerName) throws IllegalArgumentException {
|
||||
@Nullable Material material, @Nullable EntityType entity, @Nullable String playerName) throws NullPointerException {
|
||||
StatRequest request = requestManager.generateRequest(selection, statistic, material, entity, playerName);
|
||||
if (requestManager.validateAPIRequest(request)) {
|
||||
switch (selection) {
|
||||
@ -94,6 +94,7 @@ public final class PlayerStatsAPI implements PlayerStats {
|
||||
}
|
||||
}
|
||||
}
|
||||
throw new IllegalArgumentException("This is not a valid stat-request!");
|
||||
throw new NullPointerException("Not enough parameters are present for a valid statistic look-up! " +
|
||||
"Make sure you include a block/item/entity if Statistic.Type is not Untyped, and include a playerName if you want a player-statistic");
|
||||
}
|
||||
}
|
||||
@ -352,7 +352,7 @@ public class MessageBuilder {
|
||||
/** Depending on the config settings, return either a TranslatableComponent representing
|
||||
the statName (and potential subStatName), or a TextComponent with capitalized English names.*/
|
||||
private TextComponent getStatNameComponent(StatRequest request) {
|
||||
if (config.useTranslatableComponents() && !request.isAPIRequest()) {
|
||||
if (config.useTranslatableComponents()) {
|
||||
String statKey = languageKeyHandler.getStatKey(request.getStatistic());
|
||||
String subStatKey = request.getSubStatEntry();
|
||||
if (subStatKey != null) {
|
||||
|
||||
Loading…
Reference in New Issue
Block a user