문서 개요

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

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

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

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

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

상황에 맞는 경로 고르기

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

저장소 구성

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 프로토콜 하나만 있습니다. Python SDK가 가장 간편하지만, 다른 언어로 프로토콜을 따라 연결해도 됩니다.

API의 “실측 상태”란

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

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