v4-new-features

Phaser 4 の新機能

Phaser 4 の新機能と機能性: Filters (FX/BitmapMask を置き換え)、RenderNodes (Pipelines を置き換え)、CaptureFrame、Gradient、Noise ゲームオブジェクト、SpriteGPULayer、TilemapGPULayer、Lighting コンポーネント、RenderSteps、および新しい tint モード。

関連スキル: ../v3-to-v4-migration/SKILL.md, ../filters-and-postfx/SKILL.md, ../game-object-components/SKILL.md, ../tilemaps/SKILL.md

v3 からの移行ですか? ステップバイステップのコード変更、削除された API、移行チェックリストについては、v3 から v4 への移行ガイドを参照してください。

概要: v4 で変更された点

Phaser 4 は WebGL レンダリングエンジンの完全な刷新です。v3 のレンダラーでは、各サブシステムが WebGL の状態を独立して管理していたため、競合が発生していました (例えば、特定の FX が Mask を壊すなど)。v4 では、RenderNode グラフを通じて WebGL の状態管理を一元化し、各ノードが正確に 1 つのレンダリングタスクを処理します。

主な削除

v3 の機能	v4 での代替
Pipeline	RenderNode (タスクごとのレンダリングノード)
FX (preFX / postFX)	Filters (filters.internal / filters.external)
BitmapMask	FilterMask (filters システム経由)
GeometryMask (WebGL)	FilterMask (Canvas では引き続き GeometryMask を使用)
派生 FX: Bloom, Circle, Gradient, Shine	Actions (AddEffectBloom、AddEffectShine、AddMaskShape) または GameObjects
Mesh と Plane	削除 (本格的な 3D は将来計画中)
Point	代わりに Vector2 を使用

主な追加

• 新しい GameObject: CaptureFrame、Gradient、Noise、NoiseCell2D/3D/4D、NoiseSimplex2D/3D、SpriteGPULayer、Stamp、TilemapGPULayer
• 新しいコンポーネント: Lighting、RenderSteps、RenderNodes
• 新しい Tint モード: MULTIPLY、FILL、ADD、SCREEN、OVERLAY、HARD_LIGHT
• 新しい Filters: Blend、Blocky、CombineColorMatrix、GradientMap、ImageLight、Key、Mask、NormalTools、PanoramaBlur、ParallelFilters、Quantize、Sampler、Threshold
• GL の向き: v4 は標準の GL の向きを使用します (テクスチャでは Y=0 が下端)

---

Filters システム (FX と BitmapMask を置き換え)

完全なリファレンス: filters-and-postfx.md

Filters は v3 の FX システムと Mask システムを統合します。すべての filter は入力画像を受け取り、シェーダーパスを介して出力画像を生成します。Filters は任意のゲームオブジェクトまたはカメラに適用できます -- v3 では FX をサポートするオブジェクトに制限がありました。

// v3 approach (FX):
sprite.preFX.addGlow(0xff00ff, 4);
sprite.postFX.addBlur(0, 2, 2, 1);

// v4 approach (Filters):
sprite.enableFilters();
sprite.filters.internal.addGlow(0xff00ff, 4, 0, 1);
sprite.filters.external.addBlur(0, 2, 2, 1);

// v3 approach (BitmapMask):
const mask = new Phaser.Display.Masks.BitmapMask(scene, maskImage);
sprite.setMask(mask);

// v4 approach (FilterMask):
sprite.enableFilters();
sprite.filters.internal.addMask(maskImage);

Internal と External: Internal フィルターはカメラ変換の前に実行されます (オブジェクトローカル空間、より低コスト)。External フィルターは変換後に実行されます (スクリーン空間、フル解像度)。

---

RenderNodes (Pipelines を置き換え)

v3 では、Pipeline はしばしば複数の責務を処理するレンダリングシステムでした。v4 では、各 RenderNode がその run() メソッドを介して単一のレンダリングタスクを処理します。一部のノードには、描画前に状態を蓄積するための batch() メソッドもあります。

アーキテクチャ

RenderNodeManager (WebGL レンダラー上) がすべてのレンダリングノードを所有します。ゲームオブジェクトは、ロールベースのマップを通じてノードを参照します。

// RenderNode roles on a game object:
// - 'Submitter': runs other node roles for each element
// - 'Transformer': provides vertex coordinates
// - 'Texturer': handles textures

