pixijs-application

Application は、レンダラー、ルートの stage コンテナー、キャンバス、Ticker／Resize プラグインを所有する便利なラッパーです。v8 ではコンストラクターに引数を渡しません。すべての設定は、autoDetectRenderer を介してレンダラーを生成する非同期の app.init() 呼び出しに渡します。

クイックスタート

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（ブラウザー以外の環境でのセットアップ）。

基本パターン

ライフサイクル：生成、初期化、レンダリング、破棄

import { Application } from "pixi.js";

const app = new Application();

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

// ... run scene, ticker drives app.render() automatically ...

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) — 第 1 引数は renderer.destroy() に渡されます。キャンバスを DOM から削除するには、true または { removeView: true } を渡します。同じタブでアプリを破棄して再生成する際にグローバルプール（バッチ、テクスチャキャッシュ）を解放するには、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,
});

view／canvas、背景、レンダラーの優先設定（配列形式を含む）、ticker、resize、culler、events、accessibility、WebGL／WebGPU のコンテキストフラグ、Graphics のベジェ曲線の滑らかさ、GC、レンダラーごとのオーバーライド（webgl／webgpu／canvasOptions）など、すべてのオプションについては、references/application-options.md を参照してください。

Application のプロパティ

app.stage; // root Container; add all display objects here
app.renderer; // the WebGL/WebGPU/Canvas renderer instance
app.canvas; // the HTMLCanvasElement (insert it into the DOM yourself)
app.screen; // Rectangle describing the visible area in CSS pixels
app.domContainerRoot; // HTMLDivElement that holds DOMContainer overlays

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

ResizePlugin

init 時に resizeTo を設定する（または後から app.resizeTo を再設定する）と、プラグインが resize イベントを監視し、対象要素のクライアントサイズを使って renderer.resize() を呼び出します。高 DPI 出力には、autoDensity: true および resolution: window.devicePixelRatio と組み合わせてください。

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

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

app.resize(); // immediate resize to the target's current size
app.queueResize(); // defer the resize to the next animation frame
app.cancelResize(); // drop a pending 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("runs once on the next frame, then removes itself");
});

app.stop(); // pause the render loop (e.g. tab hidden)
app.start(); // resume

コールバックには Ticker インスタンスが渡されます。フレームレートに依存しない倍率（60fps で約 1.0）には ticker.deltaTime、実際のミリ秒数には 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 がティッカーを自動的に開始しないようにします。自分で app.render() を呼び出してください（同じ効果を得るには app.renderer.render({ container: app.stage }) を呼び出します）。登録済みのティッカーコールバックも実行する場合は、ループ内で 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; // this container is culled when its bounds leave the screen
world.cullableChildren = true; // default; set `false` to skip recursing into children

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>) {
    // runs inside app.init() after the renderer is created
    // attach props/methods to `this` to expose them on the app
  }

  public static destroy(this: Application) {
    // runs inside app.destroy() — tear down anything you attached
  }
}

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.canvas ではなく app.view を使用する

誤り：

document.body.appendChild(app.view);

正しい例：

document.body.appendChild(app.canvas);

v8 で app.view は 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() の Promise が解決された後です。それより前にアクセスすると undefined が返されます。

API リファレンス

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