Godot GIF

Description

GDExtension for Godot 4+ to load GIF files as AnimatedTexture and/or SpriteFrames.

NOTE: AnimatedTexture has been marked as deprecated according to development docs and could be removed in a future version of Godot.

Usage

Pre-Editor (New Feature)

Added a binary version for windows and linux to convert gifs via command line into standalone resource files which can then be added to any Godot project (4.4+) without requiring this addon (unless new gifs need to be converted at runtime)

Godot Gif Converter:

    Example Usage: godot_gif_convert --verbose -- --in=/temp/some-gif.gif --out=/temp/out --ext=res --fps=60

    --in                                    [REQUIRED]                              Gif file path or path to directory containing gifs
    --out                                   [REQUIRED]                              Path to directory to create output result
    
    --type                                  (Optional)                              Defaults to SpriteFrames. Can also be set to AnimatedTexture, or Both
    --ext                                   (Optional)                              Defaults to tres. The file extension to use when saving the resource (tres/res)
    --max_frames                            (Optional)                              Defaults to 0. When 0, no limit, otherwise only frames inclusively up to the limit will be used
    --fps                                   (Optional)                              Defaults to 30. Frames per second for SpriteFrames. Not applicable to AnimatedTexure

Editor

Gif files can be imported at edit time as one of the supported types via Import options.

Editor Imports Options

See the Editor Imports example scene.

Editor Imports Example

Runtime

Gif files can be loaded at runtime as one of the supported types via the GifManager singleton.

GifManager exposes the following methods for loading gifs either from file or from bytes directly:

e.g. to load from file

get_node("AnimFromRuntimeFile").texture = GifManager.animated_texture_from_file("res://examples/file/optic.gif")

get_node("AnimatedSprite2RuntimeFile").sprite_frames = GifManager.sprite_frames_from_file("res://examples/file/optic.gif")

See the Runtime Imports example scene.

Runtime Imports Example

Installation

Download the gdextension artifact from the latest successful build. (It should be right at the bottom of the Summary)

Extract the contents to your Godot project directory.

You should have an addons directory at the root with the following structure:

└───addons
    └───godotgif
        │   godotgif.gdextension
        │   LICENSE.txt
        │   README.md
        │
        └───bin
            │   godotgif.windows.template_debug.x86_32.dll
            │   godotgif.windows.template_debug.x86_64.dll
            │   godotgif.windows.template_release.x86_32.dll
            │   godotgif.windows.template_release.x86_64.dll
            │   libgodotgif.android.template_debug.arm64.so
            │   libgodotgif.android.template_release.arm64.so
            │   libgodotgif.linux.template_debug.x86_32.so
            │   libgodotgif.linux.template_debug.x86_64.so
            │   libgodotgif.linux.template_release.x86_32.so
            │   libgodotgif.linux.template_release.x86_64.so
            │
            ├───godotgif.macos.template_debug.framework
            │       libgodotgif.macos.template_debug
            │
            └───godotgif.macos.template_release.framework
                    libgodotgif.macos.template_release

Open your project. Any exisitng gifs should auto-import. New gifs in the project directory will automatically import as SpriteFrames. To convert them into AnimatedTexture, update the import settings.

The GifManager class should also now be available for access within GDScript.

Contributing

Setup

Ensure SCons is setup. Refer to Introduction to the buildsystem

• If using a different version of Godot, be sure to dump the bindings e.g.

      godot --dump-extension-api extension_api.json
  

• Compile with

      scons platform= custom_api_file=extension_api.json
  

Debugging

This repository is configured for use with VSCode

Launch configurations have been setup for both debugging in editor and in runtime provided certain VSCode extensions are present and environment variables are defined.

The following environment variables are required:

1. GODOT_PATH - The directory in which Godot is installed
2. GODOT_EXECUTABLE - The executable name of the Godot installation

More Details

Refer to GDExtension C++ example

License

Unless otherwise specified, the extension is released under the MIT license.

See the full list of third-party libraries with their licenses used by this extension at src/thirdparty/README.md.

This implementation heavily borrowed inspiration from the gif module for Goost that is currently only based on Godot 3