Slot animations, typed registries and API cleanup

.github/workflows/build.yml

@@ -20,7 +20,7 @@ jobs:
       java-version: '25'
       publish: true
       project-to-publish: "API:publish"
-      discord-avatar-url: "https://groupez.dev/storage/images/253.png"
+      discord-avatar-url: "https://groupez.dev/storage/images/resources/icons/253.webp"
       artifact-glob: "target/*.jar"
       changelog-exclude-pattern: '^[a-f0-9]+\s+(build|chore)\(deps\)'
     secrets:

.gitignore

@@ -60,4 +60,5 @@ build-and-deploy.sh
 GEMINI.md
 
 TODO.md
-docs/triage-issues.md
+/docs/*
+!/docs/live-sync-plan.md

API/build.gradle.kts

@@ -1,10 +1,20 @@
 plugins {
     alias(libs.plugins.groupez.publish)
+    `java-test-fixtures`
 }
 
 dependencies{
     compileOnly(libs.adventure.api)
     compileOnly(libs.adventure.text.minimessage)
+
+    testImplementation(libs.paper.api)
+    testFixturesCompileOnly(libs.paper.api)
+}
+
+// The test fixtures are shared with the tests of other modules, they are not published.
+(components["java"] as AdhocComponentWithVariants).apply {
+    withVariantsFromConfiguration(configurations["testFixturesApiElements"]) { skip() }
+    withVariantsFromConfiguration(configurations["testFixturesRuntimeElements"]) { skip() }
 }
 
 rootProject.extra.properties["sha"]?.let { sha ->
@@ -15,7 +25,6 @@ tasks {
     shadowJar {
         relocate("com.tcoded.folialib", "fr.maxlego08.menu.hooks.folialib")
         relocate("fr.traqueur.currencies", "fr.maxlego08.menu.hooks.currencies")
-        relocate("de.tr7zw.changeme.nbtapi", "fr.maxlego08.menu.hooks.nbtapi")
         relocate("com.cryptomorin.xseries", "fr.maxlego08.menu.hooks.xseries")
         relocate("fr.maxlego08.sarah", "fr.maxlego08.menu.hooks.sarah")
         relocate("net.objecthunter.exp4j", "fr.maxlego08.menu.hooks.exp4j")

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

@@ -9,7 +9,6 @@
 import fr.maxlego08.menu.api.requirement.Action;
 import fr.maxlego08.menu.api.requirement.Permissible;
 import fr.maxlego08.menu.api.requirement.Requirement;
-import fr.maxlego08.menu.api.rules.loader.RuleLoader;
 import fr.maxlego08.menu.api.utils.Loader;
 import org.bukkit.configuration.file.YamlConfiguration;
 import org.bukkit.plugin.Plugin;
@@ -37,21 +36,30 @@ public interface ButtonManager {
      * Registers a new {@link ButtonLoader} responsible for button creation.
      *
      * @param button The {@link ButtonLoader} instance to register.
+     * @deprecated register it in {@link fr.maxlego08.menu.api.registry.Registries#BUTTON}:
+     * {@code registries.writable(Registries.BUTTON).register(plugin, loader, loader.aliases())}, which
+     * throws on a name already taken instead of logging it.
      */
+    @Deprecated(since = "1.1.2.1", forRemoval = true)
     void register(@NotNull ButtonLoader button);
 
     /**
      * Unregisters an existing {@link ButtonLoader}, ceasing its button creation responsibilities.
      *
      * @param button The {@link ButtonLoader} instance to unregister.
+     * @deprecated use {@code registries.writable(Registries.BUTTON).unregister(loader.key())}.
      */
+    @Deprecated(since = "1.1.2.1", forRemoval = true)
     void unregister(@NotNull ButtonLoader button);
 
     /**
      * Unregisters all {@link ButtonLoader} instances linked to a specific plugin.
      *
      * @param plugin The plugin whose loaders should be unregistered.
+     * @deprecated a plugin's button types are removed when it disables; to remove them earlier use
+     * {@code registries.writable(Registries.BUTTON).unregisterAll(plugin)}.
      */
+    @Deprecated(since = "1.1.2.1", forRemoval = true)
     void unregisters(@NotNull Plugin plugin);
 
     /**
@@ -67,8 +75,11 @@ 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.
+     * @deprecated read {@link fr.maxlego08.menu.api.registry.Registries#BUTTON} and its
+     * {@link fr.maxlego08.menu.api.registry.KeyedRegistry#owner(net.kyori.adventure.key.Key) owners}.
      */
     @NotNull
+    @Deprecated(since = "1.1.2.1", forRemoval = true)
     Collection<ButtonLoader> getLoaders(@NotNull Plugin plugin);
 
     /**
@@ -84,15 +95,21 @@ public interface ButtonManager {
      * Registers a new {@link PermissibleLoader} responsible for permissible creation.
      *
      * @param permissibleLoader The {@link PermissibleLoader} instance to register.
+     * @deprecated register it in {@link fr.maxlego08.menu.api.registry.Registries#PERMISSIBLE}:
+     * {@code registries.writable(Registries.PERMISSIBLE).register(plugin, loader)}, which throws on a
+     * name already taken instead of logging it.
      */
