このドキュメントは、AIエージェントおよび開発者がプロジェクトの構造と設計思想を迅速に把握するためのガイドです。
Flutterによる高性能な横スクロールシューティングゲーム。リッチな描画（CustomPainter）と、拡張性の高いクリーンなアーキテクチャ（ロジックとUIの完全分離）を特徴としています。
各モジュールは責務に基づいて明確に分離されています。
main.dart- アプリ全体のエントリポイント。Rootウィジェットでの状態管理、Tickerによるフレーム更新の呼び出し、最上位のレイアウト（Stack）を管理。
game_engine.dart- ゲームの頭脳。 Mixin（
WeaponSystem,CollisionSystem）を組み合わせて、進行・移動・射撃・判定の全ロジックを一括統括します。 - 背景のスクロール停止（ボス戦等）を管理。
- ゲームの頭脳。 Mixin（
game_painter.dart- 描画エンジン。
CustomPainterを用い、全エンティティのレンダリングを統括。 - プログラマブルな描画ロジックは
painters/内の各モジュールに分散されており、このファイルはそれらを集約して描画順序を管理します。
- 描画エンジン。
constants.dart- 色、初期値、最大レベル（30など）、UIパーツのサイズなど、ゲーム全体で共有される定数の定義。
collision_system.dart: 当たり判定（自機・弾・敵・アイテム）の計算を抽出したMixin。- グリッドベースの空間分割（Spatial Partitioning）による最適化を実装済み。
weapon_system.dart: メイン/サブ武器の発射ロジック、拡散計算、誘導ミサイルのスケジュール等を担当する Mixin。level_manager.dart: スコア、パワーアップ、レベルアップ等のプレイヤーの状態管理を担当する Mixin。entity_manager.dart: 全エンティティ（弾、敵、アイテム等）のリスト管理と一括更新を担当。- エンティティ種別ごとのサブメソッド（
_updateBullets,_updateObstacles等）に分割して管理。
- エンティティ種別ごとのサブメソッド（
gamepad_manager.dart/keyboard_manager.dart: 物理デバイスからの入力を正規化し、エンジンへ伝える入力抽象化層。high_score_manager.dart: ハイスコアの永続化と読み込みを担当。
enums.dart:PowerUpType,BulletTypeなど、種別を表す定義。bullet.dart,items.dart: それぞれのエンティティのクラス定義。enemy/: 敵キャラクターの定義。enemy_base.dart: 基底クラス。描画（draw）と基本移動（update）を保持。enemy_variants.dart等: 個別の特殊な敵ロジック。
enemy_factory.dart: Waveやレア度に基づき、適切な敵インスタンスを生成する工場クラス。
game_hud.dart,game_over_overlay.dart,pause_overlay.dart: UIパーツを独立したウィジェットとしてカプセル化。title_screen.dart: ゲーム開始前のメインメニュー。
- クリーン・アーキテクチャ（ロジックとUIの分離）
- エンジン（
GameEngine）はFlutterのUI（BuildContext等）に依存せず、純粋な数学的計算に専念します。 - 描画（
GamePainter）もエンジンから渡されたデータを受け取って描画するだけで、状態の変更は行いません。
- エンジン（
- Mixinによる拡張性の確保
- 射撃や衝突判定などの巨大なロジックをMixinへ逃がすことで、
GameEngine本体の肥大化を防ぎ、機能ごとのメンテナンスを可能にしています。
- 射撃や衝突判定などの巨大なロジックをMixinへ逃がすことで、
- モデルのBarrelエクスポート
lib/models.dartが各個別モデルをリ・エクスポートすることで、外部ファイルはインポート1行で全モデルが扱えるよう利便性を確保しています。
- 新しい敵を作りたい:
models/enemy/内に定義を追加し、models/enemy_factory.dartで生成条件を設定してください。 - 新しい武器を作りたい:
engine/weapon_system.dartに発射メソッドを追加し、GameEngine.updateから呼び出すように調整してください。 - エフェクトを変えたい:
painters/内の各描画クラス、またはgame_painter.dartの該当する描画メソッド（_draw...）を編集してください。 - バランスを調整したい:
constants.dartの各種パラメータを編集、またはenemy_factory.dartのWaveごとの係数を調整してください。 - ボスの難易度を調整したい:
game_engine.dart内の_startBossBattleメソッドにある、プレイヤーの装備（パワーレベル・オプション数）に基づいたHP算出ロジックを調整してください。 - スクロール演出を変更したい: ボスが定位置で往復運動中の背景停止ロジックは
game_engine.dartのupdateメソッド内、effectiveDtScaleの算出箇所に記述されています。
- コード編集後の確認: コードを編集した後は、必ず
flutter build windowsを実行してコンパイルエラーがないか確認し、エラーがある場合は修正してください。 - フォーマット:
dart formatを実行して、コードを整形してください。 - 自動修正の適用:
dart fix --applyを実行して、推奨される修正を自動的に適用してください。