Feat/better exemple (#5)

* fix: exemples

* feat: add zItems hook for exemples

* feat: add zItems soft depend

* fix: message

Author: Traqueur-dev

api/src/main/java/fr/traqueur/crates/api/registries/HooksRegistry.java

@@ -1,5 +1,6 @@
 package fr.traqueur.crates.api.registries;
 
+import fr.traqueur.crates.api.CratesPlugin;
 import fr.traqueur.crates.api.hooks.Hook;
 import org.bukkit.plugin.java.JavaPlugin;
 
@@ -19,6 +20,6 @@ public interface HooksRegistry extends Registry<String, Hook> {
      * @param plugin      the JavaPlugin instance
      * @param packageName the package name to scan for hooks
      */
-    void scanPackage(JavaPlugin plugin, String packageName);
+    void scanPackage(CratesPlugin plugin, String packageName);
 
 }

common/src/main/java/fr/traqueur/crates/models/placedcrates/EntityCrateDisplay.java

@@ -17,7 +17,7 @@ public class EntityCrateDisplay implements CrateDisplay<Entity> {
 
     public EntityCrateDisplay(Location location, String value, float yaw) {
         this.location = location;
-        this.entityType = value.toUpperCase();
+        this.entityType = value;
         this.yaw = yaw;
     }
 

hooks/MythicMobs/src/main/java/fr/traqueur/crates/hooks/mythicmobs/MythicMobCrateDisplay.java

@@ -7,6 +7,7 @@
 import io.lumine.mythic.bukkit.MythicBukkit;
 import io.lumine.mythic.core.mobs.ActiveMob;
 import org.bukkit.Location;
+import org.bukkit.entity.Entity;
 
 import java.util.Optional;
 
@@ -20,22 +21,59 @@ public MythicMobCrateDisplay(Location location, String value, float yaw) {
 
     @Override
     public void spawn() {
+        // Create centered location while preserving yaw and pitch from original location
+        Location originalLocation = getLocation();
+        Location centeredLocation = originalLocation.clone().add(0.5, 0, 0.5);
+        centeredLocation.setYaw(originalLocation.getYaw());
+        centeredLocation.setPitch(originalLocation.getPitch());
+
+        // Remove any existing entity at this location (from previous server session)
+        // This ensures ModelEngine properly applies the model to a fresh spawn
+        Entity existingEntity = findExistingMythicEntity(centeredLocation);
+        if (existingEntity != null) {
+            // Check if it's an ActiveMob and remove it properly
+            Optional<ActiveMob> existingActiveMob = MythicBukkit.inst().getMobManager().getActiveMob(existingEntity.getUniqueId());
+            if (existingActiveMob.isPresent()) {
+                existingActiveMob.get().remove();
+            } else {
+                existingEntity.remove();
+            }
+        }
+
+        // Always spawn a fresh MythicMob to ensure ModelEngine applies the model correctly
         Optional<MythicMob> mythicMobOpt = MythicBukkit.inst().getMobManager().getMythicMob(this.entityType);
         if (mythicMobOpt.isEmpty()) {
             throw new IllegalArgumentException("MythicMob type not found: " + this.entityType);
         }
 
-        this.activeMob = mythicMobOpt.get().spawn(BukkitAdapter.adapt(getLocation()), 1);
+        // Spawn with the centered location that includes the correct yaw
+        this.activeMob = mythicMobOpt.get().spawn(BukkitAdapter.adapt(centeredLocation), 1);
         this.entity = activeMob.getEntity().getBukkitEntity();
 
-        this.entity.setRotation(getLocation().getYaw(), 0);
+        // Apply rotation immediately
+        this.entity.setRotation(centeredLocation.getYaw(), 0);
         this.entity.setInvulnerable(true);
         this.entity.setPersistent(true);
         this.entity.setGravity(false);
 
         Keys.PLACED_CRATE_ENTITY.set(this.entity.getPersistentDataContainer(), true);
     }
 
+    private Entity findExistingMythicEntity(Location centeredLocation) {
+        // Search for entities with the PDC marker in the vicinity
+        return centeredLocation.getWorld().getNearbyEntities(centeredLocation, 1, 1, 1).stream()
+                .filter(e -> {
+                    // Check if entity has our marker
+                    if (!Keys.PLACED_CRATE_ENTITY.get(e.getPersistentDataContainer(), false)) {
+                        return false;
+                    }
+                    // Check if this is a MythicMob entity
+                    return MythicBukkit.inst().getMobManager().isMythicMob(e);
+                })
+                .findFirst()
+                .orElse(null);
+    }
+
     @Override
     public void remove() {
         if (activeMob != null) {

hooks/zItems/build.gradle.kts

@@ -0,0 +1,8 @@
+repositories {
+    maven(url = "https://repo.groupez.dev/releases")
+    maven(url = "https://repo.groupez.dev/snapshots")
+}
+
+dependencies {
+    compileOnly("fr.traqueur:zitems-api:1b9d3e0")
+}

hooks/zItems/src/main/java/fr/traqueur/crates/hooks/zitems/ZItemsHook.java

@@ -0,0 +1,21 @@
+package fr.traqueur.crates.hooks.zitems;
+
+import fr.traqueur.crates.api.annotations.AutoHook;
+import fr.traqueur.crates.api.hooks.Hook;
+import fr.traqueur.crates.api.registries.ItemsProvidersRegistry;
+import fr.traqueur.crates.api.registries.Registry;
+import fr.traqueur.items.api.items.Item;
+import fr.traqueur.items.api.registries.ItemsRegistry;
+
+@AutoHook("zItems")
+public class ZItemsHook implements Hook {
+    @Override
+    public void onEnable() {
+        ItemsProvidersRegistry itemsProvidersRegistry = Registry.get(ItemsProvidersRegistry.class);
+        itemsProvidersRegistry.register("ItemsAdder", (player, itemId) -> {
+            ItemsRegistry registry = fr.traqueur.items.api.registries.Registry.get(ItemsRegistry.class);
+            Item item = registry.getById(itemId);
+            return item.build(player, 1);
+        });
+    }
+}

settings.gradle.kts

@@ -23,4 +23,5 @@ file("hooks").listFiles()?.forEach { file ->
         println("Include hooks:${file.name}")
         include(":hooks:${file.name}")
     }
-}
+}
+include("hooks:zItems")

src/main/java/fr/traqueur/crates/managers/ZCratesManager.java

@@ -58,7 +58,13 @@ public class ZCratesManager implements CratesManager {
     public void init() {
         this.getPlugin().registerListener(new CratesListener(this));
         this.ensureInventoriesExist();
-        this.loadAllPlacedCrates();
+
+        // Delay placed crates loading to ensure MythicMobs/ModelEngine are fully initialized
+        // This prevents display issues with custom models on server restart
+        Bukkit.getScheduler().runTaskLater(this.getPlugin(), () -> {
+            this.loadAllPlacedCrates();
+            Logger.debug("Placed crates loaded after initialization delay");
+        }, 40L); // 2 seconds delay (40 ticks)
     }
 
     private static class OpenedCrate {

src/main/java/fr/traqueur/crates/models/wrappers/ArrayHelper.java

@@ -0,0 +1,51 @@
+package fr.traqueur.crates.models.wrappers;
+
+import fr.traqueur.crates.api.Logger;
+import org.mozilla.javascript.NativeArray;
+
+/**
+ * Helper class for JavaScript array conversions.
+ * Provides utilities to convert JavaScript arrays to Java arrays.
+ */
+public class ArrayHelper {
+
+    /**
+     * Converts a JavaScript array to a Java int[] array.
+     * Accepts both JavaScript arrays (NativeArray) and Java int[] arrays.
+     *
+     * @param array the array to convert (can be NativeArray or int[])
+     * @return the converted int[] array, or null if conversion fails
+     */
+    public static int[] toIntArray(Object array) {
+        if (array == null) {
+            Logger.warning("Cannot convert null to int array");
+            return null;
+        }
+
+        // Already a Java int array
+        if (array instanceof int[] javaArray) {
+            return javaArray;
+        }
+
+        // JavaScript NativeArray
+        if (array instanceof NativeArray nativeArray) {
+            int length = (int) nativeArray.getLength();
+            int[] result = new int[length];
+
+            for (int i = 0; i < length; i++) {
+                Object element = nativeArray.get(i);
+                if (element instanceof Number num) {
+                    result[i] = num.intValue();
+                } else {
+                    Logger.warning("Invalid array element at index {}: {}", i, element);
+                    return null;
+                }
+            }
+
+            return result;
+        }
+
+        Logger.warning("Cannot convert {} to int array", array.getClass().getName());
+        return null;
+    }
+}

src/main/java/fr/traqueur/crates/models/wrappers/InventoryWrapper.java

@@ -98,33 +98,38 @@ public void setRandomItem(int slot) {
     /**
      * Rotates items through the specified slots (shifts them to the right).
      * Only rotates slots that are authorized.
+     * <p>
+     * Accepts both Java int[] arrays and JavaScript arrays (NativeArray).
+     * JavaScript arrays will be automatically converted to int[].
      *
-     * @param slots the slot indices to rotate
+     * @param slots the slot indices to rotate (int[] or JavaScript array)
      */
-    public void rotateItems(int[] slots) {
-        if (slots == null || slots.length < 2) {
+    public void rotateItems(Object slots) {
+        // Convert to int[] array (handles both Java and JavaScript arrays)
+        int[] slotArray = ArrayHelper.toIntArray(slots);
+        if (slotArray == null || slotArray.length < 2) {
             return;
         }
 
         // Check all slots are authorized
-        for (int slot : slots) {
+        for (int slot : slotArray) {
             if (!isAuthorized(slot)) {
                 Logger.warning("Slot " + slot + " is not authorized for rotation");
                 return;
             }
         }
 
         // Save the last item
-        ItemStack lastItem = delegate.getItem(slots[slots.length - 1]);
+        ItemStack lastItem = delegate.getItem(slotArray[slotArray.length - 1]);
 
         // Shift all items to the right
-        for (int i = slots.length - 1; i > 0; i--) {
-            ItemStack item = delegate.getItem(slots[i - 1]);
-            delegate.setItem(slots[i], item);
+        for (int i = slotArray.length - 1; i > 0; i--) {
+            ItemStack item = delegate.getItem(slotArray[i - 1]);
+            delegate.setItem(slotArray[i], item);
         }
 
         // Put the last item at the first position
-        delegate.setItem(slots[0], lastItem);
+        delegate.setItem(slotArray[0], lastItem);
     }
 
     /**

src/main/java/fr/traqueur/crates/registries/ZAnimationRegistry.java

@@ -6,6 +6,7 @@
 import fr.traqueur.crates.api.models.animations.Animation;
 import fr.traqueur.crates.api.registries.AnimationsRegistry;
 import fr.traqueur.crates.engine.ZScriptEngine;
+import fr.traqueur.crates.models.wrappers.ArrayHelper;
 import org.mozilla.javascript.*;
 
 import java.nio.file.Files;
@@ -36,6 +37,10 @@ protected Animation loadFile(Path file) {
             // Add the animation registration API
             ScriptableObject.putProperty(scope, "animations", Context.javaToJS(registrar, scope));
 
+            // Add array helper utility for JavaScript array conversions
+            ScriptableObject.putProperty(scope, "ArrayHelper",
+                Context.javaToJS(new ArrayHelper(), scope));
+
             // Execute the script
             engine.evaluateFile(scriptContent, file.getFileName().toString(), scope);