Allow defining intermediary elements in animations

Author: NichtStudioCode

invui/src/main/java/xyz/xenondevs/invui/gui/AbstractGui.java

@@ -506,7 +506,7 @@ public void playAnimation(Animation animation) {
         this.animationElements = slotElements.clone();
         animationImpl.bind(this);
         for (Slot slot : animationImpl.getRemainingSlots()) {
-            setSlotElement(slot.x(), slot.y(), null);
+            setSlotElement(slot.x(), slot.y(), animationImpl.getIntermediarySlotElement(slot));
         }
         animationImpl.addShowHandler(slots -> {
             for (Slot slot : slots) {

invui/src/main/java/xyz/xenondevs/invui/gui/Animation.java

@@ -1,7 +1,10 @@
 package xyz.xenondevs.invui.gui;
 
 import org.bukkit.Sound;
+import org.jspecify.annotations.Nullable;
 import xyz.xenondevs.invui.internal.util.ArrayUtils;
+import xyz.xenondevs.invui.item.Item;
+import xyz.xenondevs.invui.item.ItemProvider;
 
 import java.util.Set;
 import java.util.function.BiConsumer;
@@ -16,6 +19,8 @@
  * <ul>
  *     <li>Slot filter: Defines which slots are part of the animation.</li>
  *     <li>Slot selector: Selects the slots that are shown in each frame.</li>
+ *     <li>Intermediary generator: Creates intermediary {@link SlotElement SlotElements} that are displayed before
+ *     the slots pop in.</li>
  *     <li>Show handler: Called when slot(s) are shown, for example to play a sound effect.</li>
  *     <li>Finish handler: Called when the animation is finished.</li>
  * </ul>
@@ -168,7 +173,7 @@ sealed interface Builder permits AnimationImpl.BuilderImpl {
          * @param filter The filter defining which slots are part of the animation.
          * @return This {@link Builder Animation builder}
          */
-        Builder addSlotFilter(BiPredicate<Gui, Slot> filter);
+        Builder addSlotFilter(BiPredicate<? super Gui, ? super Slot> filter);
 
         /**
          * Adds a {@link #addSlotFilter(BiPredicate) filter} that ignores all empty slots.
@@ -217,23 +222,67 @@ default Builder addSoundEffect(Sound sound, float volume, float pitch) {
          * @param selector The slot selector for the animation.
          * @return This {@link Builder Animation builder}
          */
-        Builder setSlotSelector(Function<Animation, Set<Slot>> selector);
+        Builder setSlotSelector(Function<? super Animation, ? extends Set<? extends Slot>> selector);
+        
+        /**
+         * Sets the intermediary {@link ItemProvider} that is displayed before the slots pop in.
+         *
+         * @param provider The intermediary {@link ItemProvider}.
+         * @return This {@link Builder Animation builder}
+         */
+        default Builder setIntermediary(ItemProvider provider) {
+            return setIntermediary(Item.simple(provider));
+        }
+        
+        /**
+         * Sets the intermediary {@link Item} that is displayed before the slots pop in.
+         *
+         * @param item The intermediary {@link Item}.
+         * @return This {@link Builder Animation builder}
+         */
+        default Builder setIntermediary(Item item) {
+            var element = new SlotElement.Item(item);
+            return setIntermediaryElementGenerator(slot -> element);
+        }
+        
+        /**
+         * Sets the generator function that creates intermediary {@link ItemProvider ItemProviders} that are displayed
+         * before the {@link Gui Gui's} slots pop in.
+         *
+         * @param intermediaryGenerator The generator function that creates intermediary {@link ItemProvider ItemProviders}.
+         * @return This {@link Builder Animation builder}
+         */
+        default Builder setIntermediaryGenerator(Function<? super Slot, ? extends @Nullable ItemProvider> intermediaryGenerator) {
+            return setIntermediaryElementGenerator(slot -> {
+                ItemProvider provider = intermediaryGenerator.apply(slot);
+                return provider != null ? new SlotElement.Item(Item.simple(provider)) : null;
+            });
+        }
+        
+        /**
+         * Sets the generator function that creates intermediary {@link SlotElement SlotElements} that are displayed
+         * before the {@link Gui Gui's} slots pop in.
+         *
+         * @param intermediaryGenerator The generator function that creates intermediary {@link SlotElement SlotElements}.
+         * @return This {@link Builder Animation builder}
+         */
+        Builder setIntermediaryElementGenerator(Function<? super Slot, ? extends @Nullable SlotElement> intermediaryGenerator);
 
         /**
          * Adds a handler that is called when slot(s) are shown.
          *
          * @param showHandler The handler that is called when slot(s) are shown.
          * @return This {@link Builder Animation builder}
          */
-        Builder addShowHandler(BiConsumer<Animation, Set<Slot>> showHandler);
+        Builder addShowHandler(BiConsumer<? super Animation, ? super Set<? extends Slot>> showHandler);
 
         /**
          * Adds a handler that is called when the animation is finished.
          *
          * @param finishHandler The handler that is called when the animation is finished.
          * @return This {@link Builder Animation builder}
          */
-        Builder addFinishHandler(Consumer<Animation> finishHandler);
+        Builder addFinishHandler(Consumer<? super Animation> finishHandler);
 
         /**
          * Builds the animation.

invui/src/main/java/xyz/xenondevs/invui/gui/AnimationImpl.java

@@ -17,10 +17,11 @@
 final class AnimationImpl implements Animation {
 
     private final int tickDelay;
-    private final BiPredicate<Gui, Slot> slotFilter;
-    private final Function<Animation, Set<Slot>> slotSelector;
-    private BiConsumer<Animation, Set<Slot>> showHandler;
-    private Consumer<Animation> finishHandler;
+    private final BiPredicate<? super Gui, ? super Slot> slotFilter;
+    private final Function<? super Animation, ? extends Set<? extends Slot>> slotSelector;
+    private final Function<? super Slot, ? extends @Nullable SlotElement> intermediaryGenerator;
+    private BiConsumer<? super Animation, Set<? extends Slot>> showHandler;
+    private Consumer<? super Animation> finishHandler;
 
     private final Set<Slot> remainingSlots = new HashSet<>();
     private @Nullable Gui gui;
@@ -30,14 +31,16 @@ final class AnimationImpl implements Animation {
 
     public AnimationImpl(
         int tickDelay,
-        BiPredicate<Gui, Slot> slotFilter,
-        Function<Animation, Set<Slot>> slotSelector,
-        BiConsumer<Animation, Set<Slot>> showHandler,
-        Consumer<Animation> finishHandler
+        BiPredicate<? super Gui, ? super Slot> slotFilter,
+        Function<? super Animation, ? extends Set<? extends Slot>> slotSelector,
+        Function<? super Slot, ? extends @Nullable SlotElement> intermediaryGenerator,
+        BiConsumer<? super Animation, Set<? extends Slot>> showHandler,
+        Consumer<? super Animation> finishHandler
     ) {
         this.tickDelay = tickDelay;
         this.slotFilter = slotFilter;
         this.slotSelector = slotSelector;
+        this.intermediaryGenerator = intermediaryGenerator;
         this.showHandler = showHandler;
         this.finishHandler = finishHandler;
     }
@@ -65,14 +68,18 @@ public boolean isFinished() {
         return remainingSlots.isEmpty();
     }
 
-    public void addShowHandler(Consumer<Set<Slot>> showHandler) {
+    public void addShowHandler(Consumer<? super Set<? extends Slot>> showHandler) {
         this.showHandler = this.showHandler.andThen((animation, slot) -> showHandler.accept(slot));
     }
 
     public void addFinishHandler(Runnable finishHandler) {
         this.finishHandler = this.finishHandler.andThen(animation -> finishHandler.run());
     }
 
+    public @Nullable SlotElement getIntermediarySlotElement(Slot slot) {
+        return intermediaryGenerator.apply(slot);
+    }
+    
     /**
      * Binds the animation to a gui and populates the remaining slots.
      *
@@ -135,9 +142,10 @@ static final class BuilderImpl implements Animation.Builder {
 
         private int tickDelay = 1;
         private BiPredicate<Gui, Slot> slotFilter = (gui, slot) -> true;
-        private BiConsumer<Animation, Set<Slot>> showHandler = (animation, slot) -> {};
+        private @Nullable Function<? super Animation, ? extends Set<? extends Slot>> slotSelector;
+        private Function<? super Slot, ? extends @Nullable SlotElement> intermediaryGenerator = slot -> null;
+        private BiConsumer<Animation, Set<? extends Slot>> showHandler = (animation, slot) -> {};
         private Consumer<Animation> finishHandler = gui -> {};
-        private @Nullable Function<Animation, Set<Slot>> slotSelector;
 
         @Override
         public Animation.Builder setTickDelay(int tickDelay) {
@@ -146,25 +154,31 @@ public Animation.Builder setTickDelay(int tickDelay) {
         }
 
         @Override
-        public Animation.Builder setSlotSelector(Function<Animation, Set<Slot>> selector) {
+        public Animation.Builder setSlotSelector(Function<? super Animation, ? extends Set<? extends Slot>> selector) {
             this.slotSelector = selector;
             return this;
         }
 
         @Override
-        public Animation.Builder addShowHandler(BiConsumer<Animation, Set<Slot>> showHandler) {
+        public Builder setIntermediaryElementGenerator(Function<? super Slot, ? extends @Nullable SlotElement> intermediaryGenerator) {
+            this.intermediaryGenerator = intermediaryGenerator;
+            return this;
+        }
+        
+        @Override
+        public Animation.Builder addShowHandler(BiConsumer<? super Animation, ? super Set<? extends Slot>> showHandler) {
             this.showHandler = this.showHandler.andThen(showHandler);
             return this;
         }
 
         @Override
-        public Animation.Builder addFinishHandler(Consumer<Animation> finishHandler) {
+        public Animation.Builder addFinishHandler(Consumer<? super Animation> finishHandler) {
             this.finishHandler = this.finishHandler.andThen(finishHandler);
             return this;
         }
 
         @Override
-        public Animation.Builder addSlotFilter(BiPredicate<Gui, Slot> filter) {
+        public Animation.Builder addSlotFilter(BiPredicate<? super Gui, ? super Slot> filter) {
             this.slotFilter = this.slotFilter.and(filter);
             return this;
         }
@@ -174,7 +188,7 @@ public Animation build() {
             if (slotSelector == null)
                 throw new IllegalStateException("SlotSelector needs to be set");
 
-            return new AnimationImpl(tickDelay, slotFilter, slotSelector, showHandler, finishHandler);
+            return new AnimationImpl(tickDelay, slotFilter, slotSelector, intermediaryGenerator, showHandler, finishHandler);
         }
 
     }

invui/src/test/java/xyz/xenondevs/invui/gui/AnimationTest.java

@@ -1,6 +1,7 @@
 package xyz.xenondevs.invui.gui;
 
 import org.bukkit.Material;
+import org.bukkit.entity.Player;
 import org.bukkit.inventory.ItemStack;
 import org.junit.jupiter.api.AfterAll;
 import org.junit.jupiter.api.BeforeAll;
@@ -681,6 +682,54 @@ public void testAnimationCannotBePlayedTwice() {
         assertThrows(IllegalStateException.class, () -> gui2.playAnimation(rowAnimation));
     }
 
+    @Test
+    public void testIntermediaryGenerator() {
+        Player player = server.addPlayer();
+        
+        Gui gui1 = createTestGui();
+        Animation rowAnimation = Animation.row()
+            .setIntermediaryElementGenerator(s -> new SlotElement.Item(Item.simple(ItemStack.of(Material.STONE, s.y() * 9 + s.x() + 1))))
+            .build();
+        
+        gui1.playAnimation(rowAnimation);
+        
+        for (int i = 0; i < 9 * 4; i++) {
+            SlotElement element = gui1.getSlotElement(i);
+            assertNotNull(element, "i: " + i);
+            ItemStack itemStack = element.getItemStack(player);
+            assertNotNull(itemStack, "i: " + i);
+            assertEquals(i + 1, itemStack.getAmount(), "i: " + i);
+        }
+        
+        server.getScheduler().performTicks(2);
+        
+        for (int i = 0; i < 9 * 2; i++) {
+            SlotElement element = gui1.getSlotElement(i);
+            assertNotNull(element, "i: " + i);
+            ItemStack itemStack = element.getItemStack(player);
+            assertNotNull(itemStack, "i: " + i);
+            assertEquals(Material.DIAMOND, itemStack.getType(), "i: " + i);
+        }
+        for (int i = 9 * 2; i < 9 * 4; i++) {
+            SlotElement element = gui1.getSlotElement(i);
+            assertNotNull(element, "i: " + i);
+            ItemStack itemStack = element.getItemStack(player);
+            assertNotNull(itemStack, "i: " + i);
+            assertEquals(i + 1, itemStack.getAmount(), "i: " + i);
+        }
+        
+        server.getScheduler().performTicks(2);
+        assertTrue(rowAnimation.isFinished());
+        
+        for (int i = 0; i < 9 * 4; i++) {
+            SlotElement element = gui1.getSlotElement(i);
+            assertNotNull(element, "i: " + i);
+            ItemStack itemStack = element.getItemStack(player);
+            assertNotNull(itemStack, "i: " + i);
+            assertEquals(Material.DIAMOND, itemStack.getType(), "i: " + i);
+        }
+    }
+    
     private Gui createOddTestGui() {
         Gui gui = Gui.empty(3, 1);
         gui.fill(Item.simple(new ItemStack(Material.DIAMOND)), true);