========================================================================
Pixel Paint War - 環境構築ガイド (Environment Setup Guide)
========================================================================

1. 事前準備 (Prerequisites)
------------------------------------------------------------------------

1-0. 目的
    本ドキュメントは，「Pixel Paint War」のMonorepo構成による開発環境を構築
    するための手順書である．
    ※ 本プロジェクトは Node.js v20 LTS 以上を必須とする．

1-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


2. プロジェクト初期化 (Project Initialization)
------------------------------------------------------------------------

2-1. ディレクトリ作成と初期化
    1. プロジェクトルートの作成
        任意の場所にプロジェクトフォルダを作成し，移動する．
        $ mkdir SkillSemiWebGame
        $ cd SkillSemiWebGame

    2. Gitの初期化
        $ git init

    3. pnpm の初期化
        $ pnpm init

2-2. ワークスペース設定 (Monorepo Setup)
    ルートディレクトリに以下の設定ファイルを作成し，モノレポ構成を定義する．

    1. pnpm-workspace.yaml
        ・packages/shared を共通ライブラリとし，apps 配下にアプリを配置する．
        ・内容:
            packages:
              - 'apps/*'
              - 'packages/*'

    2. .npmrc
        ・依存関係解決の設定を行う (shamefully-hoist=true 推奨)．
        ・内容:
            shamefully-hoist=true

2-3. ディレクトリ構造の構築
    以下の構成になるようにディレクトリを作成する．

    root/
    ├── apps/
    │   ├── client/           # フロントエンド (Browser)
    │   └── server/           # バックエンド (Node.js)
    └── packages/
        └── shared/           # 共通ロジック (Shared Library)

    ・作成コマンド例:
        $ mkdir -p apps/client apps/server packages/shared


3. パッケージ・ライブラリ導入 (Dependency Installation)
------------------------------------------------------------------------

3-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. エントリーポイントの作成 (追加手順)
        tsupがビルド対象とするファイルを作成する．

        $ mkdir src
        $ touch src/index.ts
        
        ※ 現時点では空ファイルでよいが，将来的に constants.ts 等を export する記述を行う．
        (例: export * from './constants';)

3-2. フロントエンド (apps/client)
    Vite プロジェクトとして初期化を行う．

    1. プロジェクト作成
        $ cd ../../apps/client
        $ pnpm create vite . --template preact-ts
        ※ 実行中に表示される選択肢には以下のように回答すること：
        ? Use rolldown-vite (Experimental)? » No
        ? Install with pnpm and start now? » No

    2. 依存ライブラリのインストール
        ・Pixi.js (描画エンジン) を追加する．
        ・共通ライブラリへの依存を追加する．
        $ pnpm add pixi.js
        $ pnpm add @repo/shared --workspace

3-3. バックエンド (apps/server)
    Node.js アプリケーションとして初期化を行う．

    1. 初期化
        $ cd ../../apps/server
        $ pnpm init

    2. 依存ライブラリのインストール
        ・ws (WebSocket) を追加する．
        ・開発用ツール (tsx, typescript, @types/node, @types/ws) を追加する．
        ・共通ライブラリへの依存を追加する．
        $ pnpm add ws
        $ pnpm add -D tsx typescript @types/node @types/ws
        $ pnpm add @repo/shared --workspace
    
    3. サーバー用ディレクトリとファイルの作成
        tsxが実行対象とするエントリーポイントを作成する．
        $ mkdir src
        $ touch src/index.ts
    
    4. 実行スクリプトの定義
        package.json にサーバー起動用のコマンドを追加する．
        ・編集ファイル: apps/server/package.json
        ・内容:
            "scripts": {
              "dev": "tsx watch src/index.ts"
            }


4. 開発ツール設定 (Dev Tools Setup)
------------------------------------------------------------------------

4-1. VS Code 拡張機能
    推奨エディタである VS Code に以下の拡張機能をインストールする．

    ■ 必須拡張機能
        ・ESLint
        ・Prettier - Code formatter
        ・EditorConfig for VS Code

    ■ 推奨拡張機能
        ・Hex Editor (バイナリパケットのデバッグ用・Microsoft公式)
        ・GitHub Copilot

4-2. AI アシスタント設定
    開発効率化のため，以下のAIツールのアカウント設定を確認する．

    1. Gemini Pro
        ・学校提供ライセンスでのアクセス権限を確認する．

    2. GitHub Copilot Pro
        ・Student Developer Pack が有効化されているか確認する．
        ・VS Code 右下のアイコンからログイン状態を確認する．


5. 動作確認 (Verification)
------------------------------------------------------------------------

5-1. ビルド確認
    ルートディレクトリから全体の依存関係をインストールし，ビルドを試行する．
    
    $ cd ../../
    $ pnpm install
    $ pnpm --filter @repo/shared build

    ※ shared のビルドが成功することを確認する．

5-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」を押下する．
        ・停止後はブラウザでURLにアクセスしても接続不可となるが，再度起動
        コマンドを実行すればいつでも再開可能である．