phaser-init

Phaser 4 プロジェクトの初期化

TypeScript と Vite を使用して、新しい Phaser 4 (v4.2.1) プロジェクトの雛形を作成します。

クイック雛形作成 (推奨)

最速のセットアップには公式の雛形作成ツールを使用します:

npm create @phaserjs/game@latest

この対話型 CLI は React、Vue、Angular、Svelte、Next.js、SolidJS、およびプレーンな TypeScript をサポートしています。 初心者の方へ: プロンプトが表示されたら TypeScript + Vite を選択してください。

雛形作成後、phaser が自動的にインストールされます。次を実行してください:

cd my-game
npm install
npm run dev

手動での雛形作成

ユーザーがカスタムセットアップを必要としている場合や、各部分を理解したい場合に使用します。

ステップ 1 — プロジェクトの作成

mkdir my-game && cd my-game
npm init -y
npm install phaser
npm install -D typescript vite @types/node

ステップ 2 — ディレクトリ構造

次のレイアウトを作成します:

my-game/
├── index.html
├── package.json
├── tsconfig.json
├── vite.config.ts
├── public/
│   └── assets/
│       ├── images/
│       ├── spritesheets/
│       ├── atlases/
│       ├── audio/
│       └── tilemaps/
└── src/
    ├── main.ts
    └── scenes/
        ├── BootScene.ts
        ├── PreloaderScene.ts
        └── GameScene.ts

ステップ 3 — 設定ファイル

examples/ に示されているとおりに、これらのファイルを正確に生成します:

• examples/game-config.ts — GameConfig を含む完全な main.ts
• examples/boot-scene.ts — BootScene のスターターテンプレート
• examples/vite-config.ts — Phaser 4 用の Vite 設定

設定の重要なポイント:

package.json の scripts:

{
  "scripts": {
    "dev": "vite",
    "build": "tsc && vite build",
    "preview": "vite preview"
  }
}

tsconfig.json の重要なフィールド:

{
  "compilerOptions": {
    "target": "ES2022",
    "lib": ["ES2022", "DOM", "DOM.Iterable"],
    "module": "ESNext",
    "moduleResolution": "bundler",
    "strict": true,
    "skipLibCheck": true,
    "noEmit": true,
    "types": ["vite/client"]
  },
  "include": ["src"]
}

Phaser 4 は自身の package.json 内の exports マップを通じて型を同梱しているため、 moduleResolution: "bundler" (または "node16"/"nodenext") は、追加設定なしで import Phaser from 'phaser' からそれらを解決します。

types: ["vite/client"] は別個のものであり、必要です: これは import.meta.env に型を付け、必須の __PHASER_GAME__ 計測行がこれを使用します。これがないと npx tsc --noEmit は TS2339: Property 'env' does not exist on type 'ImportMeta' で失敗します。

types: ["Phaser"] とともに typeRoots: ["./node_modules/phaser/types"] を追加しないでください。 それは Phaser 3 / 初期 v4-RC のレシピでした。Phaser 4.2.1 に対しては、同梱の型が Phaser/index.d.ts 型ルートパッケージではなく単一の types/phaser.d.ts ファイルであるため、 TS2688: Cannot find type definition file for 'Phaser' で完全に失敗します。 その設定を引き継いでいる場合は、両方のフィールドを削除してください。

ステップ 4 — インストールの確認

npm run dev

期待される結果: ブラウザが http://localhost:5173 を開き、暗いキャンバス (または設定した背景色) が表示されます。空白のページが表示される場合は、ブラウザのコンソールでエラーを確認してください。

雛形作成後にすること

1. GameScene.ts を実際のゲームロジックに置き換えます (phaser-coder エージェントを使用)
2. public/assets/ にアセットを追加します
3. シーン全体のフローを設計します (phaser-architect エージェントを使用)
4. デバッグが完了したら arcade: { debug: false } を設定します

よくあるセットアップの間違い

• アセットが読み込まれない: Vite では、アセットは public/ に置く必要があります。import で読み込まないでください。'assets/image.png' として参照します (サーバールートからの相対パス)。
• Phaser.* での TypeScript エラー: Phaser を明示的にインポートし (import Phaser from 'phaser';)、moduleResolution: "bundler" を使用してください。tsconfig に v3 時代のテンプレートから typeRoots/types: ["Phaser"] がまだ残っている場合は、それらを削除してください — これらは v4 でビルドを壊します。ステップ 3 を参照してください。
• phaser が見つからない: npm install phaser を実行してください。beta タグは使用しないでください — phaser@beta は依然として 4.0.0-rc.7 に解決され、これは現在の安定版リリースより古いものです。
• 黒い画面: ブラウザのコンソールで 404 エラーや JS エラーを確認してください。

追加リソース

サンプルファイル

examples/ にある動作するテンプレート:

• examples/game-config.ts — シーン登録を含む完全な main.ts
• examples/boot-scene.ts — 最小限のアセット読み込みを行う BootScene
• examples/vite-config.ts — Phaser 4 用の Vite 設定

リファレンスファイル

• references/project-templates.md — TypeScript+Vite、JavaScript+Vite、および HTML のみのセットアップ向けの完全なファイル一覧
• references/template-archetypes.md — プラットフォーマー、トップダウン RPG、スペースシューター、マッチ 3 パズルゲーム向けの完全なアーキタイプ仕様

テンプレートアーキタイプ

ユーザーが空のスキャフォールドではなく特定の種類のゲームを求めている場合は、アーキタイプから完全に動作するゲームを生成します。phaser-coder エージェントはアーキタイプの仕様を使用してすべてのファイルを生成します。

利用可能なアーキタイプ（/phaser-new [template] で使用するか、phaser-coder エージェントをトリガーします）:

アーキタイプ	コマンド	主な機能
platformer	/phaser-new platformer	重力、ジャンプ、プラットフォーム、敵、コイン、ライフシステム
topdown	/phaser-new topdown	無重力、8方向移動、タイルマップワールド、NPC ダイアログ
shooter	/phaser-new shooter	スクロールする背景、弾のプーリング、敵のウェーブ、パワーアップ
puzzle	/phaser-new puzzle	マッチ3グリッド、タイルの入れ替え、連鎖マッチ、スコア
towerdefense	/phaser-new towerdefense	グリッドベースのタワー配置、敵のウェーブ、経済、発射物のプーリング
runner	/phaser-new runner	自動スクロール、ジャンプ/スライド、プロシージャルな障害物、視差効果、速度上昇
cardgame	/phaser-new cardgame	記憶合わせカード、フリップアニメーション、ペアマッチ、手数スコア
fighting	/phaser-new fighting	ステートマシンのファイター、2人ローカル対戦、ヒットボックスシステム、ラウンド制
racing	/phaser-new racing	トップダウンの回転ステアリング、タイルマップのコース、チェックポイント、AI 対戦相手

すべてのアーキタイプはプレースホルダーアセット（Graphics.generateTexture() による単色の矩形/円）で生成されるため、実際のアートがなくてもゲームはすぐに動作します。準備ができたら実際のアセットに置き換えてください。

アーキタイプの仕様: references/template-archetypes.md