API reference

Episodes loop

[Source]

episodes-loop.getOnSpawnFn(bot, host, actRecorderPort, coordinator, args)

Get spawn phase handler function

Arguments:

  • bot – Mineflayer bot instance

  • host (string) – Server host

  • actRecorderPort (number) – Act recorder port

  • coordinator – Bot coordinator instance

  • args (Object) – Configuration arguments

Returns:

function – Spawn phase handler

episodes-loop.isEvalEpisode(episodeInstance)

Check if an episode instance is an eval episode

Arguments:

  • episodeInstance (Object) – Episode instance to check

Returns:

boolean – True if the episode is an eval episode

episodes-loop.saveEpisodeInfo(params)

Persist per-episode metadata to disk (one JSON file per episode).

Arguments:

  • params (Object) – Parameters bag.

  • params.args (Object) – CLI/config args. Must include output_dir and bot_name.

  • params.bot – Mineflayer bot instance.

  • params.episodeInstance – Episode instance (used for error/eval flags).

  • params.episodeNum (number) – Episode number.

  • params.episodeType (string) – Episode type key.

Returns:

Promise.<void> – Resolves once the file is written.

episodes-loop.runSingleEpisode(bot, rcon, sharedBotRng, coordinator, episodeNum, episodeInstance, args)

Run a single episode

Arguments:

  • bot – Mineflayer bot instance

  • rcon – RCON connection instance

  • sharedBotRng (function) – Shared random number generator

  • coordinator – Bot coordinator instance

  • episodeNum (number) – Episode number

  • episodeInstance – Episode instance for this run

  • args (Object) – Configuration arguments

Returns:

Promise.<function()> – Resolves with a cleanup function for episode-scoped handlers.

episodes-loop.notifyPeerErrorAndStop(bot, rcon, sharedBotRng, coordinator, episodeNum, episodeInstance, args, error)

Notify the peer bot of an episode error and initiate the stop phase locally.

Arguments:

  • bot – Mineflayer bot instance.

  • rcon – RCON connection instance.

  • sharedBotRng (function) – Shared RNG instance.

  • coordinator – Bot coordinator instance.

  • episodeNum (number) – Episode number.

  • episodeInstance – Episode instance.

  • args (Object) – Configuration args.

  • error (unknown) – Error value.

Returns:

Promise.<void> – Resolves when peer is notified and stop is scheduled.

episodes-loop.setupBotAndWorldOnce(bot, rcon)

Setup bot protection effects and world rules (called once per bot)

Arguments:

  • bot – Mineflayer bot instance

  • rcon – RCON connection instance

episodes-loop.setupCameraPlayerOnce(bot, rcon)

Setup camera player protection effects (called once per camera)

Arguments:

  • bot – Mineflayer bot instance (used to derive camera username)

  • rcon – RCON connection instance

episodes-loop.setupBotAndCameraForEpisode(bot, rcon, args)

Setup bot and camera saturation effects for each episode

Arguments:

  • bot – Mineflayer bot instance

  • rcon – RCON connection instance

  • args (Object) – Configuration arguments

episodes-loop.clearBotInventory(bot, rcon)

Clear all items from the bot’s inventory.

Arguments:

  • bot – Mineflayer bot instance.

  • rcon – RCON connection instance.

Returns:

Promise.<void> – Resolves when the /clear command completes.

episodes-loop.getOnTeleportPhaseFn(bot, rcon, sharedBotRng, coordinator, episodeNum, episodeInstance, args, phaseDataOur)

Get teleport phase handler function

Arguments:

  • bot – Mineflayer bot instance

  • rcon – RCON connection instance

  • sharedBotRng (function) – Shared random number generator

  • coordinator – Bot coordinator instance

  • episodeNum (number) – Episode number

  • episodeInstance – Episode instance

  • args (Object) – Configuration arguments

  • phaseDataOur (Object) – Our phase data payload

Returns:

function – Teleport phase handler

episodes-loop.getOnPostTeleportPhaseFn(bot, rcon, sharedBotRng, coordinator, episodeNum, episodeInstance, args)

Get post-teleport phase handler.

Arguments:

  • bot – Mineflayer bot instance

  • rcon – RCON connection instance

  • sharedBotRng (function) – Shared RNG

  • coordinator – Bot coordinator

  • episodeNum (number) – Episode number

  • episodeInstance – Episode instance

  • args (Object) – Configuration args

Returns:

function – Post-teleport phase handler

episodes-loop.getOnSetupEpisodeFn(bot, rcon, sharedBotRng, coordinator, episodeNum, episodeInstance, args, phaseDataOur)

Get setup-episode phase handler.

Arguments:

  • bot – Mineflayer bot instance

  • rcon – RCON connection instance

  • sharedBotRng (function) – Shared RNG

  • coordinator – Bot coordinator

  • episodeNum (number) – Episode number

  • episodeInstance – Episode instance

  • args (Object) – Configuration args

  • phaseDataOur (Object) – Our phase payload (expects position)

