pixijs-scene-core-concepts

このスキルは、すべての pixijs-scene-* リーフで参照される共有メンタルモデルです。PixiJS v8 のシーングラフとは何か、Container がリーフとどう違うか、そして各概念がどこに存在するかを説明します。特定の API を詳しく説明することはなく、パーツを枠組みしてその説明をしているスキルやリファレンスファイルを示します。

クイックスタート

const world = new Container({ isRenderGroup: true });
app.stage.addChild(world);

const hero = new Container({ label: "hero" });
hero.addChild(new Sprite(bodyTexture));
hero.addChild(new Sprite(faceTexture));
world.addChild(hero);

const mask = new Graphics().rect(0, 0, 800, 600).fill(0xffffff);
world.mask = mask;
world.addChild(mask);

hero.position.set(world.width / 2, world.height / 2);

関連スキル: pixijs-scene-container (Container API の詳細)、リーフスキル (pixijs-scene-sprite、pixijs-scene-graphics、pixijs-scene-text、pixijs-scene-mesh、pixijs-scene-particle-container、pixijs-scene-dom-container、pixijs-scene-gif)、pixijs-events (ヒットテストはシーングラフを走査する)、pixijs-performance (キャッシュ、カリング、レンダーグループ)、pixijs-math (Matrix、toGlobal/toLocal の詳細)。

コアコンセプト

シーングラフとは

PixiJS のシーングラフは、app.stage をルートとする表示オブジェクトのツリーです。各ノードには親、親に対する相対的な変換 (位置、スケール、回転、ピボット、スキュー)、およびオプションの視覚状態 (透明度、色合い、ブレンドモード、表示/非表示) があります。毎フレーム、レンダラーはツリーを走査し、変換と視覚状態をワールドスペースに合成し、画面外にあるものをカリングして、ドロー呼び出しを発行します。シーングラフはレイアウトモデルであり、レンダー順序でもあります。兄弟ノードは後ろから描画されます。

v8 のすべての表示オブジェクトは Container サブクラスです。以前のバージョンの DisplayObject は削除されました。

Container vs リーフ (CRITICAL)

ツリーには 2 つの役割があります。

• Containers: 子を保持するノード。他のノードをグループ化、位置決め、または変換する任意のノードに Container (または RenderLayer) を使用します。
• Leaves: 何かを描画し、子を持たないノード。Sprite、Graphics、Text、Mesh、ParticleContainer の Particle、DOMContainer、または GifSprite をリーフとして使用します。

PixiJS v8 では、リーフは子を持つべきではありません。Sprite / Graphics / Text / Mesh に子を追加すると非推奨警告がログに出力され、ハードエラーになることが予定されています。ルールは次のとおりです: 子が必要なすべてのノードに Container を使用する。リーフシーンオブジェクト内に子をネストしない。 リーフを他のリーフでグループ化する必要がある場合は、Container でラップします。

この区別により、pixijs-scene-* スキルが以下のように分割されている理由が説明されます: pixijs-scene-container はグループ化ノードをカバーし、各リーフはその描画動作に焦点を当てた独自のスキルを取得します。

変換と座標スペース

すべての container は、その position、scale、rotation、pivot、および skew から localTransform (A Matrix) を合成します。レンダラーは親のローカル変換を乗算して worldTransform (およびレンダーグループがチェーン内にある場合は groupTransform) を生成し、ローカルポイントをシーンルートスペースにマップします。toGlobal(point) と toLocal(point, from?) を使用してスペース間を変換し、getGlobalPosition() でこのオブジェクトのワールド位置を取得します。Matrix の詳細は pixijs-math にあります。変換セッターと toLocal/toGlobal は pixijs-scene-container にあります。

レンダー順序と明示的な Z 順序付け

子はアレイ順にレンダリングされます。インデックス 0 は最初、最後のインデックスは最後です。単一の container での明示的な Z 順序付けについては、sortableChildren = true を設定し、子に zIndex 値を割り当てます。レンダー順序が論理的階層から分離されている場合 (例: キャラクターの親がゲームワールドだが、描画が UI レイヤーで行われる)、RenderLayer を使用します。sortable children と RenderLayer のどちらを優先するかを含む深い詳細は、references/scene-management.md にあります。

レンダーグループ

isRenderGroup: true でコンテナにフラグを立てる (または container.enableRenderGroup() を呼び出す) ことで、PixiJS に対してその変換を GPU に単一のマトリックスとして適用するよう、フレームごとに CPU で各子孫のワールド変換を再計算する代わりに指示します。ワールド、UI レイヤー、パラレックスストリップなどの大規模で安定した部分木にレンダーグループを使用します。深い詳細は references/scene-management.md にあります。

カリング

