mcpField
G
game-object-components

game-object-components

github.com/phaserjs開発40.6k816 回インストール10 週間前に更新
リポジトリ

game-object-components について

ゲームオブジェクトの共通動作を設定する開発者向けの Phaser 4 リファレンスです。コンポーネントのミックスイン方式と、描画、変換、テクスチャなどの API をまとめています。

主な機能

  1. 01アルファ値とブレンドモードの設定
  2. 02深度、反転、原点の調整
  3. 03境界の取得とサイズ制御
  4. 04テクスチャ、クロップ、色調の設定
  5. 05スクロール係数と表示状態の制御

活用シーン

  1. 01ゲームオブジェクトの描画順序の変更
  2. 02HUD のカメラ固定や視差表現
  3. 03テクスチャのクロップと色調変更

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/phaserjs/phaser --skill game-object-components

インストール後、Claude Code で/game-object-componentsを入力して読み込まれたか確認します。

同梱ファイルreferences/REFERENCE.md

詳細

Phaser 4 -- ゲームオブジェクトコンポーネントリファレンス

すべてのゲームオブジェクトに共通の振る舞いを提供するコンポーネントミックスイン: Alpha、BlendMode、Depth、Flip、GetBounds、Lighting、Mask、Origin、ScrollFactor、Size、Texture、TextureCrop、Tint、Transform、Visible、PathFollower、RenderNodes、RenderSteps、Filters、FilterList。

クイックスタート

// Every Game Object gets its component methods via mixins.
// Just call them directly on any game object:
const sprite = this.add.sprite(400, 300, 'hero');

sprite.setAlpha(0.5);                          // Alpha
sprite.setBlendMode(Phaser.BlendModes.ADD);    // BlendMode
sprite.setDepth(10);                           // Depth
sprite.setFlip(true, false);                   // Flip
sprite.setOrigin(0, 0);                        // Origin
sprite.setScrollFactor(0);                     // ScrollFactor (HUD)
sprite.setDisplaySize(64, 64);                 // Size
sprite.setTexture('hero', 'walk-1');           // Texture
sprite.setTint(0xff0000);                      // Tint
sprite.setPosition(100, 200);                  // Transform
sprite.setVisible(false);                      // Visible
sprite.setScale(2);                            // Transform
sprite.setAngle(45);                           // Transform

// Per-corner alpha (WebGL only)
sprite.setAlpha(1, 0.5, 0.5, 1);

// Crop a texture region
sprite.setCrop(0, 0, 32, 32);

// Enable WebGL filters (post-processing)
sprite.enableFilters();
sprite.filters.internal.addBlur(1, 2, 2, 1);

// Lighting (WebGL only, v4 feature)
sprite.setLighting(true);

基本概念

ミックスインシステム

Phaser は Phaser.Class と Mixins 配列を使用して、再利用可能なコンポーネントオブジェクトからゲームオブジェクトを構成します。各コンポーネントはプレーンな JS オブジェクトであり、そのプロパティとメソッドはクラスのプロトタイプにコピーされます。これはプロトタイプ継承ではありません -- クラス定義時のプロパティのコピーです。

// How Phaser defines Sprite internally:
var Sprite = new Class({
    Extends: GameObject,
    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
    ],
    initialize: function Sprite (scene, x, y, texture, frame) { /* ... */ }
});
重要なルール
  1. コンポーネントはインスタンスごとではなく、クラス作成時にミックスインされます。
  2. ほとんどのセッターメソッドはチェーン用に this を返します: sprite.setAlpha(0.5).setDepth(10).setPosition(100, 200)。
  3. 多くのプロパティは内部的にゲッター/セッターを使用しています (例: alpha、depth、visible、scale、rotation)。alpha = 0 または scale = 0 を設定するとレンダーフラグがクリアされ、レンダリングがスキップされます。
  4. renderFlags はビットマスクです: ビット 0 = visible、ビット 1 = alpha、ビット 2 = scale、ビット 3 = texture。オブジェクトがレンダリングされるにはすべてのビットが設定されている必要があります。
  5. Alpha と AlphaSingle: Alpha はコーナーごとのアルファ (WebGL) をサポートしますが、AlphaSingle は単一のグローバルアルファのみをサポートします。コンテナは AlphaSingle を使用します。
  6. Texture と TextureCrop: TextureCrop は Texture を拡張し、setCrop() のサポートを追加します。スプライトとイメージは TextureCrop を使用し、一部のオブジェクトはプレーンな Texture を使用します。
  7. Filters と RenderSteps は v4 専用の WebGL 専用システムで、ポストプロセッシング用です。

