Add UUIDs to layers

data/strings/en.ini

@@ -983,6 +983,7 @@ visible_layers = Visible layers
 [layer_properties]
 title = Layer Properties
 name = Name:
+uuid = UUID:
 mode = Mode:
 opacity = Opacity:
 tileset_tooltip = Tileset
@@ -1774,6 +1775,8 @@ change_sprite_props = Change Sprite Properties
 tilesets = Tilesets
 delete_tileset = Delete
 duplicate_tileset = Duplicate
+use_uuid_for_layers = Use Universally Unique Identifiers for layers
+use_uuid_for_layers_tooltip = By checking this a UUID will be automatically assigned to each layer
 
 [sprite_size]
 title = Sprite Size

data/widgets/layer_properties.xml

@@ -15,6 +15,9 @@
 
       <label text="@.opacity" />
       <opacityslider id="opacity" width="128" cell_align="horizontal" cell_hspan="2" />
+
+      <label id="uuid_label" text="@.uuid" visible="false" />
+      <label id="uuid" cell_hspan="2" visible="false"/>
     </grid>
   </vbox>
 </window>

data/widgets/sprite_properties.xml

@@ -42,6 +42,8 @@
           <button id="convert_color_profile" text="@.convert" />
         </hbox>
       </hbox>
+
+      <check text="@.use_uuid_for_layers" id="use_uuid_for_layers" tooltip="@.use_uuid_for_layers_tooltip" cell_hspan="2" />
     </grid>
 
     <vbox expansive="true" id="tilesets_placeholder">

docs/ase-file-specs.md

@@ -79,6 +79,7 @@ A 128-byte header (same as FLC/FLI header, but with other magic number):
                   1 = Layer opacity has valid value
                   2 = Layer blend mode/opacity is valid for groups
                       (composite groups separately first when rendering)
+                  4 = Layers are using UUIDs
     WORD        Speed (milliseconds between frame, like in FLC files)
                 DEPRECATED: You should use the frame duration field
                 from each frame header
@@ -202,6 +203,8 @@ entire layers layout:
     STRING      Layer name
     + If layer type = 2
       DWORD     Tileset index
+    UUID        Layer's universally unique identifier (present only if the
+                [main header](#header) "Flags" field has the bit 3 enabled)
 
 ### Cel Chunk (0x2005)
 

src/app/commands/cmd_layer_properties.cpp

@@ -32,6 +32,7 @@
 #include "app/ui/timeline/timeline.h"
 #include "app/ui/user_data_view.h"
 #include "app/ui_context.h"
+#include "base/convert_to.h"
 #include "base/scoped_value.h"
 #include "doc/image.h"
 #include "doc/layer.h"
@@ -463,6 +464,14 @@ private:
       m_userDataView.setVisible(false, false);
     }
 
+    bool uuidVisible = m_document && m_document->sprite() &&
+                       m_document->sprite()->useUuidsForLayers();
+    uuidLabel()->setVisible(uuidVisible);
+    uuid()->setVisible(uuidVisible);
+
+    if (uuidVisible)
+      uuid()->setText(m_layer ? base::convert_to<std::string>(m_layer->uuid()) : "");
+
     if (tileset()->isVisible() != tilemapVisibility) {
       tileset()->setVisible(tilemapVisibility);
       tileset()->parent()->layout();

src/app/commands/cmd_sprite_properties.cpp

@@ -142,6 +142,8 @@ public:
   {
     userData()->Click.connect([this] { onToggleUserData(); });
 
+    useUuidForLayers()->setSelected(sprite->useUuidsForLayers());
+
     m_userDataView.configureAndSet(m_sprite->userData(), propertiesGrid());
 
     if (sprite->tilesets()->size() == 0) {
@@ -397,6 +399,8 @@ void SpritePropertiesCommand::onExecute(Context* context)
 
     const UserData newUserData = window.getUserData();
 
+    sprite->setUseUuidsForLayers(window.useUuidForLayers()->isSelected());
+
     if (index != sprite->transparentColor() || pixelRatio != sprite->pixelRatio() ||
         newUserData != sprite->userData()) {
       Tx tx(writer, Strings::sprite_properties_change_sprite_props());

src/doc/layer.cpp

@@ -1,5 +1,5 @@
 // Aseprite Document Library
-// Copyright (C) 2019-2021  Igara Studio S.A.
+// Copyright (C) 2019-2025  Igara Studio S.A.
 // Copyright (C) 2001-2018  David Capello
 //
 // This file is released under the terms of the MIT license.
@@ -36,6 +36,9 @@ Layer::Layer(ObjectType type, Sprite* sprite)
          type == ObjectType::LayerTilemap);
 
   setName("Layer");
+  // Always generate a UUID for this layer, but take into account that it could
+  // be replaced. For instance, when loading a layer that already had a UUID.
+  m_uuid = base::Uuid::Generate();
 }
 
 Layer::~Layer()

src/doc/layer.h

@@ -1,5 +1,5 @@
 // Aseprite Document Library
-// Copyright (C) 2019-2024  Igara Studio S.A.
+// Copyright (C) 2019-2025  Igara Studio S.A.
 // Copyright (C) 2001-2018  David Capello
 //
 // This file is released under the terms of the MIT license.
@@ -9,6 +9,7 @@
 #define DOC_LAYER_H_INCLUDED
 #pragma once
 
+#include "base/uuid.h"
 #include "doc/blend_mode.h"
 #include "doc/cel_list.h"
 #include "doc/frame.h"
@@ -128,6 +129,9 @@ public:
   int opacity() const { return m_opacity; }
   void setOpacity(int opacity) { m_opacity = opacity; }
 
+  const base::Uuid& uuid() const { return m_uuid; }
+  void setUuid(const base::Uuid& uuid) { m_uuid = uuid; }
+
   virtual Grid grid() const;
   virtual Cel* cel(frame_t frame) const;
   virtual void getCels(CelList& cels) const = 0;
@@ -138,6 +142,9 @@ private:
   Sprite* m_sprite;     // owner of the layer
   LayerGroup* m_parent; // parent layer
   LayerFlags m_flags;   // stack order cannot be changed
+  base::Uuid m_uuid;    // The UUID is generated the first time the "HasUUID" flag
+                        // is activated when it is a null UUID. If this field had
+                        // a valid UUID already, it won't be replaced by a new one.
 
   BlendMode m_blendmode;
   int m_opacity;

src/doc/sprite.h

@@ -1,5 +1,5 @@
 // Aseprite Document Library
-// Copyright (C) 2018-2024  Igara Studio S.A.
+// Copyright (C) 2018-2025  Igara Studio S.A.
 // Copyright (C) 2001-2018  David Capello
 //
 // This file is released under the terms of the MIT license.
@@ -244,6 +244,9 @@ public:
 
   void setTileManagementPlugin(const std::string& plugin) { m_tileManagementPlugin = plugin; }
 
+  void setUseUuidsForLayers(bool value) { m_useUuidsForLayers = value; }
+  bool useUuidsForLayers() const { return m_useUuidsForLayers; }
+
 private:
   Document* m_document;
   ImageSpec m_spec;
@@ -272,6 +275,9 @@ private:
   // giving the possibility to handle tiles exclusively to a plugin.
   std::string m_tileManagementPlugin;
 
+  // This setting indicates if the layers of this sprite are using UUIDs.
+  bool m_useUuidsForLayers = false;
+
   // Disable default constructor and copying
   Sprite();
   DISABLE_COPYING(Sprite);