PixiJS Getting Started

Step 1: Install PixiJS

The recommended way to add PixiJS to a project is through npm. Run npm install pixi.js in your project directory to install the latest v8 release. This gives you full access to ES module imports and tree-shaking, so your final bundle includes only the PixiJS features you actually use.

For quick prototyping without a build step, you can load PixiJS from a CDN by adding a script tag pointing to the latest UMD build. This makes the PIXI namespace available globally without any bundler setup, though you lose tree-shaking and type-checking benefits.

If you are starting a brand new project, the fastest path is to use Vite as your bundler. Run npm create vite@latest my-pixi-game, choose the vanilla JavaScript or TypeScript template, install PixiJS, and you have a development server with hot module reloading ready in seconds. Vite's fast build times and native ES module support make it the most popular bundler choice in the PixiJS community as of 2026.

For TypeScript projects, PixiJS v8 ships with complete type definitions included in the npm package. No separate @types installation is needed. TypeScript integration provides autocomplete for all PixiJS APIs and catches type errors at compile time, which is especially helpful when working with the scene graph and texture management systems.

Step 2: Create the Application

The Application class is the entry point for every PixiJS project. It creates the renderer, sets up the stage container, and manages the frame loop. You initialize it by calling new Application() and then awaiting app.init() with your configuration options.

Common configuration options include width and height for the canvas dimensions, background for the clear color (accepts hex values like 0x1a1a2e or CSS color strings), antialias for smoother edges on shapes and text, and resolution for high-DPI display support. Setting resolution to window.devicePixelRatio ensures crisp rendering on retina screens.

After initialization, append the canvas to the DOM with document.body.appendChild(app.canvas). The canvas element is accessible through app.canvas and can be styled with CSS like any other HTML element. You can set its size to fill the viewport, constrain it to a specific container, or use CSS transforms for letterboxing.

The Application instance also provides access to app.stage, the root Container of the scene graph, and app.ticker, the frame loop manager. Everything you add to the stage becomes visible on screen, and everything you register with the ticker updates on every frame.

Step 3: Load Assets with the Assets Class

Before creating sprites, you need to load the images they will display. PixiJS v8 provides the Assets class, a unified asset loading system that handles images, sprite sheets, fonts, JSON data, and audio files with a consistent promise-based API.

The simplest approach is to call Assets.load('path/to/image.png'), which returns a promise that resolves to a Texture object. For multiple assets, use Assets.load(['image1.png', 'image2.png']) to load them in parallel and receive an object mapping paths to textures.

For larger projects, define an asset manifest that names and groups your assets into bundles. The manifest lets you load only the assets needed for the current game state (menu assets first, gameplay assets when the player starts a level) rather than loading everything at startup. Call Assets.init({ manifest }) to register the manifest, then Assets.loadBundle('gameplay') to load a specific bundle.

The Assets class automatically caches loaded textures, so requesting the same asset twice returns the cached version without a duplicate network request. It also handles format detection, loading WebP images on supported browsers and falling back to PNG on older ones if you configure format preferences in the manifest.

Always load assets before trying to create sprites from them. A common pattern is to show a loading screen (even a simple progress bar drawn with the Graphics class) while assets load, then build the game scene once all textures are ready.

Step 4: Create Sprites and Build the Scene

With textures loaded, creating a sprite is a single line: const sprite = new Sprite(texture). The sprite is now a display object that you can position, scale, rotate, and add to the scene graph.

Set the sprite's position with sprite.x and sprite.y, or use sprite.position.set(x, y) to set both at once. The anchor property controls the sprite's origin point for positioning and rotation. Setting sprite.anchor.set(0.5) centers the anchor, so the sprite rotates around its center rather than its top-left corner. Scale with sprite.scale.set(2) to double the size, and set sprite.rotation in radians for rotation.

Add the sprite to the stage with app.stage.addChild(sprite) to make it visible. You can also create Container objects to group related sprites together. For example, a game character might be a container holding a body sprite, a weapon sprite, and a health bar, all positioned relative to the container's origin. Moving the container moves all child sprites together.

The rendering order follows the order children are added: the last child added renders on top. Use container.setChildIndex(child, index) or container.sortChildren() to control layering within a container. In v8, Render Layers provide an alternative way to control visual order independently from the scene graph structure.

Build your initial scene by creating all the sprites and containers you need, positioning them, and adding them to the stage. This is your game's starting state, the arrangement of visual elements the player sees when the game begins.

Step 5: Animate with the Ticker

A static scene is not a game. The Ticker makes things move by calling your update function on every animation frame. Add a callback with app.ticker.add((ticker) => { ... }) and use ticker.deltaTime to calculate frame-rate-independent movement.

The deltaTime value represents how many frames worth of time have passed since the last update. At a steady 60 FPS, deltaTime is 1.0. If a frame takes twice as long (30 FPS), deltaTime is 2.0. Multiplying movement speed by deltaTime ensures objects move at consistent real-world speed regardless of frame rate variations.

A basic movement example: sprite.x += speed * ticker.deltaTime moves the sprite horizontally at a consistent rate. For rotation, sprite.rotation += 0.02 * ticker.deltaTime spins the sprite smoothly. Combine position, rotation, scale, and alpha changes in the ticker callback to create complex animations.

For games with distinct update phases, you can add multiple ticker callbacks with different priorities. Physics updates might run at a higher priority (lower number) than visual effects, ensuring the simulation step completes before rendering adjustments are applied. The ticker supports adding, removing, and pausing callbacks, giving you control over what runs each frame.

If you need a fixed-timestep loop where physics runs at exactly 60 updates per second regardless of rendering speed, you can implement an accumulator pattern within the ticker callback. Accumulate deltaTime, run physics steps at fixed intervals, and interpolate visual positions between physics states for smooth rendering.

Step 6: Add Input and Interaction

PixiJS v8 handles pointer input (mouse and touch) through the EventSystem. To make a sprite clickable, set its eventMode property to "static" (for objects that do not move) or "dynamic" (for moving objects that need continuous hit testing). Then attach event listeners with sprite.on('pointerdown', callback).

Supported pointer events include pointerdown, pointerup, pointermove, pointerover, pointerout, and tap. The event object provides the pointer's position in both global (screen) and local (relative to the display object) coordinates, so you can determine exactly where within a sprite the user clicked.

For keyboard input, use standard DOM event listeners on the window object: window.addEventListener('keydown', callback). Track which keys are currently pressed using a simple object or Set, then check those flags in the ticker callback to move the player character, trigger actions, or navigate menus. PixiJS does not provide a built-in keyboard abstraction because DOM events already handle this well.

Combining pointer and keyboard input with the ticker creates the core input loop for most games: the ticker reads the current input state, updates game logic accordingly, and PixiJS renders the result. This separation between input detection and game state updates keeps the code organized and testable.