pixijs-application

Application は、レンダラー、ルート stage Container、キャンバス、および Ticker/Resize プラグインを所有する便利なラッパーです。v8 ではコンストラクタは引数を取りません。すべての設定は非同期の app.init() 呼び出しに渡され、ここで autoDetectRenderer 経由でレンダラーがインスタンス化されます。

クイックスタート

import { Application } from "pixi.js";

const app = new Application();

await app.init({
  resizeTo: window,
  background: "#1099bb",
  antialias: true,
  preference: "webgl",
  autoDensity: true,
  resolution: window.devicePixelRatio,
});

document.body.appendChild(app.canvas);

関連スキル: pixijs-core-concepts (レンダラー、レンダリングパイプライン)、pixijs-ticker (レンダループの詳細)、pixijs-scene-container (app.stage の操作)、pixijs-environments (非ブラウザ環境のセットアップ)。

コアパターン

ライフサイクル: construct、init、render、destroy

import { Application } from "pixi.js";

const app = new Application();

await app.init({ width: 800, height: 600 });
document.body.appendChild(app.canvas);

// ... シーン実行、ticker が自動的に app.render() を駆動 ...

app.destroy(
  { removeView: true, releaseGlobalResources: true },
  { children: true, texture: true, textureSource: true },
);

• new Application() はインスタンスを割り当てますが、何も作成しません。ここに渡されたオプションは v8 の非推奨警告とともに無視されます。
• app.init(options) は非同期です。レンダラーを構築し、プラグインをセットアップし、app.canvas、app.renderer、または app.screen を使用できるようになる前に完了する必要があります。
• TickerPlugin は init が解決されると、毎フレーム app.render() を呼び出します (autoStart: false の場合を除く)。
• app.destroy(rendererDestroyOptions, stageDestroyOptions) — 最初の引数は renderer.destroy() に転送されます。true または { removeView: true } を渡して、キャンバスを DOM から削除します。同じタブでアプリを破棄して再作成する場合、releaseGlobalResources: true を追加してグローバルプール (バッチ、テクスチャキャッシュ) をドレインします。これを省略すると、再初期化後のちらつきとステイルなテクスチャの原因になります (pixijs-performance を参照)。

主要な init オプション

await app.init({
  width: 800,
  height: 600,
  background: 0x1099bb,
  backgroundAlpha: 1,

  antialias: true,
  resolution: window.devicePixelRatio,
  autoDensity: true,

  preference: "webgpu",

  autoStart: true,
  sharedTicker: false,

  resizeTo: window,

  canvas: document.querySelector("#game-canvas") as HTMLCanvasElement,
});

すべてのオプション — ビュー/キャンバス、背景、レンダラープリファレンス (配列形式を含む)、ticker、リサイズ、culler、イベント、アクセシビリティ、WebGL/WebGPU コンテキストフラグ、Graphics ベジェ平滑化、GC、およびレンダラーごとのオーバーライド (webgl / webgpu / canvasOptions) については、references/application-options.md を参照してください。

Application プロパティ

app.stage; // ルート Container; すべてのディスプレイオブジェクトをここに追加
app.renderer; // WebGL/WebGPU/Canvas レンダラーインスタンス
app.canvas; // HTMLCanvasElement (自分で DOM に挿入してください)
app.screen; // CSS ピクセルで表示領域を説明する Rectangle
app.domContainerRoot; // DOMContainer オーバーレイを保持する HTMLDivElement

app.stage はプレーン Container です。シーングラフの詳細 (トランスフォーム、addChild、destroy) については、pixijs-scene-container を参照してください。レンダラーレベルの操作 (抽出、generateTexture、カスタムシステム) については、pixijs-core-concepts と pixijs-custom-rendering を参照してください。app.domContainerRoot は、レンダラーが DOMContainer オーバーレイをホストするために使用する <div> です。シーンノードに固定された DOM 要素が必要な場合は、app.canvas の隣に追加します (pixijs-scene-dom-container を参照)。

ResizePlugin

初期化時に resizeTo を設定するか、後で app.resizeTo を再割り当てすると、プラグインは resize イベントをリッスンし、ターゲット要素のクライアントサイズを使用して renderer.resize() を呼び出します。autoDensity: true と resolution: window.devicePixelRatio を組み合わせて、高 DPI 出力を実現します。

await app.init({ resizeTo: window });

app.resizeTo = document.querySelector("#game-container") as HTMLElement;

app.resize(); // ターゲットの現在のサイズへの即座のリサイズ
app.queueResize(); // 次のアニメーションフレームへのリサイズを遅延
app.cancelResize(); // 保留中の queueResize をドロップ

プラグインはキャンバスをターゲットに合わせて保ちます。app.screen と app.canvas.width/height は応答して更新されます。リサイズ後に読み取って UI を配置します。

• app.resize() — 即座の同期リサイズ。
• app.queueResize() — 次のフレームへの遅延により、急速な呼び出しを統合します。window.resize リスナーによって内部的に使用され、冗長な作業を回避します。
• app.cancelResize() — キューに入っているリサイズをキャンセルします。キューに入っている queueResize をトリガーした独自のレイアウトコードを破棄する前に呼び出します。

Ticker の基本

