actions-and-utilities

Phaser 4 -- アクション & ユーティリティ関数

ゲームオブジェクトの配列に対する一括操作のための Phaser.Actions 名前空間、および Phaser.Utils.Array、Phaser.Utils.Objects、Phaser.Utils.String のヘルパー関数。

関連スキル: ../groups-and-containers/SKILL.md, ../sprites-and-images/SKILL.md

---

クイックスタート

// Create 20 sprites and batch-position them in a grid
const sprites = [];
for (let i = 0; i < 20; i++) {
    sprites.push(this.add.sprite(0, 0, 'gem'));
}

// Arrange into a 5x4 grid
Phaser.Actions.GridAlign(sprites, {
    width: 5,
    height: 4,
    cellWidth: 64,
    cellHeight: 64,
    x: 100,
    y: 100
});

// Fade alpha from 0 to 1 across all sprites
Phaser.Actions.Spread(sprites, 'alpha', 0, 1);

// Offset each sprite's x by 10, with a step of 2 per item
Phaser.Actions.IncX(sprites, 10, 2);

// Works with Groups too
const group = this.add.group({ key: 'star', repeat: 11 });
Phaser.Actions.PlaceOnCircle(group.getChildren(), new Phaser.Geom.Circle(400, 300, 200));

---

コアコンセプト

アクションのパターン

Phaser.Actions のすべてのアクションは同じパターンに従います。

1. 最初の引数は常に配列で、ゲームオブジェクト（または x、y、alpha などの必要なパブリックプロパティを持つ任意のオブジェクト）を指定します。
2. 同じ配列を返すため、チェーンやパススルーが可能です。
3. group.getChildren() を渡すことで グループでも動作します。
4. アクションは状態を保持しません。これらは一度きりの一括操作です。

PropertyValueSet と PropertyValueInc

ほとんどの Set/Inc アクションは、2 つのコア関数に委譲します。

• PropertyValueSet(items, key, value, step, index, direction) -- items[i][key] = value + (i * step) を設定します。
• PropertyValueInc(items, key, value, step, index, direction) -- items[i][key] += value + (i * step) を加算します。

step パラメータは、項目ごとに増分オフセットを追加します。index と direction パラメータは、反復の開始位置と順序を制御します（1 = 前方向、-1 = 後方向）。

ジオメトリベースの配置

PlaceOnCircle、PlaceOnLine、RandomRectangle などのアクションは、ゲームオブジェクトのシェイプではなく、Phaser のジオメトリオブジェクト（Phaser.Geom.Circle、Phaser.Geom.Line など）を受け取ります。Phaser.GameObjects.Circle を使用する場合は、代わりにその .geom プロパティを渡してください。

---

すべてのアクション

プロパティセッター

アクション	シグネチャ	説明
SetX	(items, value, step?, index?, direction?)	x プロパティを設定
SetY	(items, value, step?, index?, direction?)	y プロパティを設定
SetXY	(items, x, y?, stepX?, stepY?, index?, direction?)	x と y の両方を設定。y はデフォルトで x
SetAlpha	(items, value, step?, index?, direction?)	alpha を設定
SetBlendMode	(items, value, index?, direction?)	ブレンドモードを設定
SetDepth	(items, value, step?, index?, direction?)	レンダリング深度を設定
SetHitArea	(items, hitArea?, callback?)	インタラクティブなヒットエリアを設定
SetOrigin	(items, originX, originY?, stepX?, stepY?, index?, direction?)	原点を設定
SetRotation	(items, value, step?, index?, direction?)	回転（ラジアン）を設定
SetScale	(items, scaleX, scaleY?, stepX?, stepY?, index?, direction?)	両方のスケール軸を設定
SetScaleX	(items, value, step?, index?, direction?)	scaleX を設定
SetScaleY	(items, value, step?, index?, direction?)	scaleY を設定
SetScrollFactor	(items, x, y?, stepX?, stepY?, index?, direction?)	スクロールファクターを設定
SetScrollFactorX	(items, value, step?, index?, direction?)	水平スクロールファクターを設定
SetScrollFactorY	(items, value, step?, index?, direction?)	垂直スクロールファクターを設定
SetTint	(items, topLeft, topRight?, bottomLeft?, bottomRight?)	ティントカラーを設定
SetVisible	(items, value, index?, direction?)	可視性を設定
PropertyValueSet	(items, key, value, step?, index?, direction?)	汎用: 任意の名前付きプロパティを設定

プロパティインクリメンター