Returns:

function – Setup-episode phase handler

episodes-loop.getOnStartRecordingFn(bot, rcon, sharedBotRng, coordinator, episodeNum, episodeInstance, args)

Get start-recording phase handler.

Arguments:

  • bot – Mineflayer bot instance

  • rcon – RCON connection instance

  • sharedBotRng (function) – Shared RNG

  • coordinator – Bot coordinator

  • episodeNum (number) – Episode number

  • episodeInstance – Episode instance

  • args (Object) – Configuration args

Returns:

function – Start-recording phase handler

episodes-loop.teleport(bot, rcon, args, ourPosition, otherBotPosition, episodeInstance, sharedBotRng, episodeNum)

Teleport both bots to a randomized location (or episode-specific fixed points).

Uses spreadplayers to place both bots within the configured distance bounds. For some eval episodes, applies special-case teleporting.

Arguments:

  • bot – Mineflayer bot instance.

  • rcon – RCON connection instance.

  • args (Object) – Configuration args.

  • ourPosition – Our current position (vec3-like).

  • otherBotPosition – Peer current position (vec3-like).

  • episodeInstance – Episode instance (used for min/max distances and eval detection).

  • sharedBotRng (function) – Shared RNG (currently unused; reserved for future determinism).

  • episodeNum (number) – Episode number (for logging/commands).

Returns:

Promise.<void> – Resolves when teleport attempt finishes.

episodes-loop.getOnPeerErrorPhaseFn(bot, rcon, sharedBotRng, coordinator, episodeNum, episodeInstance, args)

Get peer-error phase handler for a specific episode.

When the peer reports an error, mark _peerError and schedule the stop phase.

Arguments:

  • bot – Mineflayer bot instance

  • rcon – RCON connection instance

  • sharedBotRng (function) – Shared RNG

  • coordinator – Bot coordinator

  • episodeNum (number) – Episode number

  • episodeInstance – Episode instance

  • args (Object) – Configuration args

Returns:

function – Peer-error phase handler

Episode classes

[Source]

All episode handlers extend episode-handlers/base-episode.BaseEpisode and implement episode-handlers/base-episode.BaseEpisode.entryPoint() (and optionally episode-handlers/base-episode.BaseEpisode.setupEpisode() and episode-handlers/base-episode.BaseEpisode.tearDownEpisode()).

Base

class episode-handlers.base-episode.BaseEpisode(sharedBotRng)

Base episode lifecycle: setupEpisode, entryPoint, tearDownEpisode, and stop-phase coordination. Subclasses override entryPoint (required), and optionally setupEpisode and tearDownEpisode.

episode-handlers.base-episode.BaseEpisode.entryPoint(bot, rcon, sharedBotRng, coordinator, iterationID, episodeNum, args)

Main episode logic. Must be implemented by subclasses.

Returns:

Promise.<any>

episode-handlers.base-episode.BaseEpisode.getOnStopPhaseFn(bot, sharedBotRng, coordinator, otherBotName)

Creates the onStopPhase handler function.

Arguments:

  • bot (Object) – The bot instance

  • sharedBotRng (Object) – Shared random number generator

  • coordinator (Object) – Coordinator for bot communication

  • otherBotName (string) – Name of the other bot

Returns:

function – Async function that handles the stop phase

episode-handlers.base-episode.BaseEpisode.getOnStoppedPhaseFn(bot, sharedBotRng, coordinator, otherBotName, episodeNum, episodeResolve)

Creates the onStoppedPhase handler function.

Arguments:

  • bot (Object) – The bot instance

  • sharedBotRng (Object) – Shared random number generator

  • coordinator (Object) – Coordinator for bot communication

  • otherBotName (string) – Name of the other bot

  • episodeNum (number) – Episode number

  • episodeResolve (function) – Function to resolve the episode promise

Returns:

function – Async function that handles the stopped phase

episode-handlers.base-episode.BaseEpisode.setupEpisode(bot, rcon, sharedBotRng, coordinator, episodeNum, args, botPosition, otherBotPosition)

Optional setup hook. No-op by default.

Returns:

Promise.<{botPositionNew: Vec3, otherBotPositionNew: Vec3}>

episode-handlers.base-episode.BaseEpisode.tearDownEpisode(bot, rcon, sharedBotRng, coordinator, episodeNum, args)

Optional teardown hook. No-op by default.

Returns:

Promise.<void>

Training episodes

class episode-handlers.build-house-episode.BuildHouseEpisode(sharedBotRng)

Episode for collaborative 5x5 house building. Both bots coordinate to build a shared house at the midpoint between them, splitting work by X-axis.

class episode-handlers.build-structure-episode.BuildStructureEpisode(sharedBotRng)

Episode for collaborative structure building (wall, tower, or platform). Structure type is chosen per episode via shared RNG; wall/tower are built individually, platform is split by X-axis.

class episode-handlers.build-tower-episode.BuildTowerEpisode()