TickerPlugin は app.ticker を作成し、UPDATE_PRIORITY.LOW で app.render() をそれに登録します。app.start()/app.stop() でループを制御し、app.ticker.add / app.ticker.addOnce でコールバックを追加します:

app.ticker.add((ticker) => {
  sprite.rotation += 0.01 * ticker.deltaTime;
});

app.ticker.addOnce(() => {
  console.log("次のフレームで 1 回実行され、その後自動的に削除される");
});

app.stop(); // レンダループを一時停止 (例: タブが非表示)
app.start(); // 再開

コールバックは Ticker インスタンスを受け取ります。ticker.deltaTime でフレームレート非依存乗数 (60fps で ~1.0) を読み取るか、ticker.deltaMS で実際のミリ秒を読み取るか、ticker.FPS で現在のフレームレートを読み取ります。優先度、FPS キャップ、onRender、共有と専用 ticker、および v8 コールバック署名の変更については、pixijs-ticker を参照してください。

手動レンダループ

await app.init({ autoStart: false, width: 800, height: 600 });
document.body.appendChild(app.canvas);

function frame() {
  updateScene();
  app.render();
  requestAnimationFrame(frame);
}
frame();

autoStart: false は TickerPlugin が ticker を自動的に開始するのを防ぎます。app.render() を自分で呼び出すか (または同じ効果のために app.renderer.render({ container: app.stage }) を呼び出す)。登録されている ticker コールバックがまだ発火する場合は、ループ内で app.render() の前に app.ticker.update() を呼び出します。

CullerPlugin (オプトイン)

CullerPlugin は、app.renderer.screen の外に落ちるコンテナのレンダリングをスキップします。デフォルトでは登録されていません。アプリを作成する前に追加します:

import {
  Application,
  Container,
  Sprite,
  extensions,
  CullerPlugin,
  Rectangle,
} from "pixi.js";

extensions.add(CullerPlugin);

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

const world = new Container();
world.cullable = true; // このコンテナは、その境界がスクリーンを離れるときにカルされます
world.cullableChildren = true; // デフォルト; 子へのリカージョンをスキップするには `false` に設定

const tile = Sprite.from("tile.png");
tile.cullable = true;
world.addChild(tile);
app.stage.addChild(world);

cullable が設定されていない限り、コンテナはカルされません。container.cullArea = new Rectangle(x, y, w, h) でデフォルトの境界チェックをオーバーライドします。子の境界の計算が高コストの場合です。プラグインは app.render() をラップして、Culler.shared.cull(app.stage, app.renderer.screen) がすべてのフレームの前に実行されます。カルペイオフの時期については、pixijs-performance を参照してください。

カスタム Application プラグイン

static init、static destroy、および static extension = ExtensionType.Application を持つクラスを登録して Application を拡張します。どちらのメソッドも this が Application インスタンスにバインドされた状態で呼び出されるため、this.renderer と this.stage が利用可能です。

import {
  Application,
  ExtensionType,
  extensions,
  type ApplicationOptions,
} from "pixi.js";

class FpsOverlay {
  public static extension = ExtensionType.Application;

  public static init(this: Application, options: Partial<ApplicationOptions>) {
    // レンダラーが作成された後、app.init() 内で実行
    // `this` にプロップ/メソッドをアタッチして、アプリで公開
  }

  public static destroy(this: Application) {
    // app.destroy() 内で実行 — アタッチしたものをすべてティアダウン
  }
}

extensions.add(FpsOverlay);

プラグインは登録順に初期化され、逆順に破棄されます。プラグインのタイプ付きオプションを追加するには、PixiMixins.ApplicationOptions を拡張します:

declare global {
  namespace PixiMixins {
    interface ApplicationOptions {
      fpsOverlay?: { visible?: boolean };
    }
  }
}

await app.init({ fpsOverlay: { visible: true } });

組み込みの ResizePlugin、TickerPlugin、およびオプトインの CullerPlugin はすべて同じコントラクトを使用しています。skipExtensionImports: true を設定した場合は、必要な組み込みを自分で登録します (extensions.add(ResizePlugin, TickerPlugin))。

一般的なミス

[CRITICAL] オプションをコンストラクタに渡す

間違い:

const app = new Application({ width: 800, height: 600 });
document.body.appendChild(app.canvas);

正解:

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

v8 では Application コンストラクタは引数を取りません。そこに渡されたオプションは無視され、非推奨警告をログします。レンダラーは非同期の init() 呼び出し内でのみ作成されます。

[HIGH] app.view の代わりに app.canvas を使用しない

間違い:

document.body.appendChild(app.view);

正解:

document.body.appendChild(app.canvas);

app.view は v8 で app.canvas に名前が変更されました。古いゲッターは仍利用可能ですが、非推奨警告を発出します。

[MEDIUM] init が解決される前に app.canvas または app.renderer に触れる

間違い:

const app = new Application();
document.body.appendChild(app.canvas);
app.init({ width: 800, height: 600 });

正解:

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

app.renderer、app.canvas、および app.screen は init() プロミスが解決されると入力されます。それより前にアクセスすると undefined が返されます。

API リファレンス

• Application
• ApplicationOptions
• ApplicationPlugin
• ResizePlugin
• ResizePluginOptions
• TickerPlugin
• TickerPluginOptions
• CullerPlugin
• autoDetectRenderer