feat: Add spritesheet support for sprites

cursoragent · 4ian · cursoragent · commit a37b144da5a1 · 2025-12-06T14:59:49.000Z
Co-authored-by: florian &lt;florian@gdevelop.io&gt;
diff --git a/Core/GDCore/Extensions/Builtin/SpriteExtension/Direction.cpp b/Core/GDCore/Extensions/Builtin/SpriteExtension/Direction.cpp
@@ -98,6 +98,15 @@ void Direction::UnserializeFrom(const gd::SerializerElement& element) {
     Sprite sprite;
 
     sprite.SetImageName(spriteElement.GetStringAttribute("image"));
+    // Support for spritesheet frames (optional fields)
+    if (spriteElement.HasAttribute("spritesheetName")) {
+      sprite.SetSpritesheetName(
+          spriteElement.GetStringAttribute("spritesheetName"));
+    }
+    if (spriteElement.HasAttribute("spritesheetFrameName")) {
+      sprite.SetSpritesheetFrameName(
+          spriteElement.GetStringAttribute("spritesheetFrameName"));
+    }
     OpenPointsSprites(sprite.GetAllNonDefaultPoints(),
                       spriteElement.GetChild("points", 0, "Points"));
 
@@ -164,6 +173,15 @@ void SaveSpritesDirection(const vector<Sprite>& sprites,
     gd::SerializerElement& spriteElement = element.AddChild("sprite");
 
     spriteElement.SetAttribute("image", sprites[i].GetImageName());
+    // Save spritesheet fields if they are set
+    if (!sprites[i].GetSpritesheetName().empty()) {
+      spriteElement.SetAttribute("spritesheetName",
+                                 sprites[i].GetSpritesheetName());
+    }
+    if (!sprites[i].GetSpritesheetFrameName().empty()) {
+      spriteElement.SetAttribute("spritesheetFrameName",
+                                 sprites[i].GetSpritesheetFrameName());
+    }
     SavePointsSprites(sprites[i].GetAllNonDefaultPoints(),
                       spriteElement.AddChild("points"));
 
diff --git a/Core/GDCore/Extensions/Builtin/SpriteExtension/Direction.h b/Core/GDCore/Extensions/Builtin/SpriteExtension/Direction.h
@@ -24,6 +24,19 @@ namespace gd {
  *
  * \todo Support UTF8 (currently convert all loaded strings from UTF8 to the
  * current locale)
+ *
+ * \note Spritesheet support: Each Sprite in a Direction can use either:
+ * - A regular image resource (via Sprite::GetImageName())
+ * - A frame from a spritesheet (via Sprite::GetSpritesheetName() and
+ *   Sprite::GetSpritesheetFrameName())
+ *
+ * \note Future enhancement: The spritesheet JSON format may include an
+ * "animations" field that maps animation names to arrays of frame names.
+ * This could be used to automatically populate a Direction with all frames
+ * from a spritesheet animation. For example:
+ * - A Direction could be configured to use a spritesheet animation name
+ * - All frames from that animation would be automatically added to the Direction
+ * - This would simplify importing animations from tools like TexturePacker
  */
 class GD_CORE_API Direction {
  public:
diff --git a/Core/GDCore/Extensions/Builtin/SpriteExtension/Sprite.cpp b/Core/GDCore/Extensions/Builtin/SpriteExtension/Sprite.cpp
@@ -19,7 +19,9 @@ Sprite::Sprite()
     : fullImageCollisionMask(false),
       origine("origine"),
       centre("centre"),
-      automaticCentre(true) {}
+      automaticCentre(true),
+      spritesheetName(""),
+      spritesheetFrameName("") {}
 
 Sprite::~Sprite(){};
 
diff --git a/Core/GDCore/Extensions/Builtin/SpriteExtension/Sprite.h b/Core/GDCore/Extensions/Builtin/SpriteExtension/Sprite.h
@@ -42,6 +42,52 @@ class GD_CORE_API Sprite {
    */
   inline gd::String& GetImageName() { return image; }
 
+  /**
+   * \brief Set the spritesheet resource name and frame name.
+   * When both are set, the sprite will use a frame from a spritesheet instead of an image.
+   */
+  inline void SetSpritesheetName(const gd::String& spritesheetName_) {
+    spritesheetName = spritesheetName_;
+  }
+
+  /**
+   * \brief Get the spritesheet resource name.
+   */
+  inline const gd::String& GetSpritesheetName() const { return spritesheetName; }
+
+  /**
+   * \brief Get the spritesheet resource name.
+   */
+  inline gd::String& GetSpritesheetName() { return spritesheetName; }
+
+  /**
+   * \brief Set the frame name within the spritesheet.
+   */
+  inline void SetSpritesheetFrameName(const gd::String& frameName_) {
+    spritesheetFrameName = frameName_;
+  }
+
+  /**
+   * \brief Get the frame name within the spritesheet.
+   */
+  inline const gd::String& GetSpritesheetFrameName() const {
+    return spritesheetFrameName;
+  }
+
+  /**
+   * \brief Get the frame name within the spritesheet.
+   */
+  inline gd::String& GetSpritesheetFrameName() {
+    return spritesheetFrameName;
+  }
+
+  /**
+   * \brief Return true if the sprite uses a spritesheet frame instead of an image.
+   */
+  inline bool UsesSpritesheet() const {
+    return !spritesheetName.empty() && !spritesheetFrameName.empty();
+  }
+
   /**
    * \brief Get the collision mask (custom or automatically generated owing to
    * IsFullImageCollisionMask())
@@ -161,6 +207,8 @@ class GD_CORE_API Sprite {
 
  private:
   gd::String image;  ///< Name of the image to be loaded in Image Manager.
+  gd::String spritesheetName;  ///< Name of the spritesheet resource (if using spritesheet).
+  gd::String spritesheetFrameName;  ///< Name of the frame within the spritesheet (if using spritesheet).
 
   bool fullImageCollisionMask;  ///< True to use a bounding box wrapping the
                                 ///< whole image as collision mask. If false,
diff --git a/Core/GDCore/Project/ResourcesContainer.cpp b/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")
@@ -144,6 +146,7 @@ const gd::String Resource::audioType = "audio";
 const gd::String Resource::fontType = "font";
 const gd::String Resource::videoType = "video";
 const gd::String Resource::jsonType = "json";
+const gd::String Resource::spritesheetType = "spritesheet";
 const gd::String Resource::tileMapType = "tilemap";
 const gd::String Resource::tileSetType = "tileset";
 const gd::String Resource::bitmapType = "bitmapFont";
diff --git a/Core/GDCore/Project/ResourcesContainer.h b/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,22 @@ class GD_CORE_API AtlasResource : public Resource {
   gd::String file;
 };
 
+/**
+ * \brief Describe a spritesheet JSON file used by a project.
+ * A spritesheet contains frame definitions that reference an image resource.
+ *
+ * \see Resource
+ * \ingroup ResourcesManagement
+ */
+class GD_CORE_API SpritesheetResource : public JsonResource {
+public:
+  SpritesheetResource() : JsonResource() { SetKind("spritesheet"); };
+  virtual ~SpritesheetResource(){};
+  virtual SpritesheetResource *Clone() const override {
+    return new SpritesheetResource(*this);
+  }
+};
+
 /**
  * \brief Describe a JavaScript file used by a project.
  *
diff --git a/GDJS/Runtime/ResourceLoader.ts b/GDJS/Runtime/ResourceLoader.ts
@@ -146,6 +146,7 @@ namespace gdjs {
     private _bitmapFontManager: BitmapFontManager;
     private _spineAtlasManager: SpineAtlasManager | null = null;
     private _spineManager: SpineManager | null = null;
+    private _spritesheetManager: PixiSpritesheetManager | null = null;
     private _svgManager: InternalInGameEditorOnlySvgManager;
 
     /**
@@ -206,6 +207,12 @@ namespace gdjs {
         );
       }
 
+      // Create spritesheet manager
+      this._spritesheetManager = new gdjs.PixiSpritesheetManager(
+        this,
+        this._imageManager
+      );
+
       const resourceManagers: Array<ResourceManager> = [
         this._imageManager,
         this._soundManager,
@@ -214,6 +221,7 @@ namespace gdjs {
         this._bitmapFontManager,
         this._model3DManager,
         this._svgManager,
+        this._spritesheetManager,
       ];
 
       if (this._spineAtlasManager)
@@ -814,6 +822,15 @@ namespace gdjs {
       return this._spineAtlasManager;
     }
 
+    /**
+     * Get the Spritesheet manager of the game, used to load spritesheets from game
+     * resources.
+     * @return The Spritesheet manager for the game
+     */
+    getSpritesheetManager(): gdjs.PixiSpritesheetManager | null {
+      return this._spritesheetManager;
+    }
+
     injectMockResourceManagerForTesting(
       resourceKind: ResourceKind,
       resourceManager: ResourceManager
diff --git a/GDJS/Runtime/SpriteAnimator.ts b/GDJS/Runtime/SpriteAnimator.ts
@@ -33,6 +33,10 @@ namespace gdjs {
   export type SpriteFrameData = {
     /** The resource name of the image used in this frame. */
     image: string;
+    /** The spritesheet resource name (if using a spritesheet frame instead of an image). */
+    spritesheetName?: string;
+    /** The frame name within the spritesheet (if using a spritesheet frame instead of an image). */
+    spritesheetFrameName?: string;
     /** The points of the frame. */
     points: Array<SpriteCustomPointData>;
     /** The origin point. */
@@ -79,7 +83,11 @@ namespace gdjs {
    * Abstraction from graphic libraries texture classes.
    */
   export interface AnimationFrameTextureManager<T> {
-    getAnimationFrameTexture(imageName: string): T;
+    getAnimationFrameTexture(
+      imageName: string,
+      spritesheetName?: string,
+      spritesheetFrameName?: string
+    ): T;
     getAnimationFrameWidth(pixiTexture: T);
     getAnimationFrameHeight(pixiTexture: T);
   }
@@ -110,7 +118,11 @@ namespace gdjs {
       textureManager: gdjs.AnimationFrameTextureManager<T>
     ) {
       this.image = frameData ? frameData.image : '';
-      this.texture = textureManager.getAnimationFrameTexture(this.image);
+      this.texture = textureManager.getAnimationFrameTexture(
+        this.image,
+        frameData?.spritesheetName,
+        frameData?.spritesheetFrameName
+      );
       this.points = new Hashtable();
       this.reinitialize(frameData, textureManager);
     }
@@ -124,7 +136,11 @@ namespace gdjs {
       textureManager: gdjs.AnimationFrameTextureManager<T>
     ) {
       this.image = frameData.image;
-      this.texture = textureManager.getAnimationFrameTexture(this.image);
+      this.texture = textureManager.getAnimationFrameTexture(
+        this.image,
+        frameData.spritesheetName,
+        frameData.spritesheetFrameName
+      );
 
       this.points.clear();
       for (let i = 0, len = frameData.points.length; i < len; ++i) {
diff --git a/GDJS/Runtime/pixi-renderers/pixi-spritesheet-manager.ts b/GDJS/Runtime/pixi-renderers/pixi-spritesheet-manager.ts
diff --git a/GDJS/Runtime/pixi-renderers/spriteruntimeobject-pixi-renderer.ts b/GDJS/Runtime/pixi-renderers/spriteruntimeobject-pixi-renderer.ts
diff --git a/GDJS/Runtime/runtimegame.ts b/GDJS/Runtime/runtimegame.ts
diff --git a/GDJS/Runtime/spriteruntimeobject.ts b/GDJS/Runtime/spriteruntimeobject.ts