コンポーネント完全リファレンス

Alpha

コーナーごとの透明度を提供します。スプライト、イメージ、テキスト、およびほとんどのレンダリング可能なオブジェクトで使用されます。

メンバー型説明
alphanumber (get/set)グローバルアルファ 0〜1。これを設定すると 4 つのコーナーすべてが設定されます。0 に設定するとレンダリングが無効になります。デフォルト: 1
alphaTopLeftnumber (get/set)左上コーナーのアルファ。WebGL 専用。
alphaTopRightnumber (get/set)右上コーナーのアルファ。WebGL 専用。
alphaBottomLeftnumber (get/set)左下コーナーのアルファ。WebGL 専用。
alphaBottomRightnumber (get/set)右下コーナーのアルファ。WebGL 専用。
setAlpha(topLeft?, topRight?, bottomLeft?, bottomRight?)methodアルファを設定します。引数 1 つ = 均一。引数 4 つ = コーナーごと (WebGL)。this を返します。
clearAlpha()methodアルファを 1 にリセットします。this を返します。
AlphaSingle

コーナーごとのサポートがない簡略化されたアルファです。コンテナで使用されます。

メンバー型説明
alphanumber (get/set)アルファ 0〜1。デフォルト: 1
setAlpha(value?)methodアルファを設定します。this を返します。
clearAlpha()methodアルファを 1 にリセットします。this を返します。
BlendMode

レンダリング時にピクセルがどのように合成されるかを制御します。

メンバー型説明
blendModenumber/string (get/set)現在のブレンドモード。Phaser.BlendModes 定数、文字列、または整数を受け付けます。
setBlendMode(value)methodブレンドモードを設定します。this を返します。

WebGL ブレンドモード: NORMAL、ADD、MULTIPLY、SCREEN、ERASE。Canvas は追加のブラウザー依存モードをサポートします。

Depth

レンダリング順序 (z-index) を制御します。depth が高いほど上に描画されます。

メンバー型説明
depthnumber (get/set)depth 値。これを設定すると深度ソートがキューに追加されます。デフォルト: 0
setDepth(value)methoddepth を設定します。this を返します。
setToTop()method表示リストの一番上に移動します (depth は変更されません)。this を返します。
setToBack()method表示リストの一番下に移動します。this を返します。
setAbove(gameObject)method表示リスト内で別のゲームオブジェクトの上に移動します。this を返します。
setBelow(gameObject)method表示リスト内で別のゲームオブジェクトの下に移動します。this を返します。
Flip

物理ボディに影響を与えずに視覚的にミラーリングします。

メンバー型説明
flipXboolean水平反転の状態。デフォルト: false
flipYboolean垂直反転の状態。デフォルト: false
setFlipX(value)method水平反転を設定します。this を返します。
setFlipY(value)method垂直反転を設定します。this を返します。
setFlip(x, y)method両方の反転状態を設定します。this を返します。
toggleFlipX()method水平反転を切り替えます。this を返します。
toggleFlipY()method垂直反転を切り替えます。this を返します。
resetFlip()method両方を false にリセットします。this を返します。
GetBounds

原点に関係なく位置と境界矩形を計算します。

メンバー型説明
getCenter(output?, includeParent?)method中心座標。Vector2Like を返します。
getTopLeft(output?, includeParent?)method左上座標。Vector2Like を返します。
getTopCenter(output?, includeParent?)method上中央座標。Vector2Like を返します。
getTopRight(output?, includeParent?)method右上座標。Vector2Like を返します。
getLeftCenter(output?, includeParent?)method左中央座標。Vector2Like を返します。
getRightCenter(output?, includeParent?)method右中央座標。Vector2Like を返します。
getBottomLeft(output?, includeParent?)method左下座標。Vector2Like を返します。
getBottomCenter(output?, includeParent?)method下中央座標。Vector2Like を返します。
getBottomRight(output?, includeParent?)method右下座標。Vector2Like を返します。
getBounds(output?)method完全な境界矩形。Rectangle を返します。

