Components + Title animation

.gitignore

@@ -48,3 +48,9 @@ target
 target-api
 *.java~
 *.kts~
+
+### OpenCode ###
+
+/AGENTS.md
+
+opencode.json

API/build.gradle.kts

@@ -2,6 +2,10 @@ plugins {
     id("re.alwyn974.groupez.publish") version "1.0.0"
 }
 
+dependencies{
+    implementation("net.kyori:adventure-api:4.25.0")
+}
+
 rootProject.extra.properties["sha"]?.let { sha ->
     version = sha
 }

API/src/main/java/fr/maxlego08/menu/ComponentsManager.java

@@ -0,0 +1,28 @@
+package fr.maxlego08.menu;
+
+import fr.maxlego08.menu.api.MenuPlugin;
+import fr.maxlego08.menu.api.exceptions.ItemComponentAlreadyRegisterException;
+import fr.maxlego08.menu.api.loader.ItemComponentLoader;
+import org.jetbrains.annotations.NotNull;
+
+import java.util.Optional;
+
+public interface ComponentsManager {
+
+    void initializeDefaultComponents(MenuPlugin plugin);
+
+    /**
+     * Register a new ItemComponentLoader.
+     * @param loader The loader to register
+     * @throws ItemComponentAlreadyRegisterException if a loader with the same name is already registered
+     **/
+    void registerComponent(@NotNull ItemComponentLoader loader) throws ItemComponentAlreadyRegisterException;
+
+    /**
+     * Get an ItemComponentLoader by its name.
+     * @param name The name of the loader
+     * @return An Optional containing the loader if found, or empty if not found
+     **/
+    @NotNull
+    Optional<ItemComponentLoader> getLoader(@NotNull String name);
+}

API/src/main/java/fr/maxlego08/menu/api/ButtonManager.java

@@ -13,6 +13,7 @@
 import org.bukkit.configuration.file.YamlConfiguration;
 import org.bukkit.plugin.Plugin;
 import org.jetbrains.annotations.NotNull;
+import org.jetbrains.annotations.Nullable;
 
 import java.io.File;
 import java.util.Collection;
