spectra-physics 1.2.0 → 1.3.0

package/README.md

@@ -129,6 +129,35 @@ Added:
 - `bot.spectra.world` – block and fluid lookups used by the engine
 - event `clientLoaded` – 1.21.4+, emitted when `player_loaded` is sent
 
+### Pathfinder
+
+A built-in pathfinder with the same API as mineflayer-pathfinder, driven by the engine itself:
+
+```js
+const { createBot, goals } = require('spectra-physics')
+
+const bot = createBot({ host: 'localhost', username: 'Steve', version: '1.21.4' })
+
+bot.once('spawn', async () => {
+  await bot.pathfinder.goto(new goals.GoalBlock(120, 64, -40))
+  bot.pathfinder.setGoal(new goals.GoalFollow(bot.nearestEntity(e => e.name === 'cow'), 2), true)
+})
+```
+
+- A* with costs in ticks, so it picks the fastest route: walking, sprinting, slabs and stairs without jumping,
+  jumps, drops, sprint-jumps over gaps, ladders and vines, swimming, and digging through, up and down
+- keys are chosen by simulating the player a few ticks ahead with this engine: when to sprint, when to jump,
+  which corners can be cut
+- turning goes through the mouse model; blocks are broken tick by tick like the game client (face in view,
+  progress and swing every tick, 5 ticks between blocks), also available as `bot.spectra.dig(block)`
+- the route is planned again when blocks on it change, the goal moves or the bot gets stuck
+- goals: `GoalBlock`, `GoalNear`, `GoalXZ`, `GoalNearXZ`, `GoalY`, `GoalGetToBlock`, `GoalLookAtBlock`,
+  `GoalFollow`, `GoalCompositeAny`, `GoalCompositeAll`, `GoalInvert`
+- `bot.pathfinder.settings`: `canDig`, `allowParkour`, `allowLongParkour`, `allowSprinting`, `maxDropDown`,
+  `thinkTimeout`, `tickTimeout`; events `path_update`, `path_reset`, `path_stop`, `goal_reached`, `goal_updated`
+
+mineflayer-pathfinder works too: `bot.physics.simulatePlayer` runs its look-ahead on this engine.
+
 ### Standalone engine
 
 The engine can run without a connection, for prediction or tests:
@@ -186,6 +215,7 @@ powder snow, ice, soul sand, pushing, item use, and the position reporting thres
 lib/engine          world access, collisions, version switches, boat
 lib/engine/player   the player tick: input, fluids, blocks under the player, move, travel, block effects and their
                     traversal order, pose, pushing
+lib/pathfinder      goals, terrain, moves, A*, block breaking and the path follower
 lib/client          mineflayer integration: controls, teleports, server packets, position reporting, riding, item use,
                     entity interaction, registry tables, protocol fixes, the shared clock
 bench               tick cost and bit-exact output fingerprints

package/index.js

@@ -25,3 +25,4 @@ module.exports.BoatPhysics = BoatPhysics
 module.exports.WorldView = WorldView
 module.exports.AABB = AABB
 module.exports.versionFlags = versionFlags
+module.exports.goals = require('./lib/pathfinder/goals')

package/lib/client/index.js

@@ -15,6 +15,8 @@ const { installTicker } = require('./ticker')
 const { installItemUse } = require('./items')
 const { installInteract } = require('./interact')
 const { installProtocolPatches } = require('./protocol')
+const { installSimulation } = require('./simulation')
+const { installPathfinder } = require('../pathfinder')
 
 function debugLogger (option) {
   if (typeof option === 'function') return option
@@ -75,6 +77,8 @@ function spectraPhysics (options = {}) {
     installTeleport(ctx)
     installServerHandlers(ctx)
     installRiding(ctx)
+    installSimulation(ctx)
+    installPathfinder(ctx)
   }
 }
 

package/lib/client/simulation.js

