MinecraftBot

Autonomer Player für Minecraft Java auf Basis von Mineflayer, MCP und einer verifizierbaren Skill-Zustandsmaschine. Er tritt dem Server als eigenständige Spielerfigur bei, erfasst die Welt vor allem über protokollbasierte strukturierte Daten und kann navigieren, Ressourcen gewinnen, handwerken, kämpfen, bauen und langfristige Aufgaben kontinuierlich ausführen.

Empfohlen wird der Einsatz zusammen mit dem separaten Desktop-Agent Demiurge: Demiurge stellt die Persona, das aktuelle LLM, das Langzeitgedächtnis, Desktop-Bilddialoge und die übergeordneten Entscheidungen bereit; Minecraft-verantwortlich für die Serververbindung, die strukturierte Wahrnehmung und die zuverlässige Ausführung. Die beiden Projekte sind voneinander unabhängig und verlangen keine Mods im Minecraft-Client.

Zwei Betriebsmodi

Das Projekt committet weder .env, API-keys, Laufzeit-Logs, SQLiteMemory-Datenbank no` noch lokale Minecraft-Daten.

Related MCP server: Minecraft Dedalus MCP

Implementierte Fähigkeiten

• Verbinden per Offline- oder Microsoft-Konto, automatisches Wiederverbinden, fester Charaktername.

• Wahrnehmung von Spielern, Inventar, Ausrüstung, Entitäten, Blöcken, Zeit, Wetter und Zeit.

• Kontextzusammenfassungen, Erinnerung an räumliche Positionen, Aufgaben-Rückverlagerung und Wiederherstellung nach Verbindungsabbruch.

• Planung über externe LLM-API, Fehlerrien-kation und verlustarme Realisierung, Fehlerbehandlung und strenge JSON-Validierung.

• Präzise Datenbanken für Gegenstände, Blöcke, Kreaturen und Rezepte sowie rekursive Materielkarberechnung.

• Lokale Anleitungs-RAG, die Markdown/TXT-Anleitungen importieren kann.

• Skill-Ressourcensperren, Prioritäts-Preemption, Timeouts, Abbruch, Fortschritt, Wiederholung und Ergebnissvalsprüfung.

• Navigation, Folgen, Mining, Freigabe, Research, Platzierung, Influenza, Herstellung, Schmelzen, Schmieden, Kampf, Flucht, Nahrung, Übergabe, Chest-Zugriff, Bauen und Explorieren.

• Überwachung von Flucht bei niedriger Lebensenergie, Stecksituationen, vollem Inventar und geringer Strategie.

• SQLite-Gedächtnis, JSON-Healthcheck-Interface, strukturiertes Logging.

• Died-Geometrie der Tiefenbuffer-Re-Projection, experiences und Clustering von Restfehlerregionen, H-Unknowns über bekannte Änderungen und optionale VLM-Analyse-Schnittstelle.

• Mock-LLM und Mock-Executor können Kernsystemtest ohne MC-Server oder API-Key durchgeführt werden.

• MCP-stdio-Tools/Ressourcen, Game-Event-Benachrichtigungen sowie die Rückkopplungsschleife aus Demiurge-Persona, -Sitzung und -Langzeitgedächtnis.

Betriebsstruktur

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

Umgebung

• Minecraft Java-Server.

• Node.js 22.13 oder höher.

• pnpm 10 oder höher, auch via Corepack aktivierbar.

• MCP-Modus erfordert Demiurge mit einem konfigurierten LLM; nur im Standalone-Betrieb ist eine OpenAI-kompatible API erforderlich.

Lokale Installation

corepack enable
pnpm install
cp .env.example .env

Beim Standalone-Betrieb mindestens anpassen:

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=你的模型名

Selbstleset zuerst ausführen, ohne Verbindung zum Server:

pnpm typecheck
pnpm test
pnpm smoke

Start-Entwicklung

pnpm dev

Produktionsmodus starten:

pnpm build
NODE_ENV=production pnpm start

Demiurge verwenden (empfohlen)

Beide Projekte separat builden, wobei “builden” hier „erstellen“ bedeutet:

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

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

Für die Windows-Erstellung von Demiurge sind außerdem Rust stable (MSVC), die Workload in
„Desktopentwicklung mit C++“ von Visual Studio 2022 Build Tools sowie das Windows SDK erforderlich; falls Sie eine Fehlermeldung zu link.exe erhalten, installieren Sie diese Komponenten zuerst.

In Demiurge unter „Settings → Minecraft“ wählen Sie:
das Projektverzeichnis und die Node.js-ausführbare Datei, dann tragen Sie die öffentliche Mehrwert-Adresse des Tencent-Servers ein, den AI-Spielnamen AI_Player und den Hauptbenutzernamen FuQiang. Abschließend lassen Sie „Enable“ aktivieren.
Nach dem Speichern der Einstellungen startet Demiurge automatisch den MCP-Unterprozess; beim Beenden, Deaktivieren oder Ändern der Konfiguration wird er beendet bzw. neu gestartet.

Im MCP-Modus werden MCP_STDIO=true und LLM_MODE=mock erzwungen. Das mock hier heißt nur, dass Mineflayer keine eigene Planung aufrufen darf. Planung, Persönlichkeit und Dialoge liegen vollständig bei dem aktuell in Demiurge konfigurierten realen LLM. Öffentlicher Chat und Private-Nachrichten transportieren stets den tatsächlichen Benutzernamen, den Kanal, die Hauptbenutzerkennung und den Kontext. Spieler geben AI_Player，跟着我 ein und werden so natürlich angespielt; nicht genannte öffentliche Nachrichten entscheidet das Modell anhand des Dialogs, ob sie an den Bot gerichtet sind. Dialoginhalte und wichtige Erfahrungen werden in den Memory-Namespace der aktuellen Persona geschrieben; den automatischen Langzeiterinnerungscode wird von Code direkt in den Kontext, den Kanal, den Spielbenutzernamen und die Hauptbenutzerkennung geschrieben und ist nicht auf ein Memory-Extraktion-Modell angewiesen.

Der Desktop-Eingabebezirk unterstütztJPEG, PNG, GIF und WebP als native multimodale Bilder (einzelne 10 MB, bis zusammen 20 MB). Bilder gehen jeweils nur an das aktuelle Demiurge-Modell, nicht in den Spiel-Chat.

Vollständige Konfiguration und Betriebsübernahme für den Live-Betrieb findest du in Demiurge-Integrationsleit (docs/DEMIURGE_INTEGRATION.md).

Minecraft-Serverkonfiguration

server.properties:

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

Nach dem Neustart der Serverkonsole ausführen:

whitelist on
whitelist add FuQiang
whitelist add AI_Player

Der Offline-Modus hat keine verlässliche Kontpad-Verifizierung für denkliches „Benutzer“. Die Sicherheitsgruppe in Tencent Cloud darf nur Ihre öffentliche IP-Adresse für TCP:25565 zulassen oder über Tailscale/WireGuard verbunden sein; verlasst sich nicht auf die Allow-Liste, um Identitätsbetrug durch gleiche Spielernamen zu verhindern.

In-Game-Befehle

MC_OWNER definiert den Hauptbenutzer. Der Benutzername wird unabhängig von Groß-/Kleinschreibung verglichen, aber Ereignisse und Speicherung behalten den exak ten, im Spielauch angezeigten Benutzernamen bei. Das Modell trennt Beziehung, Berechtigungen und Memories des Hauptbenutzers von denen anderer Spieler. Andere Spieler können weiterhin öffentlich sein, Privatgespräche oder allgemeine Hilfe anfragen. Im MCP-Modus werden natürliche Sprach-Nachrichten einheitlich der aktuellen Demiurgekonfiguration zur Beurteilung und Verarbeitung gegeben; im Standalone-Modus führt das System nur Aufgaben aus, bei denen der Hauptbenutzer den AI-Spielernamen klar findet.

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

Das feste@AI-Präfix wurde entfernt. Sprechen Sie den Bot direkt über den AI-Game-Namen an, der in den Einstellungen festgelegt ist; private Chats gelten automatisch als Ansprache, bei öffentlichen Nachrichten ohne Ansprache entscheidet das Modell, ob eine Antwort nötig ist.

Einrichtiges Leitfaden-"?

Kommentar: genauer Rezepte- und Registry-Einträge links vom Server stammen aus minecraft-data der aktuellen Server-Version und nicht über Vektor- Suche. Natürlichsprachliche Guides kann man in Serie importieren:

pnpm knowledge:index ./my-guides

Unterstützt das rekursive Lesen von .md und .txt. Standardmäßig werden lokale Hashvektoren ver wendet, dadurch entstehen keine Embedding-API-Kosten; der Vektor-Implementiert von GuideRag kann später ausGetauscht werden.

Healthcheck

Standardmäßig bindet er nur an die lokale Tencent-Cloud- Instan, um findet wird überwacht:

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

Setzen Sie HEALTH_PORT=0 zum Deaktivieren. Niemals den Health-Port öffentlich zugänglich machen.

Vision-Modul

Das Hauptsystem funktioniert ohne Screenshots. src/vision implementiert:

• Geometrische Reprojection des vergangenen Tiefenbilds mit der Kameramatrix.

• RGB-Restbild zwischen tatsächlichem und vorhergesagtem Frame.

• Bekannte Änderungsmasken über Aktion.

• Clusterung zusammenhängender Regionen und Schweffilter, also von:

• Erkennung auffälliger Ereignisse und optionale VLM-Aufrufe.

Mineflayer unterstützt selbst kein native RGB- und Tiefenbuffer. Für die aktivierte Vision wird eine Bildquelle über den Ausgaben der offscreen-Renderer (mit click HttpFrameSource) oder ein Client-Mod bereitgestellt. Die Integration erfolgt durch Setzen von VISION_ENABLED=true und VISION_FRAME_URL=http://127.0.0.1:端口/frame. Ohne externe Bildquelle bleibt VISION_ENABLED=false; alle In-Game-Funktionen nutzen weiterhin strukturierte Wahrnehmung.

Sicherheitsgrenzen

• PVP standardmäßig deaktiviert: ALLOW_PVP=false.

• Item-Drop verworfen auf: ALLOW_DROP_ITEMS=false.

• Ein Plan besteht aus maximal `MAX_PLAN_STEPSSchritten.

