@nxg-org/mineflayer-ender 1.1.1 → 1.1.3

package/README.md

@@ -0,0 +1,105 @@
+<h2 align="center">mineflayer-ender</h2>
+<h4 align="center">A Mineflayer plugin for ender-pearl planning and enderman-style movement helpers.</h4>
+
+<p align="center">
+  <a href="https://github.com/nxg-org/mineflayer-ender">
+    <img src="https://img.shields.io/badge/github-181717?style=for-the-badge&logo=github" alt="GitHub">
+  </a>
+  <a href="https://www.npmjs.com/package/@nxg-org/mineflayer-ender">
+    <img src="https://img.shields.io/npm/v/%40nxg-org%2Fmineflayer-ender?style=for-the-badge&logo=npm" alt="NPM">
+  </a>
+  <img src="https://img.shields.io/badge/license-GPL--3.0-black?style=for-the-badge" alt="License">
+</p>
+
+> [!WARNING]
+> This plugin is still under active iteration. The core pearling flow works, but the API is still fairly low-level and focused on block-targeted pearl shots.
+
+<h3 align="center">Why use this plugin?</h3>
+
+-----
+
+`mineflayer-ender` gives Mineflayer bots a reusable ender-pearl planning layer instead of forcing every project to manually calculate yaw, pitch, travel ticks, and collision checks.
+
+It is useful when you want a bot to:
+
+- Pearl onto a specific block
+- Plan whether a pearl shot is valid before throwing
+- Reuse projectile simulation logic in your own combat or movement systems
+- Build more "enderman-like" movement around a clean plugin surface
+
+<h3 align="center">Features</h3>
+
+-----
+
+- [X] Attach `bot.ender` to Mineflayer bots
+- [X] Check whether pearls are available in inventory
+- [X] Auto-equip pearls before throwing
+- [X] Plan a valid pearl shot to a target block
+- [X] Expose low-level shot simulation via `EnderShotFactory`
+- [ ] Higher-level chase / combat automation
+- [ ] Broader polished docs and examples
+
+<h3 align="center">Installation</h3>
+
+-----
+
+```bash
+npm install @nxg-org/mineflayer-ender
+```
+
+The plugin depends on `@nxg-org/mineflayer-util-plugin` and loads it automatically if your bot does not already have `bot.util`.
+
+<h3 align="center">Quick Start</h3>
+
+-----
+
+```ts
+import { createBot } from "mineflayer";
+import enderPlugin from "@nxg-org/mineflayer-ender";
+
+const bot = createBot({
+  host: "localhost",
+  port: 25565,
+  username: "ender-bot"
+});
+
+bot.loadPlugin(enderPlugin);
+
+bot.once("spawn", async () => {
+  const block = bot.findBlock({
+    matching: (b) => b.name !== "air",
+    maxDistance: 16
+  });
+
+  if (block) {
+    const success = await bot.ender.pearl(block);
+    console.log("Pearl result:", success);
+  }
+});
+```
+
+There is also a chat-driven usage example in [`example/basic.ts`](./example/basic.ts).
+
+<h3 align="center">Usage Notes</h3>
+
+-----
+
+- The plugin is centered around block-targeted pearl throws, not arbitrary teleport destinations.
+- `bot.ender.pearl(block, face?)` returns `false` when no valid shot is found or no pearls are available.
+- `shotToBlock()` can be used to inspect a candidate shot before actually throwing.
+- Off-hand support exists on the `Enderman` instance through `useOffhand`.
+
+<h3 align="center">API and Examples</h3>
+
+-----
+
+| Link | Description |
+| --- | --- |
+| [API](./docs/API.md) | Full API reference for the plugin, public classes, types, and method behavior. |
+| [Example](./example/basic.ts) | A simple example showing pearl and follow commands. |
+
+<h3 align="center">License</h3>
+
+-----
+
+This package is published as `GPL-3.0` in [`package.json`](./package.json).

package/docs/API.md

