feat: Add spritesheet support for sprites

This commit introduces support for spritesheets, allowing sprites to use frames from a spritesheet texture atlas instead of standalone images.

Key changes include:

- **Sprite Class:** Added `spritesheetResourceName` and `spritesheetFrameName` properties to the `Sprite` class to store spritesheet information.
- **Serialization:** Updated `Direction::UnserializeFrom` and `SaveSpritesDirection` to handle saving and loading spritesheet data.
- **Resource Management:**
    - Introduced `SpritesheetResource` to represent spritesheet files in the project.
    - Added `PixiSpritesheetManager` in GDJS to load and manage spritesheet JSON data and PIXI.Spritesheet objects.
    - Integrated spritesheet loading into `ResourceLoader` and `ArbitraryResourceWorker`.
- **Runtime:**
    - Modified `SpriteAnimator` and `SpriteAnimationFrame` to handle spritesheet frames.
    - Updated `PixiAnimationFrameTextureManager` and `PixiRenderer` to retrieve textures from spritesheets.
    - Added `getSpritesheetFrameTexture` to `CustomRuntimeObject3DRenderer` (though 3D objects do not support spritesheets).

This feature enhances the flexibility of sprite animations by enabling the use of more efficient texture atlases.

Co-authored-by: florian <[email protected]>

Author: cursoragent

Core/GDCore/Extensions/Builtin/SpriteExtension/Direction.cpp