Episode for individual tower building. Each bot builds a tower of random height (8–12 blocks) at their spawn position, with initial and final eye contact.

class episode-handlers.chase-episode.ChaseEpisode()

Episode where one bot chases the other using pathfinder; roles (chaser/runner) are decided by shared RNG. Chase duration is random within a range.

class episode-handlers.collector-episode.CollectorEpisode()

Episode where both bots perform mining cycles (leader-follower or independent). Leader-follower mode has one bot mine while the other follows and places torches; mode and roles use shared RNG.

class episode-handlers.mine-episode.MineEpisode()

Episode where both bots dig down, then mine toward a shared midpoint using pathfinder with torch placement. Uses diamond pickaxe and pathfinder-based navigation.

class episode-handlers.orbit-episode.OrbitEpisode()

Episode where both bots orbit around their shared midpoint, visiting checkpoints and making eye contact at each. Orbit radius is half the distance between bots.

class episode-handlers.place-and-mine-episode.PlaceAndMineEpisode()

Episode where one bot (builder) places blocks in patterns and the other (miner) watches then mines them. Roles and build location are chosen in setup; rounds repeat for a random number of times.

class episode-handlers.pve-episode.PveEpisode()

Episode where both bots fight hostile mobs (spawned via RCON). Each bot guards a position, engages nearby hostiles with mineflayer-pvp, then returns and looks at the other bot.

class episode-handlers.pvp-episode.PvpEpisode()

Episode for player-vs-player combat. Both bots equip a random sword, make eye contact, then fight for a random duration using the mineflayer-pvp plugin.

class episode-handlers.straight-line-episode.StraightLineEpisode()

Episode where one bot walks in a straight line past the other (or both stay); who walks is determined by shared RNG (lower/bigger name). The walker pathfinds past the other bot.

class episode-handlers.tower-bridge-episode.TowerBridgeEpisode()

Episode where both bots build a tower, then bridge toward the midpoint between them. Sneak is used on the tower to avoid falling; bridge target is on a shared cardinal axis.

class episode-handlers.walk-look-episode.WalkLookEpisode()

Episode with multiple iterations: bots look at each other, then either both walk, or only the lower/bigger name bot walks (mode chosen by shared RNG). Uses random-movement run().

class episode-handlers.walk-look-away-episode.WalkLookAwayEpisode()

Episode similar to WalkLook but with look-away: one bot (lower or bigger name, by shared RNG) walks while looking away; the other stays. Single run action per iteration.

Eval episodes

class episode-handlers.eval.both-look-away-eval-episode.BothLookAwayEvalEpisode()

Eval episode where both bots look away after initial eye contact (same random direction/offset); used to evaluate joint look-away behavior.

class episode-handlers.eval.one-looks-away-eval-episode.OneLooksAwayEvalEpisode()

Eval episode where one bot (lower or bigger name, by episode number) looks away by a random offset after initial eye contact; used to evaluate look-away behavior.

class episode-handlers.eval.rotation-eval-episode.RotationEvalEpisode()

Eval episode for rotation: one bot (alpha or bravo, by episode number) rotates yaw by a fixed angle (+40°, -40°, or 180°) while the other stays; used to evaluate camera rotation.

class episode-handlers.eval.structure-eval-episode.StructureEvalEpisode(sharedBotRng)

Eval episode for independent structure building: each bot builds a small structure (wall_2x2, wall_4x1, or tower_2x1) at a fixed distance, with eye contact and admire phases for evaluation.

class episode-handlers.eval.translation-eval-episode.TranslationEvalEpisode()

Eval episode for translation: one bot (by episode number) aligns to the other along one axis, then walks using run(); used to evaluate movement/translation.

class episode-handlers.eval.turn-to-look-eval-episode.TurnToLookEvalEpisode()

Eval episode: bots look at each other, then one (by name order) faces sideways; used to evaluate turning to look at the other bot.

class episode-handlers.eval.turn-to-look-opposite-eval-episode.TurnToLookOppositeEvalEpisode()

Eval episode: same as TurnToLook but both bots rotate the same direction so they end up facing opposite directions; used to evaluate turn-to-look in opposite configuration.

Primitives

[Source]

Building

primitives.building.makeHouseBlueprint5x5(options)

Generate a 5x5 house blueprint with flat roof Local coordinate frame: origin at south-west corner, +X=east, +Z=south, +Y=up

Arguments:

  • options (Object) – Configuration options

  • options.materials (Object) – Material overrides

Returns:

Array.<Object> – Array of {x, y, z, block, phase, placementOrder, data}

primitives.building.rotateLocalToWorld(local, origin, orientation)

Rotate local coordinates to world coordinates

Arguments:

  • local (Object) – Local position {x, y, z}

  • origin (Vec3) – World origin position

  • orientation (number) – Rotation in degrees (0, 90, 180, 270)

Returns:

Vec3 – World position

primitives.building.splitWorkByXAxis(targets, alphaBotName, bravoBotName)

