game-setup-and-config

ゲームのセットアップと設定

レンダラー、スケーリング、ピクセルアート、FPS、キャンバスの配置に適した GameConfig オプションを使用して Phaser.Game インスタンスを作成する方法。

主要なソースパス: src/core/Game.js、src/core/Config.js、src/core/typedefs/GameConfig.js、src/const.js、src/scale/const/ 関連スキル: ../scenes/SKILL.md、../loading-assets/SKILL.md、../scale-and-responsive/SKILL.md

クイックスタート

最もシンプルな Phaser 4 ゲーム -- デフォルトの 1024×768 キャンバスを持つ単一のシーン:

class MyScene extends Phaser.Scene {
    preload() {
        this.load.image('logo', 'assets/logo.png');
    }

    create() {
        this.add.image(400, 300, 'logo');
    }
}

const config = {
    type: Phaser.AUTO,
    scene: MyScene
};

const game = new Phaser.Game(config);

new Phaser.Game(config) は起動シーケンス全体をトリガーします: 設定の解析 (Config)、レンダラーの作成、DOM への挿入、ゲームループ (TimeStep) です。ゲームは起動前に DOMContentLoaded を待機します。

コアコンセプト

起動シーケンス (src/core/Game.js)

1. new Phaser.Game(config) -- 設定を Phaser.Core.Config インスタンスに解析します。
2. グローバルマネージャーを作成します: AnimationManager、TextureManager、CacheManager、InputManager、SceneManager、ScaleManager、SoundManager、TimeStep、PluginManager。
3. DOMContentLoaded を待機してから、boot() を呼び出します。
4. boot() はレンダラーを作成し (CreateRenderer)、キャンバスを DOM に追加し (AddToDOM)、デバッグヘッダーを出力し、BOOT を発行します。
5. テクスチャの準備が完了すると (TextureManager が READY を発行)、READY を発行してから start() を呼び出します。
6. start() は TimeStep ループを開始し、VisibilityHandler をセットアップし、config.postBoot を呼び出します。

設定の解析 (src/core/Config.js)

Config コンストラクターはフラットな GameConfig オブジェクトを読み取り、デフォルトを解決します。一部のプロパティはトップレベルまたはサブオブジェクト内のネストとして指定できます (例: width はトップレベルまたは scale.width の下に指定可能)。両方が存在する場合は scale サブオブジェクトが優先されます。

レンダープロパティも同様に、トップレベルのショートカット (例: pixelArt: true) または render の下にネストできます。

レンダラー定数 (src/const.js)

定数	値	動作
Phaser.AUTO	0	サポートされていれば WebGL、そうでなければ Canvas にフォールバック
Phaser.CANVAS	1	Canvas レンダラーを強制
Phaser.WEBGL	2	WebGL を強制 -- サポートされていない場合はフォールバックなし
Phaser.HEADLESS	3	レンダラーなし -- DOM は依然として必要。ユニットテスト専用

config.type で設定します。デフォルトは Phaser.AUTO です。

一般的なパターン

ピクセルアートゲーム

pixelArt が true の場合、Config は自動的に antialias: false、antialiasGL: false、roundPixels: true を設定します。

const config = {
    type: Phaser.AUTO,
    width: 320,
    height: 240,
    pixelArt: true,
    scale: {
        mode: Phaser.Scale.FIT,
        autoCenter: Phaser.Scale.CENTER_BOTH,
        zoom: Phaser.Scale.ZOOM_2X
    },
    scene: MyScene
};

スムーズなピクセルアート (WebGL のみ)

ブロック状のピクセルを維持しつつ、拡大時にピクセル間のエッジを滑らかにします:

const config = {
    type: Phaser.WEBGL,
    width: 320,
    height: 240,
    smoothPixelArt: true,
    scene: MyScene
};

smoothPixelArt が true の場合、Config は antialias: true、antialiasGL: true、pixelArt: false を設定します。

全ウィンドウ対応のレスポンシブゲーム

const config = {
    type: Phaser.AUTO,
    scale: {
        mode: Phaser.Scale.RESIZE,
        parent: 'game-container',
        width: '100%',
        height: '100%'
    },
    scene: MyScene
};

FIT による固定アスペクト比

