mineflayer-cicerone 1.0.0

package/index.js

@@ -0,0 +1,41 @@
+const Path = require('./lib/path');
+const { PathElement, ParentPathElement } = require('./lib/pathElement');
+const injectMovement = require('./lib/movement');
+const injectDigging = require('./lib/digging');
+const injectPlacement = require('./lib/placement');
+
+/**
+ * @param {import('mineflayer').Bot} bot
+ */
+function plugin(bot) {
+    if (!bot.cicerone) {
+        bot.cicerone = {};
+    }
+
+    bot.cicerone.settings = {
+        buildingBlocks: [
+            'cobblestone',
+            'dirt',
+            'stone',
+            'oak_planks',
+            'spruce_planks',
+            'birch_planks',
+            'jungle_planks',
+            'acacia_planks',
+            'dark_oak_planks',
+            'andesite',
+            'diorite',
+            'granite'
+        ]
+    };
+
+    injectMovement(bot);
+    injectDigging(bot);
+    injectPlacement(bot);
+}
+
+plugin.Path = Path;
+plugin.PathElement = PathElement;
+plugin.ParentPathElement = ParentPathElement;
+
+module.exports = plugin;

package/lib/digging.js

@@ -0,0 +1,56 @@
+/**
+ * @param {import('mineflayer').Bot} bot
+ * */ const {harvestTool} = require("./utils/inventory");
+module.exports = (bot) => {
+    bot.once('spawn', () => {
+        const originalDigTime = bot.digTime.bind(bot);
+
+        bot.digTime = (block) => {
+            if (!block) return 0;
+
+            const digTime = originalDigTime.call(bot, block);
+            const blockName = block.name;
+            const isSlowBlock = blockName.includes('_ore') || blockName === 'cobbled_deepslate'
+
+            return isSlowBlock ? Math.round(digTime * 1.5) + 250 : Math.round(digTime);
+        }
+    })
+
+    /**
+     * Breaks the block at the specified coordinates.
+     *
+     * @param {import('vec3').Vec3} position - Position of the target block.
+     * @returns {Promise<void>}
+     * */
+    bot.cicerone.digBlock = async (position) => {
+        while (!bot.entity.onGround) {
+            await bot.waitForTicks(1);
+        }
+
+        let block = bot.blockAt(position);
+        if (!block || !block.name || block.name === 'air') return;
+
+        try {
+            const tool = harvestTool(bot, block);
+            if (tool) {
+                await bot.equip(tool, 'hand');
+            }
+        } catch (e) {
+            console.warn(`[Cicerone] Tool selection warning: ${e.message}. Attempting to dig by hand.`);
+        }
+
+        while (block.name !== 'air' && block.name !== 'cave_air') {
+            try {
+                await bot.lookAt(block.position.clone().offset(0.5, 0.5, 0.5), true);
+                await bot.waitForTicks(5);
+                await bot.dig(block, false, 'raycast');
+            } catch (e) {
+                console.error(`[Cicerone] Failed to dig block at ${position}:`, e.message);
+                break;
+            }
+
+            await bot.waitForTicks(2);
+            block = bot.blockAt(position);
+        }
+    }
+}

package/lib/movement.js

