MinecraftBot

Minecraft Java Edition 자율 플레이어로, Mineflayer, MCP 및 검증 가능한 Skill 상태 머신을 기반으로 합니다. 독립적인 게임 캐릭터로 서버에 접속하며, 주로 프로토콜 수준의 구조화된 데이터로 세계를 인식하고 탐색, 채집, 제작, 전투, 건설 및 장기 작업을 지속적으로 실행할 수 있습니다.

독립적인 Demiurge 데스크톱 에이전트와 함께 사용하는 것을 권장합니다. Demiurge는 캐릭터 설정, 현재 LLM, 장기 기억, 데스크톱 이미지 대화 및 상위 의사 결정을 제공하고, MinecraftBot은 서버 연결, 구조화된 인식 및 안정적인 실행을 담당합니다. 두 프로젝트는 서로 독립적이며 Minecraft 클라이언트에 Mod 설치가 필요하지 않습니다.

두 가지 실행 모드

프로젝트는 .env, API Key, 실행 로그, SQLite 저장 데이터베이스 또는 로컬 Minecraft 데이터를 커밋하지 않습니다.

Related MCP server: Minecraft Dedalus MCP

구현된 기능

• 오프라인 또는 마이크로소프트 신분 인증 연결, 자동 재연결, 고정 캐릭터 이름.

• 플레이어, 인벤토리, 장비, 엔티티, 블록, 시간, 날씨 및 이벤트 인식.

• 장면 요약, 공간 위치 기억, 작업 영속화 및 연결 끊김 복원.

• 외부 LLM API로 계획 수립, 실패 복구, 엄격한 JSON 검증.

• 정확한 아이템·블록·몹·제작법 데이터베이스 및 재귀적 재료 계산.

• 로컬 공략 RAG로 Markdown/TXT 공략 가져오기.

• Skill 리소스 잠금, 우선순위 선취, 타임아웃, 취소, 진행, 재시도, 결과 검증.

• 탐색, 이동, 반복, 채집, 배치, 강제, 제련, 전투, 탈출, 섭취, 전달, 상자 입출금, 건설 및 탐험.

• 낮은 체력 탈출, 끼임, 인벤토리 가득, 도구 내구도 부족 모니터링.

• SQLite 기억, JSON 상태 인터페이스, 구조화된 로그.

• 깊이 버퍼 기하 재투영, 잔차 영역 클러스터링, 알려진 변화 마스크 및 선택적 VLM 분석 인터페이스.

• Mock LLM 및 Mock Executor를 통해 MC 서버나 API Key 없이 플레이어 시스템을 테스트할 수 있습니다.

• MCP stdio 도구/리소스, 게임 이벤트 알림 및 Demiurge 캐릭터 설정, 대화 및 장기 기억 피드백 루프.

실행 구조

PCL（FuQiang） ───────公网──────> 腾讯云 Minecraft Server
                                      ↑
本机 Demiurge ──MCP stdio──> Mineflayer AI_Player
      │ 当前角色/长期记忆           │ 结构化感知/RAG/Skill Runtime
      └────唯一 LLM 规划与对话──────┘

환경 요구 사항

• Minecraft Java 에디션 서버.

• Node.js 22.13 이상.

• pnpm 10 이상 코어팩을 통한 활성화도 가능.

• MCP 모드에는 Demiurge 설정이 필요하며, 독립 실행 모드에서는 OpenAI-compatible API가 필요합니다.

로컬 설치

corepack enable
pnpm install
cp .env.example .env

독립 실행 시 다음은 신법으로 수정합니다:

MC_HOST=127.0.0.1
MC_PORT=25565
MC_USERNAME=AI_Player
MC_AUTH=offline
MC_OWNER=FuQiang

LLM_MODE=api
LLM_BASE_URL=https://你的API地址/v1
LLM_API_KEY=你的密钥
LLM_MODEL=你的模型名

먼저 오프라인 시험 운영:

pnpm typecheck
pnpm test
pnpm smoke

개발 모드 구동:

pnpm dev

프로덕션 모드:

pnpm build
NODE_ENV=production pnpm start

Demiurge 사용(권장)

각각의 독립 프로젝트를 빌드합니다:

# 本项目
pnpm install --frozen-lockfile
pnpm build

# Demiurge（单独克隆）
git clone https://github.com/Dancncn/Demiurge.git
cd Demiurge
npm install
npm run tauri dev