const config = {
    type: Phaser.AUTO,
    scale: {
        mode: Phaser.Scale.FIT,
        parent: 'game-container',
        autoCenter: Phaser.Scale.CENTER_BOTH,
        width: 1280,
        height: 720,
        min: { width: 640, height: 360 },
        max: { width: 1920, height: 1080 }
    },
    backgroundColor: '#2d2d2d',
    scene: MyScene
};

カスタム FPS 制限

const config = {
    type: Phaser.AUTO,
    width: 800,
    height: 600,
    fps: {
        target: 60,
        limit: 30,
        forceSetTimeOut: false,
        smoothStep: true
    },
    scene: MyScene
};

HTML 上の透明キャンバス

const config = {
    type: Phaser.AUTO,
    width: 800,
    height: 600,
    transparent: true,
    parent: 'game-container',
    scene: MyScene
};

transparent が true の場合、backgroundColor はアルファ 0 の 0x000000 に強制されます。

既存のキャンバス要素

const canvas = document.getElementById('my-canvas');

const config = {
    type: Phaser.WEBGL,
    canvas: canvas,
    width: 800,
    height: 600,
    scene: MyScene
};

複数のシーン

const config = {
    type: Phaser.AUTO,
    width: 800,
    height: 600,
    scene: [BootScene, PreloadScene, MenuScene, GameScene],
    physics: {
        default: 'arcade',
        arcade: { gravity: { y: 300 } }
    }
};

最初のシーンのみが自動的に開始されます。その他のシーンは、シーン設定に { active: true } がある場合にのみ開始されます。../scenes/SKILL.md を参照してください。

起動コールバック

const config = {
    type: Phaser.AUTO,
    width: 800,
    height: 600,
    callbacks: {
        preBoot: function (game) {
            // Runs before Phaser boots. Game systems not yet available.
        },
        postBoot: function (game) {
            // Runs after boot. All systems ready, game loop starting.
        }
    },
    scene: MyScene
};

入力サブシステムの無効化

const config = {
    type: Phaser.AUTO,
    width: 800,
    height: 600,
    input: {
        keyboard: true,
        mouse: true,
        touch: false,
        gamepad: false,
        activePointers: 1,
        windowEvents: true
    },
    disableContextMenu: true,
    scene: MyScene
};

設定リファレンス

GameConfig のトップレベルプロパティ

プロパティ	型	既定値	説明
type	number	Phaser.AUTO (0)	レンダラー: AUTO、CANVAS、WEBGL、または HEADLESS
width	number|string	1024	ゲームの幅（ピクセル単位、または '100%'）。scale.width で上書きされます
height	number|string	768	ゲームの高さ（ピクセル単位、または '100%'）。scale.height で上書きされます
zoom	number	1	キャンバスのズーム倍率。scale.zoom で上書きされます
parent	HTMLElement|string|null	undefined	キャンバス用の DOM 要素または id。undefined = document body。null = 親なし
canvas	HTMLCanvasElement	null	独自のキャンバス要素を指定します
context	CanvasRenderingContext2D|WebGLRenderingContext	null	独自のレンダリングコンテキストを指定します
canvasStyle	string	null	キャンバス要素に適用される CSS スタイル
customEnvironment	boolean	false	非ブラウザー環境での機能検出をスキップします。true の場合、renderType は AUTO にできません
scene	SceneType|SceneType[]	null	シーンクラス（Phaser.Scene を継承）またはシーンクラスの配列
seed	string[]	[random]	Phaser.Math.RND のシード
title	string	''	コンソールバナーに表示されるゲームのタイトル
url	string	'https://phaser.io/...'	コンソールバナーに表示されるゲームの URL
version	string	''	コンソールバナーに表示されるゲームのバージョン
autoFocus	boolean	true	起動時とマウスダウン時にウィンドウを自動フォーカスします
stableSort	number|boolean	-1	-1 = 自動検出、0/false = 組み込みの安定ソート、1/true = ネイティブの ES2019 ソートに依存
disableContextMenu	boolean	false	右クリックのコンテキストメニューを無効にします
backgroundColor	string|number	0x000000	キャンバスの背景色。16 進数、CSS 文字列、またはカラーオブジェクトを受け付けます
banner	boolean|BannerConfig	(表示)	false でコンソールバナーを完全に非表示にします

