diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 7a07986..34dbac7 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -4,8 +4,8 @@ ## コードコメント・ドキュメント規則 -[#file:../docs/02_Guide/GUIDE_04_コードコメント規則.txt](../docs/02_Guide/GUIDE_04_コードコメント規則.txt) +[#file:../docs/01_GUIDE/GUIDE_04_コードコメント規則.txt](../docs/01_GUIDE/GUIDE_04_コードコメント規則.txt) ## プロトコル追加手順 -[#file:../docs/02_Guide/GUIDE_05_プロトコル追加手順.txt](../docs/02_Guide/GUIDE_05_プロトコル追加手順.txt) +[#file:../docs/01_GUIDE/GUIDE_05_プロトコル追加手順.txt](../docs/01_GUIDE/GUIDE_05_プロトコル追加手順.txt) diff --git a/.github/instructions/code-comment-rules.instructions.md b/.github/instructions/code-comment-rules.instructions.md index f5cf027..ef4a99e 100644 --- a/.github/instructions/code-comment-rules.instructions.md +++ b/.github/instructions/code-comment-rules.instructions.md @@ -4,4 +4,4 @@ # コードコメント・ドキュメント規則 -[#file:../../docs/02_Guide/GUIDE_04_コードコメント規則.txt](../../docs/02_Guide/GUIDE_04_コードコメント規則.txt) +[#file:../../docs/01_GUIDE/GUIDE_04_コードコメント規則.txt](../../docs/01_GUIDE/GUIDE_04_コードコメント規則.txt) diff --git a/.github/instructions/protocol-extension-guide.instructions.md b/.github/instructions/protocol-extension-guide.instructions.md index 4a9a3fe..1713aa8 100644 --- a/.github/instructions/protocol-extension-guide.instructions.md +++ b/.github/instructions/protocol-extension-guide.instructions.md @@ -4,4 +4,4 @@ # プロトコル追加手順 -[#file:../../docs/02_Guide/GUIDE_05_プロトコル追加手順.txt](../../docs/02_Guide/GUIDE_05_プロトコル追加手順.txt) +[#file:../../docs/01_GUIDE/GUIDE_05_プロトコル追加手順.txt](../../docs/01_GUIDE/GUIDE_05_プロトコル追加手順.txt) diff --git a/.vscode/settings.json b/.vscode/settings.json index 5ec339c..d8717a9 100644 --- a/.vscode/settings.json +++ b/.vscode/settings.json @@ -1,7 +1,7 @@ { "github.copilot.chat.commitMessageGeneration.instructions": [ { - "file": "docs/02_Guide/GUIDE_03_Git運用ルール.txt" + "file": "docs/01_GUIDE/GUIDE_03_Git運用ルール.txt" } ] } diff --git a/CLAUDE.md b/CLAUDE.md index 0a7f2f6..0ed9f39 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,7 +1,7 @@ # CLAUDE.md このファイルはClaude Codeがコード生成・編集・ドキュメント作成を行う際に従うべきプロジェクトルールを定義する. -各ルールの詳細は `docs/02_Guide/` 配下の対応ファイルを参照すること. +各ルールの詳細は `docs/01_GUIDE/` 配下の対応ファイルを参照すること. --- @@ -22,7 +22,7 @@ - **改行ルール**: 大見出し前に2行,中見出し・小見出し前に1行空ける - **コマンド**: 先頭に `$ ` を付ける -詳細: `docs/02_Guide/GUIDE_01_ドキュメント作成ガイド.txt` +詳細: `docs/01_GUIDE/GUIDE_01_ドキュメント作成ガイド.txt` --- @@ -48,7 +48,7 @@ - 拡張子: `.txt` - 1ファイル1テーマで分割する -詳細: `docs/02_Guide/GUIDE_02_ファイル命名規則.txt` +詳細: `docs/01_GUIDE/GUIDE_02_ファイル命名規則.txt` --- @@ -89,7 +89,7 @@ - `main` への直接コミット・直接プッシュは禁止(必ずPR経由) - 作業ブランチのベースは常に最新の `main` から作成する -詳細: `docs/02_Guide/GUIDE_03_Git運用ルール.txt` +詳細: `docs/01_GUIDE/GUIDE_03_Git運用ルール.txt` --- @@ -143,7 +143,7 @@ - ファイル内部でのみ使用し,外部に公開されない型・関数・定数 - コード自体が自明な場合 -詳細: `docs/02_Guide/GUIDE_04_コードコメント規則.txt` +詳細: `docs/01_GUIDE/GUIDE_04_コードコメント規則.txt` --- @@ -180,4 +180,4 @@ - `events.ts` に型本体を置かない(再公開専用を維持する) -詳細: `docs/02_Guide/GUIDE_05_プロトコル追加手順.txt` +詳細: `docs/01_GUIDE/GUIDE_05_プロトコル追加手順.txt` diff --git "a/docs/01_Env/ENV_01_\347\222\260\345\242\203\346\247\213\347\257\211\343\203\273\346\212\200\350\241\223\343\202\271\343\202\277\343\203\203\343\202\257.txt" "b/docs/01_Env/ENV_01_\347\222\260\345\242\203\346\247\213\347\257\211\343\203\273\346\212\200\350\241\223\343\202\271\343\202\277\343\203\203\343\202\257.txt" deleted file mode 100644 index bb06683..0000000 --- "a/docs/01_Env/ENV_01_\347\222\260\345\242\203\346\247\213\347\257\211\343\203\273\346\212\200\350\241\223\343\202\271\343\202\277\343\203\203\343\202\257.txt" +++ /dev/null @@ -1,308 +0,0 @@ -======================================================================== -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/ - │ │ │ │ ├── ports/ # ユースケース入出力境界 - │ │ │ │ ├── services/ # ゲームアプリケーションサービス - │ │ │ │ └── useCases/ # ゲームユースケース - │ │ │ ├── entities/ - │ │ │ │ └── Player.ts # サーバーPlayer - │ │ │ └── states/ - │ │ │ └── MapStore.ts # マップ状態保持 - │ │ └── room/ - │ │ ├── application/ - │ │ │ ├── ports/ # ユースケース入出力境界 - │ │ │ ├── services/ # ルームアプリケーションサービス - │ │ │ └── useCases/ # ルームユースケース - │ │ └── RoomManager.ts # ルーム管理 - │ └── network/ - │ ├── SocketManager.ts # WS接続管理 - │ ├── adapters/ - │ │ └── socketEmitters.ts # 送信アダプタ - │ ├── handlers/ - │ │ ├── CommonHandler.ts # 共通WSハンドラ - │ │ ├── GameHandler.ts # ゲームWSハンドラ(中間層) - │ │ ├── RoomHandler.ts # ルームWSハンドラ(中間層) - │ │ ├── game/ - │ │ │ ├── handleGameDisconnect.ts # ゲーム切断処理配線 - │ │ │ └── registerGameHandlers.ts # ゲーム受信イベント配線 - │ │ └── room/ - │ │ ├── handleRoomDisconnect.ts # ルーム切断処理配線 - │ │ └── registerRoomHandlers.ts # ルーム受信イベント配線 - │ ├── 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 # 管理者向け手順 - │ │ └── ENV_07_テスト操作手順.txt # テスト操作手順 - │ ├── 02_Guide/ - │ │ ├── GUIDE_01_ドキュメント作成ガイド.txt # 文書作成ルール - │ │ ├── GUIDE_02_ファイル命名規則.txt # 命名規則 - │ │ ├── GUIDE_03_Git運用ルール.txt # Git運用ルール - │ │ └── GUIDE_04_コードコメント規則.txt # コメント運用ルール - │ ├── 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 (直接参照禁止) - -5-4. 通信境界の責務分離 - - SocketEvents の解決(イベント名の参照)は `apps/server/src/network` 配下に集約する. - - `apps/server/src/domains` 配下では `protocol` を直接 import せず,意味名の Publisher 関数を受け取って利用する. - - Socket の接続制御・受信イベント登録・切断順序制御は network 層が担当し,業務ロジック判断は domain 層が担当する. \ No newline at end of file diff --git "a/docs/01_Env/ENV_02_\347\222\260\345\242\203\346\247\213\347\257\211\346\211\213\351\240\206\346\233\270.txt" "b/docs/01_Env/ENV_02_\347\222\260\345\242\203\346\247\213\347\257\211\346\211\213\351\240\206\346\233\270.txt" deleted file mode 100644 index eb01c3b..0000000 --- "a/docs/01_Env/ENV_02_\347\222\260\345\242\203\346\247\213\347\257\211\346\211\213\351\240\206\346\233\270.txt" +++ /dev/null @@ -1,246 +0,0 @@ -======================================================================== -Pixel Paint War - 開発環境利用ガイド (Development Environment Guide) -======================================================================== - -1. 事前準備 (Prerequisites) ------------------------------------------------------------------------- - -1-1. 目的 - 本ドキュメントは,「Pixel Paint War」の開発に参加する全メンバー向けの - 環境構築および利用ガイドである. - Monorepo構成とDocker(Dev Containers)を使用し,迅速に開発を開始する手順を記す. - -1-2. 【全員必須】 共通ツールのインストール - 開発メンバー全員(管理者・参加者問わず)が以下のツールをインストールする. - - 1. Docker Engine (Linux環境) - ・開発環境の実体(コンテナ)を動かすために必須である. - - ・インストール手順 (Ubuntu/Debian系の例): - ターミナルで以下のコマンドを順に実行する. - - # 1. 公式GPG鍵とリポジトリのセットアップ - sudo apt-get update - sudo apt-get install -y ca-certificates curl gnupg - sudo install -m 0755 -d /etc/apt/keyrings - curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg - sudo chmod a+r /etc/apt/keyrings/docker.gpg - - echo \ - "deb [arch="$(dpkg --print-architecture)" signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \ - "$(. /etc/os-release && echo "$VERSION_CODENAME")" stable" | \ - sudo tee /etc/apt/sources.list.d/docker.list > /dev/null - - # 2. パッケージのインストール - sudo apt-get update - sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin - - # 3. ユーザー権限の設定 (重要: VS Codeからsudoなしで利用するために必須) - sudo usermod -aG docker $USER - newgrp docker - - ・確認コマンド: - $ docker -v - # Docker version 20.x.x 等と表示されること - - 2. VS Code (Visual Studio Code) - ・メインのエディタとして使用する.最新版をインストールすること. - - 3. VS Code 拡張機能: "Dev Containers" - ・ID: ms-vscode-remote.remote-containers - ・拡張機能マーケットプレイスで検索し、インストールする. - ・これを入れることで、Dockerコンテナ内でVS Codeを開くことが可能になる. - - -2. 環境セットアップ (Setup) ------------------------------------------------------------------------- - - ■ リポジトリのクローン - 1. ソースコードの取得 - 任意のディレクトリで以下のコマンドを実行する. - $ git clone - - 2. ディレクトリ移動 - $ cd SkillSemiWebGame - - 3. 完了 - これだけで準備は完了である. - パッケージのインストール等はDocker起動時に自動で行われるため、 - 手動での `pnpm install` 等は不要である. - - -3. 開発環境(Dev Container)の起動 (Launch) ------------------------------------------------------------------------- - -3-1. プロジェクトを開く - 1. VS Codeを起動し,「ファイル > フォルダを開く」からプロジェクトルートを選択する. - -3-2. コンテナでの再起動 (Reopen in Container) - 以下のいずれかの方法で,開発環境をコンテナ内に移行する. - - 【方法A: ステータスバーから】 - 1. ウィンドウ左下の緑色(または青色)の「><」アイコンをクリックする. - 2. 表示されるメニューから「Reopen in Container」を選択する. - - 【方法B: コマンドパレットから】 - 1. [F1] または [Ctrl+Shift+P] を押下する. - 2. "Reopen" と入力し,「Dev Containers: Reopen in Container」を選択する. - - ※ トラブルシューティング: - もし起動後に node_modules が見つからない等のエラーが出た場合は, - 「Reopen」ではなく「Dev Containers: Rebuild Container」を選択して - 環境を完全に作り直してください. - -3-3. 初回ビルドの待機 - 1. 初回起動時は Dockerイメージのビルドと npmパッケージのインストールが行われる. - (数分〜十数分かかる場合がある) - 2. 右下に "Starting Dev Container" 等の通知が表示されている間は待機する. - -3-4. 起動確認 - 1. 左下のアイコンが「Dev Container: Pixel Paint War Dev」と表示されていることを確認する. - 2. VS Codeのターミナルを開き (`Ctrl + @`),パスを確認する. - - 成功例: node@...:/workspace$ - (Windowsのパス C:\Users... ではなく Linux形式になっていれば成功) - - 3. 動作確認コマンドを実行する. - $ pnpm --filter client dev - - ※ エラー時の対応: - 「sh: vite: not found」等のエラーが出る場合は,自動インストールが完了していない可能性があります. - ターミナルで `pnpm install` を手動実行するか,上記 3-2 の「Rebuild Container」を試してください. - - ・ブラウザでの確認: - ターミナルに「➜ Local: http://localhost:5173/」と表示されたら, - Google Chrome等のブラウザを開き,アドレスバーに上記URLを貼り付けて実行する. - - ・正常動作の判断基準: - 画面に「Vite + Preact」のロゴと「Vite + Preact + TypeScript」といった - テキストが表示されていれば,フロントエンドの環境構築は成功である. - - -4. 開発ツールの確認 (Tools Verification) ------------------------------------------------------------------------- -Dockerコンテナ起動完了後、定義済みのツールが正しく自動導入されているか確認する. -※ 手動でのインストールは不要である. - -4-1. VS Code 拡張機能 - 拡張機能サイドバーを開き、"Dev Container: Pixel Paint War Dev" セクションに - 以下がインストール済みであることを確認する. - ・ESLint - ・Prettier - Code formatter - ・EditorConfig for VS Code - ・Hex Editor - ・GitHub Copilot - -4-2. AI アシスタント設定 - GitHub Copilot Pro - - VS Code 右下のアイコンから、GitHubアカウントへのログイン状態を確認する. - - -5. 構成確認 (Project Structure) ------------------------------------------------------------------------- - -5-1. ディレクトリ構成 - コンテナ内で以下のディレクトリ構造が見えていることを確認する. - - SkillSemiWebGame/ <-- プロジェクトルート - ├── .devcontainer/ <-- Docker設定 - ├── .git/ - ├── docker-compose.yml <-- Docker構成 - ├── package.json <-- ルート定義 - ├── pnpm-workspace.yaml <-- ワークスペース定義 - ├── node_modules/ <-- 依存ライブラリ - │ - ├── apps/ <-- アプリケーション格納用 - │ ├── client/ <-- フロントエンド (Vite + Preact) - │ │ ├── src/ - │ │ │ ├── main.tsx - │ │ │ └── ... - │ │ ├── package.json <-- pixi.js, @repo/shared 依存あり - │ │ └── vite.config.ts - │ │ - │ └── server/ <-- バックエンド (Node.js) - │ ├── src/ - │ │ └── index.ts <-- エントリーポイント - │ └── package.json <-- ws, @repo/shared 依存あり - │ - └── packages/ <-- 共通パッケージ格納用 - └── shared/ <-- 共通ロジック - ├── dist/ <-- ビルド成果物 - ├── src/ - │ └── index.ts - └── package.json - -6. 動作確認 (Verification) ------------------------------------------------------------------------- - -6-1. ビルド確認 - ※ 注意: 以下のコマンドは全て「Dev Container内のターミナル」で実行すること. - - $ pnpm --filter @repo/shared build - ※ shared のビルドが成功することを確認する. - -6-2. 開発サーバー起動 - モノレポ構成のため,個別のディレクトリに移動せず,プロジェクトルートから - --filter オプションを使用して各アプリを起動する. - ※ ターミナルを2つ開き,両方を同時に起動した状態で開発を進めることを推奨. - - 1.Client (フロントエンド) の動作確認 - ・ルートディレクトリにて以下のコマンドを実行する. - $ pnpm --filter client dev - - ・ブラウザでの確認: - ターミナルに「➜ Local: http://localhost:5173/」と表示されたら, - Google Chrome等のブラウザを開き,アドレスバーに上記URLを貼り付けて実行する. - - ・正常動作の判断基準: - 画面に「Vite + Preact」のロゴと「Vite + Preact + TypeScript」といった - テキストが表示されていれば,フロントエンドの環境構築は成功である. - - 2. Server (バックエンド) の動作確認 - ・テスト用コードの作成: - 動作確認用のエントリーポイントを作成する. - $ touch apps/server/src/index.ts - - ファイルに以下の内容を記述する. - console.log("Server is running!"); - - ・コマンド: - $ pnpm --filter server dev - - ・正常動作の判断基準: - ターミナルに「Server is running!」と出力されれば構築成功である. - - 3.終了方法 (重要) - ・動作確認を終了し,開発サーバーを停止させる場合は,ターミナル上で - 「Ctrl + C」を押下する. - - -7. (応用) 本番ビルドの動作確認 (Production Build Check) ------------------------------------------------------------------------- -開発環境(Dev Container)ではなく,本番環境と同様のDockerイメージを作成し, -正しくビルド・起動できるかを確認する手順である. -「機能開発が終わった後」や「プルリクエストを出す前」に実施することを推奨する. - -7-1. 準備 - Dev Containerを閉じ,ホストOS(Windows/Mac)のターミナルを開く. - ※ Dev Container内からはDockerコマンドが使用できない場合があるため. - -7-2. ビルドと起動 - プロジェクトルートで以下のコマンドを実行する. - - $ docker compose -f docker-compose.prod.yml up -d --build - -7-3. 動作確認 - 1. ログ確認 - $ docker compose -f docker-compose.prod.yml logs -f - Serverが起動していることを確認する. - - 2. ブラウザ確認 - http://localhost:3001 - ※ ポート番号が開発用(3000/5173)と異なり 3001 に設定されている点に注意. - -7-4. 終了と削除 - 確認が終わったら必ず環境を停止・削除する. - $ docker compose -f docker-compose.prod.yml down \ No newline at end of file diff --git "a/docs/01_Env/ENV_03_TypeScript\346\246\202\350\246\201.txt" "b/docs/01_Env/ENV_03_TypeScript\346\246\202\350\246\201.txt" deleted file mode 100644 index e489c79..0000000 --- "a/docs/01_Env/ENV_03_TypeScript\346\246\202\350\246\201.txt" +++ /dev/null @@ -1,90 +0,0 @@ -======================================================================== -TypeScript概要 (TypeScript Overview) -======================================================================== - -1. 概要 (Overview) ------------------------------------------------------------------------- -本プロジェクト(Pixel Paint War)において採用するプログラミング言語「TypeScript」に関する基礎知識,選定理由,およびAI活用開発における優位性を定義する. -本ドキュメントは,開発チーム内での技術認識の統一を目的とする. - - -2. TypeScriptとは (What is TypeScript) ------------------------------------------------------------------------- -Microsoftによって開発されたオープンソースのプログラミング言語である.JavaScriptのスーパーセット(上位互換)として設計されており,大規模なアプリケーション開発に適した機能が拡張されている. - -2-1. JavaScriptとの違い - ・静的型付け (Static Typing): - 変数や関数の引数,戻り値に「型(Type)」を指定できる.JavaScriptは動的型付け言語であり,実行時まで型が決まらないが,TypeScriptはコンパイル(トランスパイル)時に整合性をチェックする. - ・クラスベースオブジェクト指向: - インターフェース(Interface),ジェネリクス(Generics),アクセス修飾子(public/private)など,JavaやC#に近いオブジェクト指向構文をサポートする. - ・コンパイルの必要性: - ブラウザやNode.jsはTypeScriptを直接実行できないため,JavaScriptファイルへ変換(トランスパイル)して使用する. - -2-2. 一般的な利用目的 - ・大規模Webアプリケーション開発: - コード量が増えても型定義により保守性を維持しやすい. - ・チーム開発: - 型定義がそのまま「仕様書」としての役割を果たし,メンバー間の認識齟齬を防ぐ. - ・フルスタック開発: - フロントエンド(React/Vue/Angular等)とバックエンド(Node.js/Deno等)で言語を統一し,型定義を共有する. - - -3. 言語の強み (Strengths) ------------------------------------------------------------------------- - -3-1. 安全性と品質向上 - ・コンパイルエラーによる早期発見: - 「undefinedのプロパティ参照」や「数値と文字列の誤った演算」など,JavaScriptで頻発する実行時エラーを,コードを書いている段階(コンパイル時)で検出できる. - -3-2. 開発効率の向上 - ・強力な入力補完 (IntelliSense): - VS Code等のエディタにおいて,型情報を元にした正確なコード補完,メソッドの候補表示,定義元へのジャンプが可能となる. - ・リファクタリングの容易さ: - 変数名や関数名の変更を行っても,依存する箇所をエディタが一括で修正・検知できるため,改修コストが低い. - - -4. AI活用型開発における利点 (Benefits in AI-Assisted Development) ------------------------------------------------------------------------- -本プロジェクトの方針である「AI活用型開発(Gemini Pro / GitHub Copilot Pro)」において,TypeScriptはJavaScriptと比較して以下の決定的な優位性を持つ. - -■ コンテキストの正確な伝達 - 型定義(Type/Interface)が存在することで,AIは変数の意図やデータ構造を推測ではなく「確定情報」として認識できる.これにより,提案されるコードの精度が向上する. - -■ ハルシネーション(嘘の生成)の抑制 - 存在しないプロパティや誤ったメソッドをAIが提案した場合でも,TypeScriptのコンパイラが即座にエラーを出すため,誤ったコードが実装に含まれるリスクを自動的に排除できる. - -■ 意図の明示化 - 「ENV_01」で定義された `packages/shared` のような共通型定義を参照させることで,AIはクライアント・サーバー間の通信仕様を正確に理解し,一貫性のあるロジックを生成可能となる. - - -5. 歴史と現状 (History and Current Status) ------------------------------------------------------------------------- - -5-1. 歴史 - ・開発者: Anders Hejlsberg(C#やTurbo Pascalの設計者)らが中心となり開発. - ・初版公開: 2012年10月. - ・背景: 当時,大規模化するWebアプリ開発においてJavaScriptの仕様(ES5)では保守が困難であったため,静的型付けの需要が高まっていた. - -5-2. 現在のステータス - ・世界No.1の使用率 (GitHub Octoverse 2025): - 2025年のGitHub年次レポートにおいて,長年トップであったPythonおよびJavaScriptを上回り,世界で最も使用されている言語(第1位)となった. - このランキングは,単なるコードの総量ではなく「貢献者数(Unique Contributors)」に基づいており,現在世界中で最も多くのアクティブユーザーが開発を行っている言語であることを示している. - ・デファクトスタンダード: - 現在,モダンなフロントエンド開発(React, Next.js, Vue.jsなど)において,TypeScriptは標準的な選択肢となっている. - ・普及率: - 「State of JS」などの開発者アンケートにおいて,長年「使用率」および「満足度」で上位を維持している.また,Google社内の標準言語としても採用されている(Alligator等). - - -6. 参考文献 (References) ------------------------------------------------------------------------- -・TypeScript Official Website - https://www.typescriptlang.org/ - -・The State of JS 2022/2023 (Usage & Satisfaction) - https://stateofjs.com/ - -・GitHub Octoverse 2025 - https://octoverse.github.com/ - -・Google Engineering Practices Documentation - https://google.github.io/eng-practices/ \ No newline at end of file diff --git "a/docs/01_Env/ENV_04_\343\202\271\343\203\236\343\203\233\345\256\237\346\251\237\343\203\207\343\203\220\343\203\203\343\202\260\346\211\213\351\240\206.txt" "b/docs/01_Env/ENV_04_\343\202\271\343\203\236\343\203\233\345\256\237\346\251\237\343\203\207\343\203\220\343\203\203\343\202\260\346\211\213\351\240\206.txt" deleted file mode 100644 index 06c1f56..0000000 --- "a/docs/01_Env/ENV_04_\343\202\271\343\203\236\343\203\233\345\256\237\346\251\237\343\203\207\343\203\220\343\203\203\343\202\260\346\211\213\351\240\206.txt" +++ /dev/null @@ -1,122 +0,0 @@ -======================================================================== -スマホ実機デバッグ手順 (Smartphone Debugging Guide) -======================================================================== - - -1. 概要 (Overview) ------------------------------------------------------------------------- - -1-0. 目的 - 本ドキュメントは,開発中のWebゲーム「Pixel Paint War」をスマホ実機で動作 - 確認するための手順書である. - 学校や組織のネットワーク(Fortinet等)による制限や,WSL2特有のネットワー - クの壁を回避するため,トンネリングツール「ngrok」を使用した外部公開手順 - を採用する. - -1-1. 前提条件 - ・WSL2 (Ubuntu等) 上で開発環境が構築済みであること. - ・ngrok の公式サイトでアカウント作成済みであること. - ・Authtoken (認証トークン) が取得済みであること. - - -2. ngrokのインストール (Installation) ------------------------------------------------------------------------- -Linux (WSL2) 環境へのインストール手順を記述する. -※ apt パッケージマネージャ経由ではエラーが発生しやすいため,バイナリ直接 -インストール方式を採用する. - -2-1. ダウンロードと配置 - 1. 圧縮ファイルのダウンロード - ターミナルで以下のコマンドを実行し,Linux版バイナリを取得する. - $ wget https://bin.equinox.io/c/bNyj1mQVY4c/ngrok-v3-stable-linux-amd64.tgz - - 2. 解凍とインストール - ダウンロードしたファイルを解凍し,実行パスの通ったディレクトリに移動する. - $ sudo tar xvzf ngrok-v3-stable-linux-amd64.tgz -C /usr/local/bin - - 3. 動作確認 - バージョン情報が表示されるか確認する. - $ ngrok --version - ※ "ngrok version 3.x.x" 等と表示されれば成功である. - -2-2. アカウント認証 (Authentication) - ngrok のダッシュボード (https://dashboard.ngrok.com/get-started/your-authtoken) - からトークンを確認し,以下のコマンドで設定する. - - ■ トークンの登録 - $ ngrok config add-authtoken [あなたのAuthtoken] - ※ "[あなたのAuthtoken]" の部分は実際の文字列に置き換える. - - -3. デバッグ実行手順 (Execution Steps) ------------------------------------------------------------------------- - -3-1. Client設定の修正 (Update Configuration) - 開発サーバーが外部 (ngrok) からの接続を受け付けるよう,設定を変更する. - - ■ package.json の編集 - `apps/client/package.json` を開き,`scripts` ブロックの `dev` コマンドに `--host` オプションを追加する. - - [修正前] - "dev": "vite" - - [修正後] - "dev": "vite --host" - -3-2. 開発サーバーの起動 (Launch Dev Server) - まず,ローカル環境でアプリケーションを起動する. - - ■ Clientアプリの起動 - プロジェクトルートで以下のコマンドを実行する. - $ pnpm --filter client dev - ※ ターミナルに `Network: http://x.x.x.x:5173/` と表示されれば設定成功である. - -3-3. ngrokによる公開 (Expose via ngrok) - 新しいターミナルウィンドウを開き,以下の手順でトンネルを作成する. - - 1. ngrokの起動 - Vite の Host ヘッダーチェックを回避するため,オプションを付与して実行する. - $ ngrok http 5173 --host-header="localhost" - - 2. 公開URLの確認 - 起動後に表示されるステータス画面から,"Forwarding" の行を確認する. - - Session Status online - Account User Name (Plan: Free) - Forwarding https://xxxx-xxxx.ngrok-free.app -> http://localhost:5173 - - 上記の "https://xxxx-xxxx.ngrok-free.app" が公開URLとなる. - -3-4. スマホからのアクセス (Access from Smartphone) - 1. URLの共有 - 発行された URL をスマホに送信する(QRコード作成ツールやチャット等を使用). - - 2. ブラウザでの確認 - スマホのブラウザ(Chrome,Safari等)で URL にアクセスする. - タイトル画面が表示されれば接続成功である. - - -4. 注意事項とトラブルシューティング (Notes & Troubleshooting) ------------------------------------------------------------------------- - -4-1. Freeプランの制限 - ・同時接続数: Freeプランでは同時に1つのポートしか公開できない. - ・Client/Server構成の注意: - 本手順ではフロントエンド (Port 5173) のみ公開している. - バックエンド (Port 3000) への WebSocket 通信が必要な場合,ゲーム開始時 - に接続エラーとなる可能性がある. - - 対策: UIレイアウトや描画負荷の確認を主目的として使用する. - -4-2. エラー対応 - ■ "ERR_NGROK_3200" (Tunnel already open) - ・既に別のターミナルで ngrok が起動している場合に発生する. - - 対策: 起動中の ngrok を終了 (Ctrl + C) してから再実行する. - - ■ "Invalid Host Header" (画面が真っ白になる) - ・Vite が不正なドメインからのアクセスを拒否している. - - 対策: 起動コマンドに `--host-header="localhost"` が含まれているか再確認する. - - ■ "ERR_CERT_AUTHORITY_INVALID" (Fortinet等の警告) - ・ngrok を使用せずローカルIPで接続しようとした場合に,組織内ネットワーク - のセキュリティ機器にブロックされる現象である. - - 対策: 必ず本手順の ngrok 経由 (https) で接続する. \ No newline at end of file diff --git "a/docs/01_Env/ENV_05_Docker\351\201\213\347\224\250\346\223\215\344\275\234\343\202\254\343\202\244\343\203\211.txt" "b/docs/01_Env/ENV_05_Docker\351\201\213\347\224\250\346\223\215\344\275\234\343\202\254\343\202\244\343\203\211.txt" deleted file mode 100644 index be89f13..0000000 --- "a/docs/01_Env/ENV_05_Docker\351\201\213\347\224\250\346\223\215\344\275\234\343\202\254\343\202\244\343\203\211.txt" +++ /dev/null @@ -1,82 +0,0 @@ -======================================================================== -Docker 運用・操作ガイド (Docker Operations Guide) -======================================================================== - -1. 目的 (Objective) ------------------------------------------------------------------------- -本ドキュメントは,Pixel Paint War プロジェクトにおける Docker の日常的な -操作コマンドと,トラブルシューティング手順をまとめたものである. -本プロジェクトでは「開発環境」と「本番環境」で異なる運用を行う. - - -2. 開発環境 (Development Environment) ------------------------------------------------------------------------- -VS Code の Dev Containers 機能を使用する. - -2-1. -基本操作 - ・起動: VS Code でプロジェクトを開き,「Reopen in Container」を実行する. - ・停止: VS Code を閉じる(自動的に停止する). - ・ターミナル: VS Code 内のターミナルを使用する. - -2-2. -コンテナの再構築 (Rebuild) - 依存関係の不整合や設定変更が反映されない場合に実行する. - 1. コマンドパレット (F1) を開く. - 2. 「Dev Containers: Rebuild Container」を選択する. - 3. キャッシュを無視したい場合は「Rebuild Without Cache」を選択する. - - -3. 本番環境 (Production Environment) ------------------------------------------------------------------------- -手動で Docker Compose コマンドを実行する. -※ 必ず WSL (Windows) または ホストOSのターミナルで実行すること. - -3-1. -基本コマンド - ■ 起動 (ビルド込み) - $ docker compose -f docker-compose.prod.yml up -d --build - - ■ 状態確認 - $ docker compose -f docker-compose.prod.yml ps - - ■ ログ確認 (リアルタイム) - $ docker compose -f docker-compose.prod.yml logs -f - - ■ 停止 - $ docker compose -f docker-compose.prod.yml down - -3-2. -ポート仕様 - ・ホスト側ポート: 3001 - ・コンテナ内ポート: 3000 - ・接続確認URL: http://localhost:3001 - ※ 開発用コンテナ (Port 3000) との衝突を避けるため,3001番を使用する. - - -4. トラブルシューティング (Troubleshooting) ------------------------------------------------------------------------- - -4-1. -ビルドエラー・反映漏れへの対処 - 修正したコードが反映されない,または原因不明のエラーが出る場合, - キャッシュを使わずに強制的に再ビルドを行う. - - $ docker compose -f docker-compose.prod.yml build --no-cache - $ docker compose -f docker-compose.prod.yml up -d --force-recreate - -4-2. -モジュールが見つからない (MODULE_NOT_FOUND) - 本番起動時に `ws` 等が見つからないエラーが出る場合,`Dockerfile` の - COPY記述を確認する.pnpm のシンボリックリンク構造に対応するため, - 以下が記述されている必要がある. - - COPY --from=builder /app/apps/server/node_modules ./apps/server/node_modules - -4-3. -再起動ループ (Restarting) - `docker ps` でステータスが `Restarting` になる場合,サーバープロセスが - クラッシュまたは終了している. - 1. ログを確認する: - $ docker compose -f docker-compose.prod.yml logs --tail=50 - 2. コード修正後,4-1 の手順で再デプロイする. \ No newline at end of file diff --git "a/docs/01_Env/ENV_06_\347\256\241\347\220\206\350\200\205\347\224\250\347\222\260\345\242\203\346\247\213\347\257\211\346\211\213\351\240\206.txt" "b/docs/01_Env/ENV_06_\347\256\241\347\220\206\350\200\205\347\224\250\347\222\260\345\242\203\346\247\213\347\257\211\346\211\213\351\240\206.txt" deleted file mode 100644 index 3b39784..0000000 --- "a/docs/01_Env/ENV_06_\347\256\241\347\220\206\350\200\205\347\224\250\347\222\260\345\242\203\346\247\213\347\257\211\346\211\213\351\240\206.txt" +++ /dev/null @@ -1,346 +0,0 @@ -======================================================================== -Pixel Paint War - 管理者用環境構築手順 (Admin Setup Guide) -======================================================================== - -1. はじめに (Introduction) ------------------------------------------------------------------------- - 本ドキュメントは,プロジェクトを「ゼロから新規作成・再構築する管理者」向けの - Monorepo構成およびDocker環境の構築ログである. - ※ 一般の開発メンバー(Git Cloneして参加する人)は本ドキュメントを実施不要である. - -2. 管理者用事前準備 (Prerequisites for Admin) ------------------------------------------------------------------------- - -2-1. プロジェクト作成用ツールのインストール - 1. Node.js (v20.x LTS) - ・Nodesource リポジトリを使用してインストールする. - - # リポジトリのセットアップとインストール - $ curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash - - $ sudo apt-get install -y nodejs - - ・確認コマンド: - $ node -v # v20.x.x と表示されること - - 2. pnpm (Package Manager) - ・Node.js 標準の npm ではなく pnpm を使用する. - ・Corepack (Node.js同梱) を有効化してインストールする. - $ sudo corepack enable - $ corepack prepare pnpm@latest --activate - - ・確認コマンド: - $ pnpm -v - - -3. 新規プロジェクト構築 (Project Initialization) ------------------------------------------------------------------------- - -3-1. プロジェクト初期化 - 1. ディレクトリ作成 - $ mkdir SkillSemiWebGame - $ cd SkillSemiWebGame - - 2. Git/pnpm 初期化 - $ git init - $ pnpm init - -3-2. Monorepo構成設定 - 1. pnpm-workspace.yaml 作成 - ルート直下に作成し、以下を記述する. - packages: - - 'apps/*' - - 'packages/*' - - 2. .npmrc 作成 - ルート直下に作成し、以下を記述する. - shamefully-hoist=true - -3-3. ディレクトリ構造の構築 - 以下の構成になるようにディレクトリを作成する. - - root/ - ├── apps/ - │ ├── client/ # フロントエンド (Browser) - │ └── server/ # バックエンド (Node.js) - └── packages/ - └── shared/ # 共通ロジック (Shared Library) - - ・作成コマンド例: - $ mkdir -p apps/client apps/server packages/shared - -3-4. Git除外設定 (.gitignore) - ルート直下に `.gitignore` を作成し、以下を記述する. - - node_modules/ - .pnpm-store/ - dist/ - build/ - .env - .DS_Store - .vscode/* - !.vscode/extensions.json - !.vscode/launch.json - coverage/ - !packages/ - - -4. アプリケーション雛形の作成 (Scaffolding) ------------------------------------------------------------------------- - -4-1. 共通ライブラリ (packages/shared) - 1. 初期化とビルドツール導入 - $ cd packages/shared - $ pnpm init - $ pnpm add -D typescript tsup - - 2. 設定ファイルの調整 (package.json) - ・name: "@repo/shared" と命名する(推奨). - ・main: "./dist/index.js", types: "./dist/index.d.ts" を指定する. - ・scripts: "build": "tsup src/index.ts --format cjs,esm --dts" を追加する. - - 3. エントリーポイントの作成 - $ mkdir src - $ touch src/index.ts - ※ (例: export * from './constants';) - - 4. TypeScript設定ファイルの作成 (tsconfig.json) - ・ファイル: packages/shared/tsconfig.json - ・内容: - { - "compilerOptions": { - "target": "ES2020", - "module": "ESNext", - "moduleResolution": "Bundler", - "lib": ["ES2020", "DOM", "DOM.Iterable"], - "declaration": true, - "declarationMap": true, - "sourceMap": true, - "outDir": "./dist", - "rootDir": "./src", - "strict": true, - "esModuleInterop": true, - "skipLibCheck": true, - "forceConsistentCasingInFileNames": true - }, - "include": ["src/**/*"], - "exclude": ["node_modules", "dist"] - } - -4-2. フロントエンド (apps/client) - 1. プロジェクト作成 - $ cd ../../apps/client - $ pnpm create vite . --template preact-ts - ※ Use rolldown-vite? » No - ※ Install with pnpm and start now? » No - - 2. 依存ライブラリのインストール - $ pnpm add pixi.js - $ pnpm add @repo/shared --workspace - -4-3. バックエンド (apps/server) - 1. 初期化 - $ cd ../../apps/server - $ pnpm init - - 2. 依存ライブラリのインストール - $ pnpm add ws - $ pnpm add -D tsx typescript @types/node @types/ws - $ pnpm add @repo/shared --workspace - - 3. サーバー用ディレクトリとファイルの作成 - $ mkdir src - $ touch src/index.ts - - 4. 実行スクリプトの定義 (package.json) - "scripts": { - "dev": "tsx watch src/index.ts" - } - - 5. TypeScript設定ファイルの作成 (tsconfig.json) - ・ファイル: apps/server/tsconfig.json - ・内容: - { - "compilerOptions": { - "target": "ES2022", - "module": "NodeNext", - "moduleResolution": "NodeNext", - "lib": ["ES2022"], - "strict": true, - "noEmit": true, - "esModuleInterop": true, - "skipLibCheck": true, - "forceConsistentCasingInFileNames": true, - "baseUrl": ".", - "paths": { - "@repo/shared": ["../../packages/shared/src/index.ts"] - } - }, - "include": ["src/**/*"], - "exclude": ["node_modules"] - } - -4-4. 初回コミット (Initial Commit) - 1. ルートに戻る - $ cd ../.. - 2. ステータスの確認 (node_modulesが含まれていないこと) - $ git status - 3. Gitへ保存 - $ git add . - $ git commit -m "chore: Initialize project structure and dependencies" - - -5. Docker環境定義ファイルの作成 (Configuration) ------------------------------------------------------------------------- - -5-1. Dockerfile の作成 - プロジェクトルートに `Dockerfile` を作成する. - ※ Node.js v20 をベースとし,pnpm を有効化した開発用イメージ定義. - - FROM node:20-slim - - # pnpmの準備 - ENV PNPM_HOME="/pnpm" - ENV PATH="$PNPM_HOME:$PATH" - RUN corepack enable - - # 作業ディレクトリ設定 - WORKDIR /workspace - - # 依存関係のコピーとインストール (キャッシュ活用) - COPY . . - RUN pnpm install - - # ポート公開 (Vite:5173, Server:3000) - EXPOSE 5173 3000 - - # デフォルトコマンド (docker-composeで上書きするため待機) - CMD ["sleep", "infinity"] - -5-2. docker-compose.yml の作成 (開発用) - プロジェクトルートに `docker-compose.yml` を作成する. - ※ ローカルのソースコードをコンテナにマウントする設定. - - version: "3.8" - - services: - app: - container_name: pixel-paint-war-dev - # 開発用イメージ: Node.js v20 (定義書準拠) - image: mcr.microsoft.com/devcontainers/typescript-node:20 - - # 永続化とボリュームマウント - volumes: - # カレントディレクトリをコンテナ内の /workspace にマウント - - .:/workspace:cached - # 【重要】node_modules をホスト側と切り離して高速化・安定化させる設定 - - node_modules:/workspace/node_modules - - # コマンドの上書き (コンテナを常時起動させる) - command: sleep infinity - - # ネットワーク設定 - # Client(5173) と Server(3000) のポートを開放 - ports: - - "5173:5173" - - "3000:3000" - - # 環境変数 - environment: - - NODE_ENV=development - - # ユーザー権限 (Nodeイメージ推奨のユーザー) - user: node - - volumes: - node_modules: - -5-3. .devcontainer 設定の作成 - 1. ディレクトリ作成 - $ mkdir .devcontainer - - 2. .devcontainer/devcontainer.json 作成 - VS Codeがコンテナを認識するための設定. - - { - "name": "Pixel Paint War Dev", - "dockerComposeFile": "../docker-compose.yml", - "service": "app", - "workspaceFolder": "/workspace", - - "features": { - "ghcr.io/devcontainers/features/node:1": { - "version": "20", - "pnpm": "latest" - } - }, - - "customizations": { - "vscode": { - "extensions": [ - "dbaeumer.vscode-eslint", - "esbenp.prettier-vscode", - "editorconfig.editorconfig", - "ms-vscode.hexeditor", - "github.copilot", - "github.copilot-chat" - ], - "settings": { - "editor.formatOnSave": true, - "editor.defaultFormatter": "esbenp.prettier-vscode" - } - } - }, - - // コンテナ起動後の初期化コマンド - // 1. sudo chown ... : node_modules の所有権を node ユーザーに強制変更 - // 2. pnpm install : その後,安全にインストールを実行 - // 3. build : 最後に共通パッケージをビルド - "postCreateCommand": "sudo chown -R node:node /workspace/node_modules && pnpm install && pnpm --filter @repo/shared build", - - // コンテナ内のユーザー - "remoteUser": "node" - } - -5-4. docker-compose.prod.yml の作成 (本番確認用) - プロジェクトルートに `docker-compose.prod.yml` を作成する. - ※ 本番ビルド確認用にポートをずらし、ビルドコマンドを実行する設定. - - services: - app: - build: . - ports: - - "3001:3000" - environment: - - NODE_ENV=production - command: pnpm start - - -6. 本番デプロイ構成の補足 (Deployment Config) ------------------------------------------------------------------------- -本番環境へデプロイする際は,上記 `Dockerfile` をマルチステージビルドに修正し, -軽量化を図ることが推奨される. - -6-1. Dockerfile (本番用最適化例) - ※ 必要に応じて `Dockerfile.prod` として作成する. - - FROM node:20-slim AS base - ENV PNPM_HOME="/pnpm" - ENV PATH="$PNPM_HOME:$PATH" - RUN corepack enable - COPY . /app - WORKDIR /app - - FROM base AS prod-deps - RUN --mount=type=cache,id=pnpm,target=/pnpm/store pnpm install --prod --frozen-lockfile - - FROM base AS build - RUN --mount=type=cache,id=pnpm,target=/pnpm/store pnpm install --frozen-lockfile - RUN pnpm run build - - FROM base - COPY --from=prod-deps /app/node_modules /app/node_modules - COPY --from=build /app/apps/server/dist /app/apps/server/dist - COPY --from=build /app/apps/client/dist /app/apps/client/dist - - EXPOSE 3000 - CMD [ "pnpm", "start" ] \ No newline at end of file diff --git "a/docs/01_Env/ENV_07_\343\203\206\343\202\271\343\203\210\346\223\215\344\275\234\346\211\213\351\240\206.txt" "b/docs/01_Env/ENV_07_\343\203\206\343\202\271\343\203\210\346\223\215\344\275\234\346\211\213\351\240\206.txt" deleted file mode 100644 index 9d943c7..0000000 --- "a/docs/01_Env/ENV_07_\343\203\206\343\202\271\343\203\210\346\223\215\344\275\234\346\211\213\351\240\206.txt" +++ /dev/null @@ -1,96 +0,0 @@ -======================================================================== -テスト操作手順 (Test Operation Guide) -======================================================================== - - -1. 概要 (Overview) ------------------------------------------------------------------------- -本ドキュメントは,プロジェクト内のテスト関連ファイルの実行方法を整理し,チーム内で共通の運用手順を共有することを目的とする. - - -1-1. 対象範囲 - -■ 対象ファイル -・テスト実行用スクリプト: /workspace/test/load-bot.mjs -・テスト用依存定義: /workspace/test/package.json - -■ 対象外 -・アプリ本体のビルドと起動手順 -・本番運用の監視設定 - - -2. 前提条件 (Prerequisites) ------------------------------------------------------------------------- - -2-1. 環境 -・Node.js / pnpm が利用可能であること -・インターネット接続が利用可能であること - -2-2. 設定値 -■ 接続先URL -・既定値: https://skillsemiwebgame.onrender.com -・変更方法: コマンドライン引数(--dev)または定数を編集する - - -3. 実行手順 (Execution Steps) ------------------------------------------------------------------------- - -3-1. 初回準備 -1. テスト用ディレクトリへ移動 - - コマンド: $ cd /workspace/test -2. 依存関係のインストール - - コマンド: $ pnpm install - -3-2. 実行 - - コマンド: $ pnpm start - - 開発環境に接続する場合: $ pnpm start -- --dev - - -4. パラメータ一覧 (Parameters) ------------------------------------------------------------------------- -4-1. コマンドライン引数 - ・--dev: 開発環境(DEV_SERVER_URL)に接続する - -4-2. 定数 (load-bot.constants.ts) - ・URL: 本番サーバURL - ・DEV_URL: 開発サーバURL - ・BOTS: 同時接続数 - ・DURATION_MS: 実行時間 (ms)。0以下またはInfinityで無期限 - ・JOIN_DELAY_MS: 参加間隔 (ms) - ・MOVE_TICK_MS: 移動送信間隔 (ms) - ・BOT_SPEED: 移動速度 - ・BOT_RADIUS: プレイヤー半径 - ・BOT_CAN_MOVE: ボット移動の有効化 (true/false) - ・START_DELAY_MS: 開始遅延 (ms) - ・MAX_X: X座標上限 - ・MAX_Y: Y座標上限 - ・ROOM_ID: ルームID - ・START_GAME: ゲーム開始の有効化 (true/false) - ・SOCKET_PATH: Socket.IOのパス - ・SOCKET_TRANSPORTS: Socket.IOのトランスポート - - -5. 出力と終了 (Output & Termination) ------------------------------------------------------------------------- - -5-1. 標準出力 - ・開始時に設定値が出力される - ・終了時に簡易統計 (接続数など) が出力される - -5-2. 終了方法 - ・指定時間経過後に自動終了する - ・途中終了する場合はプロセスを終了する - - -6. 注意事項 (Notes) ------------------------------------------------------------------------- - -6-1. 本番サーバへの負荷 - ・負荷テストは低負荷から段階的に実施すること - ・必要に応じて管理者へ事前連絡を行うこと - -6-2. 依存関係 - ・test配下は独立した依存関係を持つため,別途pnpm installが必要になる - -6-3. 計測の限界 - ・本スクリプトは簡易負荷確認用であり,詳細な計測は専用ツールの利用を推奨する diff --git "a/docs/01_Env/ENV_08_\347\240\224\347\251\266\345\256\244\343\202\265\343\203\274\343\203\220\343\203\207\343\203\227\343\203\255\343\202\244\346\211\213\351\240\206\346\233\270.txt" "b/docs/01_Env/ENV_08_\347\240\224\347\251\266\345\256\244\343\202\265\343\203\274\343\203\220\343\203\207\343\203\227\343\203\255\343\202\244\346\211\213\351\240\206\346\233\270.txt" deleted file mode 100644 index 6f4179d..0000000 --- "a/docs/01_Env/ENV_08_\347\240\224\347\251\266\345\256\244\343\202\265\343\203\274\343\203\220\343\203\207\343\203\227\343\203\255\343\202\244\346\211\213\351\240\206\346\233\270.txt" +++ /dev/null @@ -1,279 +0,0 @@ -======================================================================== -研究室サーバデプロイ手順書 (Lab Server Deployment Guide) -======================================================================== - -1. 概要 (Overview) ------------------------------------------------------------------------- -本ドキュメントは,Pixel Paint War を1台の研究室サーバ上に本番デプロイする -手順をまとめたものである. -Nginx をリバースプロキシとして使用し,外部公開ポートは 8803 のみとする. -フロントエンド(静的ファイル)とバックエンド(Socket.IO)は同一サーバ内で -ポートを分けて動作させ,外部デバイスは Nginx 経由でのみ通信する. - - -1-1. 構成図 - - [デバイス] ──HTTP(8803)──▶ [Nginx (:8803)] - ├── / → 静的ファイル配信(Viteビルド済み) - └── /socket.io → proxy_pass http://127.0.0.1:3000 - (サーバ内部のみ,外部非公開) - - ・外部公開ポート: 8803 のみ - ・バックエンド(ポート3000)は localhost バインドで外部アクセス不可 - ・HTTPS化する場合は Nginx で SSL 終端を行う(6章参照) - - -2. 前提条件 (Prerequisites) ------------------------------------------------------------------------- - -2-1. サーバ環境 - ・OS: Linux(Ubuntu 20.04 以上推奨) - ・Docker / Docker Compose がインストール済みであること - ・Nginx がインストール済みであること - ・Git がインストール済みであること - ・ポート 8803 がファイアウォールで許可されていること - -2-2. 確認コマンド - $ docker --version - $ docker compose version - $ nginx -v - $ git --version - - -3. デプロイ手順 (Deployment Steps) ------------------------------------------------------------------------- - -3-1. リポジトリの取得 - 1. サーバ上で任意のディレクトリにクローンする - $ git clone <リポジトリURL> /opt/pixel-paint-war - $ cd /opt/pixel-paint-war - - 2. デプロイ対象のブランチ・タグに切り替える - $ git checkout main - $ git pull origin main - -3-2. フロントエンドのビルド - フロントエンドは静的ファイルとしてビルドし,Nginx から配信する. - VITE_PROD_SERVER_URL にはデバイスからアクセスする URL を指定する. - - ■ ローカルネットワーク(HTTP)の場合 - $ docker run --rm -v $(pwd):/app -w /app node:20-slim \ - bash -c "corepack enable && pnpm install --frozen-lockfile \ - && pnpm --filter @repo/shared build \ - && VITE_PROD_SERVER_URL=http://<サーバIP>:8803 pnpm --filter client build" - - ■ ドメイン運用(HTTPS)の場合 - $ docker run --rm -v $(pwd):/app -w /app node:20-slim \ - bash -c "corepack enable && pnpm install --frozen-lockfile \ - && pnpm --filter @repo/shared build \ - && VITE_PROD_SERVER_URL=https://yourdomain.example.com:8803 pnpm --filter client build" - - ※ ビルド成果物は apps/client/dist/ に出力される - -3-3. バックエンドの起動(Docker Compose) - 本番用の docker-compose.prod.yml を使用してバックエンドを起動する. - ポートは localhost バインドとし,Nginx 経由でのみアクセスさせる. - - 1. docker-compose.prod.yml を以下の内容に編集する - - services: - game-server: - build: - context: . - dockerfile: Dockerfile - container_name: pixel-paint-server-prod - restart: unless-stopped - ports: - - "127.0.0.1:3000:3000" - environment: - - NODE_ENV=production - - ※ ポイント: ports を "127.0.0.1:3000:3000" にすることで, - localhost からのみアクセス可能となり外部に直接公開されない - - 2. コンテナをビルド・起動する - $ docker compose -f docker-compose.prod.yml up -d --build - - 3. 起動確認 - $ docker compose -f docker-compose.prod.yml ps - - STATUS が「Up」になっていることを確認する - - 4. ヘルスチェック - $ curl http://127.0.0.1:3000 - - 「ok」と返れば正常 - -3-4. Nginx の設定 - Nginx の設定ファイルを作成し,ポート 8803 でリクエストを受け付ける. - - 1. 設定ファイルを作成する - $ sudo vi /etc/nginx/sites-available/pixel-paint-war - - 2. 以下の内容を記述する - - server { - listen 8803; - server_name _; - - # フロントエンド(静的ファイル配信) - root /opt/pixel-paint-war/apps/client/dist; - index index.html; - - location / { - try_files $uri $uri/ /index.html; - } - - # バックエンド(Socket.IO → 内部ポート3000へプロキシ) - location /socket.io/ { - proxy_pass http://127.0.0.1:3000; - proxy_http_version 1.1; - proxy_set_header Upgrade $http_upgrade; - proxy_set_header Connection "upgrade"; - proxy_set_header Host $host; - proxy_set_header X-Real-IP $remote_addr; - proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; - proxy_set_header X-Forwarded-Proto $scheme; - } - } - - 3. シンボリックリンクを作成して有効化する - $ sudo ln -s /etc/nginx/sites-available/pixel-paint-war /etc/nginx/sites-enabled/ - - 4. 設定の文法チェック - $ sudo nginx -t - - 「syntax is ok」「test is successful」と表示されること - - 5. Nginx を再起動する - $ sudo systemctl restart nginx - -3-5. 動作確認 - 1. ブラウザからアクセスする - http://<サーバIP>:8803 - - 2. ゲーム画面が表示され,ルーム作成・参加が正常に動作することを確認する - - 3. バックエンドへの直接アクセスが遮断されていることを確認する - $ curl http://<サーバIP>:3000 - → 接続拒否またはタイムアウトになること - - -4. ファイアウォール設定 (Firewall) ------------------------------------------------------------------------- -外部に公開するポートを 8803 のみに制限する. - -4-1. ufw を使用する場合 - $ sudo ufw allow 8803/tcp - $ sudo ufw deny 3000/tcp - $ sudo ufw enable - $ sudo ufw status - -4-2. 確認事項 - ・ポート 8803: 外部からアクセス可能であること - ・ポート 3000: 外部からアクセス不可であること - ・SSH ポート(22): 許可済みであること(ロックアウト防止) - - -5. 運用コマンド (Operations) ------------------------------------------------------------------------- - -5-1. 基本操作 - ■ バックエンドの状態確認 - $ docker compose -f docker-compose.prod.yml ps - - ■ ログ確認(リアルタイム) - $ docker compose -f docker-compose.prod.yml logs -f - - ■ バックエンドの停止 - $ docker compose -f docker-compose.prod.yml down - - ■ バックエンドの再起動 - $ docker compose -f docker-compose.prod.yml restart - - ■ Nginx の状態確認 - $ sudo systemctl status nginx - -5-2. アップデート手順 - コードを更新して再デプロイする場合の手順. - - 1. 最新コードを取得する - $ cd /opt/pixel-paint-war - $ git pull origin main - - 2. フロントエンドを再ビルドする(3-2 の手順を再実行) - - 3. バックエンドを再ビルド・再起動する - $ docker compose -f docker-compose.prod.yml up -d --build - - 4. Nginx を再読み込みする(設定変更がある場合のみ) - $ sudo systemctl reload nginx - -5-3. キャッシュクリア再ビルド - ビルドキャッシュが原因で問題が発生する場合に実行する. - - $ docker compose -f docker-compose.prod.yml build --no-cache - $ docker compose -f docker-compose.prod.yml up -d --force-recreate - - -6. HTTPS化(任意) (HTTPS Setup) ------------------------------------------------------------------------- -ドメインを使用して HTTPS でアクセスさせる場合の追加手順. - -6-1. Let's Encrypt で証明書を取得する - $ sudo apt install certbot python3-certbot-nginx - $ sudo certbot --nginx -d yourdomain.example.com - -6-2. Nginx 設定を HTTPS 対応に変更する - - server { - listen 8803 ssl; - server_name yourdomain.example.com; - - ssl_certificate /etc/letsencrypt/live/yourdomain.example.com/fullchain.pem; - ssl_certificate_key /etc/letsencrypt/live/yourdomain.example.com/privkey.pem; - - root /opt/pixel-paint-war/apps/client/dist; - index index.html; - - location / { - try_files $uri $uri/ /index.html; - } - - location /socket.io/ { - proxy_pass http://127.0.0.1:3000; - proxy_http_version 1.1; - proxy_set_header Upgrade $http_upgrade; - proxy_set_header Connection "upgrade"; - proxy_set_header Host $host; - proxy_set_header X-Real-IP $remote_addr; - proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; - proxy_set_header X-Forwarded-Proto $scheme; - } - } - -6-3. 証明書の自動更新を確認する - $ sudo certbot renew --dry-run - - -7. トラブルシューティング (Troubleshooting) ------------------------------------------------------------------------- - -7-1. ブラウザでゲーム画面が表示されない - ・Nginx のエラーログを確認する - $ sudo tail -50 /var/log/nginx/error.log - ・静的ファイルのパスが正しいか確認する - $ ls /opt/pixel-paint-war/apps/client/dist/index.html - -7-2. Socket.IO 接続がエラーになる - ・バックエンドコンテナが起動しているか確認する - $ docker compose -f docker-compose.prod.yml ps - ・ローカルからバックエンドに疎通できるか確認する - $ curl http://127.0.0.1:3000 - ・Nginx のプロキシ設定で WebSocket ヘッダーが正しいか確認する - -7-3. ポート 8803 にアクセスできない - ・ファイアウォールでポート 8803 が許可されているか確認する - $ sudo ufw status - ・Nginx がポート 8803 で listen しているか確認する - $ sudo ss -tlnp | grep 8803 diff --git "a/docs/01_GUIDE/GUIDE_01_\343\203\211\343\202\255\343\203\245\343\203\241\343\203\263\343\203\210\344\275\234\346\210\220\343\202\254\343\202\244\343\203\211.txt" "b/docs/01_GUIDE/GUIDE_01_\343\203\211\343\202\255\343\203\245\343\203\241\343\203\263\343\203\210\344\275\234\346\210\220\343\202\254\343\202\244\343\203\211.txt" new file mode 100644 index 0000000..e4f637b --- /dev/null +++ "b/docs/01_GUIDE/GUIDE_01_\343\203\211\343\202\255\343\203\245\343\203\241\343\203\263\343\203\210\344\275\234\346\210\220\343\202\254\343\202\244\343\203\211.txt" @@ -0,0 +1,121 @@ +======================================================================== +ドキュメント作成ガイドライン (Style Guide) +======================================================================== + +1. 基本フォーマット (Basic Format) +------------------------------------------------------------------------ +・文字コード: UTF-8 +・改行コード: LF (推奨) または CRLF +・インデント: 半角スペース4つ (4 spaces) + - タブ文字は使用せず、スペースに展開して揃える. +・ファイル命名: `GUIDE_02_ファイル命名規則.txt` を参照する. + +■ ファイルヘッダー (File Header) +・ファイルの先頭には必ずタイトルブロックを記述する. +・書式: 上下を「=」(イコール)の列(72文字程度)で挟む. +・例: + ======================================================================== + ドキュメントタイトル (English Title) + ======================================================================== + + +2. 句読点・約物 (Punctuation) +------------------------------------------------------------------------ +・句読点: 「,」(全角カンマ)と「.」(全角ピリオド)を使用する. + - 「、」「。」は使用しない. +・コロン: 半角コロン+半角スペース「: 」を使用する. + - NG: 全角コロン「:」,スペースなし「:」 +・括弧: 原則として半角括弧 `( )` を使用するが、強調や補足には全角 `( )` や `「 」` も許容する. +・注釈: 文末や段落末の補足には「※」(全角米印)+半角スペースを使用する. + - 例: ※ shared は client/server 両方から import して使用する. + + +3. 階層構造と見出し (Headings & Hierarchy) +------------------------------------------------------------------------ + +3-1. レベル1:大見出し (Section) + ・書式: 数字 + ドット + 半角スペース + タイトル + (英語タイトル) + ・装飾: 下行にハイフン「-」による区切り線を挿入する. + ・例: + 1. 基本設計 (Basic Design) + ------------------------------------------------------------------------ + +3-2. レベル2:中見出し (Subsection) + ・書式: 数字-数字 + ドット + 半角スペース + タイトル + ・例: + 1-1. 製品概要 + +3-3. レベル3:小見出し (Group Heading) + ・書式: 「■」+ 半角スペース + タイトル + ・使い分け: + - セクション内で独立したトピック(カテゴリ)を列挙する場合は「■」を使用する. + - 手順やフロー、順序のある項目を示す場合は「1. 」「2. 」を使用する. + + A. 並列・カテゴリ列挙(順序不問) + - 記号: 「■ 」(全角四角+半角スペース) + - 例: ■ フィールド仕様 + + B. 手順・優先順位・ランキング(順序重要) + - 記号: 「1. 」「2. 」(半角数字+ドット+半角スペース) + - 例: 1. ユーザ体験の理想 + +3-4. レベル4:リスト項目 (List Item) + ・記号: 「・」(全角中黒) + ・書式: 「・項目名: 内容」または「・項目名」のみ. + ・使いどころ: セクション内の主要な列挙(親項目)に使用する. + ・例: + ・タイトル: Paint War + +3-5. レベル5:詳細項目 (Detail Item) + ・記号: 「- 」(半角ハイフン+半角スペース) + ・インデント: 親項目のテキスト開始位置に合わせる(基本はスペース8つ). + ・使いどころ: 親が「・」のとき,その補足・条件・内訳を子項目として記述する. + ・ルール: 親が「・」なら子は必ず「- 」を使う. + ・例: + ・接続設定 + - host: localhost + - port: 3000 + +3-6. 特殊なナンバリング (Zero Indexing) + ・目的定義: セクションの冒頭で目的や定義を述べる場合、「X-0. 目的」というナンバリング(ゼロ始まり)を使用してもよい. + - 例: 1-0. 目的 + +3-7. 階層の順守 + ・上位レベルから下位レベルへ順に記述し,階層を飛ばさないこと. + - NG例: レベル1(1. XX)の直下にレベル3(■ XX)を記述する. + - 対策: 必要に応じてレベル2(1-1. 概要 等)を設ける. + + +4. 余白・改行ルール (Spacing) +------------------------------------------------------------------------ +・大見出しの上: 2行空ける. +・中見出し(X-X)の上: 1行空ける. +・小見出し(■や数字)の上: 1行空ける. +・セクション内のリスト: 原則として行間を詰め、まとまりごとに適宜空行を入れる. +・ミニサンプル: + 1. 基本設計 (Basic Design) + ------------------------------------------------------------------------ + + + 1-1. 製品概要 + + ■ 主要要件 + ・要件A: 説明 + ・要件B: 説明 + + ■ 補足 + ・注意点: 説明 + +・NG例(空行不足): + 1. 基本設計 (Basic Design) + ------------------------------------------------------------------------ + 1-1. 製品概要 + ■ 主要要件 + ・要件A: 説明 + + +5. 技術記述・コード表記 (Technical & Code) +------------------------------------------------------------------------ +・コマンドライン: 先頭に `$ ` を付与して区別する. +・ディレクトリ構造: ツリー記号(`├──`, `│`, `└──`)を使用し,ルートディレクトリからの階層を示す. +・インデント: コードブロック内は,親の箇条書きレベルに合わせて開始位置を揃える. \ No newline at end of file diff --git "a/docs/01_GUIDE/GUIDE_02_\343\203\225\343\202\241\343\202\244\343\203\253\345\221\275\345\220\215\350\246\217\345\211\207.txt" "b/docs/01_GUIDE/GUIDE_02_\343\203\225\343\202\241\343\202\244\343\203\253\345\221\275\345\220\215\350\246\217\345\211\207.txt" new file mode 100644 index 0000000..a8217e6 --- /dev/null +++ "b/docs/01_GUIDE/GUIDE_02_\343\203\225\343\202\241\343\202\244\343\203\253\345\221\275\345\220\215\350\246\217\345\211\207.txt" @@ -0,0 +1,54 @@ +======================================================================== +ドキュメント管理・ファイル命名規則 (File Naming Conventions) +======================================================================== + +1. 命名の基本方針 (Basic Policy) +------------------------------------------------------------------------ +プロジェクトの規模拡大に伴うファイルの散乱を防ぎ,開発メンバーおよびAI(Gemini/Copilot)がファイルの内容・文脈を即座に特定できるようにするため,以下の規則を適用する. +※ 書式・記述スタイルの基準は `GUIDE_01_ドキュメント作成ガイド.txt` を参照する. + +■ 基本フォーマット +`[カテゴリ]_[連番]_[ファイル名].txt` + +・区切り文字: アンダースコア `_` を使用する. +・連番: 01から始まる2桁の数字とする. +・拡張子: プレーンテキスト `.txt` とする. + + +2. カテゴリ定義 (Category Definitions) +------------------------------------------------------------------------ +ファイル名の先頭に付与するプレフィックス(接頭辞)定義. + +■ GUIDE_ (Guide) +・内容: チーム全体のルール,規約,運用フローなど,「メタ情報」に関する定義. +・対象例: スタイルガイド,命名規則,Git運用ルール. + +■ PLAN_ (Planning) +・内容: プロジェクトの進行計画,スケジュール,要件定義など,「管理・進行」に関する定義. +・対象例: WBS,ロードマップ,要件定義書,タスク一覧. + +■ ENV_ (Environment) +・内容: 開発環境,ディレクトリ構造,ライブラリ選定など,プロジェクトの「土台」に関する定義. +・対象例: 環境構築手順,技術スタック一覧,パッケージ構成図. + +■ SPEC_ (Specification) +・内容: 企画,ゲームルール,UI/UXなど,ユーザーから見える「仕様」に関する定義. +・対象例: ゲーム企画書,画面遷移図,パラメータ設定(マップサイズ・速度など). + +■ TECH_ (Technical) +・内容: 実装詳細,アルゴリズム,データ構造など,エンジニア向けの「技術設計」に関する定義. +・対象例: 通信プロトコル仕様,同期ロジック,データベース設計,クラス設計. + +■ TEST_ (Test) +・内容: テスト計画,テストケース,品質保証手順など,「検証・品質」に関する定義. +・対象例: 単体テスト仕様書,シナリオテスト計画,テストケース一覧,品質基準. + + +3. 運用ルール (Operational Rules) +------------------------------------------------------------------------ +・1ファイル1テーマ: + ファイルサイズが肥大化しすぎないよう,トピック(例: 通信仕様,判定ロジック)ごとにファイルを分割することを推奨する. + これにより,AIへのコンテキスト入力精度が向上する. + +・スタイルの継承: + 新規作成するファイルも,必ず `GUIDE_01_ドキュメント作成ガイド.txt` に記載された書式(見出し,句読点「,.」等)に従うこと. \ No newline at end of file diff --git "a/docs/01_GUIDE/GUIDE_03_Git\351\201\213\347\224\250\343\203\253\343\203\274\343\203\253.txt" "b/docs/01_GUIDE/GUIDE_03_Git\351\201\213\347\224\250\343\203\253\343\203\274\343\203\253.txt" new file mode 100644 index 0000000..2bff163 --- /dev/null +++ "b/docs/01_GUIDE/GUIDE_03_Git\351\201\213\347\224\250\343\203\253\343\203\274\343\203\253.txt" @@ -0,0 +1,127 @@ +======================================================================== +Git運用ルール (Git Operation Rules) +======================================================================== + +1. 基本方針 (Basic Policy) +------------------------------------------------------------------------ +チーム開発におけるコードの整合性を保ち,手戻りを防ぐために以下の運用フローを徹底する. + +・メインブランチ (main): + - 本番環境または常に動作可能な状態を維持するブランチ. + - 直接のコミット(直プッシュ)は禁止する.必ずプルリクエスト(PR)経由でマージする. +・作業ブランチ (Feature Branch): + - 機能追加やバグ修正ごとに `main` から派生させて作成する. + - 作業完了後,`main` へマージし,原則として削除する. + + +2. ブランチ命名規則 (Branch Naming) +------------------------------------------------------------------------ +2-1. プレフィックス (Prefix) +作業の種類を一目で判別するために,以下のプレフィックスを使用する. + +■ カテゴリ一覧 + ・feature/: 新機能の実装,仕様変更 + ・fix/: バグ修正 + ・refactor/: コードの整理(挙動は変えない) + ・docs/: ドキュメントの追記・修正 + ・chore/: ビルド設定やツール導入など,雑多な作業 + +2-2. 書式 (Format) + ・書式: `[プレフィックス][日付(YYMMDD)]_[名前]_[概要]` + ・区切り: スラッシュ `/` および アンダースコア `_` を使用する. + ・例: + - feature/260207_yamada_player_jump + - fix/260208_tanaka_collision_bug + - docs/260210_suzuki_guide_update + + +3. 開発フロー (Development Workflow) +------------------------------------------------------------------------ +作業を開始してからマージされるまでの手順. + +1. ローカルの最新化 + ・作業開始前は必ず `main` ブランチに切り替え,リモートの最新状態を取り込む. + ・コマンド: + $ git checkout main + $ git pull origin main + +2. 作業ブランチの作成 + ・最新の `main` から新しいブランチを作成して移動する. + ・コマンド: + $ git checkout -b feature/260214_yamada_new_function + +3. 実装とコミット + ・作業単位(意味のあるまとまり)ごとにコミットする. + ・巨大なコミットは避け,レビューしやすい粒度を心がける. + ・VS CodeでCopilotを使用している場合,AIによるコミットメッセージの生成機能(キラキラアイコン等)を利用してもよい. + ただし,生成されたメッセージは必ず「4. コミットメッセージ」の書式ルール(タグや日本語化)に合わせて修正すること. + ・コマンド: + $ git add . + $ git commit -m "[add] 新機能を実装" + +4. リモートへのプッシュ + ・作業ブランチをリモートリポジトリへ送信する. + ・コマンド: + $ git push origin feature/260214_yamada_new_function + +5. プルリクエスト (PR) の作成 + ・GitHubのリポジトリ画面上部に表示される「Compare & pull request」ボタンをクリックする. + ・Baseを `main`、Compareを自分の「作業ブランチ」に設定する. + ・「Reviewers」メニューからチームメンバーを選択し、レビューを依頼する. + ・「Create pull request」ボタンを押してPRをオープンする. + +6. レビューと修正の対応 + ・レビュワーのコメントを確認し、修正が必要な場合はローカルで修正・コミット・プッシュを繰り返す. + ・GitHub上で全ての指摘に対し「Resolve conversation」を行い、やり取りを完了させる. + ・レビュワーから「Approve(承認)」のスタンプまたはメッセージをもらう. + +7. マージの実行(マージボタンの操作) + ・PR画面下部の「Merge pull request」ボタンをクリックする. + ・確認用の「Confirm merge」ボタンを押し、`main` への統合を完了させる. + ・マージ直後に表示される「Delete branch」ボタンを押し、リモート上の作業ブランチを削除する. + +8. ローカル環境のクリーンアップ + ・マージ完了後はローカル環境も最新状態に戻し、古いブランチを削除する. + $ git checkout main + $ git pull origin main + $ git branch -d [作業ブランチ名] + + +4. コミットメッセージ (Commit Messages) +------------------------------------------------------------------------ +4-1. 書式 + ・書式: `[タグ] 内容` + ・言語: 日本語 (Japanese) + ・句読点: 末尾に句点は不要. + +4-2. タグ一覧 + ・[add]: ファイルや機能の追加 + ・[update]: 機能やデータの更新・修正 + ・[fix]: バグ修正 + ・[remove]: 削除 + ・[clean]: 整理,リファクタリング + + +5. トラブルシューティング (Troubleshooting) +------------------------------------------------------------------------ +■ コンフリクト (Conflict) が発生した場合 +他メンバーの変更と競合した場合の対処手順. + +1. main の取り込み + ・作業ブランチに `main` の最新内容をマージして競合箇所を洗い出す. + ・コマンド: + $ git checkout main + $ git pull origin main + $ git checkout feature/260214_yamada_new_function + $ git merge main + +2. 競合の解消 + ・エディタ上で `<<<<<<<`, `=======`, `>>>>>>>` で囲まれた箇所を手動で修正する. + ・修正後,再度コミットしてプッシュする. + +■ 間違えて main にコミットしてしまった場合 + ・まだプッシュしていない場合,コミットを取り消して新しいブランチへ移動させる. + ・コマンド: + $ git reset --soft HEAD^ + $ git checkout -b feature/260214_yamada_new_function + $ git commit -m "..." \ No newline at end of file diff --git "a/docs/01_GUIDE/GUIDE_04_\343\202\263\343\203\274\343\203\211\343\202\263\343\203\241\343\203\263\343\203\210\350\246\217\345\211\207.txt" "b/docs/01_GUIDE/GUIDE_04_\343\202\263\343\203\274\343\203\211\343\202\263\343\203\241\343\203\263\343\203\210\350\246\217\345\211\207.txt" new file mode 100644 index 0000000..2faa119 --- /dev/null +++ "b/docs/01_GUIDE/GUIDE_04_\343\202\263\343\203\274\343\203\211\343\202\263\343\203\241\343\203\263\343\203\210\350\246\217\345\211\207.txt" @@ -0,0 +1,124 @@ +======================================================================== +コードコメント・ドキュメント規則 (Code Comment & Documentation Guide) +======================================================================== + + +1. 基本方針 (Basic Policy) +------------------------------------------------------------------------ +コードの可読性と保守性を高めるため,ファイル・型・関数・定数それぞれに対して +適切な粒度でコメントを記述する. + +・言語: 日本語で記述する. +・句読点: 「,」(全角カンマ)を使用し,文末の句点(「.」「。」)は付けない + - 列挙が続く場合は「,」で区切る +・文体: 体言止め,または「〜する」形で統一する + + +2. コメントの種類と用途 (Comment Types) +------------------------------------------------------------------------ + +2-1. ファイルドキュメント (File Header Doc Comment) + ・ファイルの先頭に必ず記述する. + ・JSDoc形式(`/** */`)を使用する. + ・書式: + + /** + * [ファイル名(拡張子なし)] + * [ファイルの主な責務を1行で説明] + * [補足情報があれば続けて記述] + */ + + ・例: + + /** + * useJoystick + * ジョイスティック入力を受け取り,座標計算と正規化ベクトルの出力を行うフック + * UI描画に必要な中心点・ノブ位置・半径も合わせて提供する + */ + +2-2. 型・定数ドキュメント (Type & Constant Doc Comment) + ・`export` される型(`type`,`interface`)および定数(`const`)には必ず記述する. + ・JSDoc形式の1行コメント(`/** */`)を直前行に記述する. + ・書式: + + /** [その型・定数が何を表すかを端的に説明] */ + export type / const ... + + ・例: + + /** UI側と共有する最大半径の既定値 */ + export const MAX_DIST = 60; + + /** 2D座標の簡易型 */ + type Point = { x: number; y: number }; + + /** フックが返すUI向けの状態とハンドラ */ + type UseJoystickReturn = { ... }; + +2-3. 関数・コンポーネント・フックドキュメント (Function Doc Comment) + ・`export` される関数,Reactコンポーネント,フックには必ず記述する. + ・JSDoc形式の1行コメント(`/** */`)を直前行に記述する. + ・書式: + + /** [その関数・コンポーネントが何をするかを端的に説明] */ + export const / function ... + + ・例: + + /** 正規化ベクトルの出力とUI用の座標を提供するフック */ + export const useJoystick = ... + + /** ポインター入力と描画を結びつけるジョイスティックUI */ + export const Joystick = ... + +2-4. ブロックコメント (Block Comment) + ・関数・コンポーネント内で,処理のまとまりが変わる箇所に記述する. + ・通常の行コメント(`//`)を使用する. + ・書式: + + // [このブロックの処理を端的に説明] + ...処理... + + ・例: + + // 入力開始時の基準座標をセットする + const handleStart = ... + + // 入力座標からベクトルを計算し,半径でクランプして正規化出力する + const handleMove = ... + +2-5. JSXコメント (JSX Comment) + ・JSX内のブロック区切りには `{/* */}` 形式を使用する. + ・例: + + {/* 見た目のみの描画(入力は扱わない) */} + + +2-6. 再エクスポートコメント (Re-export Comment) + ・外部へ再公開する `export { ... }` には1行ドキュメントを付ける. + ・例: + + /** 入力半径の既定値を外部から参照できるように再公開 */ + export { MAX_DIST } from "./useJoystick"; + + +3. 記述しない場合の判断基準 (When to Omit) +------------------------------------------------------------------------ +・ファイル内部でのみ使用し,外部に公開されない型・関数・定数は省略してもよい +・コード自体が自明な場合(変数名で意図が十分伝わる場合)は省略してもよい +・ユニットテストファイルは,テストケース名で意図が伝わる場合は省略してもよい + + +4. NG例 (Anti-patterns) +------------------------------------------------------------------------ +・句点を付ける + - NG: /** ジョイスティックの入力を受け取る. */ + - OK: /** ジョイスティックの入力を受け取る */ + +・「、」「。」を使う + - NG: // 入力開始時の基準座標をセットする。 + - OK: // 入力開始時の基準座標をセットする + +・ファイルヘッダーを通常の行コメントで書く + - NG: // useJoystick: ジョイスティック入力を受け取るフック + - OK: /** \n * useJoystick\n * ジョイスティック入力を受け取るフック\n */ diff --git "a/docs/01_GUIDE/GUIDE_05_\343\203\227\343\203\255\343\203\210\343\202\263\343\203\253\350\277\275\345\212\240\346\211\213\351\240\206.txt" "b/docs/01_GUIDE/GUIDE_05_\343\203\227\343\203\255\343\203\210\343\202\263\343\203\253\350\277\275\345\212\240\346\211\213\351\240\206.txt" new file mode 100644 index 0000000..3104ac6 --- /dev/null +++ "b/docs/01_GUIDE/GUIDE_05_\343\203\227\343\203\255\343\203\210\343\202\263\343\203\253\350\277\275\345\212\240\346\211\213\351\240\206.txt" @@ -0,0 +1,111 @@ +======================================================================== +プロトコル追加手順 (Protocol Extension Guide) +======================================================================== + + +1. 目的 (Purpose) +------------------------------------------------------------------------ +本ドキュメントは,ソケットイベントの追加・変更時に,修正箇所の漏れを防ぐための標準手順を定義する. +`packages/shared/src/protocol` の責務分割方針に従い,イベント名,ペイロード型,方向別マップ,公開エントリを順に更新する. + + +2. 適用対象 (Scope) +------------------------------------------------------------------------ +・対象レイヤ: shared プロトコル定義(client/server 共通契約) +・対象ディレクトリ: `packages/shared/src/protocol` +・対象ユースケース: 新規イベント追加,既存イベントのペイロード変更,イベント廃止 + + +3. ディレクトリ構成 (Directory Layout) +------------------------------------------------------------------------ +・基準構成は以下とする. + + packages/shared/src/protocol/ + ├── socketEvents.ts + ├── eventPayloads.ts + ├── eventPayloadMaps.ts + ├── events.ts + ├── socketEventBridge.ts + ├── payloads/ + │ ├── commonPayloads.ts + │ ├── lobbyPayloads.ts + │ └── gamePayloads.ts + └── maps/ + ├── commonEventPayloadMap.ts + ├── lobbyEventPayloadMap.ts + └── gameEventPayloadMap.ts + + +4. 標準追加フロー (Standard Flow) +------------------------------------------------------------------------ +新規イベントを追加する場合は,必ず次の順で更新する. + +4-1. イベント名を追加する + ・ファイル: socketEvents.ts + ・作業: `SocketEvents` にイベント名を追加する + ・確認: 命名規則(kebab-case / snake_case)を既存方針に合わせる + +4-2. ペイロード型を追加する + ・ファイル: payloads/commonPayloads.ts または payloads/lobbyPayloads.ts または payloads/gamePayloads.ts + ・作業: イベントに対応する payload 型を追加する + ・確認: 既存型の再利用可否を確認し,重複定義を避ける + +4-3. 方向別マップへ対応を追加する + ・ファイル: maps/commonEventPayloadMap.ts / maps/lobbyEventPayloadMap.ts / maps/gameEventPayloadMap.ts + ・作業: 追加イベントを C→S または S→C の適切な map に追記する + ・確認: 方向が誤っていないかを必ず確認する + +4-4. 集約エントリの再公開を調整する + ・ファイル: eventPayloads.ts / eventPayloadMaps.ts / events.ts + ・作業: 外部利用が必要な型のみ再公開する + ・確認: 既存 import パス互換(`@repo/shared` 経由)を維持する + +4-5. 利用側を接続する + ・対象: client/server の handler / bridge / useCase + ・作業: on/off/emit と payload 型参照を更新する + + +5. 変更時のチェックポイント (Checklist) +------------------------------------------------------------------------ +・イベント名追加済みか +・payload 型追加済みか +・map への方向別登録済みか +・events.ts 再公開が過不足ないか +・client/server で型エラーがないか +・既存イベントの型互換を壊していないか +・player 座標差分イベント(SocketEvents.UPDATE_PLAYERS / update-players)に teamId を含めていないか +・初期同期イベント(SocketEvents.CURRENT_PLAYERS / current-players,SocketEvents.NEW_PLAYER / new-player)に teamId を含めているか + + +6. 典型ミスと対策 (Common Pitfalls) +------------------------------------------------------------------------ +■ イベント名だけ追加して map を更新しない +・症状: emit/on の型推論が崩れる,もしくは any 化する +・対策: 4-3 を必須工程として実施する + +■ payload 定義場所が不適切 +・症状: common/lobby/game の境界が曖昧になる +・対策: イベント責務に従って payloads 配下へ配置する + +■ 循環参照を作る +・症状: 型解決エラー,TS2307/TS2456 系が発生しやすくなる +・対策: `events.ts` は再公開専用とし,型本体は payload 側へ置く + + +7. 検証コマンド (Validation Commands) +------------------------------------------------------------------------ +・shared 型定義のビルド確認 + $ pnpm --filter @repo/shared build + +・サーバー互換確認 + $ pnpm --filter server build + +・クライアント互換確認 + $ pnpm --filter client build + + +8. 運用ルール (Operation Rules) +------------------------------------------------------------------------ +・プロトコル追加時は,本ガイドの 4-1 から 4-5 までを PR テンプレート上でチェックする +・events.ts に型本体を戻さない(再公開専用を維持する) +・新規型のコメントは `GUIDE_04_コードコメント規則` に従う diff --git "a/docs/02_ENV/ENV_01_\347\222\260\345\242\203\346\247\213\347\257\211\343\203\273\346\212\200\350\241\223\343\202\271\343\202\277\343\203\203\343\202\257.txt" "b/docs/02_ENV/ENV_01_\347\222\260\345\242\203\346\247\213\347\257\211\343\203\273\346\212\200\350\241\223\343\202\271\343\202\277\343\203\203\343\202\257.txt" new file mode 100644 index 0000000..5fbf76b --- /dev/null +++ "b/docs/02_ENV/ENV_01_\347\222\260\345\242\203\346\247\213\347\257\211\343\203\273\346\212\200\350\241\223\343\202\271\343\202\277\343\203\203\343\202\257.txt" @@ -0,0 +1,179 @@ +======================================================================== +Pixel Paint War - 開発環境・技術スタック定義書 +======================================================================== + +1. プロジェクト基本方針 +------------------------------------------------------------------------ + +1-1. アーキテクチャ構成: Monorepo (モノレポ) + ・目的: クライアント(Client)とサーバー(Server)で,言語(TypeScript)およびゲームロジック(移動演算・定数・型定義)を完全共有するため. + ・パッケージ管理: pnpm workspaces を採用. + +1-2. コア・コンセプト + ・言語: TypeScript (Strict mode) + ・通信: WebSocket (Socket.IO) + - 全イベントを 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. プロジェクト構成 (Project Structure) +------------------------------------------------------------------------ + +2-1. 構成一覧 + root/ + ├── .devcontainer/ + │ └── devcontainer.json # 開発コンテナ設定 + ├── apps/ + │ ├── client/ # 【演出】フロントエンド (Browser) + │ │ ├── index.html # HTMLエントリ + │ │ ├── package.json # 依存・スクリプト + │ │ ├── public/ # 公開アセット (SVG・PNG等) + │ │ ├── src/ # ※ 詳細は ENV_02 参照 + │ │ ├── tsconfig.json # TS設定 + │ │ └── vite.config.ts # Vite設定 + │ └── server/ # 【権限】バックエンド (Node.js) + │ ├── package.json # 依存・スクリプト + │ ├── tsconfig.json # TS設定 + │ └── src/ # ※ 詳細は ENV_02 参照 + ├── packages/ + │ └── shared/ # 【最重要】「真実」の定義場所(型,定数,純粋ロジック) + │ ├── package.json # 依存・公開設定 + │ ├── tsconfig.json # TS設定 + │ └── src/ # ※ 詳細は ENV_02 参照 + ├── test/ # 負荷テスト用スクリプト群 + │ ├── load-bot.ts # 負荷テスト実行 + │ ├── load-bot.constants.ts # 負荷テスト定数 + │ ├── package.json # テスト依存・スクリプト + │ └── tsconfig.json # テストTS設定 + ├── docs/ # プロジェクトドキュメント + ├── .gitignore # Git除外設定 + ├── .npmrc # pnpm設定 + ├── docker-compose.yml # 開発Compose定義 + ├── docker-compose.prod.yml # 本番Compose定義 + ├── Dockerfile # 本番イメージ定義 + ├── package.json # ワークスペース定義 + ├── pnpm-lock.yaml # lockファイル + ├── pnpm-workspace.yaml # workspace設定 + ├── CLAUDE.md # Claude Code設定 + └── README.md # プロジェクト概要 + + ※ shared は client/server 両方から import して使用する. + ※ ソースコード (src/) の詳細構造は ENV_02_ディレクトリ構造.txt を参照. + + +3. 技術スタック詳細 (Tech Stack) +------------------------------------------------------------------------ + +3-1. 共通・基盤 (Common / Shared) + ・Runtime: Node.js (v20 LTS 以上) + ・Package Manager: pnpm + ・Build Tool: tsup (高速で軽量なTypeScriptバンドラ) + +3-2. フロントエンド (Client) + ・Build Tool: Vite + ・Language: TypeScript + ・Rendering Engine: Pixi.js (v8) + - 採用理由: 50人同時対戦時の大量のスプライト描画と60fps維持のため. + ・UI Library: React 18 + @pixi/react + - 採用理由: 充実したエコシステムとPixi.jsとのReact統合による効率的なUI構築のため. + ・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/domains/game/gridMap/ による独自グリッド判定) + +3-4. 開発ツール (Dev Tools) + ・Linter: ESLint + ・Formatter: Prettier + ・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 (直接参照禁止) + +5-4. 通信境界の責務分離 + - SocketEvents の解決(イベント名の参照)は `apps/server/src/network` 配下に集約する. + - `apps/server/src/domains` 配下では `protocol` を直接 import せず,意味名の Publisher 関数を受け取って利用する. + - Socket の接続制御・受信イベント登録・切断順序制御は network 層が担当し,業務ロジック判断は domain 層が担当する. diff --git "a/docs/02_ENV/ENV_02_\343\203\207\343\202\243\343\203\254\343\202\257\343\203\210\343\203\252\346\247\213\351\200\240.txt" "b/docs/02_ENV/ENV_02_\343\203\207\343\202\243\343\203\254\343\202\257\343\203\210\343\203\252\346\247\213\351\200\240.txt" new file mode 100644 index 0000000..39991ec --- /dev/null +++ "b/docs/02_ENV/ENV_02_\343\203\207\343\202\243\343\203\254\343\202\257\343\203\210\343\203\252\346\247\213\351\200\240.txt" @@ -0,0 +1,213 @@ +======================================================================== +ソースコードディレクトリ構造 (Source Code Directory Structure) +======================================================================== + +1. 概要 (Overview) +------------------------------------------------------------------------ +本ドキュメントは apps/client/src,apps/server/src,packages/shared/src 配下の +ソースコード構造を定義する. +プロジェクト全体の構成(設定ファイル・インフラ)については ENV_01 を参照すること. + + +2. クライアント (apps/client/src) +------------------------------------------------------------------------ + +2-1. 構成一覧 + src/ + ├── app.tsx # ルートUI + ├── index.css # 全体スタイル + ├── main.tsx # 起動エントリ + ├── vite-env.d.ts # Vite型定義 + ├── assets/ # 画像素材 + ├── components/ + │ └── LandscapeOnlyGate.tsx # 横向き制御ゲート + ├── config/ + │ └── index.ts # クライアント設定 + ├── hooks/ + │ ├── useAppFlow.ts # 画面遷移フック + │ ├── useSocketSubscriptions.ts # WS購読フック + │ ├── application/ # アプリケーション層フック + │ └── types/ # フック型定義 + ├── network/ + │ ├── SocketManager.ts # WSクライアント + │ └── handlers/ + │ ├── CommonHandler.ts # 共通WSハンドラ + │ ├── GameHandler.ts # ゲームWSハンドラ + │ ├── GameSyncHandler.ts # ゲーム同期ハンドラ + │ ├── LobbyHandler.ts # ロビーWSハンドラ + │ ├── TitleHandler.ts # タイトルWSハンドラ + │ └── socketEventBridge.ts # イベントブリッジ + ├── styles/ + │ └── safeArea.ts # セーフエリア定義 + └── scenes/ + ├── game/ + │ ├── GameManager.ts # ゲーム制御 + │ ├── GameScene.tsx # ゲーム画面 + │ ├── GameView.tsx # ゲーム描画 + │ ├── application/ # ゲームアプリケーション層 + │ ├── entities/ + │ │ ├── bomb/ # 爆弾エンティティ + │ │ ├── hurricane/ # ハリケーンエンティティ + │ │ ├── map/ + │ │ │ ├── GameMapController.ts # マップ制御 + │ │ │ ├── GameMapModel.ts # マップモデル + │ │ │ └── GameMapView.ts # マップ描画 + │ │ └── player/ + │ │ ├── PlayerController.ts # プレイヤー制御 + │ │ ├── PlayerModel.ts # プレイヤーモデル + │ │ ├── PlayerRepository.ts # プレイヤーリポジトリ + │ │ └── PlayerView.ts # プレイヤー描画 + │ ├── hooks/ # ゲーム画面フック + │ ├── input/ + │ │ ├── GameInputOverlay.tsx # 入力オーバーレイ + │ │ ├── bomb/ # 爆弾ボタンUI + │ │ ├── minimap/ # ミニマップUI + │ │ ├── joystick/ + │ │ │ ├── common/ # スティック定数・型 + │ │ │ ├── model/ # スティックモデル + │ │ │ ├── hooks/ # スティック制御フック + │ │ │ └── presentation/ # スティック描画 + │ │ └── presentation/ # 入力UI共通表示 + │ ├── presentation/ # ゲームHUD + │ └── styles/ # ゲーム画面スタイル + ├── lobby/ + │ ├── LobbyScene.tsx # ロビー画面 + │ ├── components/ # モーダル・設定UI + │ ├── presentation/ # ロビー表示ロジック + │ └── styles/ # ロビースタイル + ├── result/ + │ ├── ResultScene.tsx # 結果画面 + │ ├── components/ # ランキング・統計表示 + │ ├── hooks/ # 結果画面フック + │ ├── styles/ # 結果画面スタイル + │ └── types/ # 結果画面型定義 + ├── shared/ + │ └── styles/ # シーン共通スタイル + └── title/ + └── TitleScene.tsx # タイトル画面 + +2-2. 設計方針 + ・scenes/ 配下にシーン単位(title, lobby, game, result)で分割する + ・各シーンは MVC ベースの構成とし,entities/ に描画対象を集約する + ・network/ 層がサーバーとの通信を担当し,scenes/ 内から直接 protocol を参照しない + + +3. サーバー (apps/server/src) +------------------------------------------------------------------------ + +3-1. 構成一覧 + src/ + ├── index.ts # サーバー起点 + ├── application/ + │ └── coordinators/ # アプリ統合制御 + ├── common/ # 共通ユーティリティ + ├── config/ # サーバー設定 + ├── logging/ + │ ├── logger.ts # ログ出力 + │ ├── constants/ # ログ定数 + │ └── contracts/ # ログ契約型 + ├── domains/ + │ ├── game/ + │ │ ├── GameManager.ts # ゲーム状態管理 + │ │ ├── application/ + │ │ │ ├── ports/ + │ │ │ │ └── gameUseCasePorts.ts # ユースケース入出力境界 + │ │ │ ├── services/ + │ │ │ │ ├── GameSessionLifecycleService.ts # セッション管理 + │ │ │ │ ├── GamePlayerOperationService.ts # プレイヤー操作 + │ │ │ │ ├── TeamAssignmentService.ts # チーム割当 + │ │ │ │ ├── gameResultCalculator.ts # 結果算出 + │ │ │ │ └── bot/ # Bot AIシステム + │ │ │ └── useCases/ # ゲームユースケース + │ │ ├── entities/ + │ │ │ ├── bomb/ # 爆弾エンティティ + │ │ │ ├── map/ + │ │ │ │ └── MapStore.ts # マップ状態保持 + │ │ │ └── player/ + │ │ │ └── Player.ts # サーバーPlayer + │ │ └── loop/ + │ │ ├── GameLoop.ts # 固定ループ (20Hz) + │ │ ├── HurricaneSystem.ts # ハリケーン制御 + │ │ └── hurricane/ # ハリケーン詳細処理 + │ └── room/ + │ ├── RoomManager.ts # ルーム管理 + │ └── application/ + │ ├── ports/ + │ │ └── roomUseCasePorts.ts # ユースケース入出力境界 + │ ├── services/ # ルームサービス群 + │ └── useCases/ # ルームユースケース + └── network/ + ├── SocketManager.ts # WS接続管理 + ├── adapters/ + │ └── socketEmitters.ts # 送信アダプタ + ├── handlers/ + │ ├── CommonHandler.ts # 共通WSハンドラ + │ ├── game/ + │ │ └── registerGameHandlers.ts # ゲーム受信イベント配線 + │ └── room/ + │ └── registerRoomHandlers.ts # ルーム受信イベント配線 + ├── bootstrap/ + │ ├── boot.ts # 起動配線 + │ ├── createHttpServer.ts # HTTP生成 + │ ├── createIo.ts # Socket.IO生成 + │ └── createServerRuntime.ts # ランタイム生成 + ├── types/ # ネットワーク型定義 + └── validation/ # ペイロード検証 + +3-2. 設計方針 + ・domains/ にビジネスロジックを集約し,game/ と room/ に分離する + ・network/ 層が Socket.IO の接続管理・イベント配線を担当する + ・domains/ は protocol を直接参照せず,ports/ 経由で network 層と連携する + ・loop/ 配下にサーバーティック(20Hz)とハリケーンシステムを配置する + + +4. 共有パッケージ (packages/shared/src) +------------------------------------------------------------------------ + +4-1. 構成一覧 + src/ + ├── index.ts # 共有エクスポート + ├── config/ + │ ├── index.ts # 設定エクスポート + │ ├── gameConfig.ts # 共通定数 + │ ├── networkConfig.ts # 通信設定 + │ └── teamValidators.ts # チーム検証 + ├── domains/ + │ ├── app/ + │ │ ├── app.const.ts # アプリ定数 + │ │ └── app.type.ts # アプリ型 + │ ├── game/ + │ │ ├── aoi/ # 視認範囲 (Area of Interest) + │ │ ├── bombHit/ # 爆弾判定ロジック + │ │ ├── gridMap/ + │ │ │ ├── gridMap.logic.ts # マップ計算 + │ │ │ └── gridMap.type.ts # マップ型定義 + │ │ ├── player/ + │ │ │ └── player.type.ts # プレイヤー型 + │ │ └── tick/ # ティックシステム + │ └── room/ + │ ├── room.const.ts # ルーム定数 + │ └── room.type.ts # ルーム型 + └── protocol/ + ├── socketEvents.ts # イベント名定義 + ├── eventPayloads.ts # ペイロード再公開 + ├── eventPayloadMaps.ts # 型マッピング + ├── socketEventBridge.ts # 型安全ブリッジ + ├── events.ts # イベント再公開 + ├── bombIdentity.ts # 爆弾一意性保証 + ├── payloads/ + │ ├── commonPayloads.ts # 共通ペイロード型 + │ ├── gamePayloads.ts # ゲームペイロード型 + │ ├── lobbyPayloads.ts # ロビーペイロード型 + │ └── playerHitEffectPayloads.ts # ヒットエフェクト型 + └── maps/ + ├── commonEventPayloadMap.ts # 共通イベントマップ + ├── gameEventPayloadMap.ts # ゲームイベントマップ + └── lobbyEventPayloadMap.ts # ロビーイベントマップ + +4-2. 設計方針 + ・client と server の両方から import される「真実の定義場所」として機能する + ・config/ にゲーム定数・通信設定を集約する + ・domains/ にドメインロジック(移動計算・マップ・判定)を配置する + ・protocol/ にソケットイベント定義・ペイロード型・型マッピングを一元管理する + ・protocol/events.ts は再公開専用とし,型本体を置かない(GUIDE_05 参照) diff --git "a/docs/02_ENV/ENV_03_\347\256\241\347\220\206\350\200\205\347\224\250\347\222\260\345\242\203\346\247\213\347\257\211\346\211\213\351\240\206.txt" "b/docs/02_ENV/ENV_03_\347\256\241\347\220\206\350\200\205\347\224\250\347\222\260\345\242\203\346\247\213\347\257\211\346\211\213\351\240\206.txt" new file mode 100644 index 0000000..3b39784 --- /dev/null +++ "b/docs/02_ENV/ENV_03_\347\256\241\347\220\206\350\200\205\347\224\250\347\222\260\345\242\203\346\247\213\347\257\211\346\211\213\351\240\206.txt" @@ -0,0 +1,346 @@ +======================================================================== +Pixel Paint War - 管理者用環境構築手順 (Admin Setup Guide) +======================================================================== + +1. はじめに (Introduction) +------------------------------------------------------------------------ + 本ドキュメントは,プロジェクトを「ゼロから新規作成・再構築する管理者」向けの + Monorepo構成およびDocker環境の構築ログである. + ※ 一般の開発メンバー(Git Cloneして参加する人)は本ドキュメントを実施不要である. + +2. 管理者用事前準備 (Prerequisites for Admin) +------------------------------------------------------------------------ + +2-1. プロジェクト作成用ツールのインストール + 1. Node.js (v20.x LTS) + ・Nodesource リポジトリを使用してインストールする. + + # リポジトリのセットアップとインストール + $ curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash - + $ sudo apt-get install -y nodejs + + ・確認コマンド: + $ node -v # v20.x.x と表示されること + + 2. pnpm (Package Manager) + ・Node.js 標準の npm ではなく pnpm を使用する. + ・Corepack (Node.js同梱) を有効化してインストールする. + $ sudo corepack enable + $ corepack prepare pnpm@latest --activate + + ・確認コマンド: + $ pnpm -v + + +3. 新規プロジェクト構築 (Project Initialization) +------------------------------------------------------------------------ + +3-1. プロジェクト初期化 + 1. ディレクトリ作成 + $ mkdir SkillSemiWebGame + $ cd SkillSemiWebGame + + 2. Git/pnpm 初期化 + $ git init + $ pnpm init + +3-2. Monorepo構成設定 + 1. pnpm-workspace.yaml 作成 + ルート直下に作成し、以下を記述する. + packages: + - 'apps/*' + - 'packages/*' + + 2. .npmrc 作成 + ルート直下に作成し、以下を記述する. + shamefully-hoist=true + +3-3. ディレクトリ構造の構築 + 以下の構成になるようにディレクトリを作成する. + + root/ + ├── apps/ + │ ├── client/ # フロントエンド (Browser) + │ └── server/ # バックエンド (Node.js) + └── packages/ + └── shared/ # 共通ロジック (Shared Library) + + ・作成コマンド例: + $ mkdir -p apps/client apps/server packages/shared + +3-4. Git除外設定 (.gitignore) + ルート直下に `.gitignore` を作成し、以下を記述する. + + node_modules/ + .pnpm-store/ + dist/ + build/ + .env + .DS_Store + .vscode/* + !.vscode/extensions.json + !.vscode/launch.json + coverage/ + !packages/ + + +4. アプリケーション雛形の作成 (Scaffolding) +------------------------------------------------------------------------ + +4-1. 共通ライブラリ (packages/shared) + 1. 初期化とビルドツール導入 + $ cd packages/shared + $ pnpm init + $ pnpm add -D typescript tsup + + 2. 設定ファイルの調整 (package.json) + ・name: "@repo/shared" と命名する(推奨). + ・main: "./dist/index.js", types: "./dist/index.d.ts" を指定する. + ・scripts: "build": "tsup src/index.ts --format cjs,esm --dts" を追加する. + + 3. エントリーポイントの作成 + $ mkdir src + $ touch src/index.ts + ※ (例: export * from './constants';) + + 4. TypeScript設定ファイルの作成 (tsconfig.json) + ・ファイル: packages/shared/tsconfig.json + ・内容: + { + "compilerOptions": { + "target": "ES2020", + "module": "ESNext", + "moduleResolution": "Bundler", + "lib": ["ES2020", "DOM", "DOM.Iterable"], + "declaration": true, + "declarationMap": true, + "sourceMap": true, + "outDir": "./dist", + "rootDir": "./src", + "strict": true, + "esModuleInterop": true, + "skipLibCheck": true, + "forceConsistentCasingInFileNames": true + }, + "include": ["src/**/*"], + "exclude": ["node_modules", "dist"] + } + +4-2. フロントエンド (apps/client) + 1. プロジェクト作成 + $ cd ../../apps/client + $ pnpm create vite . --template preact-ts + ※ Use rolldown-vite? » No + ※ Install with pnpm and start now? » No + + 2. 依存ライブラリのインストール + $ pnpm add pixi.js + $ pnpm add @repo/shared --workspace + +4-3. バックエンド (apps/server) + 1. 初期化 + $ cd ../../apps/server + $ pnpm init + + 2. 依存ライブラリのインストール + $ pnpm add ws + $ pnpm add -D tsx typescript @types/node @types/ws + $ pnpm add @repo/shared --workspace + + 3. サーバー用ディレクトリとファイルの作成 + $ mkdir src + $ touch src/index.ts + + 4. 実行スクリプトの定義 (package.json) + "scripts": { + "dev": "tsx watch src/index.ts" + } + + 5. TypeScript設定ファイルの作成 (tsconfig.json) + ・ファイル: apps/server/tsconfig.json + ・内容: + { + "compilerOptions": { + "target": "ES2022", + "module": "NodeNext", + "moduleResolution": "NodeNext", + "lib": ["ES2022"], + "strict": true, + "noEmit": true, + "esModuleInterop": true, + "skipLibCheck": true, + "forceConsistentCasingInFileNames": true, + "baseUrl": ".", + "paths": { + "@repo/shared": ["../../packages/shared/src/index.ts"] + } + }, + "include": ["src/**/*"], + "exclude": ["node_modules"] + } + +4-4. 初回コミット (Initial Commit) + 1. ルートに戻る + $ cd ../.. + 2. ステータスの確認 (node_modulesが含まれていないこと) + $ git status + 3. Gitへ保存 + $ git add . + $ git commit -m "chore: Initialize project structure and dependencies" + + +5. Docker環境定義ファイルの作成 (Configuration) +------------------------------------------------------------------------ + +5-1. Dockerfile の作成 + プロジェクトルートに `Dockerfile` を作成する. + ※ Node.js v20 をベースとし,pnpm を有効化した開発用イメージ定義. + + FROM node:20-slim + + # pnpmの準備 + ENV PNPM_HOME="/pnpm" + ENV PATH="$PNPM_HOME:$PATH" + RUN corepack enable + + # 作業ディレクトリ設定 + WORKDIR /workspace + + # 依存関係のコピーとインストール (キャッシュ活用) + COPY . . + RUN pnpm install + + # ポート公開 (Vite:5173, Server:3000) + EXPOSE 5173 3000 + + # デフォルトコマンド (docker-composeで上書きするため待機) + CMD ["sleep", "infinity"] + +5-2. docker-compose.yml の作成 (開発用) + プロジェクトルートに `docker-compose.yml` を作成する. + ※ ローカルのソースコードをコンテナにマウントする設定. + + version: "3.8" + + services: + app: + container_name: pixel-paint-war-dev + # 開発用イメージ: Node.js v20 (定義書準拠) + image: mcr.microsoft.com/devcontainers/typescript-node:20 + + # 永続化とボリュームマウント + volumes: + # カレントディレクトリをコンテナ内の /workspace にマウント + - .:/workspace:cached + # 【重要】node_modules をホスト側と切り離して高速化・安定化させる設定 + - node_modules:/workspace/node_modules + + # コマンドの上書き (コンテナを常時起動させる) + command: sleep infinity + + # ネットワーク設定 + # Client(5173) と Server(3000) のポートを開放 + ports: + - "5173:5173" + - "3000:3000" + + # 環境変数 + environment: + - NODE_ENV=development + + # ユーザー権限 (Nodeイメージ推奨のユーザー) + user: node + + volumes: + node_modules: + +5-3. .devcontainer 設定の作成 + 1. ディレクトリ作成 + $ mkdir .devcontainer + + 2. .devcontainer/devcontainer.json 作成 + VS Codeがコンテナを認識するための設定. + + { + "name": "Pixel Paint War Dev", + "dockerComposeFile": "../docker-compose.yml", + "service": "app", + "workspaceFolder": "/workspace", + + "features": { + "ghcr.io/devcontainers/features/node:1": { + "version": "20", + "pnpm": "latest" + } + }, + + "customizations": { + "vscode": { + "extensions": [ + "dbaeumer.vscode-eslint", + "esbenp.prettier-vscode", + "editorconfig.editorconfig", + "ms-vscode.hexeditor", + "github.copilot", + "github.copilot-chat" + ], + "settings": { + "editor.formatOnSave": true, + "editor.defaultFormatter": "esbenp.prettier-vscode" + } + } + }, + + // コンテナ起動後の初期化コマンド + // 1. sudo chown ... : node_modules の所有権を node ユーザーに強制変更 + // 2. pnpm install : その後,安全にインストールを実行 + // 3. build : 最後に共通パッケージをビルド + "postCreateCommand": "sudo chown -R node:node /workspace/node_modules && pnpm install && pnpm --filter @repo/shared build", + + // コンテナ内のユーザー + "remoteUser": "node" + } + +5-4. docker-compose.prod.yml の作成 (本番確認用) + プロジェクトルートに `docker-compose.prod.yml` を作成する. + ※ 本番ビルド確認用にポートをずらし、ビルドコマンドを実行する設定. + + services: + app: + build: . + ports: + - "3001:3000" + environment: + - NODE_ENV=production + command: pnpm start + + +6. 本番デプロイ構成の補足 (Deployment Config) +------------------------------------------------------------------------ +本番環境へデプロイする際は,上記 `Dockerfile` をマルチステージビルドに修正し, +軽量化を図ることが推奨される. + +6-1. Dockerfile (本番用最適化例) + ※ 必要に応じて `Dockerfile.prod` として作成する. + + FROM node:20-slim AS base + ENV PNPM_HOME="/pnpm" + ENV PATH="$PNPM_HOME:$PATH" + RUN corepack enable + COPY . /app + WORKDIR /app + + FROM base AS prod-deps + RUN --mount=type=cache,id=pnpm,target=/pnpm/store pnpm install --prod --frozen-lockfile + + FROM base AS build + RUN --mount=type=cache,id=pnpm,target=/pnpm/store pnpm install --frozen-lockfile + RUN pnpm run build + + FROM base + COPY --from=prod-deps /app/node_modules /app/node_modules + COPY --from=build /app/apps/server/dist /app/apps/server/dist + COPY --from=build /app/apps/client/dist /app/apps/client/dist + + EXPOSE 3000 + CMD [ "pnpm", "start" ] \ No newline at end of file diff --git "a/docs/02_ENV/ENV_04_\347\222\260\345\242\203\346\247\213\347\257\211\346\211\213\351\240\206\346\233\270.txt" "b/docs/02_ENV/ENV_04_\347\222\260\345\242\203\346\247\213\347\257\211\346\211\213\351\240\206\346\233\270.txt" new file mode 100644 index 0000000..eb01c3b --- /dev/null +++ "b/docs/02_ENV/ENV_04_\347\222\260\345\242\203\346\247\213\347\257\211\346\211\213\351\240\206\346\233\270.txt" @@ -0,0 +1,246 @@ +======================================================================== +Pixel Paint War - 開発環境利用ガイド (Development Environment Guide) +======================================================================== + +1. 事前準備 (Prerequisites) +------------------------------------------------------------------------ + +1-1. 目的 + 本ドキュメントは,「Pixel Paint War」の開発に参加する全メンバー向けの + 環境構築および利用ガイドである. + Monorepo構成とDocker(Dev Containers)を使用し,迅速に開発を開始する手順を記す. + +1-2. 【全員必須】 共通ツールのインストール + 開発メンバー全員(管理者・参加者問わず)が以下のツールをインストールする. + + 1. Docker Engine (Linux環境) + ・開発環境の実体(コンテナ)を動かすために必須である. + + ・インストール手順 (Ubuntu/Debian系の例): + ターミナルで以下のコマンドを順に実行する. + + # 1. 公式GPG鍵とリポジトリのセットアップ + sudo apt-get update + sudo apt-get install -y ca-certificates curl gnupg + sudo install -m 0755 -d /etc/apt/keyrings + curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg + sudo chmod a+r /etc/apt/keyrings/docker.gpg + + echo \ + "deb [arch="$(dpkg --print-architecture)" signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \ + "$(. /etc/os-release && echo "$VERSION_CODENAME")" stable" | \ + sudo tee /etc/apt/sources.list.d/docker.list > /dev/null + + # 2. パッケージのインストール + sudo apt-get update + sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin + + # 3. ユーザー権限の設定 (重要: VS Codeからsudoなしで利用するために必須) + sudo usermod -aG docker $USER + newgrp docker + + ・確認コマンド: + $ docker -v + # Docker version 20.x.x 等と表示されること + + 2. VS Code (Visual Studio Code) + ・メインのエディタとして使用する.最新版をインストールすること. + + 3. VS Code 拡張機能: "Dev Containers" + ・ID: ms-vscode-remote.remote-containers + ・拡張機能マーケットプレイスで検索し、インストールする. + ・これを入れることで、Dockerコンテナ内でVS Codeを開くことが可能になる. + + +2. 環境セットアップ (Setup) +------------------------------------------------------------------------ + + ■ リポジトリのクローン + 1. ソースコードの取得 + 任意のディレクトリで以下のコマンドを実行する. + $ git clone + + 2. ディレクトリ移動 + $ cd SkillSemiWebGame + + 3. 完了 + これだけで準備は完了である. + パッケージのインストール等はDocker起動時に自動で行われるため、 + 手動での `pnpm install` 等は不要である. + + +3. 開発環境(Dev Container)の起動 (Launch) +------------------------------------------------------------------------ + +3-1. プロジェクトを開く + 1. VS Codeを起動し,「ファイル > フォルダを開く」からプロジェクトルートを選択する. + +3-2. コンテナでの再起動 (Reopen in Container) + 以下のいずれかの方法で,開発環境をコンテナ内に移行する. + + 【方法A: ステータスバーから】 + 1. ウィンドウ左下の緑色(または青色)の「><」アイコンをクリックする. + 2. 表示されるメニューから「Reopen in Container」を選択する. + + 【方法B: コマンドパレットから】 + 1. [F1] または [Ctrl+Shift+P] を押下する. + 2. "Reopen" と入力し,「Dev Containers: Reopen in Container」を選択する. + + ※ トラブルシューティング: + もし起動後に node_modules が見つからない等のエラーが出た場合は, + 「Reopen」ではなく「Dev Containers: Rebuild Container」を選択して + 環境を完全に作り直してください. + +3-3. 初回ビルドの待機 + 1. 初回起動時は Dockerイメージのビルドと npmパッケージのインストールが行われる. + (数分〜十数分かかる場合がある) + 2. 右下に "Starting Dev Container" 等の通知が表示されている間は待機する. + +3-4. 起動確認 + 1. 左下のアイコンが「Dev Container: Pixel Paint War Dev」と表示されていることを確認する. + 2. VS Codeのターミナルを開き (`Ctrl + @`),パスを確認する. + + 成功例: node@...:/workspace$ + (Windowsのパス C:\Users... ではなく Linux形式になっていれば成功) + + 3. 動作確認コマンドを実行する. + $ pnpm --filter client dev + + ※ エラー時の対応: + 「sh: vite: not found」等のエラーが出る場合は,自動インストールが完了していない可能性があります. + ターミナルで `pnpm install` を手動実行するか,上記 3-2 の「Rebuild Container」を試してください. + + ・ブラウザでの確認: + ターミナルに「➜ Local: http://localhost:5173/」と表示されたら, + Google Chrome等のブラウザを開き,アドレスバーに上記URLを貼り付けて実行する. + + ・正常動作の判断基準: + 画面に「Vite + Preact」のロゴと「Vite + Preact + TypeScript」といった + テキストが表示されていれば,フロントエンドの環境構築は成功である. + + +4. 開発ツールの確認 (Tools Verification) +------------------------------------------------------------------------ +Dockerコンテナ起動完了後、定義済みのツールが正しく自動導入されているか確認する. +※ 手動でのインストールは不要である. + +4-1. VS Code 拡張機能 + 拡張機能サイドバーを開き、"Dev Container: Pixel Paint War Dev" セクションに + 以下がインストール済みであることを確認する. + ・ESLint + ・Prettier - Code formatter + ・EditorConfig for VS Code + ・Hex Editor + ・GitHub Copilot + +4-2. AI アシスタント設定 + GitHub Copilot Pro + - VS Code 右下のアイコンから、GitHubアカウントへのログイン状態を確認する. + + +5. 構成確認 (Project Structure) +------------------------------------------------------------------------ + +5-1. ディレクトリ構成 + コンテナ内で以下のディレクトリ構造が見えていることを確認する. + + SkillSemiWebGame/ <-- プロジェクトルート + ├── .devcontainer/ <-- Docker設定 + ├── .git/ + ├── docker-compose.yml <-- Docker構成 + ├── package.json <-- ルート定義 + ├── pnpm-workspace.yaml <-- ワークスペース定義 + ├── node_modules/ <-- 依存ライブラリ + │ + ├── apps/ <-- アプリケーション格納用 + │ ├── client/ <-- フロントエンド (Vite + Preact) + │ │ ├── src/ + │ │ │ ├── main.tsx + │ │ │ └── ... + │ │ ├── package.json <-- pixi.js, @repo/shared 依存あり + │ │ └── vite.config.ts + │ │ + │ └── server/ <-- バックエンド (Node.js) + │ ├── src/ + │ │ └── index.ts <-- エントリーポイント + │ └── package.json <-- ws, @repo/shared 依存あり + │ + └── packages/ <-- 共通パッケージ格納用 + └── shared/ <-- 共通ロジック + ├── dist/ <-- ビルド成果物 + ├── src/ + │ └── index.ts + └── package.json + +6. 動作確認 (Verification) +------------------------------------------------------------------------ + +6-1. ビルド確認 + ※ 注意: 以下のコマンドは全て「Dev Container内のターミナル」で実行すること. + + $ pnpm --filter @repo/shared build + ※ shared のビルドが成功することを確認する. + +6-2. 開発サーバー起動 + モノレポ構成のため,個別のディレクトリに移動せず,プロジェクトルートから + --filter オプションを使用して各アプリを起動する. + ※ ターミナルを2つ開き,両方を同時に起動した状態で開発を進めることを推奨. + + 1.Client (フロントエンド) の動作確認 + ・ルートディレクトリにて以下のコマンドを実行する. + $ pnpm --filter client dev + + ・ブラウザでの確認: + ターミナルに「➜ Local: http://localhost:5173/」と表示されたら, + Google Chrome等のブラウザを開き,アドレスバーに上記URLを貼り付けて実行する. + + ・正常動作の判断基準: + 画面に「Vite + Preact」のロゴと「Vite + Preact + TypeScript」といった + テキストが表示されていれば,フロントエンドの環境構築は成功である. + + 2. Server (バックエンド) の動作確認 + ・テスト用コードの作成: + 動作確認用のエントリーポイントを作成する. + $ touch apps/server/src/index.ts + + ファイルに以下の内容を記述する. + console.log("Server is running!"); + + ・コマンド: + $ pnpm --filter server dev + + ・正常動作の判断基準: + ターミナルに「Server is running!」と出力されれば構築成功である. + + 3.終了方法 (重要) + ・動作確認を終了し,開発サーバーを停止させる場合は,ターミナル上で + 「Ctrl + C」を押下する. + + +7. (応用) 本番ビルドの動作確認 (Production Build Check) +------------------------------------------------------------------------ +開発環境(Dev Container)ではなく,本番環境と同様のDockerイメージを作成し, +正しくビルド・起動できるかを確認する手順である. +「機能開発が終わった後」や「プルリクエストを出す前」に実施することを推奨する. + +7-1. 準備 + Dev Containerを閉じ,ホストOS(Windows/Mac)のターミナルを開く. + ※ Dev Container内からはDockerコマンドが使用できない場合があるため. + +7-2. ビルドと起動 + プロジェクトルートで以下のコマンドを実行する. + + $ docker compose -f docker-compose.prod.yml up -d --build + +7-3. 動作確認 + 1. ログ確認 + $ docker compose -f docker-compose.prod.yml logs -f + Serverが起動していることを確認する. + + 2. ブラウザ確認 + http://localhost:3001 + ※ ポート番号が開発用(3000/5173)と異なり 3001 に設定されている点に注意. + +7-4. 終了と削除 + 確認が終わったら必ず環境を停止・削除する. + $ docker compose -f docker-compose.prod.yml down \ No newline at end of file diff --git "a/docs/02_ENV/ENV_05_Docker\351\201\213\347\224\250\346\223\215\344\275\234\343\202\254\343\202\244\343\203\211.txt" "b/docs/02_ENV/ENV_05_Docker\351\201\213\347\224\250\346\223\215\344\275\234\343\202\254\343\202\244\343\203\211.txt" new file mode 100644 index 0000000..be89f13 --- /dev/null +++ "b/docs/02_ENV/ENV_05_Docker\351\201\213\347\224\250\346\223\215\344\275\234\343\202\254\343\202\244\343\203\211.txt" @@ -0,0 +1,82 @@ +======================================================================== +Docker 運用・操作ガイド (Docker Operations Guide) +======================================================================== + +1. 目的 (Objective) +------------------------------------------------------------------------ +本ドキュメントは,Pixel Paint War プロジェクトにおける Docker の日常的な +操作コマンドと,トラブルシューティング手順をまとめたものである. +本プロジェクトでは「開発環境」と「本番環境」で異なる運用を行う. + + +2. 開発環境 (Development Environment) +------------------------------------------------------------------------ +VS Code の Dev Containers 機能を使用する. + +2-1. +基本操作 + ・起動: VS Code でプロジェクトを開き,「Reopen in Container」を実行する. + ・停止: VS Code を閉じる(自動的に停止する). + ・ターミナル: VS Code 内のターミナルを使用する. + +2-2. +コンテナの再構築 (Rebuild) + 依存関係の不整合や設定変更が反映されない場合に実行する. + 1. コマンドパレット (F1) を開く. + 2. 「Dev Containers: Rebuild Container」を選択する. + 3. キャッシュを無視したい場合は「Rebuild Without Cache」を選択する. + + +3. 本番環境 (Production Environment) +------------------------------------------------------------------------ +手動で Docker Compose コマンドを実行する. +※ 必ず WSL (Windows) または ホストOSのターミナルで実行すること. + +3-1. +基本コマンド + ■ 起動 (ビルド込み) + $ docker compose -f docker-compose.prod.yml up -d --build + + ■ 状態確認 + $ docker compose -f docker-compose.prod.yml ps + + ■ ログ確認 (リアルタイム) + $ docker compose -f docker-compose.prod.yml logs -f + + ■ 停止 + $ docker compose -f docker-compose.prod.yml down + +3-2. +ポート仕様 + ・ホスト側ポート: 3001 + ・コンテナ内ポート: 3000 + ・接続確認URL: http://localhost:3001 + ※ 開発用コンテナ (Port 3000) との衝突を避けるため,3001番を使用する. + + +4. トラブルシューティング (Troubleshooting) +------------------------------------------------------------------------ + +4-1. +ビルドエラー・反映漏れへの対処 + 修正したコードが反映されない,または原因不明のエラーが出る場合, + キャッシュを使わずに強制的に再ビルドを行う. + + $ docker compose -f docker-compose.prod.yml build --no-cache + $ docker compose -f docker-compose.prod.yml up -d --force-recreate + +4-2. +モジュールが見つからない (MODULE_NOT_FOUND) + 本番起動時に `ws` 等が見つからないエラーが出る場合,`Dockerfile` の + COPY記述を確認する.pnpm のシンボリックリンク構造に対応するため, + 以下が記述されている必要がある. + + COPY --from=builder /app/apps/server/node_modules ./apps/server/node_modules + +4-3. +再起動ループ (Restarting) + `docker ps` でステータスが `Restarting` になる場合,サーバープロセスが + クラッシュまたは終了している. + 1. ログを確認する: + $ docker compose -f docker-compose.prod.yml logs --tail=50 + 2. コード修正後,4-1 の手順で再デプロイする. \ No newline at end of file diff --git "a/docs/02_ENV/ENV_06_\343\203\206\343\202\271\343\203\210\346\223\215\344\275\234\346\211\213\351\240\206.txt" "b/docs/02_ENV/ENV_06_\343\203\206\343\202\271\343\203\210\346\223\215\344\275\234\346\211\213\351\240\206.txt" new file mode 100644 index 0000000..4a15b02 --- /dev/null +++ "b/docs/02_ENV/ENV_06_\343\203\206\343\202\271\343\203\210\346\223\215\344\275\234\346\211\213\351\240\206.txt" @@ -0,0 +1,96 @@ +======================================================================== +テスト操作手順 (Test Operation Guide) +======================================================================== + + +1. 概要 (Overview) +------------------------------------------------------------------------ +本ドキュメントは,プロジェクト内のテスト関連ファイルの実行方法を整理し,チーム内で共通の運用手順を共有することを目的とする. + + +1-1. 対象範囲 + +■ 対象ファイル +・テスト実行用スクリプト: /workspace/test/load-bot.ts +・テスト用依存定義: /workspace/test/package.json + +■ 対象外 +・アプリ本体のビルドと起動手順 +・本番運用の監視設定 + + +2. 前提条件 (Prerequisites) +------------------------------------------------------------------------ + +2-1. 環境 +・Node.js / pnpm が利用可能であること +・インターネット接続が利用可能であること + +2-2. 設定値 +■ 接続先URL +・既定値: https://skillsemiwebgame.onrender.com +・変更方法: コマンドライン引数(--dev)または定数を編集する + + +3. 実行手順 (Execution Steps) +------------------------------------------------------------------------ + +3-1. 初回準備 +1. テスト用ディレクトリへ移動 + - コマンド: $ cd /workspace/test +2. 依存関係のインストール + - コマンド: $ pnpm install + +3-2. 実行 + - コマンド: $ pnpm start + - 開発環境に接続する場合: $ pnpm start -- --dev + + +4. パラメータ一覧 (Parameters) +------------------------------------------------------------------------ +4-1. コマンドライン引数 + ・--dev: 開発環境(DEV_SERVER_URL)に接続する + +4-2. 定数 (load-bot.constants.ts) + ・URL: 本番サーバURL + ・DEV_URL: 開発サーバURL + ・BOTS: 同時接続数 + ・DURATION_MS: 実行時間 (ms)。0以下またはInfinityで無期限 + ・JOIN_DELAY_MS: 参加間隔 (ms) + ・MOVE_TICK_MS: 移動送信間隔 (ms) + ・BOT_SPEED: 移動速度 + ・BOT_RADIUS: プレイヤー半径 + ・BOT_CAN_MOVE: ボット移動の有効化 (true/false) + ・START_DELAY_MS: 開始遅延 (ms) + ・MAX_X: X座標上限 + ・MAX_Y: Y座標上限 + ・ROOM_ID: ルームID + ・START_GAME: ゲーム開始の有効化 (true/false) + ・SOCKET_PATH: Socket.IOのパス + ・SOCKET_TRANSPORTS: Socket.IOのトランスポート + + +5. 出力と終了 (Output & Termination) +------------------------------------------------------------------------ + +5-1. 標準出力 + ・開始時に設定値が出力される + ・終了時に簡易統計 (接続数など) が出力される + +5-2. 終了方法 + ・指定時間経過後に自動終了する + ・途中終了する場合はプロセスを終了する + + +6. 注意事項 (Notes) +------------------------------------------------------------------------ + +6-1. 本番サーバへの負荷 + ・負荷テストは低負荷から段階的に実施すること + ・必要に応じて管理者へ事前連絡を行うこと + +6-2. 依存関係 + ・test配下は独立した依存関係を持つため,別途pnpm installが必要になる + +6-3. 計測の限界 + ・本スクリプトは簡易負荷確認用であり,詳細な計測は専用ツールの利用を推奨する diff --git "a/docs/02_ENV/ENV_07_\343\202\271\343\203\236\343\203\233\345\256\237\346\251\237\343\203\207\343\203\220\343\203\203\343\202\260\346\211\213\351\240\206.txt" "b/docs/02_ENV/ENV_07_\343\202\271\343\203\236\343\203\233\345\256\237\346\251\237\343\203\207\343\203\220\343\203\203\343\202\260\346\211\213\351\240\206.txt" new file mode 100644 index 0000000..06c1f56 --- /dev/null +++ "b/docs/02_ENV/ENV_07_\343\202\271\343\203\236\343\203\233\345\256\237\346\251\237\343\203\207\343\203\220\343\203\203\343\202\260\346\211\213\351\240\206.txt" @@ -0,0 +1,122 @@ +======================================================================== +スマホ実機デバッグ手順 (Smartphone Debugging Guide) +======================================================================== + + +1. 概要 (Overview) +------------------------------------------------------------------------ + +1-0. 目的 + 本ドキュメントは,開発中のWebゲーム「Pixel Paint War」をスマホ実機で動作 + 確認するための手順書である. + 学校や組織のネットワーク(Fortinet等)による制限や,WSL2特有のネットワー + クの壁を回避するため,トンネリングツール「ngrok」を使用した外部公開手順 + を採用する. + +1-1. 前提条件 + ・WSL2 (Ubuntu等) 上で開発環境が構築済みであること. + ・ngrok の公式サイトでアカウント作成済みであること. + ・Authtoken (認証トークン) が取得済みであること. + + +2. ngrokのインストール (Installation) +------------------------------------------------------------------------ +Linux (WSL2) 環境へのインストール手順を記述する. +※ apt パッケージマネージャ経由ではエラーが発生しやすいため,バイナリ直接 +インストール方式を採用する. + +2-1. ダウンロードと配置 + 1. 圧縮ファイルのダウンロード + ターミナルで以下のコマンドを実行し,Linux版バイナリを取得する. + $ wget https://bin.equinox.io/c/bNyj1mQVY4c/ngrok-v3-stable-linux-amd64.tgz + + 2. 解凍とインストール + ダウンロードしたファイルを解凍し,実行パスの通ったディレクトリに移動する. + $ sudo tar xvzf ngrok-v3-stable-linux-amd64.tgz -C /usr/local/bin + + 3. 動作確認 + バージョン情報が表示されるか確認する. + $ ngrok --version + ※ "ngrok version 3.x.x" 等と表示されれば成功である. + +2-2. アカウント認証 (Authentication) + ngrok のダッシュボード (https://dashboard.ngrok.com/get-started/your-authtoken) + からトークンを確認し,以下のコマンドで設定する. + + ■ トークンの登録 + $ ngrok config add-authtoken [あなたのAuthtoken] + ※ "[あなたのAuthtoken]" の部分は実際の文字列に置き換える. + + +3. デバッグ実行手順 (Execution Steps) +------------------------------------------------------------------------ + +3-1. Client設定の修正 (Update Configuration) + 開発サーバーが外部 (ngrok) からの接続を受け付けるよう,設定を変更する. + + ■ package.json の編集 + `apps/client/package.json` を開き,`scripts` ブロックの `dev` コマンドに `--host` オプションを追加する. + + [修正前] + "dev": "vite" + + [修正後] + "dev": "vite --host" + +3-2. 開発サーバーの起動 (Launch Dev Server) + まず,ローカル環境でアプリケーションを起動する. + + ■ Clientアプリの起動 + プロジェクトルートで以下のコマンドを実行する. + $ pnpm --filter client dev + ※ ターミナルに `Network: http://x.x.x.x:5173/` と表示されれば設定成功である. + +3-3. ngrokによる公開 (Expose via ngrok) + 新しいターミナルウィンドウを開き,以下の手順でトンネルを作成する. + + 1. ngrokの起動 + Vite の Host ヘッダーチェックを回避するため,オプションを付与して実行する. + $ ngrok http 5173 --host-header="localhost" + + 2. 公開URLの確認 + 起動後に表示されるステータス画面から,"Forwarding" の行を確認する. + + Session Status online + Account User Name (Plan: Free) + Forwarding https://xxxx-xxxx.ngrok-free.app -> http://localhost:5173 + + 上記の "https://xxxx-xxxx.ngrok-free.app" が公開URLとなる. + +3-4. スマホからのアクセス (Access from Smartphone) + 1. URLの共有 + 発行された URL をスマホに送信する(QRコード作成ツールやチャット等を使用). + + 2. ブラウザでの確認 + スマホのブラウザ(Chrome,Safari等)で URL にアクセスする. + タイトル画面が表示されれば接続成功である. + + +4. 注意事項とトラブルシューティング (Notes & Troubleshooting) +------------------------------------------------------------------------ + +4-1. Freeプランの制限 + ・同時接続数: Freeプランでは同時に1つのポートしか公開できない. + ・Client/Server構成の注意: + 本手順ではフロントエンド (Port 5173) のみ公開している. + バックエンド (Port 3000) への WebSocket 通信が必要な場合,ゲーム開始時 + に接続エラーとなる可能性がある. + - 対策: UIレイアウトや描画負荷の確認を主目的として使用する. + +4-2. エラー対応 + ■ "ERR_NGROK_3200" (Tunnel already open) + ・既に別のターミナルで ngrok が起動している場合に発生する. + - 対策: 起動中の ngrok を終了 (Ctrl + C) してから再実行する. + + ■ "Invalid Host Header" (画面が真っ白になる) + ・Vite が不正なドメインからのアクセスを拒否している. + - 対策: 起動コマンドに `--host-header="localhost"` が含まれているか再確認する. + + ■ "ERR_CERT_AUTHORITY_INVALID" (Fortinet等の警告) + ・ngrok を使用せずローカルIPで接続しようとした場合に,組織内ネットワーク + のセキュリティ機器にブロックされる現象である. + - 対策: 必ず本手順の ngrok 経由 (https) で接続する. \ No newline at end of file diff --git "a/docs/02_ENV/ENV_08_\347\240\224\347\251\266\345\256\244\343\202\265\343\203\274\343\203\220\343\203\207\343\203\227\343\203\255\343\202\244\346\211\213\351\240\206\346\233\270.txt" "b/docs/02_ENV/ENV_08_\347\240\224\347\251\266\345\256\244\343\202\265\343\203\274\343\203\220\343\203\207\343\203\227\343\203\255\343\202\244\346\211\213\351\240\206\346\233\270.txt" new file mode 100644 index 0000000..6f4179d --- /dev/null +++ "b/docs/02_ENV/ENV_08_\347\240\224\347\251\266\345\256\244\343\202\265\343\203\274\343\203\220\343\203\207\343\203\227\343\203\255\343\202\244\346\211\213\351\240\206\346\233\270.txt" @@ -0,0 +1,279 @@ +======================================================================== +研究室サーバデプロイ手順書 (Lab Server Deployment Guide) +======================================================================== + +1. 概要 (Overview) +------------------------------------------------------------------------ +本ドキュメントは,Pixel Paint War を1台の研究室サーバ上に本番デプロイする +手順をまとめたものである. +Nginx をリバースプロキシとして使用し,外部公開ポートは 8803 のみとする. +フロントエンド(静的ファイル)とバックエンド(Socket.IO)は同一サーバ内で +ポートを分けて動作させ,外部デバイスは Nginx 経由でのみ通信する. + + +1-1. 構成図 + + [デバイス] ──HTTP(8803)──▶ [Nginx (:8803)] + ├── / → 静的ファイル配信(Viteビルド済み) + └── /socket.io → proxy_pass http://127.0.0.1:3000 + (サーバ内部のみ,外部非公開) + + ・外部公開ポート: 8803 のみ + ・バックエンド(ポート3000)は localhost バインドで外部アクセス不可 + ・HTTPS化する場合は Nginx で SSL 終端を行う(6章参照) + + +2. 前提条件 (Prerequisites) +------------------------------------------------------------------------ + +2-1. サーバ環境 + ・OS: Linux(Ubuntu 20.04 以上推奨) + ・Docker / Docker Compose がインストール済みであること + ・Nginx がインストール済みであること + ・Git がインストール済みであること + ・ポート 8803 がファイアウォールで許可されていること + +2-2. 確認コマンド + $ docker --version + $ docker compose version + $ nginx -v + $ git --version + + +3. デプロイ手順 (Deployment Steps) +------------------------------------------------------------------------ + +3-1. リポジトリの取得 + 1. サーバ上で任意のディレクトリにクローンする + $ git clone <リポジトリURL> /opt/pixel-paint-war + $ cd /opt/pixel-paint-war + + 2. デプロイ対象のブランチ・タグに切り替える + $ git checkout main + $ git pull origin main + +3-2. フロントエンドのビルド + フロントエンドは静的ファイルとしてビルドし,Nginx から配信する. + VITE_PROD_SERVER_URL にはデバイスからアクセスする URL を指定する. + + ■ ローカルネットワーク(HTTP)の場合 + $ docker run --rm -v $(pwd):/app -w /app node:20-slim \ + bash -c "corepack enable && pnpm install --frozen-lockfile \ + && pnpm --filter @repo/shared build \ + && VITE_PROD_SERVER_URL=http://<サーバIP>:8803 pnpm --filter client build" + + ■ ドメイン運用(HTTPS)の場合 + $ docker run --rm -v $(pwd):/app -w /app node:20-slim \ + bash -c "corepack enable && pnpm install --frozen-lockfile \ + && pnpm --filter @repo/shared build \ + && VITE_PROD_SERVER_URL=https://yourdomain.example.com:8803 pnpm --filter client build" + + ※ ビルド成果物は apps/client/dist/ に出力される + +3-3. バックエンドの起動(Docker Compose) + 本番用の docker-compose.prod.yml を使用してバックエンドを起動する. + ポートは localhost バインドとし,Nginx 経由でのみアクセスさせる. + + 1. docker-compose.prod.yml を以下の内容に編集する + + services: + game-server: + build: + context: . + dockerfile: Dockerfile + container_name: pixel-paint-server-prod + restart: unless-stopped + ports: + - "127.0.0.1:3000:3000" + environment: + - NODE_ENV=production + + ※ ポイント: ports を "127.0.0.1:3000:3000" にすることで, + localhost からのみアクセス可能となり外部に直接公開されない + + 2. コンテナをビルド・起動する + $ docker compose -f docker-compose.prod.yml up -d --build + + 3. 起動確認 + $ docker compose -f docker-compose.prod.yml ps + + STATUS が「Up」になっていることを確認する + + 4. ヘルスチェック + $ curl http://127.0.0.1:3000 + + 「ok」と返れば正常 + +3-4. Nginx の設定 + Nginx の設定ファイルを作成し,ポート 8803 でリクエストを受け付ける. + + 1. 設定ファイルを作成する + $ sudo vi /etc/nginx/sites-available/pixel-paint-war + + 2. 以下の内容を記述する + + server { + listen 8803; + server_name _; + + # フロントエンド(静的ファイル配信) + root /opt/pixel-paint-war/apps/client/dist; + index index.html; + + location / { + try_files $uri $uri/ /index.html; + } + + # バックエンド(Socket.IO → 内部ポート3000へプロキシ) + location /socket.io/ { + proxy_pass http://127.0.0.1:3000; + proxy_http_version 1.1; + proxy_set_header Upgrade $http_upgrade; + proxy_set_header Connection "upgrade"; + proxy_set_header Host $host; + proxy_set_header X-Real-IP $remote_addr; + proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; + proxy_set_header X-Forwarded-Proto $scheme; + } + } + + 3. シンボリックリンクを作成して有効化する + $ sudo ln -s /etc/nginx/sites-available/pixel-paint-war /etc/nginx/sites-enabled/ + + 4. 設定の文法チェック + $ sudo nginx -t + + 「syntax is ok」「test is successful」と表示されること + + 5. Nginx を再起動する + $ sudo systemctl restart nginx + +3-5. 動作確認 + 1. ブラウザからアクセスする + http://<サーバIP>:8803 + + 2. ゲーム画面が表示され,ルーム作成・参加が正常に動作することを確認する + + 3. バックエンドへの直接アクセスが遮断されていることを確認する + $ curl http://<サーバIP>:3000 + → 接続拒否またはタイムアウトになること + + +4. ファイアウォール設定 (Firewall) +------------------------------------------------------------------------ +外部に公開するポートを 8803 のみに制限する. + +4-1. ufw を使用する場合 + $ sudo ufw allow 8803/tcp + $ sudo ufw deny 3000/tcp + $ sudo ufw enable + $ sudo ufw status + +4-2. 確認事項 + ・ポート 8803: 外部からアクセス可能であること + ・ポート 3000: 外部からアクセス不可であること + ・SSH ポート(22): 許可済みであること(ロックアウト防止) + + +5. 運用コマンド (Operations) +------------------------------------------------------------------------ + +5-1. 基本操作 + ■ バックエンドの状態確認 + $ docker compose -f docker-compose.prod.yml ps + + ■ ログ確認(リアルタイム) + $ docker compose -f docker-compose.prod.yml logs -f + + ■ バックエンドの停止 + $ docker compose -f docker-compose.prod.yml down + + ■ バックエンドの再起動 + $ docker compose -f docker-compose.prod.yml restart + + ■ Nginx の状態確認 + $ sudo systemctl status nginx + +5-2. アップデート手順 + コードを更新して再デプロイする場合の手順. + + 1. 最新コードを取得する + $ cd /opt/pixel-paint-war + $ git pull origin main + + 2. フロントエンドを再ビルドする(3-2 の手順を再実行) + + 3. バックエンドを再ビルド・再起動する + $ docker compose -f docker-compose.prod.yml up -d --build + + 4. Nginx を再読み込みする(設定変更がある場合のみ) + $ sudo systemctl reload nginx + +5-3. キャッシュクリア再ビルド + ビルドキャッシュが原因で問題が発生する場合に実行する. + + $ docker compose -f docker-compose.prod.yml build --no-cache + $ docker compose -f docker-compose.prod.yml up -d --force-recreate + + +6. HTTPS化(任意) (HTTPS Setup) +------------------------------------------------------------------------ +ドメインを使用して HTTPS でアクセスさせる場合の追加手順. + +6-1. Let's Encrypt で証明書を取得する + $ sudo apt install certbot python3-certbot-nginx + $ sudo certbot --nginx -d yourdomain.example.com + +6-2. Nginx 設定を HTTPS 対応に変更する + + server { + listen 8803 ssl; + server_name yourdomain.example.com; + + ssl_certificate /etc/letsencrypt/live/yourdomain.example.com/fullchain.pem; + ssl_certificate_key /etc/letsencrypt/live/yourdomain.example.com/privkey.pem; + + root /opt/pixel-paint-war/apps/client/dist; + index index.html; + + location / { + try_files $uri $uri/ /index.html; + } + + location /socket.io/ { + proxy_pass http://127.0.0.1:3000; + proxy_http_version 1.1; + proxy_set_header Upgrade $http_upgrade; + proxy_set_header Connection "upgrade"; + proxy_set_header Host $host; + proxy_set_header X-Real-IP $remote_addr; + proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; + proxy_set_header X-Forwarded-Proto $scheme; + } + } + +6-3. 証明書の自動更新を確認する + $ sudo certbot renew --dry-run + + +7. トラブルシューティング (Troubleshooting) +------------------------------------------------------------------------ + +7-1. ブラウザでゲーム画面が表示されない + ・Nginx のエラーログを確認する + $ sudo tail -50 /var/log/nginx/error.log + ・静的ファイルのパスが正しいか確認する + $ ls /opt/pixel-paint-war/apps/client/dist/index.html + +7-2. Socket.IO 接続がエラーになる + ・バックエンドコンテナが起動しているか確認する + $ docker compose -f docker-compose.prod.yml ps + ・ローカルからバックエンドに疎通できるか確認する + $ curl http://127.0.0.1:3000 + ・Nginx のプロキシ設定で WebSocket ヘッダーが正しいか確認する + +7-3. ポート 8803 にアクセスできない + ・ファイアウォールでポート 8803 が許可されているか確認する + $ sudo ufw status + ・Nginx がポート 8803 で listen しているか確認する + $ sudo ss -tlnp | grep 8803 diff --git "a/docs/02_ENV/ENV_09_TypeScript\346\246\202\350\246\201.txt" "b/docs/02_ENV/ENV_09_TypeScript\346\246\202\350\246\201.txt" new file mode 100644 index 0000000..e489c79 --- /dev/null +++ "b/docs/02_ENV/ENV_09_TypeScript\346\246\202\350\246\201.txt" @@ -0,0 +1,90 @@ +======================================================================== +TypeScript概要 (TypeScript Overview) +======================================================================== + +1. 概要 (Overview) +------------------------------------------------------------------------ +本プロジェクト(Pixel Paint War)において採用するプログラミング言語「TypeScript」に関する基礎知識,選定理由,およびAI活用開発における優位性を定義する. +本ドキュメントは,開発チーム内での技術認識の統一を目的とする. + + +2. TypeScriptとは (What is TypeScript) +------------------------------------------------------------------------ +Microsoftによって開発されたオープンソースのプログラミング言語である.JavaScriptのスーパーセット(上位互換)として設計されており,大規模なアプリケーション開発に適した機能が拡張されている. + +2-1. JavaScriptとの違い + ・静的型付け (Static Typing): + 変数や関数の引数,戻り値に「型(Type)」を指定できる.JavaScriptは動的型付け言語であり,実行時まで型が決まらないが,TypeScriptはコンパイル(トランスパイル)時に整合性をチェックする. + ・クラスベースオブジェクト指向: + インターフェース(Interface),ジェネリクス(Generics),アクセス修飾子(public/private)など,JavaやC#に近いオブジェクト指向構文をサポートする. + ・コンパイルの必要性: + ブラウザやNode.jsはTypeScriptを直接実行できないため,JavaScriptファイルへ変換(トランスパイル)して使用する. + +2-2. 一般的な利用目的 + ・大規模Webアプリケーション開発: + コード量が増えても型定義により保守性を維持しやすい. + ・チーム開発: + 型定義がそのまま「仕様書」としての役割を果たし,メンバー間の認識齟齬を防ぐ. + ・フルスタック開発: + フロントエンド(React/Vue/Angular等)とバックエンド(Node.js/Deno等)で言語を統一し,型定義を共有する. + + +3. 言語の強み (Strengths) +------------------------------------------------------------------------ + +3-1. 安全性と品質向上 + ・コンパイルエラーによる早期発見: + 「undefinedのプロパティ参照」や「数値と文字列の誤った演算」など,JavaScriptで頻発する実行時エラーを,コードを書いている段階(コンパイル時)で検出できる. + +3-2. 開発効率の向上 + ・強力な入力補完 (IntelliSense): + VS Code等のエディタにおいて,型情報を元にした正確なコード補完,メソッドの候補表示,定義元へのジャンプが可能となる. + ・リファクタリングの容易さ: + 変数名や関数名の変更を行っても,依存する箇所をエディタが一括で修正・検知できるため,改修コストが低い. + + +4. AI活用型開発における利点 (Benefits in AI-Assisted Development) +------------------------------------------------------------------------ +本プロジェクトの方針である「AI活用型開発(Gemini Pro / GitHub Copilot Pro)」において,TypeScriptはJavaScriptと比較して以下の決定的な優位性を持つ. + +■ コンテキストの正確な伝達 + 型定義(Type/Interface)が存在することで,AIは変数の意図やデータ構造を推測ではなく「確定情報」として認識できる.これにより,提案されるコードの精度が向上する. + +■ ハルシネーション(嘘の生成)の抑制 + 存在しないプロパティや誤ったメソッドをAIが提案した場合でも,TypeScriptのコンパイラが即座にエラーを出すため,誤ったコードが実装に含まれるリスクを自動的に排除できる. + +■ 意図の明示化 + 「ENV_01」で定義された `packages/shared` のような共通型定義を参照させることで,AIはクライアント・サーバー間の通信仕様を正確に理解し,一貫性のあるロジックを生成可能となる. + + +5. 歴史と現状 (History and Current Status) +------------------------------------------------------------------------ + +5-1. 歴史 + ・開発者: Anders Hejlsberg(C#やTurbo Pascalの設計者)らが中心となり開発. + ・初版公開: 2012年10月. + ・背景: 当時,大規模化するWebアプリ開発においてJavaScriptの仕様(ES5)では保守が困難であったため,静的型付けの需要が高まっていた. + +5-2. 現在のステータス + ・世界No.1の使用率 (GitHub Octoverse 2025): + 2025年のGitHub年次レポートにおいて,長年トップであったPythonおよびJavaScriptを上回り,世界で最も使用されている言語(第1位)となった. + このランキングは,単なるコードの総量ではなく「貢献者数(Unique Contributors)」に基づいており,現在世界中で最も多くのアクティブユーザーが開発を行っている言語であることを示している. + ・デファクトスタンダード: + 現在,モダンなフロントエンド開発(React, Next.js, Vue.jsなど)において,TypeScriptは標準的な選択肢となっている. + ・普及率: + 「State of JS」などの開発者アンケートにおいて,長年「使用率」および「満足度」で上位を維持している.また,Google社内の標準言語としても採用されている(Alligator等). + + +6. 参考文献 (References) +------------------------------------------------------------------------ +・TypeScript Official Website + https://www.typescriptlang.org/ + +・The State of JS 2022/2023 (Usage & Satisfaction) + https://stateofjs.com/ + +・GitHub Octoverse 2025 + https://octoverse.github.com/ + +・Google Engineering Practices Documentation + https://google.github.io/eng-practices/ \ No newline at end of file diff --git "a/docs/02_Guide/GUIDE_01_\343\203\211\343\202\255\343\203\245\343\203\241\343\203\263\343\203\210\344\275\234\346\210\220\343\202\254\343\202\244\343\203\211.txt" "b/docs/02_Guide/GUIDE_01_\343\203\211\343\202\255\343\203\245\343\203\241\343\203\263\343\203\210\344\275\234\346\210\220\343\202\254\343\202\244\343\203\211.txt" deleted file mode 100644 index e4f637b..0000000 --- "a/docs/02_Guide/GUIDE_01_\343\203\211\343\202\255\343\203\245\343\203\241\343\203\263\343\203\210\344\275\234\346\210\220\343\202\254\343\202\244\343\203\211.txt" +++ /dev/null @@ -1,121 +0,0 @@ -======================================================================== -ドキュメント作成ガイドライン (Style Guide) -======================================================================== - -1. 基本フォーマット (Basic Format) ------------------------------------------------------------------------- -・文字コード: UTF-8 -・改行コード: LF (推奨) または CRLF -・インデント: 半角スペース4つ (4 spaces) - - タブ文字は使用せず、スペースに展開して揃える. -・ファイル命名: `GUIDE_02_ファイル命名規則.txt` を参照する. - -■ ファイルヘッダー (File Header) -・ファイルの先頭には必ずタイトルブロックを記述する. -・書式: 上下を「=」(イコール)の列(72文字程度)で挟む. -・例: - ======================================================================== - ドキュメントタイトル (English Title) - ======================================================================== - - -2. 句読点・約物 (Punctuation) ------------------------------------------------------------------------- -・句読点: 「,」(全角カンマ)と「.」(全角ピリオド)を使用する. - - 「、」「。」は使用しない. -・コロン: 半角コロン+半角スペース「: 」を使用する. - - NG: 全角コロン「:」,スペースなし「:」 -・括弧: 原則として半角括弧 `( )` を使用するが、強調や補足には全角 `( )` や `「 」` も許容する. -・注釈: 文末や段落末の補足には「※」(全角米印)+半角スペースを使用する. - - 例: ※ shared は client/server 両方から import して使用する. - - -3. 階層構造と見出し (Headings & Hierarchy) ------------------------------------------------------------------------- - -3-1. レベル1:大見出し (Section) - ・書式: 数字 + ドット + 半角スペース + タイトル + (英語タイトル) - ・装飾: 下行にハイフン「-」による区切り線を挿入する. - ・例: - 1. 基本設計 (Basic Design) - ------------------------------------------------------------------------ - -3-2. レベル2:中見出し (Subsection) - ・書式: 数字-数字 + ドット + 半角スペース + タイトル - ・例: - 1-1. 製品概要 - -3-3. レベル3:小見出し (Group Heading) - ・書式: 「■」+ 半角スペース + タイトル - ・使い分け: - - セクション内で独立したトピック(カテゴリ)を列挙する場合は「■」を使用する. - - 手順やフロー、順序のある項目を示す場合は「1. 」「2. 」を使用する. - - A. 並列・カテゴリ列挙(順序不問) - - 記号: 「■ 」(全角四角+半角スペース) - - 例: ■ フィールド仕様 - - B. 手順・優先順位・ランキング(順序重要) - - 記号: 「1. 」「2. 」(半角数字+ドット+半角スペース) - - 例: 1. ユーザ体験の理想 - -3-4. レベル4:リスト項目 (List Item) - ・記号: 「・」(全角中黒) - ・書式: 「・項目名: 内容」または「・項目名」のみ. - ・使いどころ: セクション内の主要な列挙(親項目)に使用する. - ・例: - ・タイトル: Paint War - -3-5. レベル5:詳細項目 (Detail Item) - ・記号: 「- 」(半角ハイフン+半角スペース) - ・インデント: 親項目のテキスト開始位置に合わせる(基本はスペース8つ). - ・使いどころ: 親が「・」のとき,その補足・条件・内訳を子項目として記述する. - ・ルール: 親が「・」なら子は必ず「- 」を使う. - ・例: - ・接続設定 - - host: localhost - - port: 3000 - -3-6. 特殊なナンバリング (Zero Indexing) - ・目的定義: セクションの冒頭で目的や定義を述べる場合、「X-0. 目的」というナンバリング(ゼロ始まり)を使用してもよい. - - 例: 1-0. 目的 - -3-7. 階層の順守 - ・上位レベルから下位レベルへ順に記述し,階層を飛ばさないこと. - - NG例: レベル1(1. XX)の直下にレベル3(■ XX)を記述する. - - 対策: 必要に応じてレベル2(1-1. 概要 等)を設ける. - - -4. 余白・改行ルール (Spacing) ------------------------------------------------------------------------- -・大見出しの上: 2行空ける. -・中見出し(X-X)の上: 1行空ける. -・小見出し(■や数字)の上: 1行空ける. -・セクション内のリスト: 原則として行間を詰め、まとまりごとに適宜空行を入れる. -・ミニサンプル: - 1. 基本設計 (Basic Design) - ------------------------------------------------------------------------ - - - 1-1. 製品概要 - - ■ 主要要件 - ・要件A: 説明 - ・要件B: 説明 - - ■ 補足 - ・注意点: 説明 - -・NG例(空行不足): - 1. 基本設計 (Basic Design) - ------------------------------------------------------------------------ - 1-1. 製品概要 - ■ 主要要件 - ・要件A: 説明 - - -5. 技術記述・コード表記 (Technical & Code) ------------------------------------------------------------------------- -・コマンドライン: 先頭に `$ ` を付与して区別する. -・ディレクトリ構造: ツリー記号(`├──`, `│`, `└──`)を使用し,ルートディレクトリからの階層を示す. -・インデント: コードブロック内は,親の箇条書きレベルに合わせて開始位置を揃える. \ No newline at end of file diff --git "a/docs/02_Guide/GUIDE_02_\343\203\225\343\202\241\343\202\244\343\203\253\345\221\275\345\220\215\350\246\217\345\211\207.txt" "b/docs/02_Guide/GUIDE_02_\343\203\225\343\202\241\343\202\244\343\203\253\345\221\275\345\220\215\350\246\217\345\211\207.txt" deleted file mode 100644 index a8217e6..0000000 --- "a/docs/02_Guide/GUIDE_02_\343\203\225\343\202\241\343\202\244\343\203\253\345\221\275\345\220\215\350\246\217\345\211\207.txt" +++ /dev/null @@ -1,54 +0,0 @@ -======================================================================== -ドキュメント管理・ファイル命名規則 (File Naming Conventions) -======================================================================== - -1. 命名の基本方針 (Basic Policy) ------------------------------------------------------------------------- -プロジェクトの規模拡大に伴うファイルの散乱を防ぎ,開発メンバーおよびAI(Gemini/Copilot)がファイルの内容・文脈を即座に特定できるようにするため,以下の規則を適用する. -※ 書式・記述スタイルの基準は `GUIDE_01_ドキュメント作成ガイド.txt` を参照する. - -■ 基本フォーマット -`[カテゴリ]_[連番]_[ファイル名].txt` - -・区切り文字: アンダースコア `_` を使用する. -・連番: 01から始まる2桁の数字とする. -・拡張子: プレーンテキスト `.txt` とする. - - -2. カテゴリ定義 (Category Definitions) ------------------------------------------------------------------------- -ファイル名の先頭に付与するプレフィックス(接頭辞)定義. - -■ GUIDE_ (Guide) -・内容: チーム全体のルール,規約,運用フローなど,「メタ情報」に関する定義. -・対象例: スタイルガイド,命名規則,Git運用ルール. - -■ PLAN_ (Planning) -・内容: プロジェクトの進行計画,スケジュール,要件定義など,「管理・進行」に関する定義. -・対象例: WBS,ロードマップ,要件定義書,タスク一覧. - -■ ENV_ (Environment) -・内容: 開発環境,ディレクトリ構造,ライブラリ選定など,プロジェクトの「土台」に関する定義. -・対象例: 環境構築手順,技術スタック一覧,パッケージ構成図. - -■ SPEC_ (Specification) -・内容: 企画,ゲームルール,UI/UXなど,ユーザーから見える「仕様」に関する定義. -・対象例: ゲーム企画書,画面遷移図,パラメータ設定(マップサイズ・速度など). - -■ TECH_ (Technical) -・内容: 実装詳細,アルゴリズム,データ構造など,エンジニア向けの「技術設計」に関する定義. -・対象例: 通信プロトコル仕様,同期ロジック,データベース設計,クラス設計. - -■ TEST_ (Test) -・内容: テスト計画,テストケース,品質保証手順など,「検証・品質」に関する定義. -・対象例: 単体テスト仕様書,シナリオテスト計画,テストケース一覧,品質基準. - - -3. 運用ルール (Operational Rules) ------------------------------------------------------------------------- -・1ファイル1テーマ: - ファイルサイズが肥大化しすぎないよう,トピック(例: 通信仕様,判定ロジック)ごとにファイルを分割することを推奨する. - これにより,AIへのコンテキスト入力精度が向上する. - -・スタイルの継承: - 新規作成するファイルも,必ず `GUIDE_01_ドキュメント作成ガイド.txt` に記載された書式(見出し,句読点「,.」等)に従うこと. \ No newline at end of file diff --git "a/docs/02_Guide/GUIDE_03_Git\351\201\213\347\224\250\343\203\253\343\203\274\343\203\253.txt" "b/docs/02_Guide/GUIDE_03_Git\351\201\213\347\224\250\343\203\253\343\203\274\343\203\253.txt" deleted file mode 100644 index 2bff163..0000000 --- "a/docs/02_Guide/GUIDE_03_Git\351\201\213\347\224\250\343\203\253\343\203\274\343\203\253.txt" +++ /dev/null @@ -1,127 +0,0 @@ -======================================================================== -Git運用ルール (Git Operation Rules) -======================================================================== - -1. 基本方針 (Basic Policy) ------------------------------------------------------------------------- -チーム開発におけるコードの整合性を保ち,手戻りを防ぐために以下の運用フローを徹底する. - -・メインブランチ (main): - - 本番環境または常に動作可能な状態を維持するブランチ. - - 直接のコミット(直プッシュ)は禁止する.必ずプルリクエスト(PR)経由でマージする. -・作業ブランチ (Feature Branch): - - 機能追加やバグ修正ごとに `main` から派生させて作成する. - - 作業完了後,`main` へマージし,原則として削除する. - - -2. ブランチ命名規則 (Branch Naming) ------------------------------------------------------------------------- -2-1. プレフィックス (Prefix) -作業の種類を一目で判別するために,以下のプレフィックスを使用する. - -■ カテゴリ一覧 - ・feature/: 新機能の実装,仕様変更 - ・fix/: バグ修正 - ・refactor/: コードの整理(挙動は変えない) - ・docs/: ドキュメントの追記・修正 - ・chore/: ビルド設定やツール導入など,雑多な作業 - -2-2. 書式 (Format) - ・書式: `[プレフィックス][日付(YYMMDD)]_[名前]_[概要]` - ・区切り: スラッシュ `/` および アンダースコア `_` を使用する. - ・例: - - feature/260207_yamada_player_jump - - fix/260208_tanaka_collision_bug - - docs/260210_suzuki_guide_update - - -3. 開発フロー (Development Workflow) ------------------------------------------------------------------------- -作業を開始してからマージされるまでの手順. - -1. ローカルの最新化 - ・作業開始前は必ず `main` ブランチに切り替え,リモートの最新状態を取り込む. - ・コマンド: - $ git checkout main - $ git pull origin main - -2. 作業ブランチの作成 - ・最新の `main` から新しいブランチを作成して移動する. - ・コマンド: - $ git checkout -b feature/260214_yamada_new_function - -3. 実装とコミット - ・作業単位(意味のあるまとまり)ごとにコミットする. - ・巨大なコミットは避け,レビューしやすい粒度を心がける. - ・VS CodeでCopilotを使用している場合,AIによるコミットメッセージの生成機能(キラキラアイコン等)を利用してもよい. - ただし,生成されたメッセージは必ず「4. コミットメッセージ」の書式ルール(タグや日本語化)に合わせて修正すること. - ・コマンド: - $ git add . - $ git commit -m "[add] 新機能を実装" - -4. リモートへのプッシュ - ・作業ブランチをリモートリポジトリへ送信する. - ・コマンド: - $ git push origin feature/260214_yamada_new_function - -5. プルリクエスト (PR) の作成 - ・GitHubのリポジトリ画面上部に表示される「Compare & pull request」ボタンをクリックする. - ・Baseを `main`、Compareを自分の「作業ブランチ」に設定する. - ・「Reviewers」メニューからチームメンバーを選択し、レビューを依頼する. - ・「Create pull request」ボタンを押してPRをオープンする. - -6. レビューと修正の対応 - ・レビュワーのコメントを確認し、修正が必要な場合はローカルで修正・コミット・プッシュを繰り返す. - ・GitHub上で全ての指摘に対し「Resolve conversation」を行い、やり取りを完了させる. - ・レビュワーから「Approve(承認)」のスタンプまたはメッセージをもらう. - -7. マージの実行(マージボタンの操作) - ・PR画面下部の「Merge pull request」ボタンをクリックする. - ・確認用の「Confirm merge」ボタンを押し、`main` への統合を完了させる. - ・マージ直後に表示される「Delete branch」ボタンを押し、リモート上の作業ブランチを削除する. - -8. ローカル環境のクリーンアップ - ・マージ完了後はローカル環境も最新状態に戻し、古いブランチを削除する. - $ git checkout main - $ git pull origin main - $ git branch -d [作業ブランチ名] - - -4. コミットメッセージ (Commit Messages) ------------------------------------------------------------------------- -4-1. 書式 - ・書式: `[タグ] 内容` - ・言語: 日本語 (Japanese) - ・句読点: 末尾に句点は不要. - -4-2. タグ一覧 - ・[add]: ファイルや機能の追加 - ・[update]: 機能やデータの更新・修正 - ・[fix]: バグ修正 - ・[remove]: 削除 - ・[clean]: 整理,リファクタリング - - -5. トラブルシューティング (Troubleshooting) ------------------------------------------------------------------------- -■ コンフリクト (Conflict) が発生した場合 -他メンバーの変更と競合した場合の対処手順. - -1. main の取り込み - ・作業ブランチに `main` の最新内容をマージして競合箇所を洗い出す. - ・コマンド: - $ git checkout main - $ git pull origin main - $ git checkout feature/260214_yamada_new_function - $ git merge main - -2. 競合の解消 - ・エディタ上で `<<<<<<<`, `=======`, `>>>>>>>` で囲まれた箇所を手動で修正する. - ・修正後,再度コミットしてプッシュする. - -■ 間違えて main にコミットしてしまった場合 - ・まだプッシュしていない場合,コミットを取り消して新しいブランチへ移動させる. - ・コマンド: - $ git reset --soft HEAD^ - $ git checkout -b feature/260214_yamada_new_function - $ git commit -m "..." \ No newline at end of file diff --git "a/docs/02_Guide/GUIDE_04_\343\202\263\343\203\274\343\203\211\343\202\263\343\203\241\343\203\263\343\203\210\350\246\217\345\211\207.txt" "b/docs/02_Guide/GUIDE_04_\343\202\263\343\203\274\343\203\211\343\202\263\343\203\241\343\203\263\343\203\210\350\246\217\345\211\207.txt" deleted file mode 100644 index 2faa119..0000000 --- "a/docs/02_Guide/GUIDE_04_\343\202\263\343\203\274\343\203\211\343\202\263\343\203\241\343\203\263\343\203\210\350\246\217\345\211\207.txt" +++ /dev/null @@ -1,124 +0,0 @@ -======================================================================== -コードコメント・ドキュメント規則 (Code Comment & Documentation Guide) -======================================================================== - - -1. 基本方針 (Basic Policy) ------------------------------------------------------------------------- -コードの可読性と保守性を高めるため,ファイル・型・関数・定数それぞれに対して -適切な粒度でコメントを記述する. - -・言語: 日本語で記述する. -・句読点: 「,」(全角カンマ)を使用し,文末の句点(「.」「。」)は付けない - - 列挙が続く場合は「,」で区切る -・文体: 体言止め,または「〜する」形で統一する - - -2. コメントの種類と用途 (Comment Types) ------------------------------------------------------------------------- - -2-1. ファイルドキュメント (File Header Doc Comment) - ・ファイルの先頭に必ず記述する. - ・JSDoc形式(`/** */`)を使用する. - ・書式: - - /** - * [ファイル名(拡張子なし)] - * [ファイルの主な責務を1行で説明] - * [補足情報があれば続けて記述] - */ - - ・例: - - /** - * useJoystick - * ジョイスティック入力を受け取り,座標計算と正規化ベクトルの出力を行うフック - * UI描画に必要な中心点・ノブ位置・半径も合わせて提供する - */ - -2-2. 型・定数ドキュメント (Type & Constant Doc Comment) - ・`export` される型(`type`,`interface`)および定数(`const`)には必ず記述する. - ・JSDoc形式の1行コメント(`/** */`)を直前行に記述する. - ・書式: - - /** [その型・定数が何を表すかを端的に説明] */ - export type / const ... - - ・例: - - /** UI側と共有する最大半径の既定値 */ - export const MAX_DIST = 60; - - /** 2D座標の簡易型 */ - type Point = { x: number; y: number }; - - /** フックが返すUI向けの状態とハンドラ */ - type UseJoystickReturn = { ... }; - -2-3. 関数・コンポーネント・フックドキュメント (Function Doc Comment) - ・`export` される関数,Reactコンポーネント,フックには必ず記述する. - ・JSDoc形式の1行コメント(`/** */`)を直前行に記述する. - ・書式: - - /** [その関数・コンポーネントが何をするかを端的に説明] */ - export const / function ... - - ・例: - - /** 正規化ベクトルの出力とUI用の座標を提供するフック */ - export const useJoystick = ... - - /** ポインター入力と描画を結びつけるジョイスティックUI */ - export const Joystick = ... - -2-4. ブロックコメント (Block Comment) - ・関数・コンポーネント内で,処理のまとまりが変わる箇所に記述する. - ・通常の行コメント(`//`)を使用する. - ・書式: - - // [このブロックの処理を端的に説明] - ...処理... - - ・例: - - // 入力開始時の基準座標をセットする - const handleStart = ... - - // 入力座標からベクトルを計算し,半径でクランプして正規化出力する - const handleMove = ... - -2-5. JSXコメント (JSX Comment) - ・JSX内のブロック区切りには `{/* */}` 形式を使用する. - ・例: - - {/* 見た目のみの描画(入力は扱わない) */} - - -2-6. 再エクスポートコメント (Re-export Comment) - ・外部へ再公開する `export { ... }` には1行ドキュメントを付ける. - ・例: - - /** 入力半径の既定値を外部から参照できるように再公開 */ - export { MAX_DIST } from "./useJoystick"; - - -3. 記述しない場合の判断基準 (When to Omit) ------------------------------------------------------------------------- -・ファイル内部でのみ使用し,外部に公開されない型・関数・定数は省略してもよい -・コード自体が自明な場合(変数名で意図が十分伝わる場合)は省略してもよい -・ユニットテストファイルは,テストケース名で意図が伝わる場合は省略してもよい - - -4. NG例 (Anti-patterns) ------------------------------------------------------------------------- -・句点を付ける - - NG: /** ジョイスティックの入力を受け取る. */ - - OK: /** ジョイスティックの入力を受け取る */ - -・「、」「。」を使う - - NG: // 入力開始時の基準座標をセットする。 - - OK: // 入力開始時の基準座標をセットする - -・ファイルヘッダーを通常の行コメントで書く - - NG: // useJoystick: ジョイスティック入力を受け取るフック - - OK: /** \n * useJoystick\n * ジョイスティック入力を受け取るフック\n */ diff --git "a/docs/02_Guide/GUIDE_05_\343\203\227\343\203\255\343\203\210\343\202\263\343\203\253\350\277\275\345\212\240\346\211\213\351\240\206.txt" "b/docs/02_Guide/GUIDE_05_\343\203\227\343\203\255\343\203\210\343\202\263\343\203\253\350\277\275\345\212\240\346\211\213\351\240\206.txt" deleted file mode 100644 index 3104ac6..0000000 --- "a/docs/02_Guide/GUIDE_05_\343\203\227\343\203\255\343\203\210\343\202\263\343\203\253\350\277\275\345\212\240\346\211\213\351\240\206.txt" +++ /dev/null @@ -1,111 +0,0 @@ -======================================================================== -プロトコル追加手順 (Protocol Extension Guide) -======================================================================== - - -1. 目的 (Purpose) ------------------------------------------------------------------------- -本ドキュメントは,ソケットイベントの追加・変更時に,修正箇所の漏れを防ぐための標準手順を定義する. -`packages/shared/src/protocol` の責務分割方針に従い,イベント名,ペイロード型,方向別マップ,公開エントリを順に更新する. - - -2. 適用対象 (Scope) ------------------------------------------------------------------------- -・対象レイヤ: shared プロトコル定義(client/server 共通契約) -・対象ディレクトリ: `packages/shared/src/protocol` -・対象ユースケース: 新規イベント追加,既存イベントのペイロード変更,イベント廃止 - - -3. ディレクトリ構成 (Directory Layout) ------------------------------------------------------------------------- -・基準構成は以下とする. - - packages/shared/src/protocol/ - ├── socketEvents.ts - ├── eventPayloads.ts - ├── eventPayloadMaps.ts - ├── events.ts - ├── socketEventBridge.ts - ├── payloads/ - │ ├── commonPayloads.ts - │ ├── lobbyPayloads.ts - │ └── gamePayloads.ts - └── maps/ - ├── commonEventPayloadMap.ts - ├── lobbyEventPayloadMap.ts - └── gameEventPayloadMap.ts - - -4. 標準追加フロー (Standard Flow) ------------------------------------------------------------------------- -新規イベントを追加する場合は,必ず次の順で更新する. - -4-1. イベント名を追加する - ・ファイル: socketEvents.ts - ・作業: `SocketEvents` にイベント名を追加する - ・確認: 命名規則(kebab-case / snake_case)を既存方針に合わせる - -4-2. ペイロード型を追加する - ・ファイル: payloads/commonPayloads.ts または payloads/lobbyPayloads.ts または payloads/gamePayloads.ts - ・作業: イベントに対応する payload 型を追加する - ・確認: 既存型の再利用可否を確認し,重複定義を避ける - -4-3. 方向別マップへ対応を追加する - ・ファイル: maps/commonEventPayloadMap.ts / maps/lobbyEventPayloadMap.ts / maps/gameEventPayloadMap.ts - ・作業: 追加イベントを C→S または S→C の適切な map に追記する - ・確認: 方向が誤っていないかを必ず確認する - -4-4. 集約エントリの再公開を調整する - ・ファイル: eventPayloads.ts / eventPayloadMaps.ts / events.ts - ・作業: 外部利用が必要な型のみ再公開する - ・確認: 既存 import パス互換(`@repo/shared` 経由)を維持する - -4-5. 利用側を接続する - ・対象: client/server の handler / bridge / useCase - ・作業: on/off/emit と payload 型参照を更新する - - -5. 変更時のチェックポイント (Checklist) ------------------------------------------------------------------------- -・イベント名追加済みか -・payload 型追加済みか -・map への方向別登録済みか -・events.ts 再公開が過不足ないか -・client/server で型エラーがないか -・既存イベントの型互換を壊していないか -・player 座標差分イベント(SocketEvents.UPDATE_PLAYERS / update-players)に teamId を含めていないか -・初期同期イベント(SocketEvents.CURRENT_PLAYERS / current-players,SocketEvents.NEW_PLAYER / new-player)に teamId を含めているか - - -6. 典型ミスと対策 (Common Pitfalls) ------------------------------------------------------------------------- -■ イベント名だけ追加して map を更新しない -・症状: emit/on の型推論が崩れる,もしくは any 化する -・対策: 4-3 を必須工程として実施する - -■ payload 定義場所が不適切 -・症状: common/lobby/game の境界が曖昧になる -・対策: イベント責務に従って payloads 配下へ配置する - -■ 循環参照を作る -・症状: 型解決エラー,TS2307/TS2456 系が発生しやすくなる -・対策: `events.ts` は再公開専用とし,型本体は payload 側へ置く - - -7. 検証コマンド (Validation Commands) ------------------------------------------------------------------------- -・shared 型定義のビルド確認 - $ pnpm --filter @repo/shared build - -・サーバー互換確認 - $ pnpm --filter server build - -・クライアント互換確認 - $ pnpm --filter client build - - -8. 運用ルール (Operation Rules) ------------------------------------------------------------------------- -・プロトコル追加時は,本ガイドの 4-1 から 4-5 までを PR テンプレート上でチェックする -・events.ts に型本体を戻さない(再公開専用を維持する) -・新規型のコメントは `GUIDE_04_コードコメント規則` に従う diff --git "a/docs/03_PLAN/PLAN_01_\347\247\273\345\213\225\343\203\206\343\202\271\343\203\210\345\256\237\350\243\205\350\250\210\347\224\273.txt" "b/docs/03_PLAN/PLAN_01_\347\247\273\345\213\225\343\203\206\343\202\271\343\203\210\345\256\237\350\243\205\350\250\210\347\224\273.txt" new file mode 100644 index 0000000..262bd72 --- /dev/null +++ "b/docs/03_PLAN/PLAN_01_\347\247\273\345\213\225\343\203\206\343\202\271\343\203\210\345\256\237\350\243\205\350\250\210\347\224\273.txt" @@ -0,0 +1,79 @@ +======================================================================== +Pixel Paint War - プロトタイプ実装計画 (Prototype Implementation Plan) +======================================================================== + +1. 概要 (Overview) +------------------------------------------------------------------------ +本ドキュメントは,「SPEC_03_プロトタイプ_移動テスト.txt」で定義された50人同時接続テストを達成するための段階的な実装ロードマップである. +複雑性を排除するため,最小構成から機能を積み上げる(Step-by-Step)方式を採用する. + + +2. 実装フェーズ定義 (Implementation Phases) +------------------------------------------------------------------------ + +2-1. Step 1: クライアント単体移動 (Local Movement) + ■ 目標 + サーバーを介さず,ブラウザ上でジョイスティック操作によりキャラクターが移動・描画されること. + + ■ 実装対象 + ・packages/shared/ + - src/config/gameConfig.ts: マップサイズ,移動速度等の定数定義. + - src/utils/math.ts: ベクトル計算,移動ロジック (Pos += Vel * Speed * DT). + ・apps/client/ + - src/input/Joystick.ts: タッチ入力の正規化,デッドゾーン処理. + - src/entities/PlayerSprite.ts: 描画更新処理. + - src/core/GameLoop.ts: Pixi.js Tickerを用いたメインループ. + +2-2. Step 2: サーバー開通・単体通信 (Single Player Network) + ■ 目標 + WebSocketサーバーと接続し,バイナリパケットの送受信(エコーテスト)に成功すること. + + ■ 実装対象 + ・packages/shared/ + - src/protocol/schema.ts: DataViewを用いたバイナリエンコード/デコード処理. + ・apps/server/ + - src/index.ts: WebSocketサーバー起動 (wsライブラリ). + - src/network/Connection.ts: 接続管理. + ・apps/client/ + - src/network/SocketClient.ts: バイナリ送受信の実装. + +2-3. Step 3: 複数人同期・補間 (Multiplayer Sync) + ■ 目標 + 2つのクライアント間で位置同期が行われ,他プレイヤーの動きが補間により滑らかに表示されること. + + ■ 実装対象 + ・apps/server/ + - src/managers/RoomManager.ts: 接続IDと座標の管理. + - src/network/PacketHandler.ts: 全員分の座標スナップショット作成とブロードキャスト. + ・apps/client/ + - src/entities/RemotePlayer.ts: 他プレイヤー描画クラス. + - src/network/Reconciler.ts: 線形補間 (Lerp) ロジックの実装. + +2-4. Step 4: 50人規模最適化 (Optimization & Scaling) + ■ 目標 + パケットサイズを削減し,50人同時動作時の帯域負荷を仕様内(30KB/s以下)に抑えること. + + ■ 実装対象 + ・packages/shared/ + - src/utils/quantization.ts: 座標の圧縮 (Float -> Uint16). + ・apps/server/ + - src/core/ServerEngine.ts: ループ処理の最適化,必要に応じたAoI(関心領域)判定. + +2-5. Step 5: メタデータ・UI実装 (Meta Data & UI) + ■ 目標 + ゲーム開始前のロビー画面およびUIを実装し,ゲームサイクルを完成させること. + + ■ 実装対象 + ・apps/client/ + - src/scenes/TitleScene.ts: 名前入力とスタート処理. + - src/ui/UIManager.ts: DOMベースのUIオーバーレイ. + ・packages/shared/ + - src/types/index.ts: ロビー用JSONメッセージの型定義. + + +3. 開発ルール (Development Rules) +------------------------------------------------------------------------ +・ロジックの共通化: + 移動計算式や衝突判定は必ず `packages/shared` に実装し,Client/Server間でコードを共有する. +・検証優先: + 各Step完了ごとに動作確認を行い,バグを次工程に持ち越さない. \ No newline at end of file diff --git "a/docs/03_Plan/PLAN_01_\347\247\273\345\213\225\343\203\206\343\202\271\343\203\210\345\256\237\350\243\205\350\250\210\347\224\273.txt" "b/docs/03_Plan/PLAN_01_\347\247\273\345\213\225\343\203\206\343\202\271\343\203\210\345\256\237\350\243\205\350\250\210\347\224\273.txt" deleted file mode 100644 index 262bd72..0000000 --- "a/docs/03_Plan/PLAN_01_\347\247\273\345\213\225\343\203\206\343\202\271\343\203\210\345\256\237\350\243\205\350\250\210\347\224\273.txt" +++ /dev/null @@ -1,79 +0,0 @@ -======================================================================== -Pixel Paint War - プロトタイプ実装計画 (Prototype Implementation Plan) -======================================================================== - -1. 概要 (Overview) ------------------------------------------------------------------------- -本ドキュメントは,「SPEC_03_プロトタイプ_移動テスト.txt」で定義された50人同時接続テストを達成するための段階的な実装ロードマップである. -複雑性を排除するため,最小構成から機能を積み上げる(Step-by-Step)方式を採用する. - - -2. 実装フェーズ定義 (Implementation Phases) ------------------------------------------------------------------------- - -2-1. Step 1: クライアント単体移動 (Local Movement) - ■ 目標 - サーバーを介さず,ブラウザ上でジョイスティック操作によりキャラクターが移動・描画されること. - - ■ 実装対象 - ・packages/shared/ - - src/config/gameConfig.ts: マップサイズ,移動速度等の定数定義. - - src/utils/math.ts: ベクトル計算,移動ロジック (Pos += Vel * Speed * DT). - ・apps/client/ - - src/input/Joystick.ts: タッチ入力の正規化,デッドゾーン処理. - - src/entities/PlayerSprite.ts: 描画更新処理. - - src/core/GameLoop.ts: Pixi.js Tickerを用いたメインループ. - -2-2. Step 2: サーバー開通・単体通信 (Single Player Network) - ■ 目標 - WebSocketサーバーと接続し,バイナリパケットの送受信(エコーテスト)に成功すること. - - ■ 実装対象 - ・packages/shared/ - - src/protocol/schema.ts: DataViewを用いたバイナリエンコード/デコード処理. - ・apps/server/ - - src/index.ts: WebSocketサーバー起動 (wsライブラリ). - - src/network/Connection.ts: 接続管理. - ・apps/client/ - - src/network/SocketClient.ts: バイナリ送受信の実装. - -2-3. Step 3: 複数人同期・補間 (Multiplayer Sync) - ■ 目標 - 2つのクライアント間で位置同期が行われ,他プレイヤーの動きが補間により滑らかに表示されること. - - ■ 実装対象 - ・apps/server/ - - src/managers/RoomManager.ts: 接続IDと座標の管理. - - src/network/PacketHandler.ts: 全員分の座標スナップショット作成とブロードキャスト. - ・apps/client/ - - src/entities/RemotePlayer.ts: 他プレイヤー描画クラス. - - src/network/Reconciler.ts: 線形補間 (Lerp) ロジックの実装. - -2-4. Step 4: 50人規模最適化 (Optimization & Scaling) - ■ 目標 - パケットサイズを削減し,50人同時動作時の帯域負荷を仕様内(30KB/s以下)に抑えること. - - ■ 実装対象 - ・packages/shared/ - - src/utils/quantization.ts: 座標の圧縮 (Float -> Uint16). - ・apps/server/ - - src/core/ServerEngine.ts: ループ処理の最適化,必要に応じたAoI(関心領域)判定. - -2-5. Step 5: メタデータ・UI実装 (Meta Data & UI) - ■ 目標 - ゲーム開始前のロビー画面およびUIを実装し,ゲームサイクルを完成させること. - - ■ 実装対象 - ・apps/client/ - - src/scenes/TitleScene.ts: 名前入力とスタート処理. - - src/ui/UIManager.ts: DOMベースのUIオーバーレイ. - ・packages/shared/ - - src/types/index.ts: ロビー用JSONメッセージの型定義. - - -3. 開発ルール (Development Rules) ------------------------------------------------------------------------- -・ロジックの共通化: - 移動計算式や衝突判定は必ず `packages/shared` に実装し,Client/Server間でコードを共有する. -・検証優先: - 各Step完了ごとに動作確認を行い,バグを次工程に持ち越さない. \ No newline at end of file diff --git "a/docs/04_SPEC/SPEC_03_\343\203\227\343\203\255\343\203\210\343\202\277\343\202\244\343\203\227_\347\247\273\345\213\225\343\203\206\343\202\271\343\203\210.txt" "b/docs/04_SPEC/SPEC_03_\343\203\227\343\203\255\343\203\210\343\202\277\343\202\244\343\203\227_\347\247\273\345\213\225\343\203\206\343\202\271\343\203\210.txt" new file mode 100644 index 0000000..b4400cd --- /dev/null +++ "b/docs/04_SPEC/SPEC_03_\343\203\227\343\203\255\343\203\210\343\202\277\343\202\244\343\203\227_\347\247\273\345\213\225\343\203\206\343\202\271\343\203\210.txt" @@ -0,0 +1,107 @@ +======================================================================== +プロトタイプ仕様書:50人同時移動テスト (Prototype Spec: Movement Test) +======================================================================== + + +1. プロトタイプ概要 (Overview) +------------------------------------------------------------------------ + +1-0. 目的 + 50人のプレイヤーが同じフィールド上で遅延なく移動できる通信基盤を検証する. + 衝突判定,塗り処理,ゲーム進行管理などの付随要素は実装せず,純粋な「移動同期」と「負荷検証」にフォーカスする. + +1-1. 検証範囲 + ・マップ: 100×100マスのグリッドマップ + ・人数: 最大50クライアント同時接続 + ・動作: 360度移動,カメラ追従,他者位置の同期表示 + + +2. クライアント実装仕様 (Client Implementation) +------------------------------------------------------------------------ + +2-0. 目的 + 入力処理,移動計算,および描画の基本ロジックを定義する. + +2-1. 入力・操作系 + ■ ジョイスティック操作 + ・左側エリア: 画面左半分をタッチ可能な移動ジョイスティック領域とする. + ・入力形式: 360°全方位入力. + ・ベクトル正規化: + - 入力ベクトルの長さが1.0を超える場合,1.0に正規化する. + - これにより,斜め移動時の意図しない加速を防止する. + + ■ 誤操作防止 (UX Protection) + ・スクリーンロック: + - ゲーム画面に対するスクロール,拡大縮小(ピンチ操作)を無効化する. + ・エッジデッドゾーン: + - 画面左右の端(10px〜)を入力無効領域とし,OSのジェスチャー機能暴発を防ぐ. + +2-2. 移動・演算ロジック + ■ キャラクター仕様 + ・サイズ: 0.8マス×0.8マス + ・移動速度: 秒速4〜5マス + + ■ 時間管理 (Time Management) + ・DeltaTime対応: + - 毎フレームの移動量計算に「前フレームからの経過時間 (DeltaTime)」を乗算する. + - 計算式: `Position += Velocity * Speed * DeltaTime` + - 目的: 端末のフレームレート(30fps/60fps/120fps)に依存せず,移動速度を一定に保つ. + + ■ 座標管理 + ・内部座標(計算・通信用): + - Float(浮動小数点)で管理し,滑らかな移動を実現する. + ・グリッド座標(表示目安): + - 内部座標の小数点以下を切り捨て(Floor)た値を現在のマスとする. + +2-3. カメラシステム (Camera System) + ■ カメラ追従 (Camera Follow) + ・挙動: + - 常に「自キャラクター」が画面の中央に配置されるよう,カメラ座標を毎フレーム更新する. + - マップ端に到達した場合のクランプ(固定)処理は,本プロトタイプでは実装不要とする(黒背景が見えても良い). + + +3. 通信アーキテクチャ (Network Architecture) +------------------------------------------------------------------------ + +3-0. 目的 + 50人の座標をリアルタイムに同期するためのデータ構造と通信フローを定義する. + +3-1. 通信フローと役割分担 + | カテゴリ | クライアント (Client) | サーバー (Server) | + | :--- | :--- | :--- | + | **自キャラ** | **予測 (Prediction)**: 入力を即時反映し座標を更新・送信. | **中継 (Relay)**: 受信座標を正とし,他者へブロードキャスト. | + | **他キャラ** | **補間 (Interpolation)**: 受信した過去の座標間を滑らかに補間移動. | **間引き (AoI)**: 距離に応じ送信情報を圧縮・除外. | + +3-2. サーバー更新ループ (Server Loop) + ■ ティックレート (Tick Rate) + ・頻度: 20Hz(50ms間隔) + ・処理内容: + 1. 受信バッファ内の全クライアントからの入力を取り出す. + 2. AoI(関心領域)判定を行い,各クライアントに必要なデータをフィルタリングする. + 3. 全クライアントへ「スナップショット」を一斉送信する. + + ■ スナップショット送信 (Snapshot) + ・送信データ: + - 視界範囲内にいる全キャラクターの ID,座標,向き. + - サーバータイムスタンプ(補間計算用). + +3-3. データ構造・最適化 + ■ パケット設計 + ・形式: バイナリパケット(ArrayBuffer等)を採用し,JSON等のテキスト形式は使用しない. + + ■ 座標の量子化 (Quantization) + ・目的: 通信帯域の削減. + ・手法: + - Float座標(0.0〜100.0)を,Unsigned Short(0〜65535)の整数値に変換して送信する. + - 受信側で再度Floatに戻して使用する. + + ■ 送信データ (Input Data) + クライアントからサーバーへ毎フレーム(または間引き)送信するデータ. + ・現在座標 (Position): 物理演算(DeltaTime適用)後の確定座標 (x, y). + ・移動ベクトル (Velocity): 補間予測用の補助データ. + ・角度 (Rotation): キャラクターの向き. + + ■ エリア別同期 (AoI) + ・ロジック: + - 各プレイヤーを中心とした一定範囲(例: 画面サイズの1.5倍)外にいる他プレイヤーの座標データは送信しない. + - これにより,50人全員が動いていても,各端末が受け取るデータ量を視界内のみに限定する. \ No newline at end of file diff --git "a/docs/04_Spec/SPEC_03_\343\203\227\343\203\255\343\203\210\343\202\277\343\202\244\343\203\227_\347\247\273\345\213\225\343\203\206\343\202\271\343\203\210.txt" "b/docs/04_Spec/SPEC_03_\343\203\227\343\203\255\343\203\210\343\202\277\343\202\244\343\203\227_\347\247\273\345\213\225\343\203\206\343\202\271\343\203\210.txt" deleted file mode 100644 index b4400cd..0000000 --- "a/docs/04_Spec/SPEC_03_\343\203\227\343\203\255\343\203\210\343\202\277\343\202\244\343\203\227_\347\247\273\345\213\225\343\203\206\343\202\271\343\203\210.txt" +++ /dev/null @@ -1,107 +0,0 @@ -======================================================================== -プロトタイプ仕様書:50人同時移動テスト (Prototype Spec: Movement Test) -======================================================================== - - -1. プロトタイプ概要 (Overview) ------------------------------------------------------------------------- - -1-0. 目的 - 50人のプレイヤーが同じフィールド上で遅延なく移動できる通信基盤を検証する. - 衝突判定,塗り処理,ゲーム進行管理などの付随要素は実装せず,純粋な「移動同期」と「負荷検証」にフォーカスする. - -1-1. 検証範囲 - ・マップ: 100×100マスのグリッドマップ - ・人数: 最大50クライアント同時接続 - ・動作: 360度移動,カメラ追従,他者位置の同期表示 - - -2. クライアント実装仕様 (Client Implementation) ------------------------------------------------------------------------- - -2-0. 目的 - 入力処理,移動計算,および描画の基本ロジックを定義する. - -2-1. 入力・操作系 - ■ ジョイスティック操作 - ・左側エリア: 画面左半分をタッチ可能な移動ジョイスティック領域とする. - ・入力形式: 360°全方位入力. - ・ベクトル正規化: - - 入力ベクトルの長さが1.0を超える場合,1.0に正規化する. - - これにより,斜め移動時の意図しない加速を防止する. - - ■ 誤操作防止 (UX Protection) - ・スクリーンロック: - - ゲーム画面に対するスクロール,拡大縮小(ピンチ操作)を無効化する. - ・エッジデッドゾーン: - - 画面左右の端(10px〜)を入力無効領域とし,OSのジェスチャー機能暴発を防ぐ. - -2-2. 移動・演算ロジック - ■ キャラクター仕様 - ・サイズ: 0.8マス×0.8マス - ・移動速度: 秒速4〜5マス - - ■ 時間管理 (Time Management) - ・DeltaTime対応: - - 毎フレームの移動量計算に「前フレームからの経過時間 (DeltaTime)」を乗算する. - - 計算式: `Position += Velocity * Speed * DeltaTime` - - 目的: 端末のフレームレート(30fps/60fps/120fps)に依存せず,移動速度を一定に保つ. - - ■ 座標管理 - ・内部座標(計算・通信用): - - Float(浮動小数点)で管理し,滑らかな移動を実現する. - ・グリッド座標(表示目安): - - 内部座標の小数点以下を切り捨て(Floor)た値を現在のマスとする. - -2-3. カメラシステム (Camera System) - ■ カメラ追従 (Camera Follow) - ・挙動: - - 常に「自キャラクター」が画面の中央に配置されるよう,カメラ座標を毎フレーム更新する. - - マップ端に到達した場合のクランプ(固定)処理は,本プロトタイプでは実装不要とする(黒背景が見えても良い). - - -3. 通信アーキテクチャ (Network Architecture) ------------------------------------------------------------------------- - -3-0. 目的 - 50人の座標をリアルタイムに同期するためのデータ構造と通信フローを定義する. - -3-1. 通信フローと役割分担 - | カテゴリ | クライアント (Client) | サーバー (Server) | - | :--- | :--- | :--- | - | **自キャラ** | **予測 (Prediction)**: 入力を即時反映し座標を更新・送信. | **中継 (Relay)**: 受信座標を正とし,他者へブロードキャスト. | - | **他キャラ** | **補間 (Interpolation)**: 受信した過去の座標間を滑らかに補間移動. | **間引き (AoI)**: 距離に応じ送信情報を圧縮・除外. | - -3-2. サーバー更新ループ (Server Loop) - ■ ティックレート (Tick Rate) - ・頻度: 20Hz(50ms間隔) - ・処理内容: - 1. 受信バッファ内の全クライアントからの入力を取り出す. - 2. AoI(関心領域)判定を行い,各クライアントに必要なデータをフィルタリングする. - 3. 全クライアントへ「スナップショット」を一斉送信する. - - ■ スナップショット送信 (Snapshot) - ・送信データ: - - 視界範囲内にいる全キャラクターの ID,座標,向き. - - サーバータイムスタンプ(補間計算用). - -3-3. データ構造・最適化 - ■ パケット設計 - ・形式: バイナリパケット(ArrayBuffer等)を採用し,JSON等のテキスト形式は使用しない. - - ■ 座標の量子化 (Quantization) - ・目的: 通信帯域の削減. - ・手法: - - Float座標(0.0〜100.0)を,Unsigned Short(0〜65535)の整数値に変換して送信する. - - 受信側で再度Floatに戻して使用する. - - ■ 送信データ (Input Data) - クライアントからサーバーへ毎フレーム(または間引き)送信するデータ. - ・現在座標 (Position): 物理演算(DeltaTime適用)後の確定座標 (x, y). - ・移動ベクトル (Velocity): 補間予測用の補助データ. - ・角度 (Rotation): キャラクターの向き. - - ■ エリア別同期 (AoI) - ・ロジック: - - 各プレイヤーを中心とした一定範囲(例: 画面サイズの1.5倍)外にいる他プレイヤーの座標データは送信しない. - - これにより,50人全員が動いていても,各端末が受け取るデータ量を視界内のみに限定する. \ No newline at end of file