pixijs-environments

DOMAdapter はPixiJSが行うすべてのDOM アクセス(キャンバス作成、画像読み込み、fetch、XML パース)を抽象化し、ライブラリが非ブラウザ環境で実行できるようにします。app.init() の前に DOMAdapter.set(...) を呼び出して、別のアダプターに切り替えます。

クイックスタート

// worker.ts — メインスレッドから転送されたOffscreenCanvas
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(設定削除、アダプター変更)。

コアパターン

Web Worker と OffscreenCanvas

メインスレッドから 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 を使用します。

Web Worker 内では動作しない機能(DOM アクセスなし)：

• 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 (DOM のみのモジュール除外)

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

loadEnvironmentExtensions

import { loadEnvironmentExtensions } from "pixi.js";

await loadEnvironmentExtensions(false); // false = デフォルトを読み込む; true = スキップ

loadEnvironmentExtensions(skip) は非推奨の autoDetectEnvironment ヘルパー(v8.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 を有効にするのではなく、その必要性を取り除きます。この名前は回避する 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 を直接呼び出さず、これを使用します。

よくある間違い

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

間違い：

const app = new Application();
await app.init({ width: 800, height: 600 });
DOMAdapter.set(WebWorkerAdapter); // 遅すぎます; 初期化時にアダプターが既に読み込まれています

正しい：

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

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

[高] 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 互換性を破壊します。

[高] CSP unsafe-eval インポート名の混乱

間違い：

// CSP 環境、インポートを省略
import { Application } from "pixi.js";
// スロー: "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 を有効にすることを示唆していますが、実際はその反対です。つまり、PixiJS が厳密な CSP で動作するように静的ポリフィルをインストールします。

PixiJS はレンダラー初期化時に CSP ブロッキングを検出し、上記のエラーをスローします。ブラウザは PixiJS がレポートする前に独自の CSP 違反もログに記録する可能性があります。どちらも同じ修正を指しています。

[高] 古い 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