scale (Phaser.Types.Core.ScaleConfig)

プロパティ	型	既定値	説明
width	number|string	1024	ゲームの基本幅
height	number|string	768	ゲームの基本高さ
zoom	number	1	ズーム倍率。定数を使用してください: NO_ZOOM (1)、ZOOM_2X (2)、ZOOM_4X (4)、MAX_ZOOM (-1)
parent	HTMLElement|string	undefined	キャンバスの DOM 親
mode	number	Phaser.Scale.NONE (0)	スケールモード（下の表を参照）
expandParent	boolean	true	親の CSS の高さを 100% に調整できるようにします
autoRound	boolean	false	パフォーマンスのために表示/スタイルのサイズを丸めます
autoCenter	number	NO_CENTER (0)	キャンバスの中央揃えモード（下の表を参照）
resizeInterval	number	500	ブラウザーサイズをチェックする間隔（ミリ秒）
fullscreenTarget	HTMLElement|string	null	フルスクリーンモード用の要素
min	{width, height}	{0, 0}	キャンバスの最小サイズ
max	{width, height}	{0, 0}	キャンバスの最大サイズ（0 = 制限なし）
snap	{width, height}	{0, 0}	キャンバスサイズを倍数にスナップします

スケールモード (src/scale/const/SCALE_MODE_CONST.js)

定数	値	動作
Phaser.Scale.NONE	0	スケーリングなし。キャンバスは設定サイズのままです
Phaser.Scale.WIDTH_CONTROLS_HEIGHT	1	幅に基づいて高さを調整します
Phaser.Scale.HEIGHT_CONTROLS_WIDTH	2	高さに基づいて幅を調整します
Phaser.Scale.FIT	3	アスペクト比を維持して親内に収めます（レターボックス）
Phaser.Scale.ENVELOP	4	アスペクト比を維持して親を覆います（はみ出す場合があります）
Phaser.Scale.RESIZE	5	アスペクト比を無視して、親を埋めるようにキャンバスをリサイズします
Phaser.Scale.EXPAND	6	表示領域には RESIZE のように、キャンバスのスケールには FIT のように動作します

センターモード (src/scale/const/CENTER_CONST.js)

定数	値
Phaser.Scale.NO_CENTER	0
Phaser.Scale.CENTER_BOTH	1
Phaser.Scale.CENTER_HORIZONTALLY	2
Phaser.Scale.CENTER_VERTICALLY	3

ズーム定数 (src/scale/const/ZOOM_CONST.js)

定数	値	動作
Phaser.Scale.NO_ZOOM	1	ズームなし
Phaser.Scale.ZOOM_2X	2	2 倍ズーム
Phaser.Scale.ZOOM_4X	4	4 倍ズーム
Phaser.Scale.MAX_ZOOM	-1	親要素に収まる最大の整数ズーム

render (Phaser.Types.Core.RenderConfig)

これらはトップレベルで設定することも、render の下にネストして設定することもできます。render サブオブジェクトが優先されます。

プロパティ	型	デフォルト	説明
antialias	boolean	true	スケール/回転されたテクスチャの線形補間
antialiasGL	boolean	true	WebGL コンテキスト作成時のアンチエイリアス
pixelArt	boolean	false	antialias: false、roundPixels: true を自動的に設定します
smoothPixelArt	boolean	false	WebGL のみ。滑らかなエッジを持つブロック状ピクセル
roundPixels	boolean	false	テクスチャベースのオブジェクトを整数位置にスナップします
transparent	boolean	false	透明なキャンバス背景
clearBeforeRender	boolean	true	毎フレームキャンバスをクリアします
preserveDrawingBuffer	boolean	false	フレーム間で WebGL バッファを保持します
premultipliedAlpha	boolean	true	WebGL 描画バッファでの乗算済みアルファ
desynchronized	boolean	false	非同期化されたレンダリングコンテキスト
failIfMajorPerformanceCaveat	boolean	false	ブラウザが低パフォーマンスを報告した場合に WebGL を中止します
powerPreference	string	'default'	'high-performance'、'low-power'、または 'default'
batchSize	number	16384	WebGL バッチあたりの最大クワッド数
maxTextures	number	-1	GPU テクスチャの最大数。-1 = 利用可能なすべてを使用
maxLights	number	10	カメラごとに表示される最大ライト数
autoMobileTextures	boolean	true	iOS/Android ではバッチあたり 1 テクスチャに制限します
selfShadow	boolean	false	ライティングされたテクスチャオブジェクトのセルフシャドウ
pathDetailThreshold	number	1	Graphics WebGL パスのポイント結合しきい値
skipUnreadyShaders	boolean	false	シェーダーがまだコンパイル中のオブジェクトの描画をスキップします
mipmapFilter	string	''	ミップマップフィルター: 'NEAREST'、'LINEAR'、'NEAREST_MIPMAP_NEAREST' など
renderNodes	object	{}	WebGL レンダラー用のカスタムレンダーノード

