# 문서 개요

> OpenWar3 문서: 개요와 기능, 빠른 시작·첫 번째 Bot·LLM Bot·API·프로토콜·게이트웨이·MCP, 상황별 시작 페이지 안내.

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

**OpenWar3**는 War3AI의 오픈 인터페이스 계층입니다. 워크래프트 III 1.27에 주입되는 런타임과 Python SDK로 구성됩니다.

- 런타임은 **50 ms**마다 맵 전체의 완전한 상태를 공유 메모리에 푸시합니다. 모든 플레이어의 자원과 식량, 모든 유닛의 체력/마나, 오더, 현재 공격 대상, 스킬 쿨다운, 버프, 인벤토리, 바닥의 아이템, 나무, 생산 대기열, 낮과 밤까지 담깁니다. **이벤트 스트림**도 있습니다. 유닛 등장과 사망, 피해 한 번 한 번, 생산 완료……
- 외부 프로그램은 **약 1프레임** 지연으로 **시맨틱 명령**을 내립니다. 이동, 공격, 채집, 건설, 훈련, 시전, 스킬 습득, 부활, 아이템 사용, 구매…… 모든 명령에는 **회신**이 있어 엔진이 수락했는지, 거부했다면 사유 코드가 무엇인지 알려 줍니다.
- 여러분은 "무엇을 할지"만 말하면 됩니다. 유닛은 4자리 코드로, 스킬은 오더 이름으로 지정하며 게임 속 명칭과 같습니다. "어떻게 할지"는 런타임이 맡습니다.

따라서 LLM에는 저수준 지식도, 화면을 보는 능력도 필요 없습니다. 문서를 읽고 나면 운영도 하고 전투도 하는 Bot을 작성할 수 있고, 대전에 나간 뒤에는 회신과 이벤트를 보고 스스로 수정합니다.

