phaser-build

Phaser 4 のビルドとデプロイ

開発サーバー

ホットリロード対応の開発サーバーを起動します：

npm run dev

http://localhost:5173（Vite のデフォルト）で開きます。変更はブラウザで自動的にリロードされます。

プロダクションビルド

npm run build     # Compiles TypeScript + bundles with Vite → dist/
npm run preview   # Serve the dist/ folder locally to test production build

出力は dist/ に生成されます — 任意の Web ホストで利用できる静的ファイルです。

プロジェクトの診断

ビルドの前に検証スクリプトを実行します：

bash scripts/validate-project.sh

このスクリプトは一般的な問題を自動的にチェックします。

TypeScript の型チェック

npx tsc --noEmit

リリース前にすべての型エラーを修正してください。よくある Phaser 4 の TypeScript の問題：

Phaser の型が見つからない：

// tsconfig.json — Phaser 4 resolves its own types via its exports map
{
  "compilerOptions": {
    "module": "ESNext",
    "moduleResolution": "bundler",
    "skipLibCheck": true
  }
}

その後、各ファイルで明示的にインポートします：import Phaser from 'phaser';

TS2688: Cannot find type definition file for 'Phaser' が表示される場合、そのプロジェクトは v3 時代の typeRoots + types: ["Phaser"] の組み合わせを引きずっています。両方のキーを削除してください — Phaser 4 は単一の types/phaser.d.ts を同梱しており、これは有効な type-root パッケージではありません。

this.input.keyboard が null 許容：

// Wrong:
const cursors = this.input.keyboard.createCursorKeys();
// Correct:
const cursors = this.input.keyboard!.createCursorKeys();

sprite.body が null 許容：

// Wrong:
sprite.body.velocity.x
// Correct:
(sprite.body as Phaser.Physics.Arcade.Body).velocity.x
// Or:
sprite.body?.velocity.x

this.scene.get() が基底の Scene 型を返す：

// Cast to specific scene class:
const game = this.scene.get('GameScene') as GameScene;

よくあるビルドエラー

"Cannot find module 'phaser'"

npm install phaser   # installs Phaser 4 (latest stable). Do NOT use phaser — that tag still points at 4.2.1

アセットの 404 エラー（ゲームは起動するがアセットが見つからない）

Vite では、アセットは public/ ディレクトリに置く必要があります。アセットはそのままルートで配信されます。

✅ public/assets/images/sky.png  → loads as 'assets/images/sky.png'
❌ src/assets/images/sky.png     → won't work with this.load.image()

Phaser ではアセットを ES インポートで読み込まないでください。パス文字列を参照するだけにします：

this.load.image('sky', 'assets/images/sky.png');  // ✅

"Phaser.Geom.Point is not a constructor"

v3 → v4 の破壊的変更です。Vector2 に置き換えてください：

// Old (v3):
const pt = new Phaser.Geom.Point(x, y);
// New (v4):
const pt = new Phaser.Math.Vector2(x, y);

"Math.PI2 is undefined"

v3 → v4 の破壊的変更です：

// Old (v3):
const angle = Math.PI2;        // was π (wrong!) in v3
// New (v4):
const angle = Math.TAU;        // π×2
const half = Math.PI_OVER_2;   // π/2

起動時に黒い画面になる

1. ブラウザコンソールでエラーを確認する（F12）
2. Network タブで 404 がないか確認する（アセットの欠落）
3. シーンが GameConfig の scene: [] 配列に含まれているか確認する
4. parent: 'game-container' を使用している場合、HTML に <div id="game-container"> があるか確認する
5. parent 設定を削除して document.body に直接追加してみる

WebGL コンテキストロスト

// Try Canvas renderer as fallback
const config = {
  type: Phaser.CANVAS,   // instead of Phaser.AUTO or Phaser.WEBGL
  // ...
};

または WebGL コンテキストロストの復旧リスナーを追加します：

this.game.renderer.on('contextlost', () => {
  console.warn('WebGL context lost — attempting recovery');
});

Vite の設定

// vite.config.ts
import { defineConfig } from 'vite';

export default defineConfig({
  base: './',             // IMPORTANT for itch.io and subdirectory deployment
  build: {
    outDir: 'dist',
    assetsDir: 'assets',
    minify: 'terser',
    rollupOptions: {
      output: {
        manualChunks: {
          phaser: ['phaser'],  // Bundle Phaser separately for caching
        },
      },
    },
  },
  server: {
    port: 5173,
  },
});

base: './' は重要です — itch.io、GitHub Pages、およびあらゆるサブディレクトリへのデプロイで必要になります。これがないと、アセットは /（ルート）から読み込まれ、サブディレクトリのホストで壊れます。

デプロイ先

このセクションでは、ビルドをホストに配置する仕組みを扱います。ゲームが準備完了かどうかの判断 — リリース可否の基準、バージョニング、ストアでの公開、ローンチ当日 — については skills/phaser-release/ を参照してください。

itch.io

1. npm run build
2. dist/ フォルダの中身を Zip にする（フォルダ自体ではなく、中身を Zip にします）
3. Zip を itch.io にアップロード → 「Upload files」 → HTML ゲーム
4. 「This file will be played in the browser」を設定する
5. 必要に応じて「SharedArrayBuffer support」をチェックする

GitHub Pages

# .github/workflows/deploy.yml
name: Deploy to GitHub Pages
on:
  push:
    branches: [main]
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with: { node-version: '18' }
      - run: npm ci
      - run: npm run build
      - uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./dist

GitHub Pages（サブディレクトリ）では、vite.config.ts に base: '/repo-name/' を設定します。

Netlify / Vercel

git リポジトリを接続します。以下を設定します：

• ビルドコマンド：npm run build
• 出力ディレクトリ：dist

どちらも main へのプッシュで自動デプロイされます。

Capacitor（iOS/Android）

npm install @capacitor/core @capacitor/cli @capacitor/ios @capacitor/android
npx cap init
npx cap add ios
npx cap add android
npm run build
npx cap sync
npx cap open ios    # Opens Xcode
npx cap open android  # Opens Android Studio

リリース前のパフォーマンスチェックリスト

• GameConfig に arcade: { debug: false } を設定する
• アセットはテクスチャアトラスにまとめる（個別の画像ではなく）
• 音声を圧縮する（BGM は 128kbps MP3、SFX は 96kbps）
• 弾・パーティクル・敵にオブジェクトプーリングを使用する
• すべてのパーティクルエミッターに maxParticles を設定する
• npx tsc --noEmit がエラー 0 で通る
• Chrome、Firefox、Safari でテスト済み
• モバイルでテスト済み（モバイル向けの場合）

詳細なパフォーマンスのプレイブック（計測優先のプロンプティング、フレームごとのアロケーション排除、空間グリッド、音声の遅延読み込み、アトラスのパッキング、トゥイーンリークの修正）については、skills/phaser-analyze/references/performance-playbook.md を参照してください。FPS が気になる場合は、リリース前に /phaser-analyze でプロジェクト全体の監査を行ってください。

スクリプト

プロジェクトのバリデータを実行します：

bash scripts/validate-project.sh

バリデータは以下をチェックします：Phaser のバージョン、tsconfig のフィールド、シーンファイルの存在、非推奨の v3 API の使用。