cullable = true + cullArea: Rectangle を設定すると、CullerPlugin (またはカリングパス) に対して、表示可能な領域外にあるオブジェクトのレンダリングをスキップするよう指示します。cullableChildren = false は、子が常に画面上にある部分木の再帰的カリングをショートサーキットします。カリングはパフォーマンストピックです。pixijs-performance と references/scene-management.md はトレードオフをカバーしています。

マスキング

別の表示オブジェクトに container.mask を設定して、その描画をクリップします。PixiJS はマスクタイプを自動的に選択します: Graphics または Container マスクはステンシルバッファを使用し、Sprite マスクはアルファフィルターを使用し、数値は ColorMask を選択します。4 つのマスクタイプ (AlphaMask、StencilMask、ScissorMask、ColorMask) はすべて references/masking.md でカバーされています。

表示/非表示、透明度、色合い、ブレンドモード

visible = false はレンダリングと変換更新をスキップします。renderable = false はレンダリングをスキップしますが、変換は更新します (ヒットテストまたは境界クエリをライブのままにしておく必要がある場合に使用します)。alpha と tint は部分木全体に乗算されます。blendMode は、このコンテナの描画命令がターゲット上に既にあるものに対してどのように合成されるかを制御します。ブレンドモードの完全なリストは pixijs-blend-modes で、ノードごとの状態は pixijs-scene-container で参照してください。

Destroy セマンティクス

container.destroy() は 1 つのノードのリンクを解除します。container.destroy({ children: true }) は部分木全体を再帰的に破棄します。ブランチを削除するときはこれを常に使用します。texture: true と textureSource: true は、リーフが所有する GPU リソースをさらに取り除きます。cacheAsTexture がオンの場合、破棄する前に無効にします。完全なシグネチャは pixijs-scene-container で文書化されています。

ライフサイクルイベント

コンテナーは階層と表示/非表示の変更に関するイベントを発行します: 親に対する childAdded / childRemoved、子に対する added / removed、およびコンテナー自体に対する visibleChanged と destroyed。リアクティブ UI の更新またはリソースブックキーピングの配線に役立ちます。完全な詳細は references/container-hierarchy.md にあります。

リーフの比較: どのスキルがどのオブジェクトをカバーするか

リーフ	主な用途	スキル
Sprite	単一のテクスチャを位置に描画 (UI パネルをサイズ変更可能にする NineSliceSprite と、背景を繰り返す TilingSprite のバリアント)	pixijs-scene-sprite
Text / BitmapText / HTMLText / SplitText / SplitBitmapText	テキストをレンダリング。汎用の Canvas ベースの Text、大量の安価なテキストの BitmapText、リッチ HTML/CSS レイアウトの HTMLText、文字ごとのアニメーション用の分割バリアント	pixijs-scene-text
Graphics	ベクトル描画: 図形、線、パス、塗りつぶし、ストローク。GraphicsContext でサポート	pixijs-scene-graphics
Mesh / MeshSimple / MeshPlane / MeshRope / PerspectiveMesh	シェーダーまたはテクスチャを使用したカスタムジオメトリ。テクスチャ付きパスに従うリボンに MeshRope を使用し、2D パースペクティブに PerspectiveMesh を使用	pixijs-scene-mesh
ParticleContainer + Particle	制限された変換セットで数千の軽量なスプライト。高スループット パーティクル効果用	pixijs-scene-particle-container
DOMContainer	シーングラフ内に配置された HTML 要素をレンダリング (入力、iframe、アクセシビリティオーバーレイに便利)	pixijs-scene-dom-container
GifSprite	アニメーション GIF 再生を表示オブジェクトとして。pixi.js/gif が必要	pixijs-scene-gif

Container 自体は pixijs-scene-container でカバーされており、すべてのリーフが存在するノードです。

何を使うか (クイック判断)

• 「複数の表示オブジェクトをグループ化して変換したい」→ Container、pixijs-scene-container を参照。
• 「テクスチャを描画したい」→ Sprite、pixijs-scene-sprite を参照。
• 「ベクター図形またはパスを描画したい」→ Graphics、pixijs-scene-graphics を参照。
• 「テキストを描画したい」→ Text / BitmapText / HTMLText、pixijs-scene-text を参照。
• 「数千の安価なスプライトを描画したい」→ ParticleContainer、pixijs-scene-particle-container を参照。
• 「カスタムジオメトリメッシュまたは変形スプライトを描画したい」→ Mesh またはそのバリアント、pixijs-scene-mesh を参照。
• 「部分木をクリップしたい」→ .mask を設定、references/masking.md を参照。
• 「デカップリングされたレンダー順序が必要」→ RenderLayer、references/scene-management.md を参照。
• 「大規模で安定した部分木に GPU レベルの変換が必要」→ isRenderGroup: true、references/scene-management.md を参照。
• 「オフスクリーンレンダリングをスキップしたい」→ cullable = true + CullerPlugin、pixijs-performance を参照。

