@elizaos/plugin-minecraft 2.0.0-beta.1 → 2.0.3-beta.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Shaw Walters and elizaOS Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,8 +1,94 @@
-# @elizaos/plugin-minecraft (TypeScript)
+# @elizaos/plugin-minecraft
 
-TypeScript plugin entrypoint for Minecraft automation via the local Mineflayer bridge server.
+Minecraft automation plugin for elizaOS. Gives an Eliza agent the ability to connect to a Minecraft server and control a bot — moving, building, mining, chatting, navigating, and attacking — through natural language.
 
-Most users should read the root docs:
+## How it works
 
-- `plugins/plugin-minecraft/README.md`
+The plugin manages a local WebSocket bridge process (`mineflayer-server`) that runs a [Mineflayer](https://github.com/PrismarineJS/mineflayer) bot. The elizaOS agent communicates with the bridge over a local WebSocket and drives the bot via a single `MC` action.
 
+## Capabilities
+
+### Action: `MC`
+
+One action with 13 operations, selected by an `action` parameter:
+
+| Operation | Parameters | What it does |
+|---|---|---|
+| `connect` | `host?`, `port?`, `username?`, `auth?`, `version?` | Join a Minecraft server |
+| `disconnect` | — | Leave the server |
+| `goto` | `x`, `y`, `z` | Pathfind to coordinates |
+| `stop` | — | Cancel movement |
+| `look` | `yaw`, `pitch` | Point the bot's view |
+| `control` | `control`, `state`, `durationMs?` | Press/release a movement key (`forward`, `back`, `left`, `right`, `jump`, `sprint`, `sneak`) |
+| `waypoint_set` | `name` | Save current position as a named waypoint |
+| `waypoint_goto` | `name` | Navigate to a saved waypoint |
+| `waypoint_delete` | `name` | Delete a saved waypoint |
+| `dig` | `x`, `y`, `z` | Mine a block at given coordinates |
+| `place` | `x`, `y`, `z`, `face` | Place the held block against a reference block face (`up`/`down`/`north`/`south`/`east`/`west`) |
+| `chat` | `message` | Send a chat message in-game |
+| `attack` | `entityId` | Attack a nearby entity by ID |
+
+Natural-language aliases work: "join", "move/walk", "mine/break", "say/tell", "hit", "navigate", etc.
+
+### Providers
+
+The plugin injects three context providers into the agent's state each turn:
+
+- **MC_WORLD_STATE** — connection status, position, health, food, inventory contents, nearby entities.
+- **MC_WAYPOINTS** — list of saved named waypoints and their coordinates.
+- **MC_VISION** — biome, what the bot is looking at, nearby ores and logs (radius 16), nearby entities.
+
+### Services
+
+- **MinecraftService** — manages the bot lifecycle and bridge connection.
+- **WaypointsService** — persists named waypoints via agent memory (durable when `plugin-sql` or another durable adapter is loaded).
+
+## Requirements
+
+- **Node.js only** — does not run in browser or mobile runtimes.
+- A running Minecraft server (local or remote) for the bot to connect to. Offline-mode local servers work out of the box.
+
+## Configuration
+
+All settings are optional. Defaults work for a local offline server.
+
+| Variable | Default | Description |
+|---|---|---|
+| `MC_HOST` | `127.0.0.1` | Minecraft server host |
+| `MC_PORT` | `25565` | Minecraft server port |
+| `MC_USERNAME` | `null` (bridge default: `ElizaBot`) | Bot login name |
+| `MC_AUTH` | `offline` | Auth mode: `offline` or `microsoft` |
+| `MC_VERSION` | `null` (bridge default: `1.20.4`) | Minecraft protocol version |
+| `MC_SERVER_PORT` | `3457` | Local bridge WebSocket port (internal, rarely changed) |
+
+Set these as environment variables or via `agentConfig.pluginParameters` in your character config.
+
+## Enabling the plugin
+
+Add `@elizaos/plugin-minecraft` to your agent's plugin list:
+
+```json
+{
+  "plugins": ["@elizaos/plugin-minecraft"]
+}
+```
+
+The bridge server starts automatically when the plugin initializes.
+
+## Development
+
+```bash
+# Build the plugin
+bun run --cwd plugins/plugin-minecraft build
+
+# Build the bridge server (required first time)
+bun run --cwd plugins/plugin-minecraft/mineflayer-server build
+
+# Run tests
+bun run --cwd plugins/plugin-minecraft test
+
+# Watch mode
+bun run --cwd plugins/plugin-minecraft dev
+```
+
+For agent-facing documentation (file layout, how to extend, gotchas), see `CLAUDE.md` in this directory.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@elizaos/plugin-minecraft",
   "description": "Minecraft automation plugin for ElizaOS (Mineflayer bridge)",
-  "version": "2.0.0-beta.1",
+  "version": "2.0.3-beta.3",
   "type": "module",
   "main": "dist/index.js",
   "module": "dist/index.js",
@@ -22,13 +22,30 @@
   "exports": {
     "./package.json": "./package.json",
     ".": {
+      "eliza-source": {
+        "types": "./src/index.ts",
+        "import": "./src/index.ts",
+        "default": "./src/index.ts"
+      },
       "import": {
         "types": "./dist/index.d.ts",
         "default": "./dist/index.js"
       }
+    },
+    "./*.css": "./dist/*.css",
+    "./*": {
+      "types": "./dist/*.d.ts",
+      "eliza-source": {
+        "types": "./src/*.ts",
+        "import": "./src/*.ts",
+        "default": "./src/*.ts"
+      },
+      "import": "./dist/*.js",
+      "default": "./dist/*.js"
     }
   },
   "files": [
+    "registry-entry.json",
     "dist",
     "README.md",
     "package.json"
@@ -38,7 +55,7 @@
     "zod": "^4.4.3"
   },
   "peerDependencies": {
-    "@elizaos/core": "2.0.0-beta.1"
+    "@elizaos/core": "2.0.3-beta.3"
   },
   "devDependencies": {
     "@biomejs/biome": "^2.4.14",
@@ -47,9 +64,9 @@
   },
   "scripts": {
     "dev": "bun --hot build.ts",
-    "test": "vitest run --passWithNoTests",
+    "test": "vitest run",
     "lint": "bunx @biomejs/biome check --write --unsafe .",
-    "typecheck": "tsc --noEmit",
+    "typecheck": "tsgo --noEmit",
     "clean": "rm -rf dist .turbo",
     "lint:check": "bunx @biomejs/biome check .",
     "build": "bun run build.ts",
@@ -108,5 +125,6 @@
         "sensitive": false
       }
     }