親 Container のトランスフォームを考慮するには includeParent = true を設定します。

Lighting (v4, WebGL のみ)

Phaser 4 のライティングシステムによるライトベースのレンダリングを有効にします。

メンバー型説明
lightingbooleanライティングを使用するかどうか。デフォルト: false
selfShadowobject{ enabled, penumbra, diffuseFlatThreshold }。セルフシャドウの設定。
setLighting(enable)methodライティングを有効/無効にします。this を返します。
setSelfShadow(enabled?, penumbra?, diffuseFlatThreshold?)methodセルフシャドウを設定します。ゲーム設定のデフォルトを使用するには enabled に null を渡します。this を返します。
Mask (v4 では Canvas のみ)

Canvas レンダラー用のジオメトリマスクです。WebGL では代わりに Filters.addMask() を使用してください。

メンバー型説明
maskGeometryMask現在のマスク、または null。
setMask(mask)methodGeometryMask を適用します。Canvas のみ。WebGL では警告をログに出力します。this を返します。
clearMask(destroyMask?)methodマスクを削除します。true を渡すとマスクも破棄します。this を返します。
createGeometryMask(graphics?)methodGraphics/Shape オブジェクトから GeometryMask を作成します。GeometryMask を返します。
Origin

位置、回転、スケールの基準点を制御します。0~1 に正規化されています。

メンバー型説明
originXnumber水平方向の原点。デフォルト: 0.5 (中央)
originYnumber垂直方向の原点。デフォルト: 0.5 (中央)
displayOriginXnumber (get/set)ピクセル単位の原点。設定すると originX が再計算されます。
displayOriginYnumber (get/set)ピクセル単位の原点。設定すると originY が再計算されます。
setOrigin(x?, y?)method原点 (正規化) を設定します。y のデフォルトは x です。デフォルト: 0.5。this を返します。
setOriginFromFrame()methodテクスチャ Frame のピボットから原点を設定します。this を返します。
setDisplayOrigin(x?, y?)methodピクセル単位で原点を設定します。this を返します。
updateDisplayOrigin()method表示原点のキャッシュを再計算します。this を返します。
ScrollFactor

カメラのスクロールがオブジェクトの描画位置にどのように影響するかを制御します。

メンバー型説明
scrollFactorXnumber水平方向のスクロール係数。デフォルト: 1
scrollFactorYnumber垂直方向のスクロール係数。デフォルト: 1
setScrollFactor(x, y?)methodスクロール係数を設定します。y のデフォルトは x です。this を返します。

主な値: 0 = カメラに固定 (HUD 要素)、1 = カメラとともに移動、0.5 = 半分の速度で視差移動。

Size

ネイティブサイズと表示サイズを管理します。

メンバー型説明
widthnumberネイティブ (スケール前) の幅。
heightnumberネイティブ (スケール前) の高さ。
displayWidthnumber (get/set)スケール後の幅。設定すると scaleX が調整されます。
displayHeightnumber (get/set)スケール後の高さ。設定すると scaleY が調整されます。
setSize(width, height)methodネイティブサイズを設定します。描画サイズには影響しません。this を返します。
setDisplaySize(width, height)method描画サイズを設定します (スケールを調整)。this を返します。
setSizeToFrame(frame?)methodテクスチャの Frame からサイズを設定します。this を返します。
Texture

描画に使用するテクスチャとフレームを取得および設定します。

メンバー型説明
texturePhaser.Textures.Texture現在の Texture。
framePhaser.Textures.Frame現在の Frame。
setTexture(key, frame?, updateSize?, updateOrigin?)methodキーでテクスチャを設定します。this を返します。
setFrame(frame, updateSize?, updateOrigin?)method名前、インデックス、または Frame インスタンスでフレームを設定します。デフォルトでサイズと原点を更新します。this を返します。
TextureCrop

