pixijs-scene-particle-container

ParticleContainer は、数百から数万の軽量なスプライトを 1 つのドロー呼び出しでレンダリングするための特殊なコンテナです。パーティクルエフェクト、弾幕パターン、または同じような見た目を持つ大量のオブジェクトが必要な場合に使用します。オブジェクトごとのオーバーヘッドが最小限です。パーティクルは単一のベーステクスチャを共有し、制限されたトランスフォームセットを持ちます。これらは完全な Container の子ではありません。

pixijs-scene-core-concepts に精通していることを前提としています。ParticleContainer は別の意味での特殊なリーフです。独自の particleChildren 配列に Particle インスタンスを含み、通常の PixiJS の子を拒否します。addChild ではなく addParticle を使用し、シーンオブジェクトの他の部分とグループ化する必要がある場合は、ParticleContainer 全体を Container でラップします。

Particle API は v8 で新しく導入されていますが、本番環境での使用に対して安定しています。

クイックスタート

const texture = await Assets.load("particle.png");

const container = new ParticleContainer({
  texture,
  boundsArea: new Rectangle(0, 0, app.screen.width, app.screen.height),
  dynamicProperties: {
    position: true,
    rotation: false,
    color: false,
  },
});

for (let i = 0; i < 10000; i++) {
  container.addParticle(
    new Particle({
      texture,
      x: Math.random() * app.screen.width,
      y: Math.random() * app.screen.height,
    }),
  );
}

app.stage.addChild(container);

関連スキル: pixijs-scene-core-concepts（シーングラフの基本）、pixijs-scene-sprite（オブジェクトごとに完全な機能が必要な場合）、pixijs-assets（共有テクスチャ、アトラス）、pixijs-performance（バッチング、テクスチャ最適化）、pixijs-scene-container（他のディスプレイオブジェクトでラップ）。

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

ParticleContainerOptions

すべての Container オプション（position、scale、tint、label、filters、zIndex など）もここで有効です。skills/pixijs-scene-core-concepts/references/constructor-options.md を参照してください。children は省略されています。代わりに particles を使用します。

オプション	型	デフォルト	説明
texture	Texture	null	すべてのパーティクル用の共有ベーステクスチャ。省略されている場合、コンテナは追加された最初のパーティクルのテクスチャにフォールバックします。すべてのパーティクルは同じベーステクスチャソースを共有する必要があります。
particles	T[]	[]	Particle（または IParticle）インスタンスの初期配列。各要素に対して addParticle を呼び出すのと同等ですが、呼び出しごとのビュー更新をスキップします。
dynamicProperties	ParticleProperties	{ vertex: false, position: true, rotation: false, uvs: false, color: false }	パーティクル属性がフレームごとに GPU に再アップロードされるかどうかのフラグ。デフォルトではтолько position が動的です。アニメーション化するプロパティをマークし、残りは速度のため静的のままにします。
roundPixels	boolean	false	パーティクルの位置を最も近いピクセルに丸めます。ピクセルアート風のスタイルではより鮮明なレンダリングを生成しますが、スムーズなサブピクセルモーションを犠牲にします。
shader	Shader	デフォルトパーティクルシェーダ	デフォルトのパーティクルシェーダを任意の Shader インスタンスで置き換えます。カスタムシェーダは aPosition、aUV、aColor を宣言する必要があり、dynamicProperties で有効にされた動的属性も同様です。

boundsArea は Container から継承されていますが、ParticleContainer では事実上必須です。パフォーマンスのためにコンテナはデフォルトで空の境界 (0, 0, 0, 0) を返すため、boundsArea がないとカリングが有効な場合に見えないものとしてカリングされ、containsPoint は常にミスします。

ParticleOptions

Particle は軽量な構造体で、Container サブクラスではありません。ContainerOptions フィールドは適用されません。完全なオプションリスト：

