Automatically exports visible layers from your Aseprite file into structured folders, based on your group hierarchy

Scripts & Extensions
1

:bullseye: Export By Group (Recursive) — Aseprite Script

Hi everyone! :waving_hand:
I’m Feel, an indie artist and amateur developer.
I’m sharing a script I made (with a lot of help from ChatGPT)
to make my Aseprite workflow smoother — and hopefully yours too!

:brain: What this script does

This tool automatically exports visible layers from your Aseprite file into structured folders, based on your group hierarchy. It’s especially handy for projects with many nested groups.

:white_check_mark: Recursively walks all groups and sub-groups
:white_check_mark: Supports @group → merges all visible image layers into a single PNG
:white_check_mark: Automatically trims transparent pixels
:white_check_mark: Skips groups/layers that contain # in their name
:white_check_mark: Automatically creates export folders based on group names
:white_check_mark: Writes a full export log to keep track of everything
:white_check_mark: :new_button: Define export path inside your Aseprite file (no script editing needed !)
:white_check_mark: :new_button: @groups are now flattened with full opacity & blend mode support !

:file_folder:! New ! Set your export path inside your Aseprite file

Instead of editing the script to set your export folder,
you now simply add a layer named with % followed by the path.

Example in aseprite, layer name must be :
% E:/MyGame/Exports/

:stop_sign: Rules for the export path layer:

  • You must have exactly one %layer
  • The name must start with %
  • The path must end with a / or \\
  • Use double backslashes if you’re using Windows paths (\\ instead of \)

:white_check_mark: Valid:
% E:/MyGame/Exports/
% E:\\MyGame\\Exports\\

:cross_mark: Invalid:
% E:\MyGame\Exports
% E:\MyGame\Exports\

Discord_8qydLZAKdJ
Discord_8qydLZAKdJ392×548 3.94 KB

:package: Example Aseprite structure

Items
├── @sword_iron → exported as a merged sprite: sword_iron.png
├── @shield_wood → exported as a merged sprite: shield_wood.png
├── #hidden_stuff → ignored automatically
└── coin → exported as individual layer PNGs

Exemple of logs :

[2025-05-22 06:10]
Export from: E:\ -redacted- \exemple project.aseprite

→ Skipped (inherited or contains '#'): #Background
→ Entering group: UI
→ Entering group: Trees
→ Entering group: Items

→ Merging group: @shield_wood
→ Exported: E:/  -redacted- /Items/shield_wood.png (trimmed 157x195)

→ Merging group: @sword_iron
→ Exported: E:/ -redacted- /Items/sword_iron.png (trimmed 84x130)
→ Skipped (inherited or contains '#'): #hidden_stuff
Checking layer: coin
→ Exported: E:/ -redacted- /Items/coin.png (trimmed 68x68)

Total exported : 3 layer(s)
Total skipped  : 2 layer(s)
------------

:wrench: How to install

  1. Download the script from GitHub:
    :backhand_index_pointing_right: GitHub – Export By Group (Recursive)

  2. Place the export-by-group-recursive.lua file in your Aseprite scripts folder:
    C:\Users\YourName\AppData\Roaming\Aseprite\scripts\

  3. Run the script in Aseprite via:
    File > Scripts > export-by-group-recursive.lua

Let me know what you think! I’d love feedback, ideas, or improvements.
Happy pixel crafting ! :artist_palette::hammer_and_wrench:

It’s my first script and first GitHub project,
so please don’t hesitate to tell me if I forgot something or did anything wrong :see_no_evil_monkey:

1 Like
2

Since I’m a new member, I couldn’t include both screenshots in the main post — so here’s a side-by-side view of the Aseprite layer structure and the resulting export folders, to make things easier to understand if it was not clear :blush:

explorer_JbGDRzmLAO
explorer_JbGDRzmLAO924×365 41.3 KB

3

:file_folder:! New ! Set your export path inside your Aseprite file

Instead of editing the script to set your export folder,
you now simply add a layer named with % followed by the path.

Example in aseprite, layer name must be :
% E:/MyGame/Exports/

:stop_sign: Rules for the export path layer:

  • You must have exactly one %layer
  • The name must start with %
  • The path must end with a / or \\
  • Use double backslashes if you’re using Windows paths (\\ instead of \)

:white_check_mark: Valid:
% E:/MyGame/Exports/
% E:\\MyGame\\Exports\\

:cross_mark: Invalid:
% E:\MyGame\Exports
% E:\MyGame\Exports\

Discord_8qydLZAKdJ
Discord_8qydLZAKdJ392×548 3.94 KB

1 Like
4

Hello !

:new_button: Major update to my Aseprite script “Export by Group (Recursive)”.

It now supports automatic flattening of @groups
using Aseprite’s native FlattenLayers()

Which means correct handling of opacity and blend modes

Yeah bcs that wasn’t the case before :face_with_peeking_eye:
I really struggled to get it working properly,
but I’ve tested it on two different projects now and it works great.

Feel free to try the script and let me know what you think. Cheers!