pixijs-scene-sprite

PixiJS には、描画タスクに応じて使い分ける 3 つのスプライトクラスがあります。Sprite は画像を描画する標準のリーフノードです。NineSliceSprite は、角のアートを保ったままサイズを変更できる UI パネル用のバリエーションです。TilingSprite は、領域全体にテクスチャを繰り返し表示します。Sprite のサブクラスである AnimatedSprite は、フレームベースのアニメーション用にテクスチャフレームを順に切り替えます。

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 は実行中のレンダラーのサイズに依存するため、位置はコンストラクターの呼び出し後に設定します。固定の位置は、Container から継承した x／y を使って、オプションオブジェクトに直接指定できます。

関連スキル： pixijs-scene-core-concepts（リーフノード、変換）、pixijs-assets（テクスチャの読み込み）、pixijs-scene-particle-container（数千個のスプライト）、pixijs-performance（スプライトシート、バッチ処理）。

バリエーション

バリエーション	使用する場面	トレードオフ	リファレンス
Sprite	単一のテクスチャを指定位置に描画する	サイズは固定（テクスチャのサイズと同じ）	references/sprite.md
AnimatedSprite	テクスチャ配列またはスプライトシートを使ったフレームベースのアニメーション	事前にレンダリングされたフレームのみ。トゥイーンには非対応	references/animated-sprite.md
NineSliceSprite	サイズ変更可能な UI パネル、ボタン、ダイアログのフレーム	枠線の幅は固定で、中央部分が伸縮する	references/nineslice-sprite.md
TilingSprite	スクロールする背景、パララックス、繰り返しパターン	単一のテクスチャを繰り返し表示し、tilePosition でスクロールする	references/tiling-sprite.md

AnimatedSprite は Sprite のサブクラスです。Sprite のすべてのプロパティ（アンカー、色調、位置）が適用されます。

各バリエーションのコンストラクターオプションは、個別のリファレンスファイル（references/{variant}.md）に記載されています。すべてのバリエーションで Container のオプション（position、scale、tint、label、filters、zIndex など）も使用できます。詳しくは skills/pixijs-scene-core-concepts/references/constructor-options.md を参照してください。

使い分け

• 「画像を 1 枚、指定した位置に描画したい」 → Sprite。2D ゲームやアプリのコンテンツの 90％ では、まずこれを選びます。
• 「キャラクターを一連のフレームでアニメーションさせたい」 → AnimatedSprite。Assets でスプライトシートを読み込み、sheet.animations['walk'] を渡します。詳しくは references/animated-sprite.md を参照してください。
• 「枠線を伸ばさずにサイズ変更できる UI ボタン／パネルがほしい」 → NineSliceSprite。枠線の幅を設定してから、width／height を設定します。詳しくは references/nineslice-sprite.md を参照してください。
• 「繰り返し表示される背景をスクロールさせたい」 → TilingSprite。tilePosition をアニメーションさせてスクロールします。詳しくは references/tiling-sprite.md を参照してください。
• 「同じスプライトを数千個表示したい」 → 通常のスプライトではなく、Particle インスタンスと ParticleContainer を使います（pixijs-scene-particle-container を参照）。
• 「図形やパスを描画したい」 → スプライトではなく、Graphics を使います（pixijs-scene-graphics を参照）。

基本概念

アンカーとピボット

Sprite.anchor は [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");

v8 では Texture.from() はキャッシュを参照するだけです。先に Assets.load() を使ってください。その戻り値がテクスチャです。

[HIGH] アンカーとピボットを混同する

誤り：

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

正しい方法：

sprite.anchor.set(0.5);

anchor は描画原点のみを移動します。pivot は変換原点と見た目の位置の両方を移動するため、スプライトが意図せず動きます。

[HIGH] 古い NineSlicePlane という名前

v8 で NineSlicePlane は NineSliceSprite に改名され、オプションオブジェクトを使うコンストラクターに変更されました：new NineSliceSprite({ texture, leftWidth, topHeight, rightWidth, bottomHeight })。

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

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

API リファレンス

• スプライト
• SpriteOptions
• AnimatedSprite
• NineSliceSprite
• TilingSprite
• テクスチャ