@@ -0,0 +1,35 @@
+'use strict'
+// bot.physics.simulatePlayer for plugins written against prismarine-physics (mineflayer-pathfinder plans
+// its jumps with it): the prediction runs on this engine, so plans match how the bot really moves.
+
+const conv = require('mineflayer/lib/conversions')
+
+function installSimulation (ctx) {
+  const { bot, player } = ctx
+  const running = new WeakMap()
+
+  bot.physics.simulatePlayer = (state) => {
+    let sim = running.get(state)
+    if (!sim) {
+      sim = player.clone()
+      running.set(state, sim)
+    }
+    sim.pos = { x: state.pos.x, y: state.pos.y, z: state.pos.z }
+    sim.vel = { x: state.vel.x, y: state.vel.y, z: state.vel.z }
+    sim.onGround = !!state.onGround
+    sim.yRot = conv.toNotchianYaw(state.yaw)
+    sim.xRot = conv.toNotchianPitch(state.pitch)
+    const c = state.control ?? {}
+    sim.tick({ forward: !!c.forward, back: !!c.back, left: !!c.left, right: !!c.right, jump: !!c.jump, sprint: !!c.sprint, sneak: !!c.sneak })
+    state.pos.set(sim.pos.x, sim.pos.y, sim.pos.z)
+    state.vel.set(sim.vel.x, sim.vel.y, sim.vel.z)
+    state.onGround = sim.onGround
+    state.isInWater = sim.isInWater()
+    state.isInLava = sim.isInLava()
+    state.isCollidedHorizontally = sim.horizontalCollision
+    state.isCollidedVertically = sim.verticalCollision
+    return state
+  }
+}
+
+module.exports = { installSimulation }

package/lib/engine/player/index.js

@@ -79,6 +79,17 @@ class PlayerPhysics {
     this.events = { abilitiesChanged: false }
   }
 
+  // an independent copy for looking ahead: same world and environment, own state
+  clone () {
+    const copy = new PlayerPhysics(this.world, this.V, this.env)
+    for (const key of Object.keys(this)) {
+      if (key === 'world' || key === 'V' || key === 'env' || key === 'collisionContext') continue
+      const value = this[key]
+      copy[key] = value !== null && typeof value === 'object' ? structuredClone(value) : value
+    }
+    return copy
+  }
+
   height () { return pose.POSES[this.pose].height }
   eyeHeight () { return pose.POSES[this.pose].eye }
   bbAt (x, y, z) { return pose.boxFor(this.pose, x, y, z) }

package/lib/pathfinder/astar.js