Windows에서 Demiurge를 빌드하려면 기존에 Rust stable(MSVC), Visual Studio 2022 Build Tools의 “C++를 사용한 데스크톱 개발” 및 Windows SDK가 필요합니다. link.exe를 찾을 수 없다는 오류가 발생하면 먼저 도구 구성 요소를 추가합니다.

Demiurge의 “설정 → Minecraft”에서 이 프로젝트 디렉터리 및 Node.js 실행 파일을 선택하고, Tencent Cloud 서버의 공용 주소, AI 게임 사용자명 AI_Player와 사용자명 FuQiang을 입력한 후 “활성화”를 켭니다. 설정을 저장하면 Demiurge가 자동으로 MCP 하위 프로세스를 시작하며, 종료 · 비활성화 · 설정 변경 시 중지/재가동됩니다.

MCP 모드는 MCP_STDIO=true 및 LLM_MODE=mock을 강제로 사용하며, 여기서 mock은 단지 Mineflayer가 내부 계획 모델을 호출하지 않음을 의미합니다. 계획 전반과 페르소나 및 대화는 여전히 Demiurge에 현재 설정된 라이브 LLM이 처리합니다. 공개 채팅 및 귓속말 모두 알림 메시지가 포함되며, 사용자 이름, 채널, 메인 사용자 표식 및 장면 정보가 포함됩니다. 플레이어가 AI_Player, 나를 따라와라고 말하면 이름이 직접 호명됩니다. 호명되지 않은 공개 메시지는 모델이 대화 맥락에서 자신이 맞는지 판단합니다. 대화 및 핵심 경험은 해당 캐릭터와 동일한 메모리 네임스페이스에 기록됩니다. 자동 장기 기억은 코드에서 장면, 채널, 플레이어명, 메인 사용자 표식을 강제로 기록하므로, 기억 추출 모델이 항상 이 정보를 별도로 유지하지 않습니다.

데스크톱 입력 영역은 JPEG, PNG, GIF, WebP 형식의 , 이미지(단일 10MB, 총 20MB) 지원이며, 대화형 모델에만 전송되고 온라인 게임 채팅 과정에 포함되지 않습니다.

전체 설정 및 연결 검증은 Demiurge 통합 가이드 문서를 참조하세요.

Minecraft 服务器 서버 설정

server.properties:

online-mode=false
server-port=25565
server-ip=
white-list=true

서버를 재시작한 후 서버 콘솔에서 다음 명령을 실행합니다:

whitelist on
whitelist add FuQiang
whitelist add AI_Player

오프라인 모드에는 신뢰할 수 있는 계정 인증이 없습니다. Tencent Cloud 보안 그룹이 공용 IP에서만 TCP:25565에 접근하도록 허용하지 않거나 Tailscale/WireGuard 연결 방식을 사용해야 합니다. 비공개 명단만으로 동일한 이름을 사용할 수 없습니다.

게임 내 명령

MC_OWNER는 메인 유저를 지정하며, 이름 비교는 대소문자를 구분하지 않습니다. 그러나 이벤트와 기억에는 조종자가 실시간으로 표시한 정확한 이름이 유지됩니다. 목델은 메인 사용자와 다른 플레이어의 관계, 권한 및 기억을 분리합니다. 다른 플레이어도 공개 채팅, 귓속말, 일반적인 도움 요청을 할 수 있으며, 공식 문서에 정의했습니다. MCP 모드에서는 자연어 메시지를 Demiurge 현재 영의 판단에 따라 처리합니다. 독립 모드에서는 사용자가 명시적으로 AI 게임 사용자 이름을 부르는 작업만 수행합니다.

AI_Player，帮助
AI_Player，状态
AI_Player，停止
AI_Player，跟着我
AI_Player，去 120 64 -30
AI_Player，收集16个橡木
AI_Player，制作一把石镐并交给我
AI_Player，探索周围区域

고정된 @AI 접두사는 없습니다. 사용자 설정에서 AI 게임 사용자명으로 직접 부릅니다. 비공개 채팅은 자연스럽게 AI에게 전달되고, 대화가 아닌 공개 채팅에 대해서는 모델이 참여 여부를 판단합니다.

공략 지식

