🎨 Aseprite Modular Export: Layer × Tag Combinations

Export modular layers and tag combinations into organized folders — perfect for Unity, Godot, Unreal or any game engine with customizable characters.

---

📋 Description

This Aseprite script allows you to export each individual layer inside well-structured layer groups, organized by nested tag combinations.

It’s perfect for modular character systems in game engines like Unity, Godot, or Unreal — where thousands of combinations are built from base parts, skins, and animation states.

Ideal for modular character systems, it enables exporting thousands of variants based on:

• ✅Organize body parts via Layer Groups
  • (e.g., FrontArm, Head, Torso)
• ✅ Export animation states using nested tag hierarchy
  • (e.g., Idle → Idle_Sword → Idle_Sword_Loop)
• ✅ Customize skins/effects through layers inside each group
  • (e.g., RedHair, GoldenArmor)
• ✅ Support deep tag nesting for sub-animations
  • (e.g., Walk/Bare/Loop)
• ✅ Export to structured paths like:
  • FrontArm/Idle/Sword/Golden.png
  • FrontArm/Run/Sword/Loop/Golden.png
  • FrontArm/Run/Sword/Brake/Golden.png
• ✅ Export as spritesheets
• ✅ Organize cleanly by tags + structured groups
• ✅ Unlimited tag depth (recursive folder structure)
• ✅ Auto-parse tags using _ as level separators
  • (e.g., Idle_Sword, Run_Staff_Loop)
• ✅ Split animations into rows or columns
• ✅ Integrate easily with Unity's ScriptableObject-based customization systems

💡 Ideal for modular skin systems: easily swap weapons, armor, hair, effects, etc.

---

⚠️ Requirements & Notes

• ⚠️ Do not use the same name for:
  • A layer group and any of its child layers
  • Tags that appear at the same level in the hierarchy
• ⚠️ Tags must use underscores () to define hierarchy: TagLevel1_TagLevel2...
  • Example: Run_Loop→ TagLevel1 Name = Run, TagLevel2 Name = Loop.
• ❌ Layers outside any tag range will be skipped.
• ✅ All body skins must be inside a named layer group.
• ✅ Only layers inside tags will be exported.
• ✅ Layer groups should be well-structured.

---

🏷️ Multi-Level Tag Structure

To generate a nested folder structure during export, Aseprite tags must follow a consistent naming pattern using underscores _.

📌 Tag Format:

Use underscores (_) to define hierarchical levels of animation or state.

Each part separated by _ becomes a subfolder in the output path.

---

📁 Layer

To maintain a clean and modular export structure, this script follows the pattern:

LayerGroups/TagLevel1/TagLevel2/.../Layer.png

Examples:

• FrontArm/Idle/Golden.png
• FrontArm/Idle/Wooden.png
• Weapon/Run/Loop/Wooden.png

Why This Structure?

This path format is ideal for modular asset pipelines in game engines like Unity, Godot, or Unreal.

---

It enables:

🔄 Easy swapping of components (e.g., different armors or hairstyles)

🧩 Plug-and-play combination of character parts

📦 Automatic loading using Resources.Load or addressable paths

🛠️ Cleaner ScriptableObject definitions matching asset paths

---

🛠️ Configuration Options

You can customize the export with the following:

Option	Description
📁 Output Directory	Where to save the exported files
🖼 Format	PNG, GIF, JPG
🔍 Tag Split Mode	Choose between splitting tags into Rows or Columns
🔄 Scale	Export scale multiplier (1x to 10x)
💾 Save Sprite	Optionally save the original .aseprite after export

---

👨‍💻 Author & Credits

• 🔧 Script by: Nguyễn Trần Dinh
• 🧭 Based on: PKGaspi's Aseprite Scripts
• 📦 GitHub: Aseprite-Export-Combinations

---