@@ -0,0 +1,167 @@
+'use strict'
+// A* over the move graph. The search can be spread over several ticks (compute() returns 'partial' while
+// it is still thinking) and always offers the best path found so far.
+
+const { performance } = require('perf_hooks')
+const { neighbours } = require('./moves')
+
+// Plain A* (optimal) while the search converges. When it keeps expanding without reaching the goal, as when
+// digging makes the real cost far higher than any estimate, the heuristic gets more weight step by step and
+// the search turns greedy enough to find a route in time.
+const RELAX_EVERY = 2000
+const RELAX_FACTOR = 2
+const MAX_WEIGHT = 10000
+
+const OFFSET = 2 ** 19
+const SPAN = 2 ** 20
+
+class Heap {
+  constructor () { this.items = [] }
+  get size () { return this.items.length }
+
+  push (n) {
+    const a = this.items
+    a.push(n)
+    let i = a.length - 1
+    n.heapIndex = i
+    while (i > 0) {
+      const p = (i - 1) >> 1
+      if (!less(a[i], a[p])) break
+      swap(a, i, p)
+      i = p
+    }
+  }
+
+  pop () {
+    const a = this.items
+    const top = a[0]
+    const last = a.pop()
+    if (a.length) {
+      a[0] = last
+      last.heapIndex = 0
+      this.down(0)
+    }
+    top.heapIndex = -1
+    return top
+  }
+
+  update (n) {
+    const a = this.items
+    let i = n.heapIndex
+    while (i > 0) {
+      const p = (i - 1) >> 1
+      if (!less(a[i], a[p])) break
+      swap(a, i, p)
+      i = p
+    }
+  }
+
+  down (i) {
+    const a = this.items
+    for (;;) {
+      const l = 2 * i + 1
+      const r = l + 1
+      let m = i
+      if (l < a.length && less(a[l], a[m])) m = l
+      if (r < a.length && less(a[r], a[m])) m = r
+      if (m === i) return
+      swap(a, i, m)
+      i = m
+    }
+  }
+}
+
+const less = (a, b) => a.f < b.f || (a.f === b.f && a.h < b.h)
+function swap (a, i, j) {
+  const t = a[i]; a[i] = a[j]; a[j] = t
+  a[i].heapIndex = i; a[j].heapIndex = j
+}
+
+class AStar {
+  constructor (start, goal, terrain, opts) {
+    this.goal = goal
+    this.terrain = terrain
+    this.opts = opts
+    this.ox = start.x
+    this.oz = start.z
+    this.nodes = new Map()
+    this.open = new Heap()
+    this.started = performance.now()
+    this.visited = 0
+    this.weight = 1
+    const first = this.record(start)
+    first.g = 0
+    first.h = goal.heuristic(start)
+    first.f = first.h
+    this.best = first
+    this.open.push(first)
+  }
+
+  key (x, y, z) {
+    return ((x - this.ox + OFFSET) * SPAN + (z - this.oz + OFFSET)) * 8192 + (y + 4096)
+  }
+
+  record (n) {
+    const key = this.key(n.x, n.y, n.z)
+    let r = this.nodes.get(key)
+    if (!r) {
+      r = { ...n, g: Infinity, h: 0, f: Infinity, parent: null, heapIndex: -1, closed: false }
+      this.nodes.set(key, r)
+    }
+    return r
+  }
+
+  // runs until the goal is found, the tick budget is spent, or the search gives up
+  compute () {
+    const { tickTimeout, thinkTimeout, maxNodes } = this.opts
+    const tickStart = performance.now()
+    const goal = this.goal
+    while (this.open.size) {
+      if (performance.now() - tickStart > tickTimeout) return this.result('partial')
+      if (performance.now() - this.started > thinkTimeout || this.visited > maxNodes) return this.result('timeout')
+      if (this.visited > 0 && this.visited % RELAX_EVERY === 0 && this.weight < MAX_WEIGHT) this.relax()
+      const cur = this.open.pop()
+      if (goal.isEnd(cur)) return this.result('success', cur)
+      cur.closed = true
+      this.visited++
+      for (const nb of neighbours(cur, this.terrain, this.opts)) {
+        const r = this.record(nb)
+        if (r.closed) continue
+        const g = cur.g + nb.cost
+        if (g >= r.g) continue
+        Object.assign(r, nb)
+        r.parent = cur
+        r.g = g
+        r.h = goal.heuristic(r)
+        r.f = g + r.h * this.weight
+        if (r.h < this.best.h || (r.h === this.best.h && g < this.best.g)) this.best = r
+        if (r.heapIndex < 0) this.open.push(r)
+        else this.open.update(r)
+      }
+    }
+    return this.result('noPath')
+  }
+
+  relax () {
+    this.weight = Math.min(MAX_WEIGHT, this.weight * RELAX_FACTOR)
+    const items = this.open.items
+    for (const n of items) n.f = n.g + n.h * this.weight
+    for (let i = (items.length >> 1) - 1; i >= 0; i--) this.open.down(i)
+  }
+
+  result (status, end = this.best) {
+    const path = []
+    for (let n = end; n && n.parent; n = n.parent) path.push(n)
+    path.reverse()
+    return {
+      status,
+      path,
+      cost: end.g,
+      time: performance.now() - this.started,
+      visitedNodes: this.visited,
+      generatedNodes: this.nodes.size
+    }
+  }
+}
+
+module.exports = { AStar }

