AI 스킴

스킴 하나 = 완전한 AI 하나: 폴더 하나 + 매니페스트 scheme.json + 코드. 게임 인스턴스마다 스킴을 하나씩 고르며, Farsight에서 클릭 한 번으로 바꿀 수 있고 진행 중인 게임도 즉시 새 스킴이 넘겨받습니다.

다른 사람이 공유한 스킴을 가져오면 별도의 영역에 들어가므로 여러분의 스킴과 서로 영향을 주지 않습니다. 고치고 싶다면 “내 스킴으로 복사”하세요.

schemes/
  mine/<id>/          내 스킴: 직접 쓴 것, 또는 다른 스킴에서 복사해 고친 것(마음대로 수정, 다음 게임부터 적용)
  installed/<id>/     설치됨: 다른 사람이 공유한 zip을 여기에 풂(처음 실행하기 전에 신뢰 확인 필요)
brains/xwar3/         내장: 레퍼런스 브레인(완전한 AI)
brains/examples/      내장: 교육용 예제 4개 hello / rush / macro / micro, 동료 예제 buddy, 게임플레이 모드 2개(영웅 로그라이크, 무한 디펜스)

스킴이 꼭 여러분 대신 싸우는 AI일 필요는 없습니다. kind: mod인 스킴은 하나의 게임 규칙입니다. 여러분이 직접 플레이하고 스킴은 과제를 냅니다. 게임플레이 모드를 참고하세요.

Farsight에서 사용하기

“AI 스킴” 페이지(왼쪽 사이드바 “시스템 → AI 스킴”):

작업	하는 일
스킴 가져오기(zip)	installed/에 설치. 같은 id가 이미 설치되어 있으면 교체할지 물음(교체하면 신뢰를 다시 확인해야 함)
인스턴스에 적용…	인스턴스 선택 + “즉시 적용”(현재 AI를 멈추고 새 스킴이 이 게임을 넘겨받음) 또는 “다음 테스트 시작부터 적용”
내 스킴으로 복사	mine/에 복사본을 만들고, 작성자는 “나”, 버전은 0.1.0으로 기록하며, 어느 스킴의 어느 버전에서 복사했는지도 기록
zip 내보내기	<id>-<버전>.zip으로 묶음. 다른 사람에게 보내면 그것이 곧 공유
폴더 열기	탐색기에서 스킴 폴더를 열어 코드를 직접 수정
신뢰	다른 사람의 스킴은 처음 실행하기 전에 반드시 눌러야 함(아래 “신뢰와 보안” 참고)
최근 전적	이 스킴의 게임별 승패, 경기 시간, 종료 사유
삭제	“내 스킴”과 “설치됨”만 삭제 가능. 인스턴스가 사용 중이면 삭제 불가

인스턴스 카드에도 “AI 스킴” 줄이 추가되었습니다. 드롭다운에서 스킴을 고르고 → “전환(즉시 적용)”. 인스턴스가 실행 중이 아닐 때는 버튼 이름이 “선택”이며, 다음에 “테스트 시작”을 누르면 그 스킴으로 AI를 시작합니다.

매니페스트 scheme.json

{
  "format": 1,
  "id": "fast-rush",
  "name": "3분 러시",
  "version": "1.2.0",
  "author": "홍길동",
  "description": "이 AI가 어떤 전략을 쓰는지 한 문장으로 설명",
  "entry": "rush_bot.py",
  "class": "RushBot",
  "fair": true,
  "hz": 5,
  "races": ["human", "orc"],
  "license": "MIT"
}

필드	필수	설명
id	✔	영문 소문자, 숫자, -, _. 2 ~ 41자
entry	✔	스킴 폴더 안의 .py 파일 하나(절대 경로 불가, .. 불가)
kind		기본값 bot(openwar3.Bot의 하위 클래스, 여러분 대신 싸움). mod = 게임플레이 모드(openwar3.Mod의 하위 클래스. 항상 공정 모드를 쓰지 않으며, 대전 규칙으로 승패를 판정하지 않음)
class		진입 파일 안의 Bot(또는 Mod) 하위 클래스 이름. 생략하면 진입 파일의 마지막 openwar3.Bot 하위 클래스를 사용
fair		기본값 true: 시야 안의 것만 보며, 아레나와 같은 규칙. false = 맵 전체가 보이며, 이때만 JASS 채널을 쓸 수 있음(동료에게 필요)
judge		기본값 true: 대전 규칙으로 승패 판정. RPG / 동료 스킴은 false
hz		on_tick을 초당 몇 번 호출할지. 기본값 5
format		매니페스트 형식 버전. 현재 1. 이 컴퓨터의 OpenWar3보다 새 버전이면 거부하고 업데이트를 안내
기타		name, version, author, description, races, license, homepage, forked_from은 표시용

