pixijs-scene-sprite

PixiJS には異なる描画タスク用の 3 つのスプライトクラスがあります。Sprite は標準的な画像描画の葉ノード、NineSliceSprite はコーナーアートを保持する resizable UI パネルのバリアント、TilingSprite はテクスチャを領域全体に繰り返します。AnimatedSprite は Sprite のサブクラスで、フレームベースのアニメーション用にテクスチャフレームをサイクルさせます。

pixijs-scene-core-concepts に関する知識があることを前提としています。すべてのスプライトクラスは葉ノードであり、子要素を持つことはできません。複数のスプライトをグループ化するには、Container でラップしてください。

クイックスタート

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

const sprite = new Sprite({
  texture,
  anchor: 0.5,
  tint: 0xff8888,
});
sprite.x = app.screen.width / 2;
sprite.y = app.screen.height / 2;

app.stage.addChild(sprite);

位置はコンストラクタの後に設定されます。これは app.screen.width / 2 がライブレンダラーサイズに依存するためです。リテラル位置は x/y 経由（Container から継承）でオプションオブジェクトに直接指定できます。

関連スキル: pixijs-scene-core-concepts（葉、変換）、pixijs-assets（テクスチャ読み込み）、pixijs-scene-particle-container（数千のスプライト）、pixijs-performance（スプライトシート、バッチング）。

バリアント

バリアント	使用場面	トレードオフ	リファレンス
Sprite	単一テクスチャを位置に描画	固定サイズ = テクスチャサイズ	references/sprite.md
AnimatedSprite	テクスチャ配列またはスプライトシートからフレームアニメーション	プリレンダフレームのみ、tweening は不可	references/animated-sprite.md
NineSliceSprite	Resizable UI パネル、ボタン、ダイアログフレーム	ボーダー幅は固定、中央は拡大	references/nineslice-sprite.md
TilingSprite	スクロール背景、パララックス、繰り返しパターン	単一テクスチャ繰り返し、tilePosition でスクロール	references/tiling-sprite.md

AnimatedSprite は Sprite のサブクラスであり、すべての Sprite プロパティ（anchor、tint、position）が適用されます。

各バリアントのコンストラクタオプションは、それぞれのサブリファレンスファイル（references/{variant}.md）に記載されています。すべてのバリアントは Container オプション（position、scale、tint、label、filters、zIndex など）も受け付けます — skills/pixijs-scene-core-concepts/references/constructor-options.md を参照してください。

何をどんな時に使うか

• 「単一の画像を位置に描画したい」 → Sprite。2D ゲームとアプリコンテンツの 90% のデフォルト選択。
• 「キャラクターを一連のフレームでアニメーションさせたい」 → AnimatedSprite。Assets 経由でスプライトシートを読み込み、sheet.animations['walk'] を渡してください。references/animated-sprite.md を参照。
• 「UI ボタン/パネルをボーダーを伸ばさずに resizable にしたい」 → NineSliceSprite。ボーダー幅を設定してから width/height を設定してください。references/nineslice-sprite.md を参照。
• 「スクロール繰り返し背景が欲しい」 → TilingSprite。tilePosition をアニメーションさせてスクロールしてください。references/tiling-sprite.md を参照。
• 「数千の同一スプライトが欲しい」 → 通常のスプライトではなく、ParticleContainer と Particle インスタンスを使用してください（pixijs-scene-particle-container を参照）。
• 「シェイプまたはパスを描画したい」 → スプライトではなく Graphics を使用してください（pixijs-scene-graphics を参照）。

クイックコンセプト

Anchor vs pivot

Sprite.anchor は normalized [0, 1] で、テクスチャ描画のオリジンのみをシフトします。位置オフセットはありません。Container.pivot はピクセル空間で、変換オリジンと視覚的位置の両方をシフトします。スプライトをセンタリングする場合は、常に anchor.set(0.5) を使用してください。

作成前のロード

Sprite.from(id) は Assets キャッシュのみを読み込みます。フェッチはしません。常に最初に await Assets.load(...) を実行するか、返された Texture を new Sprite(texture) に直接渡してください。

ダイナミックテクスチャ

テクスチャが読み込まれた後、その frame を変更するか、ソースをスワップしても、スプライトに自動的に通知されません。一度 texture.dynamic = true を設定するか、変更後に sprite['onViewUpdate']() を手動で呼び出してください。

よくある間違い

[HIGH] Texture.from(url) を使用して読み込む

間違い:

const texture = Texture.from("https://example.com/image.png");

正しい:

const texture = await Assets.load("https://example.com/image.png");

Texture.from() は v8 ではキャッシュのみを読み込みます。最初に Assets.load() を使用してください。その戻り値がテクスチャです。

[HIGH] anchor と pivot を混同する

間違い:

sprite.pivot.set(sprite.width / 2, sprite.height / 2);

正しい:

sprite.anchor.set(0.5);

anchor は描画オリジンのみをシフトします。pivot は変換オリジンと視覚的位置の両方をシフトし、スプライトが予期せず移動します。

[HIGH] 古い NineSlicePlane 名

NineSlicePlane は v8 で NineSliceSprite に改名され、オプションオブジェクトコンストラクタに切り替わりました: new NineSliceSprite({ texture, leftWidth, topHeight, rightWidth, bottomHeight })。

[MEDIUM] スプライトに子要素を追加する

Sprite、NineSliceSprite、TilingSprite はすべて allowChildren = false を設定します。スプライトを他のコンテンツとグループ化するには Container でラップしてください。

API リファレンス

• Sprite
• SpriteOptions
• AnimatedSprite
• NineSliceSprite
• TilingSprite
• Texture