package/lib/pathfinder/costs.js

@@ -0,0 +1,21 @@
+'use strict'
+// Move costs in game ticks, from the engine's own speeds: sprinting 0.2806 blocks per tick, climbing
+// 0.1176 up and 0.15 down, swimming about 0.11. A* then finds the fastest route, not just the shortest.
+
+const walk = 1 / 0.2806
+
+const COST = {
+  walk,
+  diagonal: walk * Math.SQRT2,
+  jumpUp: walk + 2.5, // the jump costs a few ticks of forward speed
+  dropDown: walk + 1, // plus fallTick per block fallen
+  fallTick: 1.2,
+  parkourGap: 2, // extra for every jump over a gap, on top of the distance
+  climbUp: 1 / 0.1176,
+  climbDown: 1 / 0.15,
+  swim: 9,
+  digSetup: 6, // stopping and turning to the block
+  avoid: 40 // stepping somewhere unpleasant but harmless (soul sand, honey, a cobweb we must cross)
+}
+
+module.exports = { COST }

package/lib/pathfinder/digger.js

@@ -0,0 +1,132 @@
+'use strict'
+// Block breaking the way MultiPlayerGameMode does it: look at a visible face, START on one tick, add the
+// destroy progress and swing every tick, STOP on the tick it reaches 1, then wait 5 ticks before the next
+// block. mineflayer's dig() runs on a wall clock and swings every 350 ms instead.
+
+const { Vec3 } = require('vec3')
+
+const DESTROY_DELAY = 5
+const FACES = [
+  { axis: 'y', sign: -1, face: 0 }, { axis: 'y', sign: 1, face: 1 },
+  { axis: 'z', sign: -1, face: 2 }, { axis: 'z', sign: 1, face: 3 },
+  { axis: 'x', sign: -1, face: 4 }, { axis: 'x', sign: 1, face: 5 }
+]
+
+function installDigger (ctx) {
+  const { bot, client, V } = ctx
+  const hasSequence = V.protocol >= 759
+  let sequence = 0
+  let job = null
+  let delay = 0
+
+  const send = (status, block, face) => {
+    const packet = { status, location: block.position, face }
+    if (hasSequence) packet.sequence = status === 0 || status === 2 ? ++sequence : 0
+    client.write('block_dig', packet)
+  }
+
+  // faces the eyes can see, aimed at through the open side; closest first
+  function aimPoints (block) {
+    const eye = bot.entity.position.offset(0, bot.entity.eyeHeight ?? 1.62, 0)
+    const c = block.position.offset(0.5, 0.5, 0.5)
+    const out = []
+    for (const f of FACES) {
+      const toward = f.sign * (eye[f.axis] - c[f.axis])
+      if (toward <= 0.5) continue
+      const point = c.clone()
+      point[f.axis] += f.sign * 0.5
+      const dir = point.minus(eye).normalize()
+      const hit = bot.world.raycast(eye, dir, 6)
+      if (!hit || !hit.position.equals(block.position)) continue
+      out.push({ point: hit.intersect ?? point, face: hit.face ?? f.face, distance: eye.distanceTo(point) })
+    }
+    return out.sort((a, b) => a.distance - b.distance)
+  }
+
+  async function equipBest (block) {
+    const tool = bestTool(bot, block)
+    if (tool && bot.heldItem?.type !== tool.type) await bot.equip(tool, 'hand')
+  }
+
+  bot.on('physicsTick', () => {
+    if (delay > 0) delay--
+    if (!job) return
+    const block = bot.blockAt(job.block.position)
+    if (!block || block.type !== job.block.type) return finish(null)
+    if (!job.started) {
+      if (delay > 0) return
+      job.started = true
+      const ticks = Math.ceil(bot.digTime(block) / 50)
+      send(0, block, job.face)
+      bot.swingArm()
+      if (ticks <= 1) return finish(null, true)
+      return
+    }
+    if (job.waitingBreak) {
+      if (++job.waited > 20) finish(new Error('the server did not break the block'))
+      return
+    }
+    job.progress += 50 / Math.max(50, bot.digTime(block))
+    bot.swingArm()
+    if (job.progress >= 1 - 1e-9) {
+      send(2, block, job.face)
+      delay = DESTROY_DELAY
+      job.waitingBreak = true
+      job.waited = 0
+    }
+  })
+
+  bot.on('blockUpdate', (oldBlock, newBlock) => {
+    if (!job || !newBlock || !newBlock.position.equals(job.block.position)) return
+    if (newBlock.type !== job.block.type) finish(null)
+  })
+
+  function finish (err) {
+    const j = job
+    job = null
+    if (!j) return
+    if (err) j.reject(err)
+    else j.resolve()
+  }
+
+  ctx.dig = async (block) => {
+    if (job) throw new Error('already digging')
+    const aim = aimPoints(block)[0]
+    if (!aim) throw new Error(`${block.name} is not in view`)
+    await bot.lookAt(aim.point)
+    await equipBest(block)
+    if (bot.digTime(block) === Infinity) throw new Error(`cannot dig ${block.name}`)
+    return new Promise((resolve, reject) => {
+      job = { block, face: aim.face, progress: 0, started: false, resolve, reject }
+      setTimeout(() => { if (job && job.block === block) finish(new Error('dig timeout')) }, 60000)
+    })
+  }
+
+  ctx.stopDigging = () => {
+    if (!job) return
+    if (job.started && !job.waitingBreak) send(1, job.block, job.face)
+    finish(new Error('digging stopped'))
+  }
+
+  ctx.isDigging = () => !!job
+}
+
+// the inventory item that breaks a block fastest (null: the empty hand is as good)
+function bestTool (bot, block) {
+  let best = null
+  let bestTime = bot.digTime ? digTimeWith(bot, block, null) : Infinity
+  for (const item of bot.inventory.items()) {
+    const t = digTimeWith(bot, block, item)
+    if (t < bestTime) { best = item; bestTime = t }
+  }
+  return best
+}
+
+function digTimeWith (bot, block, item) {
+  let enchants = []
+  try { enchants = item?.enchants ?? [] } catch { enchants = [] }
+  return block.digTime(item ? item.type : null, bot.game?.gameMode === 'creative', bot.entity.isInWater, !bot.entity.onGround,
+    Array.isArray(enchants) ? enchants : [], bot.entity.effects)
+}
+
+module.exports = { installDigger, bestTool, Vec3 }