기본 제작 및 레지스트리는 서버 버전에 맞는 minecraft-data 데이터셋을 사용하며, 벡터 검색을 기술합니다. 자연어 공략은 다음과 같이 일괄 가져올 수 있습니다.

pnpm knowledge:index ./my-guides

.md 및 .txt 파일을 원형적으로 반복해서 읽습니다. 기본적으로 로컬 해시 벡터를 사용하여 embedding API 비용이 발생하지 않습니다. 이후 GuideRag의 벡터 구현을 대체할 수 있습니다.

상태 점검

기본적으로 테스트 클라우드 컨테이너만 감시합니다:

GET http://127.0.0.1:3008/health
GET http://127.0.0.1:3008/metrics

HEALTH_PORT=0으로 설정하면 실행을 중지할 수 있습니다. 상태 포트를 공용 네트워크에 노출하지 마십시오.

필수 가시성 필드

주 시스템은 스크린샷에 의존하지 않습니다. src/vision이 구현한 기능:

• 이전 프레임의 깊이와 카메라 매트릭스를 통해 데이터를 재투영합니다.

• 실제 프레임과 예측 프레임의 RGB 오차를 측정합니다.

• 주요 장면입니다.

• 연결성 영역들을 클러스터링하여 임계값 필터링을 수행합니다.

• 변칙 상황에 대응하며 선택적으로 VLM() 호출합니다.

Mineflayer 자체는 네이티브 RGB와 깊이 버퍼를 제공하지 않으므로, 시각 기능을 사용하려면 별도의 렌더러 또는 클라이언트 Mod(붕)와 프레임이 필요합니다. 프로젝트에는 HttpFrameSource 가 구현되어 있습니다. VISION_ENABLED=true와 VISION_FRAME_URL=http://127.0.0.1:PORT/frame을 설정하면 해당 프레임 소스에 연결할 수 있습니다. 외부 프레임가이드 없을 때는 VISION_ENABLED=false로 유지하고, 모든 게임에서는 실시간 능력 대신 구조화 인식 정보만 사용합니다.

안전 범위

• PVP 최대화: 비활성화: ALLOW_PVP=false.

• 아이템 버리기 가능: ALLOW_DROP_ITEMS=false.

• 단일 계획에서 최대 MAX_PLAN_STEPS 단계로 기본합니다.

• 단일 목표 거리 제한(비활성입력)은 MAX_ACTION_DISTANCE에 적용됩니다.

• 독립 모드는 명시적으로 AI 게임 사용자를 부른 메인 유저의 요청만 처리합니다. MCP 모드에서는 Demiurge가 공개 채팅에 응답할지 판단합니다.

• LLM은 등록된 Skill만 선택할 수 있으며, 인자는 Zod 패턴으로 검증됩니다.

• APIKey는 환경 변수로만 제공되며, 로그의 특정 필드는 필터링됩니다.

• 비상 시 우선순위는 일반 작업보다 높으며, 이동 및 관전을 중단할 수 있습니다.

더 자세한 Tencent Cloud 배포 단계는 docs/DEPLOY_TENCENT.md, 구조적 스킬 인터페이스는 docs/SKILLS.md, 시각 연결 라규약은 docs/VISION.md를 참조하십시오.

프로젝트 범위

• 현재 Minecraft Java Edition을 대상으로 합니다. 통신연결은 Mineflayer를 통해 수행됩니다.

• 구조화된 인식은 기본 메인 경로이며, 부분 시각 분석과 VLM은 외부 프레임 소스가 필요합니다.

• 밀리초 단위의 이동과 전투는 실행기와 Skill이 처리하고, LLM은 루프에 관여하지 않습니다.

• 오프라인 서버는 사용자 이름 소유를 안정적으로 검증할 수 없습니다. 서버 포트 허용 범위를 제한하거나 프라이빗 네트워크 연결을 사용해야 합니다.

• MCP 모드에서 모든 공개 채팅은 Demiurge의 문맥 판단을 발생시킬 수 있으므로, 서버 내 이용자 수를 고려하여 API 비용을 평가해야 합니다.

게임 내 통합 검증 테스트

pnpm typecheck
pnpm test
pnpm build
pnpm smoke

테스트에서는 실제 Minecraft 서버 및 실제 LLM Key가 있을 필요가 없습니다. Mock Executor와 Mock LLM은 계획, 스킬, 기억, MCP 알림, 및 시각 오차의 주요 파이프라인을 테스트합니다.