========================================================================
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/
├── .devcontainer/
│ └── devcontainer.json # 開発コンテナ設定
├── apps/
│ ├── client/ # 【演出】フロントエンド (Browser)
│ │ ├── .gitignore # 除外設定
│ │ ├── index.html # HTMLエントリ
│ │ ├── package.json # 依存・スクリプト
│ │ ├── public/
│ │ │ └── vite.svg # 公開アイコン
│ │ ├── src/
│ │ │ ├── app.tsx # ルートUI
│ │ │ ├── index.css # 全体スタイル
│ │ │ ├── main.tsx # 起動エントリ
│ │ │ ├── assets/
│ │ │ │ └── preact.svg # ロゴ素材
│ │ │ ├── entities/
│ │ │ │ ├── GameMap.ts # マップ描画
│ │ │ │ └── Player.ts # プレイヤー描画
│ │ │ ├── input/
│ │ │ │ └── VirtualJoystick.tsx # 仮想スティック
│ │ │ ├── managers/
│ │ │ │ └── GameManager.ts # ゲーム制御
│ │ │ ├── network/
│ │ │ │ └── SocketClient.ts # WSクライアント
│ │ │ └── scenes/
│ │ │ ├── GameScene.tsx # ゲーム画面
│ │ │ ├── LobbyScene.tsx # ロビー画面
│ │ │ └── TitleScene.tsx # タイトル画面
│ │ ├── tsconfig.app.json # アプリTS設定
│ │ ├── tsconfig.json # TS親設定
│ │ ├── tsconfig.node.json # Node向けTS設定
│ │ └── vite.config.ts # Vite設定
│ └── server/ # 【権限】バックエンド (Node.js)
│ ├── package.json # 依存・スクリプト
│ ├── tsconfig.json # TS設定
│ └── src/
│ ├── index.ts # サーバー起点
│ ├── domains/
│ │ ├── game/
│ │ │ ├── GameHandler.ts # ゲーム入出力
│ │ │ ├── GameLoop.ts # 固定ループ
│ │ │ ├── GameManager.ts # ゲーム状態管理
│ │ │ ├── entities/
│ │ │ │ └── Player.ts # サーバーPlayer
│ │ │ └── states/
│ │ │ └── MapStore.ts # マップ状態保持
│ │ └── room/
│ │ ├── RoomHandler.ts # ルーム入出力
│ │ └── RoomManager.ts # ルーム管理
│ └── network/
│ └── SocketManager.ts # WS接続管理
├── docs/
│ ├── 01_Env/
│ │ ├── ENV_01_環境構築・技術スタック.txt # 環境・技術定義
│ │ ├── ENV_02_環境構築手順書.txt # 初期構築手順
│ │ ├── ENV_03_TypeScript概要.txt # TS基礎説明
│ │ ├── ENV_04_スマホ実機デバッグ手順.txt # 実機デバッグ手順
│ │ ├── ENV_05_Docker運用操作ガイド.txt # Docker運用手順
│ │ └── ENV_06_管理者用環境構築手順.txt # 管理者向け手順
│ ├── 02_Guide/
│ │ ├── GUIDE_01_ドキュメント作成ガイド.txt # 文書作成ルール
│ │ ├── GUIDE_02_ファイル命名規則.txt # 命名規則
│ │ └── GUIDE_03_Git運用ルール.txt # Git運用ルール
│ ├── 03_Plan/
│ │ └── PLAN_01_移動テスト実装計画.txt # 実装計画
│ └── 04_Spec/
│ └── SPEC_03_プロトタイプ_移動テスト.txt # 機能仕様
├── packages/
│ └── shared/ # 【最重要】「真実」の定義場所（型、定数、純粋ロジック）
│ ├── package.json # 依存・公開設定
│ ├── tsconfig.json # TS設定
│ └── src/
│ ├── index.ts # 共有エクスポート
│ ├── config/
│ │ ├── index.ts # 設定エクスポート
│ │ ├── gameConfig.ts # 共通定数
│ │ └── networkConfig.ts # 通信設定
│ ├── domains/
│ │ ├── gridMap/
│ │ │ ├── gridMap.logic.ts # マップ計算
│ │ │ └── gridMap.type.ts # マップ型定義
│ │ ├── player/
│ │ │ └── player.type.ts # プレイヤー型
│ │ └── room/
│ │ ├── room.const.ts # ルーム定数
│ │ └── room.type.ts # ルーム型
│ └── protocol/
│ └── events.ts # 通信イベント定義
├── test/ # テスト用スクリプト群
│ ├── load-bot.constants.ts # 負荷テスト定数
│ ├── load-bot.ts # 負荷テスト実行
│ ├── node_modules/ # テスト依存
│ ├── package.json # テスト依存・スクリプト
│ └── tsconfig.json # テストTS設定
├── .gitignore # Git除外設定
├── .npmrc # pnpm設定
├── docker-compose.prod.yml # 本番Compose定義
├── docker-compose.yml # 開発Compose定義
├── Dockerfile # 本番イメージ定義
├── package.json # ワークスペース定義
├── pnpm-lock.yaml # lockファイル
├── pnpm-workspace.yaml # workspace設定
└── README.md # プロジェクト概要
※ 右側コメントは，役割が一行で分かる短文で記載する．
※ 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
3-5. インフラ・コンテナ技術 (Infrastructure)
・Containerization: Docker
- 採用理由: 開発環境(Dev Containers)と本番環境の差異を排除するため．
・Orchestration:
- Dev: Docker Compose (ボリュームマウントによるホットリロード)
- Prod: Docker Compose (再起動ポリシーとポート開放のみの最小構成)
・Deployment Image: Multi-stage Build (Node.js Slim)
- ビルド戦略:
1. Builderステージ: 全依存をインストールし，TypeScript (Shared -> Server) をコンパイル．
2. Prune: `pnpm prune --prod` により開発依存を削除．
3. Copy: pnpmの仕様(シンボリックリンク)に対応するため，`node_modules` を明示的にコピーする．
4. Runnerステージ: 必要な `dist` と `node_modules` のみをコピーし，イメージサイズを最小化する．
4. 開発マシンの前提条件 (Prerequisites)
------------------------------------------------------------------------
本プロジェクトは Docker (Dev Containers) による開発環境統一を推奨する．
これにより、ホストOS（Windows/Mac）の環境を汚さずに構築が可能となる。
4-1. 【必須】ホストマシンにインストールするもの
以下のツールのみ，開発者のPC（ホストOS）にインストールが必要である．
1. Docker実行環境
- Docker Desktop (最新版)
- WSL2 (Windowsの場合必須)
2. エディタ
- VS Code (Visual Studio Code)
3. VS Code 拡張機能
- Dev Containers (ID: ms-vscode-remote.remote-containers)
※ これが「必須」である．これさえあれば，以下の開発ツール群は自動セットアップされる．
4. アカウント・AI
- GitHub Copilot Pro (Student)
- Gemini Pro (学校提供ライセンス)
4-2. 【自動】コンテナ内に構築されるもの (インストール不要)
以下のツールは `devcontainer.json` に定義済みであり，コンテナ起動時に
自動的にインストール・設定されるため，手動導入は不要である．
1. Runtime & Package Manager
- Node.js (v20.x LTS)
- pnpm (Latest)
2. VS Code 拡張機能 (コンテナ内)
- ESLint
- Prettier
- EditorConfig
- Hex Editor
※ ホスト側で `node -v` や `pnpm -v` を実行する必要はなく，
全て VS Code の「ターミナル (コンテナ接続済)」で行う．
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 (直接参照禁止)
