Extension Details

Editor menu command to allow somewhat more human-readable creation and editing of Playdate SystemAsset animation.txt files, for animated launch cards and icons.

Provided "as is." Use at your own risk.

Feel free to modify, improve, and share this extension. (Just note in the README that you've done so.)

By Morgan Adams, Adams Immersive

To Use

Work with the animation in a separate, human-readable (see below) working text file, outside of the Playdate project.

Then copy that into your project's animation.txt file, Select All, and apply this command to convert the selection into the official Playdate SDK format.

It's up to you to then save the animation.txt file, but don't accidentally convert your original human-readable file. You'll need it if you want to make changes easily later.

Formatting Rules

1. Omit the "frames =". (It will be added for you when you run this extension.)

2. Instead of "x" before frame quantities, use "-". (It will be changed to "x" for you when you run this extension.)

So instead of typing...

frames = 1x5, 2x5, 3x5, 4x5

...you would simply type...

1-5, 2-5, 3-5, 4-5

Human-Readable Additions

1. You can use ASCII alphabetic names to refer to your frame images. Add any letters you wish (upper or lowercase) before, after, or around the image digits, as long as the digits remain in the name somewhere. These names must be ONLY letters, no spaces, punctuation, symbols, accented characters, or additional digits other than the file number. (These letters will be removed from the final conversion, so you don't even have to be consistent in your naming: only the digit actually matters.)

So instead of typing...

frames = 1x5, 2x5, 3x5, 4x5

...you could type...

1spaceshipStart-5, 2spaceshipLaunchA-5, 3spaceshipLaunchB-5, 4spaceshipLaunchC-5, 5spaceshipEnd-5

(The actual images should still have filenames that are just numbers: 1.png, 2.png, etc.)

1. Unlimited whitespace: you can use spaces, tabs, and newlines freely to organize your frames. (Tabs, newlines, and returns will be converted to spaces, which ARE allowed in the SDK format.) You still need the commas between images.

2. You can, optionally, put a comma after EVERY image including the last one. No need to treat the last frame differently as you re-order your images. (If there is an extraneous comma at the end of the file, this extension removes it, even if it is followed by whitespace.)

So instead of typing...

frames = 1x5, 2x5, 3x5, 4x5

...you could type (note trailing comma)...

1spaceshipStart-5,

2spaceshipLaunchA-5,
    3spaceshipLaunchB-5, 4spaceshipLaunchC-5,

5spaceshipEnd-5,

When you run this extension, all illegal whitespace is removed, along with all alphabetic characters (leaving just the image numbers and frame quantities). The hyphens are changed to "x", and "frames = " is appended to the resulting single line. Extraneous runs of multiple spaces are also condensed into single spaces, non-breaking spaces are converted to regular spaces, and any leading/trailing whitespace is removed.

Converting an Existing animation.txt to a More Readable Form

You can use a series of find-and-replace operations (not part of this extension) to turn your existing numeric images with "x" into human-readable names with hyphens for use with this script.

For example: replace "1x" with "1spaceshipStart-". (Remember to keep the image number somewhere in the name.)

Remember to also remove "frames =" from the beginning.

Tips

20 frames = 1 second.

Even though the image files themselves still lack useful names, you can easily view any one: with the enclosing folder ("card-highlighted") open in a window, hit the spacebar and then type the image number. (After you stop typing for a moment, you can type another image number any time without hitting spacebar to close the Quick Look view.)

Version 1.0

Initial release