빠른 시작 - War3AI

필요한 것

	요구 사항	설명
시스템	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가 필요 없습니다.

설치

코드 받기
```
git clone https://github.com/OPENXXAI/OpenWar3AI.git
```
또는 압축 파일을 내려받아 풀어도 됩니다. 런타임(주입 DLL과 런처)은 저장소에 함께 들어 있으므로 따로 내려받지 않아도 됩니다.
start.bat 더블클릭하기

처음 실행하면 다음을 알아서 합니다.
- Python 3.13을 내려받습니다.
- Python 패키지를 설치하고, 런타임 파일을 확인한 뒤 설치합니다.
- AMAI를 내려받아 레퍼런스 브레인이 쓰는 전략 데이터를 생성합니다(AMAI는 자체 라이선스이며, 생성물은 git에 포함되지 않습니다. 실패해도 레퍼런스 브레인에만 영향이 있습니다).
- Farsight의 첫 화면인 “컨트롤 센터” http://127.0.0.1:8866을 엽니다.
단계마다 결과를 출력하고, 실패한 단계는 어떻게 보완하면 되는지 알려 줍니다. 그다음부터는 더블클릭할 때마다 1~2초 정도 확인만 하고 Farsight를 엽니다.

검은 창은 몇 초 뒤 저절로 닫힙니다. Farsight는 백그라운드에서 계속 실행되며, 브라우저를 닫아도 멈추지 않습니다.
컨트롤 센터에서 게임 디렉터리 설정하기

컨트롤 센터 맨 위에서 “자동 찾기”를 누르거나, “찾아보기…”로 워크래프트 III 디렉터리를 직접 고를 수 있습니다. Farsight는 게임 버전을 확인하고 본인의 게임에서 데이터를 추출합니다(유닛 테이블, 스킬, 아이템, 상성표…… Blizzard의 파일은 코드와 함께 배포하지 않습니다).

버전이 1.27a가 아니면 알려 줍니다. 맵과 다음 게임 설정은 모두 이 디렉터리를 기준으로 합니다(<게임 디렉터리>\Maps 아래 모든 폴더의 맵을 고를 수 있습니다). 나중에 디렉터리를 바꾸려면 “설정” 페이지에서 바꿉니다.
게임을 시작하고 예제 Bot에게 맡기기

가장 간단한 방법은 Farsight의 “인스턴스와 게임 시작” 페이지에서 인스턴스 번호 하나를 체크하고, AI 스킴을 고른 뒤 “테스트 시작”을 누르는 것입니다. 명령줄로도 할 수 있습니다:
```
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

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 인자

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`		공정 모드
`--player`		몇 번 플레이어로서 지휘할지(AI 대 AI일 때 사용)

--minimize로 게임을 띄우지 마세요. 창이 최소화되어 있으면 게임 시뮬레이션이 멈춰 있어서(시계가 흐르지 않음) Bot이 게임 시작을 끝없이 기다리게 됩니다.

play.py를 거치지 않고 SDK 명령줄로 이미 실행 중인 인스턴스에 바로 연결할 수도 있습니다:

python -m openwar3 run brains/examples/hello_bot.py --inst 5     # Bot 실행
python -m openwar3 status --inst 5                              # 연결해서 스냅샷 / 고속 레인 상태 출력
python -m openwar3 catalog                                      # API 목록 출력

실행에 성공했다면

첫 번째 Bot 작성하기 10줄짜리 최소 Bot에서 시작해 유닛 생산과 공격을 한 단계씩 추가합니다. LLM에게 맡기기 프롬프트 템플릿을 복사하고, 전략을 평범한 말로 설명하세요.

자체 점검

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

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