@@ -98,6 +98,16 @@ void Direction::UnserializeFrom(const gd::SerializerElement& element) {
     Sprite sprite;
 
     sprite.SetImageName(spriteElement.GetStringAttribute("image"));
+
+    // Spritesheet support: load spritesheet resource name and frame name if present
+    if (spriteElement.HasAttribute("spritesheetResourceName") ||
+        spriteElement.HasChild("spritesheetResourceName")) {
+      sprite.SetSpritesheetResourceName(
+          spriteElement.GetStringAttribute("spritesheetResourceName", ""));
+      sprite.SetSpritesheetFrameName(
+          spriteElement.GetStringAttribute("spritesheetFrameName", ""));
+    }
+
     OpenPointsSprites(sprite.GetAllNonDefaultPoints(),
                       spriteElement.GetChild("points", 0, "Points"));
 
@@ -164,6 +174,15 @@ void SaveSpritesDirection(const vector<Sprite>& sprites,
     gd::SerializerElement& spriteElement = element.AddChild("sprite");
 
     spriteElement.SetAttribute("image", sprites[i].GetImageName());
+
+    // Spritesheet support: save spritesheet resource name and frame name if used
+    if (sprites[i].UsesSpritesheetFrame()) {
+      spriteElement.SetAttribute("spritesheetResourceName",
+                                 sprites[i].GetSpritesheetResourceName());
+      spriteElement.SetAttribute("spritesheetFrameName",
+                                 sprites[i].GetSpritesheetFrameName());
+    }
+
     SavePointsSprites(sprites[i].GetAllNonDefaultPoints(),
                       spriteElement.AddChild("points"));
 

Core/GDCore/Extensions/Builtin/SpriteExtension/Sprite.h

@@ -18,6 +18,13 @@ namespace gd {
 /**
  * \brief Represents a sprite to be displayed on the screen.
  *
+ * A sprite can display either:
+ * - A standalone image (using `image` field)
+ * - A frame from a spritesheet (using `spritesheetResourceName` and `spritesheetFrameName`)
+ *
+ * When using a spritesheet, the `image` field should be empty, and the texture
+ * will be obtained from the spritesheet's frame data.
+ *
  * \see Direction
  * \see SpriteObject
  * \ingroup SpriteObjectExtension
@@ -29,6 +36,7 @@ class GD_CORE_API Sprite {
 
   /**
    * \brief Change the name of the sprite image.
+   * \note When using a spritesheet, this should be empty.
    */
   inline void SetImageName(const gd::String& image_) { image = image_; }
 
@@ -42,6 +50,46 @@ class GD_CORE_API Sprite {
    */
   inline gd::String& GetImageName() { return image; }
 
+  /**
+   * \brief Set the spritesheet resource name for this frame.
+   * \note When set, the frame texture will be obtained from the spritesheet.
+   */
+  inline void SetSpritesheetResourceName(const gd::String& resourceName) {
+    spritesheetResourceName = resourceName;
+  }
+
+  /**
+   * \brief Get the spritesheet resource name for this frame.
+   * \return The spritesheet resource name, or empty string if not using a spritesheet.
+   */
+  inline const gd::String& GetSpritesheetResourceName() const {
+    return spritesheetResourceName;
+  }
+
+  /**
+   * \brief Set the frame name within the spritesheet.
+   * \note This corresponds to a key in the "frames" object of the spritesheet JSON.
+   */
+  inline void SetSpritesheetFrameName(const gd::String& frameName) {
+    spritesheetFrameName = frameName;
+  }
+
+  /**
+   * \brief Get the frame name within the spritesheet.
+   * \return The frame name within the spritesheet, or empty string if not using a spritesheet.
+   */
+  inline const gd::String& GetSpritesheetFrameName() const {
+    return spritesheetFrameName;
+  }
+
+  /**
+   * \brief Check if this sprite uses a spritesheet frame.
+   * \return true if using a spritesheet frame, false if using a standalone image.
+   */
+  inline bool UsesSpritesheetFrame() const {
+    return !spritesheetResourceName.empty() && !spritesheetFrameName.empty();
+  }
+
   /**
    * \brief Get the collision mask (custom or automatically generated owing to
    * IsFullImageCollisionMask())
@@ -162,6 +210,11 @@ class GD_CORE_API Sprite {
  private:
   gd::String image;  ///< Name of the image to be loaded in Image Manager.
 
+  // Spritesheet support: if spritesheetResourceName is not empty, the texture
+  // is obtained from the spritesheet's frame data instead of the image field.
+  gd::String spritesheetResourceName;  ///< Name of the spritesheet resource (if using spritesheet).
+  gd::String spritesheetFrameName;     ///< Frame name within the spritesheet (key in "frames" object).
+
   bool fullImageCollisionMask;  ///< True to use a bounding box wrapping the
                                 ///< whole image as collision mask. If false,
                                 ///< custom collision mask is used.

Core/GDCore/Extensions/Builtin/SpriteExtension/SpriteAnimationList.cpp

@@ -109,8 +109,21 @@ void SpriteAnimationList::ExposeResources(gd::ArbitraryResourceWorker& worker) {
       for (std::size_t l = 0;
            l < GetAnimation(j).GetDirection(k).GetSpritesCount();
            l++) {
-        worker.ExposeImage(
-            GetAnimation(j).GetDirection(k).GetSprite(l).GetImageName());
+        Sprite& sprite = GetAnimation(j).GetDirection(k).GetSprite(l);
+        
+        // Expose either the image or the spritesheet resource
+        if (sprite.UsesSpritesheetFrame()) {
+          // Expose the spritesheet resource (and its embedded image)
+          gd::String spritesheetResourceName = sprite.GetSpritesheetResourceName();
+          worker.ExposeSpritesheet(spritesheetResourceName);
+          
+          // Update the resource name if it was changed by the worker
+          if (spritesheetResourceName != sprite.GetSpritesheetResourceName()) {
+            sprite.SetSpritesheetResourceName(spritesheetResourceName);
+          }
+        } else {
+          worker.ExposeImage(sprite.GetImageName());
+        }
       }
     }
   }

Core/GDCore/Extensions/Builtin/SpriteExtension/SpriteAnimationList.h

@@ -22,6 +22,35 @@ namespace gd {
  * 
  * It's used in the configuration of object that implements image-based animations.
  *
+ * ## Spritesheet Support
+ *
+ * Individual sprites (frames) can use textures from spritesheets. When a sprite's
+ * `spritesheetResourceName` and `spritesheetFrameName` are set, the texture is
+ * obtained from the spritesheet's frame data instead of a standalone image.
+ *
+ * ### Future Improvements (Spritesheet Animation Import)
+ *
+ * Spritesheet JSON files can contain animation definitions in their `meta.animations`
+ * field. These are arrays of frame names that define complete animations. For example:
+ * 
+ * ```json
+ * {
+ *   "frames": { "walk1": {...}, "walk2": {...}, "idle1": {...}, "idle2": {...} },
+ *   "meta": {
+ *     "image": "sprites.png",
+ *     "animations": {
+ *       "walk": ["walk1", "walk2"],
+ *       "idle": ["idle1", "idle2"]
+ *     }
+ *   }
+ * }
+ * ```
+ *
+ * A future improvement could add methods to:
+ * - Import all frames from a spritesheet as a Direction
+ * - Import animation definitions from `meta.animations` as complete Animations
+ * - The Sprite editor could provide UI to import spritesheet animations directly
+ *
  * \see Animation
  * \see Direction
  * \see Sprite

Core/GDCore/IDE/Project/ArbitraryResourceWorker.cpp

@@ -62,6 +62,11 @@ void ArbitraryResourceWorker::ExposeSpine(gd::String& resourceName){
     // do.
 };
 
+void ArbitraryResourceWorker::ExposeSpritesheet(gd::String& resourceName){
+    // Nothing to do by default - each child class can define here the action to
+    // do.
+};
+
 void ArbitraryResourceWorker::ExposeJavaScript(gd::String& resourceName){
     // Nothing to do by default - each child class can define here the action to
     // do.
@@ -200,6 +205,11 @@ void ArbitraryResourceWorker::ExposeResourceWithType(
     ExposeSpine(resourceName);
     return;
   }
+  if (resourceType == "spritesheet") {
+    ExposeSpritesheet(resourceName);
+    ExposeEmbeddeds(resourceName);
+    return;
+  }
   if (resourceType == "javascript") {
     ExposeJavaScript(resourceName);
     return;

Core/GDCore/IDE/Project/ArbitraryResourceWorker.h

@@ -107,6 +107,11 @@ class GD_CORE_API ArbitraryResourceWorker {
    */
   virtual void ExposeSpine(gd::String &resourceName);
 
+  /**
+   * \brief Expose a spritesheet, which is always a reference to a "spritesheet" resource.
+   */
+  virtual void ExposeSpritesheet(gd::String &resourceName);
+
   /**
    * \brief Expose a video, which is always a reference to a "video" resource.
    */

Core/GDCore/Project/ResourcesContainer.cpp

@@ -130,6 +130,8 @@ ResourcesContainer::CreateResource(const gd::String &kind) {
     return std::make_shared<AtlasResource>();
   else if (kind == "spine")
     return std::make_shared<SpineResource>();
+  else if (kind == "spritesheet")
+    return std::make_shared<SpritesheetResource>();
   else if (kind == "javascript")
     return std::make_shared<JavaScriptResource>();
   else if (kind == "internal-in-game-editor-only-svg")
@@ -150,6 +152,7 @@ const gd::String Resource::bitmapType = "bitmapFont";
 const gd::String Resource::model3DType = "model3D";
 const gd::String Resource::atlasType = "atlas";
 const gd::String Resource::spineType = "spine";
+const gd::String Resource::spritesheetType = "spritesheet";
 const gd::String Resource::javaScriptType = "javascript";
 const gd::String Resource::internalInGameEditorOnlySvgType = "internal-in-game-editor-only-svg";
 
@@ -616,6 +619,20 @@ void AtlasResource::SerializeTo(SerializerElement &element) const {
   element.SetAttribute("file", GetFile());
 }
 
+void SpritesheetResource::SetFile(const gd::String &newFile) {
+  file = NormalizePathSeparator(newFile);
+}
+
+void SpritesheetResource::UnserializeFrom(const SerializerElement &element) {
+  SetUserAdded(element.GetBoolAttribute("userAdded"));
+  SetFile(element.GetStringAttribute("file"));
+}
+
+void SpritesheetResource::SerializeTo(SerializerElement &element) const {
+  element.SetAttribute("userAdded", IsUserAdded());
+  element.SetAttribute("file", GetFile());
+}
+
 void JavaScriptResource::SetFile(const gd::String &newFile) {
   file = NormalizePathSeparator(newFile);
 }

Core/GDCore/Project/ResourcesContainer.h

@@ -37,6 +37,7 @@ class GD_CORE_API Resource {
   static const gd::String model3DType;
   static const gd::String atlasType;
   static const gd::String spineType;
+  static const gd::String spritesheetType;
   static const gd::String javaScriptType;
   static const gd::String internalInGameEditorOnlySvgType;
 
@@ -566,6 +567,37 @@ class GD_CORE_API AtlasResource : public Resource {
   gd::String file;
 };
 
+/**
+ * \brief Describe a spritesheet JSON file used by a project.
+ *
+ * A spritesheet resource contains JSON data that describes frames in a texture
+ * atlas. The JSON format follows the standard PixiJS/TexturePacker format with
+ * "frames" (mapping frame names to coordinates/dimensions) and "meta" (containing
+ * the texture image reference).
+ *
+ * \see Resource
+ * \ingroup ResourcesManagement
+ */
+class GD_CORE_API SpritesheetResource : public Resource {
+public:
+  SpritesheetResource() : Resource() { SetKind("spritesheet"); };
+  virtual ~SpritesheetResource(){};
+  virtual SpritesheetResource *Clone() const override {
+    return new SpritesheetResource(*this);
+  }
+
+  virtual const gd::String &GetFile() const override { return file; };
+  virtual void SetFile(const gd::String &newFile) override;
+
+  virtual bool UseFile() const override { return true; }
+  void SerializeTo(SerializerElement &element) const override;
+
+  void UnserializeFrom(const SerializerElement &element) override;
+
+private:
+  gd::String file;
+};
+
 /**
  * \brief Describe a JavaScript file used by a project.
  *

Extensions/3D/CustomRuntimeObject3DRenderer.ts

@@ -163,6 +163,22 @@ namespace gdjs {
       });
     }
 
+    getSpritesheetFrameTexture(
+      spritesheetResourceName: string,
+      frameName: string
+    ): THREE.Material {
+      // Spritesheet frames are not supported for 3D objects.
+      // Return an invalid/empty material.
+      console.warn(
+        'Spritesheet frames are not supported for 3D objects. Returning empty material.'
+      );
+      return this._imageManager.getThreeMaterial('', {
+        useTransparentTexture: true,
+        forceBasicMaterial: true,
+        vertexColors: false,
+      });
+    }
+
     getAnimationFrameWidth(material: THREE.Material) {
       const map = (
         material as THREE.MeshBasicMaterial | THREE.MeshStandardMaterial

GDJS/Runtime/ResourceCache.ts

@@ -50,5 +50,13 @@ namespace gdjs {
       this._nameToContent.clear();
       this._fileToContent.clear();
     }
+
+    /**
+     * Get all the values stored in the cache.
+     * @returns An iterable of all cached content values.
+     */
+    getAllValues(): IterableIterator<C> {
+      return this._nameToContent.values();
+    }
   }
 }