API V3

.github/workflows/build.yml

@@ -12,10 +12,10 @@ jobs:
 
     steps:
       - name: Checkout Repository
-        uses: actions/checkout@v2
+        uses: actions/checkout@v4
 
       - name: Cache Gradle dependencies
-        uses: actions/cache@v2
+        uses: actions/cache@v4
         with:
           path: ~/.gradle
           key: ${{ runner.os }}-gradle-${{ hashFiles('**/*.gradle*', '**/gradle-wrapper.properties') }}

api/src/main/java/de/oliver/fancyholograms/api/FancyHologramsPlugin.java → api/src/main/java/de/oliver/fancyholograms/api/FancyHolograms.java

@@ -1,15 +1,20 @@
 package de.oliver.fancyholograms.api;
 
 import de.oliver.fancyanalytics.logger.ExtendedFancyLogger;
+import de.oliver.fancyholograms.api.data.HologramData;
+import de.oliver.fancyholograms.api.hologram.Hologram;
+import de.oliver.fancyholograms.api.trait.HologramTraitRegistry;
 import org.bukkit.Bukkit;
 import org.bukkit.plugin.Plugin;
 import org.bukkit.plugin.java.JavaPlugin;
+import org.jetbrains.annotations.ApiStatus;
 
 import java.util.concurrent.ScheduledExecutorService;
+import java.util.function.Function;
 