@@ -0,0 +1,278 @@
+# API
+
+This page documents the current public surface of `@nxg-org/mineflayer-ender`.
+
+## Installation
+
+```bash
+npm install @nxg-org/mineflayer-ender
+```
+
+## Plugin Setup
+
+```ts
+import { createBot } from "mineflayer";
+import enderPlugin from "@nxg-org/mineflayer-ender";
+
+const bot = createBot({
+  host: "localhost",
+  username: "ender-bot"
+});
+
+bot.loadPlugin(enderPlugin);
+```
+
+When the plugin loads, it augments Mineflayer with:
+
+```ts
+bot.ender: Enderman
+```
+
+If `bot.util` is missing, the plugin automatically loads `@nxg-org/mineflayer-util-plugin`.
+
+## Exports
+
+### Default Export
+
+```ts
+import enderPlugin from "@nxg-org/mineflayer-ender";
+```
+
+Mineflayer plugin loader that attaches `bot.ender`.
+
+### Named Exports
+
+```ts
+import { Enderman, EnderShotFactory } from "@nxg-org/mineflayer-ender";
+```
+
+- `Enderman`: main runtime helper attached to the bot
+- `EnderShotFactory`: lower-level shot simulator constructor for custom projectile work
+
+## Bot Augmentation
+
+The plugin declares:
+
+```ts
+declare module "mineflayer" {
+  interface Bot {
+    ender: Enderman;
+  }
+}
+```
+
+It also declares several bot events in the module augmentation, but the current plugin implementation shown in this repository does not emit those events itself.
+
+## `Enderman` Class
+
+This is the primary class most users will interact with.
+
+## Properties
+
+### `enabled: boolean`
+
+General runtime flag used by the class. Defaults to `false`.
+
+### `useOffhand: boolean`
+
+Controls whether pearl equip/usage should target the off-hand. Defaults to `false`.
+
+## Methods
+
+### `shotToBlock(block: Block, face?: BlockFace): CheckedShot | null`
+
+Calculates a candidate pearl shot to the target block using the internal planner.
+
+```ts
+const shot = bot.ender.shotToBlock(block);
+if (shot?.hit) {
+  console.log(shot.yaw, shot.pitch, shot.ticks);
+}
+```
+
+Returns:
+
+- `CheckedShot` when planning succeeds
+- `null` when no viable shot is found
+
+### `hasPearls(): boolean`
+
+Checks whether the bot has any item whose name includes `"_pearl"` in inventory.
+
+```ts
+if (!bot.ender.hasPearls()) {
+  console.log("Need more pearls");
+}
+```
+
+### `equipPearls(): Promise<boolean>`
+
+Ensures an ender pearl is equipped in the currently selected hand.
+
+Behavior:
+
+- returns `true` if pearls are already equipped
+- returns `true` after equipping a pearl from inventory
+- returns `false` if no pearls are found
+
+### `cancel(): void`
+
+Stops the current ender action state and deactivates the held item.
+
+If a shot is mid-charge and internal shot info exists, it also forces the bot to look back toward that stored shot direction before cancelling.
+
+### `pearl(block: Block, face?: number): Promise<boolean>`
+
+Main high-level method for throwing a pearl at a target block.
+
+```ts
+const success = await bot.ender.pearl(targetBlock, 1);
+```
+
+Behavior:
+
+- rejects concurrent pearl actions
+- computes a valid shot using the planner
+- equips pearls if needed
+- force-looks to the computed yaw and pitch
+- waits for an internal pearl cooldown gate
+- swings and activates the held item to throw the pearl
+
+Returns `false` when:
+
+- a pearl throw is already in progress
+- no pearls are available
+- no valid shot is found
+- shot validation fails
+
+Returns `true` after the throw sequence is triggered.
+
+## `EnderShotFactory`
+
+Static helper class for constructing `EnderShot` instances.
+
+### `EnderShotFactory.fromPlayer(shotEntity, bot, interceptCalcs?): EnderShot`
+
+Builds an `EnderShot` from a player's position, yaw, pitch, and velocity.
+
+```ts
+const shot = EnderShotFactory.fromPlayer(
+  {
+    position: bot.entity.position,
+    yaw: 0,
+    pitch: -Math.PI / 4,
+    velocity: bot.entity.velocity
+  },
+  bot
+);
+```
+
+Useful when you want to simulate a potential pearl shot before using `bot.ender.pearl()`.
+
+### `EnderShotFactory.fromEntity(projectileInfo, bot, interceptCalcs?): EnderShot`
+
+Builds an `EnderShot` from an existing projectile-like position and velocity.
+
+This is a lower-level helper for custom simulations.
+
+## `EnderShot`
+
+`EnderShot` is not re-exported from `src/index.ts`, but it is part of the internal API surface used by the factory. It stores simulated trajectory points and can evaluate collisions against a target block.
+
+### Important Properties
+
+- `initialPos: Vec3`
+- `initialVel: Vec3`
+- `initialYaw: number`
+- `initialPitch: number`
+- `gravity: number`
+- `points: Vec3[]`
+- `pointVelocities: Vec3[]`
+- `blockHit: boolean`
+- `blockCheck: boolean`
+
+### `calcToBlock(target: Block | Vec3, blockChecking = false): BasicShotInfo`
+
+Simulates a projectile trajectory until it intersects the target block area or collides with another block.
+
+The returned `BasicShotInfo` includes:
+
+```ts
+type BasicShotInfo = {
+  XZLandingDistance: number;
+  YLandingDistance: number;
+  block: Block | null;
+  blockFace?: BlockFace;
+  closestPoint: Vec3 | null;
+  totalTicks: number;
+};
+```
+
+This method is useful when you want detailed trajectory information, not just a simple success/fail result.
+
+## Important Types
+
+## `CheckedShot`
+
+```ts
+type CheckedShot = {
+  hit: boolean;
+  yaw: number;
+  pitch: number;
+  ticks: number;
+  shotInfo: BasicShotInfo | null;
+};
+```
+
+Returned by planner operations like `shotToBlock()`.
+
+## `BlockFace`
+
+```ts
+enum BlockFace {
+  UNKNOWN = -999,
+  BOTTOM = 0,
+  TOP = 1,
+  NORTH = 2,
+  SOUTH = 3,
+  WEST = 4,
+  EAST = 5
+}
+```
+
+Useful when you want to constrain the desired face of the destination block.
+
+## `ShotEntity`
+
+```ts
+type ShotEntity = {
+  position: Vec3;
+  velocity: Vec3;
+  yaw?: number;
+  pitch?: number;
+  heldItem?: Item | null;
+};
+```
+
+Used by `EnderShotFactory.fromPlayer()`.
+
+## Example Flow
+
+```ts
+const target = bot.blockAt(player.position.offset(0, -1, 0));
+
+if (target) {
+  const plan = bot.ender.shotToBlock(target);
+
+  if (plan?.hit) {
+    await bot.ender.pearl(target, plan.shotInfo?.blockFace);
+  }
+}
+```
+
+## Caveats
+
+- The plugin is focused on pearl-to-block planning, not a broad teleport behavior framework
+- Several internal Mineflayer event declarations in `src/index.ts` are not emitted by the implementation shown here
+- `EnderShot` itself is not re-exported from the package root
+- The public API is still fairly low-level compared with more polished Mineflayer movement plugins