@@ -0,0 +1,142 @@
+/**
+ * @typedef {Object} GotoOptions
+ * @property {number} [precision=0.15] - Hit radius in blocks.
+ * @property {number} [timeout=30_000] - Time to move in ms.
+ * */
+
+/**
+ * @param {import('mineflayer').Bot} bot
+ * */
+module.exports = (bot) => {
+    const DEFAULT_TIMEOUT_MS = 30_000;
+
+    let isMoving = false;
+    let moveTimeout = null;
+    let tickListener = null;
+
+    let activeResolve = null;
+    let activeReject = null;
+
+    /**
+     * Internal method for completely stopping movement and cleaning up resources.
+     * @param {Error|null} [err] - If passed, the promise will complete with an error (rejection).
+     *  */
+    const stopMovement = (err = null) => {
+        if (!isMoving) return;
+
+        isMoving = false;
+        bot.clearControlStates();
+
+        if (moveTimeout) {
+            clearTimeout(moveTimeout);
+            moveTimeout = null;
+        }
+
+        if (tickListener) {
+            bot.removeListener('physicsTick', tickListener);
+            tickListener = null;
+        }
+
+        const resolve = activeResolve;
+        const reject = activeReject;
+
+        activeResolve = null;
+        activeReject = null;
+
+        if (err) {
+            if (reject) reject(err);
+        } else {
+            if (resolve) resolve();
+        }
+    };
+
+    /**
+     * Moves the bot to the specified point along the horizontal plane (X, Z).
+     *
+     * @param {import('vec3').Vec3} vec - Coordinates of the target point.
+     * @param {GotoOptions} [options] - Movement settings.
+     * @returns {Promise<void>} - Allowed on successful arrival, rejected on error/timeout/abortion.
+     * */
+    bot.cicerone.goto = async (vec, options = {}) => {
+        const precision = options.precision ?? 0.15;
+        const timeoutMs = options.timeout ?? DEFAULT_TIMEOUT_MS;
+
+        if (isMoving) {
+            stopMovement(new Error('Movement interrupted by a new goto call.'));
+        }
+
+        isMoving = true;
+
+        // Offset target to block center.
+        const targetX = vec.x + 0.5;
+        const targetZ = vec.z + 0.5;
+
+        return new Promise((resolve, reject) => {
+            activeResolve = resolve;
+            activeReject = reject;
+
+            let lastDistance = Infinity;
+
+            moveTimeout = setTimeout(() => {
+                stopMovement(new Error(`Movement timeout at position: ${vec}`));
+            }, timeoutMs );
+
+            tickListener = () => {
+                if (!bot.entity) return;
+
+                const pos = bot.entity.position;
+                const dx = targetX - pos.x;
+                const dz = targetZ - pos.z;
+                const distance = Math.sqrt(dx * dx + dz * dz);
+
+                // Successful arrival
+                if (distance <= precision) {
+                    stopMovement();
+                    return;
+                }
+
+                if (distance > lastDistance + 0.05 && distance < 0.8) {
+                    stopMovement();
+                    return;
+                }
+
+                lastDistance = distance;
+
+                const targetYaw = Math.atan2(-dx, -dz);
+
+                // Normalization of angle differences to the range [-PI, PI]
+                let diffYaw = (targetYaw - bot.entity.yaw) % (Math.PI * 2);
+                if (diffYaw > Math.PI) diffYaw -= Math.PI * 2;
+                if (diffYaw < -Math.PI) diffYaw += Math.PI * 2;
+
+                bot.look(targetYaw, bot.entity.pitch, true).catch(() => {});
+
+                // Starts walking forward only if the bot is looking roughly in the direction of the target.
+                // Margin of error ~2.86 degrees.
+                if (Math.abs(diffYaw) < 0.05) {
+                    bot.setControlState('forward', true);
+                } else {
+                    bot.setControlState('forward', false);
+                }
+
+                // It slows down (sneak) when getting very close, to avoid overshooting the point.
+                if (distance < 0.6) {
+                    bot.setControlState('sneak', true);
+                } else {
+                    bot.setControlState('sneak', false);
+                }
+            };
+
+            bot.on('physicsTick', tickListener);
+        });
+    };
+
+    /**
+     * Forcefully stops the bot's current movement.
+     * */
+    bot.cicerone.stopMove = () => {
+        if (isMoving) {
+            stopMovement(new Error('Movement was forcefully interrupted.'));
+        }
+    };
+};

package/lib/path.js