• Die Distanz zu einem einzelnen Ziel ist durch MAX_ACTION_DISTANCE beschränkt.

• Der Standalone-Modus nimmt nur Aufgaben an, bei denen der Hauptnutzerden AI-Titel explizit für den bot nennt; im MCP-Modus entscheidet Demiurge, ob eine nicht näher adressierte, öffentliche Nachricht beantwortet werden soll.

• Der LLM darf nur registrierte Skills wählen; Parameter werden mit Serie Zod validiert.

• API-Keys kommen ausschließlich aus den Umgebungsvariablen; Logs sind geschützt und verlieren den Feldinhalt.

• Der Notflucht hat Vorrang und kann Bewegung und Blickrichtung preemptively übernehmen.

Die spezifische Deployment-Instruktion für Tencent- Cloud in docs/DEPLOY_TENCENT.md, die Skill-Interface in docs/SKILLS.mdund die Vision-Integration in docs/VISION.md.

Projektgrenzen

• Das Projekt richtet sich derzeit an Minecraft Java; die Protokollanbindung stammt von Fireflake.

• Struktur wahrnehmen ist Standard-Pfad; lokale Vision und VLM extra Boden, zusätzliche Quellen.

• Mikro- und Millisekunden-räumliche bzw. Kampf-Details übernimmt der Ausführungs-Executor und die Skills; LLM greift nicht in jedes Frame ein.

• Ein Offline-Server kann die Zuordnung von Benutzernamen nicht verlässlich überprüfen; deshalb Port-Quellen beschränken oder private Netzwerke verwenden.

• Im MCP-Modus kann jeder öffentliche Chat den Kontext von Demiur betroffen; berücksichtige bei der API-Kostenbewertung die aktive Spieleranzahl auf dem Server.

Entwicklung und Verifizierung

pnpm typecheck
pnpm test
pnpm build
pnpm smoke

Der Test läuft ohne echten Minecraft-Server und ohne EE-Key; Mock Executor und Mock-Programm abend planen, Skill, Memory, MCP-Benachrichtigungen und die Vision-Hauptkette, um den Vollständigkeitscheck zu erreichen.