クロッピングをサポートするよう Texture を拡張したものです。Sprite と Image で使用されます。

メンバー型説明
texturePhaser.Textures.Texture現在の Texture。
framePhaser.Textures.Frame現在の Frame。
isCroppedbooleanクロッピングが有効かどうか。
setTexture(key, frame?)methodキーでテクスチャを設定します。this を返します。
setFrame(frame, updateSize?, updateOrigin?)methodフレームを設定します。クロップされている場合はクロップ UV も更新します。this を返します。
setCrop(x?, y?, width?, height?)methodクロップ矩形を設定します。引数を渡さないとクリアされます。最初の引数として Rectangle を受け付けます。this を返します。
Tint (WebGL のみ)

頂点ごとのコーナーカラーによってテクスチャにカラーティントを適用します。

メンバー型説明
tintnumber (get/set)均一なティントカラー (tintTopLeft を読み取ります)。デフォルト: 0xffffff
tintTopLeftnumber左上の頂点ティント。デフォルト: 0xffffff
tintTopRightnumber右上の頂点ティント。デフォルト: 0xffffff
tintBottomLeftnumber左下の頂点ティント。デフォルト: 0xffffff
tintBottomRightnumber右下の頂点ティント。デフォルト: 0xffffff
tintModenumberティントのブレンドモード。デフォルト: Phaser.TintModes.MULTIPLY
isTintedboolean (readonly)いずれかのティントまたはモードが設定されている場合に true。
setTint(topLeft?, topRight?, bottomLeft?, bottomRight?)methodティントカラーを設定します。引数が 1 つの場合は均一になります。this を返します。
setTintMode(mode)methodティントモードを設定します (v4)。モード: MULTIPLY、FILL、ADD、SCREEN、OVERLAY、HARD_LIGHT。this を返します。
clearTint()method白 + MULTIPLY にリセットします。this を返します。

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

Transform

位置、スケール、回転、および座標変換です。

メンバー型説明
xnumberX 位置。デフォルト: 0
ynumberY 位置。デフォルト: 0
znumberZ 位置(レンダリング順序ではありません。depth を使用してください)。デフォルト: 0
wnumberW 位置。デフォルト: 0
scalenumber (get/set)均一スケール。取得時は scaleX と scaleY の平均を返します。
scaleXnumber (get/set)水平スケール。デフォルト: 1
scaleYnumber (get/set)垂直スケール。デフォルト: 1
anglenumber (get/set)度数法での回転(時計回り、0 = 右)。
rotationnumber (get/set)ラジアンでの回転。
setPosition(x?, y?, z?, w?)method位置を設定します。y のデフォルトは x です。this を返します。
copyPosition(source)methodVector ライクなオブジェクトから x/y/z/w をコピーします。this を返します。
setRandomPosition(x?, y?, width?, height?)method領域内で位置をランダム化します。this を返します。
setRotation(radians?)methodラジアンで回転を設定します。this を返します。
setAngle(degrees?)method度数法で回転を設定します。this を返します。
setScale(x?, y?)methodスケールを設定します。y のデフォルトは x です。this を返します。
setX(value?)methodx を設定します。this を返します。
setY(value?)methody を設定します。this を返します。
setZ(value?)methodz を設定します。this を返します。
setW(value?)methodw を設定します。this を返します。
getLocalTransformMatrix(tempMatrix?)methodローカル変換行列を取得します。TransformMatrix を返します。
getWorldTransformMatrix(tempMatrix?, parentMatrix?)method親 Container を含むワールド変換を取得します。TransformMatrix を返します。
getLocalPoint(x, y, point?, camera?)methodワールド座標をローカル空間に変換します。Vector2 を返します。
getWorldPoint(point?, tempMatrix?, parentMatrix?)method親コンテナを考慮したワールド位置を取得します。Vector2 を返します。
getParentRotation()methodすべての親コンテナの回転の合計をラジアンで返します。
Visible

Game Object をレンダリングするかどうかを制御します。非表示のオブジェクトでも更新ロジックは実行されます。

メンバー型説明
visibleboolean (get/set)表示状態。デフォルト: true
setVisible(value)method表示状態を設定します。this を返します。
PathFollower