-  }
+  },
+  "gitHead": "f54b0f4eaed317d59fa7dbcdce20f4cdb0734420"
 }

package/registry-entry.json

@@ -0,0 +1,79 @@
+{
+  "id": "minecraft",
+  "name": "Minecraft",
+  "description": "Minecraft automation app for driving Mineflayer bots from Eliza agents.",
+  "npmName": "@elizaos/plugin-minecraft",
+  "version": "2.0.0-beta.0",
+  "source": "bundled",
+  "tags": ["app", "games", "minecraft", "automation", "mineflayer"],
+  "config": {
+    "MC_AUTH": {
+      "type": "string",
+      "required": false,
+      "sensitive": false,
+      "label": "Auth",
+      "help": "Minecraft auth mode (offline/microsoft)",
+      "advanced": false
+    },
+    "MC_HOST": {
+      "type": "string",
+      "required": false,
+      "sensitive": false,
+      "label": "Host",
+      "help": "Server host address",
+      "advanced": false
+    },
+    "MC_PORT": {
+      "type": "number",
+      "required": false,
+      "sensitive": false,
+      "label": "Port",
+      "help": "Minecraft server port",
+      "advanced": false,
+      "min": 1,
+      "max": 65535
+    },
+    "MC_VERSION": {
+      "type": "string",
+      "required": false,
+      "sensitive": false,
+      "label": "Version",
+      "help": "Minecraft version",
+      "advanced": false
+    },
+    "MC_USERNAME": {
+      "type": "string",
+      "required": false,
+      "sensitive": false,
+      "label": "Username",
+      "help": "Minecraft username",
+      "advanced": false
+    },
+    "MC_SERVER_PORT": {
+      "type": "number",
+      "required": false,
+      "sensitive": false,
+      "label": "Server Port",
+      "help": "Local server port",
+      "advanced": false,
+      "min": 1,
+      "max": 65535
+    }
+  },
+  "render": {
+    "visible": true,
+    "pinTo": [],
+    "style": "card",
+    "icon": "Pickaxe",
+    "group": "gaming",
+    "groupOrder": 11,
+    "actions": ["enable", "configure"]
+  },
+  "resources": {
+    "homepage": "https://github.com/elizaos/eliza#readme",
+    "repository": "https://github.com/elizaos/eliza"
+  },
+  "dependsOn": [],
+  "kind": "plugin",
+  "subtype": "gaming"
+}