@@ -0,0 +1,103 @@
+const vec3 = require('vec3');
+const { PathElement, ParentPathElement } = require('./pathElement');
+
+class Path {
+    constructor() {
+        this.pathElements = [];
+        this.lastParentElement = null;
+    }
+
+    /**
+     * Adds a new element to the path.
+     *
+     * @param {import('vec3').Vec3} position
+     * @param {string} type
+     */
+    add(position, type) {
+        if (this.pathElements.length === 0 || type === 'move') {
+            const parent = new ParentPathElement(position, type);
+            this.pathElements.push(parent);
+            this.lastParentElement = parent;
+        } else if (this.lastParentElement) {
+            const child = new PathElement(position, type);
+            this.lastParentElement.addChild(child);
+        }
+    }
+
+    /**
+     * Clear path.
+     * */
+    reset() {
+        this.pathElements = [];
+        this.lastParentElement = null;
+    }
+
+    /**
+     * Performs the route.
+     *
+     * @param {import('mineflayer').Bot} bot
+     */
+    async resolve(bot) {
+        while (this.pathElements.length > 0) {
+            const currentParent = this.pathElements.shift();
+            await currentParent.resolve(bot);
+
+            while (currentParent.hasChildren()) {
+                const child = currentParent.children.shift();
+                await child.resolve(bot);
+            }
+        }
+    }
+
+    /**
+     * Performs the return route.
+     *
+     * @param {import('mineflayer').Bot} bot
+     */
+    async revert(bot) {
+        while (this.pathElements.length > 0) {
+            const currentParent = this.pathElements.pop();
+            await currentParent.revert(bot);
+
+            while (currentParent.hasChildren()) {
+                const child = currentParent.children.pop();
+                await child.revert(bot);
+            }
+        }
+    }
+
+    toJSON() {
+        return this.pathElements;
+    }
+
+    /**
+     * Reconstructs the path from JSON format.
+     *
+     * @param {Array|string} json
+     * @returns {Path}
+     */
+    static fromJSON(json) {
+        const rawElements = typeof json === 'string' ? JSON.parse(json) : json;
+        const pathInstance = new Path();
+
+        pathInstance.pathElements = rawElements.map(parentRaw => {
+            const parentPos = new vec3(parentRaw.position.x, parentRaw.position.y, parentRaw.position.z);
+            const parent = new ParentPathElement(parentPos, parentRaw.type);
+
+            if (parentRaw.children && Array.isArray(parentRaw.children)) {
+                parentRaw.children.forEach(childRaw => {
+                    const childPos = new vec3(childRaw.position.x, childRaw.position.y, childRaw.position.z);
+                    const child = new PathElement(childPos, childRaw.type);
+                    parent.addChild(child);
+                });
+            }
+            return parent;
+        });
+
+        pathInstance.lastParentElement = pathInstance.pathElements[pathInstance.pathElements.length - 1] || null;
+
+        return pathInstance;
+    }
+}
+
+module.exports = Path;

package/lib/pathElement.js

@@ -0,0 +1,112 @@
+const elementType = Object.freeze({
+    move: 'move',
+    dig: 'dig',
+    place: 'place',
+    down: 'down',
+    up: 'up',
+});
+
+const resolveMap = Object.freeze({
+    [elementType.move]: async (bot, position) => {
+        await bot.cicerone.goto(position);
+    },
+    [elementType.dig]: async (bot, position) => {
+        await bot.cicerone.digBlock(position);
+    },
+    [elementType.place]: async (bot, position) => {
+        await bot.cicerone.placeBuildingBlock(position);
+    },
+    [elementType.down]: async (bot, position) => {
+        await bot.cicerone.digBlock(position);
+    },
+    [elementType.up]: async (bot, _) => {
+        await bot.cicerone.buildUp();
+    }
+});
+
+const revertMap = Object.freeze({
+    [elementType.move]: async (bot, position) => {
+        await bot.cicerone.goto(position);
+    },
+    [elementType.dig]: async (bot, position) => {
+        await bot.cicerone.placeBuildingBlock(position);
+    },
+    [elementType.place]: async (bot, position) => {
+        await bot.cicerone.digBlock(position);
+    },
+    [elementType.down]: async (bot, _) => {
+        await bot.cicerone.buildUp();
+    },
+    [elementType.up]: async (bot, position) => {
+        await bot.cicerone.digBlock(position);
+    }
+});
+
+class PathElement {
+    /**
+     * @param {import('vec3').Vec3} position
+     * @param {keyof typeof elementType} type
+     */
+    constructor(position, type) {
+        this.position = position;
+        this.type = type;
+    }
+
+    getInfo() {
+        return `Type: ${this.type}, Position: ${this.position}`;
+    }
+
+    async resolve(bot) {
+        const handler = resolveMap[this.type];
+        if (handler) {
+            try {
+                await handler(bot, this.position);
+            } catch (e) {
+                throw new Error(`[Cicerone] Unable to resolve [${this.getInfo()}]: ${e.message}`);
+            }
+        } else {
+            throw new Error(`[Cicerone] Unhandled resolve for type: ${this.type}`);
+        }
+    }
+
+    async revert(bot) {
+        const handler = revertMap[this.type];
+        if (handler) {
+            try {
+                await handler(bot, this.position);
+            } catch (e) {
+                throw new Error(`[Cicerone] Unable to revert [${this.getInfo()}]: ${e.message}`);
+            }
+        } else {
+            throw new Error(`[Cicerone] Unhandled revert for type: ${this.type}`);
+        }
+    }
+}
+
+class ParentPathElement extends PathElement {
+    /**
+     * @param {import('vec3').Vec3} position
+     * @param {keyof typeof elementType} type
+     */
+    constructor(position, type) {
+        super(position, type);
+        this.children = [];
+    }
+
+    /**
+     * @param {PathElement} child
+     */
+    addChild(child) {
+        this.children.push(child);
+    }
+
+    hasChildren() {
+        return this.children.length > 0;
+    }
+}
+
+module.exports = {
+    elementType,
+    PathElement,
+    ParentPathElement
+};

