======================================================================== 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 # ロゴ素材 │ │ │ ├── hooks/ │ │ │ │ └── useAppFlow.ts # 画面遷移フック │ │ │ ├── network/ │ │ │ │ ├── SocketManager.ts # WSクライアント │ │ │ │ └── handlers/ │ │ │ │ ├── CommonHandler.ts # 共通WSハンドラ │ │ │ │ ├── GameHandler.ts # ゲームWSハンドラ │ │ │ │ ├── LobbyHandler.ts # ロビーWSハンドラ │ │ │ │ └── TitleHandler.ts # タイトルWSハンドラ │ │ │ └── scenes/ │ │ │ ├── game/ │ │ │ │ ├── GameInputManager.ts # 入力管理 │ │ │ │ ├── GameManager.ts # ゲーム制御 │ │ │ │ ├── GameScene.tsx # ゲーム画面 │ │ │ │ ├── GameView.tsx # ゲーム描画 │ │ │ │ ├── entities/ │ │ │ │ │ ├── map/ │ │ │ │ │ │ ├── GameMapController.ts # マップ制御 │ │ │ │ │ │ ├── GameMapModel.ts # マップモデル │ │ │ │ │ │ └── GameMapView.ts # マップ描画 │ │ │ │ │ └── player/ │ │ │ │ │ ├── PlayerController.ts # プレイヤー制御 │ │ │ │ │ ├── PlayerModel.ts # プレイヤーモデル │ │ │ │ │ └── PlayerView.ts # プレイヤー描画 │ │ │ │ └── input/ │ │ │ │ ├── joystick/ │ │ │ │ │ ├── JoystickInputPresenter.tsx # 仮想スティックUI │ │ │ │ │ ├── JoystickModel.ts # スティックモデル │ │ │ │ │ ├── JoystickView.tsx # スティック描画 │ │ │ │ │ └── common/ │ │ │ │ │ ├── index.ts # スティック共通 │ │ │ │ │ ├── joystick.constants.ts # スティック定数 │ │ │ │ │ └── joystick.types.ts # スティック型 │ │ │ │ ├── useJoystickController.ts # スティック制御フック │ │ │ │ └── useJoystickState.ts # スティック状態 │ │ │ ├── lobby/ │ │ │ │ └── LobbyScene.tsx # ロビー画面 │ │ │ └── title/ │ │ │ └── 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 # サーバー起点 │ ├── logging/ │ │ └── logEvent.ts # 共通ログ出力 │ ├── domains/ │ │ ├── game/ │ │ │ ├── GameLoop.ts # 固定ループ │ │ │ ├── GameManager.ts # ゲーム状態管理 │ │ │ ├── application/ # ユースケース・サービス │ │ │ ├── entities/ │ │ │ │ └── Player.ts # サーバーPlayer │ │ │ └── states/ │ │ │ └── MapStore.ts # マップ状態保持 │ │ └── room/ │ │ ├── application/ # ユースケース・サービス │ │ └── RoomManager.ts # ルーム管理 │ └── network/ │ ├── SocketManager.ts # WS接続管理 │ ├── adapters/ │ │ └── socketEmitters.ts # 送信アダプタ │ ├── handlers/ │ │ ├── CommonHandler.ts # 共通WSハンドラ │ │ ├── GameHandler.ts # ゲームWSハンドラ(中間層) │ │ ├── RoomHandler.ts # ルームWSハンドラ(中間層) │ │ ├── game/ # ゲーム中粒度配線 │ │ └── room/ # ルーム中粒度配線 │ ├── bootstrap/ │ │ ├── createHttpServer.ts # HTTP生成 │ │ ├── createIo.ts # Socket.IO生成 │ │ └── boot.ts # 起動配線 ├── 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/ │ │ ├── app/ │ │ │ ├── app.const.ts # アプリ定数 │ │ │ └── app.type.ts # アプリ型 │ │ ├── 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: socket.io-client 3-3. バックエンド (Server) ・Runtime: Node.js ・Execution: tsx (開発時の高速実行・ウォッチ用) ・WebSocket Library: Socket.IO - 採用理由: 接続管理・イベント配線を明確化しやすく，Client 側 (socket.io-client) と整合するため． ・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 (直接参照禁止)