How to Integrate GSAP with Pixi.js

Integrating Pixi.js for high-performance 2D rendering with GSAP (GreenSock Animation Platform) for robust animation control allows developers to create complex, hardware-accelerated web animations with ease. This guide provides a straightforward walkthrough on how to seamlessly connect GSAP with Pixi.js objects, covering direct property tweening, leveraging the specialized GSAP PixiPlugin, and managing render updates.

Direct Property Tweening

Because Pixi.js display objects (like Sprites, Graphics, and Containers) are standard JavaScript objects with numeric properties, GSAP can animate them directly out of the box. You do not need any special configuration to animate basic properties like position, rotation, or opacity.

import * as PIXI from 'pixi.js';
import { gsap } from 'gsap';

// Create a Pixi.js Sprite
const sprite = PIXI.Sprite.from('character.png');

// Tween basic properties directly
gsap.to(sprite, {
  duration: 2,
  x: 500,
  y: 300,
  rotation: Math.PI * 2, // Rotates 360 degrees (in radians)
  alpha: 0.5,
  ease: 'power2.out'
});

Using GSAP’s PixiPlugin

While direct tweening works for flat properties, Pixi.js often nests properties. For example, scale is controlled via sprite.scale.x and sprite.scale.y. Animating these directly requires referencing the sub-objects.

To simplify your code, GSAP provides a dedicated PixiPlugin. This plugin flattens nested properties, handles colors (tints), and manages complex visual effects like blurs and displacement maps.

1. Installation and Registration

First, you must register the PixiPlugin with GSAP and provide it with your Pixi.js instance.

import * as PIXI from 'pixi.js';
import { gsap } from 'gsap';
import { PixiPlugin } from 'gsap/PixiPlugin';

// Register the plugin
gsap.registerPlugin(PixiPlugin);

// Provide the global PIXI object to the plugin
PixiPlugin.registerPIXI(PIXI);

2. Animating with the Pixi Namespace

Once registered, wrap all Pixi-specific properties inside a pixi: {} object within your GSAP vars.

gsap.to(sprite, {
  duration: 1.5,
  pixi: {
    scale: 1.5,          // Uniformly scales scale.x and scale.y
    scaleX: 2,           // Scales only the X axis
    tint: '#FF5733',     // Automatically handles hex color conversions
    colorMatrixFilter: { // Adjust contrast, saturation, and hue
      hue: 180, 
      saturation: 2 
    },
    blur: 10             // Applies and animates a blur filter
  }
});

Coordinating the Render Loop

By default, Pixi.js runs its own rendering loop via app.ticker, redrawing the stage approximately 60 times per second. GSAP also runs on its own internal requestAnimationFrame ticker to update object properties.

Because GSAP updates the property values on the JavaScript object and Pixi’s ticker renders whatever values those objects hold on the next frame, integration is naturally seamless. No manual render calls are required inside your tweens.

However, if you want to ensure perfect synchronization or pause rendering when no animations are active to save CPU/GPU cycles, you can let GSAP drive the render loop:

// Stop the default Pixi ticker
app.ticker.stop();

// Use GSAP's ticker to trigger the Pixi renderer
gsap.ticker.add(() => {
  app.renderer.render(app.stage);
});