package/lib/placement.js

@@ -0,0 +1,128 @@
+const { Vec3 } = require('vec3');
+
+/**
+ * Finds an adjacent solid block on whose edge a new block can be placed.
+ *
+ * @param {import('mineflayer').Bot} bot
+ * @param {import('vec3').Vec3} position - The target point where the block should be placed.
+ * @returns {{ referenceBlock: ReturnType<import('mineflayer').Bot['blockAt']>, faceVector: import('vec3').Vec3 | null }}
+ * */
+function getReferenceBlockAndFaceVector(bot, position) {
+    const directions = [
+        new Vec3(0, -1, 0),
+        new Vec3(0, 1, 0),
+        new Vec3(-1, 0, 0),
+        new Vec3(1, 0, 0),
+        new Vec3(0, 0, -1),
+        new Vec3(0, 0, 1)
+    ];
+
+    for (const dir of directions) {
+        const referenceBlockPos = position.plus(dir);
+        const block = bot.blockAt(referenceBlockPos);
+
+        if (block && block.name !== 'air' && block.name !== 'cave_air' && block.name !== 'water' && block.name !== 'lava') {
+            const faceVector = dir.scaled(-1);
+            return { referenceBlock: block, faceVector };
+        }
+    }
+
+    return { referenceBlock: null, faceVector: null };
+}
+
+/**
+ * Finds any solid building block in the bot's inventory and equips it.
+ *
+ * @param {import('mineflayer').Bot} bot
+ * @returns {Promise<import('prismarine-item').Item>}
+ */
+async function equipBuildingBlock(bot) {
+    const allowedBlocks = bot.cicerone?.settings?.buildingBlocks || [];
+
+    if (allowedBlocks.length === 0) {
+        throw new Error('[Cicerone] No building blocks configured in bot.cicerone.settings.buildingBlocks');
+    }
+
+    const item = bot.inventory.items().find(i => allowedBlocks.includes(i.name));
+
+    if (!item) {
+        throw new Error('[Cicerone] No suitable building blocks found in inventory matching your settings.');
+    }
+
+    await bot.equip(item, 'hand');
+    return item;
+}
+
+/**
+ * @param {import('mineflayer').Bot} bot
+ */
+module.exports = (bot) => {
+    /**
+     * Safely places a building block at the specified coordinates.
+     *
+     * @param {import('vec3').Vec3} position - The target point where the block should be placed
+     * @returns {Promise<void>}
+     */
+    bot.cicerone.placeBuildingBlock = async (position) => {
+        const { referenceBlock, faceVector } = getReferenceBlockAndFaceVector(bot, position);
+
+        if (!referenceBlock || !faceVector) {
+            throw new Error(`[Cicerone] Reference block not found to place block at position: ${position}`);
+        }
+
+        await equipBuildingBlock(bot);
+
+        const lookTarget = referenceBlock.position.plus(faceVector.scaled(0.5));
+        await bot.lookAt(lookTarget, true);
+        await bot.waitForTicks(1);
+
+        await bot.placeBlock(referenceBlock, faceVector);
+    };
+
+    /**
+     * Causes the bot to jump and place a building block underneath itself.
+     *
+     * @returns {Promise<void>}
+     */
+    bot.cicerone.buildUp = async () => {
+        bot.clearControlStates();
+
+        while (!bot.entity.onGround) {
+            await bot.waitForTicks(1);
+        }
+
+        const initialPosition = bot.entity.position.clone();
+        const targetBlockPosition = initialPosition.floored();
+
+        await equipBuildingBlock(bot);
+        await bot.waitForTicks(1);
+
+        bot.setControlState('jump', true);
+
+        return new Promise((resolve, reject) => {
+            const yPosListener = async () => {
+                if (!bot.entity) {
+                    bot.removeListener('physicsTick', yPosListener);
+                    reject(new Error('Bot disconnected during buildup.'));
+                    return;
+                }
+
+                if (bot.entity.position.y >= initialPosition.y + 1.15) {
+                    bot.removeListener('physicsTick', yPosListener);
+                    bot.setControlState('jump', false);
+
+                    try {
+                        await bot.cicerone.placeBuildingBlock(targetBlockPosition);
+                        resolve();
+                    } catch (err) {
+                        reject(err);
+                    } finally {
+                        bot.clearControlStates();
+                    }
+                }
+            };
+
+            bot.on('physicsTick', yPosListener);
+        });
+    };
+}