アクション	シグネチャ	説明
IncX	(items, value, step?, index?, direction?)	x に加算します
IncXY	(items, x, y?, stepX?, stepY?, index?, direction?)	x と y に加算します
IncY	(items, value, step?, index?, direction?)	y に加算します
IncAlpha	(items, value, step?, index?, direction?)	alpha に加算します
Angle	(items, value, step?, index?, direction?)	angle (度) に加算します
Rotate	(items, value, step?, index?, direction?)	rotation (ラジアン) に加算します
ScaleX	(items, value, step?, index?, direction?)	scaleX に加算します
ScaleXY	(items, scaleX, scaleY?, stepX?, stepY?, index?, direction?)	両方のスケール軸に加算します
ScaleY	(items, value, step?, index?, direction?)	scaleY に加算します
PropertyValueInc	(items, key, value, step?, index?, direction?)	汎用: 任意の名前付きプロパティをインクリメントします

ジオメトリ上への配置

アクション	シグネチャ	説明
PlaceOnCircle	(items, circle, startAngle?, endAngle?)	円の周囲に均等に配置します
PlaceOnEllipse	(items, ellipse, startAngle?, endAngle?)	楕円の周囲に均等に配置します
PlaceOnLine	(items, line)	直線に沿って均等に配置します
PlaceOnRectangle	(items, rect, shift?)	長方形の周囲に均等に配置します
PlaceOnTriangle	(items, triangle, stepRate?)	三角形の周囲に均等に配置します
RandomCircle	(items, circle)	円内のランダムな位置に配置します
RandomEllipse	(items, ellipse)	楕円内のランダムな位置に配置します
RandomLine	(items, line)	直線に沿ったランダムな位置に配置します
RandomRectangle	(items, rect)	長方形内のランダムな位置に配置します
RandomTriangle	(items, triangle)	三角形内のランダムな位置に配置します

レイアウトと整列

アクション	シグネチャ	説明
GridAlign	(items, config)	グリッド状に配置します。config: { width, height, cellWidth, cellHeight, position, x, y }
AlignTo	(items, position, offsetX?, offsetY?)	Phaser.Display.Align の定数を使用して、各アイテムを前のアイテムの隣に連鎖的に整列します
FitToRegion	(items, scaleMode?, region?, itemCoverage?)	各 GO を長方形に合わせてスケール/配置します (v4.0.0+)。scaleMode: 0=伸縮、-1=内側にフィット、1=外側をカバー

分布と補間

アクション	シグネチャ	説明
Spread	(items, property, min, max, inc?)	すべてのアイテムにわたってプロパティを min から max まで線形に分布させます
SmoothStep	(items, property, min, max, inc?)	エルミート スムーズステップ補間を使用して分布させます
SmootherStep	(items, property, min, max, inc?)	Ken Perlin の smootherstep を使用して分布させます

回転と移動

アクション	シグネチャ	説明
RotateAround	(items, point, angle)	すべてのアイテムをある点を中心に回転させます (ラジアン)
RotateAroundDistance	(items, point, angle, distance)	ある点を中心に固定距離で回転させます
ShiftPosition	(items, x, y, direction?, output?)	スネーク状: 先頭を x/y に移動し、各アイテムは前のアイテムの位置を引き継ぎます
WrapInRectangle	(items, rect, padding?)	長方形の境界内に収まるように x/y をラップします

クエリと反復

アクション	シグネチャ	説明
GetFirst	(items, compare, index?)	compare オブジェクト内のすべてのプロパティに一致する最初のアイテムを検索します
GetLast	(items, compare, index?)	compare オブジェクト内のすべてのプロパティに一致する最後のアイテムを検索します
Call	(items, callback, context)	各アイテムに対してコールバックを呼び出します
Shuffle	(items)	配列をランダムに並べ替えます (Fisher-Yates)
ToggleVisible	(items)	各アイテムの visible を切り替えます
PlayAnimation	(items, key, ignoreIfPlaying?)	anims コンポーネントを持つすべてのアイテムでアニメーションを再生します

エフェクト (v4.0.0+)

アクション	シグネチャ	説明
AddEffectBloom	(items, config?)	Camera または GO にブルームフィルターエフェクトを追加します。{ parallelFilters, threshold, blur }[] を返します
AddEffectShine	(items, config?)	シャインフィルターエフェクトを追加します
AddMaskShape	(items, config?)	任意のブラー付きで、図形ベースのマスク（円、正方形、長方形、楕円）を適用します

---

配列ユーティリティ

名前空間: Phaser.Utils.Array