// GameObjects have default and custom render node maps:
gameObject.defaultRenderNodes  // built-in nodes per role
gameObject.customRenderNodes   // overrides per role
gameObject.renderNodeData      // data keyed by node name

カスタム RenderNodes の設定

// Override a specific render role:
gameObject.setRenderNodeRole('Submitter', 'MyCustomSubmitter');

// Pass data to a render node:
gameObject.setRenderNodeRole('Transformer', 'MyTransformer', {
    customProperty: 42
});

// Remove a custom node (falls back to default):
gameObject.setRenderNodeRole('Submitter', null);

組み込み RenderNode タイプ

バッチハンドラー（描画呼び出しごとに複数のオブジェクトを蓄積して描画します）:

• BatchHandlerQuad -- 標準的なクワッドバッチ処理（Image、Sprite、BitmapText など）
• BatchHandlerQuadSingle -- 単一クワッドのバリアント
• BatchHandlerTileSprite -- TileSprite のバッチ処理
• BatchHandlerTriFlat -- フラット三角形のバッチ処理（Graphics、Shape）
• BatchHandlerPointLight -- ポイントライトのバッチ処理
• BatchHandlerStrip -- トライアングルストリップのバッチ処理

サブミッター（オブジェクトタイプごとにレンダリングを調整します）:

• SubmitterQuad、SubmitterTile、SubmitterTileSprite
• SubmitterSpriteGPULayer、SubmitterTilemapGPULayer

トランスフォーマー（頂点位置を計算します）:

• TransformerImage、TransformerStamp、TransformerTile、TransformerTileSprite

テクスチャラー（テクスチャのバインドを管理します）:

• TexturerImage、TexturerTileSprite

フィルター（ポストプロセッシング -- filters-and-postfx.md を参照）:

• BaseFilter、BaseFilterShader
• FilterBarrel、FilterBlend、FilterBlocky、FilterBlur（Low/Med/High のバリアント）
• FilterBokeh、FilterColorMatrix、FilterCombineColorMatrix
• FilterDisplacement、FilterGlow、FilterGradientMap、FilterImageLight
• FilterKey、FilterMask、FilterNormalTools、FilterPanoramaBlur
• FilterParallelFilters、FilterPixelate、FilterQuantize
• FilterSampler、FilterShadow、FilterThreshold、FilterVignette、FilterWipe

その他:

• Camera、FillCamera、FillRect、FillPath、FillTri
• DrawLine、StrokePath、ShaderQuad
• ListCompositor、RebindContext、YieldContext
• DynamicTextureHandler

拡張: カスタム RenderNode

// Register a custom node constructor:
renderer.renderNodes.addNodeConstructor('MyNode', MyNodeClass);

// Or add a pre-built node instance:
renderer.renderNodes.addNode('MyNode', myNodeInstance);

---

新しいゲームオブジェクト

CaptureFrame

ディスプレイリスト内でその位置にある時点の現在のフレームバッファの内容をテクスチャにキャプチャします。それ自体は何もレンダリングしません。WebGL 専用です。

// Everything above this in the display list gets captured:
const image1 = this.add.image(400, 300, 'background');

// Enable framebuffer usage on the camera:
this.cameras.main.setForceComposite(true);

// Create the capture point:
const capture = this.add.captureFrame('myCapturedTexture');

// Use the captured texture on another object:
const overlay = this.add.image(400, 300, 'myCapturedTexture');
// Add filters to the overlay to distort the captured scene

主な詳細:

• camera.setForceComposite(true) またはフレームバッファコンテキスト（Filters、DynamicTexture、部分的なアルファを持つカメラ）が必要です
• フィルターを持つ Container の内部では、その Container の内容のみをキャプチャします
• visible = false に設定するとキャプチャを停止します
• コンポーネント: BlendMode、Depth、RenderNodes、Visible

ソース: src/gameobjects/captureframe/CaptureFrame.js

Gradient

GPU でレンダリングされたカラーグラデーションを表示します。Shader を拡張します。線形、放射状、その他のシェイプモードをサポートし、ColorBand オブジェクトを含む設定可能な ColorRamp を持ちます。

// Simple linear gradient:
const grad = this.add.gradient(undefined, 100, 100, 200, 200);