Split work between two bots by X-axis Alpha builds west half + center (x ≤ 2), Bravo builds east half (x ≥ 3)

Arguments:

  • targets (Array.<Object>) – Array of block targets

  • alphaBotName (string) – Name of alpha bot

  • bravoBotName (string) – Name of bravo bot

Returns:

Object – {alphaTargets, bravoTargets}

primitives.building.calculateMaterialCounts(blueprint)

Calculate material counts from blueprint

Arguments:

  • blueprint (Array.<Object>) – Blueprint array

Returns:

Object – Material counts {blockName: count}

primitives.building.buildPhase(bot, targets, options)

Build a phase of blocks for one bot with auto-scaffolding

Arguments:

  • bot – Mineflayer bot instance

  • targets (Array.<Object>) – Array of block targets with worldPos

  • options (Object) – Options {args, delayMs}

Returns:

Promise.<Object> – Build statistics {success, failed}

primitives.building.buildBridge(bot, targetPos, bridgeBlockType, bridgeGoalDistance, bridgeTimeoutMs, args)

Build a bridge towards a target position using pathfinder with automatic scaffolding This leverages mineflayer-pathfinder’s built-in block placement capabilities

Arguments:

  • bot – Mineflayer bot instance

  • targetPos (Vec3) – Target position to build towards

  • bridgeBlockType (string) – Block type to use for bridge

  • bridgeGoalDistance (number) – Goal distance to target

  • bridgeTimeoutMs (number) – Timeout in milliseconds

  • args (Object) – Configuration arguments

Returns:

Promise.<Object> – Build statistics

primitives.building.cleanupScaffolds(bot)

Cleanup scaffold blocks after building

Arguments:

  • bot – Mineflayer bot instance

Returns:

Promise.<void>

primitives.building.admireHouse(bot, doorWorldPos, orientation, options)

Both bots exit through door and admire the house

Arguments:

  • bot – Mineflayer bot instance

  • doorWorldPos (Vec3) – World position of door

  • orientation (number) – House orientation (0, 90, 180, 270)

  • options (Object) – Options {backOff: distance}

Returns:

Promise.<void>

primitives.building.calculateFloorPlacementOrder(width=5, depth=5)

Calculate placement order for floor blocks (edge-to-center spiral) Strategy: Place perimeter first, then work inward layer by layer This ensures bots never stand on unplaced blocks

Arguments:

  • width (number) – Width of floor (default 5)

  • depth (number) – Depth of floor (default 5)

Returns:

Array.<{x: number, z: number, order: number}> – Ordered positions

primitives.building.getPerimeterPosition(x, z)

Helper: Get perimeter position for clockwise ordering

Arguments:

  • x (number) – X coordinate

  • z (number) – Z coordinate

Returns:

number – Position along perimeter

primitives.building.calculateWallPlacementOrder(wallBlocks)

Calculate placement order for wall blocks Strategy: Bottom-up, corners first, then edges

Arguments:

  • wallBlocks (Array.<{x: number, y: number, z: number}>) – Wall block positions

Returns:

Map.<string, number> – Map of “x,y,z” -> order

primitives.building.calculateRoofPlacementOrder(width=5, depth=5)

Calculate placement order for roof blocks Strategy: Similar to floor (edge-to-center) but bots are below

Arguments:

  • width (number) – Width of roof (default 5)

  • depth (number) – Depth of roof (default 5)

Returns:

Array.<{x: number, z: number, order: number}> – Ordered positions

primitives.building.isBotCollidingWithBlock(bot, targetPos)

Check if bot’s hitbox overlaps with target block position Bot hitbox: 0.6 wide × 1.8 tall, centered at bot position

Arguments:

  • bot – Mineflayer bot instance

  • targetPos (Vec3) – Target block position

Returns:

boolean – True if bot is standing on/inside target block

primitives.building.placeAt(bot, targetPos, itemName, options)

Robust place at exact target (x,y,z) with itemName Auto-finds a reference face, ensures reach/LOS, sneaks if needed, retries Enhanced with pre-placement ritual for human-like behavior Phase 7: Added fallback mechanisms, validation, and graceful error handling

Arguments:

  • bot – Mineflayer bot instance

  • targetPos (Vec3) – Target position to place block

  • itemName (string) – Name of block/item to place

  • options (Object) – Options for placement {useSneak, tries, args, prePlacementDelay, maxRetries}

Returns:

Promise.<boolean> – True if successfully placed

primitives.building.placeMultiple(bot, positions, itemName, options)

Place multiple blocks in a deterministic order (bottom-up, near-to-far)

Arguments:

  • bot – Mineflayer bot instance

  • positions (Array.<Vec3>) – Array of positions to place blocks

  • itemName (string) – Name of block/item to place

  • options (Object) – Options for placement {useSneak, tries, args, delayMs, useBuildOrder, useSmartPositioning}

Returns:

Promise.<Object> – {success: number, failed: number, skipped: number}

primitives.building.isAirLike(block)

Check if a block is air or air-like (passable)

