sprites-and-images

スプライトと画像

Phaser 4 で Sprite および Image ゲームオブジェクトを作成・操作する方法 -- ファクトリメソッド、テクスチャ/フレームの選択、コンポーネントミックスインシステム、および一般的なビジュアル操作(位置、スケール、回転、ティント、反転、アルファ、原点、深度)。

主要なソースパス: src/gameobjects/sprite/、src/gameobjects/image/、src/gameobjects/GameObject.js、src/gameobjects/components/ 関連スキル: ../loading-assets/SKILL.md、../animations/SKILL.md、../physics-arcade/SKILL.md、../game-object-components/SKILL.md

クイックスタート

// In a Scene's create() method:

// Static image (no animation support, slightly cheaper)
const bg = this.add.image(400, 300, 'background');

// Sprite (supports animations)
const player = this.add.sprite(100, 200, 'player', 'idle-0');

// Common operations -- all methods return `this` for chaining
player.setPosition(200, 300);
player.setScale(2);
player.setAngle(45);
player.setTint(0xff0000);
player.setAlpha(0.8);
player.setOrigin(0, 1);       // bottom-left
player.setDepth(10);
player.setFlip(true, false);  // flip horizontally
player.setVisible(false);

// Chained
this.add.sprite(100, 100, 'coin')
    .setScale(0.5)
    .setTint(0xffff00)
    .play('spin');

コアコンセプト

Sprite と Image

どちらも GameObject を継承し、同じコンポーネントミックスインのセットを共有しています。唯一の違いは、Sprite には AnimationState インスタンス(sprite.anims)とアニメーション用の便利なメソッド(play、stop、chain など)が含まれていることです。

機能	Image	Sprite
静的なテクスチャ表示	はい	はい
ティント、アルファ、反転、スケール、回転	はい	はい
物理ボディ	はい	はい
入力 / ヒットエリア	はい	はい
アニメーション(play、stop、chain)	いいえ	はい
毎フレーム preUpdate が呼ばれる	いいえ	はい(アニメーションを更新)
Scene の updateList に追加される	いいえ	はい

経験則: フレームごとのアニメーションが不要なものには Image を使用します。毎フレームの preUpdate コストを回避でき、API サーフェスも小さくなります。Animation コンポーネントが必要な場合にのみ Sprite を使用してください。

コンポーネントミックスインシステム

Phaser は、コンポーネントオブジェクトをプロトタイプにミックスインすることで Game Object クラスを構築します。Sprite と Image の両方が、この同一の Mixins 配列を共有しています(src/gameobjects/sprite/Sprite.js および src/gameobjects/image/Image.js に由来):

Mixins: [
    Components.Alpha,
    Components.BlendMode,
    Components.Depth,
    Components.Flip,
    Components.GetBounds,
    Components.Lighting,
    Components.Mask,
    Components.Origin,
    Components.RenderNodes,
    Components.ScrollFactor,
    Components.Size,
    Components.TextureCrop,
    Components.Tint,
    Components.Transform,
    Components.Visible,
    SpriteRender / ImageRender   // render-specific (differs per class)
]

基底の GameObject クラス自体は以下をミックスインしています:

Mixins: [
    Components.Filters,
    Components.RenderSteps
]

各コンポーネントは、すべてのインスタンスに特定のプロパティとメソッドを追加します。たとえば、Components.Transform は x、y、scale、rotation、setPosition() などを追加します。利用可能なコンポーネントの完全なリストは src/gameobjects/components/index.js にあります。

エージェント向けの重要ポイント: Sprite で setAlpha() のようなメソッドを見かけた場合、それは Sprite クラス自体ではなく Components.Alpha に由来します。そのメソッドのシグネチャと動作に関する信頼できる参照元は、コンポーネントのソースファイルです。

テクスチャとフレーム

Sprite と Image の両方が TextureCrop コンポーネントを使用しており、以下を提供します:

• texture -- Phaser.Textures.Texture インスタンス
• frame -- 現在の Phaser.Textures.Frame インスタンス
• setTexture(key, frame) -- テクスチャ(およびオプションでフレーム)を変更します
• setFrame(frame, updateSize, updateOrigin) -- フレームのみを変更します
• setCrop(x, y, width, height) -- テクスチャの矩形領域をクロップします
• isCropped -- ブール値、setCrop 後にクロップのオン/オフを切り替えます

ファクトリメソッドおよびコンストラクタの texture パラメータは、文字列キー(Texture Manager に登録されたもの)または Phaser.Textures.Texture インスタンスのいずれかを受け付けます。

frame パラメータは、文字列名またはテクスチャのフレームコレクションへの数値インデックスを受け付けます。省略した場合、ベースフレーム(フレーム 0 / '__BASE')が使用されます。

// Change texture at runtime
sprite.setTexture('enemies', 'goblin-walk-1');

// Change only the frame (must belong to current texture)
sprite.setFrame('goblin-walk-2');

// setFrame signature:
// setFrame(frame, updateSize=true, updateOrigin=true)
// Pass false to prevent automatic resize/origin recalculation
sprite.setFrame('small-frame', false, false);

// Crop to show only a 50x50 region starting at (10, 10)
sprite.setCrop(10, 10, 50, 50);
// Reset crop
sprite.setCrop();

一般的なパターン

作成と配置

Transform コンポーネント(src/gameobjects/components/Transform.js):

// Properties (all read/write)
sprite.x           // horizontal position (default: 0)
sprite.y           // vertical position (default: 0)
sprite.z           // z position (does NOT control render order -- use depth)
sprite.w           // w position

// Methods
sprite.setPosition(x, y, z, w)        // y defaults to x if omitted
sprite.setRandomPosition(x, y, w, h)  // random within area; defaults to game size
sprite.copyPosition(source)            // copy from any {x, y} object

Size コンポーネント(src/gameobjects/components/Size.js):

sprite.width            // native (un-scaled) width
sprite.height           // native (un-scaled) height
sprite.displayWidth      // scaled width (read/write -- setting adjusts scaleX)
sprite.displayHeight     // scaled height (read/write -- setting adjusts scaleY)

sprite.setSize(width, height)           // set internal size (not visual)
sprite.setDisplaySize(width, height)    // set visual size (adjusts scale)
sprite.setSizeToFrame(frame)            // reset size to match frame

スケーリングと回転

Transform コンポーネント(続き):

// Scale properties
sprite.scale       // uniform scale (getter returns average of scaleX+scaleY)
sprite.scaleX      // horizontal scale (default: 1)
sprite.scaleY      // vertical scale (default: 1)

// Scale methods
sprite.setScale(x, y)    // y defaults to x if omitted

// Rotation properties
sprite.rotation    // in radians (right-hand clockwise: 0=right, PI/2=down)
sprite.angle       // in degrees (0=right, 90=down, 180/-180=left, -90=up)

// Rotation methods
sprite.setRotation(radians)   // defaults to 0
sprite.setAngle(degrees)      // defaults to 0

ティントとアルファ

Tint コンポーネント(src/gameobjects/components/Tint.js) -- WebGL のみ:

// Properties
sprite.tint             // overall tint (getter returns tintTopLeft)
sprite.tintTopLeft      // default: 0xffffff
sprite.tintTopRight     // default: 0xffffff
sprite.tintBottomLeft   // default: 0xffffff
sprite.tintBottomRight  // default: 0xffffff
sprite.tintMode         // default: Phaser.TintModes.MULTIPLY
sprite.isTinted         // read-only boolean

// Methods
sprite.setTint(topLeft, topRight, bottomLeft, bottomRight)
// If only topLeft given, applies uniformly to all four corners
sprite.setTintMode(mode)   // Phaser.TintModes.MULTIPLY | FILL | ADD | SCREEN | OVERLAY | HARD_LIGHT
sprite.clearTint()         // resets to 0xffffff + MULTIPLY mode