// Complex radial gradient with multiple color bands:
const halo = this.add.gradient({
    bands: [
        { start: 0.5, end: 0.6, colorStart: [0.5, 0.5, 1, 0], colorEnd: 0xffffff, colorSpace: 1, interpolation: 4 },
        { start: 0.6, end: 1, colorStart: 0xffffff, colorEnd: [1, 0.5, 0.5, 0], colorSpace: 1, interpolation: 3 }
    ],
    dither: true,
    repeatMode: 1,
    shapeMode: 2,       // radial
    start: { x: 0.5, y: 0.5 },
    shape: { x: 0.5, y: 0.0 }
}, 400, 300, 800, 800);

// Animate:
halo.offset = 0.1 * (1 + Math.sin(time / 1000));

主な詳細:

• 設定: bands、shapeMode、repeatMode、start、shape、dither を持つ GradientQuadConfig
• 色は ColorBand オブジェクトを持つ ColorRamp を介して定義します（HSV、各種補間モードをサポート）
• 実行時にランプデータを変更した後は gradient.ramp.encode() を呼び出します

ソース: src/gameobjects/gradient/Gradient.js

Noise ゲームオブジェクト

すべてのノイズタイプは Shader を拡張し、WebGL 専用です。6 つのバリアントがあります:

タイプ	ファクトリー	説明
Noise	this.add.noise()	ホワイトノイズ（ランダムハッシュベース）
NoiseCell2D	this.add.noiseCell2D()	2D セルラー/Worley/Voronoi ノイズ
NoiseCell3D	this.add.noiseCell3D()	3D セルラーノイズ（アニメーション用の Z 軸スライス）
NoiseCell4D	this.add.noiseCell4D()	4D セルラーノイズ（Z+W 軸スライス）
NoiseSimplex2D	this.add.noiseSimplex2D()	2D シンプレックス/グラデーションノイズ（雲、炎、水）
NoiseSimplex3D	this.add.noiseSimplex3D()	3D シンプレックスノイズ

// Basic white noise:
const noise = this.add.noise({
    noiseOffset: [0, 0],
    noisePower: 1
}, 100, 100, 256, 256);

// Cellular noise with customization:
const cells = this.add.noiseCell2D({
    noiseOffset: [0, 0],
    noiseIterations: 3,
    noiseNormalMap: true    // output as normal map for lighting
}, 200, 200, 256, 256);

// Simplex noise for natural effects:
const simplex = this.add.noiseSimplex2D({
    noiseFlow: 0,           // animate this for evolution
    noiseIterations: 4,
    noiseWarpAmount: 0.5,   // turbulence
    noiseSeed: 42,
    noiseNormalMap: false
}, 300, 300, 256, 256);

ノイズタイプに共通するプロパティ:

• noiseOffset -- パターンをスクロールするための [x, y] 配列
• noisePower -- 出力レベルを調整します（値を大きくすると高い値が抑制されます）
• noiseNormalMap -- ノーマルマップを出力します（ライティング統合用）
• noiseIterations -- 詳細レベル（セルラー/シンプレックスタイプ）

数学的等価物: Phaser.Math.Hash()、Phaser.Math.HashCell()、Phaser.Math.HashSimplex()

ソース: src/gameobjects/noise/

SpriteGPULayer

データを静的な GPU バッファに格納することで、非常に多数のクワッド（最大数百万）を単一のドローコールでレンダリングします。個別のスプライトと比べて最大 100 倍高速です。WebGL のみ。

const layer = this.add.spriteGPULayer(texture, size); // size = max number of members

// Add members (do this all at once, not incrementally):
const member = { x: 100, y: 200, frame: 'tree', scaleX: 1, scaleY: 1, alpha: 1 };
layer.addMember(member);

// Reuse the member object for efficiency with millions of entries:
member.x = 300;
member.y = 400;
member.frame = 'bush';
layer.addMember(member);

// Enable lighting on the layer:
layer.setLighting(true);

主な詳細:

• 単一テクスチャのみ（マルチアトラス不可）、レイヤーごとに単一画像
• メンバーは作成時に定義されたトゥイーンのようなアニメーション（フェード、バウンス、ウェーブ、カラーシフト）をサポート
• バッファ内容の更新は高コスト -- 一度だけ構築し、変更しないでください
• ピクセルアートでは継ぎ目を避けるため 2 のべき乗テクスチャを推奨
• scaleX/scaleY/alpha を 0 に設定することでメンバーを視覚的に「削除」できます（バッファの再構築を回避）
• コンポーネント: Alpha, BlendMode, Depth, ElapseTimer, Lighting, Mask, RenderNodes, TextureCrop, Visible

ソース: src/gameobjects/spritegpulayer/SpriteGPULayer.js

---

新しいコンポーネント

コンポーネントの完全なリファレンス: game-object-components.md

Lighting コンポーネント

ライティングパイプラインを割り当てる v3 のアプローチを置き換えます。WebGL のみ。

// v3 approach:
sprite.setPipeline('Light2D');

// v4 approach:
sprite.setLighting(true);

// Self-shadowing (simulates surface shadows from texture brightness):
sprite.setSelfShadow(true, 0.5, 1/3);
// Args: enabled, penumbra (lower = sharper), diffuseFlatThreshold (0-1)

// Use game-wide default for self-shadow:
sprite.setSelfShadow(null);  // reads from config.render.selfShadow

サポート対象: BitmapText, Blitter, Graphics, Shape, Image, Sprite, Particles, SpriteGPULayer, Stamp, Text, TileSprite, Video, TilemapLayer, TilemapGPULayer。

バッチ処理の注意: Lighting はシェーダーを変更するため、バッチが分割されます。最高のパフォーマンスを得るには、ライト付きオブジェクトをまとめ、ライトなしオブジェクトをまとめてください。

ソース: src/gameobjects/components/Lighting.js

RenderSteps コンポーネント

ゲームオブジェクトのレンダリングプロセスにカスタムロジックを注入できます。WebGL のみ。Filters システムは内部的に RenderSteps を使用します。

// Add a custom render step:
gameObject.addRenderStep(function (renderer, gameObject, drawingContext, parentMatrix, renderStep, displayList, displayListIndex) {
    // Custom rendering logic here
    // Call next step when ready:
    var nextFn = gameObject._renderSteps[renderStep + 1];
    if (nextFn) {
        nextFn(renderer, gameObject, drawingContext, parentMatrix, renderStep + 1, displayList, displayListIndex);
    }
});

主な詳細:

• ステップは _renderSteps 配列に格納され、renderWebGLStep() を介して実行されます
• 最初のステップが最初に実行され、後続のステップを呼び出す責任があります
• これが Filters が renderWebGL フローを遅延および制御する方法です

ソース: src/gameobjects/components/RenderSteps.js

RenderNodes コンポーネント

ゲームオブジェクトに defaultRenderNodes、customRenderNodes、renderNodeData マップを提供します。使用方法については上記の RenderNodes セクションを参照してください。

ソース: src/gameobjects/components/RenderNodes.js

---

TilemapGPULayer

タイルマップの完全なリファレンス: tilemaps.md

高性能な GPU ベースのタイルマップレンダリング。専用シェーダーを介してレイヤー全体を単一のクワッドとしてレンダリングします。WebGL のみ。

// Create via Tilemap with the gpu flag:
const map = this.make.tilemap({ key: 'level1' });
const tileset = map.addTilesetImage('tiles', 'tilesImage');
const gpuLayer = map.createLayer('Ground', tileset, 0, 0, true);  // last arg: gpu = true

機能:

• 単一のテクスチャ画像を持つ単一のタイルセット
• 最大 4096x4096 タイル、最大 2^23 の一意のタイル ID
• タイルの反転とアニメーションをサポート
• 正投影タイルマップのみ（アイソメトリック/六角形は不可）
• LINEAR モードでの完璧なテクスチャフィルタリング（タイルの継ぎ目なし）
• コストはタイル単位ではなくピクセル単位 -- 表示されるタイルが多くてもパフォーマンス低下なし

制限:

• 複数のタイルセットは使用できません
• 編集には手動で generateLayerDataTexture() を呼び出して更新する必要があります
• 正投影のみ

内部データ: タイルデータはテクスチャに格納されます（タイルあたり 4 バイト: 2 つの反転ビット、1 つのアニメーションビット、1 つの未使用、28 ビットのタイルインデックス）。アニメーションデータは別のテクスチャに格納されます。

ソース: src/tilemaps/TilemapGPULayer.js

---

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