add builder for addAnimation

Author: mikebarkmin

CHANGELOG.md

@@ -4,6 +4,20 @@ index: 4
 lang: en
 ---
 
+## 4.21.0
+
+- 🚀 Feat: Add `addAnimation` with a builder function to the AnimatedSprite
+class. This allows you to add animations with a more flexible API. The function
+receives the frame number and returns the path to the image for that frame.
+This is useful if you want to generate the image path dynamically or if you
+want to use a naming convention for your images. To be consistant with the
+pattern the frames start counting at 1.
+
+```java
+mySprite.addAnimation("run", frame -> "test" + frame + ".png", 10);
+```
+
+
 ## 4.20.0
 
 - 🚀 Feat: Add 9-Slice scaling to the Sprite class. This allows you to scale a sprite in a way that the corners are not stretched, but the middle part is stretched. This is useful for UI elements like buttons or panels.

docs/de/book/reference/extensions/animation/animated-sprite/looks/addAnimation.md.json

@@ -7,6 +7,7 @@
   "description": "Fügt eine Animation hinzu. Die Animation kann entweder eine Reihe von einzelnen Bildern oder ein Teil eines Spritesheets sein.",
   "syntax": [
     ".addAnimation(name, pattern, frames)",
+    ".addAnimation(name, builder, frames)",
     ".addAnimation(name, path, frames, width, height)",
     ".addAnimation(name, path, frames, width, height, row)"
   ],
@@ -42,6 +43,11 @@
       "description": "Ein Muster für das Finden von Bilden, welche die einzelnen Frames der Animation repräsentieren.",
       "type": "String"
     },
+    {
+      "name": "builder",
+      "description": "Eine Funktion, die einen String für jedes Frame der Animation zurückgibt. Diese Funktion wird aufgerufen, um die Bilder zu laden.",
+      "type": "Function<Integer, String>"
+    },
     {
       "name": "frames",
       "description": "Die Anzahl der Frames der Animation.",

docs/en/book/reference/extensions/animation/animated-sprite/looks/addAnimation.md.json

@@ -7,6 +7,7 @@
   "description": "Add an animation to the sprite. The animation can either be multiple images or parts of a spritesheet.",
   "syntax": [
     ".addAnimation(name, pattern, frames)",
+    ".addAnimation(name, builder, frames)",
     ".addAnimation(name, path, frames, width, height)",
     ".addAnimation(name, path, frames, width, height, row)"
   ],
@@ -42,6 +43,11 @@
       "description": "A pattern for finding images representing the frames.",
       "type": "String"
     },
+    {
+      "name": "builder",
+      "description": "A function that returns a String for each frame of the animation. This function is called to load the images.",
+      "type": "Function<Integer, String>"
+    },
     {
       "name": "frames",
       "description": "The number of frames for this animation.",

resources/build.properties

@@ -40,7 +40,7 @@ author.url=https://openpatch.org
 # This is NOT a direct link to where to download it.
 
 library.url=https://github.com/openpatch/scratch-for-java
-library.version=4.20.0
+library.version=4.21.0
 
 
 # Set the category (or categories) of your Library from the following list:

src/org/openpatch/scratch/extensions/animation/AnimatedSprite.java

@@ -4,11 +4,14 @@
 import org.openpatch.scratch.Sprite;
 
 /**
- * The AnimatedSprite class represents a sprite that can play animations. It extends the Sprite
- * class and provides methods to add animations, play animations, set the interval between animation
+ * The AnimatedSprite class represents a sprite that can play animations. It
+ * extends the Sprite
+ * class and provides methods to add animations, play animations, set the
+ * interval between animation
  * frames, and reset the animation.
  *
- * <p>Example usage:
+ * <p>
+ * Example usage:
  *
  * <pre>{@code
  * AnimatedSprite sprite = new AnimatedSprite();
@@ -29,9 +32,10 @@ public class AnimatedSprite extends Sprite {
   /**
    * Adds an animation to the sprite.
    *
-   * @param name the name of the animation
-   * @param pattern the pattern (@see String#format) of the file names
-   * @param frames the number of frames in the animation
+   * @param name    the name of the animation
+   * @param pattern the pattern (@see String#format) of the file names. The frame
+   *                starts from 1.
+   * @param frames  the number of frames in the animation
    */
   public void addAnimation(String name, String pattern, int frames) {
     String[] animation = new String[frames];
@@ -47,10 +51,29 @@ public void addAnimation(String name, String pattern, int frames) {
   /**
    * Adds an animation to the sprite.
    *
-   * @param name the name of the animation
-   * @param path the path to the animation frames
+   * @param name    the name of the animation
+   * @param builder a function that builds the file names for the animation frames
+   * @param frame   the number of frames in the animation. The frame starts from
+   *                1.
+   */
+  public void addAnimation(
+      String name, java.util.function.Function<Integer, String> builder, int frame) {
+    String[] animation = new String[frame];
+    for (int i = 0; i < animation.length; i++) {
+      String costumeName = "_animation_" + name + "_" + i;
+      this.addCostume(costumeName, builder.apply(i + 1));
+      animation[i] = costumeName;
+    }
+    animations.put(name, animation);
+  }
+
+  /**
+   * Adds an animation to the sprite.
+   *
+   * @param name   the name of the animation
+   * @param path   the path to the animation frames
    * @param frames the number of frames in the animation
-   * @param width the width of each frame
+   * @param width  the width of each frame
    * @param height the height of each frame
    */
   public void addAnimation(String name, String path, int frames, int width, int height) {
@@ -60,12 +83,12 @@ public void addAnimation(String name, String path, int frames, int width, int he
   /**
    * Adds an animation to the sprite.
    *
-   * @param name the name of the animation
-   * @param path the path to the animation frames
+   * @param name   the name of the animation
+   * @param path   the path to the animation frames
    * @param frames the number of frames in the animation
-   * @param width the width of each frame
+   * @param width  the width of each frame
    * @param height the height of each frame
-   * @param row the row of the animation frames
+   * @param row    the row of the animation frames
    */
   public void addAnimation(String name, String path, int frames, int width, int height, int row) {
     String[] animation = new String[frames];
@@ -80,12 +103,12 @@ public void addAnimation(String name, String path, int frames, int width, int he
   /**
    * Adds an animation to the sprite.
    *
-   * @param name the name of the animation
-   * @param path the path to the animation frames
-   * @param frames the number of frames in the animation
-   * @param width the width of each frame
-   * @param height the height of each frame
-   * @param column the column of the animation frames
+   * @param name       the name of the animation
+   * @param path       the path to the animation frames
+   * @param frames     the number of frames in the animation
+   * @param width      the width of each frame
+   * @param height     the height of each frame
+   * @param column     the column of the animation frames
    * @param useColumns whether to use columns or rows
    */
   public void addAnimation(