リファレンス

• references/constructor-options.md: すべての Container 派生ノードによって継承される約 30 個のフィールド (変換、表示、階層、ソート、レイアウト、エフェクト、コールバック)、デフォルト、型、および行ごとの割り当てが適切な場合。すべてのリーフスキルの共有リファレンス。
• references/container-hierarchy.md: 子の追加/削除/入れ替え、変換保存によるリペアレント化、ラベルナビゲーション、部分木の破棄。
• references/transforms.md: 位置、スケール、回転、ピボット、原点、スキュー、toGlobal/toLocal、3 つの行列 (local/group/world)、境界。
• references/masking.md: AlphaMask、StencilMask、ScissorMask、ColorMask、逆マスキング、コスト比較。
• references/layers.md: RenderLayer、アタッチ/デタッチ、ソート済みレイヤー、レイヤー + 論理親の分割。
• references/render-groups.md: isRenderGroup、GPU レベルの変換、使用時期、レンダーグループ vs cacheAsTexture。
• references/scene-management.md: 統合ビュー。レンダーグループ、RenderLayer、カリング、zIndex ソート、boundsArea。

よくある間違い

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

間違い:

const sprite = new Sprite(texture);
sprite.addChild(new Graphics().rect(0, 0, 10, 10).fill(0xff0000));

正解:

const group = new Container();
group.addChild(new Sprite(texture));
group.addChild(new Graphics().rect(0, 0, 10, 10).fill(0xff0000));

v8 ではリーフ (Sprite、Graphics、Text、Mesh、ParticleContainer、DOMContainer、GifSprite) は技術的には Container を拡張しますが、子を保持すべきではありません。リーフに子を追加すると、未定義のレンダリング動作が発生します。グループ化が必要な場合は、リーフを Container でラップしてください。

[CRITICAL] DisplayObject への参照

間違い:

import { DisplayObject } from "pixi.js"; // v8 にはそのようなエクスポートがない
function moveNode(node: DisplayObject) {
  node.x += 1;
}

正解:

import { Container } from "pixi.js";
function moveNode(node: Container) {
  node.x += 1;
}

DisplayObject は v8 で削除されました。Sprite、Graphics、Text、Mesh を含むすべての表示オブジェクトが、現在は Container サブクラスです。ベース型として Container を使用します。

[HIGH] 大規模な静的部分木での isRenderGroup の忘却

間違い:

const world = new Container();
for (let i = 0; i < 5000; i++) {
  world.addChild(new Sprite(texture));
}
app.stage.addChild(world);

正解:

const world = new Container({ isRenderGroup: true });
for (let i = 0; i < 5000; i++) {
  world.addChild(new Sprite(texture));
}
app.stage.addChild(world);

isRenderGroup: true がない場合、レンダラーはフレームごとに親に対してすべての子の変換を再合成します。部分木をレンダーグループとしてマークすると、子が変わるまで変換と描画状態がキャッシュされます。これは大規模またはほぼ静的なツリーに不可欠です。

[HIGH] child.x をワールドスペースとして扱う

間違い:

const enemy = new Container();
enemy.x = 500;
world.addChild(enemy);
world.x = 200;
console.log(enemy.x); // 500 (local)、700 (world) ではない

正解:

const worldPos = enemy.toGlobal({ x: 0, y: 0 });
console.log(worldPos.x); // 700

Container.x/y/scale/rotation は親の LOCAL です。ワールドスペース座標を計算するには toGlobal(point) を使用するか、コンテナーのワールド空間での原点に対して getGlobalPosition() を使用します。ワールド変換は単純な x/y のペアとして公開されていません。

[MEDIUM] zIndex なしの sortableChildren

間違い:

const layer = new Container();
layer.sortableChildren = true;
layer.addChild(bg); // zIndex なし
layer.addChild(mid); // zIndex なし
layer.addChild(fg); // zIndex なし
// 順序は変わらない — すべての zIndex のデフォルトは 0

正解:

const layer = new Container();
layer.sortableChildren = true;
bg.zIndex = 0;
mid.zIndex = 10;
fg.zIndex = 20;
layer.addChild(bg, mid, fg);

sortableChildren はレンダリング前に子を zIndex でソートし直しますが、子が実際に異なる zIndex 値を持つ場合にのみ有効になります。親フラグのみを設定しても目に見える効果はありません。

ツーリング

PixiJS Devtools Chrome 拡張機能を使用すると、実行中のシーングラフをリアルタイムで検査および操作できます。平凡でないレイアウトまたはレンダー順序のデバッグに備えてインストールしてください。

API リファレンス

• Container
• ViewContainer
• RenderLayer
• RenderGroup
• Bounds
• Culler
• CullerPlugin