package/dist/actions/helpers.d.ts

@@ -1,18 +0,0 @@
-import type { ActionResult, Content, HandlerCallback, HandlerOptions, Memory } from "@elizaos/core";
-import type { JsonValue } from "../protocol.js";
-import { type Vec3 } from "./utils.js";
-export declare function isRecord(value: unknown): value is Record<string, unknown>;
-export declare function parseJsonObject(text: string): Record<string, unknown>;
-export declare function readParams(options?: HandlerOptions | Record<string, JsonValue | undefined>): Record<string, unknown>;
-export declare function mergedInput(message: Memory, options?: HandlerOptions | Record<string, JsonValue | undefined>): Record<string, unknown>;
-export declare function readString(params: Record<string, unknown>, ...keys: string[]): string | null;
-export declare function readNumber(params: Record<string, unknown>, ...keys: string[]): number | null;
-export declare function readBoolean(params: Record<string, unknown>, ...keys: string[]): boolean | null;
-export declare function parseVec3(params: Record<string, unknown>, text: string): Vec3 | null;
-export type PlaceFace = "up" | "down" | "north" | "south" | "east" | "west";
-export declare function isPlaceFace(value: string | null): value is PlaceFace;
-export declare function callbackContent(actionName: string, text: string, source: unknown): Content;
-export declare function emit(actionName: string, callback: HandlerCallback | undefined, text: string, source: unknown, result: Omit<ActionResult, "text">): Promise<ActionResult>;
-export declare function withMinecraftTimeout<T>(promise: Promise<T>, label: string): Promise<T>;
-export declare function capMinecraftData<T>(value: T): T;
-//# sourceMappingURL=helpers.d.ts.map

package/dist/actions/helpers.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"helpers.d.ts","sourceRoot":"","sources":["../../src/actions/helpers.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAEV,YAAY,EACZ,OAAO,EACP,eAAe,EACf,cAAc,EACd,MAAM,EACP,MAAM,eAAe,CAAC;AACvB,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAChD,OAAO,EAAe,KAAK,IAAI,EAAE,MAAM,YAAY,CAAC;AAMpD,wBAAgB,QAAQ,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAEzE;AAED,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CASrE;AAED,wBAAgB,UAAU,CACxB,OAAO,CAAC,EAAE,cAAc,GAAG,MAAM,CAAC,MAAM,EAAE,SAAS,GAAG,SAAS,CAAC,GAC/D,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAGzB;AAED,wBAAgB,WAAW,CACzB,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE,cAAc,GAAG,MAAM,CAAC,MAAM,EAAE,SAAS,GAAG,SAAS,CAAC,GAC/D,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAKzB;AAED,wBAAgB,UAAU,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,IAAI,EAAE,MAAM,EAAE,GAAG,MAAM,GAAG,IAAI,CAM5F;AAED,wBAAgB,UAAU,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,IAAI,EAAE,MAAM,EAAE,GAAG,MAAM,GAAG,IAAI,CAU5F;AAED,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,GAAG,IAAI,CAW9F;AAED,wBAAgB,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,CAMpF;AAED,MAAM,MAAM,SAAS,GAAG,IAAI,GAAG,MAAM,GAAG,OAAO,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,CAAC;AAE5E,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,KAAK,IAAI,SAAS,CASpE;AAED,wBAAgB,eAAe,CAAC,UAAU,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,GAAG,OAAO,CAM1F;AAED,wBAAsB,IAAI,CACxB,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,eAAe,GAAG,SAAS,EACrC,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,OAAO,EACf,MAAM,EAAE,IAAI,CAAC,YAAY,EAAE,MAAM,CAAC,GACjC,OAAO,CAAC,YAAY,CAAC,CAIvB;AAED,wBAAsB,oBAAoB,CAAC,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC,CAO5F;AAED,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,CAAC,CAG/C"}