@@ -43,20 +44,21 @@ public interface ButtonManager {
      *
      * @param button The {@link ButtonLoader} instance to unregister.
      */
-    void unregister(ButtonLoader button);
+    void unregister(@NotNull ButtonLoader button);
 
     /**
      * Unregisters all {@link ButtonLoader} instances linked to a specific plugin.
      *
      * @param plugin The plugin whose loaders should be unregistered.
      */
-    void unregisters(Plugin plugin);
+    void unregisters(@NotNull Plugin plugin);
 
     /**
      * Retrieves all registered {@link ButtonLoader} instances.
      *
      * @return A collection containing all registered {@link ButtonLoader} instances.
      */
+    @NotNull
     Collection<ButtonLoader> getLoaders();
 
     /**
@@ -65,28 +67,31 @@ public interface ButtonManager {
      * @param plugin The plugin whose loaders are to be retrieved.
      * @return A collection of {@link ButtonLoader} instances or an empty collection if none are found.
      */
-    Collection<ButtonLoader> getLoaders(Plugin plugin);
+    @NotNull
+    Collection<ButtonLoader> getLoaders(@NotNull Plugin plugin);
 
     /**
      * Retrieves a {@link ButtonLoader} based on the name of the associated {@link Button}.
      *
      * @param name The name of the {@link ButtonLoader}.
      * @return An {@link Optional} containing the {@link ButtonLoader}, if found.
      */
-    Optional<ButtonLoader> getLoader(String name);
+    @NotNull
+    Optional<ButtonLoader> getLoader(@Nullable String name);
 
     /**
      * Registers a new {@link PermissibleLoader} responsible for permissible creation.
      *
      * @param permissibleLoader The {@link PermissibleLoader} instance to register.
      */
-    void registerPermissible(PermissibleLoader permissibleLoader);
+    void registerPermissible(@NotNull PermissibleLoader permissibleLoader);
 
     /**
      * Retrieves a mapping of permissible keys to their associated {@link PermissibleLoader} instances.
      *
      * @return A map linking permissible keys to their corresponding {@link PermissibleLoader} instances.
      */
+    @NotNull
     Map<String, PermissibleLoader> getPermissibles();
 
     /**
@@ -95,22 +100,24 @@ public interface ButtonManager {
      * @param key The key identifying the permissible.
      * @return An {@link Optional} containing the {@link PermissibleLoader}, if found.
      */
-    Optional<PermissibleLoader> getPermission(String key);
+    @NotNull
+    Optional<PermissibleLoader> getPermission(@NotNull String key);
 
     /**
      * Registers a new {@link ActionLoader} responsible for action creation.
      *
      * @param actionLoader The {@link ActionLoader} instance to register.
      */
-    void registerAction(ActionLoader actionLoader);
+    void registerAction(@NotNull ActionLoader actionLoader);
 
     /**
      * Retrieves an {@link Optional} {@link ActionLoader} based on a specific action key.
      *
      * @param key The key identifying the action.
      * @return An {@link Optional} containing the {@link ActionLoader}, if found.
      */
-    Optional<ActionLoader> getActionLoader(String key);
+    @NotNull
+    Optional<ActionLoader> getActionLoader(@NotNull String key);
 
     /**
      * Converts a list of map elements from a configuration file into a list of {@link Permissible} objects.
@@ -120,7 +127,8 @@ public interface ButtonManager {
      * @param file     The configuration file in use.
      * @return A list of {@link Permissible} objects derived from the configuration.
      */
-    List<Permissible> loadPermissible(List<Map<String, Object>> elements, String path, File file);
+    @NotNull
+    List<@NotNull Permissible> loadPermissible(@NotNull List<@NotNull Map<String, Object>> elements,@NotNull String path,@NotNull File file);
 
     /**
      * Converts a list of map elements from a configuration file into a list of {@link Permissible} objects.
@@ -130,7 +138,8 @@ public interface ButtonManager {
      * @param file          The file where the configuration is located.
      * @return A list of {@link Permissible} objects derived from the configuration.
      */
-    List<Permissible> loadPermissible(YamlConfiguration configuration, String path, File file);
+    @NotNull
+    List<@NotNull Permissible> loadPermissible(@NotNull YamlConfiguration configuration,@NotNull String path,@NotNull File file);
 
     /**
      * Converts a list of map elements from a configuration file into a list of {@link Action} objects.
@@ -142,9 +151,11 @@ public interface ButtonManager {
      * @param file     The configuration file in use.
      * @return A list of {@link Action} objects derived from the configuration.
      */
-    List<Action> loadActions(List<Map<String, Object>> elements, String path, File file);
+    @NotNull
+    List<@NotNull Action> loadActions(@NotNull List<@NotNull Map<String, Object>> elements,@NotNull String path,@NotNull File file);
 
-    List<Action> loadActions(List<Map<String, Object>> elements, String path, File file, @NotNull List<ActionPattern> defaultActions, boolean useSuccess, boolean stopOnEmpty);
+    @NotNull
+    List<@NotNull Action> loadActions(@NotNull List<Map<String, Object>> elements,@NotNull String path,@NotNull File file, @NotNull List<@NotNull ActionPattern> defaultActions, boolean useSuccess, boolean stopOnEmpty);
 
     /**
      * Converts a list of map elements from a configuration file into a list of {@link Action} objects.
@@ -156,13 +167,17 @@ public interface ButtonManager {
      * @param file          The configuration file in use.
      * @return A list of {@link Action} objects derived from the configuration.
      */
-    List<Action> loadActions(YamlConfiguration configuration, String path, File file);
+    @NotNull
+    List<@NotNull Action> loadActions(@NotNull YamlConfiguration configuration,@NotNull String path,@NotNull File file);
 
-    List<Action> loadActions(YamlConfiguration configuration, String path, File file, @NotNull List<ActionPattern> defaultActions, boolean useSuccess, boolean stopOnEmpty);
+    @NotNull
+    List<@NotNull Action> loadActions(@NotNull YamlConfiguration configuration,@NotNull String path,@NotNull File file, @NotNull List<@NotNull ActionPattern> defaultActions, boolean useSuccess, boolean stopOnEmpty);
 
-    List<Requirement> loadRequirements(YamlConfiguration configuration, String path, File file) throws InventoryException;
+    @NotNull
+    List<Requirement> loadRequirements(@Nullable YamlConfiguration configuration,@NotNull String path,@NotNull File file) throws InventoryException;
 
-    Requirement loadRequirement(YamlConfiguration configuration, String path, File file) throws InventoryException;
+    @NotNull
+    Requirement loadRequirement(@NotNull YamlConfiguration configuration,@NotNull String path,@NotNull File file) throws InventoryException;
 
     /**
      * Retrieves a list of all empty actions from the given configuration elements.
@@ -173,7 +188,8 @@ public interface ButtonManager {
      * @param elements The list of configuration items detailing an action's entire configuration.
      * @return A list of all empty actions from the given configuration elements.
      */
-    List<String> getEmptyActions(List<Map<String, Object>> elements);
+    @NotNull
+    List<String> getEmptyActions(@NotNull List<Map<String, Object>> elements);
 
     /**
      * Retrieves a list of all empty permissibles from the given configuration elements.
@@ -184,18 +200,20 @@ public interface ButtonManager {
      * @param elements The list of configuration items detailing a permissible's entire configuration.
      * @return A list of all empty permissibles from the given configuration elements.
      */
-    List<String> getEmptyPermissible(List<Map<String, Object>> elements);
+    @NotNull
+    List<String> getEmptyPermissible(@NotNull List<Map<String, Object>> elements);
 
     /**
      * Retrieves a {@link Loader} for a {@link Button} object based on the given parameters.
      *
      * <p>This method is used to create a loader for a button object, given the plugin instance, file, size, and matrix.</p>
      *
      * @param menuPlugin The plugin instance associated with the button loader.
-     * @param file The file from which the button configuration is loaded.
-     * @param size The size of the button.
-     * @param matrix The matrix containing the button's configuration data.
+     * @param file       The file from which the button configuration is loaded.
+     * @param size       The size of the button.
+     * @param matrix     The matrix containing the button's configuration data.
      * @return A {@link Loader} for a {@link Button} object based on the given parameters.
      */
-    Loader<Button> getLoaderButton(MenuPlugin menuPlugin, File file, int size, Map<Character, List<Integer>> matrix);
+    @NotNull
+    Loader<Button> getLoaderButton(@NotNull MenuPlugin menuPlugin,@NotNull File file, int size,@NotNull Map<Character,@NotNull List<Integer>> matrix);
 }