関数	シグネチャ	説明
Add	(array, item, limit?, callback?, context?)	まだ存在しない場合にアイテムを追加します。サイズ制限を任意で指定できます
AddAt	(array, item, index?, limit?, callback?, context?)	指定したインデックスにアイテムを挿入します
BringToTop	(array, item)	アイテムを配列の末尾に移動します
CountAllMatching	(array, property, value, startIndex?, endIndex?)	プロパティが値と等しいアイテムを数えます
Each	(array, callback, context, ...args)	コールバックで反復処理します。アイテムと追加引数を渡します
EachInRange	(array, callback, context, startIndex, endIndex, ...args)	範囲のスライスをコールバックで反復処理します
FindClosestInSorted	(value, array, key?)	ソート済み配列で二分探索方式により最も近い一致を探します
Flatten	(array, output?)	ネストされた配列を単一の配列に平坦化します
GetAll	(array, property?, value?, startIndex?, endIndex?)	プロパティ/値に一致するアイテムをフィルタリングします
GetFirst	(array, property?, value?, startIndex?, endIndex?)	プロパティ/値に一致する最初のアイテムを取得します
GetRandom	(array, startIndex?, length?)	ランダムな要素を返します
MoveAbove	(array, item1, item2)	item2 を item1 の直上に移動します
MoveBelow	(array, item1, item2)	item2 を item1 の直下に移動します
MoveDown	(array, item)	アイテムをインデックス 0 の方向へ 1 つ移動します
MoveTo	(array, item, index)	アイテムを指定したインデックスへ移動します
MoveUp	(array, item)	アイテムを末尾の方向へ 1 つ移動します
NumberArray	(start, end, prefix?, suffix?)	[start..end] の範囲を生成します。文字列のプレフィックス/サフィックスを任意で指定できます
NumberArrayStep	(start?, end?, step?)	カスタムのステップサイズで範囲を生成します
QuickSelect	(array, k, left?, right?, compare?)	部分ソート: k 番目に小さい要素をその場で求めます
Range	(a, b, options?)	範囲設定から配列を生成します
Remove	(array, item, callback?, context?)	配列からアイテムを削除します
RemoveAt	(array, index, callback?, context?)	指定したインデックスのアイテムを削除します
RemoveBetween	(array, startIndex, endIndex, callback?, context?)	範囲内のアイテムを削除します
RemoveRandomElement	(array, startIndex?, length?)	ランダムな要素を削除して返します
Replace	(array, oldItem, newItem)	あるアイテムを別のアイテムに置き換えます
RotateLeft	(array, total?)	要素を左にシフトします。最後の要素は先頭に回り込みます
RotateRight	(array, total?)	要素を右にシフトします。最初の要素は末尾に回り込みます
SafeRange	(array, startIndex, endIndex, throwError?)	インデックス範囲が境界内にあるかを検証します
SendToBack	(array, item)	アイテムをインデックス 0 に移動します
SetAll	(array, property, value, startIndex?, endIndex?)	範囲内のすべてのアイテムにプロパティを設定します
Shuffle	(array)	Fisher-Yates シャッフルです。その場で変更します
SortByDigits	(array)	文字列に埋め込まれた数値でソートします
SpliceOne	(array, index)	高速な単一要素の splice です
StableSort	(array, compare?)	安定ソートを保証します（ネイティブの安定ソートを持たないエンジン向けにマージソートへフォールバックします）
Swap	(array, item1, item2)	2 つのアイテムをその場で交換します

2D 行列操作用の Phaser.Utils.Array.Matrix サブ名前空間も含まれます。

---

オブジェクトユーティリティ

名前空間: Phaser.Utils.Objects

関数	シグネチャ	説明
Clone	(obj)	オブジェクトのシャローコピー
DeepCopy	(obj)	オブジェクトまたは配列の再帰的なディープコピー
Extend	(target, ...sources)	jQuery スタイルの extend。sources から target へプロパティをコピーします
GetAdvancedValue	(source, key, defaultValue)	GetValue と似ていますが、ランダム値やコールバックの設定値を解決します
GetFastValue	(source, key, defaultValue?)	トップレベルのみのプロパティ検索。ドットパスはサポートしません。GetValue より高速です
GetMinMaxValue	(source, key, min, max, defaultValue)	min と max の間にクランプされた値を取得します
GetValue	(source, key, defaultValue, altSource?)	ドットパスによるプロパティ検索（例: 'render.screen.width'）。altSource、次に defaultValue の順にフォールバックします
HasAll	(source, keys)	source がリストされたすべてのキーを持つ場合に true
HasAny	(source, keys)	source がリストされたいずれかのキーを持つ場合に true
HasValue	(source, key)	source がそのキーを持つ場合に true
IsPlainObject	(obj)	obj がプレーンな {} オブジェクト（DOM でも window でもない）の場合に true
Merge	(obj1, obj2)	obj1 のクローンに obj2 をマージします
MergeRight	(obj1, obj2)	obj2 のクローンに obj1 をマージします
Pick	(source, keys)	指定されたキーのみを持つ新しいオブジェクトを返します
SetValue	(source, key, value)	ドットパスのプロパティ値を設定します

