pixijs-environments

DOMAdapter は、PixiJS が行うあらゆる DOM アクセス（キャンバスの作成、Image の読み込み、fetch、XML の解析）を抽象化し、ライブラリをブラウザー以外のコンテキストでも実行できるようにします。別のアダプターに切り替えるには、app.init() の前に DOMAdapter.set(...) を呼び出してください。

クイックスタート

// worker.ts — OffscreenCanvas posted from main thread
DOMAdapter.set(WebWorkerAdapter);

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

unsafe-eval をブロックする CSP 環境では、レンダラーを初期化する前にポリフィルをインポートしてください。

import "pixi.js/unsafe-eval";

関連スキル： pixijs-application（標準的なブラウザー初期化）、pixijs-migration-v8（設定の削除、アダプターの変更）。

基本パターン

OffscreenCanvas を使った Web Worker

メインスレッドから OffscreenCanvas を転送し、ワーカー内で PixiJS を初期化します。

// 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) は、new Application() より前に実行する必要があります。WebWorkerAdapter は、document.createElement('canvas') の代わりに OffscreenCanvas を、XML 解析には @xmldom/xmldom を使用します。

DOM にアクセスできない Web Worker 内では、次の機能は動作しません。

• DOMContainer — オーバーレイする実際の DOM ノードがありません。
• AccessibilitySystem — ライブ DOM のフォーカスとスクリーンリーダーのフックに依存します。
• Font Loading API による FontFace の読み込み — 代わりに、変換済みのビットマップフォント（BitmapFont.install または .fnt アセット）を使用してください。

環境別のサブパスインポート

pixi.js をインポートする代わりに、環境ごとに用意された厳選済みのバンドルを読み込めます。

import "pixi.js/browser"; // accessibility, dom, events, spritesheet, rendering, filters
import "pixi.js/webworker"; // spritesheet, rendering, filters (no DOM-only modules)

pixi.js/webworker には、DOM を必要とする accessibility、dom、events は意図的に含まれていません。レンダラー初期化時に loadEnvironmentExtensions が適切なセットを動的インポートするのに頼らず、静的かつ同期的なモジュール登録を行いたい場合は、これらのサブパスエントリーを使用してください。

loadEnvironmentExtensions

import { loadEnvironmentExtensions } from "pixi.js";

await loadEnvironmentExtensions(false); // false = load defaults; true = skip

loadEnvironmentExtensions(skip) は、非推奨の autoDetectEnvironment ヘルパー（8.1.6 以降）に代わるものです。カスタム環境を初期化する際に、既定のブラウザー拡張機能の自動読み込みを無効にするには、true を渡してください。autoDetectEnvironment(add) は、loadEnvironmentExtensions(!add) に処理を引き継ぐシムとして、引き続き使用できます。

CSP に準拠したセットアップ

PixiJS は、シェーダーのコンパイルと uniform の同期に内部で new Function() を使用します。unsafe-eval をブロックする Content Security Policy 環境では、ポリフィルをインポートしてください。

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

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

pixi.js/unsafe-eval をインポートすると、eval ベースのコード生成が、シェーダー同期、UBO 同期、uniform 同期、パーティクルバッファ更新用の静的ポリフィルに置き換わります。このインポートは、PixiJS のレンダラー初期化より前に行う必要があります。

注意点： pixi.js/unsafe-eval という名前は直感に反します。unsafe eval を有効にするのではなく、unsafe eval を不要にします。この名前は、回避する CSP ディレクティブに由来します。

カスタムアダプター

Node.js、ヘッドレステスト、SSR などの標準外の環境では、Adapter インターフェース全体を実装してください。

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);

Adapter インターフェースでは、次のメソッドが必要です。createCanvas、createImage、getCanvasRenderingContext2D、getWebGLRenderingContext、getNavigator、getBaseUrl、getFontFaceSet、fetch、parseXML。

現在のアダプターを確認する

import { DOMAdapter } from "pixi.js";

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

DOMAdapter.get() は、現在設定されているアダプターを返します。PixiJS に関連するコード内で DOM にアクセスする場合は、document や Image を直接呼び出す代わりに使用してください。

よくある間違い

[CRITICAL] app.init() の前にアダプターを設定しない

誤り：

const app = new Application();
await app.init({ width: 800, height: 600 });
DOMAdapter.set(WebWorkerAdapter); // too late; adapter already read during init

正しい例：

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

ブラウザー以外の環境では、app.init() より前に DOMAdapter.set() を呼び出す必要があります。PixiJS はレンダラーの作成時、app.init() 中にアダプターを読み取ります。new Application() 自体はステージの Container を作成するだけで、アダプターは読み取りません。

[HIGH] document や Image を直接使用する

誤り：

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

正しい例：

import { DOMAdapter } from "pixi.js";

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

PixiJS 内のすべての DOM アクセスは、DOMAdapter を通じて行われます。document、Image、その他のブラウザーグローバルを直接使用すると、Web Worker および SSR との互換性が損なわれます。

[HIGH] CSP の unsafe-eval に関するインポート名の混同

誤り：

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

正しい例：

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

pixi.js/unsafe-eval のインポートにより、シェーダーのコンパイルで eval() / new Function() を使う必要がなくなります。名前から unsafe eval が有効になるように見えますが、実際はその逆です。静的なポリフィルを導入し、厳格な CSP の下で PixiJS が動作するようにします。

PixiJS はレンダラーの初期化時に CSP によるブロックを検出し、上記のエラーをスローします。PixiJS が報告する前に、ブラウザー独自の CSP 違反もログに記録される場合があります。どちらも同じ修正方法を示しています。

[HIGH] 古い settings.ADAPTER パターンの使用

誤り：

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

正しい例：

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

settings オブジェクトは v8 で削除されました。アダプターの設定にはすべて DOMAdapter.set() を使用します。

API リファレンス

• DOMAdapter
• BrowserAdapter
• WebWorkerAdapter
• autoDetectEnvironment
• loadEnvironmentExtensions