rmalde/minecraft-agent

Astra planner and JEV controller for Minecraft, with native recording, tested routes, and run verification.

Astra 및 JEV Minecraft 에이전트

개요 – 두 가지 언어 모델 서비스를 결합하여 Minecraft Java 1.16.5 스피드런(엔더 드래곤 전투)을 완전히 플레이하는 오픈소스 봇:

Astra(또는 이전 버전의 Sol)는 플래너 역할: 현재 세계 상태를 기반으로 높은 수준의 목표, 아이템 목표 및 웨이포인트를 설정합니다.
JEV는 플래너의 목표와 상세한 게임 관찰을 소비하고 제한된 집합(이동, 채굴, 제작, 먹기, 전투 등)에서 단일 구체적 행동을 선택합니다.

봇은 표준 플레이어 프로토콜(Mineflayer 라이브러리 경유)로 바닐라 서버와 통신합니다. 숨겨진 읽기 전용 Minecraft 클라이언트가 비디오 캡처를 위해 게임 상태를 미러링합니다. 봇은 게임 규칙이나 엔티티를 변경하지 않습니다.

작동 방식

구성 요소	역할
서버	공식 바닐라 1.16.5 서버(`server/`에 제공). 사용자 정의 Java 센서(`DragonObserver`)를 실행하여 로컬 HTTP 엔드포인트로 드래곤 머리 위치를 노출합니다.
Mineflayer	플레이어 연결, 경로 찾기 및 저수준 동작(파기, 배치, 공격, 상자 열기 등)을 구현하는 Node‑JS 라이브러리.
플래너(Astra / Sol)	OpenRouter(`/api/v1/chat/completions`)를 통해 호출. 전체 구조화된 관찰(블록, 인벤토리, 좌표)을 수신하고 목표와 웨이포인트를 반환합니다.
JEV	Typesafe의 결정 모델(`typesafe/jev-1.13`)을 `/api/alpha/decisions`로 액세스. 현재 관찰에서 하나의 합법적 행동을 선택합니다.
네이티브 클라이언트 및 레코더	소스에서 빌드된 숨겨진 Minecraft 클라이언트가 세계를 렌더링하고 모델 이름, 시간, 좌표, 목표 및 선택된 행동을 표시하는 오버레이와 함께 960 × 540 @ 20 fps 비디오를 캡처합니다.
글루 스크립트	`nether-agent.mjs`가 루프를 조정: 센서 읽기 → 플래너에 전송 → 플래너 출력 및 관찰을 JEV에 전송 → Mineflayer를 통해 선택된 행동 실행.

모든 통신은 텍스트 기반입니다. 모델은 스크린샷을 볼 수 없습니다. 봇은 로드된 청크의 블록 데이터를 볼 수 있으며 시드와 알려진 포털 좌표가 제공됩니다.

빠른 시작

전제 조건
- Node ≥ 18, Java 17, Python 3, Google Secret Manager에 저장된 로컬 OpenRouter API 키.
- Minecraft Java 1.16.5 클라이언트(리포지토리에 포함되지 않음).

설치

npm install               # Node 종속성
cd native-client && python3 install.py && ./build.sh

서버 시작

cd server && ./start-server.sh   # 제공된 시드로 server.jar 시작

새 에이전트 실행 (NEW_RUN을 고유한 이름으로 교체)
```
PLANNER_MODEL=openai/gpt-6-astra RUN_ID=NEW_RUN \
NATIVE_VIEW=1 WAIT_NATIVE=1 NATIVE_RECORD=1 \
DRAGON_SENSOR_URL=http://127.0.0.1:3093 \
node nether-agent.mjs NEW_RUN
```
스크립트는 첫 번째 행동 전에 숨겨진 네이티브 클라이언트(python3 native-client/launch.py)를 기다립니다.
검증
```
node --test evidence.test.mjs native-mirror.test.mjs ...
```
테스트는 실행이 필요한 승리 증거(victory.json)를 생성하고 모든 정책 검사가 통과했는지 확인합니다.

성공 증거

README에는 전체 실행(nether‑final‑08)이 기록되어 있으며, 6번의 침대 폭발로 엔더 드래곤을 처치하고, 전체 체력으로 포털을 나와 8분 43초에 완료 – 이전 최고보다 40% 빠름.
로그(runs/<run>/events.jsonl)에는 모든 모델 요청/응답, 선택된 행동 및 게임 결과가 포함됩니다.
로컬에 저장된 비디오(full-playthrough-banner.mp4)는 숨겨진 클라이언트 렌더링, 오버레이 HUD 및 최종 승리 이벤트를 보여줍니다.
자동화된 테스트(evidence.test.mjs, combat‑lab 스크립트)는 드래곤 사망 조건과 세계 상태가 기록된 증거와 일치하는지 검증합니다.

범위 및 제한 사항

스피드런 전용 – 경로, 시드 및 세계 구성이 고정되어 있습니다. 봇은 범용 Minecraft AI가 아닙니다.
읽기 전용 센서 – 봇은 아이템을 부여하거나, 체력을 수정하거나, 드래곤 AI를 변경할 수 없습니다. 일반 플레이어 행동만 발행합니다.
모델 비용 – 각 실행은 약 35회의 플래너 호출과 130회의 JEV 결정을 수행합니다. OpenRouter 크레딧이 필요합니다.
플랫폼 – 개발 스크립트는 macOS를 대상으로 합니다. 다른 OS는 수동 경로 조정이 필요합니다.

다음 단계

optimization/nether/config.json – 고정 경로 및 웨이포인트.
observer/DragonObserver.java – 드래곤 머리 센서의 소스.
combat-lab/ – 침대 폭발 전투 로직을 위한 격리된 테스트 하네스.
링크된 TypeSafe 및 OpenAI 문서에서 더 깊은 모델 API 세부 정보를 확인하세요.

결론 – 이 리포지토리는 대규모 언어 모델(Astra)과 타입이 지정된 결정 모델(JEV)을 사용한 구조화된 상태 제어를 보여주는 재현 가능하고 완전 자동화된 Minecraft 스피드런 봇을 제공합니다. 이는 복잡하고 실시간 가상 환경에서 작동하는 LLM 기반 구현 에이전트의 구체적인 예입니다.