Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/foxcapades/renpy-generated-animations

Demonstration and source for generating animations from a collection of frames.
https://github.com/foxcapades/renpy-generated-animations

animation renpy

Last synced: 5 days ago
JSON representation

Demonstration and source for generating animations from a collection of frames.

Awesome Lists containing this project

README 

        
= Generate Animations from Frames

:source-highlighter: highlight.js

:toc:



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.



[source, python]

----

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:



[source, python]

----

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



. Download the link:https://github.com/Foxcapades/renpy-generated-animations/releases/latest[latest release].

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

. Create a new directory inside your `game` directory to contain your animation

frames.

. Ensure your frames are named with an incrementing number (with an optional

common prefix or a suffix).

. Create your generated animation!

+

[source, python]

----

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...

[%collapsible]

====

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.



[source]

----

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.



[source]

----

file001.png

...

file010.png

...

file245.png

----

====

+

.Arguments

--

[cols="1m,1m,8"]

|===



| 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

--

[cols="1m,1m,8"]

|===

| 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: link:https://www.reddit.com/r/RenPy/comments/vhgn1h/comment/id7frau/?utm_source=share&utm_medium=web3x&utm_name=web3xcss&utm_term=1&utm_content=share_button[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 link:https://github.com/Foxcapades[GitHub], my

link:https://foxcapades.itch.io/[Itch.io], or just call me Foxcapades.