gif

The gif namespace decodes animated GIF files into individual pre-composited GPU textures with transparency and disposal handling resolved automatically.

---

Decoding GIFs

local anim = gif.decode(file_bytes: string) --> gif_t | nil

Decodes raw GIF data (read via files.read). Returns nil if corrupted or invalid.

Decode Once & Memory Management

Each frame becomes an individual Direct3D texture (width * height * 4 bytes). Always decode GIFs once at startup and call anim:release() in your unload callback.

---

gif_t Methods & Properties

Member	Type	Description
width	number	Frame canvas width in pixels.
height	number	Frame canvas height in pixels.
duration	number	Total animation cycle duration in seconds.
loop_count	number	Loop count (0 = loop indefinitely).
g:frame_count()	number	Total frame count in the animation.
g:frame(i)	image_t	Returns the texture for 1-based frame index i.
g:delay(i)	number	Delay in seconds for frame i.
g:at(time)	image_t	Returns the appropriate frame texture for the given timestamp in seconds.
g:draw(pos, time, clr?)	nil	Composites and renders the active frame at pos directly.
g:release()	nil	Deallocates all GPU textures associated with the animation.

---

Example: Rendering an Animated Mascot

local cat_gif = nil
if files.exists("aimsense/scripts/data/cat.gif") then
    cat_gif = gif.decode(files.read("aimsense/scripts/data/cat.gif"))
end

client.add_callback("render", function()
    if cat_gif then
        cat_gif:draw(vector(50, 50), globals.realtime)
    end
end)

client.add_callback("unload", function()
    if cat_gif then
        cat_gif:release()
    end
end)