# War3AI / OpenWar3

> AI Agent를 위한 워크래프트 III 1.27 오픈 인터페이스. 주입형 런타임이 50 ms마다 맵 전체의 완전한 상태와 이벤트 스트림을 푸시하고, 외부 프로그램은 약 1프레임 지연으로 시맨틱 명령을 내리며, 모든 명령에는 회신과 사유 코드가 있습니다. Python SDK(openwar3)는 모든 것을 게임 속 명칭(4자리 코드, 스킬 오더 이름)으로 표현합니다.

Bot을 작성하는 가장 빠른 길: "15가지 규칙"과 api.json의 API를 읽고, openwar3.Bot을 상속해 on_start(g) / on_tick(g) / on_event(g, ev)를 구현합니다. api.json에 있는 메서드만 사용하세요.
모든 문서를 한 파일로 모은 버전: https://war3ai.com/ko/llms-full.txt

## 시작하기

- [문서 개요](https://war3ai.com/ko/docs/index.md): OpenWar3 문서: 개요와 기능, 빠른 시작·첫 번째 Bot·LLM Bot·API·프로토콜·게이트웨이·MCP, 상황별 시작 페이지 안내.
- [빠른 시작](https://war3ai.com/ko/docs/quickstart.md): start.bat을 더블클릭하면 필요한 것이 모두 자동으로 설치됩니다. Farsight에서 게임 디렉터리를 설정하고 게임을 시작해 예제 Bot이 지휘를 넘겨받는 모습을 확인합니다. 약 15분 걸립니다.
- [첫 번째 Bot](https://war3ai.com/ko/docs/first-bot.md): 10줄짜리 최소 Bot에서 시작해 농부 생산, 인구 확보, 병력 생산, 영웅, 공격을 추가하고 마지막으로 회신을 읽는 법을 익힙니다.

## AI로 Bot 만들기

- [LLM으로 Bot 만들기](https://war3ai.com/ko/docs/ai-bot.md): 프로그래밍을 몰라도 됩니다. 여러분은 어떻게 싸우고 싶은지 명확히 설명하고, 코드는 LLM이 씁니다. 프롬프트 템플릿을 복사해 전략을 설명하고, 실행해 본 뒤 다시 고쳐 달라고 하세요.
- [Agent 자율 반복](https://war3ai.com/ko/docs/agent-loop.md): Coding Agent가 스스로 게임을 돌리고, 결과를 읽고, 코드를 고치고, 다시 돌리게 합니다. 이를 위해 무인 실행 명령 하나, 구조화된 게임 리포트 하나, 명확한 목표 하나가 필요합니다.
- [LLM을 참모로](https://war3ai.com/ko/docs/llm-coach.md): "무엇을 모을지, 일꾼을 어디에 배치할지, 이번 1분은 싸울지 버틸지"를 LLM에게 맡기고, 규칙 계층은 실행과 거부만 담당합니다. 레퍼런스 브레인이 이미 이렇게 동작하며, 이 페이지에서는 그 패턴과 함정을 설명합니다.
- [LLM이 도구를 직접 호출(MCP)](https://war3ai.com/ko/docs/mcp.md): tools/war3_mcp.py는 MCP 서버입니다. Claude Code, Claude Desktop 또는 MCP를 지원하는 어떤 클라이언트든 이 서버를 연결하면, LLM이 코드를 먼저 쓰지 않고도 게임 상황을 보고, 명령을 내리고, 화면에서 플레이어에게 말하고, 카드를 띄워 플레이어에게 묻고, 스크린숏으로 화면을 볼 수 있습니다.

## 핵심 개념

- [멘탈 모델](https://war3ai.com/ko/docs/concepts.md): 스냅샷, 명령, 회신, 이벤트, 틱, 배치. 이 여섯 가지 개념을 이해하면 API가 왜 이런 모양인지, 어떻게 써야 빠른지 알 수 있습니다.
- [15가지 규칙](https://war3ai.com/ko/docs/rules.md): 모두 실제 대전에서 부딪히며 얻은 규칙입니다. Bot을 작성할 때 한 번씩 대조해 보면 디버깅 시간을 대부분 아낄 수 있습니다.
- [공정 모드](https://war3ai.com/ko/docs/fair-mode.md): 게임에 주입된 클라이언트는 맵 전체를 읽을 수 있습니다. 공정 모드는 Bot이 시야 안의 것만 보게 합니다. 사람 플레이어와 같고, 아레나 규칙과도 같습니다.

## 가이드

- [프로 운영 레시피](https://war3ai.com/ko/docs/cookbook.md): 고수의 강점은 대부분 수십 가지 "작은 습관"에서 나옵니다. 이 페이지는 흔히 쓰는 프로 운영을 하나씩 SDK 코드로 옮겼으며, 각 코드는 그대로 on_tick에 붙여 넣을 수 있습니다.
- [예제 Bot](https://war3ai.com/ko/docs/examples.md): 단순한 것부터 복잡한 것까지 네 가지 예제입니다. 모두 바로 실행할 수 있고, 로직 하나하나가 SDK 기능 하나에 대응합니다. 완전한 레퍼런스 브레인도 함께 제공합니다.
- [디버깅과 성능](https://war3ai.com/ko/docs/debugging.md): 틱이 왜 느린지, 명령이 왜 먹히지 않는지, 게임이 왜 멈춰 있는지. 증상별로 점검하고 내장된 실게임 검증 스크립트로 확인합니다.

## 게임플레이 확장

- [RPG 동료](https://war3ai.com/ko/docs/companion.md): RPG / 커스텀 맵에서 플레이어에게 AI 동료를 붙여 줍니다. 따라다니고, 사냥을 돕고, 체력이 낮으면 치유해 주고, 말동무가 되어 줍니다. 네 가지 모드가 있으며, 클래스 하나를 상속하고 속성 몇 개만 바꾸면 나만의 동료가 됩니다.
- [캔버스](https://war3ai.com/ko/docs/canvas.md): 게임 화면에 텍스트 상자, 패널, 진행 바, 이미지, 지면에 붙는 원, 화살표가 달린 경로를 그립니다. 런타임이 매 프레임 직접 그리며 게임 상태를 바꾸지 않으므로 멀티플레이 게임에서도 안전합니다. Python, HTTP, 공유 메모리 직접 쓰기를 모두 지원합니다.
- [UI와 입력](https://war3ai.com/ko/docs/ui-input.md): 캔버스 위의 버튼과 선택 카드를 클릭할 수 있고, 마우스를 올리면 자동으로 강조됩니다. 단축키를 등록하고, 지면을 클릭해 위치를 고르고, 마우스가 가리키는 곳을 읽고, 로컬 플레이어가 무엇을 선택했는지 알 수 있습니다. 클릭, 단축키, 스킬 시전, 채팅 전문, 플레이어 퇴장이 모두 이벤트 스트림에 들어옵니다.
- [JASS 채널](https://war3ai.com/ko/docs/jass.md): 맵 제작자가 쓸 수 있는 JASS 함수 1291개를 이제 게임 밖에서 이름으로 바로 호출할 수 있습니다. 유닛 생성, 속성 변경, 특수 효과, 패널, 대화 상자, 사운드, 카메라, 전장의 안개…… Farsight 콘솔, 명령줄, HTTP, Python 네 가지 방법으로 쓸 수 있습니다.
- [게임플레이 모드](https://war3ai.com/ko/docs/mods.md): 스킴은 여러분 대신 싸우는 AI일 뿐 아니라 하나의 규칙이 될 수도 있습니다. 여러분은 게임 창에서 직접 플레이하고, 모드는 시작 배치, 몬스터 생성, 보상, 화면의 버튼과 선택 카드, 승패 판정을 맡습니다. openwar3.Mod를 상속하면 파일 하나가 곧 하나의 게임 방식입니다.

## 도구

- [Farsight 콘솔](https://war3ai.com/ko/docs/console.md): 로컬 웹 콘솔이자 유일한 진입점입니다. 게임 디렉터리 설정, 각 서비스 시작과 중지, 게임 인스턴스 시작과 중지, 다음 게임 설정, AI의 생각 보기, 수동 명령, 중계 연출, 대전 기록을 제공합니다.
- [AI 스킴](https://war3ai.com/ko/docs/schemes.md): 스킴 하나가 곧 완전한 AI 하나입니다. Farsight에서 클릭 한 번으로 바꾸고, 진행 중인 게임도 즉시 새 AI가 넘겨받을 수 있습니다. zip으로 내보내 공유하고, 다른 사람의 스킴을 가져와 테스트하며, 스킴마다 전적이 자동으로 집계됩니다.
- [말풍선과 로컬 모델](https://war3ai.com/ko/docs/speech.md): 게임 속 어떤 유닛이든 원하는 신분으로 머리 위에 대화 말풍선을 띄웁니다. 로컬 LLM을 연결하면 한 마디가 들어가고 답변 한 마디가 유닛 머리 위에 나타납니다.
- [게이트웨이](https://war3ai.com/ko/docs/gateway.md): WebSocket / JSON 게이트웨이: Python SDK로 호출할 수 있는 공개 API를 JS, C#, Go, Rust, 브라우저 페이지, 다른 컴퓨터의 프로그램에서도 호출할 수 있습니다. 세 가지 역할, JS 클라이언트와 브라우저 데모 페이지 포함. 지연은 고속 레인에 약 1 ms가 더해지는 정도입니다.

## 레퍼런스

- [W3P 프로토콜](https://war3ai.com/ko/docs/protocol.md): 런타임과 외부 프로그램 사이의 모든 계약입니다. 공유 메모리 여덟 블록, 월드 상태 읽기, 이벤트 읽기, 명령 내리기, 회신, 레인 역할, 캔버스, UI와 입력. Python 이외의 언어로 연동하려면 이 페이지를 보세요.
- [회신과 사유 코드](https://war3ai.com/ko/docs/reason-codes.md): 모든 명령의 회신에는 상태 코드와 사유 코드가 담깁니다. Bot과 Agent가 스스로 오류를 고치는 근거로, "왜 안 됐는가"를 기계가 읽을 수 있는 숫자로 바꿔 줍니다.
- [데이터 출처](https://war3ai.com/ko/docs/data-sources.md): 데이터 종류별 출처와 정밀도입니다. "뭔가 이상해 보이는" 일이 생기면 이 페이지부터 확인하세요.

## 기타

- [자주 묻는 질문](https://war3ai.com/ko/docs/faq.md): 핵인가요? 어떤 버전을 지원하나요? AI는 무엇을 보고 무엇을 할 수 있나요? 프로그래밍을 몰라도 쓸 수 있나요?……
- [이용 범위](https://war3ai.com/ko/docs/legal.md): 할 수 있는 일과 할 수 없는 일, 이 웹사이트의 방문 통계, 그리고 상표와 서드파티 라이선스 안내입니다. 이 프로젝트를 사용하면 이 범위를 준수하는 데 동의한 것으로 간주합니다.

## API

- [api.json](https://war3ai.com/ko/api.json): 전체 103개 Game 메서드(name / category / status / latency / mechanism / signature / doc), 코드에서 생성
- [API 카탈로그(웹)](https://war3ai.com/ko/api/): 같은 데이터의 검색 가능한 버전

## 선택

- [llms-full.txt](https://war3ai.com/ko/llms-full.txt): 전체 문서 + API 카탈로그를 한 번에 읽기
- [이용 범위](https://war3ai.com/ko/docs/legal.md): 자신이 합법적으로 소유한 클라이언트에서만 사용. Battle.net이나 안티치트가 있는 어떤 서버에서도 사용 불가