Attention: Here be dragons (unstable version)

This is the latest (unstable) version of this documentation, which may document features not available in or compatible with released stable versions of Redot.

Checking the stable version of the documentation...

ImageFrames

Inherits: Resource < RefCounted < Object

A container for sequence of Images.

Description

A container of Images used to load and arrange a sequence of frames. Each frame can specify a delay for animated images.

Can be used to load animated image formats externally.

Supported animated image formats are GIF (.gif), APNG (.png and .apng), WepP (.webp), and any format exposed via a GDExtension plugin.

An ImageTexture is not meant to be operated from within the editor interface directly, and is mostly useful for rendering images on screen dynamically via code. If you need to generate images procedurally from within the editor, consider saving and importing images as custom texture resources implementing a new EditorImportPlugin.

Properties

int	frame_count	`0`
int	loop_count	`0`

Methods

float	get_frame_delay(frame: int) const
Image	get_frame_image(frame: int) const
bool	is_empty() const
Error	load(path: String)
Error	load_apng_from_buffer(buffer: PackedByteArray, max_frames: int)
ImageFrames	load_from_file(path: String) static
Error	load_gif_from_buffer(buffer: PackedByteArray, max_frames: int)
Error	load_webp_from_buffer(buffer: PackedByteArray, max_frames: int)
void	set_frame_delay(frame: int, delay: float)
void	set_frame_image(frame: int, image: Image)

Property Descriptions

int frame_count = 0 🔗

void set_frame_count(value: int)
int get_frame_count()

Number of frames to use in the animation. While you can create the frames independently with set_frame_image(), you need to set this value for the animation to take new frames into account.

int loop_count = 0 🔗

void set_loop_count(value: int)
int get_loop_count()

Number of times the animation loops. A value of 0 represents infinity.

Method Descriptions

float get_frame_delay(frame: int) const 🔗

Returns the given frame's duration, in seconds.

Image get_frame_image(frame: int) const 🔗

Returns the given frame's Image.

bool is_empty() const 🔗

Returns true if the frame_count is 0.

Error load(path: String) 🔗

Loads a sequence of image frames from file path.

Warning: This method should only be used in the editor or in cases when you need to load external images at run-time, such as images located at the user:// directory, and may not work in exported projects.

var frames = ImageFrames.load_from_file("res://animated.gif")
var animated_texture = AnimatedTexture.create_from_image_frames(frames)
$Sprite2D.texture = animated_texture

This way, textures can be created at run-time by loading images both from within the editor and externally.

Warning: Prefer to load imported textures with @GDScript.load() over loading them from within the filesystem dynamically with load(), as it may not work in exported projects:

var animated_texture = load("res://animated.gif")
$Sprite2D.texture = texture

This is because images have to be imported as an AnimatedTexture first to be loaded with @GDScript.load(). If you'd still like to load an animated image file just like any other Resource, import it as an ImageFrames resource instead, and then load it normally using the @GDScript.load() method.

Note: The image frame can be create from an imported texture using the AnimatedTexture.create_from_image_frames() method:

var texture = load("res://animated.gif")
var image: AnimatedTexture = AnimatedTexture.create_from_image_frames(texture)

Error load_apng_from_buffer(buffer: PackedByteArray, max_frames: int) 🔗

Loads image frames from the binary contents of an APNG file.

Note: This function will read standard PNG files just like Image.load_png_from_buffer(). If libpng is not compiled with support for reading APNG files, APNG files are treated as PNG files.

ImageFrames load_from_file(path: String) static 🔗

Creates a new ImageFrames and loads data from the specified file.

Error load_gif_from_buffer(buffer: PackedByteArray, max_frames: int) 🔗

Loads image frames from the binary contents of a GIF file.

Error load_webp_from_buffer(buffer: PackedByteArray, max_frames: int) 🔗

Loads image frames from the binary contents of a WebP file.

void set_frame_delay(frame: int, delay: float) 🔗

Sets the delay of any given frame. If set to 0, the frame may be skipped if converted into an AnimatedTexture.

void set_frame_image(frame: int, image: Image) 🔗

Assigns an Image to the given frame. Frame IDs start at 0, so the first frame has ID 0, and the last frame has ID frame_count - 1.