# クイックスタート

> start.bat をダブルクリックすればすべて自動でインストールされます。Farsight でゲームのディレクトリを設定し、試合を始めてサンプル Bot に操作を任せます。所要時間は約 15 分です。

出典: https://war3ai.com/ja/docs/quickstart/

## 必要なもの

| | 要件 | 説明 |
|---|---|---|
| OS | Windows 10 / 11、64 ビット | 現在は Windows のみ対応 |
| ゲーム | Warcraft III **1.27a**（The Frozen Throne、`Game.dll` 1.27.0.52240） | あなたが正規に所有しているクライアント。ディスク上のゲームファイルは一切変更しません |

**ほかに事前にインストールするものはありません。** `start.bat` がダウンロードするのは Python 3.13（公式のポータブル版、約 14 MB）だけで、リポジトリの `bin\env\` に配置します。管理者権限は不要で、システムの PATH も変更しません。中国国内のネットワークでは自動でミラーに切り替えます。使える Python がすでにマシンに入っていれば、それをそのまま使います。PowerShell は Windows 標準のものを使い、Farsight の Web ページはビルド済みのものがリポジトリに同梱されているため、Node.js は不要です。

## インストール

1. **コードを入手する**

   ```bash
   git clone https://github.com/OPENXXAI/OpenWar3AI.git
   ```

   または [ZIP をダウンロード](https://github.com/OPENXXAI/OpenWar3AI/archive/refs/heads/main.zip)して展開します。ランタイム（注入 DLL とランチャー）はリポジトリに同梱されているので、別途ダウンロードする必要はありません。

2. **`start.bat` をダブルクリックする**

   初回は次のことを自動で行います。

   - Python 3.13 をダウンロード
   - Python パッケージをインストールし、ランタイムのファイルを照合してから配置
   - AMAI をダウンロードして、リファレンスブレインが使う戦略データを生成（AMAI は独自ライセンスのため、生成物は git に含めません。失敗してもリファレンスブレインにしか影響しません）
   - Farsight のトップページ「コントロールセンター」 `http://127.0.0.1:8866` を開く

   各ステップの結果を表示し、うまくいかなかったステップでは補う方法を教えてくれます。2 回目以降のダブルクリックでは 1〜2 秒のチェックだけを行って Farsight を開きます。

   黒いウィンドウは数秒で自動的に閉じます。Farsight はバックグラウンドで動き続け、ブラウザを閉じても止まりません。

3. **コントロールセンターでゲームのディレクトリを設定する**

   コントロールセンターの一番上で「自動検出」するか、「参照…」から Warcraft III のディレクトリを自分で選びます。Farsight はゲームのバージョンを確認し、**あなた自身のゲームからデータを抽出**します（ユニット表、アビリティ、アイテム、相性表……Blizzard のファイルはコードと一緒には配布されません）。

   バージョンが 1.27a でない場合は知らせてくれます。マップと次の試合の設定は、どちらもこのディレクトリが基準です（`<ゲームディレクトリ>\Maps` 以下のすべてのフォルダのマップを選べます）。あとでディレクトリを変えるときは「設定」ページで行います。

4. **試合を始めて、サンプル Bot に任せる**

   いちばん手軽なのは、Farsight の「インスタンスと開始設定」ページでインスタンス番号にチェックを入れ、AI スキームを選んで「テスト開始」をクリックする方法です。コマンドラインでも実行できます。

   ```bash
   python tools/play.py --bot brains/examples/hello_bot.py
   ```

   このコマンドは、ゲームインスタンスを起動し、ランタイムを注入し、自動で試合を開始してから Bot を立ち上げます。**農民が採掘に向かい、本拠地が農民の生産を始めれば成功です。**

   コマンドの `python` には `openwar3.json` に記録されているものを使います。`start.bat` が自分でインストールしたものは `bin\env\python\python.exe` にあります。

## start.bat と stop.bat