package/example/basic.ts

@@ -0,0 +1,82 @@
+import { createBot } from "mineflayer";
+import enderPearling from "../src/index";
+import { Vec3 } from "vec3";
+import utilPlugin from "@nxg-org/mineflayer-util-plugin"
+import {pathfinder, goals} from "mineflayer-pathfinder"
+import type { Entity } from "prismarine-entity";
+import type { Block } from "prismarine-block";
+import { promisify } from "util";
+
+const sleep = promisify(setTimeout)
+
+const bot = createBot({
+    username: "ender-testing",
+    host: process.argv[2] ?? "localhost",
+    port: Number(process.argv[3]) ?? 25565,
+});
+
+bot.loadPlugin(utilPlugin)
+bot.loadPlugin(enderPearling);
+bot.loadPlugin(pathfinder);
+let pearlThrown: boolean = false
+
+//lazy implementation. Will automate throwing later.
+// bot.on("physicsTick", async () => {
+//     target = bot.nearestEntity((e) => e.type === "player" && e !== bot.entity);
+//     if (!target) return;
+//     if (target.position.distanceTo(bot.entity.position) > 10) {
+//         if (!pearlThrown) pearlThrown = await pearl(target.username);
+//     } else {
+//         come(target.username);
+//         pearlThrown = false;
+//     }
+// });
+
+bot._client.prependListener("entity_velocity", (packet: any) => {
+    if (packet.entityId === bot.entity.id) {
+        bot.entity.velocity.set(0, 0, 0)
+    }
+
+})
+
+
+bot.on("chat", async (username, message) => {
+    const split = message.split(" ");
+    switch (split[0]) {
+        case "pearl":
+            pearl(split[1] ?? username)
+            break;
+        case "come":
+        case "here":
+            come(split[1] ?? username)
+            break;
+        case "stop":
+        case "cease":
+            bot.pathfinder.setGoal(null);
+            break;
+    }
+});
+
+function pearl(name?: string) {
+    const pearlTarget = bot.nearestEntity((e) => (e.username ?? e.name) === name);
+    if (!pearlTarget) {
+        console.log("no entity");
+        return false;
+    }
+    const pearlBlock = bot.blockAt(pearlTarget.position.offset(0, -1, 0));
+    if (!pearlBlock) {
+        console.log("no block under entity");
+        return false;
+    }
+    return bot.ender.pearl(pearlBlock, 1);
+}
+
+function come(name?: string) {
+    const comeTarget = bot.nearestEntity((e) => (e.username ?? e.name) === name);
+    if (!comeTarget) {
+        console.log("no entity");
+        return;
+    }
+    bot.pathfinder.setGoal(new goals.GoalFollow(comeTarget, 3), true);
+    // bot.util.move.followEntityWithRespectRange(comeTarget, 3);
+}