---

文字列ユーティリティ

名前空間: Phaser.Utils.String

関数	シグネチャ	説明
Format	(string, values)	%1、%2 などのマーカーを配列の値で置き換えます
Pad	(str, len?, pad?, dir?)	文字列を指定した長さまでパディングします。dir: 1=左、2=右、デフォルト=両方
RemoveAt	(string, index)	指定したインデックスの文字を削除します
Reverse	(string)	文字列を反転します
UppercaseFirst	(string)	最初の文字を大文字にします
UUID	()	RFC4122 v4 UUID 文字列を生成します

---

一般的なパターン

グループでアクションを使用する

const enemies = this.add.group({ key: 'enemy', repeat: 9 });

// Position all children in a grid
Phaser.Actions.GridAlign(enemies.getChildren(), {
    width: 5, height: 2,
    cellWidth: 80, cellHeight: 80,
    x: 100, y: 50
});

// Fan out alpha across all enemies
Phaser.Actions.Spread(enemies.getChildren(), 'alpha', 0.3, 1);

値をずらすための step パラメータ

// Place sprites starting at x=100, each one 50px further right
Phaser.Actions.SetX(sprites, 100, 50);
// Result: items[0].x=100, items[1].x=150, items[2].x=200, ...

// Increment rotation with increasing step
Phaser.Actions.Rotate(sprites, 0.1, 0.05);
// Result: items[0].rotation += 0.1, items[1].rotation += 0.15, items[2].rotation += 0.2, ...

散布してから制約する

const bounds = new Phaser.Geom.Rectangle(0, 0, 800, 600);
// Random scatter
Phaser.Actions.RandomRectangle(sprites, bounds);
// Keep wrapped in bounds during update
Phaser.Actions.WrapInRectangle(sprites, bounds);

設定の解析に GetValue を使用する

// Deep property access with fallback
const width = Phaser.Utils.Objects.GetValue(config, 'render.screen.width', 800);

// Fast top-level lookup (no dot-path, better performance)
const speed = Phaser.Utils.Objects.GetFastValue(config, 'speed', 100);

アセットキーに NumberArray を使用する

// Generate frame key strings
const keys = Phaser.Utils.Array.NumberArray(1, 10, 'frame_', '.png');
// Result: ['frame_1.png', 'frame_2.png', ..., 'frame_10.png']

---

注意点

• アクションは Group を直接ではなく、プレーンな配列を操作します。 配列を取得するには必ず group.getChildren() を呼び出してください。
• PlaceOn/Random のジオメトリアクションには、Game Object の図形ではなく Phaser.Geom オブジェクトが必要です。 Phaser.GameObjects.Circle の場合は、circle.geom を渡してください。
• SetXY は y が undefined または null の場合、y を x にデフォルト設定します。 y=0 で x を別の値にしたい場合は、明示的に 0 を渡してください。
• 単一のアイテムで Spread を使用すると、min ではなく中点 (min + max) / 2 に配置されます。
• step は累積的に加算されるのではなく、反復インデックスで乗算されます。 アイテム 0 は value + 0*step、アイテム 1 は value + 1*step のようになります。
• StableSort は、エンジンが安定ソートをサポートしている場合はネイティブの Array.sort を使用し、必要な場合のみマージソートにフォールバックします。
• Shuffle（Actions と Utils.Array の両方）は配列をその場で変更し、それを返します。
• GetValue と GetFastValue の使い分け: キーが常にトップレベル（ドットなし）の場合は GetFastValue を使用してください。ドットパスの解析をスキップするため、ホットループ内で高速です。
• AddEffectBloom / AddEffectShine / AddMaskShape は v4 専用のフィルタベースのエフェクトです。入力の代わりに、作成されたエフェクトの配列を返します。

---

ソースファイルマップ

領域	パス
すべてのアクション	src/actions/
アクションのインデックス	src/actions/index.js
コアの set/inc ヘルパー	src/actions/PropertyValueSet.js, src/actions/PropertyValueInc.js
GridAlign 設定の typedef	src/actions/typedefs/
配列ユーティリティ	src/utils/array/
配列行列ユーティリティ	src/utils/array/matrix/
オブジェクトユーティリティ	src/utils/object/
文字列ユーティリティ	src/utils/string/