内部トゥイーンを使用して Phaser.Curves.Path の追従を管理します。

メンバー型説明
pathPhaser.Curves.Path追従している Path。
rotateToPathbooleanパスの方向を向くように自動回転します。デフォルト: false
pathRotationOffsetnumberrotateToPath が true の場合の度数法での回転オフセット。
pathOffsetVector2パス座標からの位置オフセット。
pathVectorVector2パス上の現在のポイント。
pathDeltaVector2前回の更新以降に移動した距離。
pathTweenTweenパスの移動を駆動するトゥイーン。
setPath(path, config?)method新しい Path を設定します。this を返します。
setRotateToPath(value, offset?)method自動回転を有効にします。this を返します。
isFollowing()methodアクティブに追従している場合は true を返します。
startFollow(config?, startAt?)method追従を開始します。config には duration(数値)または PathConfig を指定できます。this を返します。
pauseFollow()method移動を一時停止します。this を返します。
resumeFollow()method移動を再開します。this を返します。
stopFollow()method追従を停止します。this を返します。
RenderNodes、RenderSteps、Filters、FilterList(v4、WebGL のみ)

RenderNodes、RenderSteps、FilterList の詳細については、filters-and-postfx スキルおよびreferences/REFERENCE.mdを参照してください。

重要なポイント: filters にアクセスする前に、ゲームオブジェクトで enableFilters() を呼び出してください。カメラはデフォルトでフィルターを持っています。オブジェクトローカルのエフェクトには filters.internal を、スクリーンスペースのエフェクトには filters.external を使用してください。

コンポーネントとゲームオブジェクトの完全な対応表については、references/REFERENCE.mdを参照してください。

ファクトリ登録とディスプレイリスト

カスタムゲームオブジェクトのファクトリ登録

カスタムゲームオブジェクトをファクトリに登録すると、this.add.myObject() で作成できるようになります:

class LaserBeam extends Phaser.GameObjects.Sprite {
    constructor(scene, x, y) {
        super(scene, x, y, 'laser');
    }
}

Phaser.GameObjects.GameObjectFactory.register('laserBeam', function (x, y) {
    const beam = new LaserBeam(this.scene, x, y);
    this.displayList.add(beam);
    return beam;
});

// Now usable in any scene:
const laser = this.add.laserBeam(100, 200);
ファクトリ(this.add)とクリエイター(this.make)

this.add はオブジェクトを作成し、ディスプレイリストに追加します。this.make はオブジェクトを作成しますが追加はしません -- 画面外での準備や遅延表示に便利です。

// Added to display list immediately
const visible = this.add.sprite(100, 100, 'hero');

// Created but NOT on the display list
const offscreen = this.make.sprite({ key: 'hero', x: 100, y: 100 });

// Add it later when ready
this.add.existing(offscreen);
柔軟な設定のための GetAdvancedValue

GetAdvancedValue は、設定オブジェクトから静的値、ランダム配列、randInt/Float の範囲、コールバックを解決します:

// Static value
{ speed: 100 }

// Random from array
{ speed: [100, 200, 300] }

// Random integer range
{ speed: { randInt: [50, 150] } }

// Random float range
{ speed: { randFloat: [0.5, 1.5] } }

// Callback
{ speed: function () { return Math.random() * 100; } }
ディスプレイリストの順序

後から追加されたオブジェクトは、先に追加されたオブジェクトの上に描画されます。順序を制御するには:

// Depth-based ordering (higher = on top, triggers sort)
sprite.setDepth(10);

// Display list position (no depth change)
sprite.setToTop();
sprite.setToBack();
sprite.setAbove(otherSprite);
sprite.setBelow(otherSprite);

depth とディスプレイリストの位置の両方を使用した場合、次のソート処理後に depth が優先されます。