대전만이 아닙니다. [캔버스](https://war3ai.com/ko/docs/canvas/)로 게임 화면 위에 나만의 패널과 표시를 그릴 수 있고, [UI와 입력](https://war3ai.com/ko/docs/ui-input/)을 쓰면 화면에 그린 버튼을 클릭할 수 있고 단축키도 반응하며, [JASS 채널](https://war3ai.com/ko/docs/jass/)로 게임 속 함수 1291개를 외부에서 호출할 수 있고, RPG 맵에서는 나만의 [AI 동료](https://war3ai.com/ko/docs/companion/)를 곁에 둘 수도 있습니다. 완성한 AI는 [스킴](https://war3ai.com/ko/docs/schemes/)으로 만들어 클릭 한 번으로 전환하고, 내보내 공유할 수 있습니다. 새로운 게임 방식 하나를 통째로 [게임플레이 모드](https://war3ai.com/ko/docs/mods/)로 작성할 수도 있습니다.

Python을 쓰지 않고도 연결할 수 있습니다. [게이트웨이](https://war3ai.com/ko/docs/gateway/)를 쓰면 어떤 언어든, 브라우저 페이지든 WebSocket / JSON으로 같은 API를 호출할 수 있고, [MCP 서버](https://war3ai.com/ko/docs/mcp/)를 쓰면 Claude Code 같은 Agent가 도구를 직접 호출해 게임 상황을 보고 명령을 내립니다.

  - [빠른 시작](https://war3ai.com/ko/docs/quickstart/): 환경을 설치하고 명령 한 줄로 게임을 띄워 예제 Bot이 조종하는 모습을 확인합니다.
  - [LLM으로 Bot 만들기](https://war3ai.com/ko/docs/ai-bot/): 프로그래밍을 몰라도 됩니다. 프롬프트를 복사하고 전략을 설명한 뒤 Agent에게 맡기세요.
  - [멘탈 모델](https://war3ai.com/ko/docs/concepts/): 스냅샷, 명령, 회신, 이벤트, 틱. Bot을 작성하기 전에 5분만 투자해 읽어 보세요.
  - [API 카탈로그](https://war3ai.com/ko/api/): 전체 API. 모두 실측 상태, 지연 등급, 내부 메커니즘이 표시되어 있습니다.

## 상황에 맞는 경로 고르기

| 여러분은 | 여기부터 읽기 | 그다음 |
|---|---|---|
| 워크래프트는 할 줄 알지만 프로그래밍은 모름 | [빠른 시작](https://war3ai.com/ko/docs/quickstart/) → [LLM으로 Bot 만들기](https://war3ai.com/ko/docs/ai-bot/) | 문제가 생기면 [자주 묻는 질문](https://war3ai.com/ko/docs/faq/) |
| Python을 다룰 줄 앎 | [첫 번째 Bot](https://war3ai.com/ko/docs/first-bot/) → [멘탈 모델](https://war3ai.com/ko/docs/concepts/) → [15가지 규칙](https://war3ai.com/ko/docs/rules/) | [프로 전략 레시피](https://war3ai.com/ko/docs/cookbook/), [예제 Bot](https://war3ai.com/ko/docs/examples/) |
| Coding Agent / 자동화를 만드는 중 | [Agent 자율 반복](https://war3ai.com/ko/docs/agent-loop/) | [회신과 사유 코드](https://war3ai.com/ko/docs/reason-codes/), [`llms-full.txt`](https://war3ai.com/ko/llms-full.txt) |
| LLM이 게임 중에 의사결정을 하게 하고 싶음 | [LLM 참모](https://war3ai.com/ko/docs/llm-coach/) | [말풍선과 로컬 모델](https://war3ai.com/ko/docs/speech/) |
| Agent가 직접 조작하게 하고 싶음(Claude Code 등) | [LLM이 도구를 직접 호출(MCP)](https://war3ai.com/ko/docs/mcp/) | [UI와 입력](https://war3ai.com/ko/docs/ui-input/) |
| 다른 언어 사용(JS, C#, Go, Rust……) | [게이트웨이](https://war3ai.com/ko/docs/gateway/) | 더 낮은 계층: [W3P 프로토콜](https://war3ai.com/ko/docs/protocol/) |
| 여러 사람의 AI끼리 대결시키고 싶음 | [공정 모드](https://war3ai.com/ko/docs/fair-mode/) | [아레나](https://war3ai.com/ko/arena/) |
| RPG / 커스텀 맵에서 나만의 플레이를 만들고 싶음 | [게임플레이 모드](https://war3ai.com/ko/docs/mods/) | [UI와 입력](https://war3ai.com/ko/docs/ui-input/), [캔버스](https://war3ai.com/ko/docs/canvas/), [JASS 채널](https://war3ai.com/ko/docs/jass/), [RPG 동료](https://war3ai.com/ko/docs/companion/) |
| 내 AI를 다른 사람과 공유하고 싶음 | [AI 스킴](https://war3ai.com/ko/docs/schemes/) | [Farsight 콘솔](https://war3ai.com/ko/docs/console/) |

## 저장소 구성

```text
start.bat       유일한 진입점: 처음부터 배포 + Farsight 열기. stop.bat은 모두 완전히 중지
sdk/python/     인터페이스 계층. openwar3/가 외부용 파사드(Game + Bot)이며 여기서 시작합니다
brains/         의사결정 계층
  examples/       hello_bot(경제) → rush_bot(병력 생산) → macro_bot(운영) → micro_bot(컨트롤 + 크립 사냥); buddy(RPG 동료);
                  mod_hero_roguelike / mod_endless_defense(게임플레이 모드)
  xwar3/          레퍼런스 브레인: 전략 레이어(초 단위) + 반사 레이어(프로세스 4개) + 승률 모델
console/        Farsight 웹 콘솔(FastAPI + React)
gateway/        게이트웨이(WebSocket / JSON) + JS 클라이언트 + 브라우저 데모 페이지
director/       자동 카메라 연출, 머리 위 체력 바
speech/         머리 위 채팅 말풍선 + 로컬 LLM
runtime/        다중 인스턴스 오케스트레이션(게임마다 설정대로 재시작)
data/           order-ids.txt, 자신의 게임에서 데이터를 추출하는 도구
schemes/        내 AI 스킴(mine/)과 다른 사람이 공유한 스킴(installed/), 저장소에는 포함되지 않음
tools/          play.py(명령 한 줄로 게임 시작), run_scheme.py(스킴 실행기), war3_mcp.py(MCP 서버), run_tests.py, 실게임 검증 스크립트
docs/           API 카탈로그 api.json(코드에서 생성), 프로토콜, 매뉴얼
```

런타임과 여러분의 코드 사이에는 버전이 붙은 [W3P 프로토콜](https://war3ai.com/ko/docs/protocol/) 하나만 있습니다. Python SDK가 가장 간편하지만, 다른 언어로 프로토콜을 따라 연결해도 됩니다.

## API의 "실측 상태"란

API 카탈로그의 모든 API에는 다음 세 상태 중 하나가 표시됩니다.

- **실게임 검증 완료**: 내부 경로(액션 번호, 파라미터 형태, 다시 읽어 온 효과)가 실제 대전에서 검증되었고, 검증 스크립트가 이를 지키고 있습니다.
- **실험**: 새로 추가된 API로, 테스트 인스턴스에서 동작을 확인했고 항목별 실게임 검증을 진행 중입니다. 사용할 수는 있지만 API 세부 사항은 바뀔 수 있습니다.
- **추정 / 실측 미완**: 내부 메커니즘은 엔진 자체의 방식(예: JASS의 동등 함수)을 그대로 따르지만, 아직 대전에서 항목별로 검증하지는 않았습니다. 사용하기 전에 회신부터 확인하세요.

> **참고**
>
> 현재는 **워크래프트 III 1.27**(프로즌 쓰론)만 지원합니다. 1.24 ~ 1.28은 같은 엔진 구조이며, 다중 버전 지원은 [로드맵](https://war3ai.com/ko/roadmap/)의 P4 단계에 있습니다. 1.29 이후 버전과 리포지드는 다른 엔진이므로 지원 약속 범위에 포함되지 않습니다.