pixijs-events

PixiJS の federated event system は DOM イベントをシーングラフ上にミラーリングします。container.eventMode = 'static' を設定してオブジェクトをオプトインし、.on(), addEventListener(), または onEventName プロパティハンドラーでリッスンします。Move イベントはリッスン中のオブジェクト上でのみ発火します。ドラッグ操作には globalpointermove を使用します。

クイックスタート

const button = new Sprite(await Assets.load("button.png"));
button.eventMode = "static";
button.cursor = "pointer";
app.stage.addChild(button);

button.on("pointertap", (event) => {
  console.log("clicked at", event.global.x, event.global.y);
});

let dragging = false;
button.on("pointerdown", () => {
  dragging = true;
});
button.on("pointerup", () => {
  dragging = false;
});
button.on("pointerupoutside", () => {
  dragging = false;
});
button.on("globalpointermove", (event) => {
  if (dragging) button.parent.toLocal(event.global, undefined, button.position);
});

関連スキル: pixijs-accessibility (スクリーンリーダー + キーボード)、pixijs-scene-dom-container (HTML オーバーレイ)、pixijs-performance (イベント多用シーン)。

コアパターン

eventMode の値

import { Sprite } from "pixi.js";

const sprite = new Sprite();

// インタラクションなし。子要素も無視される
sprite.eventMode = "none";

// デフォルト。自身はインタラクティブではないが、インタラクティブな子要素は動作する
sprite.eventMode = "passive";

// 親がインタラクティブな場合のみヒットテストされる
sprite.eventMode = "auto";

// 標準的なインタラクション: ポインター/マウス/タッチイベントを受け取る
sprite.eventMode = "static";

// static と同様だが、ticker からポインターが静止している場合に
// 合成イベントも発火する（カーソル下のアニメートするオブジェクト用）
sprite.eventMode = "dynamic";

ボタン、UI要素、ドラッグ対象には 'static' を使用します。'dynamic' は静止したカーソル下で移動するオブジェクトで継続的なホバー更新が必要な場合のみ使用します。

isInteractive() を使用してオブジェクトがイベントを受け取れるかどうかを確認できます:

sprite.eventMode = "static";
sprite.isInteractive(); // true

sprite.eventMode = "passive";
sprite.isInteractive(); // false

イベントタイプ

ポインターイベント（クロスデバイス互換性に推奨）: pointerdown, pointerup, pointerupoutside, pointermove, pointerover, pointerout, pointerenter, pointerleave, pointertap, pointercancel.

マウスイベント: mousedown, mouseup, mouseupoutside, mousemove, mouseover, mouseout, mouseenter, mouseleave, click, rightdown, rightup, rightupoutside, rightclick, wheel.

タッチイベント: touchstart, touchend, touchendoutside, touchmove, touchcancel, tap. 各タッチは native TouchEvent からコピーされた altKey, ctrlKey, metaKey, shiftKey を保持しており、修飾キーはマウス/ポインターイベントと同じように動作します。

グローバル move イベント: globalpointermove, globalmousemove, globaltouchmove. これらはポインターがリッスン中のオブジェクト上にあるかどうかに関わらず、すべてのポインター移動時に発火します。

コンテナーライフサイクルイベント（eventMode は不要）: added, removed, destroyed, childAdded, childRemoved, visibleChanged.

リッスンのスタイル

import { Sprite } from "pixi.js";

const sprite = new Sprite();
sprite.eventMode = "static";

// EventEmitter スタイル（推奨）
const handler = (e) => console.log("clicked");
sprite.on("pointerdown", handler);
sprite.once("pointerdown", handler); // 一度きり
sprite.off("pointerdown", handler);

// DOM スタイル
sprite.addEventListener(
  "click",
  (event) => {
    console.log("Clicked!", event.detail);
  },
  { once: true },
);

// プロパティベースのハンドラー
sprite.onclick = (event) => {
  console.log("Clicked!", event.detail);
};

ポインターイベントとプロパゲーション

import { Sprite, Container } from "pixi.js";

const parent = new Container();
parent.eventMode = "static";

const child = new Sprite();
child.eventMode = "static";
parent.addChild(child);

