# Minecraft JS Function Reference These are the JavaScript functions available to agents at runtime. Call them with `await` inside your action code. The action sandbox is restricted: use these provided functions plus standard JavaScript syntax. Global timers such as `setTimeout` and `setInterval` are not available. Do NOT pass a `bot` argument; it is supplied automatically. Call e.g. `await skills.attackPlayer("Jack")`, not `skills.attackPlayer(bot, "Jack")`. ## Skills ### `skills.craftRecipe(itemName, num = 1)` Attempt to craft the given item name from a recipe. May craft many items. Recipes that need a crafting table require one within reach (4.5 blocks). **Parameters:** - `itemName` — the item name to craft. - `num` — the number of times to craft the recipe. Defaults to 1. **Returns:** true if the recipe was crafted, false otherwise. **Example:** ```js await skills.craftRecipe("stick"); await skills.craftRecipe("oak_planks", 4); ``` --- ### `skills.smeltItem(itemName, num = 1, options = {})` Put the given item in a furnace within reach (4.5 blocks). Add fuel as needed. Collect the output. The server decides whether the item has a recipe. Stop after 1 second without progress. Leave the remaining items in the furnace. - fuel: the item to burn, e.g. "oak_planks". Defaults to coal or charcoal, then logs or planks, then coal blocks or lava buckets, then other fuels without durability. - fuelCount: the number of fuel items to add. Defaults to the amount that the fuel duration and furnace recipe require. Unknown durations require an explicit count. The furnace holds one fuel type at a time, and accepts only items that burn. **Parameters:** - `itemName` — the item name to put in the furnace input slot. - `num` — the number of items to smelt. Defaults to 1. - `options` — optional fuel settings: **Returns:** true if the item was smelted, false otherwise. **Example:** ```js await skills.smeltItem("raw_iron"); await skills.smeltItem("beef"); await skills.smeltItem("raw_iron", 3, { fuel: "oak_planks" }); await skills.smeltItem("raw_iron", 8, { fuel: "stick", fuelCount: 16 }); ``` --- ### `skills.clearNearestFurnace()` Clear the nearest furnace, within reach (4.5 blocks), of all items. **Returns:** true if the furnace was cleared, false otherwise. **Example:** ```js await skills.clearNearestFurnace(); ``` --- ### `skills.attackNearest(mobType, kill = true)` Attack the nearest mob of the given type. Accepts "player" as mobType to attack the nearest player. Does not auto-equip a weapon or pick up loot. **Parameters:** - `mobType` — the type of mob to attack (e.g. "zombie", "skeleton", "player"). - `kill` — whether or not to continue attacking until the mob is dead. Defaults to true. **Returns:** true if the mob was attacked, false if the mob type was not found. **Example:** ```js await skills.attackNearest("zombie", true); await skills.attackNearest("player"); ``` --- ### `skills.attackEntity(entity, kill = true)` Attack the given entity. Does not auto-equip a weapon or pick up loot. **Parameters:** - `entity` — the entity to attack. - `kill` — whether to continue attacking until the entity is dead. Defaults to true. **Returns:** true if the entity was attacked, false if interrupted. **Example:** ```js let entity = world.getNearestEntityWhere(e => e.name === "zombie", 16); await skills.attackEntity(entity, true); ``` --- ### `skills.attackPlayer(player_name)` Attack the given player. **Parameters:** - `player_name` — the name of the player to attack. **Returns:** true if the player was attacked, false if interrupted **Example:** ```js await skills.attackPlayer("player_name"); ``` --- ### `skills.voteForPlayer(player_name)` Vote for another player. Each agent can only vote once per game. You cannot vote for yourself. To pick one of a challenge's predefined options (e.g. a room or path), use skills.voteForOption instead. **Parameters:** - `player_name` — the name of the player to vote for. **Returns:** true if the vote was cast, false if trying to vote for yourself. **Example:** ```js await skills.voteForPlayer("player_name"); ``` --- ### `skills.voteForOption(vote_id, option)` Cast your vote in one of the challenge's votes. Each vote has a fixed set of options; the available votes and options are described in your task. You can vote only once per vote — a second vote for the same vote_id is ignored. To vote for or against another participant instead, use skills.voteForPlayer. vote_id or option is not valid for this challenge. **Parameters:** - `vote_id` — the id of the vote, e.g. "selectroom". - `option` — the option you pick, e.g. "red". **Returns:** true if a valid vote was submitted, false if the **Example:** ```js await skills.voteForOption("selectroom", "red"); ``` --- ### `skills.shootArrow(target_name, force = 1.0)` Shoot an arrow at the specified player. **Parameters:** - `target_name` — - The username of the player to shoot at - `force` — - Optional force/power for the shot (0.1-1.0), defaults to 1.0 **Returns:** true if arrow was shot, false otherwise **Example:** ```js await skills.shootArrow("player_name", 0.8); ``` --- ### `skills.shootArrowAt(x, y, z, force = 1.0)` Shoot an arrow at specific coordinates. **Parameters:** - `x` — - X coordinate to shoot at - `y` — - Y coordinate to shoot at - `z` — - Z coordinate to shoot at - `force` — - Optional force/power for the shot (0.1-1.0), defaults to 1.0 **Returns:** true if arrow was shot, false otherwise **Example:** ```js await skills.shootArrowAt(100, 65, 200, 0.9); ``` --- ### `skills.shootArrowAtEntity(entity_type, force = 1.0)` Shoot an arrow at the nearest entity of specified type. **Parameters:** - `entity_type` — - The type of entity to shoot (e.g., "pig", "zombie", "creeper") - `force` — - Optional force/power for the shot (0.1-1.0), defaults to 1.0 **Returns:** true if arrow was shot, false otherwise **Example:** ```js await skills.shootArrowAtEntity("pig", 0.7); await skills.shootArrowAtEntity("zombie", 1.0); ``` --- ### `skills.shootArrowAtBlock(block_type, force = 1.0)` Shoot an arrow at the nearest block of specified type. **Parameters:** - `block_type` — - The type of block to shoot at (e.g., "target", "glass", "wood_button") - `force` — - Optional force/power for the shot (0.1-1.0), defaults to 1.0 **Returns:** true if arrow was shot, false otherwise **Example:** ```js await skills.shootArrowAtBlock("target", 1.0); await skills.shootArrowAtBlock("glass", 0.5); ``` --- ### `skills.pickupNearbyItems(distance = 8)` Pick up all nearby items. **Parameters:** - `distance` — the maximum distance from the bot to search. Defaults to 8. **Returns:** true if one or more items were picked up, false otherwise. **Example:** ```js await skills.pickupNearbyItems(); ``` --- ### `skills.pickupItemsAt(x, y, z, distance = 8)` Pick up all item entities within a radius of the given coordinates. **Parameters:** - `x` — the x coordinate of the center position. - `y` — the y coordinate of the center position. - `z` — the z coordinate of the center position. - `distance` — the maximum distance from the target position to search. Defaults to 8. **Returns:** true if one or more items were picked up, false otherwise. **Example:** ```js await skills.pickupItemsAt(100, 65, 200, 4) ``` --- ### `skills.breakBlockAt(x, y, z, force = false)` Break the block at the given position. Will use the bot's most adapted tool to break the block. If the bot is in survival mode and has no tool that can harvest the block, the skill will fail, unless force is `true` in which case the block will be broken with bare hands. The block must be within reach (4.5 blocks). Fractional coordinates are floored to the containing block (e.g. y=-61.06 targets the block at y=-62); the result message reports that block's integer coordinates. **Parameters:** - `x` — the x coordinate of the block to break. - `y` — the y coordinate of the block to break. - `z` — the z coordinate of the block to break. - `force` — if true, the block will be broken with bare hands if no adapted tool is found. **Returns:** true if the block was broken, false otherwise. **Example:** ```js let position = world.getPosition(); await skills.breakBlockAt(position.x, position.y - 1, position.z); ``` --- ### `skills.placeBlock(blockType, x, y, z, placeOn = "auto", dontCheat = false)` Place the given block type at the given position, building off from any adjacent solid block. For oriented blocks (torches, stairs, levers, buttons, ladders, doors, beds, repeaters, signs, etc.), `placeOn` selects which adjacent face the new block attaches to and therefore which direction it faces. For plain cube blocks (cobblestone, oak_log, dirt, ...), placeOn just disambiguates which neighbor is used and the visual result is identical. placeOn values: - 'auto' — no orientation preference; build off any available neighbor - 'bottom' — build off the block below the target (e.g. floor torch) - 'top' — build off the block above (e.g. ceiling button / lever) - 'side' — build off any horizontal neighbor (e.g. wall torch) - 'north' | 'south' | 'east' | 'west' — build off that specific neighbor (e.g. wall torch facing a specific direction, stair orientation) Fails (returns false) if: - placeOn is not one of the values above, - the target position is not empty (break the obstructing block first), - there is no adjacent block to build off of (with the chosen placeOn), - your body is occupying the target volume (jump or move away first), - you are more than 4.5 blocks from the target. The last four apply only outside cheat mode. Fractional coordinates are floored to the containing block; the result message reports that block's integer coordinates. Outside cheat mode the target must be within reach (4.5 blocks), and it will not move out of its own way. In cheat mode, uses /setblock with automatic block-state handling for facing-aware blocks: it works from any distance, needs no adjacent block, and can overwrite an occupied position, so do not walk, fly, or teleport between placements. For a solid or hollow box, cheats.fillBlocks places the whole region in one call and is far faster than a placeBlock loop. In creative mode, auto-spawns items into inventory if not already held. are canonical ("repeater", "redstone_wire"); a "minecraft:" prefix and the aliases "redstone_dust"/"redstone" are accepted. A "[state=value,...]" suffix is accepted too: in cheat mode its valid states are set as written ("repeater[facing=east,delay=2]", "piston[facing=up]"); by hand only facing/face apply, mapped onto placeOn when placeOn is "auto", and the half of a slab ("oak_slab[type=top]") or of stairs and trapdoors ("oak_stairs[half=top]"). A top half needs a block above or beside the target, a bottom half a block below or beside it. The log says what was rewritten or ignored. In cheat mode "air" clears the block; by hand, use breakBlockAt instead. **Parameters:** - `blockType` — the type of block to place. Bare minecraft-data names - `x` — the x coordinate of the block to place. - `y` — the y coordinate of the block to place. - `z` — the z coordinate of the block to place. - `placeOn` — which adjacent face to build off. One of 'auto', 'top', 'bottom', 'side', 'north', 'south', 'east', 'west'. Defaults to 'auto'. - `dontCheat` — overrides cheat mode to place the block normally. Defaults to false. **Returns:** true if the block was placed, false otherwise. **Example:** ```js let p = world.getPosition(); await skills.placeBlock("oak_log", p.x + 2, p.y, p.z); await skills.placeBlock("torch", p.x + 1, p.y, p.z, "north"); // wall torch facing north await skills.placeBlock("oak_stairs", p.x, p.y, p.z + 1, "east"); // stairs facing east await skills.placeBlock("oak_slab[type=top]", p.x + 1, p.y + 1, p.z); // slab in the upper half ``` --- ### `skills.equip(itemName, destination = "auto")` Equip the given item to the proper body part, like tools or armor. The item can be a bare id or a label from your observation: a label picks that exact stack ("diamond_sword[enchantments={sharpness:5}]" equips the Sharpness sword, not another diamond sword). The parts of a label you leave out do not matter: "stone_sword[enchantments={fire_aspect:2}]" matches it whatever its wear. **Parameters:** - `itemName` — the item id or label to equip. - `destination` — where to equip it: "auto" (armor to its slot, a shield to the off-hand, anything else to the hand), "hand", "off-hand", "head", "chest", "legs" or "feet". Defaults to "auto". **Returns:** true if the item was equipped, false otherwise. **Example:** ```js await skills.equip("iron_pickaxe"); await skills.equip("totem_of_undying", "off-hand"); await skills.equip("diamond_sword[enchantments={sharpness:5}]"); ``` --- ### `skills.discard(itemName, num = -1)` Discard the given item. A label from your observation picks the stacks that match it; a bare id discards every stack of that item. **Parameters:** - `itemName` — the item id or label to discard. - `num` — the number of items to discard. Defaults to -1, which discards all items. **Returns:** true if the item was discarded, false otherwise. **Example:** ```js await skills.discard("oak_log"); ``` --- ### `skills.putInNearestChest(itemName, num = -1)` Put the given item in the nearest chest (searched within 32 blocks); walks into reach first if needed. **Parameters:** - `itemName` — the item id, or a label from your observation to put that exact stack. - `num` — the number of items to put in the chest. Defaults to -1, which puts all items. **Returns:** true if the item was put in the chest, false otherwise. **Example:** ```js await skills.putInNearestChest("oak_log"); ``` --- ### `skills.putInChestAt(x, y, z, itemName, num = -1)` Put the given item in the chest at the given coordinates; walks into reach (4.5 blocks) first if needed. **Parameters:** - `x` — the x coordinate of the chest. - `y` — the y coordinate of the chest. - `z` — the z coordinate of the chest. - `itemName` — the item id, or a label from your observation to put that exact stack. - `num` — the number of items to put in the chest. Defaults to -1, which puts all items. **Returns:** true if the item was put in the chest, false otherwise. **Example:** ```js await skills.putInChestAt(100, 65, 200, "oak_log"); ``` --- ### `skills.takeFromNearestChest(itemName, num = -1)` Take the given item from the nearest chest (searched within 32 blocks); walks into reach first if needed. **Parameters:** - `itemName` — the item id, or a label: in a chest a label tells stacks apart by name, lore, enchantments and wear only. - `num` — the number of items to take from the chest. Defaults to -1, which takes all items. **Returns:** true if the item was taken from the chest, false otherwise. **Example:** ```js await skills.takeFromNearestChest("oak_log"); ``` --- ### `skills.takeFromChestAt(x, y, z, itemName, num = -1)` Take the given item from the chest at the given coordinates; walks into reach (4.5 blocks) first if needed. **Parameters:** - `x` — the x coordinate of the chest. - `y` — the y coordinate of the chest. - `z` — the z coordinate of the chest. - `itemName` — the item id, or a label: in a chest a label tells stacks apart by name, lore, enchantments and wear only. - `num` — the number of items to take from the chest. Defaults to -1, which takes all items. **Returns:** true if the item was taken from the chest, false otherwise. **Example:** ```js await skills.takeFromChestAt(100, 65, 200, "oak_log"); ``` --- ### `skills.viewNearestChest()` View the contents of the nearest chest (searched within 32 blocks); walks into reach first if needed. **Returns:** true if the chest was viewed, false otherwise. **Example:** ```js await skills.viewNearestChest(); ``` --- ### `skills.viewChestAt(x, y, z)` View the contents of the chest at the given coordinates; walks into reach (4.5 blocks) first if needed. **Parameters:** - `x` — the x coordinate of the chest. - `y` — the y coordinate of the chest. - `z` — the z coordinate of the chest. **Returns:** true if the chest was viewed, false otherwise. **Example:** ```js await skills.viewChestAt(100, 65, 200); ``` --- ### `skills.tradeWithVillager(entity, offerIndex, times = 1)` Buy or sell through a villager's live offers in survival. Walk into reach (3 blocks), open the trader, then execute the selected offer exactly `times` times. `offerIndex` is zero-based, matching the order of the villager's Offers.Recipes in nearby observations' additional.nbt. Prices and stock are read again from the live window; the observation can be stale. Refuse before spending if the initial stock or either payment is insufficient. Requires a free inventory slot for the result. Stop between trades on interruption or failure; a partial batch is not rolled back. Always close the window, and report how many trades completed. Exhausted offers may restock later; this skill does not wait for or force a restock. **Parameters:** - `entity` — - A villager or wandering trader from a world entity query. - `offerIndex` — - Zero-based live offer index. - `times` — - Positive integer number of trades, default 1. **Returns:** True only when all requested trades completed. **Example:** ```js const trader = world.getNearestEntityWhere(e => e.name === "villager", 16); await skills.tradeWithVillager(trader, 0, 2); ``` --- ### `skills.consume(itemName = "")` Eat/drink the given item. Works with food (e.g. "cooked_beef", "bread", "apple", "golden_apple"), potions ("potion"), and milk ("milk_bucket"). The item must be in your inventory. Normal food needs an empty slot in your hunger bar. Potions, milk, golden apples, chorus fruit and suspicious stew work at full hunger too. A label from your observation picks that exact stack, so with several potions you drink the one you name. **Parameters:** - `itemName` — the item id or label to eat/drink. **Returns:** true if the item was consumed, false otherwise. **Example:** ```js await skills.consume("cooked_beef"); await skills.consume("potion[potion_contents={potion:swiftness}]"); ``` --- ### `skills.giveToPlayer(itemType, username, num = 1)` Give the specified item(s) to the specified player. The items move directly from your inventory into theirs — nothing is dropped on the ground. You must be within 3 blocks of them. Works for both agents and human players. Note: the items arrive as fresh copies, so durability, enchantments and every other component of a label are not preserved. **Parameters:** - `itemType` — the item id to give; a label gives fresh items of its id. - `username` — the username of the player to give the item to. - `num` — the number of items to give. Defaults to 1. **Returns:** true if the items were given, false otherwise. **Example:** ```js await skills.giveToPlayer("oak_log", "player1"); ``` --- ### `skills.goToPosition(x, y, z, min_distance = 2)` Navigate to the given position. The pathfinder only walks, jumps, and swims — it will NOT break or place blocks to clear a path. If the route is blocked, break or place blocks yourself before calling this. In cheat mode, teleports instantly instead. **Parameters:** - `x` — the x coordinate to navigate to. - `y` — the y coordinate to navigate to. - `z` — the z coordinate to navigate to. - `min_distance` — the distance to keep from the position. Defaults to 2. Clamped to a minimum of 0.25. **Returns:** true if the position was reached, false otherwise. **Example:** ```js let position = world.getNearestBlock("oak_log", 64).position; await skills.goToPosition(position.x, position.y, position.z); ``` --- ### `skills.goToNearestBlock(blockType, min_distance = 2, range = 64)` Navigate to the nearest block of the given type. The pathfinder only walks, jumps, and swims — it will NOT break or place blocks to clear a path. In cheat mode, teleports instead. **Parameters:** - `blockType` — the type of block to navigate to. - `min_distance` — the distance to keep from the block. Defaults to 2. - `range` — the range to look for the block. Defaults to 64. **Returns:** true if the block was reached, false otherwise. **Example:** ```js await skills.goToNearestBlock("oak_log"); ``` --- ### `skills.goToNearestEntity(entityType, min_distance = 2, range = 64)` Navigate to the nearest entity of the given type. The pathfinder only walks, jumps, and swims — it will NOT break or place blocks to clear a path. In cheat mode, teleports instead. **Parameters:** - `entityType` — the type of entity to navigate to. - `min_distance` — the distance to keep from the entity. Defaults to 2. - `range` — the range to look for the entity. Defaults to 64. **Returns:** true if the entity was reached, false otherwise. **Example:** ```js await skills.goToNearestEntity("cow", 2, 32); ``` --- ### `skills.goToPlayer(username, distance = 3)` Navigate to the given player. The pathfinder only walks, jumps, and swims — it will NOT break or place blocks to clear a path. In cheat mode, teleports instantly instead. **Parameters:** - `username` — the username of the player to navigate to. - `distance` — the goal distance to the player. Defaults to 3. **Returns:** true if the player was reached, false otherwise. **Example:** ```js await skills.goToPlayer("player"); ``` --- ### `skills.moveAway(distance)` Move away from current position in any direction. The pathfinder only walks, jumps, and swims — it will NOT break or place blocks to clear a path. **Parameters:** - `distance` — the distance to move away. **Returns:** true if the bot moved away, false otherwise. **Example:** ```js await skills.moveAway(8); ``` --- ### `skills.moveAwayFromEntity(entity, distance = 16)` Move away from the given entity. The pathfinder only walks, jumps, and swims — it will NOT break or place blocks to clear a path. **Parameters:** - `entity` — the entity to move away from. - `distance` — the distance to move away. Defaults to 16. **Returns:** true if the bot moved away, false otherwise. **Example:** ```js let creeper = world.getNearestEntityWhere((e) => e.name === "creeper", 16); if (creeper) await skills.moveAwayFromEntity(creeper, 10); ``` --- ### `skills.wait(seconds = 1)` Wait in place, doing nothing, for a number of seconds. This is the way to pause or let time pass: for a timer, a phase change, or another player. New code you send interrupts the wait. **Parameters:** - `seconds` — how long to wait. Defaults to 1. -1 waits until interrupted. **Returns:** true if the full wait completed, false if interrupted or invalid. **Example:** ```js await skills.wait(2); await skills.wait(-1); ``` --- ### `skills.flyTo(x, y, z, min_distance = 1)` Fly to the given position. Only works in creative mode. Plans a route through the air around blocks, so it can reach places goToPosition cannot walk to: high up, across gaps, over walls. It will NOT break blocks; a target sealed inside solid blocks is unreachable. If you arrive above solid ground you land and stop flying. Otherwise you stay hovering in the air until you fly again, walk (any walking skill lands you first), or call skills.stopFlying(). Refuses outside creative mode even when cheats are on. In creative mode with cheats, teleports instantly instead, then hovers or lands the same way. **Parameters:** - `x` — the x coordinate to fly to. - `y` — the y coordinate to fly to. - `z` — the z coordinate to fly to. - `min_distance` — how close to get to the position. Defaults to 1. Clamped to a minimum of 0.25. **Returns:** true if the position was reached, false otherwise. **Example:** ```js // Fly 20 blocks straight up to get a view of the area. let pos = world.getPosition(); await skills.flyTo(pos.x, pos.y + 20, pos.z); let top = world.getNearestBlock("beacon", 64).position; await skills.flyTo(top.x, top.y + 1, top.z); ``` --- ### `skills.stopFlying()` Stop flying and drop to the ground. Only meaningful in creative mode after skills.flyTo left you hovering in the air. You cannot get hurt by the fall in creative mode. **Returns:** true if you were flying and are now falling or standing, false if you were not flying. **Example:** ```js await skills.flyTo(100, 90, 100); await skills.stopFlying(); ``` --- ### `skills.jump(resolve_at = "apex")` In water, hold jump to swim upward for one second ("instant" returns as soon as you rise). Repeat to ascend through deep water. This does not require ground or wait for an apex or landing. On land, jump once. Resolves per `resolve_at`: - "instant" — right after takeoff (still rising). Fire-and-forget. - "apex" (default) — at the jump's peak. Use for mid-air actions like placing a block under the bot's feet. - "end" — after landing. **Parameters:** - `resolve_at` — "instant", "apex", or "end". Defaults to "apex". **Returns:** true if the jump succeeded, false otherwise. **Example:** ```js await skills.jump(); // at the apex await skills.jump("instant"); // fire-and-forget await skills.jump("end"); // wait until landed ``` --- ### `skills.sneak(toggle = true)` Toggle sneaking on or off. **Parameters:** - `toggle` — whether sneaking should be enabled. Defaults to true. **Returns:** true after updating the sneak state. **Example:** ```js await skills.sneak(true); await skills.sneak(false); ``` --- ### `skills.useItemOnBlock(itemName, x, y, z, face = "top")` Equip an inventory item in the main hand and right-click a block face. Walk into reach (4.5 blocks) first. Use the normal Minecraft action in all game modes. Use tools, plant items, apply bone meal, place blocks, or use buckets. Minecraft decides the result. A sent action does not confirm a state change. **Parameters:** - `itemName` — the item id or label to use. A minecraft: prefix is accepted. - `x` — the x coordinate of the block to click. - `y` — the y coordinate of the block to click. - `z` — the z coordinate of the block to click. - `face` — top, bottom, north, south, east, or west. Defaults to top. **Returns:** true when the action was sent. False when use was unavailable or interrupted. **Example:** ```js await skills.useItemOnBlock("iron_axe", 10, 64, 5, "top"); ``` --- ### `skills.useItemOnEntity(itemName, entity)` Equip an inventory item in the main hand and right-click an entity. Walk into reach (3 blocks) first. Use the normal Minecraft action in all game modes. Minecraft decides the result. A sent action does not confirm a state change. **Parameters:** - `itemName` — the item id or label to use. A minecraft: prefix is accepted. - `entity` — the target from a world entity query. **Returns:** true when the action was sent. False when use was unavailable or interrupted. **Example:** ```js let sheep = world.getNearestEntityWhere(e => e.name === "sheep", 16); await skills.useItemOnEntity("shears", sheep); ``` --- ### `skills.useHeldItem(itemName, x?, y?, z?)` Equip an item in the main hand and use it in the air, the right click with nothing targeted: throw a splash or lingering potion, an ender pearl, a snowball, an egg or a wind charge, or blow a goat horn. With a position, look at it first: a thrown item flies toward it, in an arc. A label from your observation picks that exact stack. To eat or drink, use skills.consume; to shoot, use skills.shootArrowAt. Minecraft decides the result. A sent action does not confirm what it did. **Parameters:** - `itemName` — the item id or label to use. - `x` — optional: the x coordinate to look at before the use. - `y` — optional: the y coordinate to look at. - `z` — optional: the z coordinate to look at. **Returns:** true when the use was sent. False when the item is missing or the action was interrupted. **Example:** ```js await skills.useHeldItem("ender_pearl", 20, 64, -5); await skills.useHeldItem("splash_potion[potion_contents={potion:healing}]"); ``` --- ### `skills.activateBlockAt(x, y, z)` Activate (right-click) the block at the given coordinates. Toggles doors, trapdoors, and fence gates open/closed, flips levers, presses buttons, and opens other interactable blocks. Walks into reach (4.5 blocks) first if needed. To pass through a door, activate it then walk through with skills.goToPosition. **Parameters:** - `x` — the x coordinate of the block to activate. - `y` — the y coordinate of the block to activate. - `z` — the z coordinate of the block to activate. **Returns:** true if the block was activated, false otherwise. **Example:** ```js let door = world.getNearestBlock("oak_door", 16); await skills.activateBlockAt(door.position.x, door.position.y, door.position.z); ``` --- ### `skills.activateNearestBlock(type)` Activate the nearest block of the given type (searched within 16 blocks); walks into reach first if needed. **Parameters:** - `type` — the type of block to activate. **Returns:** true if the block was activated, false otherwise. **Example:** ```js await skills.activateNearestBlock("lever"); ``` --- ### `skills.sendChatMessage(message)` Send a chat message or a command from the challenge. The challenge instructions describe its commands and arguments. Use slash command text with positional arguments. Quote argument values that contain spaces. The result confirms submission, not acceptance by the challenge. This skill is disabled when your response includes a value for "message", since that message is already sent as chat. Use either the "message" field or skills.sendChatMessage in code, not both. **Parameters:** - `message` — the message to send. **Returns:** true if the message was sent, false otherwise. **Example:** ```js await skills.sendChatMessage("Hello!"); ``` --- ### `skills.whisper(player_name, message)` Whisper a message to the given player. **Parameters:** - `player_name` — the name of the player to whisper to. - `message` — the message to send. **Returns:** true if the message was sent, false otherwise. **Example:** ```js await skills.whisper("player_name", "Hello!"); ``` --- ## World ### `world.getNearestFreeSpace(size = 1, distance = 8)` Get the nearest empty space with solid blocks beneath it of the given size. **Parameters:** - `size` — - The (size x size) of the space to find, default 1. - `distance` — - The maximum distance to search, default 8. **Returns:** - The south west corner position of the nearest free space. **Example:** ```js let position = world.getNearestFreeSpace(1, 8); ``` --- ### `world.getBlockAt(x, y, z)` Get the block at the given coordinates with its state: the properties that differ from the block's default (`powered`, `open`, `delay`, `power`, `lit`, `extended`, `age`...) and, for a sign, a lectern or a skull, the block entity data. A block at its default state has an empty state. **Parameters:** - `x` — - The x coordinate of the block. - `y` — - The y coordinate of the block. - `z` — - The z coordinate of the block. **Returns:** | null} - The block, or null when its chunk is not loaded. **Example:** ```js let lever = world.getBlockAt(10, 64, 5); if (lever && lever.state.powered) { skills.log("The lever is on"); } ``` --- ### `world.getNearestBlocks(blockTypes = null, distance = 16, count = 10000)` Get a list of the nearest blocks of the given types. **Parameters:** - `blockTypes` — - The names of the blocks to search for. - `distance` — - The maximum distance to search, default 16. - `count` — - The maximum number of blocks to find, default 10000. **Returns:** - The nearest blocks of the given type. **Example:** ```js let woodBlocks = world.getNearestBlocks(['oak_log', 'birch_log'], 16, 1); ``` --- ### `world.getNearestBlock(blockType, distance = 16)` Get the nearest block of the given type. **Parameters:** - `blockType` — - The name of the block to search for. - `distance` — - The maximum distance to search, default 16. **Returns:** - The nearest block of the given type. **Example:** ```js let coalBlock = world.getNearestBlock('coal_ore', 16); ``` --- ### `world.getNearestBlocksFiltering(blockTypes, filter, distance, count)` Get the nearest blocks matching given types and an optional filter predicate. Returns blocks sorted by distance (nearest first). More flexible than getNearestBlocks — use this when you need custom filtering logic. **Parameters:** - `blockTypes` — - Block type names to search for, or null for all non-air blocks. - `filter` — - Optional predicate to further filter blocks (e.g. by properties). - `distance` — - The maximum distance to search. - `count` — - The maximum number of blocks to return. **Returns:** - Array of matching blocks sorted by distance (nearest first). **Example:** ```js // Find the nearest open door within 16 blocks let openDoors = world.getNearestBlocksFiltering(["oak_door"], (b) => b.getProperties().open, 16, 1); ``` --- ### `world.getNearbyEntities(maxDistance = 16)` Get a list of all nearby entities (mobs, players, items, etc.) sorted by distance (nearest first). **Parameters:** - `maxDistance` — - The maximum distance to search, default 16. **Returns:** - A list of nearby entities sorted by distance. **Example:** ```js let entities = world.getNearbyEntities(32); for (let entity of entities) { skills.log(entity.name, entity.position); } ``` --- ### `world.getNearestEntityWhere(predicate, maxDistance = 16)` Get the nearest entity matching a custom predicate function. **Parameters:** - `predicate` — - A function that takes an Entity and returns true if it matches. - `maxDistance` — - The maximum distance to search, default 16. **Returns:** - The nearest matching entity, or null if none found. **Example:** ```js let cow = world.getNearestEntityWhere((e) => e.name === "cow", 32); let damaged = world.getNearestEntityWhere((e) => e.name === "zombie" && e.health < 10, 16); ``` --- ### `world.getEntityDisplayName(entity)` Get the display name for an entity, including item type for item entities. **Parameters:** - `entity` — - The entity to get the display name for. **Returns:** - The display name (e.g., "zombie", "item:diamond"). --- ### `world.matchesEntityType(entity, targetType)` Check if an entity matches the given type, handling item:type format. **Parameters:** - `entity` — - The entity to check. - `targetType` — - The type to match (e.g., "zombie", "item:diamond"). **Returns:** - True if the entity matches the type. --- ### `world.getNearbyPlayers(maxDistance = 16)` Get a list of all nearby player entities sorted by distance (nearest first). Each returned entity has a `.username` property with the player's name. Does not include the bot itself. **Parameters:** - `maxDistance` — - The maximum distance to search, default 16. **Returns:** - A list of nearby player entities, each with a .username property. **Example:** ```js let players = world.getNearbyPlayers(32); for (let p of players) { skills.log(p.username, p.position); } ``` --- ### `world.getInventoryStacks()` Get the bot's inventory as a list of raw Item objects. Unlike getInventoryCounts (which returns name→count), this returns full Item objects with properties like .name, .count, .durabilityUsed, .customName and .components (the item's components as `[{type, data}]`, e.g. `{type: "enchantments", data: {enchantments: [{id, level}]}}`). Use this when you need detailed item info beyond just counts. **Returns:** - A list of Item objects in the bot's inventory. **Example:** ```js let items = world.getInventoryStacks(); for (let item of items) { skills.log(item.name, item.count); } ``` --- ### `world.getEquippedArmor()` Get the bot's currently equipped armor pieces. **Returns:** - An object with keys head, chest, legs, feet. Each value is the item name (e.g. "iron_helmet") or null if nothing is equipped in that slot. **Example:** ```js let armor = world.getEquippedArmor(); if (!armor.chest) { skills.log("No chestplate equipped!"); } ``` --- ### `world.getInventoryCounts()` Get an object representing the bot's inventory. **Returns:** - An object with item names as keys and counts as values. **Example:** ```js let inventory = world.getInventoryCounts(); let oakLogCount = inventory['oak_log']; let hasWoodenPickaxe = inventory['wooden_pickaxe'] > 0; ``` --- ### `world.getInventoryCountForItem(item)` Get the number of items in the bot's inventory. **Parameters:** - `item` — - The name of the item to get the count for. **Returns:** - The number of items in the bot's inventory. **Example:** ```js let count = world.getInventoryCountForItem('oak_log'); ``` --- ### `world.getCraftableItems()` Get a list of all items that can be crafted with the bot's current inventory. **Returns:** - A list of all items that can be crafted. **Example:** ```js let craftableItems = world.getCraftableItems(); ``` --- ### `world.getPosition()` Get your position in the world (Note that y is vertical). **Returns:** - An object with x, y, and z attributes representing the position of the bot. **Example:** ```js let position = world.getPosition(); let x = position.x; ``` --- ### `world.getNearbyEntityTypes()` Get a list of all nearby mob types. **Returns:** - A list of all nearby mobs. **Example:** ```js let mobs = world.getNearbyEntityTypes(); ``` --- ### `world.getNearbyPlayerNames(maxDistance = 16)` Get a list of all nearby player names. **Parameters:** - `maxDistance` — - The maximum distance to search, default 16. **Returns:** - A list of all nearby players. **Example:** ```js let players = world.getNearbyPlayerNames(); ``` --- ### `world.getNearbyPlayerInfo(maxDistance = 16)` Get nearby players with their position data. **Parameters:** - `maxDistance` — - The maximum distance to search, default 16. **Returns:** - Map of player names to position info. --- ### `world.getNearbyEntityInfo(maxDistance = 16)` Get nearby non-player entities with their position data. **Parameters:** - `maxDistance` — - The maximum distance to search, default 16. **Returns:** - Nearby non-player entities with structured metadata. --- ### `world.getNearbyBlockTypes(distance = 16)` Get a list of all distinct nearby block names. **Parameters:** - `distance` — - The maximum distance to search, default 16. **Returns:** - A list of all nearby blocks. **Example:** ```js let blocks = world.getNearbyBlockTypes(); ``` --- ### `world.getVisibleBlocks(xRadius = 16, yRadius = 16, zRadius = 16)` Get a 3D matrix of block names in the area around the bot. Each cell contains the block name at that relative position (x, y, z). Radii are clamped to 16 (larger values scan 16); the returned matrix is always sized to the radius actually scanned. **Parameters:** - `xRadius` — - The x radius to scan, default 16, max 16. - `yRadius` — - The y radius to scan, default 16, max 16. - `zRadius` — - The z radius to scan, default 16, max 16. **Returns:** - A 3D matrix of block names indexed by [x][y][z]. **Example:** ```js let blocks = await world.getVisibleBlocks(16); ``` --- ### `world.scanNearbyBlocks(options = {})` Scan the area around the bot and return blocks in a layered, compressed relative format. By default the area is 15x15x7: x and z from -7 to 7, y from -3 to 3 (0 is the feet). Blocks are grouped by relative Y offset, then by type. Each position is either a [dx, dz] pair (single block) or a [x1, z1, x2, z2] rectangle (filled area). Skips air. This function returns the scan result but does not print it, so use console.log(...) on the returned value if you want it to appear in observation output. **Parameters:** - `options` — - Optional. `x`, `y`, `z`: the relative range on each axis as [min, max] from your position, each bound within ±16. `includeBlockStates`: group a block by its state (`lever[powered=true]`) instead of its name; default false. **Returns:** {[dy, {blockName: coords[]}][]} - Array of [dy, blocks] sorted by Y. **Example:** ```js let layers = world.scanNearbyBlocks(); console.log(layers); // layers: [[-1, {stone: [[-7,-7,7,7]]}], [0, {grass_block: [[0,0]]}], ...] // The redstone in front of you, with the states. let wiring = world.scanNearbyBlocks({ x: [-8, 8], y: [0, 6], z: [-8, 0], includeBlockStates: true }); // [[0, {"lever[powered=true]": [[2,-3]], redstone_wire: [[3,-3,6,-3]], "redstone_wire[power=15]": [[2,-4]]}], ...] ``` --- ### `world.isClearPath(target)` Check if there is a path to the target that requires no digging or placing blocks. **Parameters:** - `target` — - The target entity to path to. **Returns:** - True if there is a clear path, false otherwise. **Example:** ```js let enemy = world.getNearestEntityWhere((e) => e.name === "zombie", 32); if (enemy && (await world.isClearPath(enemy))) { await skills.attackEntity(enemy); } ``` --- ### `world.getBiomeName()` Get the name of the biome the bot is in. **Returns:** - The name of the biome. **Example:** ```js let biome = world.getBiomeName(); ``` --- ### `world.getStats()` Get a formatted summary of the bot's current stats, including position, gamemode, health, hunger, biome, weather, time of day, and nearby players. **Returns:** - A multi-line string with the bot's stats. **Example:** ```js let stats = world.getStats(); ``` --- ### `world.getInventory()` Get the inventory of the bot as a string. **Returns:** - The inventory of the bot. **Example:** ```js let inventory = world.getInventory(); ``` --- ## Cheats (cheatMode only) ### `cheats.command(command)` Send a whitelisted Minecraft command. Requires challenge cheats. Accepts commands with or without the leading slash. The whitelist excludes execute, function, server administration, and other unsupported commands. Follow your challenge role prompt for which commands to use. succeeded. False means it was blocked or interrupted. No server feedback is returned; verify the result in the world. Syntax and availability depend on the server version, so a whitelisted command may still be unsupported. **Parameters:** - `command` — - Minecraft command and arguments. **Returns:** True means the command was sent, not that it **Example:** ```js await cheats.command("/item replace entity @s armor.head with diamond_helmet"); ``` --- ### `cheats.summonMobType(mobType, num = 1)` Summon mobs of the given type. **Parameters:** - `mobType` — the type of mob to summon. - `num` — the number of mobs to summon. Defaults to 1. **Returns:** true if the mobs were summoned, false if the mob type was not found. **Example:** ```js await cheats.summonMobType("zombie", 10); ``` --- ### `cheats.fillBlocks(blockType, x, y, z, dx, dy, dz)` Fill the box from (x, y, z) to (x + dx, y + dy, z + dz), inclusive, with the given block type: (dx + 1) * (dy + 1) * (dz + 1) blocks in one /fill command, from any distance. Prefer this over a placeBlock loop for any solid region; a hollow room is a fill followed by a smaller fill of "air" inside it. One call handles up to 32768 blocks. **Parameters:** - `blockType` — the type of block to fill. - `x` — the x coordinate of the block to fill. - `y` — the y coordinate of the block to fill. - `z` — the z coordinate of the block to fill. - `dx` — the x distance to fill. - `dy` — the y distance to fill. - `dz` — the z distance to fill. **Returns:** true if the block was filled, false if the block type was not found. **Example:** ```js // A 5x3x5 stone platform starting at (10, 64, 10). await cheats.fillBlocks("stone", 10, 64, 10, 4, 2, 4); ``` ---