fps (Phaser.Types.Core.FPSConfig)

プロパティ	型	デフォルト	説明
min	number	5	許容される最小 FPS
target	number	60	目標 FPS (情報提供のみで、強制はされません)
limit	number	0	最大 FPS を強制します。0 = 制限なし
forceSetTimeOut	boolean	false	requestAnimationFrame の代わりに setTimeout を使用します
deltaHistory	number	10	デルタの平滑化のために平均化するフレーム数
panicMax	number	120	パニック後にデルタを再び信頼するまでのフレーム数
smoothStep	boolean	true	デルタの平滑化を適用します

その他のサブ設定

サブ設定キー	型	ソース
callbacks	CallbacksConfig	src/core/typedefs/CallbacksConfig.js
dom	DOMContainerConfig	src/core/typedefs/DOMContainerConfig.js
input	InputConfig	src/core/typedefs/InputConfig.js
loader	LoaderConfig	src/core/typedefs/LoaderConfig.js
physics	PhysicsConfig	src/core/typedefs/PhysicsConfig.js
plugins	PluginObject|PluginObjectItem[]	src/core/typedefs/PluginObject.js
audio	AudioConfig	src/core/typedefs/AudioConfig.js
images	ImagesConfig	src/core/typedefs/ImagesConfig.js

ゲームのライフサイクル、一時停止/再開、および破棄

ゲームのライフサイクルイベント

可視性とフォーカスの変化を監視するには、game.events(または Scene から this.game.events)をリッスンします:

game.events.on('blur', () => { /* tab lost focus */ });
game.events.on('focus', () => { /* tab regained focus */ });
game.events.on('hidden', () => { /* Page Visibility API: page hidden */ });
game.events.on('visible', () => { /* Page Visibility API: page visible */ });
game.events.on('pause', () => { /* game.pause() was called */ });
game.events.on('resume', () => { /* game.resume() was called */ });

名前付き定数を使用してください: Phaser.Core.Events.BLUR、FOCUS、HIDDEN、VISIBLE、PAUSE、RESUME。

一時停止と再開

// Pause the entire game loop (rendering and updates stop)
game.pause();

// Resume the game loop
game.resume();

// Check if the game is currently paused
if (game.isPaused) {
    // game loop is not running
}

ゲームの破棄

// Remove the canvas from the DOM and clean up
game.destroy(true);

// Full cleanup -- pass noReturn=true if you will NEVER create another Phaser instance
// This allows the framework to release additional internal references
game.destroy(true, true);

destroy(removeCanvas, noReturn) は非同期です -- 次のフレームでゲームに破棄のフラグを立てます。完了に反応するには Phaser.Core.Events.DESTROY をリッスンしてください。

ゲームのグローバルメンバー

Game インスタンスは主要なマネージャーをプロパティとして公開しており、どの Scene からでも this.game を通じてアクセスできます:

プロパティ	型	説明
game.config	Phaser.Core.Config	解析済みの GameConfig(起動後は読み取り専用)
game.scene	SceneManager	すべての Scene の開始、停止、切り替え、および管理
game.registry	DataManager	すべての Scene 間で共有されるデータストア
game.anims	AnimationManager	グローバルなアニメーション定義
game.cache	CacheManager	読み込まれたテクスチャ以外のアセット(JSON、XML など)を格納
game.textures	TextureManager	読み込まれたすべてのテクスチャとスプライトシートを格納
game.sound	SoundManager	グローバルなサウンド再生マネージャー