child.on("pointerdown", (event) => {
  console.log("child pressed");
  event.stopPropagation(); // 親がこのイベントを受け取ることを防ぐ
});

parent.on("pointerdown", () => {
  console.log("parent pressed (只有子没有阻止传播时才触发)");
});

キャプチャフェーズイベント

すべてのイベントはイベント名に capture を付加することでキャプチャフェーズをサポートします（例: pointerdowncapture, clickcapture）。キャプチャリスナーはキャプチャフェーズ中、イベントがターゲットに到達する前に発火します。

container.addEventListener(
  "pointerdown",
  (event) => {
    event.stopImmediatePropagation(); // イベントが子要素に到達するのをブロック
  },
  { capture: true },
);

ヒットテスト

ポインターイベントが発火するとき、PixiJS はディスプレイツリーを走査してポインター下の最上位のインタラクティブ要素を見つけます。走査は以下のルールに従います:

• コンテナーで eventMode = 'none' の場合、その要素とサブツリー全体がスキップされます。
• コンテナーで interactiveChildren = false の場合、その子要素がスキップされます（コンテナー自体はテストされます）。
• hitArea は境界ベースのテストをオーバーライドします。形状のみがチェックされます。
• 見えない、レンダー不可、計測不可のオブジェクトはスキップされます。

カスタム hitArea を設定して、境界ベースのテストをオーバーライドできます。これは大きいか複雑なオブジェクトのヒットテストを高速化します:

import { Sprite, Rectangle, Circle, Polygon } from "pixi.js";

const sprite = new Sprite();
sprite.eventMode = "static";

// 矩形ヒットエリア
sprite.hitArea = new Rectangle(0, 0, 100, 50);

// 円形ヒットエリア
sprite.hitArea = new Circle(50, 50, 40);

// ポリゴンヒットエリア
sprite.hitArea = new Polygon([0, 0, 100, 0, 50, 100]);

// contains() 経由のカスタムヒットテスト
sprite.hitArea = {
  contains(x: number, y: number): boolean {
    return x >= 0 && x <= 100 && y >= 0 && y <= 100;
  },
};

グローバル move イベントとドラッグ

import { Sprite, FederatedPointerEvent } from "pixi.js";

const sprite = new Sprite();
sprite.eventMode = "static";
sprite.cursor = "grab";

let dragging = false;

sprite.on("pointerdown", (event: FederatedPointerEvent) => {
  dragging = true;
  sprite.cursor = "grabbing";
});

// globalpointermove はポインターがオブジェクトを離れても発火
sprite.on("globalpointermove", (event: FederatedPointerEvent) => {
  if (dragging) {
    sprite.position.set(event.global.x, event.global.y);
  }
});

sprite.on("pointerup", () => {
  dragging = false;
  sprite.cursor = "grab";
});

sprite.on("pointerupoutside", () => {
  dragging = false;
  sprite.cursor = "grab";
});

カーソルスタイル

基本的な使用方法はオブジェクトごとに cursor プロパティを設定します。再利用可能なカーソルについて、イベントシステムに名前付きスタイルを登録します:

app.renderer.events.cursorStyles.default = "url('bunny.png'), auto";
app.renderer.events.cursorStyles.hover = "url('bunny_saturated.png'), auto";

sprite.eventMode = "static";
sprite.cursor = "hover"; // 登録された 'hover' スタイルを使用

カーソルスタイルは文字列（CSS カーソル値）、オブジェクト（CSS スタイルとして適用）、または関数（モード文字列で呼び出す）です。

イベントプロパティ

FederatedPointerEvent は豊富な入力データを保持します。より有用なフィールドは:

sprite.on("pointerdown", (event: FederatedPointerEvent) => {
  event.global; // イベントが発生したシーン空間の Point
  event.client; // ビューポートに相対的な CSS ピクセル Point
  event.offset; // ワールド空間でターゲット Container w.r.t. の Point（現在サポートされていません）
  event.target; // イベントを受け取った Container
  event.currentTarget; // リスナーが実行されている Container

  event.pointerType; // 'mouse' | 'pen' | 'touch'
  event.pointerId; // マルチタッチ追跡用の一意な ID
  event.isPrimary; // マルチポインタージェスチャーの最初のポインター
  event.pressure; // 0-1 ペン/タッチ圧力
  event.button; // 0 左, 1 中, 2 右
  event.buttons; // 押下されたボタンのビットマスク
  event.altKey; // 修飾キーの状態
  event.ctrlKey;
  event.shiftKey;
  event.metaKey;

  event.nativeEvent; // 基盤となる DOM PointerEvent / MouseEvent / Touch
  event.preventDefault();
  event.stopPropagation();
  event.stopImmediatePropagation();
});

