pixijs-scene-container

Container は PixiJS v8 のシーングラフの汎用ノードです。子要素を保持し、変形、アルファ、色合い、ブレンドモードをサブツリー全体に適用します。作成するすべてのディスプレイオブジェクトは、ブランチを構築する Container か、その中にネストされるリーフ（Sprite、Graphics、Text、Mesh）のいずれかになります。

pixijs-scene-core-concepts に精通していることを前提としています。

クイックスタート

const group = new Container({
  label: "hero-group",
  x: 200,
  y: 150,
  sortableChildren: true,
});

const body = new Sprite(await Assets.load("body.png"));
const head = new Sprite(await Assets.load("head.png"));
head.position.set(0, -40);
head.zIndex = 1;

group.addChild(body, head);
group.pivot.set(group.width / 2, group.height / 2);
group.scale.set(1.5);

app.stage.addChild(group);

関連スキル: pixijs-scene-core-concepts（シーングラフの思考モデル、マスキング、レイヤー、レンダーグループ）、pixijs-scene-sprite / pixijs-scene-graphics / pixijs-scene-text / pixijs-scene-mesh（コンテナの内部に配置されるリーフオブジェクト）、pixijs-events（eventMode、ヒットテスト）、pixijs-math（Matrix、toGlobal/toLocal の詳細）、pixijs-performance（cacheAsTexture、カリング、レンダーグループ）。

コアパターン

コンストラクタオプション

const container = new Container({
  label: "world",
  x: 100,
  y: 50,
  scale: 2,
  rotation: Math.PI / 4,
  alpha: 0.8,
  visible: true,
  tint: 0xffaa00,
  blendMode: "add",
  sortableChildren: true,
  isRenderGroup: true,
  origin: { x: 0, y: 0 },
  boundsArea: new Rectangle(0, 0, 1920, 1080),
});

すべての Container オプション（position、scale、tint、label、filters、zIndex など）もここで有効です — skills/pixijs-scene-core-concepts/references/constructor-options.md を参照してください。

Container コンストラクタは assignWithIgnore を使用して、options オブジェクト内のすべてのフィールドをインスタンスにバルクコピーしますが、children、parent、effects は除きます。Container のすべてのパブリックプロパティは有効なコンストラクタオプションです：cullable、cullArea、mask、filterArea、eventMode、hitArea など。上記の options ブロックは最も一般的なものをグループ化しています。完全なリストについては、上記の共有リファレンスを参照してください。

isRenderGroup: true はコンテナを独自のレンダーグループに昇格させるため、その変形は CPU で子ごとに再計算される代わりに GPU で適用されます。安定したサブツリー（大規模な静的ワールド、UI レイヤー）に使用します。過度に使用しないでください。ほとんどのシーンは明示的なレンダーグループを必要とせず、多すぎるとパフォーマンスが低下します。昇格させる前にプロファイルしてください。pixijs-scene-core-concepts/references/scene-management.md を参照してください。

sortableChildren: true は、次のレンダーで子が zIndex で再度ソートされるようにします。以下の zIndex を参照してください。

origin は第一級の v8 変形ヘルパーです：ObservablePoint で、コンテナを移動せずに回転/スケールの中心として機能します。pivot はローカル原点のプロジェクションを親空間にシフトし（回転中心を変更することで オブジェクトを移動させる）、origin は位置を変わらず、指定されたローカルポイント周辺で単に回転/スケールします。PointData、単一の数値（両軸に適用される）を受け付けるか、container.origin.set(x, y) 経由でライブに設定できます。同じコンテナに pivot と origin の両方を設定すると、複合動作が発生し、推奨されません。1 つを選択してください。

boundsArea は getBounds() を強制的に子を再帰的に測定する代わりに固定矩形を返します。これは数百の安価で予測可能な子を持つコンテナのパフォーマンス向上です。

cullable と cullArea は有効なコンストラクタオプション（assignWithIgnore パスは他のフィールドと同様にコピーします）ですが、カリングの設定はシーングラフの懸念ではなくパフォーマンスの懸念であるため、pixijs-performance に記載されています。

リーフ vs コンテナ

const parent = new Container();
const sprite = new Sprite(texture);

parent.addChild(sprite);

Container（および RenderLayer のような子を保持する意図したサブクラス）のみが子を持つべきです。Sprite、Graphics、Text、Mesh、ParticleContainer パーティクル、および DOMContainer コンテンツは PixiJS v8 の慣例によってリーフです。物をグループ化する必要があるときはいつでも Container でラップしてください。コンテナにレイアウトロジックを与え、リーフを純粋なビジュアルデータとして保ちます。リーフに子を追加するとデプリケーション警告がログに記録され、将来のバージョンではハードエラーになる予定です。

子の追加と削除

const parent = new Container();

parent.addChild(a, b, c);
parent.addChildAt(d, 0);
parent.swapChildren(a, b);
parent.setChildIndex(c, 0);

parent.removeChild(b);
parent.removeChildAt(0);
parent.removeChildren();

parent.removeChildren(0, 2);