Phaser 4 での変更: setTintFill() は削除されました。代わりに setTint(color).setTintMode(Phaser.TintModes.FILL) を使用してください。

Alpha コンポーネント(src/gameobjects/components/Alpha.js):

// Properties
sprite.alpha             // global alpha 0-1 (default: 1)
sprite.alphaTopLeft      // per-corner alpha (WebGL only)
sprite.alphaTopRight
sprite.alphaBottomLeft
sprite.alphaBottomRight

// Methods
sprite.setAlpha(topLeft, topRight, bottomLeft, bottomRight)
// If only topLeft given, applies uniformly to whole object
sprite.clearAlpha()     // resets to 1 (fully opaque)

alpha を 0 に設定するとレンダーフラグがクリアされ、オブジェクトは描画されません。0 以外の値に戻すと復元されます。

反転

Flip コンポーネント (src/gameobjects/components/Flip.js):

// Properties
sprite.flipX    // boolean (default: false)
sprite.flipY    // boolean (default: false)

// Methods
sprite.setFlipX(value)        // set horizontal flip
sprite.setFlipY(value)        // set vertical flip
sprite.setFlip(x, y)          // set both at once
sprite.toggleFlipX()          // invert current horizontal flip
sprite.toggleFlipY()          // invert current vertical flip
sprite.resetFlip()            // set both to false

反転はレンダリングの切り替えのみです。物理ボディやヒットエリアには影響しません。反転はテクスチャの中央から行われ、scale の値は変更されません。

原点と深度

Origin コンポーネント (src/gameobjects/components/Origin.js):

// Properties (normalized 0-1)
sprite.originX          // default: 0.5 (center)
sprite.originY          // default: 0.5 (center)
sprite.displayOriginX   // pixel value (originX * width)
sprite.displayOriginY   // pixel value (originY * height)

// Methods
sprite.setOrigin(x, y)           // y defaults to x; defaults to 0.5
sprite.setDisplayOrigin(x, y)    // set origin in pixels; y defaults to x
sprite.setOriginFromFrame()      // use Frame pivot if set, else 0.5
sprite.updateDisplayOrigin()     // recalculate pixel origin from normalized

Depth コンポーネント (src/gameobjects/components/Depth.js):

// Properties
sprite.depth    // default: 0 (higher = renders on top)

// Methods
sprite.setDepth(value)
sprite.setToTop()              // move to top of display list (no depth change)
sprite.setToBack()             // move to back of display list (no depth change)
sprite.setAbove(gameObject)    // position above another object in the list
sprite.setBelow(gameObject)    // position below another object in the list

depth を設定すると、Scene 内で深度ソートがキューに追加されます。setToTop/setToBack/setAbove/setBelow メソッドは、depth の値を変更せずに表示リストの位置を変更します。

ゲームオブジェクトの破棄

sprite.destroy();           // removes from display list, update list, and cleans up
sprite.ignoreDestroy = true; // prevent destruction (you manage lifecycle manually)
sprite.isDestroyed           // boolean, true after destroy() has been called

Sprite の場合、destroy() は this.anims.destroy() も呼び出して AnimationState をクリーンアップします。

追加のコンポーネント

Visible (src/gameobjects/components/Visible.js):

sprite.visible              // boolean (default: true)
sprite.setVisible(value)    // invisible objects skip rendering but still update

ScrollFactor (src/gameobjects/components/ScrollFactor.js):

sprite.scrollFactorX        // default: 1 (moves with camera)
sprite.scrollFactorY        // default: 1
sprite.setScrollFactor(x, y)  // 0 = fixed to camera; y defaults to x

BlendMode (src/gameobjects/components/BlendMode.js):

sprite.blendMode            // default: Phaser.BlendModes.NORMAL
sprite.setBlendMode(value)  // Phaser.BlendModes.ADD, MULTIPLY, SCREEN, ERASE, etc.