-public interface FancyHologramsPlugin {
+public interface FancyHolograms {
 
-    static FancyHologramsPlugin get() {
+    static FancyHolograms get() {
         if (isEnabled()) {
             return EnabledChecker.getPlugin();
         }
@@ -25,45 +30,24 @@ static boolean isEnabled() {
 
     ExtendedFancyLogger getFancyLogger();
 
-    HologramManager getHologramManager();
-
-    /**
-     * Returns the configuration of the plugin.
-     *
-     * @return The configuration.
-     */
     HologramConfiguration getHologramConfiguration();
 
-    /**
-     * Sets the configuration of the plugin.
-     *
-     * @param configuration The new configuration.
-     * @param reload        Whether the configuration should be reloaded.
-     */
-    void setHologramConfiguration(HologramConfiguration configuration, boolean reload);
-
-    /**
-     * @return The hologram storage.
-     */
-    HologramStorage getHologramStorage();
-
-    /**
-     * @return The hologram thread
-     */
+    @ApiStatus.Internal
+    Function<HologramData, Hologram> getHologramFactory();
+
     ScheduledExecutorService getHologramThread();
 
-    /**
-     * Sets the hologram storage.
-     *
-     * @param storage The new hologram storage.
-     * @param reload  Whether the current hologram cache should be reloaded.
-     */
-    void setHologramStorage(HologramStorage storage, boolean reload);
+    HologramRegistry getRegistry();
+
+    HologramController getController();
+
+    @ApiStatus.Experimental
+    HologramTraitRegistry getTraitRegistry();
 
     class EnabledChecker {
 
         private static Boolean enabled;
-        private static FancyHologramsPlugin plugin;
+        private static FancyHolograms plugin;
 
         public static Boolean isFancyHologramsEnabled() {
             if (enabled != null) return enabled;
@@ -72,7 +56,7 @@ public static Boolean isFancyHologramsEnabled() {
 
             if (pl != null && pl.isEnabled()) {
                 try {
-                    plugin = (FancyHologramsPlugin) pl;
+                    plugin = (FancyHolograms) pl;
                 } catch (ClassCastException e) {
                     throw new IllegalStateException("API failed to access plugin, if using the FancyHolograms API make sure to set the dependency to compile only.");
                 }
@@ -84,7 +68,7 @@ public static Boolean isFancyHologramsEnabled() {
             return false;
         }
 
-        public static FancyHologramsPlugin getPlugin() {
+        public static FancyHolograms getPlugin() {
             return plugin;
         }
     }

api/src/main/java/de/oliver/fancyholograms/api/HologramConfiguration.java

@@ -9,7 +9,7 @@ public interface HologramConfiguration {
      *
      * @param plugin The plugin instance.
      */
-    void reload(@NotNull FancyHologramsPlugin plugin);
+    void reload(@NotNull FancyHolograms plugin);
 
     /**
      * Returns whether version notifications are muted.

api/src/main/java/de/oliver/fancyholograms/api/HologramController.java

@@ -0,0 +1,43 @@
+package de.oliver.fancyholograms.api;
+
+import de.oliver.fancyholograms.api.hologram.Hologram;
+import org.bukkit.entity.Player;
+import org.jetbrains.annotations.ApiStatus;
+import org.jetbrains.annotations.NotNull;
+
+import java.util.Collection;
+
+/**
+ * The controller for holograms, responsible for showing and hiding them to players.
+ */
+public interface HologramController {
+
+    /**
+     * Shows the hologram to the given players, if they should see it, and it is not already shown to them.
+     */
+    @ApiStatus.Internal
+    void showHologramTo(@NotNull final Hologram hologram, @NotNull final Player ...players);
+
+    /**
+     * Hides the hologram from the given players, if they should not see it, and it is shown to them.
+     */
+    @ApiStatus.Internal
+    void hideHologramFrom(@NotNull final Hologram hologram, @NotNull final Player ...players);
+
+    /**
+     * Returns whether the given player should see the hologram.
+     */
+    @ApiStatus.Internal
+    boolean shouldSeeHologram(@NotNull final Hologram hologram, @NotNull final Player player);
+
+    /**
+     * Spawns the hologram to the given players, if they should see it, and it is not already shown to them.
+     * Hide the hologram from the players that should not see it.
+     */
+    void refreshHologram(@NotNull final Hologram hologram, @NotNull final Player ...players);
+
+    default void refreshHologram(@NotNull final Hologram hologram, @NotNull final Collection<? extends Player> players) {
+        refreshHologram(hologram, players.toArray(new Player[0]));
+    }
+
+}

api/src/main/java/de/oliver/fancyholograms/api/HologramRegistry.java

@@ -0,0 +1,74 @@
+package de.oliver.fancyholograms.api;
+
+import de.oliver.fancyholograms.api.hologram.Hologram;
+
+import java.util.Collection;
+import java.util.Optional;
+
+/**
+ * An interface for managing the registration and retrieval of holograms.
+ * Provides methods to register, unregister, and query holograms by their name.
+ */
+public interface HologramRegistry {
+
+    /**
+     * Registers a hologram in the registry.
+     *
+     * @param hologram the hologram to be registered
+     * @return {@code true} if the registration was successful, otherwise {@code false}
+     */
+    boolean register(Hologram hologram);
+
+    /**
+     * Unregisters the specified hologram from the registry.
+     *
+     * @param hologram the hologram to be unregistered
+     * @return {@code true} if the hologram was successfully unregistered, otherwise {@code false}
+     */
+    boolean unregister(Hologram hologram);
+
+    /**
+     * Checks if a hologram with the specified name exists in the registry.
+     *
+     * @param name the name of the hologram to check for existence
+     * @return {@code true} if a hologram with the specified name exists, otherwise {@code false}
+     */
+    boolean contains(String name);
+
+    /**
+     * Retrieves a hologram by its name from the registry.
+     *
+     * @param name the name of the hologram to retrieve
+     * @return an {@code Optional} containing the hologram if found, or an empty {@code Optional} if no hologram exists with the specified name
+     */
+    Optional<Hologram> get(String name);
+
+    /**
+     * Retrieves a hologram by its name from the registry, ensuring that the hologram exists.
+     * If no hologram exists with the specified name, this method will throw an exception.
+     *
+     * @param name the name of the hologram to retrieve
+     * @return the hologram associated with the specified name
+     * @throws IllegalArgumentException if no hologram exists with the given name
+     */
+    Hologram mustGet(String name);
+
+    /**
+     * Retrieves all holograms currently registered in the registry.
+     *
+     * @return a collection containing all registered holograms
+     */
+    Collection<Hologram> getAll();
+
+    /**
+     * Retrieves all persistent holograms currently registered in the registry.
+     *
+     * @return a collection containing all persistent holograms
+     */
+    Collection<Hologram> getAllPersistent();
+
+    /**
+     * Removes all holograms from the registry, effectively clearing its contents.
+     */
+    void clear();
+}

api/src/main/java/de/oliver/fancyholograms/api/data/BlockHologramData.java

@@ -4,6 +4,7 @@
 import org.bukkit.Location;
 import org.bukkit.Material;
 import org.bukkit.configuration.ConfigurationSection;
+import org.jetbrains.annotations.ApiStatus;
 
 import java.util.Objects;
 
@@ -36,6 +37,7 @@ public BlockHologramData setBlock(Material block) {
     }
 
     @Override
+    @ApiStatus.Internal
     public boolean read(ConfigurationSection section, String name) {
         super.read(section, name);
         block = Material.getMaterial(section.getString("block", "GRASS_BLOCK").toUpperCase());
@@ -44,6 +46,7 @@ public boolean read(ConfigurationSection section, String name) {
     }
 
     @Override
+    @ApiStatus.Internal
     public boolean write(ConfigurationSection section, String name) {
         super.write(section, name);
         section.set("block", block.name());

api/src/main/java/de/oliver/fancyholograms/api/data/DisplayHologramData.java

@@ -131,6 +131,7 @@ public DisplayHologramData setInterpolationDuration(int interpolationDuration) {
     }
 
     @Override
+    @ApiStatus.Internal
     public boolean read(ConfigurationSection section, String name) {
         super.read(section, name);
         scale = new Vector3f(
@@ -170,6 +171,7 @@ public boolean read(ConfigurationSection section, String name) {
     }
 
     @Override
+    @ApiStatus.Internal
     public boolean write(ConfigurationSection section, String name) {
         super.write(section, name);
         section.set("scale_x", scale.x);

api/src/main/java/de/oliver/fancyholograms/api/data/HologramData.java

@@ -1,12 +1,13 @@
 package de.oliver.fancyholograms.api.data;
 
-import de.oliver.fancyholograms.api.FancyHologramsPlugin;
+import de.oliver.fancyholograms.api.FancyHolograms;
 import de.oliver.fancyholograms.api.data.property.Visibility;
 import de.oliver.fancyholograms.api.hologram.HologramType;
 import org.bukkit.Bukkit;
 import org.bukkit.Location;
 import org.bukkit.World;
 import org.bukkit.configuration.ConfigurationSection;
+import org.jetbrains.annotations.ApiStatus;
 import org.jetbrains.annotations.NotNull;
 import org.jetbrains.annotations.Nullable;
 
@@ -23,7 +24,7 @@ public class HologramData implements YamlData {
     private final String name;
     private final HologramType type;
     private Location location;
-    private boolean hasChanges;
+    private boolean hasChanges = false;
     private int visibilityDistance = DEFAULT_VISIBILITY_DISTANCE;
     private Visibility visibility = DEFAULT_VISIBILITY;
     private boolean persistent = DEFAULT_PERSISTENCE;
@@ -78,7 +79,7 @@ public int getVisibilityDistance() {
             return visibilityDistance;
         }
 
-        return FancyHologramsPlugin.get().getHologramConfiguration().getDefaultVisibilityDistance();
+        return FancyHolograms.get().getHologramConfiguration().getDefaultVisibilityDistance();
     }
 
     public HologramData setVisibilityDistance(int visibilityDistance) {
@@ -135,6 +136,7 @@ public HologramData setLinkedNpcName(String linkedNpcName) {
     }
 
     @Override
+    @ApiStatus.Internal
     public boolean read(ConfigurationSection section, String name) {
         String worldName = section.getString("location.world", "world");
         float x = (float) section.getDouble("location.x", 0);
@@ -145,7 +147,7 @@ public boolean read(ConfigurationSection section, String name) {
 
         World world = Bukkit.getWorld(worldName);
         if (world == null) {
-            FancyHologramsPlugin.get().getFancyLogger().warn("Could not load hologram '" + name + "', because the world '" + worldName + "' is not loaded");
+            FancyHolograms.get().getFancyLogger().warn("Could not load hologram '" + name + "', because the world '" + worldName + "' is not loaded");
             return false;
         }
 
@@ -163,6 +165,7 @@ public boolean read(ConfigurationSection section, String name) {
     }
 
     @Override
+    @ApiStatus.Internal
     public boolean write(ConfigurationSection section, String name) {
         section.set("type", type.name());
         section.set("location.world", location.getWorld().getName());

api/src/main/java/de/oliver/fancyholograms/api/data/ItemHologramData.java

@@ -5,6 +5,7 @@
 import org.bukkit.Material;
 import org.bukkit.configuration.ConfigurationSection;
 import org.bukkit.inventory.ItemStack;
+import org.jetbrains.annotations.ApiStatus;
 
 import java.util.Objects;
 
@@ -37,6 +38,7 @@ public ItemHologramData setItemStack(ItemStack item) {
     }
 
     @Override
+    @ApiStatus.Internal
     public boolean read(ConfigurationSection section, String name) {
         super.read(section, name);
         item = section.getItemStack("item", DEFAULT_ITEM);
@@ -45,6 +47,7 @@ public boolean read(ConfigurationSection section, String name) {
     }
 
     @Override
+    @ApiStatus.Internal
     public boolean write(ConfigurationSection section, String name) {
         super.write(section, name);
         section.set("item", item);