package/lib/pathfinder/goals.js

@@ -0,0 +1,236 @@
+'use strict'
+// Goals for the pathfinder, with the same shape as mineflayer-pathfinder's (heuristic, isEnd, hasChanged,
+// isValid) so code written for it keeps working. Heuristics are in ticks, matching the move costs: the
+// fastest way over flat ground is sprinting (about 3.56 ticks per block), so they never overestimate.
+
+const { COST } = require('./costs')
+
+function horizontal (dx, dz) {
+  const ax = Math.abs(dx)
+  const az = Math.abs(dz)
+  return Math.max(ax, az) + (Math.SQRT2 - 1) * Math.min(ax, az)
+}
+
+// lower bound on the ticks needed to cover the offset: going up is at least a walk per block,
+// going down at least the fall time per block
+function estimate (dx, dy, dz) {
+  return COST.walk * Math.max(horizontal(dx, dz), Math.max(0, dy)) + COST.fallTick * Math.max(0, -dy)
+}
+
+class Goal {
+  heuristic () { return 0 }
+  isEnd () { return true }
+  hasChanged () { return false }
+  isValid () { return true }
+}
+
+class GoalBlock extends Goal {
+  constructor (x, y, z) {
+    super()
+    this.x = Math.floor(x); this.y = Math.floor(y); this.z = Math.floor(z)
+  }
+
+  heuristic (node) { return estimate(this.x - node.x, this.y - node.y, this.z - node.z) }
+  isEnd (node) { return node.x === this.x && node.y === this.y && node.z === this.z }
+}
+
+class GoalNear extends Goal {
+  constructor (x, y, z, range) {
+    super()
+    this.x = Math.floor(x); this.y = Math.floor(y); this.z = Math.floor(z)
+    this.rangeSq = range * range
+    this.range = range
+  }
+
+  heuristic (node) {
+    const d = estimate(this.x - node.x, this.y - node.y, this.z - node.z)
+    return Math.max(0, d - this.range * COST.walk)
+  }
+
+  isEnd (node) {
+    const dx = this.x - node.x; const dy = this.y - node.y; const dz = this.z - node.z
+    return dx * dx + dy * dy + dz * dz <= this.rangeSq
+  }
+}
+
+class GoalXZ extends Goal {
+  constructor (x, z) {
+    super()
+    this.x = Math.floor(x); this.z = Math.floor(z)
+  }
+
+  heuristic (node) { return COST.walk * horizontal(this.x - node.x, this.z - node.z) }
+  isEnd (node) { return node.x === this.x && node.z === this.z }
+}
+
+class GoalNearXZ extends Goal {
+  constructor (x, z, range) {
+    super()
+    this.x = Math.floor(x); this.z = Math.floor(z)
+    this.range = range
+    this.rangeSq = range * range
+  }
+
+  heuristic (node) { return Math.max(0, COST.walk * (horizontal(this.x - node.x, this.z - node.z) - this.range)) }
+  isEnd (node) {
+    const dx = this.x - node.x; const dz = this.z - node.z
+    return dx * dx + dz * dz <= this.rangeSq
+  }
+}
+
+class GoalY extends Goal {
+  constructor (y) {
+    super()
+    this.y = Math.floor(y)
+  }
+
+  heuristic (node) { return estimate(0, this.y - node.y, 0) }
+  isEnd (node) { return node.y === this.y }
+}
+
+// stand next to a block (any of the 6 neighbours, or on top of it)
+class GoalGetToBlock extends Goal {
+  constructor (x, y, z) {
+    super()
+    this.x = Math.floor(x); this.y = Math.floor(y); this.z = Math.floor(z)
+  }
+
+  heuristic (node) {
+    const dx = this.x - node.x; const dy = this.y - node.y; const dz = this.z - node.z
+    return Math.max(0, estimate(dx, dy, dz) - COST.walk)
+  }
+
+  isEnd (node) {
+    return Math.abs(this.x - node.x) + Math.abs(this.y - node.y) + Math.abs(this.z - node.z) === 1
+  }
+}
+
+// a face of the block can be seen and reached from the eyes (survival 4.5 blocks)
+class GoalLookAtBlock extends Goal {
+  constructor (pos, world, options = {}) {
+    super()
+    this.x = Math.floor(pos.x); this.y = Math.floor(pos.y); this.z = Math.floor(pos.z)
+    this.world = world
+    this.reach = options.reach ?? 4.5
+    this.eyeHeight = options.eyeHeight ?? 1.62
+    this.reachSq = this.reach * this.reach
+  }
+
+  visible (node) {
+    if (!this.world?.raycast) return true
+    const { Vec3 } = require('vec3')
+    const eye = new Vec3(node.x + 0.5, (node.floor ?? node.y) + this.eyeHeight, node.z + 0.5)
+    const faces = [[0.5, 1.001, 0.5], [0.5, -0.001, 0.5], [-0.001, 0.5, 0.5], [1.001, 0.5, 0.5], [0.5, 0.5, -0.001], [0.5, 0.5, 1.001]]
+    for (const [fx, fy, fz] of faces) {
+      const target = new Vec3(this.x + fx, this.y + fy, this.z + fz)
+      const dir = target.minus(eye)
+      const length = dir.norm()
+      if (length > this.reach) continue
+      const hit = this.world.raycast(eye, dir.normalize(), length + 0.01)
+      if (hit && hit.position.x === this.x && hit.position.y === this.y && hit.position.z === this.z) return true
+    }
+    return false
+  }
+
+  heuristic (node) {
+    const d = estimate(this.x - node.x, this.y - node.y, this.z - node.z)
+    return Math.max(0, d - (this.reach - 1) * COST.walk)
+  }
+
+  isEnd (node) {
+    const dx = this.x + 0.5 - (node.x + 0.5)
+    const dy = this.y + 0.5 - (node.y + this.eyeHeight)
+    const dz = this.z + 0.5 - (node.z + 0.5)
+    if (node.x === this.x && node.z === this.z && (node.y === this.y || node.y + 1 === this.y)) return false
+    return dx * dx + dy * dy + dz * dz <= this.reachSq && this.visible(node)
+  }
+}
+
+class GoalCompositeAny extends Goal {
+  constructor (goals = []) {
+    super()
+    this.goals = goals
+  }
+
+  push (goal) { this.goals.push(goal) }
+  heuristic (node) { return Math.min(...this.goals.map(g => g.heuristic(node))) }
+  isEnd (node) { return this.goals.some(g => g.isEnd(node)) }
+  hasChanged () { return this.goals.some(g => g.hasChanged()) }
+  isValid () { return this.goals.every(g => g.isValid()) }
+}
+
+class GoalCompositeAll extends Goal {
+  constructor (goals = []) {
+    super()
+    this.goals = goals
+  }
+
+  push (goal) { this.goals.push(goal) }
+  heuristic (node) { return Math.max(...this.goals.map(g => g.heuristic(node))) }
+  isEnd (node) { return this.goals.every(g => g.isEnd(node)) }
+  hasChanged () { return this.goals.some(g => g.hasChanged()) }
+  isValid () { return this.goals.every(g => g.isValid()) }
+}
+
+class GoalInvert extends Goal {
+  constructor (goal) {
+    super()
+    this.goal = goal
+  }
+
+  heuristic (node) { return -this.goal.heuristic(node) }
+  isEnd (node) { return !this.goal.isEnd(node) }
+  hasChanged () { return this.goal.hasChanged() }
+  isValid () { return this.goal.isValid() }
+}
+
+// stay within range of an entity; the path is refreshed when it moves away from where it was planned to
+class GoalFollow extends Goal {
+  constructor (entity, range) {
+    super()
+    this.entity = entity
+    this.range = range
+    this.rangeSq = range * range
+    this.update()
+  }
+
+  update () {
+    const p = this.entity.position
+    this.x = Math.floor(p.x); this.y = Math.floor(p.y); this.z = Math.floor(p.z)
+  }
+
+  heuristic (node) {
+    const d = estimate(this.x - node.x, this.y - node.y, this.z - node.z)
+    return Math.max(0, d - this.range * COST.walk)
+  }
+
+  isEnd (node) {
+    const dx = this.x - node.x; const dy = this.y - node.y; const dz = this.z - node.z
+    return dx * dx + dy * dy + dz * dz <= this.rangeSq
+  }
+
+  hasChanged () {
+    const p = this.entity.position
+    const x = Math.floor(p.x); const y = Math.floor(p.y); const z = Math.floor(p.z)
+    if (x === this.x && y === this.y && z === this.z) return false
+    this.x = x; this.y = y; this.z = z
+    return true
+  }
+
+  isValid () { return this.entity != null && this.entity.isValid !== false }
+}
+
+module.exports = {
+  Goal,
+  GoalBlock,
+  GoalNear,
+  GoalXZ,
+  GoalNearXZ,
+  GoalY,
+  GoalGetToBlock,
+  GoalLookAtBlock,
+  GoalCompositeAny,
+  GoalCompositeAll,
+  GoalInvert,
+  GoalFollow
+}