パフォーマンスに関する注意: ブレンドモードを変更すると WebGL のバッチが分断されます。可能な限りオブジェクトをブレンドモードごとにグループ化してください（例: すべての ADD モードのスプライトをまとめてレンダリングする）。これによりドローコールを最小限に抑えられます。

ファクトリメソッド

this.add.sprite

ソース: src/gameobjects/sprite/SpriteFactory.js

// Signature
this.add.sprite(x, y, texture, frame);

パラメータ	型	必須	説明
x	number	はい	ワールド座標での水平位置
y	number	はい	ワールド座標での垂直位置
texture	string | Phaser.Textures.Texture	はい	テクスチャキーまたは Texture インスタンス
frame	string | number	いいえ	テクスチャ内のフレーム名またはインデックス

戻り値: Phaser.GameObjects.Sprite

内部的には次を実行します: this.displayList.add(new Sprite(this.scene, x, y, texture, frame))

Sprite コンストラクタは次を呼び出します: setTexture -> setPosition -> setSizeToFrame -> setOriginFromFrame -> initRenderNodes。

this.add.image

ソース: src/gameobjects/image/ImageFactory.js

// Signature
this.add.image(x, y, texture, frame);

パラメータ	型	必須	説明
x	number	はい	ワールド座標での水平位置
y	number	はい	ワールド座標での垂直位置
texture	string | Phaser.Textures.Texture	はい	テクスチャキーまたは Texture インスタンス
frame	string | number	いいえ	テクスチャ内のフレーム名またはインデックス

戻り値: Phaser.GameObjects.Image

内部的には次を実行します: this.displayList.add(new Image(this.scene, x, y, texture, frame))

Image コンストラクタは Sprite と同じ初期化シーケンスを呼び出します: setTexture -> setPosition -> setSizeToFrame -> setOriginFromFrame -> initRenderNodes。

特殊なゲームオブジェクト

NineSlice

固定サイズの角と伸縮可能な辺・中央を持つ、スケーラブルな UI パネルです。枠を歪めずにサイズ変更する必要があるボタン、パネル、ダイアログボックスに最適です。

// nineslice(x, y, texture, frame, width, height, leftWidth, rightWidth, topHeight, bottomHeight)
const panel = this.add.nineslice(400, 300, 'panel', null, 300, 200, 20, 20, 20, 20);

// Resize at runtime -- corners stay fixed, edges stretch
panel.setSize(500, 400);

TileSprite

エリアを埋める繰り返しテクスチャです。v4 ではアトラスフレームをサポートし、新しい tileRotation プロパティも備えています。

const bg = this.add.tileSprite(400, 300, 800, 600, 'grass');

// Scroll the tile in update() for parallax backgrounds
bg.tilePositionX += 0.5;
bg.tilePositionY += 0.25;

// v4: rotate the tile pattern
bg.tileRotation = 0.1;

Blitter

多数の静的または半静的なスプライトを対象とした、高性能なバッチレンダリングです。Blitter の子（Bob）は回転、スケール、物理を持ちませんが、個々の Sprite よりも大幅に高速にレンダリングされます。

const blitter = this.add.blitter(0, 0, 'particles');

// Create Bobs (lightweight display objects)
for (let i = 0; i < 1000; i++) {
    const bob = blitter.create(
        Phaser.Math.Between(0, 800),
        Phaser.Math.Between(0, 600),
        'particle_01'   // frame name within the texture
    );
    bob.setAlpha(Math.random());
}

Video

位置、スケール、フィルターをサポートするゲームオブジェクトとしての動画再生です。

// Load in preload:
this.load.video('intro', 'intro.mp4');

// Create in create:
const video = this.add.video(400, 300, 'intro');
video.play();

詳細な設定オプション、API リファレンスの表、ソースファイルのマップについては、リファレンスガイドを参照してください。