pixijs-environments

DOMAdapter abstrait chaque accès au DOM que PixiJS effectue (création de canvas, chargement d'images, fetch, parsing XML) pour que la bibliothèque puisse s'exécuter en dehors du navigateur. Appelez DOMAdapter.set(...) avant app.init() pour utiliser un adaptateur différent.

Démarrage rapide

// worker.ts — OffscreenCanvas posté depuis le thread principal
DOMAdapter.set(WebWorkerAdapter);

self.onmessage = async (event) => {
  const app = new Application();
  await app.init({
    canvas: event.data.canvas,
    width: 800,
    height: 600,
  });
};

Pour les contextes CSP qui bloquent unsafe-eval, importez le polyfill avant toute initialisation de renderer :

import "pixi.js/unsafe-eval";

Skills associés : pixijs-application (initialisation standard du navigateur), pixijs-migration-v8 (suppression de paramètres, changements d'adaptateur).

Motifs principaux

Web Worker avec OffscreenCanvas

Transférez un OffscreenCanvas depuis le thread principal, puis initialisez PixiJS dans le worker :

// main.ts
const canvas = document.createElement("canvas");
canvas.width = 800;
canvas.height = 600;
document.body.appendChild(canvas);

const offscreen = canvas.transferControlToOffscreen();
const worker = new Worker("worker.ts", { type: "module" });
worker.postMessage({ canvas: offscreen }, [offscreen]);

// worker.ts
import { Application, DOMAdapter, WebWorkerAdapter } from "pixi.js";

DOMAdapter.set(WebWorkerAdapter);

self.onmessage = async (event) => {
  const app = new Application();
  await app.init({
    canvas: event.data.canvas,
    width: 800,
    height: 600,
  });
};

DOMAdapter.set(WebWorkerAdapter) doit être appelé avant new Application(). WebWorkerAdapter utilise OffscreenCanvas au lieu de document.createElement('canvas') et @xmldom/xmldom pour le parsing XML.

Les fonctionnalités qui ne fonctionnent pas à l'intérieur d'un Web Worker (pas d'accès au DOM) :

• DOMContainer — il n'existe aucun nœud DOM réel à superposer.
• AccessibilitySystem — dépend du focus DOM actif et des hooks de lecteur d'écran.
• Chargement de FontFace via l'API Font Loading — utilisez plutôt des fonts bitmap pré-converties (BitmapFont.install ou assets .fnt).

Imports par sous-chemins spécifiques à l'environnement

Au lieu d'importer pixi.js, vous pouvez charger un bundle sélectionné pour chaque environnement :

import "pixi.js/browser"; // accessibility, dom, events, spritesheet, rendering, filters
import "pixi.js/webworker"; // spritesheet, rendering, filters (pas de modules DOM uniquement)

pixi.js/webworker omet volontairement accessibility, dom et events car ils nécessitent le DOM. Utilisez ces entrées de sous-chemins quand vous souhaitez un enregistrement de module statique et synchrone au lieu de vous fier à loadEnvironmentExtensions pour importer dynamiquement le bon ensemble à l'initialisation du renderer.

loadEnvironmentExtensions

import { loadEnvironmentExtensions } from "pixi.js";

await loadEnvironmentExtensions(false); // false = charger les défauts ; true = ignorer

loadEnvironmentExtensions(skip) remplace le helper autoDetectEnvironment dépréciée (depuis 8.1.6). Passez true pour refuser le chargement automatique des extensions navigateur par défaut quand vous amorçez un environnement personnalisé. autoDetectEnvironment(add) existe toujours comme un shim qui transfère vers loadEnvironmentExtensions(!add).

Configuration conforme à CSP

PixiJS utilise new Function() en interne pour la compilation de shaders et la synchronisation d'uniformes. Dans les environnements Content Security Policy qui bloquent unsafe-eval, importez le polyfill :

import "pixi.js/unsafe-eval";
import { Application } from "pixi.js";

const app = new Application();
await app.init({ width: 800, height: 600 });

L'import pixi.js/unsafe-eval remplace la génération de code basée sur eval par des polyfills statiques pour la synchronisation de shaders, la synchronisation UBO, la synchronisation d'uniformes et les mises à jour de buffer de particules. Cet import doit précéder toute initialisation de renderer PixiJS.

Note de tension : Le nom pixi.js/unsafe-eval est contre-intuitif. Il n'active pas unsafe eval ; il supprime le besoin de l'utiliser. Le nom fait référence à la directive CSP qu'il contourne.

Adaptateur personnalisé

Pour des environnements non-standard (Node.js, tests sans interface, SSR), implémentez l'interface Adapter complète :

import { DOMAdapter } from "pixi.js";
import type { Adapter } from "pixi.js";
import { createCanvas, Image } from "canvas";
import { DOMParser } from "@xmldom/xmldom";

const HeadlessAdapter: Adapter = {
  createCanvas: (width, height) => createCanvas(width ?? 0, height ?? 0),
  createImage: () => new Image(),
  getCanvasRenderingContext2D: () => CanvasRenderingContext2D,
  getWebGLRenderingContext: () => WebGLRenderingContext,
  getNavigator: () => ({ userAgent: "HeadlessAdapter", gpu: null }),
  getBaseUrl: () => "file://",
  getFontFaceSet: () => null,
  fetch: (url, options) => fetch(url, options),
  parseXML: (xml) => new DOMParser().parseFromString(xml, "text/xml"),
};

DOMAdapter.set(HeadlessAdapter);

L'interface Adapter requiert ces méthodes : createCanvas, createImage, getCanvasRenderingContext2D, getWebGLRenderingContext, getNavigator, getBaseUrl, getFontFaceSet, fetch, parseXML.

Vérifier l'adaptateur actuel

import { DOMAdapter } from "pixi.js";

const adapter = DOMAdapter.get();
const canvas = adapter.createCanvas(256, 256);
const img = adapter.createImage();

DOMAdapter.get() retourne l'adaptateur actuellement défini. Utilisez-le pour tout accès au DOM dans du code adjacent à PixiJS au lieu d'appeler directement document ou Image.

Erreurs courantes

[CRITIQUE] Ne pas définir l'adaptateur avant app.init()

Faux :

const app = new Application();
await app.init({ width: 800, height: 600 });
DOMAdapter.set(WebWorkerAdapter); // trop tard ; adaptateur déjà lu pendant init

Correct :

DOMAdapter.set(WebWorkerAdapter);
const app = new Application();
await app.init({ width: 800, height: 600 });

DOMAdapter.set() doit être appelé avant app.init() dans les environnements hors navigateur. PixiJS lit l'adaptateur pendant app.init() quand le renderer est créé. new Application() lui-même ne crée que le Container stage et ne lit pas l'adaptateur.

[ÉLEVÉE] Utiliser document ou Image directement

Faux :

const img = new Image();
img.src = "texture.png";

Correct :

import { DOMAdapter } from "pixi.js";

const img = DOMAdapter.get().createImage();
img.src = "texture.png";

Tout accès au DOM dans PixiJS transite par DOMAdapter. L'utilisation directe de document, Image ou d'autres globals du navigateur casse la compatibilité Web Worker et SSR.

[ÉLEVÉE] Confusion sur le nom de l'import CSP unsafe-eval

Faux :

// Environnement CSP, import omis
import { Application } from "pixi.js";
// Lance : "Current environment does not allow unsafe-eval,
// please use pixi.js/unsafe-eval module to enable support."

Correct :

import "pixi.js/unsafe-eval";
import { Application } from "pixi.js";

L'import pixi.js/unsafe-eval supprime le besoin de eval() / new Function() dans la compilation de shaders. Malgré un nom suggérant qu'il active unsafe eval, il fait le contraire : il installe des polyfills statiques pour que PixiJS fonctionne sous CSP strict.

PixiJS détecte le blocage CSP à l'initialisation du renderer et lance l'erreur ci-dessus. Le navigateur peut aussi enregistrer sa propre violation CSP avant que PixiJS ne rapporte ; les deux pointent vers le même correctif.

[ÉLEVÉE] Utiliser l'ancien motif settings.ADAPTER

Faux :

import { settings, WebWorkerAdapter } from "pixi.js";
settings.ADAPTER = WebWorkerAdapter;

Correct :

import { DOMAdapter, WebWorkerAdapter } from "pixi.js";
DOMAdapter.set(WebWorkerAdapter);

L'objet settings a été supprimé en v8. Toute configuration d'adaptateur utilise DOMAdapter.set().

Référence API

• DOMAdapter
• BrowserAdapter
• WebWorkerAdapter
• autoDetectEnvironment
• loadEnvironmentExtensions