Arguments:

  • block – Block to check

Returns:

boolean – True if air-like

primitives.building.inReach(bot, pos, max=4.5)

Check if a position is within reach

Arguments:

  • bot – Mineflayer bot instance

  • pos (Vec3) – Position to check

  • max (number) – Maximum reach distance

Returns:

boolean – True if in reach

primitives.building.findPlaceReference(bot, targetPos)

Find a reference block + face vector to place at targetPos DEPRECATED: Use findBestPlaceReference() instead Kept for backward compatibility

Arguments:

  • bot – Mineflayer bot instance

  • targetPos (Vec3) – Target position to place block

Returns:

Object|null – {refBlock, faceVec} or null if no valid reference

primitives.building.ensureReachAndSight(bot, refBlock, faceVec, maxTries=3)

Move close enough to place if needed

Arguments:

  • bot – Mineflayer bot instance

  • refBlock – Reference block to click

  • faceVec (Vec3) – Face vector

  • maxTries (number) – Maximum attempts

Returns:

Promise.<boolean> – True if in reach

primitives.building.fastPlaceBlock(bot, referenceBlock)

Fast block placement - no checks, just place immediately Used during pillar jumping where we know the context

Arguments:

  • bot – Mineflayer bot instance

  • referenceBlock – Block to place on top of

Returns:

Promise.<boolean> – True if placement was attempted

primitives.building.buildTowerUnderneath(bot, towerHeight, args, options)

Build a tower by jumping and placing blocks directly underneath Uses the classic Minecraft “pillar jumping” technique with configurable retry logic

Arguments:

  • bot – Mineflayer bot instance

  • towerHeight (number) – Height of tower to build

  • args (Object) – Configuration arguments (for RCON if needed)

  • options (Object) – Optional configuration

  • options.blockType (string) – Type of block to place (default: ‘oak_planks’)

  • options.enableRetry (boolean) – Enable retry logic for failed placements (default: true)

  • options.breakOnFailure (boolean) – Break immediately on failure (default: false)

  • options.maxPlaceAttempts (number) – Max attempts to place each block (default: 10)

  • options.settleDelayMs (number) – Delay to settle after placing (default: 200)

  • options.jumpDurationMs (number) – How long to hold jump (default: 50)

  • options.placeRetryDelayMs (number) – Delay between place attempts (default: 20)

Returns:

Promise.<Object> – Build statistics {success, failed, heightGained}

primitives.building.scoreFace(bot, faceVec, refBlockPos)

Calculate a score for how good a face is for placement Considers bot’s view direction, face orientation, and accessibility

Arguments:

  • bot – Mineflayer bot instance

  • faceVec (Vec3) – Face vector (normal direction)

  • refBlockPos (Vec3) – Position of reference block

Returns:

number – Score from 0-100 (higher is better)

primitives.building.findBestPlaceReference(bot, targetPos, options)

Find the best reference block and face for placing at targetPos Enhanced version with visibility checks and scoring Returns all viable candidates for fallback support

Arguments:

  • bot – Mineflayer bot instance

  • targetPos (Vec3) – Target position to place block

  • options (Object) – Options {returnAll: boolean, minScore: number}

Returns:

Object|Array|null – Best candidate, all candidates array, or null

primitives.building.raycastToPosition(bot, fromPos, toPos)

Perform a raycast from one position to another to check for obstructions Steps through the ray in small increments and checks for solid blocks

Arguments:

  • bot – Mineflayer bot instance

  • fromPos (Vec3) – Starting position (usually bot’s eye position)

  • toPos (Vec3) – Target position (usually face center)

Returns:

Object – {clear: boolean, obstruction: Vec3|null}

primitives.building.isBlockObstructed(bot, targetPos)

Check if a target position is completely obstructed (all faces blocked) Used to detect if a block is enclosed and cannot be placed

Arguments:

  • bot – Mineflayer bot instance

  • targetPos (Vec3) – Position to check

Returns:

boolean – True if all 6 faces are blocked by solid blocks

primitives.building.canSeeFace(bot, refBlock, faceVec)

Check if the bot can see a specific face of a reference block Performs detailed line-of-sight validation using raycast

Arguments:

  • bot – Mineflayer bot instance

  • refBlock – Reference block to check

  • faceVec (Vec3) – Face vector (normal direction of the face)

Returns:

boolean – True if bot has clear line of sight to the face

primitives.building.isPositionSafe(bot, position, targetPos)

Check if a position is safe for the bot to stand Validates ground support, no obstructions, and reasonable distance

Arguments:

  • bot – Mineflayer bot instance

  • position (Vec3) – Position to check

  • targetPos (Vec3) – Target block position (for distance check)

Returns:

boolean – True if position is safe

primitives.building.calculateOptimalPosition(bot, refBlock, faceVec, targetPos)

Calculate the optimal position for the bot to stand when placing a block Considers face direction, distance, and viewing angle