package/dist/actions/index.d.ts

@@ -1,10 +0,0 @@
-/**
- * Action registry for `@elizaos/plugin-minecraft`.
- *
- * Single planner-facing parent: `MC` (Pattern C) — absorbs the seven
- * old leaves (MC_ATTACK, MC_BLOCK, MC_CHAT, MC_CONNECT, MC_DISCONNECT,
- * MC_LOCOMOTE, MC_WAYPOINT). Old names live as similes for trace
- * continuity.
- */
-export { minecraftAction } from "./mc.js";
-//# sourceMappingURL=index.d.ts.map

package/dist/actions/index.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/actions/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC"}

package/dist/actions/mc.d.ts

@@ -1,25 +0,0 @@
-/**
- * MC — single Pattern C parent action that absorbs the seven leaves
- * (MC_ATTACK, MC_BLOCK, MC_CHAT, MC_CONNECT, MC_DISCONNECT, MC_LOCOMOTE,
- * MC_WAYPOINT) into a single planner-facing surface.
- *
- * Op set:
- *   connect          { host?, port?, username?, auth?, version? }
- *   disconnect       { }
- *   goto             { x, y, z }
- *   stop             { }
- *   look             { yaw, pitch }
- *   control          { control, state, durationMs? }
- *   waypoint_goto    { name }
- *   dig              { x, y, z }
- *   place            { x, y, z, face }
- *   chat             { message }
- *   attack           { entityId }
- *   waypoint_set     { name }
- *   waypoint_delete  { name }
- *
- * Old leaf names are kept as similes for trace continuity.
- */
-import type { Action } from "@elizaos/core";
-export declare const minecraftAction: Action;
-//# sourceMappingURL=mc.d.ts.map

package/dist/actions/mc.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"mc.d.ts","sourceRoot":"","sources":["../../src/actions/mc.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,KAAK,EACV,MAAM,EAOP,MAAM,eAAe,CAAC;AAsOvB,eAAO,MAAM,eAAe,EAAE,MAmY7B,CAAC"}

package/dist/actions/utils.d.ts

@@ -1,7 +0,0 @@
-export type Vec3 = {
-    x: number;
-    y: number;
-    z: number;
-};
-export declare function extractVec3(text: string): Vec3 | null;
-//# sourceMappingURL=utils.d.ts.map

package/dist/actions/utils.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../src/actions/utils.ts"],"names":[],"mappings":"AAEA,MAAM,MAAM,IAAI,GAAG;IAAE,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AAIvD,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,CAwBrD"}

package/dist/index.d.ts

@@ -1,12 +0,0 @@
-import type { Plugin } from "@elizaos/core";
-export * from "./actions/index.js";
-export * from "./protocol.js";
-export * from "./providers/index.js";
-export * from "./services/minecraft-service.js";
-export * from "./services/process-manager.js";
-export * from "./services/waypoints-service.js";
-export * from "./services/websocket-client.js";
-export * from "./types.js";
-export declare const minecraftPlugin: Plugin;
-export default minecraftPlugin;
-//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAiB,MAAM,EAAY,MAAM,eAAe,CAAC;AAIrE,cAAc,oBAAoB,CAAC;AACnC,cAAc,eAAe,CAAC;AAC9B,cAAc,sBAAsB,CAAC;AACrC,cAAc,iCAAiC,CAAC;AAChD,cAAc,+BAA+B,CAAC;AAC9C,cAAc,iCAAiC,CAAC;AAChD,cAAc,gCAAgC,CAAC;AAC/C,cAAc,YAAY,CAAC;AAuB3B,eAAO,MAAM,eAAe,EAAE,MAwB7B,CAAC;AAEF,eAAe,eAAe,CAAC"}