package/lib/calc/aabbUtil.d.ts

@@ -1,10 +1,10 @@
-import { AABB } from "@nxg-org/mineflayer-util-plugin";
-import type { Block } from "prismarine-block";
-import type { Vec3 } from "vec3";
-export declare function getEntityAABB(entity: {
-    position: Vec3;
-    height: number;
-    width?: number;
-}): AABB;
-export declare function getBlockAABB(block: Block, height?: number): AABB;
-export declare function getBlockPosAABB(block: Vec3, height?: number): AABB;
+import { AABB } from "@nxg-org/mineflayer-util-plugin";
+import type { Block } from "prismarine-block";
+import type { Vec3 } from "vec3";
+export declare function getEntityAABB(entity: {
+    position: Vec3;
+    height: number;
+    width?: number;
+}): AABB;
+export declare function getBlockAABB(block: Block, height?: number): AABB;
+export declare function getBlockPosAABB(block: Vec3, height?: number): AABB;

package/lib/calc/aabbUtil.js

@@ -1,21 +1,21 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.getBlockPosAABB = exports.getBlockAABB = exports.getEntityAABB = void 0;
-const mineflayer_util_plugin_1 = require("@nxg-org/mineflayer-util-plugin");
-function getEntityAABB(entity) {
-    var _a;
-    const w = (_a = entity.width) !== null && _a !== void 0 ? _a : (entity.height / 2);
-    const { x, y, z } = entity.position;
-    return new mineflayer_util_plugin_1.AABB(-w, 0, -w, w, entity.height, w).offset(x, y, z);
-}
-exports.getEntityAABB = getEntityAABB;
-function getBlockAABB(block, height = 1) {
-    const { x, y, z } = block.position;
-    return new mineflayer_util_plugin_1.AABB(x, y, z, x + 1, y + height, z + 1);
-}
-exports.getBlockAABB = getBlockAABB;
-function getBlockPosAABB(block, height = 1) {
-    const { x, y, z } = block.floored();
-    return new mineflayer_util_plugin_1.AABB(x, y, z, x + 1, y + height, z + 1);
-}
-exports.getBlockPosAABB = getBlockPosAABB;
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getBlockPosAABB = exports.getBlockAABB = exports.getEntityAABB = void 0;
+const mineflayer_util_plugin_1 = require("@nxg-org/mineflayer-util-plugin");
+function getEntityAABB(entity) {
+    var _a;
+    const w = (_a = entity.width) !== null && _a !== void 0 ? _a : (entity.height / 2);
+    const { x, y, z } = entity.position;
+    return new mineflayer_util_plugin_1.AABB(-w, 0, -w, w, entity.height, w).translate(x, y, z);
+}
+exports.getEntityAABB = getEntityAABB;
+function getBlockAABB(block, height = 1) {
+    const { x, y, z } = block.position;
+    return new mineflayer_util_plugin_1.AABB(x, y, z, x + 1, y + height, z + 1);
+}
+exports.getBlockAABB = getBlockAABB;
+function getBlockPosAABB(block, height = 1) {
+    const { x, y, z } = block.floored();
+    return new mineflayer_util_plugin_1.AABB(x, y, z, x + 1, y + height, z + 1);
+}
+exports.getBlockPosAABB = getBlockPosAABB;

package/lib/calc/constants.d.ts

