pixijs-scene-gif
Use this skill when displaying animated GIFs in PixiJS v8. Covers the pixi.js/gif side-effect import, Assets.load returning a GifSource, GifSprite playback (play/stop/currentFrame/animationSpeed), autoPlay/loop options, onComplete/onLoop/onFrameChange callbacks, GifSource sharing, clone, destroy. Triggers on: GifSprite, GifSource, pixi.js/gif, animationSpeed, currentFrame, autoPlay, onComplete, onFrameChange, constructor options, GifSpriteOptions.
- Installs
- 5.6K
- Last 24h
- +31
- Trending rank
- #4298
- Security
- Pass
Install
Works with every agent the skills CLI supports.
npx skills add https://github.com/pixijs/pixijs-skills --skill pixijs-scene-gif- 01
Install
Run the command in your project. The CLI asks which agents to install for.
- 02
Describe the task
Ask your agent for something this skill covers. It loads pixijs-scene-gif automatically when relevant.
- 03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.
Security audits
Independent scans of the skill's instructions and bundled files.
SKILL.md
The instructions your agent reads when the skill is triggered.
GifSprite plays an animated GIF as a display object. Assets.load('animation.gif') returns a GifSource (not a Texture), and you wrap that in a GifSprite. Requires a side-effect import 'pixi.js/gif' to register the loader extension.
Assumes familiarity with pixijs-scene-core-concepts. GifSprite extends Sprite, so it is a leaf: do not nest children inside it. Wrap multiple GifSprite instances in a Container to group them.
Quick Start
import "pixi.js/gif";
import { GifSprite } from "pixi.js/gif";
const source = await Assets.load("animation.gif");
const gif = new GifSprite({
source,
autoPlay: true,
loop: true,
animationSpeed: 1,
});
gif.anchor.set(0.5);
gif.x = app.screen.width / 2;
gif.y = app.screen.height / 2;
app.stage.addChild(gif);
[!NOTE] GIFs decode every frame into a separate canvas texture. For performance-critical animations with many frames, prefer a spritesheet with
AnimatedSprite— it uses a single atlas texture and batches better on the GPU.
Related skills: pixijs-scene-core-concepts (scene graph basics), pixijs-scene-sprite (AnimatedSprite for spritesheet-based animation), pixijs-assets (Assets.load, caching, unloading), pixijs-ticker (frame timing), pixijs-performance (texture memory).
Constructor options
GifSpriteOptions extends Omit<SpriteOptions, 'texture'>; texture is managed internally (set from source.textures[0] and swapped per frame). All other Sprite options (anchor, scale, tint, roundPixels, etc.) are valid, and all Container options (position, scale, tint, label, filters, zIndex, etc.) are also valid here — see skills/pixijs-scene-core-concepts/references/constructor-options.md.
Leaf-specific options added by GifSpriteOptions:
| Option | Type | Default | Description |
|---|---|---|---|
source | GifSource | — | Required. The parsed GIF data returned by Assets.load('file.gif'). Can be shared across multiple GifSprite instances. |
autoPlay | boolean | true | Start playback immediately on construction. If false, you must call gif.play() to begin. |
loop | boolean | true | Repeat the animation on reaching the last frame. When false, the sprite stops at the final frame and fires onComplete. |
animationSpeed | number | 1 | Multiplier on the GIF's native frame timing. 2 runs at double speed; 0.5 runs at half. |
autoUpdate | boolean | true | Connect playback to Ticker.shared. Set to false to drive updates yourself via gif.update(ticker). |
fps | number | 30 | Fallback frame rate for GIFs that do not specify per-frame delays. |
onComplete | () => void | null | null | Called when a non-looping animation reaches the last frame. |
onLoop | () => void | null | null | Called each time a looping animation wraps around. |
onFrameChange | (frame: number) => void | null | null | Called every time the displayed frame index changes. |
scaleMode | SCALE_MODE | 'linear' | Deprecated since 8.13.0 — pass scaleMode via Assets.load(..., { data: { scaleMode } }) instead. |
The constructor also accepts a bare GifSource as its sole argument (new GifSprite(source)), which is shorthand for new GifSprite({ source }) using the defaults above.
Core Patterns
Setup and the side-effect import
import "pixi.js/gif";
import { Assets } from "pixi.js";
import { GifSprite } from "pixi.js/gif";
const source = await Assets.load("animation.gif");
const gif = new GifSprite({ source });
pixi.js/gif calls extensions.add(GifAsset), registering .gif with the asset loader. Without it, Assets.load does not recognize GIF files. GifSprite and GifSource are exported from pixi.js/gif, not pixi.js.
Importing a named export from pixi.js/gif also triggers the side effect, so a bare import 'pixi.js/gif' is only needed when you don't import anything from that path.
Playback control
const gif = new GifSprite({ source });
gif.play();
gif.stop();
gif.currentFrame = 5;
gif.animationSpeed = 2;
gif.animationSpeed = 0.5;
gif.playing; // read-only
gif.progress; // 0-1 playback position
gif.totalFrames; // number of frames
gif.duration; // total duration in ms
autoPlay: true (default) starts playback immediately; loop: true (default) repeats. animationSpeed is a multiplier on the GIF's native frame timing. currentFrame is zero-based.
Loading options
const source = await Assets.load({
src: "animation.gif",
data: {
fps: 12,
scaleMode: "nearest",
resolution: 2,
},
});
const fromDataUri = await Assets.load("data:image/gif;base64,R0lGODlh...");
Options in data are passed to GifSource.from. fps sets the fallback frame delay for GIFs that don't specify timing. scaleMode and resolution control the canvas textures created for each frame. The loader matches both .gif file extensions and data:image/gif URIs.
Callbacks
const gif = new GifSprite({
source,
loop: false,
onComplete: () => console.log("animation finished"),
onLoop: () => console.log("loop completed"),
onFrameChange: (frame) => console.log("now on frame", frame),
});
onCompletefires when a non-looping animation reaches the last frame.onLoopfires each time a looping animation wraps around.onFrameChangefires every time the displayed frame changes.
Manual update mode
const gif = new GifSprite({ source, autoUpdate: false });
app.ticker.add((ticker) => {
gif.update(ticker);
});
autoUpdate: false disconnects from Ticker.shared. You call gif.update(ticker) yourself, passing any Ticker instance. Useful when animation should be driven by a private ticker (e.g., a pause-aware game ticker).
Sharing source data and cloning
const source = await Assets.load("animation.gif");
const gif1 = new GifSprite({ source, autoPlay: true });
const gif2 = new GifSprite({ source, autoPlay: false });
const gif3 = gif1.clone();
gif3.animationSpeed = 0.5;
GifSource can be shared across multiple GifSprite instances; each sprite has independent playback state. clone() copies all playback settings but creates an independent instance.
Common Mistakes
[HIGH] Not importing pixi.js/gif
Wrong:
import { Assets } from "pixi.js";
const gif = await Assets.load("animation.gif");
Correct:
import "pixi.js/gif";
import { Assets } from "pixi.js";
const source = await Assets.load("animation.gif");
The GIF loader extension must be registered before loading. Without the side-effect import, the loader does not recognize .gif files and the load either fails or returns raw data.
[MEDIUM] Expecting Assets.load to return a Texture
Wrong:
const texture = await Assets.load("animation.gif");
const sprite = new Sprite(texture);
Correct:
const source = await Assets.load("animation.gif");
const gif = new GifSprite({ source });
Assets.load on a GIF returns a GifSource containing frame textures and timing data. Pass the source to GifSprite; for a single still frame, read source.textures[0].
[MEDIUM] GIF memory not released on destroy
Wrong:
gif.destroy();
// GifSource and frame textures remain in memory
Correct:
gif.destroy(true);
// or
await Assets.unload("animation.gif");
GIF frames hold decoded pixel data as individual canvas textures. gif.destroy() (or destroy(false)) destroys the sprite but keeps the GifSource intact. Pass true to also destroy the source. For shared sources, only destroy when the last consumer is done, or call Assets.unload to let the asset cache handle it.
[LOW] Do not nest children inside a GifSprite
GifSprite extends Sprite, which sets allowChildren = false. It is a leaf. To group a GIF with other display objects, wrap them all in a plain Container:
const group = new Container();
group.addChild(gif, label);
API Reference
FAQ
What does the pixijs-scene-gif skill do?
Use this skill when displaying animated GIFs in PixiJS v8. Covers the pixi.js/gif side-effect import, Assets.load returning a GifSource, GifSprite playback (play/stop/currentFrame/animationSpeed), autoPlay/loop options, onComplete/onLoop/onFrameChange callbacks, GifSource sharing, clone, destroy. Triggers on: GifSprite, GifSource, pixi.js/gif, animationSpeed, currentFrame, autoPlay, onComplete, onFrameChange, constructor options, GifSpriteOptions.
How do I install pixijs-scene-gif?
Run npx skills add https://github.com/pixijs/pixijs-skills --skill pixijs-scene-gif in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/pixijs-scene-gif/ (personal) or .claude/skills/pixijs-scene-gif/ (project).
Which AI agents can use pixijs-scene-gif?
Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.
Is pixijs-scene-gif safe to install?
Security partners have reviewed it: Gen Agent Trust Hub passed; Socket passed; Snyk passed; ZeroLeaks passed. As with any skill, read the SKILL.md and bundled scripts before installing.
Who maintains pixijs-scene-gif?
It is published by pixijs in pixijs/pixijs-skills. It has 5,610 recorded installs.
More from pixijs/pixijs-skills
pixijs
pixijs/pixijs-skills
Use this skill first for ANY PixiJS v8 task; it routes to the right specialized skill for the job. Covers the full PixiJS surface: Application setup, the scene graph (Container, Sprite, Graphics, Text, Mesh, ParticleContainer, DOMContainer, GifSprite), rendering (WebGL/WebGPU/Canvas, render loop, custom shaders, filters, blend modes), assets, events, color, math, ticker, accessibility, performance, environments, migration from v7, and project scaffolding. Triggers on: pixi, pixi.js, pixijs, PixiJS, v8, Application, app.init, Sprite, Container, Graphics, Text, Mesh, ParticleContainer, DOMContainer, GifSprite, Assets, Ticker, renderer, WebGL, WebGPU, scene graph, filter, shader, blend mode, texture, 3D texture, depth slice, layer, storage texture, BitmapText, create-pixi, how do I draw, how do I render, how do I animate in pixi.
pixijs-application
pixijs/pixijs-skills
Use this skill when creating and configuring a PixiJS v8 Application. Covers new Application() + async app.init() options (width, height, background, antialias, resolution, autoDensity, preference, resizeTo, autoStart, sharedTicker, canvas, useBackBuffer, powerPreference, eventFeatures, accessibilityOptions, gcActive, bezierSmoothness, webgl/webgpu/canvasOptions per-renderer overrides), app.stage/renderer/canvas/screen/domContainerRoot access, ResizePlugin, TickerPlugin, CullerPlugin (cullable, cullArea), custom ApplicationPlugin via ExtensionType.Application, start/stop lifecycle, and app.destroy() with releaseGlobalResources. Triggers on: Application, app.init, app.stage, app.renderer, app.canvas, app.screen, app.domContainerRoot, ApplicationOptions, ApplicationPlugin, ExtensionType.Application, resizeTo, sharedTicker, skipExtensionImports, preferWebGLVersion, preserveDrawingBuffer, cullable, CullerPlugin, app.start, app.stop, app.destroy, releaseGlobalResources.
pixijs-performance
pixijs/pixijs-skills
Use this skill when profiling or optimizing a PixiJS v8 app for FPS, draw calls, or GPU memory. Covers destroy patterns (cacheAsTexture(false), releaseGlobalResources), GCSystem and TextureGCSystem, PrepareSystem, object pooling, batching rules, BitmapText for dynamic text, culling (Culler, CullerPlugin, cullable, cullArea), resolution/antialias tradeoffs, low-level wins (transient MSAA render textures, render bundles, partial buffer updates). Triggers on: FPS, jank, draw calls, batching, object pool, GCSystem, PrepareSystem, Culler, cacheAsTexture, memory leak, destroy patterns, render bundle, transient, MSAA, Buffer.update, WebGPU performance, TexturePool, repeatEdgePixels, bind group.
pixijs-scene-graphics
pixijs/pixijs-skills
Use this skill when drawing vector shapes and paths in PixiJS v8. Covers the Graphics API: shape-then-fill methods (rect/circle/ellipse/poly/roundRect/star/regularPoly/roundPoly/roundShape/filletRect/chamferRect), path methods (moveTo/lineTo/bezierCurveTo/quadraticCurveTo/arc/arcTo/arcToSvg/closePath), fill/stroke/cut, holes, FillGradient (linear/radial), FillPattern, GraphicsContext sharing, svg import/export, containsPoint hit testing, cloning, clearing, bounds, fillStyle/strokeStyle, draw-time transforms (rotateTransform/scaleTransform/translateTransform/setTransform/save/restore), default styles, GraphicsPath reuse. Triggers on: Graphics, GraphicsContext, rect, circle, poly, roundRect, fill, stroke, cut, hole, beginHole, FillGradient, FillPattern, moveTo, bezierCurveTo, svg, graphicsContextToSvg, svg export, GraphicsOptions, containsPoint, clone, clear, bounds, rotateTransform, translateTransform, setFillStyle, setStrokeStyle, GraphicsPath.
pixijs-core-concepts
pixijs/pixijs-skills
Use this skill when understanding how PixiJS v8 renders frames: the systems-and-pipes renderer, the render loop, and how the library adapts to different environments. Covers WebGLRenderer/WebGPURenderer/CanvasRenderer selection, renderer.render() pipeline, environment detection, rendering into RenderTextures and RenderTargets (flipY, mipLevel, layer, bind/push/pop, copyDepthTexture), WebGL context loss and WebGPU device loss recovery, and pointers to per-topic deep dives. Triggers on: renderer, WebGL, WebGPU, Canvas, render loop, render pipeline, systems, environments, autoDetectRenderer, RenderTexture, RenderTarget, render to texture, flipY, mipLevel, layer, 3D texture, depth slice, renderTarget.bind, copyToTexture, copyDepthTexture, depth-only, WebGLLoader, WebGPULoader, CanvasLoader, RendererLoader, lazy-load renderer systems, code splitting, context lost, webglcontextlost, device lost, GPUDevice.lost.
pixijs-assets
pixijs/pixijs-skills
Use this skill when loading and managing resources in PixiJS v8. Covers Assets.init, Assets.load/add/unload, bundles, manifests, background loading, onProgress, caching, spritesheets, video textures, web fonts, bitmap fonts, animated GIFs, compressed textures, SVG as texture or Graphics, resolution detection, per-asset data options, and forcing a specific loader with the parser field (for extension-less URLs). Triggers on: Assets, Assets.load, Assets.init, loadBundle, manifest, backgroundLoad, Spritesheet, Cache, LoadOptions, unload, parser, loadParser, loadWebFont, loadBitmapFont, loadVideoTextures, GifSource, VideoSourceOptions.
Popular other skills
hyperframes-cli
heygen-com/hyperframes
The HyperFrames CLI by job - scaffold, check, look at frames, edit the timeline, preview, render locally or in the cloud, publish, project history - plus reading its JSON and recovering from build or render failures.
triage
mattpocock/skills
Move issues and external PRs through a state machine of triage roles, categorise, verify, grill if needed, and write agent-ready briefs.
ask-matt
mattpocock/skills
Ask which skill or flow fits your situation. A router over the skills in this repo.
to-questionnaire
mattpocock/skills
Turn a decision you can't fully answer into a questionnaire for someone else to fill in.
loop-me
mattpocock/skills
Grill me about specs for the workflows I want to build, within this workspace.