```bash
start.bat              # デプロイのチェック + Farsight を開く
start.bat setup        # 完全チェック：Python パッケージの再インストール、AMAI の再試行
start.bat restart      # Farsight のバックエンドだけを再起動（ゲームと各サービスには影響なし）
start.bat node         # あわせて Node.js もインストール（公式サイトをプレビューするときにしか使わず、普段は不要）
start.bat 5 6          # あわせて 5 番、6 番インスタンスのテストを開始（ゲーム + リファレンスブレイン）
stop.bat               # すべてを完全に停止。stop.bat --keep-llm ならローカルモデルを VRAM に残す
```

ゲートウェイ、頭上の吹き出し、ローカル LLM も Farsight の「コントロールセンター」で起動・停止でき、別のスクリプトを探す必要はありません。**完全に停止する**には、`stop.bat` をダブルクリックするか、コントロールセンター右上の「すべて停止」をクリックします。ゲームインスタンス、AI、ゲートウェイ、吹き出し、このシステムが使うローカルモデル、Farsight のバックエンドが順にすべて停止します。MCP サーバーは Claude などのクライアントが管理しているため、停止されません。

> **設定ファイル**
>
> `openwar3.json` は `start.bat` と Farsight が自動で書き込みます。このマシン固有のパスだけを保存し、git には含めません。ポート、ローカル LLM のアドレスやモデル名を変えたいときは、`openwar3.example.json` を参考に、それと異なる項目だけを書きます。

## play.py のパラメーター

```bash
python tools/play.py --bot my_bot.py --inst 9 --race 2 --enemy-race 1 --difficulty 3 --speed 200
python tools/play.py --bot my_bot.py --inst 9 --attach      # ゲームはすでに起動済み。Bot だけを接続する
python tools/play.py --bot my_bot.py --fair                 # フェアモード：視界内のものだけが見える
```

| パラメーター | デフォルト | 説明 |
|---|---|---|
| `--bot` | 必須 | Bot ファイルのパス（ファイル内に `Bot` のサブクラスが 1 つ必要） |
| `--inst` | `9` | インスタンス番号。実行中のインスタンスと番号がぶつからないようにしてください（Farsight の「インスタンスと開始設定」ページで使用中の番号を確認できます） |
| `--race` | `1` | 自軍の種族：1 ヒューマン、2 オーク、3 アンデッド、4 ナイトエルフ |
| `--enemy-race` | `0` | 相手の種族 |
| `--difficulty` | `2` | コンピューターの難易度：2 Easy、3 Normal、4 Insane |
| `--speed` | `100` | ゲーム速度（パーセント、200 = 2 倍速） |
| `--map` | 設定の `default_map` | マップ |
| `--attach` | | ゲームを起動せず、すでに実行中のインスタンスに接続するだけ |
| `--hz` | `5` | 1 秒あたりの `on_tick` の呼び出し回数 |
| `--minutes` | `60` | 最大実行時間（実時間の分） |
| `--fair` | | [フェアモード](https://war3ai.com/ja/docs/fair-mode/) |
| `--player` | | 何番のプレイヤーとして指揮するか（AI 対 AI のときに使用） |

> **注意**
>
> `--minimize` でゲームを起動しないでください。**ウィンドウを最小化するとゲームのシミュレーションは止まり**（クロックが進まない）、Bot はいつまでも試合開始を待ち続けます。

`play.py` を使わずに、SDK のコマンドラインから実行中のインスタンスに直接接続することもできます。

```bash
python -m openwar3 run brains/examples/hello_bot.py --inst 5     # Bot を実行
python -m openwar3 status --inst 5                              # 接続して、スナップショット / ファストレーンの状態を表示
python -m openwar3 catalog                                      # API カタログを表示
```

## 動いたら次へ

  - [最初の Bot を書く](https://war3ai.com/ja/docs/first-bot/): 10 行の最小 Bot から始めて、兵の生産と出撃を一歩ずつ加えます。
  - [LLM に書いてもらう](https://war3ai.com/ja/docs/ai-bot/): プロンプトテンプレートをコピーし、戦い方を普段の言葉で説明します。

## セルフチェック

```bash
python tools/run_tests.py          # SDK / リファレンスブレイン / リフレックス層 / コンソール / 吹き出し / サンプル。それぞれ 1 つのサブプロセスで実行
```

オフラインテストはゲームを起動しなくても実行できます。Farsight の「コントロールセンター」にも環境チェックがあり、各部分がインストールできているかを確認できます。