spectra-physics 1.1.0 → 1.3.0

package/README.md

@@ -25,14 +25,18 @@ several places that are visible to the server:
 | Position packets | time based, last-sent values reset on teleport | `sendPosition` rules: 0.03 threshold before 1.18.2 and 2·10⁻⁴ after, 20-tick reminder, last-sent values kept across teleports |
 | Input | raw ±1 | per version: sneak/item scaling then 0.98 up to 1.21.4, normalized square movement from 1.21.5 |
 | Wall collisions | always zeroes the blocked axis | 1.14–1.18.1 keep X speed in corners, 1.18.2+ compare with an epsilon |
-| Block effects | during the move | during the move before 1.21.2, after travel along the path from 1.21.2 |
+| Block effects | during the move | during the move before 1.21.2; from 1.21.2 after travel, walking the path in each version's own block order |
+| Powder snow | never solid | solid from above in leather boots (not while sneaking), 0.9 high when falling onto it |
+| Item use | any `activateItem`, cleared by any entity's status | only items with a use animation (food when hungry, potions, shield, bow with arrows, …), ended by release, slot change or the server; movement slowed to a fifth |
+| Actions | sent whenever called | use, dig, interact, attack and swing go out at the start of the next tick, before movement; `use_item` carries that tick's rotation |
+| Entity clicks, mounting | `interact` only | aim, `interact_at` with the hit point, `interact`, swing; leaving a vehicle by holding sneak |
 | Rotation | continuous interpolation | whole mouse steps of 0.15°, accumulated in float |
 | Sprint | applied the same tick | speed follows the sprint state in the tick it is sent, as the server applies it |
 | Tick loop | fixed interval | `Minecraft` timer: catches up at most 10 ticks |
 | 1.21.2+ | no `tick_end` | `tick_end` after every tick, `player_input` on key change |
 | 1.21.4+ | `player_loaded` on first health update | sent once the level around the player is loaded |
 | Teleport answer | one order for all versions | per version (1.21.2–1.21.3 send position before the confirmation) |
-| Vehicles | rotation packets only | boat simulation with paddle / input / vehicle move packets, minecart riding |
+| Vehicles | rotation packets only | boat simulation with paddle / input / vehicle move packets (input applies a tick later, as in the game), minecart riding |
 | Brand, 1.20.2+ | sent in play state | sent in the configuration phase, once |
 | Open container | keeps moving | movement keys are ignored while a window is open, as in the game |
 
@@ -42,12 +46,23 @@ It also works around mineflayer issues that break movement:
 - a removed vehicle is never dismounted (`entityGone` is listened for on the wrong emitter);
 - an out-of-range hotbar slot from the server throws inside the packet handler;
 - player attributes are misread: stored under `undefined` on 1.16.5 – 1.20.4 and named from an outdated id table
-  on 1.21+ (on 1.21.2 – 1.21.5 movement speed arrives as step height), so speed effects and step height go wrong.
+  on 1.21+ (on 1.21.2 – 1.21.5 movement speed arrives as step height), so speed effects and step height go wrong;
+- `set_passengers` without the bot never clears `bot.vehicle`, so after every dismount the bot keeps acting as a passenger;
+- enchantments on 1.20.5+ items are not a list (reading boots throws), and from 1.21 their ids come from the server's registry;
+- the 1.16 data numbers dolphin's grace wrong and marks every entity, arrows and items included, as a mob;
+- recipe packets on 1.20.5 – 1.21.3 and advancements on 1.21.2 – 1.21.3 fail to parse; they arrive as raw buffers there.
 
 Before 1.18.2 the client only reports moves longer than 0.03. Airborne moves shorter than that are still reported,
 and on 1.17 – 1.18.1 the mouse holds a turn for up to two seconds while such moves last, because anti-cheats
 cannot reconstruct the skipped vertical movement.
 