package/lib/utils/inventory.js

@@ -0,0 +1,61 @@
+const {getEnchantments, getDurability} = require('./item')
+
+/**
+ * Finds the most suitable tool for mining the specified block in the bot's inventory.
+ *
+ * @param {import('mineflayer').Bot} bot - An instance of the mineflayer bot.
+ * @param {import('prismarine-block').Block} block - Target block.
+ * @returns {import('prismarine-item').Item | null} The optimal tool, or null if the tool is not required.
+ * @throws {Error} If a block requires a tool, but there is no suitable one in the inventory.
+ * */
+function harvestTool(bot, block) {
+    const MIN_DURABILITY = 5;
+
+    if (!block.material) {
+        return null;
+    }
+
+    const materialParts = block.material.split('/');
+    const toolName = materialParts[1];
+
+    if (!toolName) {
+        return null;
+    }
+
+    let isOre = block.name.includes('_ore');
+
+    const tools = bot.inventory.items().filter(item => {
+        if (!item.name.includes(toolName)) return false;
+
+        if (item.maxDurability) {
+            const remainingDurability = getDurability(item);
+
+            if (remainingDurability <= MIN_DURABILITY ) {
+                return false;
+            }
+        }
+
+        return true;
+    });
+
+    if (tools.length === 0) {
+        throw new Error(`Could not find matching tool of type: ${toolName}`);
+    }
+
+    let tool;
+    if (isOre) {
+        tool = tools.find(item => getEnchantments(item).silk_touch);
+    } else {
+        tool = tools.find(item => getEnchantments(item).fortune);
+    }
+
+    if (!tool) {
+        tool = tools[0];
+    }
+
+    return tool;
+}
+
+module.exports = {
+    harvestTool,
+}

package/lib/utils/item.js

@@ -0,0 +1,39 @@
+/**
+ * Converts an item's enchantments into "name:level" format.
+ *
+ * @param {import('prismarine-item').Item | null} item - Item to be checked.
+ * @returns {Object<string, number>} Enchantment List.
+ * */
+function getEnchantments(item) {
+    const enchants = {};
+
+    if (!item) return enchants;
+
+    if (item.enchants && Array.isArray(item.enchants)) {
+        for (const enchant of item.enchants) {
+            enchants[enchant.name] = enchant.lvl;
+        }
+    }
+
+    return enchants;
+}
+
+/**
+ * Calculates the remaining durability of the item.
+ *
+ * @param {import('prismarine-item').Item | null} item - Item to be checked.
+ * @returns {number} Remaining amount of durability units.
+ * */
+function getDurability(item) {
+    if (!item) return 0;
+    const max = item.maxDurability;
+    if (!max) return 100;
+
+    const used = item.durabilityUsed || 0;
+    return max - used;
+}
+
+module.exports = {
+    getEnchantments,
+    getDurability,
+}

package/package.json

@@ -0,0 +1,24 @@
+{
+	"name": "mineflayer-cicerone",
+	"version": "1.0.0",
+	"description": "An advanced plugin for navigation and action execution for Mineflayer.",
+	"main": "index.js",
+	"scripts": {
+		"test": "echo \"Error: no test specified\" && exit 1"
+	},
+	"keywords": [
+		"mineflayer",
+		"minecraft",
+		"bot",
+		"navigation",
+		"cicerone"
+	],
+	"author": "Lirihiwa",
+	"license": "MIT",
+	"peerDependencies": {
+		"mineflayer": "^4.37.1"
+	},
+	"dependencies": {
+		"vec3": "^0.2.0"
+	}
+}