@@ -1,27 +1,27 @@
-declare type ProjectileInfo = {
-    v0: number;
-    g: number;
-    ph: number;
-};
-declare type ProjectileInfos = {
-    [name: string]: ProjectileInfo;
-};
-declare type ProjectileGravity = {
-    [name: string]: number;
-};
-export declare const trajectoryInfo: ProjectileInfos;
-export declare const projectileGravity: ProjectileGravity;
-export declare const airResistance: {
-    y: number;
-    h: number;
-};
-export declare enum BlockFace {
-    UNKNOWN = -999,
-    BOTTOM = 0,
-    TOP = 1,
-    NORTH = 2,
-    SOUTH = 3,
-    WEST = 4,
-    EAST = 5
-}
-export {};
+type ProjectileInfo = {
+    v0: number;
+    g: number;
+    ph: number;
+};
+type ProjectileInfos = {
+    [name: string]: ProjectileInfo;
+};
+type ProjectileGravity = {
+    [name: string]: number;
+};
+export declare const trajectoryInfo: ProjectileInfos;
+export declare const projectileGravity: ProjectileGravity;
+export declare const airResistance: {
+    y: number;
+    h: number;
+};
+export declare enum BlockFace {
+    UNKNOWN = -999,
+    BOTTOM = 0,
+    TOP = 1,
+    NORTH = 2,
+    SOUTH = 3,
+    WEST = 4,
+    EAST = 5
+}
+export {};

package/lib/calc/constants.js

@@ -1,36 +1,36 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.BlockFace = exports.airResistance = exports.projectileGravity = exports.trajectoryInfo = void 0;
-exports.trajectoryInfo = {
-    bow: { v0: 3, g: -0.05, ph: 1.62 },
-    crossbow: { v0: 3.15, g: -0.05, ph: 1.62 },
-    crossbow_firework: { v0: 1.6, g: 0.00, ph: 1.62 },
-    trident: { v0: 2.5, g: -0.05, ph: 1.62 },
-    snowball: { v0: 1.5, g: -0.04, ph: 1.52 },
-    egg: { v0: 1.5, g: -0.04, ph: 1.52 },
-    ender_pearl: { v0: 1.5, g: -0.03, ph: 1.52 },
-    splash_potion: { v0: 0.4, g: -0.03, ph: 1.52 },
-};
-exports.projectileGravity = {
-    arrow: 0.05,
-    trident: 0.05,
-    egg: 0.04,
-    snowball: 0.04,
-    ender_pearl: 0.03,
-    splash_potion: 0.03,
-    firework_rocket: 0.00,
-};
-exports.airResistance = {
-    y: 0.01,
-    h: 0.01
-};
-var BlockFace;
-(function (BlockFace) {
-    BlockFace[BlockFace["UNKNOWN"] = -999] = "UNKNOWN";
-    BlockFace[BlockFace["BOTTOM"] = 0] = "BOTTOM";
-    BlockFace[BlockFace["TOP"] = 1] = "TOP";
-    BlockFace[BlockFace["NORTH"] = 2] = "NORTH";
-    BlockFace[BlockFace["SOUTH"] = 3] = "SOUTH";
-    BlockFace[BlockFace["WEST"] = 4] = "WEST";
-    BlockFace[BlockFace["EAST"] = 5] = "EAST";
-})(BlockFace = exports.BlockFace || (exports.BlockFace = {}));
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BlockFace = exports.airResistance = exports.projectileGravity = exports.trajectoryInfo = void 0;
+exports.trajectoryInfo = {
+    bow: { v0: 3, g: -0.05, ph: 1.62 },
+    crossbow: { v0: 3.15, g: -0.05, ph: 1.62 },
+    crossbow_firework: { v0: 1.6, g: 0.00, ph: 1.62 },
+    trident: { v0: 2.5, g: -0.05, ph: 1.62 },
+    snowball: { v0: 1.5, g: -0.04, ph: 1.52 },
+    egg: { v0: 1.5, g: -0.04, ph: 1.52 },
+    ender_pearl: { v0: 1.5, g: -0.03, ph: 1.52 },
+    splash_potion: { v0: 0.4, g: -0.03, ph: 1.52 },
+};
+exports.projectileGravity = {
+    arrow: 0.05,
+    trident: 0.05,
+    egg: 0.04,
+    snowball: 0.04,
+    ender_pearl: 0.03,
+    splash_potion: 0.03,
+    firework_rocket: 0.00,
+};
+exports.airResistance = {
+    y: 0.01,
+    h: 0.01
+};
+var BlockFace;
+(function (BlockFace) {
+    BlockFace[BlockFace["UNKNOWN"] = -999] = "UNKNOWN";
+    BlockFace[BlockFace["BOTTOM"] = 0] = "BOTTOM";
+    BlockFace[BlockFace["TOP"] = 1] = "TOP";
+    BlockFace[BlockFace["NORTH"] = 2] = "NORTH";
+    BlockFace[BlockFace["SOUTH"] = 3] = "SOUTH";
+    BlockFace[BlockFace["WEST"] = 4] = "WEST";
+    BlockFace[BlockFace["EAST"] = 5] = "EAST";
+})(BlockFace = exports.BlockFace || (exports.BlockFace = {}));