========================================================================
Pixel Paint War - 開発環境・技術スタック定義書
========================================================================

1. プロジェクト基本方針
------------------------------------------------------------------------

1-1. アーキテクチャ構成: Monorepo (モノレポ)
    ・目的: クライアント(Client)とサーバー(Server)で，言語(TypeScript)およびゲームロジック(移動演算・定数・型定義)を完全共有するため．
    ・パッケージ管理: pnpm workspaces を採用．

1-2. コア・コンセプト
    ・言語: TypeScript (Strict mode)
    ・通信: WebSocket + Hybrid Protocol
        - Core Game (移動・塗り): Custom Binary (DataView) による極小パケット通信
        - Meta Data (ロビー・チャット): JSON (開発効率とデバッグ容易性を優先)
    ・描画: WebGL 2D (Pixi.js)
    ・同期: サーバー権限 (Authoritative) + クライアント予測 (Prediction)

1-3. AI活用型開発 (AI-Assisted Development)
    ・採用ツール:
        - Gemini Pro (学校提供ライセンス)
        - GitHub Copilot Pro (GitHub Student Developer Pack)
    ・言語選定の優位性:
        TypeScriptを採用することで厳密な型定義(Type/Interface)を保持する．
        これによりAIがコードの文脈や意図を正確に解釈可能となり，
        型のないJavaScriptと比較して，コード生成・補完・リファクタリングの精度が著しく向上する．


2. ディレクトリ構造 (Directory Structure)
------------------------------------------------------------------------

2-1. 構成一覧
    root/
    ├── package.json          # pnpm workspace 定義
    ├── pnpm-workspace.yaml   # ワークスペース設定
    ├── .npmrc                # 依存関係解決の設定
    │
    ├── apps/
    │   ├── client/           # 【演出】フロントエンド (Browser)
    │   │   ├── src/
    │   │   │   ├── assets/     # 画像・音声リソース
    │   │   │   ├── core/       # クライアントの心臓部 (GameApp, MainLoop)
    │   │   │   ├── entities/   # 描画用エンティティ (PlayerSprite - 補間・描画ロジック含む)
    │   │   │   ├── input/      # 入力処理 (Joystick, Keyboard)
    │   │   │   ├── network/    # 通信処理 (SocketClient, Reconciler/補正処理)
    │   │   │   ├── scenes/     # 画面管理 (Title, Lobby, Game, Result)
    │   │   │   ├── ui/         # HTML UI管理 (HUD, Modal)
    │   │   │   └── main.ts     # エントリーポイント
    │   │   ├── index.html
    │   │   ├── vite.config.ts
    │   │   └── package.json
    │   │
    │   └── server/           # 【権限】バックエンド (Node.js)
    │       ├── src/
    │       │   ├── core/       # サーバーの心臓部 (GameLoop, ServerEngine)
    │       │   ├── entities/   # サーバー側エンティティ (Player, Item - 状態管理のみ)
    │       │   ├── managers/   # 管理クラス (RoomManager, ScoreManager)
    │       │   ├── network/    # WebSocket処理 (Connection, PacketHandler)
    │       │   └── index.ts    # エントリーポイント
    │       ├── tsconfig.json
    │       └── package.json
    │
    └── packages/
        └── shared/           # 【最重要】「真実」の定義場所（型、定数、純粋ロジック）
            ├── src/
            │   ├── config/     # ゲーム定数 (マップサイズ, TickRate, 物理定数)
            │   ├── protocol/   # 通信規約 (パケット構造, OpCode, バイナリ定義)
            │   ├── types/      # 型定義 (PlayerState, InputData, RoomInfo)
            │   ├── utils/      # 純粋関数 (Vector計算, 衝突判定, グリッド計算)
            │   └── index.ts    # エントリーポイント (tsupビルド対象)
            ├── tsup.config.ts  # ビルド設定
            └── package.json

        ※ shared は client/server 両方から import して使用する．


3. 技術スタック詳細 (Tech Stack)
------------------------------------------------------------------------

3-1. 共通・基盤 (Common / Shared)
    ・Runtime: Node.js (v20 LTS 以上)
    ・Package Manager: pnpm
    ・Build Tool: tsup (高速で軽量なTypeScriptバンドラ)
    ・Serialization: Custom Binary (Standard DataView API)
        - 採用理由: ライブラリ依存をなくし、仕様書要件（30KB/s以下）を満たす最適化を行うため。
        - 用途: 座標データ、入力情報の圧縮通信。

3-2. フロントエンド (Client)
    ・Build Tool: Vite
    ・Language: TypeScript
    ・Rendering Engine: Pixi.js (v8)
        - 採用理由: 50人同時対戦時の大量のスプライト描画と60fps維持のため．
    ・UI Library: Preact (または Vanilla HTML/CSS)
        - 採用理由: ゲームループへの負荷を避けつつ，軽量なHUDを構築するため．
    ・Network: Native WebSocket API

3-3. バックエンド (Server)
    ・Runtime: Node.js
    ・Execution: tsx (開発時の高速実行・ウォッチ用)
    ・WebSocket Library: ws
        - 採用理由: 軽量かつ標準的．uWebSockets.js への移行も視野に入れるが初期は ws で実装．
    ・Logic: 独自ループ (20Hz固定)
        - Physics Engine: 使用しない (shared/physics.ts による独自グリッド判定)

3-4. 開発ツール (Dev Tools)
    ・Linter: ESLint
    ・Formatter: Prettier
    ・Test: Vitest (共通ロジックの単体テスト用)
    ・AI Assistant: GitHub Copilot Pro, Gemini Pro


4. 開発マシンの前提条件 (Prerequisites)
------------------------------------------------------------------------
以下のツールがインストールされていること．

    1. Node.js (v20.x LTS)
       $ node -v

    2. pnpm (Corepack enabled or standalone install)
       $ pnpm -v

    3. VS Code (推奨エディタ)
       以下の拡張機能を導入推奨:
       - ESLint
       - Prettier - Code formatter
       - EditorConfig for VS Code
       - Hex Editor (バイナリパケットのデバッグ用・Microsoft公式)
       - GitHub Copilot (要ログイン確認)

    4. AI・アカウント環境
       - 学校提供の Gemini Pro へのアクセス権限確認
       - GitHub Copilot Pro (Student) の有効化確認


5. 実装上の重要ルール (Implementation Rules)
------------------------------------------------------------------------

5-1. ロジックの一元管理
   - 「移動速度」「ヒット判定」「マップ更新」の計算式は必ず `packages/shared` に記述する．
   - Client と Server で別の計算式を書くことを禁止する（同期ズレ防止）．

5-2. 座標系
   - 内部計算: Float (浮動小数点)
   - 通信データ: Integer (整数 / 100倍して送信など圧縮を考慮)
   - 描画: Float (補間処理あり)

5-3. 依存方向
   - OK: Client -> Shared
   - OK: Server -> Shared
   - NG: Client -> Server / Server -> Client (直接参照禁止)