스킴 폴더는 Python 모듈 검색 경로에 추가되므로, 진입 파일에서 같은 폴더의 다른 파일을 import할 수 있습니다. 서드파티 패키지(numpy, torch……)는 자동으로 설치되지 않습니다 — 무엇이 필요한지 description에 분명히 적으세요.

가장 작은 스킴은 파일 두 개면 충분합니다:

# my_bot.py
from openwar3 import Bot

class MyBot(Bot):
    def on_tick(self, g):
        for w in g.idle_workers():
            mine = g.nearest(g.gold_mines(), w)
            if mine:
                g.gather(w, mine)

{"id": "my-first", "name": "나의 첫 AI", "entry": "my_bot.py"}

schemes/mine/my-first/에 넣고 Farsight를 새로 고치면 바로 보입니다. 더 간편한 출발점: “내장”에서 예제를 하나 골라 “내 스킴으로 복사”를 누르세요.

실행 방식과 전적

스킴은 스킴 러너가 실행합니다(Farsight의 “테스트 시작 / 전환”이 띄우는 것이 바로 이것입니다).

python tools/run_scheme.py --inst 20 --scheme builtin/micro --hours 6

• 인스턴스마다 상주하는 감독 프로세스가 하나 있고, 게임마다 자식 프로세스를 하나 띄워 스킴을 실행합니다. 스킴 코드가 죽어도 감독 프로세스는 영향을 받지 않으며, “내 스킴”의 코드를 고치면 다음 게임부터 자동으로 새 코드를 씁니다.
• 게임이 끝날 때마다 전적을 한 줄 기록합니다: 스킴, 버전, 작성자, 승패, 사유, 게임 시간, 오류 횟수. Farsight의 승률은 여기서 집계합니다.

승패 판정 방법:

상황	기록
상대 건물이 전부 없어짐	승
아군 건물이 전부 없어짐(병력이 살아 있어도 마찬가지 — 대전에서는 이렇게 패배를 판정함)	패
아군 유닛이 전부 없어짐	패
Farsight에서 수동으로 종료 / 중지	미정
전환 시점에 이 게임이 이미 60 게임 초 이상 진행됨(중간에 넘겨받음)	따로 집계하며 승률에 넣지 않음
게임 시계가 오랫동안 멈춤	미정

승패가 가려지면 러너가 결과 화면을 닫고 “다음 게임 설정”에 따라 다음 게임을 시작하며, 스킴이 이어서 넘겨받습니다 — 밤새 켜 두고 전적을 쌓을 수 있습니다. 일시정지는 종료가 아닙니다. 일시정지 중에도 Bot은 평소처럼 돌아가고, 게임 시계만 멈춥니다.

신뢰와 보안

스킴은 코드이며, 실행되면 여러분 본인과 같은 권한을 가집니다(파일을 읽고 쓰고, 네트워크에 접속할 수 있음). 그래서:

• installed/의 스킴은 기본적으로 신뢰되지 않으며, 여러분이 “신뢰”를 누를 때까지 Farsight와 러너 모두 실행을 거부합니다.
• 같은 id의 스킴을 교체 설치하면 신뢰가 초기화됩니다(새 버전 = 새 코드).
• 가져올 때 검사합니다: zip은 50 MB 이하, 파일 2000개 이하. 절대 경로와 ..는 허용하지 않습니다(스킴 폴더 밖에 쓰는 것을 방지). 매니페스트가 올바르지 않거나 진입 파일이 없으면 바로 거부합니다.

API(스크립트용)

API	설명
GET /api/schemes	스킴 목록 + 전적 + 인스턴스별로 선택된 스킴과 실행 중인 스킴
GET /api/schemes/results?ref=	한 스킴의 최근 30게임
POST /api/schemes/import	zip 가져오기
GET /api/schemes/export?ref=	zip 다운로드
POST /api/schemes/fork	내 스킴으로 복사
POST /api/schemes/trust	신뢰
DELETE /api/schemes?ref=	삭제(인스턴스가 사용 중이면 거부)
POST /api/instances/{n}/scheme	인스턴스의 스킴 변경: 이 게임을 즉시 넘겨받거나, 다음 테스트 시작부터 적용

Python에서는 라이브러리를 바로 쓰면 됩니다: from openwar3 import schemes(list_schemes, install_zip, export_zip, fork, trust, stats……).

앞으로: 스킴 웹사이트

내보낸 zip이 곧 공유 단위이므로, 웹사이트는 그 바깥에 한 겹만 더하면 됩니다. Farsight에서 클릭 한 번으로 업로드하고, 웹사이트에서 받은 스킴은 “스킴 가져오기”와 완전히 같은 검사를 거치며 마찬가지로 신뢰를 확인해야 합니다. 전적 보고를 선택할 수 있고, 웹사이트는 버전별로 승률을 집계합니다. Farsight의 “스킴 웹사이트에 공유” 버튼은 이미 자리를 마련해 두었습니다. 진행 상황은 로드맵을 보세요.