オプション	型	デフォルト	説明
texture	Texture	—	必須。このパーティクルをレンダリングするテクスチャ。同じ ParticleContainer 内のすべてのパーティクルは同じベーステクスチャソースを共有する必要があります。
x	number	0	コンテナのローカルスペースでの X 位置。
y	number	0	コンテナのローカルスペースでの Y 位置。
scaleX	number	1	水平スケール係数。
scaleY	number	1	垂直スケール係数。
anchorX	number	0	0–1 範囲での水平アンカー。0 は左、0.5 は中央、1 は右。
anchorY	number	0	0–1 範囲での垂直アンカー。0 は上、0.5 は中央、1 は下。
rotation	number	0	ラジアン単位での回転。
tint	ColorSource	0xffffff	16 進数または CSS カラー文字列としてのティント色。alpha と一緒に内部の color フィールドに結合されます。
alpha	number	1	透明度（0–1）。範囲外の値はクランプされます。tint と一緒に内部の color フィールドに結合されます。

コンストラクタは、その唯一の引数としてベアな Texture も受け入れます（new Particle(texture)）。これは上記のデフォルトを使用して new Particle({ texture }) の短縮形です。

Particle.defaultOptions は静的オブジェクトで、グローバルにデフォルトを変更するために再割り当てできます。以下の「パーティクル作成」セクションを参照してください。

コアパターン

パーティクル作成

const particle = new Particle({
  texture,
  x: 100,
  y: 200,
  scaleX: 0.5,
  scaleY: 0.5,
  anchorX: 0.5,
  anchorY: 0.5,
  rotation: Math.PI / 4,
  tint: 0xff0000,
  alpha: 0.8,
});

container.addParticle(particle);

Particle は平坦な数値フィールドを持つ軽量な構造体です。x、y、scaleX、scaleY、anchorX、anchorY、rotation、color、texture があります。また、内部の color フィールドに結合される tint（16 進数/CSS カラー）と alpha（0-1）をセッターとして公開します。トランスフォーム階層、イベント、フィルタはありません。

唯一の引数として Texture を直接渡すことができます。new Particle(texture)。

Particle.defaultOptions をオーバーライドしてグローバルにデフォルトを変更します。

Particle.defaultOptions = {
  ...Particle.defaultOptions,
  anchorX: 0.5,
  anchorY: 0.5,
};

particles オプションで事前に入力

const particles = Array.from(
  { length: 10000 },
  () =>
    new Particle({
      texture,
      x: Math.random() * 800,
      y: Math.random() * 600,
    }),
);

const container = new ParticleContainer({
  texture,
  boundsArea: new Rectangle(0, 0, 800, 600),
  particles,
});

コンストラクタで particles を渡すことは、コンテナを空で作成してから各要素に対して addParticle を呼び出すのと同等ですが、呼び出しごとのビュー更新を回避します。

動的プロパティと静的プロパティおよび update()

const container = new ParticleContainer({
  dynamicProperties: {
    rotation: true,
  },
});

dynamicProperties は、パーティクル属性がフレームごとに GPU に再アップロードされるかを制御します。ParticleContainer.defaultOptions.dynamicProperties のデフォルトは以下の通りです。

{ vertex: false, position: true, rotation: false, uvs: false, color: false }

アニメーション化しているプロパティのみをオーバーライドする必要があります。残りはデフォルトを継承します（位置は動的、その他はすべて静的）。合計 5 つのプロパティがあります。

• vertex：スケール/アンカー頂点
• position：位置
• rotation：回転
• uvs：テクスチャ座標（フレーム交換パーティクル用）
• color：ティントとアルファ

アニメーション化しているもののみをマークしてください。静的プロパティの方が安くなります。実行時に静的プロパティを変更した場合は、container.update() を呼び出して再アップロードします。

container.particleChildren.forEach((p) => {
  p.tint = 0x00ff00;
});
container.update();

particleChildren のバッチ操作

// バルク追加
const batch = [];
for (let i = 0; i < 5000; i++) {
  batch.push(
    new Particle({ texture, x: Math.random() * 800, y: Math.random() * 600 }),
  );
}
container.particleChildren.push(...batch);
container.update();

// バルク削除
container.particleChildren.length = 0;
container.update();

addParticle、addParticleAt、removeParticle、removeParticleAt、removeParticles はすべて呼び出しごとにビュー更新をトリガーします。大規模なバッチ操作の場合、直接配列操作に加えて 1 回の update() の方が高速です。

テクスチャとシェーダオプション

