Handle WebGL Context Loss in Pixi.js

WebGL context loss occurs when the computer’s graphics card resets or runs out of memory, causing your WebGL application to crash or freeze. This article provides a straightforward guide on how to detect this event, listen for restoration, and gracefully handle these disruptions in a Pixi.js application to prevent crashes and maintain a seamless user experience.

Understanding WebGL Context Loss

When a browser tab goes to sleep, the computer enters standby mode, or the GPU becomes overloaded, the browser may terminate the WebGL context. When this happens, all textures, buffers, and shaders loaded into GPU memory are lost.

While Pixi.js automatically attempts to rebuild its internal state and reload textures when the context is restored, you must actively manage your application state (like pausing the game loop and updating the UI) to prevent errors and ensure a smooth recovery.

Step 1: Listen to Context Loss Events

You can detect context loss by adding event listeners to the canvas element utilized by your Pixi.js application.

In your initialization code, target the canvas (app.view in Pixi.js v7 and below, or app.canvas in Pixi.js v8) and listen for the standard WebGL events:

const canvas = app.canvas || app.view; // Supports Pixi.js v7 and v8

// 1. Listen for context loss
canvas.addEventListener('webglcontextlost', (event) => {
    // Prevent the browser's default behavior to allow manual recovery
    event.preventDefault();
    handleContextLost();
}, false);

// 2. Listen for context restoration
canvas.addEventListener('webglcontextrestored', () => {
    handleContextRestored();
}, false);

Step 2: Handle Context Loss (The Pause Phase)

When the context is lost, the renderer cannot draw anything to the screen. Attempting to continue updating the game loop will result in WebGL errors. You should immediately pause your application’s ticker and display a visual fallback.

function handleContextLost() {
    console.warn("WebGL context lost. Pausing application...");
    
    // Stop the Pixi.js ticker to halt rendering and logic updates
    app.ticker.stop();
    
    // Show a loading spinner or "Context lost, recovering..." overlay to the user
    showRecoveryUI();
}

Step 3: Handle Context Restoration (The Recovery Phase)

Once the GPU is ready again, the browser fires the webglcontextrestored event. Pixi.js will automatically attempt to re-upload its base textures and reset the WebGL state.

Your job during restoration is to recreate any custom shaders, trigger manual texture reloads if you bypass Pixi’s default loaders, and resume the application loop.

function handleContextRestored() {
    console.log("WebGL context restored. Reinitializing assets...");

    // Re-initialize custom shaders or low-level WebGL states if applicable
    // (Standard Pixi.js sprites and graphics reconstruct automatically)

    // Hide the recovery overlay
    hideRecoveryUI();

    // Restart the ticker to resume rendering
    app.ticker.start();
}

Best Practices for Graceful Recovery