注意点

  1. alpha=0 はレンダリングを完全に防ぎます: alpha を 0 に設定すると、レンダリングフラグのビットがクリアされます。オブジェクトは単に透明になるのではなく、まったく描画されません。同じことが scale = 0 と visible = false にも当てはまります。

  2. 反転は物理に影響しません: 反転はレンダリングのみです。物理ボディは変化しません。衝突コードではこれを考慮してください。

  3. ScrollFactor と物理: 物理衝突はワールド位置を使用します。1 以外のスクロールファクターは、テクスチャが描画される位置をオフセットしますが、ボディの位置は変わりません。スクロールファクターが 0 の HUD 要素には、物理ボディを追加しないでください。

  4. depth とディスプレイリストの順序: setDepth() はソートをキューに入れ、主要な z 順序付けのツールです。setToTop()、setAbove() などは、depth を変更せずにディスプレイリストを並べ替えます。両方を混在させた場合、次のソート後に depth が優先されます。

  5. Mask コンポーネントは v4 では Canvas 専用です: WebGL のマスキングには、enableFilters() を使用してから filters.internal.addMask() を使用してください。setMask() メソッドは WebGL で警告をログに出力します。

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

  7. v4 のティントモード: ティントモードはティントカラーとは別になりました。使用可能なモード: MULTIPLY(デフォルト)、FILL、ADD、SCREEN、OVERLAY、HARD_LIGHT。

  8. displayWidth/displayHeight はスケールを調整します: displayWidth または displayHeight を設定すると、scaleX/scaleY が変更されます。width/height は変更されません。

  9. setSize と setDisplaySize: setSize() は内部寸法(フレーム、物理に使用)を変更します。setDisplaySize() はスケールを調整してレンダリングサイズを変更します。

  10. 原点のデフォルトは 0.5 です: すべてのゲームオブジェクトはデフォルトで中央原点です。左上の配置には setOrigin(0, 0) を使用してください。Text と BitmapText は代わりにデフォルトで左上の配置になります。

  11. Transform.z は depth ではありません: Transform の z プロパティはカスタム用途のためのものです。レンダリング順序は depth(Depth コンポーネント)またはディスプレイリストの位置で制御されます。

  12. フィルターは高コストです: アクティブなフィルターを持つ各オブジェクトには、追加の描画呼び出しが必要です。一時的に無効にするには renderFilters = false を使用してください。内部フィルターは外部フィルターよりも低コストです。

ソースファイルマップ

ファイル説明
src/gameobjects/components/index.jsコンポーネントレジストリ。すべてのコンポーネントをエクスポートします
src/gameobjects/components/Alpha.jsコーナーごとのアルファミックスイン
src/gameobjects/components/AlphaSingle.js単一値アルファミックスイン
src/gameobjects/components/BlendMode.jsブレンドモードミックスイン
src/gameobjects/components/Depth.js深度/z オーダーミックスイン
src/gameobjects/components/Flip.js視覚的フリップミックスイン
src/gameobjects/components/GetBounds.js境界計算ミックスイン
src/gameobjects/components/Lighting.jsv4 ライティングミックスイン
src/gameobjects/components/Mask.jsCanvas ジオメトリマスクミックスイン
src/gameobjects/components/Origin.js原点/アンカーミックスイン
src/gameobjects/components/ScrollFactor.jsカメラスクロールファクターミックスイン
src/gameobjects/components/Size.js寸法ミックスイン
src/gameobjects/components/Texture.jsテクスチャ/フレーム割り当てミックスイン
src/gameobjects/components/TextureCrop.jsクロップをサポートするテクスチャミックスイン
src/gameobjects/components/Tint.js頂点カラーティントミックスイン
src/gameobjects/components/Transform.js位置/スケール/回転ミックスイン
src/gameobjects/components/Visible.js可視性ミックスイン
src/gameobjects/components/PathFollower.jsパス追従ミックスイン
src/gameobjects/components/RenderNodes.jsv4 WebGL レンダーノードミックスイン
src/gameobjects/components/RenderSteps.jsv4 WebGL レンダーステップミックスイン
src/gameobjects/components/Filters.jsv4 WebGL フィルターシステムミックスイン
src/gameobjects/components/FilterList.jsv4 フィルターリストクラス(エフェクトの追加)
src/gameobjects/components/TransformMatrix.js2D 変換行列ユーティリティ

関連スキル: sprites-and-images.md、custom-game-objects.md

コメント