Usage Guide for the Aseprite Lua Script: Batch Replacement of Specific Components in Sprite Sheets

1. Preparation

Sprite Sheet: Open Aseprite and use the "File" > "Open" option to load the sprite sheet you plan to modify. Make sure it has the components you want to replace.

Script Installation: Find the Aseprite script folder. You can do this by going to "File" > "Scripts" and looking for the option to open the script folder. Put the Lua script for batch replacement into this folder. Then, go back to "File" > "Scripts" and select "Refresh Script Folder" so that the script shows up in the list of available scripts.

2. Running the Script

Initialization: Choose the newly added script from the "Scripts" menu. A dialog box will appear.

Background Handling: 

For Transparent Backgrounds: Because of a software bug, transparent backgrounds may make the find-and-replace function misalign. Click the "Add Background Image" option in the dialog box to add a background.

For Non - Transparent Backgrounds: If your sprite sheet already has a non-transparent background, you can skip this step and directly move on to the next operation.

3. Defining the Replacement Areas

Select the Source Area: Use the selection tool in Aseprite to pick the specific part of the sprite sheet you want to replace. After making the selection, click the "Record Query Selection" button to save this area for identification.

Modify and Define the Target Area: Change the selected area as you need. After that, click the "Record Replacement Selection" button to set the new content for replacement.

4. Performing the Replacement

Replacement Options: 

Normal Replacement: Click the "Normal Replacement" button to directly replace the identified components with the new content.

Rotation - based Replacements: Select "Match 90 - degree Replacement", "180 - degree Replacement", or "270 - degree Replacement" if you want the replacement content rotated by the corresponding angle before matching and replacing components in the sprite sheet.

Flip - based Replacements: Use the "Horizontal Flip" and "Vertical Flip" options to replace components with the horizontally or vertically flipped versions of the replacement content.

5. Final Steps

Background Removal (if applicable): If you added a background at first, click the "Remove Background" button to get back the original transparency of the sprite sheet. Now, your sprite sheet should have all the specified components replaced as per your settings.