+    @Deprecated(since = "1.1.2.1", forRemoval = true)
     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.
+     * @return A copy of the registered types, by their lowercased name.
+     * @deprecated read {@link fr.maxlego08.menu.api.registry.Registries#PERMISSIBLE}.
      */
     @NotNull
+    @Deprecated(since = "1.1.2.1", forRemoval = true)
     Map<String, PermissibleLoader> getPermissibles();
 
     /**
@@ -108,19 +125,13 @@ public interface ButtonManager {
      * Registers a new {@link ActionLoader} responsible for action creation.
      *
      * @param actionLoader The {@link ActionLoader} instance to register.
+     * @deprecated register it in {@link fr.maxlego08.menu.api.registry.Registries#ACTION}:
+     * {@code registries.writable(Registries.ACTION).register(plugin, loader, loader.aliases())}, which
+     * throws on a name already taken instead of logging it.
      */
+    @Deprecated(since = "1.1.2.1", forRemoval = true)
     void registerAction(@NotNull ActionLoader actionLoader);
 
-    /**
-     * Registers a {@link RuleLoader} so its rule type (and aliases) can be used in item rules,
-     * for example in an {@code item_drag} button or an {@code item-rule} requirement.
-     * <p>
-     * Unlike {@code @AutoRuleLoader}, which only scans the zMenu package, this lets external plugins add rule types.
-     *
-     * @param ruleLoader The {@link RuleLoader} instance to register.
-     */
-    void registerRuleLoader(@NotNull RuleLoader ruleLoader);
-
     /**
      * Retrieves an {@link Optional} {@link ActionLoader} based on a specific action key.
      *

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

@@ -1,6 +1,5 @@
 package fr.maxlego08.menu.api;
 
-import fr.maxlego08.menu.api.exceptions.ItemComponentAlreadyRegisterException;
 import fr.maxlego08.menu.api.loader.ItemComponentLoader;
 import org.jetbrains.annotations.NotNull;
 
@@ -12,11 +11,14 @@ public interface ComponentsManager {
     void initializeDefaultComponents(MenuPlugin plugin);
 
     /**
-     * Register a new ItemComponentLoader.
+     * Register a new ItemComponentLoader. A name already taken is logged and the loader is not registered.
      * @param loader The loader to register
-     * @throws ItemComponentAlreadyRegisterException if a loader with the same name is already registered
+     * @deprecated register it in {@link fr.maxlego08.menu.api.registry.Registries#ITEM_COMPONENT}:
+     * {@code registries.writable(Registries.ITEM_COMPONENT).register(plugin, loader, loader.aliases())},
+     * which throws on a name already taken.
      **/
-    void registerComponent(@NotNull ItemComponentLoader loader) throws ItemComponentAlreadyRegisterException;
+    @Deprecated(since = "1.1.2.1", forRemoval = true)
+    void registerComponent(@NotNull ItemComponentLoader loader);
 
     /**
      * Get an ItemComponentLoader by its name.

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

@@ -13,6 +13,8 @@
 import fr.maxlego08.menu.api.utils.OpenWithItem;
 import fr.maxlego08.menu.api.utils.Placeholders;
 import fr.maxlego08.menu.api.utils.SectionSerializable;
+import net.kyori.adventure.key.Key;
+import net.kyori.adventure.key.Keyed;
 import org.bukkit.configuration.ConfigurationSection;
 import org.bukkit.entity.Player;
 import org.bukkit.event.inventory.InventoryType;
@@ -31,7 +33,19 @@
  * Documentation: <a href="https://docs.zmenu.dev/api/create-inventory">Inventory documentation</a>
  * <p>This class encapsulates information about an inventory, including its size, buttons, patterns, and associated requirements.</p>
  */
-public interface Inventory extends SectionSerializable {
+public interface Inventory extends Keyed, SectionSerializable {
+
+    /**
+     * Returns the key of the inventory: the name of its plugin and its file name, lowercased, with
+     * every character a key cannot hold replaced by "_".
+     *
+     * @return the key
+     * @see ZMenuKeys#fileKey(String, String)
+     */
+    @Override
+    default @NotNull Key key() {
+        return ZMenuKeys.fileKey(this.getPlugin().getName(), this.getFileName());
+    }
 
     /**
      * Returns the size of the inventory.
@@ -91,6 +105,9 @@ public interface Inventory extends SectionSerializable {
     /**
      * Returns the name of the file associated with the inventory.
      *
+     * <p>Use it to display or store the inventory, not to identify it: the case is kept, so it can
+     * differ from {@link #key()}. Compare and look up inventories with {@link #key()}.</p>
+     *
      * @return The file name. This name is the name of the configuration file.
      */
     String getFileName();