rmalde/minecraft-agent

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

Astra と JEV Minecraft エージェント

概要 – 2 つの言語モデルサービスを組み合わせて、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` でアクセス。現在の観測から 1 つの合法アクションを選択します。
ネイティブクライアントとレコーダー	ソースからビルドされた隠れた 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 では手動でパスを調整する必要があります。

結論 – このリポジトリは、大規模言語モデル（Astra）と型付き意思決定モデル（JEV）を使用した構造化状態制御を示す、再現可能で完全自動の Minecraft スピードランボットを提供します。これは、複雑でリアルタイムの仮想環境で動作する LLM 駆動の具現化エージェントの具体的な例です。