API/src/main/java/fr/maxlego08/menu/api/DialogInventory.java

@@ -7,6 +7,7 @@
 import fr.maxlego08.menu.api.utils.dialogs.record.ActionButtonRecord;
 import fr.maxlego08.menu.api.utils.dialogs.record.ZDialogInventoryBuild;
 import org.bukkit.entity.Player;
+import org.jetbrains.annotations.NotNull;
 
 import java.io.File;
 import java.util.List;
@@ -135,7 +136,7 @@ public interface DialogInventory {
 
     void setActionButtonServerLink(ActionButtonRecord actionButtonRecord);
 
-    ActionButtonRecord getActionButtonServerLink(Player player);
+    ActionButtonRecord getActionButtonServerLink(@NotNull Player player);
 
     ActionButtonRecord getActionButtonServerLink();
 

API/src/main/java/fr/maxlego08/menu/api/Inventory.java

@@ -1,5 +1,6 @@
 package fr.maxlego08.menu.api;
 
+import fr.maxlego08.menu.api.animation.TitleAnimation;
 import fr.maxlego08.menu.api.button.Button;
 import fr.maxlego08.menu.api.engine.InventoryEngine;
 import fr.maxlego08.menu.api.engine.InventoryResult;
@@ -216,4 +217,8 @@ public interface Inventory {
      * @return The player name placeholder.
      */
     String getTargetPlayerNamePlaceholder();
+
+    void setTitleAnimation(TitleAnimation load);
+
+    TitleAnimation getTitleAnimation();
 }

API/src/main/java/fr/maxlego08/menu/api/InventoryManager.java

@@ -14,6 +14,7 @@
 import fr.maxlego08.menu.api.loader.MaterialLoader;
 import fr.maxlego08.menu.api.utils.Message;
 import fr.maxlego08.menu.api.utils.MetaUpdater;
+import fr.maxlego08.menu.api.utils.Placeholders;
 import org.bukkit.OfflinePlayer;
 import org.bukkit.command.CommandSender;
 import org.bukkit.configuration.file.YamlConfiguration;
@@ -559,6 +560,8 @@ public interface InventoryManager extends Listener {
 
     ItemStack postProcessSkullItemStack(ItemStack itemStack, Button button, Player player);
 
+    ItemStack postProcessSkullItemStack(ItemStack itemStack, Button button, Player player, Placeholders placeholders);
+
     void sendMessage(CommandSender sender, Message message, Object... args);
 
     void load();

API/src/main/java/fr/maxlego08/menu/api/ItemManager.java

@@ -34,6 +34,8 @@ public interface ItemManager {
 
     void registerMechanicFactory(MechanicFactory<?> factory);
 
+    Optional<MechanicFactory<?>> getMechanicFactory(String mechanicId);
+
     void giveItem(Player player, String itemId);
 
     void executeCheckInventoryItems(Player player);