FederatedWheelEvent は deltaX, deltaY, deltaZ, deltaMode を追加します。ホイールイベントはポインターイベントと同じヒットテストされたオブジェクト上で発火します。

イベント機能

パフォーマンスのためイベントカテゴリをグローバルにトグルします:

await app.init({
  eventFeatures: {
    move: true, // ポインター/マウス/タッチ move イベント
    globalMove: true, // グローバル move イベント (globalpointermove など)
    click: true, // click/tap/press イベント
    wheel: true, // マウスホイールイベント
  },
});

// または init 後に設定
app.renderer.events.features.globalMove = false;

パフォーマンスのヒント

• インタラクティブでないサブツリーで eventMode = 'none' を設定してヒットテストを完全にスキップします。
• interactiveChildren = false をコンテナーで設定して、コンテナー自身のみがインタラクション必要な場合。
• 大きいか複雑なオブジェクトで hitArea を使用して、境界ベースのヒットテストを安価な形状チェックに置き換えます。
• 静止要素には 'static' を推奨し、静止したポインター下で移動/アニメートするオブジェクトに 'dynamic' を予約します。
• eventFeatures 経由の未使用イベント機能を無効化します（例: globalMove: false）フレームごとの作業を削減するため。

一般的な間違い

[高] デフォルト eventMode は passive

誤り:

const sprite = new Sprite(texture);
sprite.on("pointerdown", () => {
  console.log("clicked");
});

正解:

const sprite = new Sprite(texture);
sprite.eventMode = "static";
sprite.on("pointerdown", () => {
  console.log("clicked");
});

デフォルト eventMode は 'passive' で、オブジェクト自身はイベントを受け取りません。リスナーが発火する前に明確に eventMode を 'static' または 'dynamic' に設定する必要があります。

[高] buttonMode は削除されました。cursor を使用してください

誤り:

sprite.interactive = true;
sprite.buttonMode = true;

正解:

sprite.eventMode = "static";
sprite.cursor = "pointer";

buttonMode は v8 で削除されました。ホバー時に手のカーソルを表示するには cursor = 'pointer' を使用します。interactive = true は eventMode = 'static' のエイリアスとしてまだ動作しますが、eventMode が推奨されます。

[高] Move イベントは v8 ではオブジェクト上でのみ発火

誤り:

sprite.eventMode = "static";
sprite.on("pointermove", (event) => {
  // どこでも発火することを期待しますが、sprite 境界内でのみ発火
  updateDrag(event.global.x, event.global.y);
});

正解:

sprite.eventMode = "static";
sprite.on("globalpointermove", (event) => {
  // どこでも発火します、sprite 境界外でも
  updateDrag(event.global.x, event.global.y);
});

v8 では、pointermove, mousemove, touchmove はポインターがディスプレイオブジェクト上にある場合のみ発火します。v7 ではキャンバス移動時に発火していました。ドラッグ操作またはグローバル追跡には globalpointermove, globalmousemove, globaltouchmove を使用します。

[中] カーソルは親から継承されません

親コンテナーで cursor を設定しても、その子要素には影響しません。直接ヒットターゲットの cursor 値のみが適用されます。

// これは子要素にポインターカーソルを表示させません
parent.cursor = "pointer";

// 各インタラクティブな子要素は独自のカーソルを必要とします
child.eventMode = "static";
child.cursor = "pointer";

すべての子要素で統一されたカーソルを使用したい場合、各インタラクティブな子要素で cursor を個別に設定するか、親に hitArea を設定して子を非インタラクティブにします。

API リファレンス

• EventSystem
• FederatedEvent
• FederatedPointerEvent
• FederatedMouseEvent
• FederatedWheelEvent
• EventBoundary