+ * Each API instance only manages the holograms and the placeholders of a specific plugin, see {@link #get(Plugin)}. * * @since 1 */ public interface HolographicDisplaysAPI { /** - * Returns the API version number, which is increased every time the API changes. This number is used to check if a - * certain method or class (which may have been added later) is present or not. + * Returns the API version number, which is increased every time the API changes. *
* All public API classes and methods are documented with the Javadoc tag {@code @since}, indicating in which API * version that element was introduced. *
- * It can be used it to require a minimum version, as features may be added (rarely removed) in future versions. The - * first version of the API is 1. + * This number can be used it to require a minimum version, as features may be added (rarely removed) in future + * versions. The first version of the API is 1. *
- * The API version is independent of the normal plugin version.
+ * The API version is unrelated to the standard plugin version.
*
* @return the current API version
* @since 1
@@ -61,57 +64,134 @@ public interface HolographicDisplaysAPI {
}
/**
- * Creates a hologram at given location.
+ * Creates a hologram.
*
- * @param location the location where it will appear
+ * @param location the initial location of the hologram
* @return the created hologram
* @since 1
*/
@NotNull Hologram createHologram(@NotNull Location location);
+ /**
+ * Creates a hologram.
+ *
+ * @param position the initial position of the hologram
+ * @return the created hologram
+ * @since 1
+ */
@NotNull Hologram createHologram(@NotNull Position position);
/**
- * Returns all the active holograms. A hologram is no longer active after {@link Hologram#delete()} is invoked.
+ * Returns all the holograms. Deleted holograms are not included.
*
- * @return an immutable collection of active holograms
+ * @return an immutable copy of all the holograms
* @since 1
*/
@NotNull Collection
+ * This is a simplified method to register a placeholder by providing separately its replace function for
+ * {@link GlobalPlaceholder#getReplacement(String)} and a fixed refresh interval for
+ * {@link Placeholder#getRefreshIntervalTicks()}
+ *
+ * @param identifier the case-insensitive identifier of the placeholder
+ * @param refreshIntervalTicks the minimum interval in ticks between invocations of the replace function
+ * (when the placeholder is in use), see {@link Placeholder#getRefreshIntervalTicks()}
+ * @param replaceFunction the callback function to provide the replacement text to display
* @since 1
*/
- void registerGlobalPlaceholder(@NotNull String identifier, int refreshIntervalTicks, @NotNull GlobalPlaceholderReplaceFunction replaceFunction);
+ void registerGlobalPlaceholder(
+ @NotNull String identifier,
+ int refreshIntervalTicks,
+ @NotNull GlobalPlaceholderReplaceFunction replaceFunction);
/**
+ * Registers a new global placeholder. Any previously registered element (global or individual) with the same
+ * identifier is overwritten. See {@link GlobalPlaceholder} to know more about global placeholders.
+ *
+ * @param identifier the case-insensitive identifier of the placeholder
+ * @param placeholder the placeholder to register
* @since 1
*/
void registerGlobalPlaceholder(@NotNull String identifier, @NotNull GlobalPlaceholder placeholder);
/**
+ * Registers a new global placeholder factory. Any previously registered element (global or individual) with the
+ * same identifier is overwritten. See {@link GlobalPlaceholder} to know more about global placeholders.
+ *
+ * This method is more complex and not usually needed: it is necessary if parsing the argument of the placeholder is
+ * performance intensive, for example a mathematical expression or a JSON string.
+ *
+ * See {@link GlobalPlaceholderFactory} to know more about global placeholder factories.
+ *
+ * @param identifier the case-insensitive identifier of the placeholder factory
+ * @param placeholderFactory the placeholder factory to register
* @since 1
*/
- void registerGlobalPlaceholderFactory(@NotNull String identifier, @NotNull GlobalPlaceholderFactory placeholderFactory);
+ void registerGlobalPlaceholderFactory(
+ @NotNull String identifier,
+ @NotNull GlobalPlaceholderFactory placeholderFactory);
/**
+ * Registers a new individual placeholder. Any previously registered element (global or individual) with the
+ * same identifier is overwritten. See {@link IndividualPlaceholder} to know more about individual placeholders.
+ *
+ * This is a simplified method to register a placeholder by providing separately its replace function for
+ * {@link IndividualPlaceholder#getReplacement(Player, String)} and a fixed refresh interval for
+ * {@link Placeholder#getRefreshIntervalTicks()}
+ *
+ * @param identifier the case-insensitive identifier of the placeholder
+ * @param refreshIntervalTicks the minimum interval in ticks between invocations of the replace function for
+ * each player (when the placeholder is in use), see {@link Placeholder#getRefreshIntervalTicks()}
+ * @param replaceFunction the callback function to provide the replacement text to display
* @since 1
*/
- void registerIndividualPlaceholder(@NotNull String identifier, int refreshIntervalTicks, @NotNull IndividualPlaceholderReplaceFunction replaceFunction);
+ void registerIndividualPlaceholder(
+ @NotNull String identifier,
+ int refreshIntervalTicks,
+ @NotNull IndividualPlaceholderReplaceFunction replaceFunction);
/**
+ * Registers a new individual placeholder. Any previously registered element (global or individual) with the same
+ * identifier is overwritten. See {@link IndividualPlaceholder} to know more about individual placeholders.
+ *
+ * @param identifier the case-insensitive identifier of the placeholder
+ * @param placeholder the placeholder to register
* @since 1
*/
void registerIndividualPlaceholder(@NotNull String identifier, @NotNull IndividualPlaceholder placeholder);
/**
+ * Registers a new individual placeholder factory. Any previously registered element (global or individual) with the
+ * same identifier is overwritten. See {@link IndividualPlaceholder} to know more about individual placeholders.
+ *
+ * This method is more complex and not usually needed: it is necessary if parsing the argument of the placeholder is
+ * performance intensive, for example a mathematical expression or a JSON string.
+ *
+ * See {@link IndividualPlaceholderFactory} to know more about individual placeholder factories.
+ *
+ * @param identifier the case-insensitive identifier of the placeholder factory
+ * @param placeholderFactory the placeholder factory to register
* @since 1
*/
- void registerIndividualPlaceholderFactory(@NotNull String identifier, @NotNull IndividualPlaceholderFactory placeholderFactory);
+ void registerIndividualPlaceholderFactory(
+ @NotNull String identifier,
+ @NotNull IndividualPlaceholderFactory placeholderFactory);
/**
+ * Returns if a placeholder with a given identifier is registered.
+ *
+ * @param identifier the case-insensitive identifier of the placeholder
* @since 1
*/
boolean isRegisteredPlaceholder(@NotNull String identifier);
@@ -119,23 +199,21 @@ public interface HolographicDisplaysAPI {
/**
* Returns all the registered placeholder identifiers.
*
- * @return a collection of placeholder identifiers
+ * @return an immutable copy of the registered placeholder identifiers
* @since 1
*/
@NotNull Collection
- * Can be useful to reset placeholders before registering all of them.
+ * Unregisters all placeholders.
*
* @since 1
*/
diff --git a/api/src/main/java/me/filoghost/holographicdisplays/api/Position.java b/api/src/main/java/me/filoghost/holographicdisplays/api/Position.java
index c313da17..a5411fb9 100644
--- a/api/src/main/java/me/filoghost/holographicdisplays/api/Position.java
+++ b/api/src/main/java/me/filoghost/holographicdisplays/api/Position.java
@@ -14,72 +14,277 @@ import org.bukkit.util.Vector;
import org.jetbrains.annotations.NotNull;
import org.jetbrains.annotations.Nullable;
+/**
+ * Represents an immutable 3-dimensional position in a world. Differently from a {@link Location} it holds a reference
+ * to a world's name instead of a {@link World} object directly, making it suitable for unloaded worlds. Another
+ * difference is the lack of yaw and pitch.
+ *
+ * @since 1
+ */
public interface Position {
+ /**
+ * Returns the position with the given world and coordinates.
+ *
+ * @param world the world
+ * @param x the X coordinate
+ * @param y the Y coordinate
+ * @param z the Z coordinate
+ * @return the created position
+ * @since 1
+ */
static @NotNull Position of(@NotNull World world, double x, double y, double z) {
return HolographicDisplaysAPIProvider.getImplementation().createPosition(world, x, y, z);
}
+ /**
+ * Returns the position with the given world and coordinates.
+ *
+ * @param worldName the name of the world
+ * @param x the X coordinate
+ * @param y the Y coordinate
+ * @param z the Z coordinate
+ * @return the created position
+ * @since 1
+ */
static @NotNull Position of(@NotNull String worldName, double x, double y, double z) {
return HolographicDisplaysAPIProvider.getImplementation().createPosition(worldName, x, y, z);
}
+ /**
+ * Returns the position from a Location.
+ *
+ * @param location the location from which to obtain the position
+ * @return the created position
+ * @since 1
+ */
static @NotNull Position of(@NotNull Location location) {
return HolographicDisplaysAPIProvider.getImplementation().getPosition(location);
}
+ /**
+ * Returns the position of an entity.
+ *
+ * @param entity the entity from which to obtain the position
+ * @return the created position
+ * @since 1
+ */
static @NotNull Position of(@NotNull Entity entity) {
return HolographicDisplaysAPIProvider.getImplementation().getPosition(entity);
}
+ /**
+ * Returns the position of a block.
+ *
+ * @param block the block from which to obtain the position
+ * @return the created position
+ * @since 1
+ */
static @NotNull Position of(@NotNull Block block) {
return HolographicDisplaysAPIProvider.getImplementation().getPosition(block);
}
+ /**
+ * Returns the name of the world of this position.
+ *
+ * @return the world name
+ * @since 1
+ */
@NotNull String getWorldName();
+ /**
+ * Returns the X coordinate of this position.
+ *
+ * @return the X coordinate
+ * @since 1
+ */
double getX();
+ /**
+ * Returns the Y coordinate of this position.
+ *
+ * @return the Y coordinate
+ * @since 1
+ */
double getY();
+ /**
+ * Returns the Z coordinate of this position.
+ *
+ * @return the Z coordinate
+ * @since 1
+ */
double getZ();
+ /**
+ * Returns the loaded world of this position or null if it's not loaded.
+ *
+ * @return the loaded world or null if not loaded
+ * @since 1
+ */
@Nullable World getWorldIfLoaded();
+ /**
+ * Returns if this position is in the same world of another position.
+ *
+ * @param position the position to compare
+ * @return true if the world is the same, false otherwise
+ * @since 1
+ */
boolean isInSameWorld(@NotNull Position position);
+ /**
+ * Returns if this position is in the same world of a Location.
+ *
+ * @param location the location to compare
+ * @return true if the world is the same, false otherwise
+ * @since 1
+ */
boolean isInSameWorld(@NotNull Location location);
+ /**
+ * Returns if this position is in the same world of an entity.
+ *
+ * @param entity the entity to compare
+ * @return true if the world is the same, false otherwise
+ * @since 1
+ */
boolean isInSameWorld(@NotNull Entity entity);
+ /**
+ * Returns if this position is in the given world.
+ *
+ * @param world the world to compare
+ * @return true if the world matches, false otherwise
+ * @since 1
+ */
boolean isInWorld(@Nullable World world);
+ /**
+ * Returns if this position is in the given world name.
+ *
+ * @param worldName the world name to compare
+ * @return true if the world name matches, false otherwise
+ * @since 1
+ */
boolean isInWorld(@Nullable String worldName);
+ /**
+ * Returns the X coordinate of the block in this position.
+ *
+ * @return the block's X coordinate
+ * @since 1
+ */
int getBlockX();
+ /**
+ * Returns the Y coordinate of the block in this position.
+ *
+ * @return the block's Y coordinate
+ * @since 1
+ */
int getBlockY();
+ /**
+ * Returns the Z coordinate of the block in this position.
+ *
+ * @return the block's Z coordinate
+ * @since 1
+ */
int getBlockZ();
+ /**
+ * Returns a new position made by adding the given lengths to each coordinate.
+ *
+ * @param x the length to add to the X coordinate
+ * @param y the length to add to the Y coordinate
+ * @param z the length to add to the Z coordinate
+ * @since 1
+ */
@NotNull Position add(double x, double y, double z);
+ /**
+ * Returns a new position made by subtracting the given lengths from each coordinate.
+ *
+ * @param x the length to subtract from the X coordinate
+ * @param y the length to subtract from the Y coordinate
+ * @param z the length to subtract from the Z coordinate
+ * @since 1
+ */
@NotNull Position subtract(double x, double y, double z);
+ /**
+ * Returns the distance between this position and another position. Avoid repeatedly calling this method as it uses
+ * a costly square-root function, or consider using {@link #distanceSquared(Position)} instead.
+ *
+ * @param position the position from which to measure the distance
+ * @return the distance from the other position
+ * @since 1
+ */
double distance(@NotNull Position position);
+ /**
+ * Returns the distance between this position and a Location. Avoid repeatedly calling this method as it uses
+ * a costly square-root function, or consider using {@link #distanceSquared(Location)} instead.
+ *
+ * @param location the location from which to measure the distance
+ * @return the distance from the Location
+ * @since 1
+ */
double distance(@NotNull Location location);
+ /**
+ * Returns the distance between this position and an entity. Avoid repeatedly calling this method as it uses
+ * a costly square-root function, or consider using {@link #distanceSquared(Entity)} instead.
+ *
+ * @param entity the entity from which to measure the distance
+ * @return the distance from the entity
+ * @since 1
+ */
double distance(@NotNull Entity entity);
+ /**
+ * Returns the squared distance between this position and another position.
+ *
+ * @param position the position from which to measure the distance
+ * @return the squared distance from the other position
+ * @since 1
+ */
double distanceSquared(@NotNull Position position);
+ /**
+ * Returns the squared distance between this position and a Location.
+ *
+ * @param location the location from which to measure the distance
+ * @return the squared distance from the Location
+ * @since 1
+ */
double distanceSquared(@NotNull Location location);
+ /**
+ * Returns the squared distance between this position and an entity.
+ *
+ * @param entity the entity from which to measure the distance
+ * @return the squared distance from the entity
+ * @since 1
+ */
double distanceSquared(@NotNull Entity entity);
+ /**
+ * Returns a new Location derived from this position. Warning: if the world is not loaded, the Location will
+ * contain a null {@link World}, which can lead to unexpected errors.
+ *
+ * @return A new Location based on this position
+ * @since 1
+ */
@NotNull Location toLocation();
+ /**
+ * Returns a new Vector derived from this position.
+ *
+ * @return a new Vector based on this position
+ * @since 1
+ */
@NotNull Vector toVector();
}
diff --git a/api/src/main/java/me/filoghost/holographicdisplays/api/hologram/Hologram.java b/api/src/main/java/me/filoghost/holographicdisplays/api/hologram/Hologram.java
index a0654ff8..a1bdfed1 100644
--- a/api/src/main/java/me/filoghost/holographicdisplays/api/hologram/Hologram.java
+++ b/api/src/main/java/me/filoghost/holographicdisplays/api/hologram/Hologram.java
@@ -12,24 +12,27 @@ import org.bukkit.World;
import org.jetbrains.annotations.NotNull;
/**
- * Entity to manage a group of vertically aligned lines, which display floating text and items.
- * To create one see {@link HolographicDisplaysAPI}.
+ * Group of one or more vertically aligned lines which appear as floating text lines and items. To create one see
+ * {@link HolographicDisplaysAPI#createHologram(Position)}.
+ *
+ * The lines are displayed in a top to bottom order starting from the hologram position and going down.
*
* @since 1
*/
public interface Hologram {
/**
- * Returns the editable list of lines.
+ * Returns the editable lines of this hologram.
*
+ * @return the editable lines
* @since 1
*/
@NotNull HologramLines getLines();
/**
- * Returns the {@link VisibilitySettings} of this hologram.
+ * Returns the visibility settings.
*
- * @return the VisibilitySettings of this hologram
+ * @return the visibility settings
* @since 1
*/
@NotNull VisibilitySettings getVisibilitySettings();
@@ -53,7 +56,7 @@ public interface Hologram {
/**
* Moves the hologram to the given position.
*
- * @param worldName the world name where the hologram should be moved
+ * @param worldName the name of the world where the hologram should be moved
* @param x the X coordinate
* @param y the Y coordinate
* @param z the Z coordinate
@@ -81,28 +84,33 @@ public interface Hologram {
void setPosition(@NotNull Location location);
/**
+ * Returns the placeholder setting.
+ *
+ * @return the placeholder setting
* @since 1
*/
@NotNull PlaceholderSetting getPlaceholderSetting();
/**
+ * Changes the placeholder setting.
+ *
+ * @param placeholderSetting the new placeholder setting
* @since 1
*/
void setPlaceholderSetting(@NotNull PlaceholderSetting placeholderSetting);
/**
- * Deletes this hologram. Editing or teleporting the hologram when deleted
- * will throw an exception. Lines will be automatically cleared.
- * You should remove all the references of the hologram after deletion.
+ * Deletes this hologram, clearing the lines. Editing or teleporting the hologram after deleting it throws an
+ * exception. A deleted hologram should no longer be referenced.
*
* @since 1
*/
void delete();
/**
- * Checks if a hologram was deleted.
+ * Returns if this hologram is deleted.
*
- * @return true if this hologram was deleted
+ * @return true if this hologram is deleted
* @since 1
*/
boolean isDeleted();
diff --git a/api/src/main/java/me/filoghost/holographicdisplays/api/hologram/HologramLines.java b/api/src/main/java/me/filoghost/holographicdisplays/api/hologram/HologramLines.java
index f275f102..5067175f 100644
--- a/api/src/main/java/me/filoghost/holographicdisplays/api/hologram/HologramLines.java
+++ b/api/src/main/java/me/filoghost/holographicdisplays/api/hologram/HologramLines.java
@@ -13,14 +13,15 @@ import org.jetbrains.annotations.NotNull;
import org.jetbrains.annotations.Nullable;
/**
- * The editable list of lines of a hologram.
+ * The editable lines of a hologram, following a top to bottom order (first line is top one, last line is the bottom
+ * one).
*
* @since 1
*/
public interface HologramLines {
/**
- * Adds a new text line at the end.
+ * Adds a new text line at the bottom.
*
* @param text the content of the line, see {@link TextHologramLine#setText(String)}
* @return the created line
@@ -29,7 +30,7 @@ public interface HologramLines {
@NotNull TextHologramLine appendText(@Nullable String text);
/**
- * Adds a new item line at the end.
+ * Adds a new item line at the bottom.
*
* @param itemStack the content of the line, see {@link ItemHologramLine#setItemStack(ItemStack)}
* @return the created line
@@ -38,9 +39,9 @@ public interface HologramLines {
@NotNull ItemHologramLine appendItem(@Nullable ItemStack itemStack);
/**
- * Inserts a new text line before the given index.
+ * Inserts a new text line before the line at the given index, shifting all the lines below.
*
- * @param beforeIndex the index before which the line is inserted, 0 to insert as first
+ * @param beforeIndex the index before which the line should be inserted, 0 to insert on top
* @param text the content of the line, see {@link TextHologramLine#setText(String)}
* @return the created line
* @throws IndexOutOfBoundsException if the index is out of range (index < 0 || index >= size())
@@ -49,9 +50,9 @@ public interface HologramLines {
@NotNull TextHologramLine insertText(int beforeIndex, @Nullable String text);
/**
- * Inserts a new item line before the given index.
+ * Inserts a new item line before the line at the given index, shifting all the lines below.
*
- * @param beforeIndex the index before which the line is inserted, 0 to insert as first
+ * @param beforeIndex the index before which the line should be inserted, 0 to insert on top
* @param itemStack the content of the line, see {@link ItemHologramLine#setItemStack(ItemStack)}
* @return the created line
* @throws IndexOutOfBoundsException if the index is out of range (index < 0 || index >= size())
@@ -95,15 +96,15 @@ public interface HologramLines {
void clear();
/**
- * Returns the amount of lines.
+ * Returns the current amount of lines.
*
- * @return the amount of lines
+ * @return the current amount of lines
* @since 1
*/
int size();
/**
- * The total height of the lines, including the gaps between them.
+ * The total height in blocks occupied by the lines, including the gaps between them.
*
* @return the total height of the lines
* @since 1
diff --git a/api/src/main/java/me/filoghost/holographicdisplays/api/hologram/PlaceholderSetting.java b/api/src/main/java/me/filoghost/holographicdisplays/api/hologram/PlaceholderSetting.java
index 975a7488..905f1398 100644
--- a/api/src/main/java/me/filoghost/holographicdisplays/api/hologram/PlaceholderSetting.java
+++ b/api/src/main/java/me/filoghost/holographicdisplays/api/hologram/PlaceholderSetting.java
@@ -5,10 +5,33 @@
*/
package me.filoghost.holographicdisplays.api.hologram;
+/**
+ * The option to enable or disable placeholders inside the text lines of hologram.
+ *
+ * @see Hologram#setPlaceholderSetting(PlaceholderSetting)
+ * @since 1
+ */
public enum PlaceholderSetting {
+ /**
+ * The default setting for placeholders (which is currently equivalent to {@link #DISABLE_ALL}).
+ *
+ * @since 1
+ */
DEFAULT,
+
+ /**
+ * Enable all placeholders.
+ *
+ * @since 1
+ */
ENABLE_ALL,
+
+ /**
+ * Disable all placeholders.
+ *
+ * @since 1
+ */
DISABLE_ALL
}
diff --git a/api/src/main/java/me/filoghost/holographicdisplays/api/hologram/VisibilitySettings.java b/api/src/main/java/me/filoghost/holographicdisplays/api/hologram/VisibilitySettings.java
index 3bb40c8d..2b21a834 100644
--- a/api/src/main/java/me/filoghost/holographicdisplays/api/hologram/VisibilitySettings.java
+++ b/api/src/main/java/me/filoghost/holographicdisplays/api/hologram/VisibilitySettings.java
@@ -9,7 +9,7 @@ import org.bukkit.entity.Player;
import org.jetbrains.annotations.NotNull;
/**
- * Settings to manage the visibility of a hologram to players. Allows to set a global visibility and an individual
+ * Settings to manage the visibility of a hologram to players. Allows to set both a global visibility and an individual
* visibility for specific players.
*
* @since 1
@@ -17,7 +17,10 @@ import org.jetbrains.annotations.NotNull;
public interface VisibilitySettings {
/**
- * Returns the visibility of the hologram. The initial value is {@link Visibility#VISIBLE}.
+ * Returns the global visibility. This value only affects player which do not have an individual visibility (see
+ * {@link #setIndividualVisibility(Player, Visibility)}).
+ *
+ * The initial value is {@link Visibility#VISIBLE}, which means that all players can see the hologram.
*
* @return the visibility
* @since 1
@@ -25,8 +28,8 @@ public interface VisibilitySettings {
@NotNull Visibility getGlobalVisibility();
/**
- * Sets the visibility of the hologram. This value only affects player which do not have an individual visibility
- * (see {@link #setIndividualVisibility(Player, Visibility)}).
+ * Sets the global visibility. This value only affects player which do not have an individual visibility (see
+ * {@link #setIndividualVisibility(Player, Visibility)}).
*
* @param visibility the new visibility
* @since 1
@@ -34,15 +37,16 @@ public interface VisibilitySettings {
void setGlobalVisibility(@NotNull Visibility visibility);
/**
- * Sets the visibility for a specific player, overriding the global value of ({@link #getGlobalVisibility()}).
- * The individual visibility value can be removed with {@link #removeIndividualVisibility(Player)}.
+ * Sets the visibility for a specific player, with precedence over the global visibility
+ * ({@link #getGlobalVisibility()}). The individual visibility value can be removed with
+ * {@link #removeIndividualVisibility(Player)}.
*
* @since 1
*/
void setIndividualVisibility(@NotNull Player player, @NotNull Visibility visibility);
/**
- * Removes the individual visibility for a player. The visibility for the player would then be determined by the
+ * Removes the individual visibility for a player. The visibility for the player will then be determined by the
* global visibility ({@link #getGlobalVisibility()}).
*
* @since 1
@@ -50,7 +54,8 @@ public interface VisibilitySettings {
void removeIndividualVisibility(@NotNull Player player);
/**
- * Removes the individual visibility of all players which have one.
+ * Removes the individual visibility for all players. The visibility for all players will then be determined by the
+ * global visibility ({@link #getGlobalVisibility()}).
*
* @since 1
*/
@@ -58,7 +63,7 @@ public interface VisibilitySettings {
/**
* Checks if a hologram is visible to a player, taking into account both the global visibility and the individual
- * visibility of the player (if set).
+ * visibility for the player (if set).
*
* @param player the player
* @return if the player can see the hologram
@@ -68,11 +73,24 @@ public interface VisibilitySettings {
/**
- * The available statuses for the visibility of a hologram.
+ * The visibility status of a hologram, which can be set both globally and for individual players.
+ *
+ * @since 1
*/
enum Visibility {
+ /**
+ * The hologram is visible.
+ *
+ * @since 1
+ */
VISIBLE,
+
+ /**
+ * The hologram is not visible.
+ *
+ * @since 1
+ */
HIDDEN
}
diff --git a/api/src/main/java/me/filoghost/holographicdisplays/api/hologram/line/ClickableHologramLine.java b/api/src/main/java/me/filoghost/holographicdisplays/api/hologram/line/ClickableHologramLine.java
index d0f4263b..b063d17f 100644
--- a/api/src/main/java/me/filoghost/holographicdisplays/api/hologram/line/ClickableHologramLine.java
+++ b/api/src/main/java/me/filoghost/holographicdisplays/api/hologram/line/ClickableHologramLine.java
@@ -8,7 +8,8 @@ package me.filoghost.holographicdisplays.api.hologram.line;
import org.jetbrains.annotations.Nullable;
/**
- * A hologram line that can be clicked (left or right click).
+ * A hologram line that can be left-clicked or right-click. Currently, both {@link TextHologramLine} and
+ * {@link ItemHologramLine} are clickable.
*
* @since 1
*/
@@ -17,7 +18,7 @@ public interface ClickableHologramLine extends HologramLine {
/**
* Returns the current click listener.
*
- * @return the current click listener, null if not present
+ * @return the current click listener, null if absent
* @since 1
*/
@Nullable HologramLineClickListener getClickListener();
@@ -25,7 +26,7 @@ public interface ClickableHologramLine extends HologramLine {
/**
* Sets the click listener.
*
- * @param clickListener the new click listener, null to unset
+ * @param clickListener the new click listener, null to remove it
* @since 1
*/
void setClickListener(@Nullable HologramLineClickListener clickListener);
diff --git a/api/src/main/java/me/filoghost/holographicdisplays/api/hologram/line/HologramLine.java b/api/src/main/java/me/filoghost/holographicdisplays/api/hologram/line/HologramLine.java
index 7fe7a371..1e8cdec6 100644
--- a/api/src/main/java/me/filoghost/holographicdisplays/api/hologram/line/HologramLine.java
+++ b/api/src/main/java/me/filoghost/holographicdisplays/api/hologram/line/HologramLine.java
@@ -6,8 +6,10 @@
package me.filoghost.holographicdisplays.api.hologram.line;
/**
- * Interface to represent a line in a Hologram.
+ * A line of a hologram.
*
+ * @see TextHologramLine
+ * @see ItemHologramLine
* @since 1
*/
public interface HologramLine {
diff --git a/api/src/main/java/me/filoghost/holographicdisplays/api/hologram/line/HologramLineClickEvent.java b/api/src/main/java/me/filoghost/holographicdisplays/api/hologram/line/HologramLineClickEvent.java
index 23dcc42d..b8cdfe20 100644
--- a/api/src/main/java/me/filoghost/holographicdisplays/api/hologram/line/HologramLineClickEvent.java
+++ b/api/src/main/java/me/filoghost/holographicdisplays/api/hologram/line/HologramLineClickEvent.java
@@ -7,8 +7,22 @@ package me.filoghost.holographicdisplays.api.hologram.line;
import org.bukkit.entity.Player;
+/**
+ * The event of a player clicking on a {@link ClickableHologramLine}.
+ *
+ * This is not a Bukkit event, the listener must be set with
+ * {@link ClickableHologramLine#setClickListener(HologramLineClickListener)}.
+ *
+ * @since 1
+ */
public interface HologramLineClickEvent {
+ /**
+ * Returns the player who clicked on the line.
+ *
+ * @return the player who clicked
+ * @since 1
+ */
Player getPlayer();
}
diff --git a/api/src/main/java/me/filoghost/holographicdisplays/api/hologram/line/HologramLineClickListener.java b/api/src/main/java/me/filoghost/holographicdisplays/api/hologram/line/HologramLineClickListener.java
index bbdd4992..523c984d 100644
--- a/api/src/main/java/me/filoghost/holographicdisplays/api/hologram/line/HologramLineClickListener.java
+++ b/api/src/main/java/me/filoghost/holographicdisplays/api/hologram/line/HologramLineClickListener.java
@@ -8,7 +8,10 @@ package me.filoghost.holographicdisplays.api.hologram.line;
import org.jetbrains.annotations.NotNull;
/**
- * Interface to handle clickable hologram lines.
+ * The listener class for {@link HologramLineClickEvent}.
+ *
+ * This is not a Bukkit listener, it must be set with
+ * {@link ClickableHologramLine#setClickListener(HologramLineClickListener)}.
*
* @since 1
*/
@@ -16,6 +19,9 @@ import org.jetbrains.annotations.NotNull;
public interface HologramLineClickListener {
/**
+ * Invoked when a player clicks on the clickable line.
+ *
+ * @param clickEvent the event data
* @since 1
*/
void onClick(@NotNull HologramLineClickEvent clickEvent);
diff --git a/api/src/main/java/me/filoghost/holographicdisplays/api/hologram/line/HologramLinePickupEvent.java b/api/src/main/java/me/filoghost/holographicdisplays/api/hologram/line/HologramLinePickupEvent.java
index 7c056715..409e7838 100644
--- a/api/src/main/java/me/filoghost/holographicdisplays/api/hologram/line/HologramLinePickupEvent.java
+++ b/api/src/main/java/me/filoghost/holographicdisplays/api/hologram/line/HologramLinePickupEvent.java
@@ -7,8 +7,22 @@ package me.filoghost.holographicdisplays.api.hologram.line;
import org.bukkit.entity.Player;
+/**
+ * The event of a player being in pickup range of an {@link ItemHologramLine}.
+ *
+ * This is not a Bukkit event, the listener must be set with
+ * {@link ItemHologramLine#setPickupListener(HologramLinePickupListener)}.
+ *
+ * @since 1
+ */
public interface HologramLinePickupEvent {
+ /**
+ * Returns the player being in pickup range of the item line.
+ *
+ * @return the player in pickup range of the item line
+ * @since 1
+ */
Player getPlayer();
}
diff --git a/api/src/main/java/me/filoghost/holographicdisplays/api/hologram/line/HologramLinePickupListener.java b/api/src/main/java/me/filoghost/holographicdisplays/api/hologram/line/HologramLinePickupListener.java
index 6b12c7e6..d8ef706d 100644
--- a/api/src/main/java/me/filoghost/holographicdisplays/api/hologram/line/HologramLinePickupListener.java
+++ b/api/src/main/java/me/filoghost/holographicdisplays/api/hologram/line/HologramLinePickupListener.java
@@ -8,7 +8,10 @@ package me.filoghost.holographicdisplays.api.hologram.line;
import org.jetbrains.annotations.NotNull;
/**
- * Interface to handle hologram lines being picked up by players.
+ * The listener class for {@link HologramLinePickupEvent}.
+ *
+ * This is not a Bukkit listener, it must be set with
+ * {@link ItemHologramLine#setPickupListener(HologramLinePickupListener)}.
*
* @since 1
*/
@@ -16,6 +19,11 @@ import org.jetbrains.annotations.NotNull;
public interface HologramLinePickupListener {
/**
+ * Invoked when a player is being in pickup range of the item line. Note that this method is invoked repeatedly
+ * every tick until the player moves out of range, the listener is removed, the item line is no longer visible to
+ * the player, or the item line is removed.
+ *
+ * @param pickupEvent the event data
* @since 1
*/
void onPickup(@NotNull HologramLinePickupEvent pickupEvent);
diff --git a/api/src/main/java/me/filoghost/holographicdisplays/api/hologram/line/ItemHologramLine.java b/api/src/main/java/me/filoghost/holographicdisplays/api/hologram/line/ItemHologramLine.java
index d9c5b335..88862f11 100644
--- a/api/src/main/java/me/filoghost/holographicdisplays/api/hologram/line/ItemHologramLine.java
+++ b/api/src/main/java/me/filoghost/holographicdisplays/api/hologram/line/ItemHologramLine.java
@@ -9,22 +9,24 @@ import org.bukkit.inventory.ItemStack;
import org.jetbrains.annotations.Nullable;
/**
+ * A hologram line displaying an item.
+ *
* @since 1
*/
public interface ItemHologramLine extends ClickableHologramLine {
/**
- * Returns the ItemStack of this ItemLine.
+ * Returns the currently displayed item.
*
- * @return the ItemStack if this ItemLine.
+ * @return the current item
* @since 1
*/
@Nullable ItemStack getItemStack();
/**
- * Sets the ItemStack for this ItemLine.
+ * Sets the displayed item.
*
- * @param itemStack the new item, should not be null.
+ * @param itemStack the new item, null to display air
* @since 1
*/
void setItemStack(@Nullable ItemStack itemStack);
@@ -32,7 +34,7 @@ public interface ItemHologramLine extends ClickableHologramLine {
/**
* Returns the current pickup listener.
*
- * @return the current pickup listener, null if not present
+ * @return the current pickup listener, null if absent
* @since 1
*/
@Nullable HologramLinePickupListener getPickupListener();
@@ -40,7 +42,7 @@ public interface ItemHologramLine extends ClickableHologramLine {
/**
* Sets the pickup listener.
*
- * @param pickupListener the new pickup listener, null to unset
+ * @param pickupListener the new pickup listener, null to remove it
* @since 1
*/
void setPickupListener(@Nullable HologramLinePickupListener pickupListener);
diff --git a/api/src/main/java/me/filoghost/holographicdisplays/api/hologram/line/TextHologramLine.java b/api/src/main/java/me/filoghost/holographicdisplays/api/hologram/line/TextHologramLine.java
index a88c792f..87f65c5a 100644
--- a/api/src/main/java/me/filoghost/holographicdisplays/api/hologram/line/TextHologramLine.java
+++ b/api/src/main/java/me/filoghost/holographicdisplays/api/hologram/line/TextHologramLine.java
@@ -8,6 +8,8 @@ package me.filoghost.holographicdisplays.api.hologram.line;
import org.jetbrains.annotations.Nullable;
/**
+ * A hologram line displaying text.
+ *
* @since 1
*/
public interface TextHologramLine extends ClickableHologramLine {
@@ -15,7 +17,7 @@ public interface TextHologramLine extends ClickableHologramLine {
/**
* Returns the currently displayed text.
*
- * @return the currently displayed text.
+ * @return the current text
* @since 1
*/
@Nullable String getText();
@@ -23,7 +25,7 @@ public interface TextHologramLine extends ClickableHologramLine {
/**
* Sets the displayed text.
*
- * @param text the new displayed text.
+ * @param text the new text
* @since 1
*/
void setText(@Nullable String text);
diff --git a/api/src/main/java/me/filoghost/holographicdisplays/api/internal/HolographicDisplaysAPIProvider.java b/api/src/main/java/me/filoghost/holographicdisplays/api/internal/HolographicDisplaysAPIProvider.java
index 47958ae7..36a9768d 100644
--- a/api/src/main/java/me/filoghost/holographicdisplays/api/internal/HolographicDisplaysAPIProvider.java
+++ b/api/src/main/java/me/filoghost/holographicdisplays/api/internal/HolographicDisplaysAPIProvider.java
@@ -14,6 +14,9 @@ import org.bukkit.entity.Entity;
import org.bukkit.plugin.Plugin;
import org.jetbrains.annotations.ApiStatus.Internal;
+/**
+ * This class is used internally and can change without notice, do not use it.
+ */
@Internal
public abstract class HolographicDisplaysAPIProvider {
diff --git a/api/src/main/java/me/filoghost/holographicdisplays/api/placeholder/GlobalPlaceholder.java b/api/src/main/java/me/filoghost/holographicdisplays/api/placeholder/GlobalPlaceholder.java
index 725e52a2..2f766974 100644
--- a/api/src/main/java/me/filoghost/holographicdisplays/api/placeholder/GlobalPlaceholder.java
+++ b/api/src/main/java/me/filoghost/holographicdisplays/api/placeholder/GlobalPlaceholder.java
@@ -8,18 +8,25 @@ package me.filoghost.holographicdisplays.api.placeholder;
import org.jetbrains.annotations.Nullable;
/**
+ * A global placeholder that displays the same text to all players. See {@link Placeholder} for general information
+ * about placeholders.
+ *
* @since 1
*/
public interface GlobalPlaceholder extends Placeholder {
/**
- * Callback for providing a placeholder replacement, given the argument of the placeholder (if present).
+ * Callback for providing a placeholder replacement for a given optional argument. The same replacement is shown to
+ * all players.
*
- * For example, the argument of {test} is null, the argument of {test: hello world} is the string "hello world".
+ * The argument is provided through the placeholder text: for example, the argument of {test} is null, the argument
+ * of {test: hello world} is the string "hello world".
*
- * Warning: this method should be performance efficient, as it may be invoked often.
+ * Warning: the implementation should be performance efficient, as it may be invoked often depending on the
+ * refresh interval of the placeholder.
*
- * @return the placeholder replacement
+ * @param argument the optional placeholder argument, null if not specified
+ * @return the optional placeholder replacement, null to leave the placeholder unreplaced
* @since 1
*/
@Nullable String getReplacement(@Nullable String argument);
diff --git a/api/src/main/java/me/filoghost/holographicdisplays/api/placeholder/GlobalPlaceholderFactory.java b/api/src/main/java/me/filoghost/holographicdisplays/api/placeholder/GlobalPlaceholderFactory.java
index f78c76ae..ffef9c05 100644
--- a/api/src/main/java/me/filoghost/holographicdisplays/api/placeholder/GlobalPlaceholderFactory.java
+++ b/api/src/main/java/me/filoghost/holographicdisplays/api/placeholder/GlobalPlaceholderFactory.java
@@ -8,11 +8,25 @@ package me.filoghost.holographicdisplays.api.placeholder;
import org.jetbrains.annotations.Nullable;
/**
+ * Advanced class to create separate {@link GlobalPlaceholder} instances depending on the placeholder argument, instead
+ * of providing a single one when registering the placeholder.
+ *
+ * This is mostly used for performance reasons, to parse the argument only when necessary, instead of doing it every
+ * time the method {@link GlobalPlaceholder#getReplacement(String)} is invoked. For example, the argument might consist
+ * of multiple comma-separated values, be a JSON string, or require a regular expression to parse it.
+ *
+ * Another less common use case is to keep a separate internal state for each different argument.
+ *
* @since 1
*/
public interface GlobalPlaceholderFactory {
/**
+ * Returns the placeholder instance to provide the replacement for the given argument. This method might be invoked
+ * again for the same argument if the placeholder is temporarily unused (not displayed to any player).
+ *
+ * @param argument the argument for which the placeholder instance will provide the replacement
+ * @return the placeholder instance
* @since 1
*/
@Nullable GlobalPlaceholder getPlaceholder(@Nullable String argument);
diff --git a/api/src/main/java/me/filoghost/holographicdisplays/api/placeholder/GlobalPlaceholderReplaceFunction.java b/api/src/main/java/me/filoghost/holographicdisplays/api/placeholder/GlobalPlaceholderReplaceFunction.java
index 0693ee0b..af502dc6 100644
--- a/api/src/main/java/me/filoghost/holographicdisplays/api/placeholder/GlobalPlaceholderReplaceFunction.java
+++ b/api/src/main/java/me/filoghost/holographicdisplays/api/placeholder/GlobalPlaceholderReplaceFunction.java
@@ -5,10 +5,14 @@
*/
package me.filoghost.holographicdisplays.api.placeholder;
+import me.filoghost.holographicdisplays.api.HolographicDisplaysAPI;
import org.jetbrains.annotations.Nullable;
/**
- * Simple callback to provide a placeholder replacement.
+ * Simplified version of {@link GlobalPlaceholder} where the refresh interval in ticks is passed through the
+ * registration method
+ * {@link HolographicDisplaysAPI#registerGlobalPlaceholder(String, int, GlobalPlaceholderReplaceFunction)} as a
+ * constant.
*
* @since 1
*/
@@ -16,7 +20,7 @@ import org.jetbrains.annotations.Nullable;
public interface GlobalPlaceholderReplaceFunction {
/**
- * @see GlobalPlaceholder#getReplacement(String)
+ * Same as {@link GlobalPlaceholder#getReplacement(String)}.
*
* @since 1
*/
diff --git a/api/src/main/java/me/filoghost/holographicdisplays/api/placeholder/IndividualPlaceholder.java b/api/src/main/java/me/filoghost/holographicdisplays/api/placeholder/IndividualPlaceholder.java
index 1ce6f15a..6011a283 100644
--- a/api/src/main/java/me/filoghost/holographicdisplays/api/placeholder/IndividualPlaceholder.java
+++ b/api/src/main/java/me/filoghost/holographicdisplays/api/placeholder/IndividualPlaceholder.java
@@ -10,11 +10,26 @@ import org.jetbrains.annotations.NotNull;
import org.jetbrains.annotations.Nullable;
/**
+ * An individual placeholder that can display a different text to each player. See {@link Placeholder} for general
+ * information about placeholders.
+ *
* @since 1
*/
public interface IndividualPlaceholder extends Placeholder {
/**
+ * Callback for providing a placeholder replacement for a given player and an optional argument. A different
+ * replacement can be shown to each player.
+ *
+ * The argument is provided through the placeholder text: for example, the argument of {test} is null, the argument
+ * of {test: hello world} is the string "hello world".
+ *
+ * Warning: the implementation should be performance efficient, as it may be invoked often depending on the
+ * refresh interval of the placeholder and the number of players viewing the hologram.
+ *
+ * @param player the player that will see the provided replacement
+ * @param argument the optional placeholder argument, null if not specified
+ * @return the optional placeholder replacement, null to leave the placeholder unreplaced
* @since 1
*/
@Nullable String getReplacement(@NotNull Player player, @Nullable String argument);
diff --git a/api/src/main/java/me/filoghost/holographicdisplays/api/placeholder/IndividualPlaceholderFactory.java b/api/src/main/java/me/filoghost/holographicdisplays/api/placeholder/IndividualPlaceholderFactory.java
index 21baebad..060ee9d9 100644
--- a/api/src/main/java/me/filoghost/holographicdisplays/api/placeholder/IndividualPlaceholderFactory.java
+++ b/api/src/main/java/me/filoghost/holographicdisplays/api/placeholder/IndividualPlaceholderFactory.java
@@ -5,14 +5,29 @@
*/
package me.filoghost.holographicdisplays.api.placeholder;
+import org.bukkit.entity.Player;
import org.jetbrains.annotations.Nullable;
/**
+ * Advanced class to create separate {@link IndividualPlaceholder} instances depending on the placeholder argument,
+ * instead of providing a single one when registering the placeholder.
+ *
+ * This is mostly used for performance reasons, to parse the argument only when necessary, instead of doing it every
+ * time the method {@link IndividualPlaceholder#getReplacement(Player, String)} is invoked. For example, the argument
+ * might consist of multiple comma-separated values, be a JSON string, or require a regular expression to parse it.
+ *
+ * Another less common use case is to keep a separate internal state for each different argument.
+ *
* @since 1
*/
public interface IndividualPlaceholderFactory {
/**
+ * Returns the placeholder instance to provide the replacement for the given argument. This method might be invoked
+ * again for the same argument if the placeholder is temporarily unused (not displayed to any player).
+ *
+ * @param argument the argument for which the placeholder instance will provide the replacement
+ * @return the placeholder instance
* @since 1
*/
@Nullable IndividualPlaceholder getPlaceholder(@Nullable String argument);
diff --git a/api/src/main/java/me/filoghost/holographicdisplays/api/placeholder/IndividualPlaceholderReplaceFunction.java b/api/src/main/java/me/filoghost/holographicdisplays/api/placeholder/IndividualPlaceholderReplaceFunction.java
index ea0eb1b7..c9f7d2ad 100644
--- a/api/src/main/java/me/filoghost/holographicdisplays/api/placeholder/IndividualPlaceholderReplaceFunction.java
+++ b/api/src/main/java/me/filoghost/holographicdisplays/api/placeholder/IndividualPlaceholderReplaceFunction.java
@@ -5,18 +5,24 @@
*/
package me.filoghost.holographicdisplays.api.placeholder;
+import me.filoghost.holographicdisplays.api.HolographicDisplaysAPI;
import org.bukkit.entity.Player;
import org.jetbrains.annotations.NotNull;
import org.jetbrains.annotations.Nullable;
/**
+ * Simplified version of {@link IndividualPlaceholder} where the refresh interval in ticks is passed through the
+ * registration method
+ * {@link HolographicDisplaysAPI#registerIndividualPlaceholder(String, int, IndividualPlaceholderReplaceFunction)} as a
+ * constant.
+ *
* @since 1
*/
@FunctionalInterface
public interface IndividualPlaceholderReplaceFunction {
/**
- * @see IndividualPlaceholder#getReplacement(Player, String)
+ * Same as {@link IndividualPlaceholder#getReplacement(Player, String)}.
*
* @since 1
*/
diff --git a/api/src/main/java/me/filoghost/holographicdisplays/api/placeholder/Placeholder.java b/api/src/main/java/me/filoghost/holographicdisplays/api/placeholder/Placeholder.java
index 625d9cec..35151454 100644
--- a/api/src/main/java/me/filoghost/holographicdisplays/api/placeholder/Placeholder.java
+++ b/api/src/main/java/me/filoghost/holographicdisplays/api/placeholder/Placeholder.java
@@ -5,9 +5,50 @@
*/
package me.filoghost.holographicdisplays.api.placeholder;
+import me.filoghost.holographicdisplays.api.HolographicDisplaysAPI;
+import me.filoghost.holographicdisplays.api.hologram.Hologram;
+import me.filoghost.holographicdisplays.api.hologram.PlaceholderSetting;
+
+/**
+ * A placeholder is a dynamic text value that can be displayed in a text hologram line.
+ *
+ * Placeholders can be global (show the same text to all players) or individual (show a different text to each player).
+ * Global placeholders are preferable when possible, as individual placeholders have a higher performance impact.
+ *
+ * To add a placeholder a class must implement either {@link GlobalPlaceholder} or {@link IndividualPlaceholder}, then
+ * it must be registered with {@link HolographicDisplaysAPI#registerGlobalPlaceholder(String, GlobalPlaceholder)} or
+ * {@link HolographicDisplaysAPI#registerIndividualPlaceholder(String, IndividualPlaceholder)} by providing an
+ * identifier string.
+ *
+ * The valid formats to display the placeholder inside a text line are:
+ *
+ * The parts of the placeholder format are:
+ *
+ * Placeholders are disabled by default and need to be enabled with
+ * {@link Hologram#setPlaceholderSetting(PlaceholderSetting)}.
+ *
+ * @since 1
+ */
public interface Placeholder {
/**
+ * Returns the minimum interval in ticks between invocations of the replacement callback. For individual
+ * placeholders the interval is counted separately for each player.
+ *
+ * Note that more ticks can pass between invocations if no player is near, do not use the replacement callback as a
+ * timer.
+ *
* @since 1
*/
int getRefreshIntervalTicks();
+ *
+ *
+ *
+ *