// Example: access the registry from any scene
this.game.registry.set('highScore', 9999);

// Example: access the scene manager
this.game.scene.start('MenuScene');

注意点とよくある間違い

1. scale とトップレベルの config。 width、height、zoom、parent はトップレベルまたは scale 内で設定できます。scale サブオブジェクトの値が優先されます。混乱を避けるため、両方を設定しないでください。

2. Phaser.WEBGL にはフォールバックがありません。 AUTO とは異なり、Phaser.WEBGL を直接使用すると、WebGL が利用できない場合に Canvas へフォールバックしません。ゲームはサイレントに失敗します。

3. parent: null と parent: undefined。 undefined(または省略)はキャンバスを document.body に追加します。null は Phaser がキャンバスを DOM にまったく追加しないことを意味します -- 自分で追加する必要があります。

4. transparent は backgroundColor を上書きします。 transparent: true の場合、設定した内容に関係なく背景色は rgba(0,0,0,0) に強制されます。

5. fps.target はフレームレートを強制しません。 これは助言的なものにすぎません。実際にフレームレートを制限するには fps.limit を使用してください。ブラウザのディスプレイリフレッシュレートが常に上限となります。

6. fps.limit は遅くするだけで、速くはしません。 60Hz のディスプレイで limit: 120 を設定しても、結果は 60 FPS のままです。

7. DOM コンテナには親が必要です。 parent 要素を指定せずに dom.createContainer: true を設定しても機能しません。

8. smoothPixelArt は WebGL 専用です。 Canvas レンダラーでは効果がありません。

9. window.FORCE_WEBGL と window.FORCE_CANVAS。 Config.js は解析の最後にこれらのグローバルをチェックし、type 設定を上書きします。これは開発/テストを目的としています。

10. Game.destroy() は非同期です。 次のフレームでゲームに破棄のフラグを立てます。完了に反応するには DESTROY イベントをリッスンしてください。同じページで二度と Phaser インスタンスを作成しない場合にのみ noReturn: true を渡してください。

v3 から v4 への変更点

• デフォルトの寸法が変更されました: 幅のデフォルトは 1024(以前は 800)、高さは 768(以前は 600)になりました。
• EXPAND スケールモードが追加されました: Phaser.Scale.EXPAND(値 6)が新規追加されました -- RESIZE の可視領域の動作と FIT のキャンバススケーリングを組み合わせたものです。
• Loader の maxRetries デフォルト: loader.maxRetries のデフォルトは 2(初期の v3 では 0)になりました。
• smoothPixelArt オプション: ブロック状のピクセル間のエッジを滑らかにする、WebGL 専用の新しいレンダリングモードです。
• renderNodes config: カスタム WebGL レンダーノード登録のための新しい render.renderNodes プロパティです。
• skipUnreadyShaders: シェーダーの並列コンパイルによりスタッターを防ぐための新しいオプションです。
• pathDetailThreshold: Graphics WebGL のパス点結合のための新しい config です。

ソースファイルマップ

概念	ファイル
Game クラス / 起動シーケンス	src/core/Game.js
設定の解析 / すべてのデフォルト値	src/core/Config.js
GameConfig typedef	src/core/typedefs/GameConfig.js
Renderer 定数 (AUTO, WEBGL, CANVAS, HEADLESS)	src/const.js
FPSConfig typedef	src/core/typedefs/FPSConfig.js
RenderConfig typedef	src/core/typedefs/RenderConfig.js
ScaleConfig typedef	src/core/typedefs/ScaleConfig.js
Scale モード定数	src/scale/const/SCALE_MODE_CONST.js
Center 定数	src/scale/const/CENTER_CONST.js
Zoom 定数	src/scale/const/ZOOM_CONST.js
TimeStep (ゲームループ)	src/core/TimeStep.js
Renderer の生成	src/core/CreateRenderer.js
ScaleManager	src/scale/ScaleManager.js
CallbacksConfig typedef	src/core/typedefs/CallbacksConfig.js
DOMContainerConfig typedef	src/core/typedefs/DOMContainerConfig.js
InputConfig typedef	src/core/typedefs/InputConfig.js
LoaderConfig typedef	src/core/typedefs/LoaderConfig.js
すべてのコア typedef	src/core/typedefs/