Using the Aseprite CLI to Export Sprites

Here’s a really quick one on our workflow for character sprites in Cobalt Core. It’s not rocket science, but it makes the process of editing and updating character art a lot quicker + less error prone, which adds up really quickly over months and years of editing dozens of characters, hundreds of loops, and thousands of sprites.

Aseprite has a few ways built in to export animations, either as a series of images or spritesheets. In our case, we assemble our thousands of sprites into a single texture atlas in the build, so what we needed was:

• A consistent export format for character animation loops, based on their name, tag, and frame.
• A script to update these in bulk, so you don’t have to remember the formatting string in each file, or create directories yourself, or ever have to update dozens of characters by hand if I need to change the output convention.

What we’re working with:

Each character in Cobalt Core has their own .ase Aseprite file, with animation loops tagged by different moods. Frame 1 of each loop is the “done talking” sprite, and frames 2+ are the sprites that loop while text is printing out.

When we’re done editing a character, we run this bash script that exports them to a folder with their name, next to the source file.

in Data/sprites/characters

# this is the aseprite file, the source of truth
riggs.ase

# these are the baked out pngs of each loop
# named by {character}_{tag}_{frame}
riggs/riggs_neutral_0.png 
riggs/riggs_neutral_1.png 
riggs/riggs_neutral_2.png 
riggs/riggs_neutral_3.png 
riggs/riggs_serious_0.png 
riggs/riggs_serious_1.png 
riggs/riggs_serious_2.png 
riggs/riggs_serious_3.png 
riggs/riggs_serious_4.png
[...] and so on

The Script:

The script scans the entire character directory for aseprite files, and converts them to pngs. If you want to only update specific sprites, you can give it a string to filter character names. So, ./ase.sh will update everything, ./ase.sh riggs will only update Riggs the possum.

Here’s that entire script. You’ll have to update it with your own paths, of course.

#!/bin/bash
set -e

# aseprite folder should be in your system path
ASEPRITE="Aseprite"

# fail if not present
"$ASEPRITE" --version

FILTER=$1

doCharacterFolder () {
  SOURCEPATH=$1
  DESTPATH=$2

  for ASE in $SOURCEPATH; do
    echo -n "$ASE"

    if [[ $ASE = *"$FILTER"* ]]; then
      echo -e "\033[33m - Matched search filter, updating generated sprites... \033[0m"
    else
      echo -e "\033[34m - skipping \033[0m"
      continue
    fi

    SPRITENAME=$(basename "$ASE")
    SPRITENAME="${SPRITENAME%.*}"

    mkdir -p "$DESTPATH"/"$SPRITENAME"
    rm -f "$DESTPATH"/"$SPRITENAME"/*.png

    "$ASEPRITE" -b "$ASE" --filename-format '{path}/{title}_{innertag}_{tagframe}.{extension}' --save-as "$DESTPATH"/"$SPRITENAME"/"$SPRITENAME".png
  done
}

doCharacterFolder "Data/sprites/characters/*.ase" "Data/sprites/characters"

That’s it! From there, all the game’s sprites get pulled into a big 8k texture atlas, but that’s another topic. The game can also run loading sprites individually, which saves a few seconds for us when developing and editing sprites.

Riggs is in there somewhere, I promise! Hopefully you found this useful!