+## Performance
+
+All bots in a process share one 20 TPS clock. Inside a tick the engine memoises chunk columns and block data and
+reuses its collision boxes, so a player tick costs about 3 µs (`node bench/tick.js`, 50 players on a course of
+slabs, fences, water, cobwebs and honey). `node bench/trajectory.js --check` compares a fingerprint of every
+simulated position with `bench/baseline.json`, which is how optimisations are checked to change nothing.
+
 ## Installation
 
 ```bash
@@ -114,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:
@@ -148,6 +192,7 @@ See [`test/helpers.js`](test/helpers.js) for a complete in-memory world.
 - being pushed out of blocks and by overlapping entities
 - levitation, slow falling, jump boost, dolphin's grace, depth strider and soul speed,
   attributes: movement speed, gravity, jump strength, step height, sneaking speed, movement and water efficiency
+- using items: eating, drinking, blocking with a shield, drawing a bow
 - creative flight, including toggling with a double jump and landing
 - knockback and explosion velocity, 1.21.2+ relative teleports with velocity
 - riding boats (client-controlled) and minecarts
@@ -162,14 +207,18 @@ npm test
 
 Offline tests for 1.16.5 – 26.1 cover free fall, landing on blocks and slabs, walking and sprinting speed,
 jump height, step-up, walls and corners, sneaking at an edge, input per version, swimming, cobwebs, bubble columns,
-ice, soul sand, pushing, and the position reporting thresholds.
+powder snow, ice, soul sand, pushing, item use, and the position reporting thresholds.
 
 ## Layout
 
 ```
 lib/engine          world access, collisions, version switches, boat
