MinecraftBot

Mineflayer、MCP、検証可能なSkillステートマシンに基づくMinecraft Java Edition自律プレイヤー。独立したゲームキャラクターとしてサーバーに参加し、主にプロトコルレベルの構造化データで世界を認識し、ナビゲーション、採集、クラフト、戦闘、建築、長時間タスクの継続実行が可能です。

独立した Demiurge デスクトップエージェントとの併用を推奨します。Demiurge が人物設定、現在の LLM、長期記憶、デスクトップ画像対話、高次意思決定を提供し、MinecraftBot はサーバー接続、構造化認識、信頼できる実行を担当します。両プロジェクトは互いに独立しており、Minecraft クライアントへの Mod インストールは不要です。

2つの実行モード

このプロジェクトは .env、API キー、ランログ、SQLiteiro記憶データベース、ローカル Minecraft データをコミットしません。.

Related MCP server: Minecraft Dedalus MCP

実装済み機能

• オフライン または Microsoft アカウント接続、自動再接続、固定キャラクター名。

• プレイヤー、インベントリ、装備、エンティティ、ブロック、時刻、天気、イベントの認識。

• シーン要約、空間位置記憶、タスク永続とくるぶしライン復旧。

• 外部外部 LLM API による計画、失敗時リトライ、厳密な JSON 検証。

• 正確なアイテる、ブロック、Mob、レシピデータベースと再帰的な材料計算。

• ローカル攻略ガイド RAG。Markdown/TTXT ガイドのインポートが可能。

• 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 以降（Corepack で有効化可能）。

• MCP モードでは LLM を設定した Demiurge が必要。独立実行モードでは OpenAI 互換 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 の使用（推奨）

2つの独立プロジェクトをそれぞれ構築:

# 本项目
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 実行可能なファイルを選択し、十フェスサーバーのパブリック名前、AI ゲームユーザー名 AI_Player、メインユーザーゲーム名 FuQiang を入力後、「有効化」しをオンにします。設定を保存すると Demiurge が自動的に MCP 子プロセスを起動します。終了・無効化・設定変更時には停止/再起動します。

MCP モードでは強制的 MCP_STDIO=true、LLM_MODE=mock が使用されますが、ここでの mock は Mineflayer が内部計画モデルを呼び出す禁止を意味するだけです。すべての計画、人格、対話は Demiurge の現在の設定にある実盤 LLM によって行われます。公開チャットとプライベートメッセージには、実際の通信、チャンネル、メインユーザー識別子、シーンが含まれます。プレイヤーが AI_Player，跟着我 と入力すれば自然に指名できます。指名なしの公開メッセージは、モデルが対話・文脈に基づき、自分へのメッセージが否かを判断します。会話と重要な経験は、現在のキャラクターの同じ memory namespace に書き込まれます。自動長期記憶は、シーン、チャンネル、プレイヤー、ユーザー名、メインユーザー識別子をコードで強制的に書き込みます。記憶抽出モデルに依存せずに、これらの情報をそのまま保持します。

デスクト入力領域は、JPEG、PNG、GI の、WebP のネイティブマルチモーダル画像g（単張 10 MB、合計 20 MB）をサポートします。画像は Demiurge の現在のモデルに渡されるのみ、ゲームチャットは経由しません。

完全な設定とオンライ検証は Demiurge 統合ガイド を参照してください。

Minecraft サーバー設定

server.properties:

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

サーバーを再起動後、サーバーコンソールで実行:

whitelist on
whitelist add FuQiang
whitelist add AI_Player

オフラインモード改修に、アカウント認証は信頼できません。腾讯云セキュリティグループでは、あなたのパブリック IP のみが TCP:25565 にアクセスできるようにするか、Tailscale/WireGuard で接続してください。ホワイトリストだけで同名の impersonationを防ぐのは不可能です。

GPT内のコマンド

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 のベクトソル実装を置き換えることもできます。

ヘルスチェックのヘルスチェック

デフォルトでは、腾讯云のローカル IP のみで検聴されます:

Wait, I need to check the line: "默认只监听腾讯云本机：" — Let me translate: "デフォルトでは腾讯云のローカルホストのみリッスン："

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:ポート/frame を設定することで接続できます。外部フレームソースがない場合は VISION_ENABLED=false のまま、すべてのゲーム機能は構造化の認識を引き続き使用します。

セキュリティ境界

• デフォルトで PVP 無効: ALLOW_PVP=false。

• アイテム投棄を無効に可能: ALLOW_DROP_ITEMS=false。

• 一つのプランは最大 MAX_PLAN_STEPS ステップまで。

• 単一の目的距離は MAX_ACTION_DISTANCE によって制限されます。

• 独立モードは、メインユーザーが AI ゲームユーザー名を指示されたタスクのみを受け付けます。MCP モードでは Demiurge が、指定されていない公開チャットに応答が必要かを判断します。

• LLM は登録された Skill のみを選択でき、パラメーターはパラメータ Zod 検証されます。

• API キーは環境変からのみ読み取り、ログからはフィールドのフィールドを書き出します。

• 緊急脱出は通常のタスクより優先され、移動と視線を優先的に占取できます。

具体的な腾讯云やデプロイ手順は docs/DEPLOY_TENCENT.md、Skill インターフェースは docs/SKILLS.md、ビジュアル接続の取り決めは docs/VISION.md を参照してください。

プロジェクトの境界

• 現在は Minecraft Java 版を対象とし、SQLite メモリ、JSON ヘルスケア、構造化ログにより接続性を提供します。

• 構造化認識がデフォルトのメインです。ローカルビジョンと VLM には、ソース外フレームが必要です。

• ミリ秒/マイクロ秒レベルの移動と戦闘の詳細は、エクゼキューターと実行者と Skill が処理します。LLM はフレームごとの制御を行いません。

• オフラインサーバーはユーザー名の帰属を確実できないため、サーバーのポートのソースを制限するか、専用ネットワークを使用してください。

• MCP モッドでは、すべての公開チャットが Demiurge のコンテキストを引き出す可能性があります。サーバー上のプレイヤー数に基いて API コストを評価する必要があります。

開発と検証

pnpm typecheck
pnpm test
pnpm build
pnpm smoke

テストに必要となる実際の Minecraft サーバーはリアルな LLM キーは不要です。Mock Executor と Mock LLM がスキルの計画・記憶・MCP 通知・視覚残差のメインループをカプセル化します。