addChild は任意の数の子を受け付け、最初のものを返します。子は配列の順序でレンダリングされます。インデックス 0 は最初に描画されます（背後）、最後のインデックスは最後に描画されます（前方）。addChildAt は特定のインデックスに挿入します。setChildIndex は既存の子を移動します。swapChildren は 2 つの子の位置を交換します。

removeChildren(beginIndex?, endIndex?) はスライスを削除し、削除された配列を返します。

既に同じコンテナに属する子で addChildAt を呼び出すと、暗黙的に新しいインデックスに移動します。親子関係は変わらないため、added / childAdded / removed / childRemoved イベントは発火しません。イベントは子が別の親から来たときのみ発火します（または親がいない場合）。

ワールド変形を保持する再親化（子が視覚的にジャンプしない）では、reparentChild / reparentChildAt を使用します。古い子のローカル変形をコピーしながら所定の位置で子を交換する場合は、replaceChild を使用します。

変形プロパティ

const obj = new Container();

obj.x = 100;
obj.y = 200;
obj.position.set(100, 200);

obj.scale.set(2);
obj.scale = 2;

obj.rotation = Math.PI / 4;
obj.angle = 45;

obj.pivot.set(50, 50);
obj.skew.set(0.1, 0.2);

obj.alpha = 0.5;
obj.tint = 0xff0000;
obj.visible = false;
obj.renderable = false;

• position、scale、pivot、skew は ObservablePoint です。scale = 2 を割り当てることは有効であり、両軸を設定します。
• rotation はラジアン。angle は度数。それらはエイリアスで同期を保ちます。
• pivot はローカル空間の点を設定し、親空間の position にマップします。変更すると、コンテナを移動させ、回転させます。
• alpha と tint は子に掛け算で伝播します。blendMode はこのコンテナの描画命令に適用されます。
• visible = false はレンダリングと変形更新をスキップします。renderable = false はレンダリングをスキップしますが、変形の更新は続けます（描画なしで getBounds() またはヒットテストが必要な場合に使用）。

zIndex と sortableChildren

const world = new Container({ sortableChildren: true });

const ground = new Sprite(groundTexture);
ground.zIndex = 0;

const player = new Sprite(playerTexture);
player.zIndex = 10;

const ui = new Sprite(uiTexture);
ui.zIndex = 100;

world.addChild(ground, player, ui);

sortableChildren が true の場合、コンテナは次のレンダー前に zIndex で子を再ソートします。子の zIndex を変更すると、親が自動的に再ソートが必要なものとしてマークされます。必要なものだけをソートしてください。sortableChildren を無効のままにする方が安くなります。完全な手動制御が必要な場合は、zIndex 値を変更した後、container.sortChildren() を自分で呼び出してください。

階層と分離された レンダーオーダーコントロール（子はロジカルペアレントを保ちますが、別の z でレンダリング）については、RenderLayer を使用します。pixijs-scene-core-concepts/references/scene-management.md を参照してください。

バウンズと座標変換

const bounds = container.getBounds();
console.log(bounds.x, bounds.y, bounds.width, bounds.height);

const rect = container.getBounds().rectangle;

const local = new Point(10, 20);
const world = container.toGlobal(local);
const backToLocal = container.toLocal(world);

const selfPos = container.getGlobalPosition();

getBounds() は Bounds オブジェクト（Rectangle ではない）を返します。基本的なゲッター（x、y、width、height）機能しますが、.contains() のような Rectangle 固有のメソッドまたは Rectangle を必要とする API に渡す場合は、.rectangle プロパティを読み込みます。シグネチャは getBounds(skipUpdate?: boolean, bounds?: Bounds) です — 強制的な変形更新をスキップするには最初の引数として true を渡し、新しいインスタンスを割り当てることを避けるために 2 番目の引数として オプションの Bounds インスタンスを渡します。

toGlobal(point) はこのコンテナのローカル空間の点をシーンルート空間に変換します。toLocal(point, from?) は別のコンテナのローカル空間（または from を省略した場合はグローバル空間）から変換します。getGlobalPosition() は parent.toGlobal(this._position) の短縮形です。

サイズ指定

const sprite = new Sprite(texture);

sprite.setSize(200, 100);
const { width, height } = sprite.getSize();

setSize は scale を調整し、コンテナのバウンズが要求されたピクセルサイズに収まるようにします（1 つの操作）。.width と .height を個別に設定すると機能しますが、各割り当てはバウンズの再計算をトリガーします。両軸を変更する場合は setSize を優先してください。

コンテナイベント

const parent = new Container();

parent.on("childAdded", (child, container, index) => {
  console.log("added at", index, child.label);
});

parent.on("childRemoved", (child, container, index) => {
  console.log("removed from", index);
});

const child = new Container();
child.on("added", (newParent) => console.log("entered", newParent.label));
child.on("removed", (oldParent) => console.log("left", oldParent.label));
child.on("visibleChanged", (visible) => console.log("visible:", visible));
child.on("destroyed", (destroyed) => console.log("gone", destroyed.label));