Arguments:

  • bot – Mineflayer bot instance

  • refBlock – Reference block to place on

  • faceVec (Vec3) – Face vector

  • targetPos (Vec3) – Target position where block will be placed

Returns:

Object – {position: Vec3, yaw: number, pitch: number}

primitives.building.moveToPlacementPosition(bot, refBlock, faceVec, targetPos, timeoutMs=5000)

Move the bot to an optimal position for placing a block Uses pathfinder to navigate and validates line of sight after movement

Arguments:

  • bot – Mineflayer bot instance

  • refBlock – Reference block to place on

  • faceVec (Vec3) – Face vector

  • targetPos (Vec3) – Target position where block will be placed

  • timeoutMs (number) – Timeout for pathfinding (default: 5000ms)

Returns:

Promise.<Object> – {success: boolean, position: Vec3, reason: string}

primitives.building.hasAdjacentSupport(bot, targetPos, placedBlocks)

Check if a target position has adjacent support for placement A block can only be placed if at least one adjacent block exists

Arguments:

  • bot – Mineflayer bot instance

  • targetPos (Vec3) – Position to check for support

  • placedBlocks (Set.<string>) – Set of already placed block positions (as “x,y,z” strings)

Returns:

boolean – True if position has at least one adjacent solid block

primitives.building.sortByBuildability(positions, bot)

Sort block positions by buildability Ensures blocks are placed in a valid order with proper support

Arguments:

  • positions (Array.<Vec3>) – Array of positions to sort

  • bot – Mineflayer bot instance

Returns:

Array.<Vec3> – Sorted array of positions (buildable order)

primitives.building.prepareForPlacement(bot, refBlock, faceVec, delayMs=500)

Prepare the bot for block placement with natural-looking behavior Looks at the target face, validates reach and sight line

Arguments:

  • bot – Mineflayer bot instance

  • refBlock – Reference block to place on

  • faceVec (Vec3) – Face vector

  • delayMs (number) – Delay after looking (default: 250ms)

Returns:

Promise.<Object> – {ready: boolean, reason: string}

primitives.building.buildStructure(bot, positions, blockType, args)

Main building loop - bot builds assigned structure

Arguments:

  • bot – Mineflayer bot instance

  • positions (Array.<Vec3>) – Positions to build at

  • blockType (string) – Type of block to place

  • args (Object) – Configuration arguments

Returns:

Promise.<Object> – Build statistics

primitives.building.getBlockPlaceDelayTicks(blockCount)

Compute an appropriate tick delay between block placements for a structure size.

Arguments:

  • blockCount (number) – Number of blocks in the structure being placed

Returns:

number – Delay in ticks between placements

Digging

primitives.digging.digWithTimeout(bot, block, options)

Dig a block with a timeout, similar to gotoWithTimeout.

Arguments:

  • bot – Mineflayer bot instance

  • block (Object) – Block to dig

  • options (Object)

  • options.timeoutMs (number) – Maximum time to attempt digging

  • options.stopOnTimeout (boolean) – Stop digging when timeout triggers

Returns:

Promise.<void> – Resolves when dig completes; rejects on timeout/error

primitives.digging.digBlock(bot, blockPos)

Dig a block at a world position, if present.

Arguments:

  • bot – Mineflayer bot instance

  • blockPos (Vec3) – Block position to dig

Returns:

Promise.<boolean> – True if the block was air/dug successfully; false on error

primitives.digging.placeTorchOnFloor(bot, movementDirection=null)

Place a torch on the floor at the bot’s current feet position

Arguments:

  • bot – Mineflayer bot instance

  • movementDirection (Vec3) – Direction the bot is moving (not used)

Returns:

Promise.<boolean> – True if torch was placed

primitives.digging.placeTorch(bot, mcData, oreIds, maxTryTime=6000, stopRetryCondition)

Place a torch on a nearby surface

Arguments:

  • bot – Mineflayer bot instance

  • mcData (Object) – Minecraft data

  • oreIds (Array) – Array of ore block IDs to avoid

  • maxTryTime (number) – Maximum time to try placing torch (default 6 seconds)

  • stopRetryCondition (function) – Function to check if torch placement should stop (default false)

primitives.digging.findVisibleOres(bot, oreIds)

Find visible valuable ores

Arguments:

  • bot – Mineflayer bot instance

  • oreIds (Array) – Array of ore block IDs

Returns:

Array – Array of visible ore blocks

primitives.digging.isBlockVisible(bot, block)

Check if a block is visible to the bot

Arguments:

  • bot – Mineflayer bot instance

  • block – Block to check

Returns:

boolean – Whether the block is visible

Fighting

primitives.fighting.giveRandomSword(bot, rcon)

Give the bot a randomly selected sword via RCON.

Arguments:

  • bot – Mineflayer bot instance

  • rcon – RCON connection instance (must support send())

Returns:

Promise.<void>

primitives.fighting.equipSword(bot)

Equip the first sword found in the bot’s inventory.

Arguments:

  • bot – Mineflayer bot instance

Returns:

Promise.<void>

primitives.fighting.isInForwardFOV(bot, targetPos, fovDegrees)

Check if a position is within the bot’s forward-facing FOV cone.

Arguments:

  • bot (any) – The bot instance

  • targetPos (any) – The target position (Vec3)

  • fovDegrees (number) – Field of view in degrees (default 90)

Returns:

boolean – True if the target is in the bot’s FOV

Items

primitives.items.unequipHand(bot, itemType="null")

Unequips an item from the bot’s hand

Arguments:

  • bot – Mineflayer bot instance

  • itemType (string) – Optional item type to check for (e.g., “sword”, “pickaxe”)

Returns:

Promise.<boolean> – True if successfully unequipped or nothing to unequip

primitives.items.ensureBotHasEnough(bot, rcon, itemName="stone", targetCount=128)

Ensure the bot has at least targetCount of the given item in inventory

Arguments:

  • bot – Mineflayer bot instance

  • rcon – RCON connection instance

  • itemName (string) – Minecraft item name (e.g., ‘stone’)

  • targetCount (number) – Desired count in inventory

primitives.items.ensureItemInHand(bot, itemName, args=null)

Ensure an item is equipped in hand

Arguments:

  • bot – Mineflayer bot instance

  • itemName (string) – Name of item to equip

  • args (Object) – Configuration arguments with rcon settings (optional)

Returns:

Promise.<number> – Item ID

Movement

primitives.movement.stopAll(bot)

Stop all bot movement and actions

Arguments:

  • bot – Mineflayer bot instance

primitives.movement.setControls(bot, controls)

Set multiple movement controls at once

Arguments:

  • bot – Mineflayer bot instance

  • controls (Object) – Object with control states {forward: true, sprint: true, etc.}

primitives.movement.enableSprint(bot)

Enable sprint mode

Arguments:

  • bot – Mineflayer bot instance

primitives.movement.disableSprint(bot)

Disable sprint mode

Arguments:

  • bot – Mineflayer bot instance

primitives.movement.initializePathfinder(bot, options)

Initialize pathfinder with optimal settings for bot movement

Arguments:

  • bot – Mineflayer bot instance

  • options (Object) – Pathfinder configuration options

primitives.movement.stopPathfinder(bot)

Stop pathfinder and clear current goal

Arguments:

  • bot – Mineflayer bot instance

primitives.movement.gotoWithTimeout(bot, goal, options)

Go to a goal using pathfinder with a timeout.

Arguments:

  • bot – Mineflayer bot instance

  • goal (Object) – mineflayer-pathfinder Goal instance

  • options (Object)

  • options.timeoutMs (number) – Maximum time to attempt navigation

  • options.stopOnTimeout (boolean) – Stop pathfinder when timeout triggers

Returns:

Promise.<void> – Resolves when reached; rejects on timeout/error

primitives.movement.moveDirection(bot, direction, sprint=false)

Move in a specific direction

Arguments:

  • bot – Mineflayer bot instance

  • direction (string) – Direction to move (“forward”, “back”, “left”, “right”)

  • sprint (boolean) – Whether to sprint while moving

primitives.movement.moveToward(bot, targetPosition, sprint=false, threshold=0.5)

Move toward a target position using directional controls

Arguments:

  • bot – Mineflayer bot instance

  • targetPosition (Vec3) – Target position to move toward

  • sprint (boolean) – Whether to sprint while moving

  • threshold (number) – Distance threshold to consider “reached” (default: 0.5)

Returns:

string – The primary direction being moved

primitives.movement.moveAway(bot, avoidPosition, sprint=false)

Move away from a position (opposite direction)

Arguments:

  • bot – Mineflayer bot instance

  • avoidPosition (Vec3) – Position to move away from

  • sprint (boolean) – Whether to sprint while moving

Returns:

string – The primary direction being moved

primitives.movement.lookAtSmooth(bot, targetPosition, degreesPerSecond=90, options)

Smoothly rotate bot camera to look at target position

Arguments:

  • bot – Mineflayer bot instance

  • targetPosition (Vec3) – Position to look at

  • degreesPerSecond (number) – Rotation speed in degrees per second

  • options (Object) – Look options (see lookSmooth for details)

primitives.movement.lookSmooth(bot, targetYaw, targetPitch, degreesPerSecond, options)

Smoothly rotate bot camera to specified yaw and pitch

Arguments:

  • bot – Mineflayer bot instance

  • targetYaw (number) – Target yaw angle in radians

  • targetPitch (number) – Target pitch angle in radians

  • degreesPerSecond (number) – Base rotation speed in degrees per second

  • options (Object) – Look options

  • options.useEasing (boolean) – Whether to use easing for the rotation

  • options.randomized (boolean) – Whether to use log-normal speed randomization

  • options.volatility (number) – Sigma parameter for log-normal speed randomization To view how log-normal scaling works, see: https://www.desmos.com/calculator/wazayi56xf

primitives.movement.lookAtBot(bot, targetBotName, degreesPerSecond=90, options)