ParticleContainerOptions の texture はオプショナルです。省略された場合、コンテナは追加された最初のパーティクルのテクスチャにフォールバックします。その後のすべてのパーティクルは同じベーステクスチャソースを共有する必要があります。アトラスを事前に宣言する場合、または最初のパーティクルが実行中に変わる可能性がある場合に明示的に設定します。

const container = new ParticleContainer({ texture });

shader を使用すると、デフォルトのパーティクルシェーダを任意の Shader インスタンスで置き換えられます。カスタムシェーダは、パーティクルパイプがアップロードする属性（aPosition、aUV、aColor、および dynamicProperties で有効にされた動的属性）を宣言する必要があります。これを使用して、カスタムブレンディング数学、距離フィールドスプライト、または非標準エフェクトに使用します。

const container = new ParticleContainer({ texture, shader: myCustomShader });

制限事項

ParticleContainer は意図的に機能を犠牲にして速度を優先します。

• 個別のパーティクルにフィルタ、マスク、ブレンドモードはありません。
• パーティクル上にネストされた子はありません。
• 自動境界計算はありません。
• すべてのパーティクルは同じベーステクスチャソースを共有する必要があります（アトラスは機能します。複数の関連のないテクスチャは機能しません）。
• カスタムシェーダは shader オプションでサポートされています。

コンテナメソッドの移行

ParticleContainer は GPU バッファ更新向けに最適化された別の子管理 API を使用します。標準の Container 子メソッドは ParticleContainer で呼び出されるとスローします。

標準 Container メソッド	ParticleContainer 同等物
addChild(child)	addParticle(particle)
removeChild(child)	removeParticle(particle)
addChildAt(child, index)	addParticleAt(particle, index)
removeChildAt(index)	removeParticleAt(index)
removeChildren(begin, end)	removeParticles(begin, end)
getChildAt(index)	container.particleChildren[index] に直接アクセス
swapChildren()	利用不可
reparentChild()	利用不可

よくある間違い

[CRITICAL] ParticleContainer へのスプライト追加

間違い：

const container = new ParticleContainer();
const sprite = new Sprite(texture);
container.addChild(sprite);

正解：

const container = new ParticleContainer();
const particle = new Particle(texture);
container.addParticle(particle);

ParticleContainer は Sprite の子を受け入れません。addChild はエラーをスローします。パーティクルは Particle インスタンス（または IParticle を実装する任意のオブジェクト）である必要があり、addParticle を経由して追加されます。これは v7 からの完全なやり直しです。v7 では ParticleContainer は Sprite の子を受け入れました。

[HIGH] ParticleContainer で boundsArea を設定しない

間違い：

const container = new ParticleContainer();
// 境界は常に (0, 0, 0, 0) — カリングとヒットテストが失敗する

正解：

const container = new ParticleContainer({
  boundsArea: new Rectangle(0, 0, 800, 600),
});

ParticleContainer はパフォーマンスのためデフォルトで空の境界 (0, 0, 0, 0) を返します。boundsArea がないと、カリングが有効な場合にコンテナは見えないものとしてカリングされ、containsPoint は常にミスします。パーティクルが占める領域に boundsArea を設定します。

[HIGH] children の代わりに particleChildren を使用しない

間違い：

container.addParticle(new Particle(texture));
console.log(container.children.length); // 0

正解：

container.addParticle(new Particle(texture));
console.log(container.particleChildren.length); // 1

パーティクルは children 配列ではなく particleChildren 配列に格納されます。標準の Container.children 配列は ParticleContainer では空です。すべてのパーティクル列挙、カウント、操作は particleChildren と *Particle メソッドを使用する必要があります。

[MEDIUM] ParticleContainer を通常のコンテナとして使用しない

ParticleContainer はパーティクルを含みます。ディスプレイオブジェクトではありません。パーティクルシステムを背景スプライトまたは UI オーバーレイとグループ化する必要がある場合は、ParticleContainer 自体をプレーンな Container でラップします。

const world = new Container();
world.addChild(backgroundSprite, particleContainer, uiLayer);

API リファレンス

• ParticleContainer
• ParticleContainerOptions
• Particle
• ParticleOptions
• IParticle
• ParticleProperties