-lib/engine/player   the player tick: input, fluids, blocks under the player, move, travel, block effects, pose, pushing
-lib/client          mineflayer integration: controls, teleports, server packets, position reporting, riding, tick loop
+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
 ```
 
 ## License

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/clock.js

@@ -0,0 +1,38 @@
+'use strict'
+// One 20 TPS timer for every bot in the process (Minecraft's Timer: catches up at most 10 ticks,
+// gives up after falling a second behind).
+
+const { performance } = require('perf_hooks')
+
+const TICK_MS = 50
+const MAX_CATCH_UP = 10
+
+const tickers = new Set()
+let timer = null
+let nextAt = 0
+
+function loop () {
+  const now = performance.now()
+  for (let n = 0; now >= nextAt && n < MAX_CATCH_UP; n++) {
+    for (const tick of tickers) tick()
+    nextAt += TICK_MS
+  }
+  if (now - nextAt > 1000) nextAt = now + TICK_MS
+  timer = tickers.size ? setTimeout(loop, Math.max(0, nextAt - performance.now())) : null
+}
+
+function startTicking (tick) {
+  tickers.add(tick)
+  if (timer) return
+  nextAt = performance.now() + TICK_MS
+  timer = setTimeout(loop, TICK_MS)
+}
+
+function stopTicking (tick) {
+  tickers.delete(tick)
+  if (tickers.size || !timer) return
+  clearTimeout(timer)
+  timer = null
+}
+
+module.exports = { startTicking, stopTicking, TICK_MS }

package/lib/client/connection.js

@@ -3,6 +3,9 @@
 // brand + client information in the configuration phase (1.20.2+), settings before brand on older versions,
 // and player_loaded only when the level has actually loaded.
 
+// actions the game sends from Minecraft#handleKeybinds, before the movement packet of the same tick
+const TICK_ACTIONS = new Set(['use_item', 'block_dig', 'block_place', 'use_entity', 'attack', 'arm_animation', 'entity_action', 'spectate'])
+
 const isBrand = (channel) => channel === 'minecraft:brand' || channel === 'MC|Brand'
 
 function brandPayload (brand) {
@@ -25,6 +28,7 @@ function installConnection (ctx) {
   let ours = false
 
   const report = (name, params) => {
+    for (const watch of ctx.outgoing) watch(name, params)
     if (ctx.onSend) ctx.onSend(name, params)
     if (ctx.debug) ctx.debug('C->S', name, JSON.stringify(params))
   }
@@ -35,7 +39,13 @@ function installConnection (ctx) {
     try { rawWrite(name, params) } finally { ours = false }
   }
 
+  const queued = []
+
   client.write = function (name, params) {
+    if (!ours && TICK_ACTIONS.has(name) && client.state === 'play' && state.inLevel) {
+      queued.push([name, params])
+      return
+    }
     if (!ours) {
       if (name === 'player_loaded' && V.clientLoaded) return
       if (name === 'custom_payload' && isBrand(params?.channel) && client.state === 'play') {
@@ -72,6 +82,16 @@ function installConnection (ctx) {
 
   client.on('finish_configuration', () => { state.suppressPlaySettings = true })
 
+  // use_item carries the rotation of the tick it is sent in (checked by servers since 1.21)
+  ctx.flushActions = () => {
+    while (queued.length) {
+      const [name, params] = queued.shift()
+      if (name === 'use_item' && params.rotation) params.rotation = { x: ctx.player.yRot, y: ctx.player.xRot }
+      report(name, params)
+      rawWrite(name, params)
+    }
+  }
+
   ctx.flushHeldBrand = () => {
     if (!state.heldBrand) return
     const held = state.heldBrand

package/lib/client/environment.js

@@ -1,46 +1,16 @@
 'use strict'
 // What the movement engine needs to know about the player besides the world.
 
-const { PV } = require('../engine/version')
+const { attributeKeyMapper, effectIdMapper, createEnchantmentReader, entityCategory } = require('./registries')
+
 const SPRINT_UUID = '662a6b8d-da3e-4c1c-8813-96ea6097278d'
 const OPERATIONS = { add_value: 0, add_multiplied_base: 1, add_multiplied_total: 2 }
 const PUSH_RANGE = 4
 const PUSHABLE_OBJECTS = /boat|raft|minecart/
 const LIVING_TYPES = new Set(['player', 'mob', 'animal', 'hostile', 'passive', 'water_creature', 'ambient'])
+const NEVER_PUSHES = new Set(['armor_stand', 'bat', 'parrot'])
 const BOOTS_SLOT = 8
 
-const normalizeKey = (key) => String(key)
-  .replace(/^minecraft:/, '')
-  .replace(/^(generic|player)\./, '')
-  .replace(/([a-z])([A-Z])/g, '$1_$2')
-  .toLowerCase()
-
-// attribute registry order from 1.21 on; the protocol tables in minecraft-data stop at the 1.20.5 list
-function attributeRegistry (pv) {
-  if (pv < PV['1.21']) return null
-  return [
-    'armor', 'armor_toughness', 'attack_damage', 'attack_knockback', 'attack_speed', 'block_break_speed',
-    'block_interaction_range', 'burning_time', ...(pv >= PV['1.21.6'] ? ['camera_distance'] : []),
-    'explosion_knockback_resistance', 'entity_interaction_range', 'fall_damage_multiplier', 'flying_speed',
-    'follow_range', 'gravity', 'jump_strength', 'knockback_resistance', 'luck', 'max_absorption', 'max_health',
-    'mining_efficiency', 'movement_efficiency', 'movement_speed', 'oxygen_bonus', 'safe_fall_distance', 'scale',
-    'sneaking_speed', 'spawn_reinforcements', 'step_height', 'submerged_mining_speed', 'sweeping_damage_ratio',
-    ...(pv >= PV['1.21.2'] ? ['tempt_range'] : []), 'water_movement_efficiency',
-    ...(pv >= PV['1.21.6'] ? ['waypoint_receive_range', 'waypoint_transmit_range'] : [])
-  ]
-}
-
-// mineflayer names attributes through the outdated table; map those names back to ids and then to the real names
-function attributeKeyMapper (registry) {
-  const names = attributeRegistry(registry.version.version)
-  const type = registry.protocol?.play?.toClient?.types?.packet_entity_update_attributes
-  const table = type && JSON.stringify(type).match(/"mappings":(\{[^}]*\})/)
-  if (!names || !table) return normalizeKey
-  const ids = {}
-  for (const [id, name] of Object.entries(JSON.parse(table[1]))) ids[name] = Number(id)
-  return (key) => ids[key] != null && names[ids[key]] ? names[ids[key]] : normalizeKey(key)
-}
-
 const SPRINT_IDS = new Set([SPRINT_UUID, 'minecraft:sprinting', 'sprinting'])
 const isSprintModifier = (m) => SPRINT_IDS.has(m.uuid) || SPRINT_IDS.has(m.id)
 const operationOf = (m) => typeof m.operation === 'number' ? m.operation : (OPERATIONS[m.operation] ?? 0)
@@ -56,9 +26,9 @@ function attributeValue (property, extra = []) {
   return value
 }
 
-function createEnvironment (bot) {
-  const effectIds = {}
-  for (const [name, effect] of Object.entries(bot.registry.effectsByName ?? {})) effectIds[name.toLowerCase()] = effect.id
+function createEnvironment (bot, state = {}) {
+  const effectId = effectIdMapper(bot.registry)
+  const enchantmentLevel = createEnchantmentReader(bot)
   const attributeName = attributeKeyMapper(bot.registry)
 
   // kept from the packets directly: mineflayer files 1.16 - 1.20.4 attributes under "undefined"
@@ -80,7 +50,9 @@ function createEnvironment (bot) {
   function isPushable (e) {
     if (!e || e === bot.entity || !e.position || e.isValid === false) return false
     if (e === bot.vehicle || e.vehicle === bot.entity) return false
-    return LIVING_TYPES.has(e.type) || PUSHABLE_OBJECTS.test(e.name ?? '')
+    if (NEVER_PUSHES.has(e.name)) return false
+    // living entities, boats and minecarts push the player; items, projectiles and frames do not
+    return LIVING_TYPES.has(entityCategory(e)) || PUSHABLE_OBJECTS.test(e.name ?? '')
   }
 
   return {
@@ -93,18 +65,15 @@ function createEnvironment (bot) {
       return attributeValue(property, sprinting ? [{ amount: 0.3, operation: 2 }] : [])
     },
     effect (name) {
-      const id = effectIds[name.replace(/_/g, '')]
+      const id = effectId(name)
       if (id == null) return null
       const effect = bot.entity?.effects?.[id]
       return effect ? effect.amplifier : null
     },
-    bootsEnchant (name) {
-      const enchants = boots()?.enchants ?? []
-      return enchants.find(e => e.name === name)?.lvl ?? 0
-    },
+    bootsEnchant: (name) => enchantmentLevel(boots(), name),
     bootsItem: () => boots()?.name ?? null,
     food: () => bot.food ?? 20,
-    usingItem: () => !!bot.usingHeldItem,
+    usingItem: () => state.using != null,
     gameMode: () => bot.game?.gameMode,
     ultraWarm: () => /nether/.test(String(bot.game?.dimension ?? '')),
     nearbyEntities () {

package/lib/client/index.js

@@ -12,6 +12,11 @@ const { installServerHandlers } = require('./server')
 const { installReporter } = require('./reporter')
 const { installRiding } = require('./riding')
 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
@@ -23,7 +28,18 @@ function spectraPhysics (options = {}) {
     const registry = bot.registry
     const V = versionFlags(registry)
     const world = new WorldView(bot)
-    const player = new PlayerPhysics(world, V, createEnvironment(bot))
+    const state = {
+      inLevel: false,
+      configBrandSent: false,
+      suppressPlaySettings: false,
+      playSettingsSent: false,
+      heldBrand: null,
+      selectedSlot: 0,
+      carriedSlot: 0,
+      lastRotationAt: 0,
+      using: null
+    }
+    const player = new PlayerPhysics(world, V, createEnvironment(bot, state))
 
     const ctx = {
       bot,
@@ -35,16 +51,8 @@ function spectraPhysics (options = {}) {
       options,
       debug: debugLogger(options.debug),
       onSend: options.onSend ?? null,
-      state: {
-        inLevel: false,
-        configBrandSent: false,
-        suppressPlaySettings: false,
-        playSettingsSent: false,
-        heldBrand: null,
-        selectedSlot: 0,
-        carriedSlot: 0,
-        lastRotationAt: 0
-      }
+      outgoing: [],
+      state
     }
 
     bot.physicsEnabled = true
@@ -59,13 +67,18 @@ function spectraPhysics (options = {}) {
       set onSend (fn) { ctx.onSend = typeof fn === 'function' ? fn : null }
     }
 
+    installProtocolPatches(ctx)
     installConnection(ctx)
+    installItemUse(ctx)
     installControls(ctx)
+    installInteract(ctx)
     installReporter(ctx)
     installTicker(ctx)
     installTeleport(ctx)
     installServerHandlers(ctx)
     installRiding(ctx)
+    installSimulation(ctx)
+    installPathfinder(ctx)
   }
 }
 

package/lib/client/interact.js

@@ -0,0 +1,79 @@
+'use strict'
+// Right click on an entity the way Minecraft#startUseItem does it: aim, interact_at with the hit point,
+// then interact (a single packet with the location from 26.1), and leaving a vehicle by holding sneak.
+
+const { Vec3 } = require('vec3')
+
+const DISMOUNT_TICKS = 3
+
+// where the look ray enters the entity's box, relative to the entity position
+function hitPoint (eye, look, entity) {
+  const w = (entity.width ?? 0.6) / 2
+  const h = entity.height ?? 1.8
+  const p = entity.position
+  const min = [p.x - w, p.y, p.z - w]
+  const max = [p.x + w, p.y + h, p.z + w]
+  const origin = [eye.x, eye.y, eye.z]
+  const dir = [look.x, look.y, look.z]
+  let near = -Infinity
+  let far = Infinity
+  for (let i = 0; i < 3; i++) {
+    if (Math.abs(dir[i]) < 1e-9) {
+      if (origin[i] < min[i] || origin[i] > max[i]) return new Vec3(0, h / 2, 0)
+      continue
+    }
+    let t1 = (min[i] - origin[i]) / dir[i]
+    let t2 = (max[i] - origin[i]) / dir[i]
+    if (t1 > t2) [t1, t2] = [t2, t1]
+    near = Math.max(near, t1)
+    far = Math.min(far, t2)
+  }
+  if (near > far || far < 0) return new Vec3(0, h / 2, 0)
+  const t = Math.max(near, 0)
+  return new Vec3(eye.x + dir[0] * t - p.x, eye.y + dir[1] * t - p.y, eye.z + dir[2] * t - p.z)
+}
+
+function installInteract (ctx) {
+  const { bot, client, registry, player, state } = ctx
+  const useEntityType = JSON.stringify(registry.protocol?.play?.toServer?.types?.packet_use_entity ?? '')
+  const singleInteract = !useEntityType.includes('"mouse"')
+  state.dismountTicks = 0
+
+  function lookVector () {
+    const yaw = player.yRot * Math.PI / 180
+    const pitch = player.xRot * Math.PI / 180
+    return { x: -Math.sin(yaw) * Math.cos(pitch), y: -Math.sin(pitch), z: Math.cos(yaw) * Math.cos(pitch) }
+  }
+
+  async function rightClick (entity, swing) {
+    if (!entity?.position) throw new Error('entity is gone')
+    await bot.lookAt(entity.position.offset(0, (entity.height ?? 1) / 2, 0))
+    const eye = { x: player.pos.x, y: player.pos.y + player.eyeHeight(), z: player.pos.z }
+    const hit = hitPoint(eye, lookVector(), entity)
+    const sneaking = !!ctx.keys().sneak
+    if (singleInteract) {
+      client.write('use_entity', { target: entity.id, hand: 'main_hand', location: { x: hit.x, y: hit.y, z: hit.z }, sneaking })
+    } else {
+      client.write('use_entity', { target: entity.id, mouse: 2, x: hit.x, y: hit.y, z: hit.z, hand: 0, sneaking })
+      client.write('use_entity', { target: entity.id, mouse: 0, hand: 0, sneaking })
+    }
+    if (swing) client.write('arm_animation', { hand: 0 })
+  }
+
+  bot.useOn = (entity) => rightClick(entity, false)
+  bot.mount = (entity) => rightClick(entity, true)
+
+  bot.dismount = () => {
+    if (!bot.vehicle) {
+      bot.emit('error', new Error('dismount: not mounted'))
+      return
+    }
+    state.dismountTicks = DISMOUNT_TICKS
+  }
+
+  const readKeys = ctx.keys
+  ctx.keys = () => state.dismountTicks > 0 ? { ...readKeys(), sneak: true } : readKeys()
+  bot.on('physicsTick', () => { if (state.dismountTicks > 0) state.dismountTicks-- })
+}
+
+module.exports = { installInteract, hitPoint }

package/lib/client/items.js

@@ -0,0 +1,85 @@
+'use strict'
+// LocalPlayer#startedUsingItem: whether a held item is being used, which slows movement to a fifth.
+// mineflayer's usingHeldItem is set for any item and cleared by any entity's status packet, so the state is
+// rebuilt here from what the client sends and from the server's own view of the player.
+
+const ALWAYS_EDIBLE = new Set(['golden_apple', 'enchanted_golden_apple', 'chorus_fruit', 'honey_bottle', 'suspicious_stew'])
+const DRINKS = new Set(['potion', 'milk_bucket', 'ominous_bottle'])
+const HELD_USE = new Set(['shield', 'trident', 'spyglass', 'goat_horn'])
+const ARROWS = new Set(['arrow', 'spectral_arrow', 'tipped_arrow'])
+const OFFHAND_SLOT = 45
+const FINISHED_USING = 9
+
+function isCharged (item) {
+  const projectiles = item.components?.find?.(c => c.type === 'charged_projectiles')
+  if (projectiles) return (projectiles.data?.projectiles ?? projectiles.data ?? []).length > 0
+  return item.nbt?.value?.Charged?.value === 1
+}
+
+function installItemUse (ctx) {
+  const { bot, client, V, state } = ctx
+  const flagsIndex = V.protocol >= 755 ? 8 : 7
+  const cooldowns = new Map()
+  state.using = null
+
+  const itemIn = (hand) => hand === 1 ? bot.inventory.slots[OFFHAND_SLOT] : bot.heldItem
+  const creative = () => bot.game?.gameMode === 'creative'
+  const hasAmmo = () => creative() || bot.inventory.slots.some(i => i && ARROWS.has(i.name))
+
+  // Item#use returning CONSUME / startUsingItem for the items that have a use animation
+  function canStartUsing (item) {
+    if (!item || (cooldowns.get(item.name) ?? 0) > Date.now()) return false
+    const name = item.name
+    if (DRINKS.has(name) || HELD_USE.has(name)) return true
+    if (name === 'bow') return hasAmmo()
+    if (name === 'crossbow') return !isCharged(item) && (hasAmmo() || bot.inventory.slots[OFFHAND_SLOT]?.name === 'firework_rocket')
+    if (bot.registry.foodsByName?.[name]) return ALWAYS_EDIBLE.has(name) || creative() || (bot.food ?? 20) < 20
+    return false
+  }
+
+  const start = (hand) => {
+    const item = itemIn(hand)
+    state.using = item ? { hand, name: item.name } : null
+  }
+  const stop = () => { state.using = null }
+
+  ctx.outgoing.push((name, params) => {
+    if (name === 'use_item') {
+      const hand = params.hand ?? 0
+      if (canStartUsing(itemIn(hand))) start(hand)
+    } else if (name === 'block_place' && params.direction === -1) {
+      if (canStartUsing(bot.heldItem)) start(0)
+    } else if (name === 'block_dig' && params.status === 5) {
+      stop()
+    }
+  })
+
+  client.on('entity_status', (packet) => {
+    if (packet.entityId === bot.entity?.id && packet.entityStatus === FINISHED_USING) stop()
+  })
+
+  // the server's living entity flags override the client state (LocalPlayer#onSyncedDataUpdated)
+  client.on('entity_metadata', (packet) => {
+    if (packet.entityId !== bot.entity?.id) return
+    const entry = packet.metadata?.find(m => m.key === flagsIndex)
+    if (!entry || typeof entry.value !== 'number') return
+    const active = (entry.value & 1) !== 0
+    if (active && !state.using) start((entry.value & 2) !== 0 ? 1 : 0)
+    else if (!active && state.using) stop()
+  })
+
+  client.on('set_cooldown', (packet) => {
+    const key = packet.cooldownGroup ?? bot.registry.items[packet.itemID]?.name
+    if (key) cooldowns.set(String(key).replace(/^minecraft:/, ''), Date.now() + (packet.cooldownTicks ?? 0) * 50)
+  })
+
+  client.on('respawn', stop)
+  bot.on('death', stop)
+
+  // LivingEntity#updatingUsingItem: switching or losing the item stops the use
+  ctx.updateItemUse = () => {
+    if (state.using && itemIn(state.using.hand)?.name !== state.using.name) stop()
+  }
+}
+
+module.exports = { installItemUse }

package/lib/client/protocol.js

@@ -0,0 +1,42 @@
+'use strict'
+// Fixes for packet layouts minecraft-data gets wrong. They are merged into the client's custom packets
+// before the play state starts, so the parser is built with them.
+
+const { PV } = require('../engine/version')
+
+// recipe and advancement packets whose layout in minecraft-data does not match the game; mineflayer reads neither
+function brokenPackets (pv) {
+  if (pv >= PV['1.20.5'] && pv < PV['1.21.2']) return ['declare_recipes']
+  if (pv === PV['1.21.2']) return ['declare_recipes', 'recipe_book_add', 'advancements']
+  return []
+}
+
+// minecraft-protocol merges custom packets field by field, so every original field has to be overridden:
+// the first one takes the whole payload, the others read nothing
+function rawLayout (original) {
+  const fields = Array.isArray(original?.[1]) ? original[1] : [{}]
+  return ['container', fields.map((field, i) => i === 0
+    ? { name: 'data', type: 'restBuffer' }
+    : { name: field.name ?? `unused${i}`, type: 'void' })]
+}
+
+function installProtocolPatches (ctx) {
+  const { client, registry } = ctx
+  const names = brokenPackets(registry.version.version)
+  if (!names.length) return
+  const types = registry.protocol?.play?.toClient?.types ?? {}
+  const patch = {}
+  for (const name of names) patch[`packet_${name}`] = rawLayout(types[`packet_${name}`])
+
+  const major = registry.version.majorVersion
+  const custom = client.customPackets ?? {}
+  const own = custom[major] ?? {}
+  const userTypes = own.play?.toClient?.types ?? {}
+  custom[major] = {
+    ...own,
+    play: { ...own.play, toClient: { ...own.play?.toClient, types: { ...patch, ...userTypes } } }
+  }
+  client.customPackets = custom
+}
+
+module.exports = { installProtocolPatches }

package/lib/client/registries.js

@@ -0,0 +1,86 @@
+'use strict'
+// Ids the server uses for attributes, effects and enchantments. minecraft-data is outdated or wrong for
+// several of them, so the tables here follow the game registries instead.
+
+const { PV } = require('../engine/version')
+
+const normalizeKey = (key) => String(key)
+  .replace(/^minecraft:/, '')
+  .replace(/^(generic|player|zombie)\./, '')
+  .replace(/([a-z])([A-Z])/g, '$1_$2')
+  .toLowerCase()
+
+// attribute registry order from 1.21 on; the protocol tables in minecraft-data stop at the 1.20.5 list
+function attributeRegistry (pv) {
+  if (pv < PV['1.21']) return null
+  return [
+    'armor', 'armor_toughness', 'attack_damage', 'attack_knockback', 'attack_speed', 'block_break_speed',
+    'block_interaction_range', 'burning_time', ...(pv >= PV['1.21.6'] ? ['camera_distance'] : []),
+    'explosion_knockback_resistance', 'entity_interaction_range', 'fall_damage_multiplier', 'flying_speed',
+    'follow_range', 'gravity', 'jump_strength', 'knockback_resistance', 'luck', 'max_absorption', 'max_health',
+    'mining_efficiency', 'movement_efficiency', 'movement_speed', 'oxygen_bonus', 'safe_fall_distance', 'scale',
+    'sneaking_speed', 'spawn_reinforcements', 'step_height', 'submerged_mining_speed', 'sweeping_damage_ratio',
+    ...(pv >= PV['1.21.2'] ? ['tempt_range'] : []), 'water_movement_efficiency',
+    ...(pv >= PV['1.21.6'] ? ['waypoint_receive_range', 'waypoint_transmit_range'] : [])
+  ]
+}
+
+// mineflayer names attributes through the outdated table; map those names back to ids and then to the real names
+function attributeKeyMapper (registry) {
+  const names = attributeRegistry(registry.version.version)
+  const type = registry.protocol?.play?.toClient?.types?.packet_entity_update_attributes
+  const table = type && JSON.stringify(type).match(/"mappings":(\{[^}]*\})/)
+  if (!names || !table) return normalizeKey
+  const ids = {}
+  for (const [id, name] of Object.entries(JSON.parse(table[1]))) ids[name] = Number(id)
+  return (key) => ids[key] != null && names[ids[key]] ? names[ids[key]] : normalizeKey(key)
+}
+
+// MobEffects registration order (stable for the effects movement cares about); 1-based before 1.20.2
+const EFFECTS = [
+  'speed', 'slowness', 'haste', 'mining_fatigue', 'strength', 'instant_health', 'instant_damage', 'jump_boost',
+  'nausea', 'regeneration', 'resistance', 'fire_resistance', 'water_breathing', 'invisibility', 'blindness',
+  'night_vision', 'hunger', 'weakness', 'poison', 'wither', 'health_boost', 'absorption', 'saturation', 'glowing',
+  'levitation', 'luck', 'unluck', 'slow_falling', 'conduit_power', 'dolphins_grace', 'bad_omen',
+  'hero_of_the_village', 'darkness'
+]
+
+function effectIdMapper (registry) {
+  const zeroBased = registry.version.version >= PV['1.20.2']
+  return (name) => {
+    const index = EFFECTS.indexOf(name)
+    return index < 0 ? null : index + (zeroBased ? 0 : 1)
+  }
+}
+
+// enchantments: item NBT names before 1.20.5, built-in ids in 1.20.5 - 1.20.6, the server's registry from 1.21
+function createEnchantmentReader (bot) {
+  const registry = bot.registry
+  let synced = null
+  bot._client.on('registry_data', (packet) => {
+    if (!/enchantment$/.test(String(packet.id ?? ''))) return
+    synced = (packet.entries ?? []).map(e => normalizeKey(e.key ?? e.id ?? ''))
+  })
+  const nameOf = (id) => synced?.[id] ?? registry.enchantments?.[id]?.name ?? null
+
+  return (item, name) => {
+    if (!item) return 0
+    const component = item.components?.find?.(c => c.type === 'enchantments')
+    if (component) {
+      const list = component.data?.enchantments ?? []
+      return list.find(e => nameOf(e.id) === name)?.level ?? 0
+    }
+    let legacy
+    try { legacy = item.enchants } catch { legacy = null }
+    return Array.isArray(legacy) ? (legacy.find(e => normalizeKey(e.name) === name)?.lvl ?? 0) : 0
+  }
+}
+
+// entity categories; the 1.16 tables mark every entity as a mob, so a later table is used by name
+let entityTable = null
+function entityCategory (entity) {
+  entityTable ??= require('minecraft-data')('1.20.4').entitiesByName
+  return entityTable[entity.name]?.type ?? entity.type
+}
+
+module.exports = { normalizeKey, attributeKeyMapper, effectIdMapper, createEnchantmentReader, entityCategory }