Look at another bot by name

Arguments:

  • bot – Mineflayer bot instance

  • targetBotName (string) – Name of the bot to look at

  • degreesPerSecond (number) – Rotation speed in degrees per second

  • options (Object) – Look options (see lookSmooth for details)

primitives.movement.lookDirection(bot, yawRadians, pitchRadians=0)

Look in a specific direction (yaw only)

Arguments:

  • bot – Mineflayer bot instance

  • yawRadians (number) – Yaw angle in radians

  • pitchRadians (number) – Pitch angle in radians (default: 0)

primitives.movement.sleep(ms)

Sleep for a specified duration

Arguments:

  • ms (number) – Milliseconds to sleep

Returns:

Promise – Promise that resolves after the specified time

primitives.movement.distanceTo(pos1, pos2)

Calculate distance between two positions

Arguments:

  • pos1 (Vec3) – First position

  • pos2 (Vec3) – Second position

Returns:

number – Distance between positions

primitives.movement.horizontalDistanceTo(pos1, pos2)

Calculate 2D horizontal distance between two positions (ignoring Y)

Arguments:

  • pos1 (Vec3) – First position

  • pos2 (Vec3) – Second position

Returns:

number – Horizontal distance between positions

primitives.movement.getDirectionTo(fromPos, toPos)

Get the direction vector from one position to another

Arguments:

  • fromPos (Vec3) – Starting position

  • toPos (Vec3) – Target position

Returns:

Object – Normalized direction vector {x, z, distance}

primitives.movement.isNearPosition(bot, targetPosition, threshold=1)

Check if bot is close to a target position

Arguments:

  • bot – Mineflayer bot instance

  • targetPosition (Vec3) – Target position to check

  • threshold (number) – Distance threshold (default: 1.0)

Returns:

boolean – True if bot is within threshold distance

primitives.movement.isNearBot(bot, targetBotName, threshold=1)

Check if bot is close to another bot

Arguments:

  • bot – Mineflayer bot instance

  • targetBotName (string) – Name of the target bot

  • threshold (number) – Distance threshold (default: 1.0)

Returns:

boolean – True if bots are within threshold distance

primitives.movement.land_pos(bot, x, z)

Find suitable landing position at given coordinates

Arguments:

  • bot – Mineflayer bot instance

  • x (number) – X coordinate

  • z (number) – Z coordinate

Returns:

Vec3|null – Landing position or null if not found

primitives.movement.jump(bot, durationMs)

Make bot jump for specified duration

Arguments:

  • bot – Mineflayer bot instance

  • durationMs (number) – Duration in milliseconds

primitives.movement.sneak(bot, durationTicks=5, idleTicks=25)

Make bot sneak for specified number of ticks (default: 5 ticks)

Arguments:

  • bot – Mineflayer bot instance

  • durationTicks (number) – Number of ticks to sneak (default: 5)

  • idleTicks (number) – Number of ticks to idle for after releasing sneak (default: 5)

primitives.movement.directTeleport(bot, rcon, otherBotName, episodeNum, points)

Direct teleport to specific points from a list. Used for episodes that require precise positioning (e.g. TurnToLookEpisode).

Arguments:

  • bot – Mineflayer bot instance

  • rcon – RCON connection instance

  • otherBotName (string) – Name of the other bot

  • episodeNum (number) – Episode number

  • points (Array.<Array.<number>>) – List of [x, y, z] coordinates

primitives.movement.getScaffoldingBlockIds(mcData, blockNames=null)

Get scaffolding block IDs from block names

Arguments:

  • mcData (Object) – minecraft-data instance for the bot’s version

  • blockNames (Array.<string>) – Optional array of block names (defaults to DEFAULT_SCAFFOLDING_BLOCK_NAMES)

Returns:

Array.<number> – Array of block item IDs

Random-movement

primitives.random-movement.walk(bot, distance, lookAway, flipCameraInReturn, args, customConstants={})

Perform a single randomized walk action (optionally looking away) and return.

Arguments:

  • bot – Mineflayer bot instance

  • distance (number) – Distance to walk before returning

  • lookAway (boolean) – If true, rotate camera away while walking

  • flipCameraInReturn (boolean) – If true, flip camera and reuse same dir on return

  • args – Episode args (expects walk_timeout)

  • customConstants (Object) – Optional per-episode constant overrides

Returns:

Promise.<void>

primitives.random-movement.run(bot, actionCount, lookAway, args, customConstants={})

Run a sequence of randomized movement actions.

Arguments:

  • bot – Mineflayer bot instance

  • actionCount (number) – Number of actions to execute

  • lookAway (boolean) – If true, include “look away” variants of actions

  • args – Episode args (expects walk_timeout)

  • customConstants (Object) – Optional per-episode constant overrides

Returns:

Promise.<void>

primitives.random-movement.getRandomDirection()

Get random cardinal direction (north, south, east, west)

Returns:

Object – Direction object with name and offset