Generate Animations from Frames

Table of Contents

• Why?
  • What about…​?
• Usage
• Functions
• Credits
• License

The source code and a demonstration of automatically generating an animation based on png frames in a subdirectory of the game directory.

Why?

If you have ever constructed animations by doing the following, you quickly realize how tedious it can be.

image tacos:
    "images/tacos/frame1"
    pause 0.2
    "images/tacos/frame2"
    pause 0.2
    "images/tacos/frame3"
    pause 0.2
    "images/tacos/frame4"
    pause 0.2
    "images/tacos/frame5"
    pause 0.2
    "images/tacos/frame6"
    pause 0.2
    repeat

While this approach is fine if you have few frames or few animations, if you have to construct an animation with many frames or a lot of animations, this quickly becomes a pain.

Instead, for situations where the pause duration is the same between frames, we can replace that tedium with a simple function call:

image tacos = generate_animation("images/tacos", pause=0.2, looping=True)

In the provided demonstration, we create an animation out of a 48 frame explosion, which would be really hecking tedious to do manually.

What about…​?

Animations with variable framerates

If your animation holds on some frames for longer than or shorter than others, this is not the solution for you. This will set the pause duration on all frames to the value given (or the default of 30 frames per second).

Usage

1. Download the latest release.

2. Unzip it into your project directory (the directory above game).

3. Create a new directory inside your game directory to contain your animation frames.

4. Ensure your frames are named with an incrementing number (with an optional common prefix or a suffix).

5. Create your generated animation!

   image explosion = generate_animation("images/explosion", fps=45)

Functions

generate_animation

Generates an animation from the png files in the given directory, in name order.

It is advised that, to keep the ordering of frames correct, the files in the given directory are suffixed with an incrementing integer with one or more preceding zeros. For example: [ file01.png, file02.png, file03.png, …​ ] or [ 01.png, 02.png, 03.png, …​ ].

Notes on filename suffix leading zeros…​

The leading zeros are necessary due to the fact that sorting files by name will put file10.png before file2.png as it will compare the 1 in 10 to the 2 and stop there. However, with file02.png and file10.png, it will compare the 0 in 02 to the 1 in 10 and stop there, putting them in the correct relative order based on that.

The number of preceding zeros necessary depends on the number of frames in your animation, and the zeros are only necessary for filenames with a lesser number of digits than the max digit count for the last frame.

For example, if you have 10 frames, it would be advised that the numbers 0-9 be prefixed with a single leading zero so the total digit width of the suffix number is always 2.

file01.png
...
file10.png

If you had 100-999 frames for your animation (whoa, nelly!) it would be advised that you put 2 leading zeros before the numbers 0-9 and 1 leading zero before the numbers 10-99 to keep the ordering correct.

file001.png
...
file010.png
...
file245.png

Arguments

directory

str

The directory containing the animation frames. This path is relative to the game directory. For example, a path may look like: "images/animations/explosion".

Keyword Arguments

fps	int|float	Frames per second for the animation. Incompatible with the pause keyword argument; setting both will cause an error. Defaults to 30.
pause	float	How long to pause between each frame. Incompatible with the fps keyword argument; setting both will cause an error. Defaults to None.
looping	bool	Whether or not the animation should loop. Defaults to False.
hold_last_frame	bool	Whether or not the animation should hold on the last frame or vanish after completion. Defaults to False.

Credits

• Original inspiration: Blue_Budgies on Reddit

• Explosion frames: https://www.pngegg.com/en/png-nvowz

License

This source code and project are released under the MIT license, which to paraphrase in a way that is not legally binding:

• You can use it for free things

• You can use it for paid things

• You can modify it however you see fit

• You can redistribute it as you see fit

• Go nuts!

For a better breakdown of what the license actually means see: https://choosealicense.com/licenses/mit/

I do ask that you credit me in some way, but if you don’t I’m not gonna call the open-source police on you. If you do choose to credit me you can do so by providing a link to my GitHub, my Itch.io, or just call me Foxcapades.