# 빠른 시작

> start.bat을 더블클릭하면 필요한 것이 모두 자동으로 설치됩니다. Farsight에서 게임 디렉터리를 설정하고 게임을 시작해 예제 Bot이 지휘를 넘겨받는 모습을 확인합니다. 약 15분 걸립니다.

출처: https://war3ai.com/ko/docs/quickstart/

## 필요한 것

| | 요구 사항 | 설명 |
|---|---|---|
| 시스템 | Windows 10 / 11, 64비트 | 현재 Windows만 지원합니다 |
| 게임 | 워크래프트 III **1.27a**(프로즌 쓰론, `Game.dll` 1.27.0.52240) | 본인이 합법적으로 보유한 클라이언트. 디스크의 게임 파일은 전혀 수정하지 않습니다 |

**그 밖에는 미리 설치할 것이 없습니다.** `start.bat`이 내려받는 것은 딱 하나, Python 3.13(공식 포터블 패키지, 약 14MB)뿐입니다. 저장소의 `bin\env\`에 넣어 두며, 관리자 권한이 필요 없고 시스템 PATH도 바꾸지 않으며, 중국 내 네트워크에서는 자동으로 미러를 사용합니다. 컴퓨터에 이미 쓸 수 있는 Python이 있으면 그대로 사용합니다. PowerShell은 Windows에 내장된 것을 쓰고, Farsight의 웹 페이지는 저장소에 미리 빌드되어 제공되므로 Node.js가 필요 없습니다.

## 설치

1. **코드 받기**

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

   또는 [압축 파일](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`을 엽니다.

   단계마다 결과를 출력하고, 실패한 단계는 어떻게 보완하면 되는지 알려 줍니다. 그다음부터는 더블클릭할 때마다 1~2초 정도 확인만 하고 Farsight를 엽니다.

   검은 창은 몇 초 뒤 저절로 닫힙니다. Farsight는 백그라운드에서 계속 실행되며, 브라우저를 닫아도 멈추지 않습니다.

3. **컨트롤 센터에서 게임 디렉터리 설정하기**

   컨트롤 센터 맨 위에서 "자동 찾기"를 누르거나, "찾아보기…"로 워크래프트 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`이 직접 설치한 Python은 `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가 자동으로 작성하며, 이 PC의 경로만 저장하고 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`의 서브클래스가 하나 있어야 합니다) |
| `--inst` | `9` | 인스턴스 번호. 실행 중인 인스턴스와 번호가 겹치지 않게 하세요(Farsight의 "인스턴스와 게임 시작" 페이지에서 사용 중인 번호를 볼 수 있습니다) |
| `--race` | `1` | 아군 종족: 1 휴먼, 2 오크, 3 언데드, 4 나이트 엘프 |
| `--enemy-race` | `0` | 상대 종족 |
| `--difficulty` | `2` | 컴퓨터 상대 난이도: 2 쉬움, 3 보통, 4 Insane |
| `--speed` | `100` | 게임 배속(퍼센트, 200 = 2배속) |
| `--map` | 설정의 `default_map` | 맵 |
| `--attach` | | 게임을 띄우지 않고, 이미 실행 중인 인스턴스에 연결만 합니다 |
| `--hz` | `5` | 초당 `on_tick` 호출 횟수 |
| `--minutes` | `60` | 최대 실행 시간(분, 실제 시간) |
| `--fair` | | [공정 모드](https://war3ai.com/ko/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/ko/docs/first-bot/): 10줄짜리 최소 Bot에서 시작해 유닛 생산과 공격을 한 단계씩 추가합니다.
  - [LLM에게 맡기기](https://war3ai.com/ko/docs/ai-bot/): 프롬프트 템플릿을 복사하고, 전략을 평범한 말로 설명하세요.

## 자체 점검

```bash
python tools/run_tests.py          # SDK / 레퍼런스 브레인 / 반사 계층 / 콘솔 / 말풍선 / 예제, 스위트마다 하위 프로세스 하나
```

오프라인 테스트는 게임을 띄우지 않아도 됩니다. Farsight "컨트롤 센터"에도 환경 점검이 있어 각 부분이 제대로 설치됐는지 볼 수 있습니다.