parent.addChild(child);

イベント	発火する対象	引数
childAdded	子を受け取る親	(child, container, index)
childRemoved	子を失う親	(child, container, index)
added	アタッチされた子	(parent)
removed	デタッチされた子	(parent)
destroyed	破棄されたコンテナ	(container)
visibleChanged	visible がフリップしたコンテナ	(visible)

これらは Container の EventEmitter 側で発出されます。pixijs-events からのポインタイベントと混同しないでください。

destroyed は内部クリーンアップ後ですがリスナーが削除される前に発火するため、ハンドラが実行される時点で position、scale、pivot、origin、skew、parent はすでに null になっており、children は空になっています（長さ 0、ただし配列参照自体は null ではない）。ハンドラの内部ではなく、destroy() を呼び出す前に、コンテナから必要なデータをキャプチャしてください。

onRender でのフレームごとの更新

const container = new Container();

container.onRender = (renderer) => {
  container.rotation += 0.01;
};

container.onRender = null;

onRender はコンテナがレンダリングされている間、毎フレーム実行され、アクティブな Renderer を受け取ります。特定のコンテナに関連付けられた軽量なアニメーションまたはフレームごとの更新に使用します。v7 ではこのパターンは updateTransform をオーバーライドすることで実行されていたが、v8 では毎フレーム実行されなくなります。onRender = null を設定してコールバックをデタッチします。

ラベルで検索して親から削除

const player = world.getChildByLabel("player");
const enemies = world.getChildrenByLabel(/enemy-\d+/, true);

const bounds = hud.getLocalBounds();

oldSprite.removeFromParent();

• getChildByLabel(label, deep?) — 文字列または RegExp で最初にマッチ。再帰的な検索は true を渡します。
• getChildrenByLabel(label, deep?, out?) — すべてのマッチ。オプションの再利用可能な出力配列を受け付けます。
• getLocalBounds() — このコンテナ独自の座標空間内のバウンズ、親の変形を無視します。自己完結型のレイアウト計算の場合、getBounds() より安くなります。
• removeFromParent() — 現在の親からこのインスタンスをデタッチします（既にオーファンの場合はノーオペレーション）。

破棄

container.destroy();

container.destroy({
  children: true,
  texture: true,
  textureSource: true,
});

console.log(container.destroyed);

デフォルトでは destroy() はこのコンテナを親からアンリンクし、その独自の状態を破棄します。{ children: true } を渡して、すべての子孫を再帰的に破棄します。これはサブツリー全体を強制するための通常の呼び出しです。texture: true と textureSource: true はさらに、リーフ子によって参照される GPU リソースを破棄します（それらのためにロードされたテクスチャを持つスプライトに便利）。cacheAsTexture がオンの場合、破棄する前に container.cacheAsTexture(false) で無効にします。

一般的な間違い

[CRITICAL] リーフシーンオブジェクトへの子の追加

間違い：

const sprite = new Sprite(texture);
const overlay = new Sprite(overlayTexture);
sprite.addChild(overlay);

正解：

const group = new Container();
const sprite = new Sprite(texture);
const overlay = new Sprite(overlayTexture);
group.addChild(sprite, overlay);

Sprite、Graphics、Text、Mesh はリーフです。子を追加すると、現在はデプリケーション警告がログに記録され、将来のバージョンではエラーになります。グループ化が必要なときはいつでも Container でラップしてください。

[HIGH] getBounds() が Rectangle を返すことを期待

間違い：

const rect = container.getBounds();
rect.contains(x, y); // TypeError: contains is not a function

正解：

const rect = container.getBounds().rectangle;
rect.contains(x, y);

const bounds = container.getBounds();
console.log(bounds.width, bounds.height);

getBounds() は v8 で Bounds インスタンスを返します。その基本的なゲッター（x、y、width、height）は機能しますが、.contains() のような Rectangle 固有のメソッドや Rectangle を必要とする API に渡す場合は、.rectangle プロパティを読み込みます。

[HIGH] cacheAsBitmap の代わりに cacheAsTexture を使用

間違い：

container.cacheAsBitmap = true;

正解：

container.cacheAsTexture(true);

cacheAsBitmap（v7 プロパティ）は v8 で cacheAsTexture()（メソッド）に名前が変更されました。destroy() を呼び出す前に、常に cacheAsTexture(false) で無効にします。

[MEDIUM] container.name の代わりに container.label を使用

name は v8 で label に名前が変更されました。古いプロパティはまだ非推奨エイリアスとして機能します。getChildByLabel は v8 の子を名前で検索する方法です。

[MEDIUM] 同じコンテナに pivot と origin の両方を設定

Pivot はローカル原点のプロジェクションを親空間にシフトします（回転中心を変更することで オブジェクトを移動させる）。Origin は回転/スケール中心を位置を変わらずに変更します。同じコンテナに両方を設定すると、予期しない複合動作が発生します。1 つを選択してください。

API リファレンス

• Container
• ContainerOptions
• ViewContainer
• Bounds
• Point
• ObservablePoint
• RenderGroup