spectra-physics 1.0.0 → 1.2.0

package/README.md

@@ -22,21 +22,46 @@ several places that are visible to the server:
 | Collision | legacy 1.8 algorithm | `Shapes.collide` with VoxelShape epsilons, Y → larger horizontal axis order |
 | Step-up | single step | pre-1.21 heuristic and 1.21+ candidate step heights |
 | First tick after a teleport | moves immediately | no movement, gravity applied after `move`, like vanilla |
-| Position packets | time based, last-sent values reset on teleport | `sendPosition` rules: 2·10⁻⁴ threshold, 20-tick reminder, last-sent values kept across teleports |
+| 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; 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 attribute updated at the end of the tick, as in `Player#aiStep` |
+| 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 |
 
-It also fixes three mineflayer issues that leave a bot stuck:
+It also works around mineflayer issues that break movement:
 
 - an empty full chunk (no sections) sent to a 1.16 client is treated as an unload, so the player never ticks in it;
 - 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.
+- 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;
+- `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
 
@@ -131,16 +156,19 @@ See [`test/helpers.js`](test/helpers.js) for a complete in-memory world.
 ## What is simulated
 
 - gravity, air drag and ground friction (slipperiness per block, supporting block on 1.20+)
-- collisions against block shapes, step-up, sneaking edge back-off (both the old and the 1.21.2+ rules)
-- walking, sprinting (double-tap and key), sprint-jumping, crouch pose and its bounding box
-- water and lava with flow pushing, climbing (ladders, vines, scaffolding, trapdoors over ladders)
-- cobweb, sweet berry bush, powder snow, honey (sliding), soul sand, slime and bed bouncing
-- levitation, slow falling, jump boost, speed / slowness via attributes, dolphin's grace
+- collisions against block shapes, step-up, sneaking edge back-off
+- walking, sprinting (double-tap and key), sprint-jumping, crouching, crawling and swimming poses
+- water and lava with flow pushing, swimming, climbing (ladders, vines, scaffolding, trapdoors over ladders, powder snow in leather boots)
+- cobweb (and weaving), sweet berry bush, powder snow, honey sliding, bubble columns, soul sand, slime and bed bouncing
+- 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
 
-Not simulated yet: elytra flight, swimming pose, bubble columns, entity collisions, world border.
+Not simulated yet: elytra flight, riptide, world border.
 
 ## Tests
 
@@ -148,20 +176,20 @@ Not simulated yet: elytra flight, swimming pose, bubble columns, entity collisio
 npm test
 ```
 
-Offline tests for 1.16.5, 1.18.2, 1.20.4, 1.21.4 and 26.1 cover free fall, landing on full blocks and slabs,
-walking and sprinting speed, jump height, step-up, wall collision, sneaking at an edge, ice and cobwebs.
-
-## Releasing
+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,
+powder snow, ice, soul sand, pushing, item use, and the position reporting thresholds.
 
-Releases are published to [npm](https://www.npmjs.com/package/spectra-physics) by GitHub Actions.
+## Layout
 
-1. Bump `version` in `package.json` and push to `main`.
-2. Create a GitHub release with the tag `v<version>` (for example `v1.0.1`).
-
-The *Publish to npm* workflow then runs the tests, checks that the tag matches `package.json`, and runs
-`npm publish --provenance --access public`. Publishing needs the repository secret `NPM_TOKEN`
-(an npm granular access token with read and write access to packages and two-factor bypass enabled;
-set it with `gh secret set NPM_TOKEN`). npm limits the lifetime of such tokens, so rotate it before it expires.
+```
+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/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

@@ -1,7 +1,7 @@
 'use strict'
 
-const spectraPhysics = require('./lib/plugin')
-const { PlayerPhysics } = require('./lib/engine/physics')
+const spectraPhysics = require('./lib/client')
+const { PlayerPhysics } = require('./lib/engine/player')
 const BoatPhysics = require('./lib/engine/boat')
 const WorldView = require('./lib/engine/world')
 const AABB = require('./lib/engine/aabb')

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

@@ -0,0 +1,103 @@
+'use strict'
+// Outgoing packets. Also reorders what mineflayer sends on login so it matches the game client:
+// 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) {
+  const text = Buffer.from(brand, 'utf8')
+  const length = []
+  let n = text.length
+  do {
+    let byte = n & 0x7f
+    n >>>= 7
+    if (n) byte |= 0x80
+    length.push(byte)
+  } while (n)
+  return { channel: 'minecraft:brand', data: Buffer.concat([Buffer.from(length), text]) }
+}
+
+function installConnection (ctx) {
+  const { client, V, state } = ctx
+  const rawWrite = client.write.bind(client)
+  const brand = ctx.options.brand ?? client.options?.brand ?? 'vanilla'
+  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))
+  }
+
+  ctx.send = (name, params) => {
+    report(name, params)
+    ours = true
+    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') {
+        if (V.configPhase && state.configBrandSent) return
+        if (!V.configPhase && !state.playSettingsSent) {
+          state.heldBrand = params
+          return
+        }
+      }
+      if (name === 'settings') {
+        if (client.state === 'configuration' && V.configPhase && !state.configBrandSent) {
+          ctx.send('custom_payload', brandPayload(brand))
+          state.configBrandSent = true
+        } else if (client.state === 'play') {
+          if (state.suppressPlaySettings) {
+            state.suppressPlaySettings = false
+            return
+          }
+          report(name, params)
+          rawWrite(name, params)
+          state.playSettingsSent = true
+          if (state.heldBrand) {
+            const held = state.heldBrand
+            state.heldBrand = null
+            rawWrite('custom_payload', held)
+          }
+          return
+        }
+      }
+      report(name, params)
+    }
+    return rawWrite(name, params)
+  }
+
+  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
+    state.heldBrand = null
+    ctx.send('custom_payload', held)
+  }
+}
+
+module.exports = { installConnection }

package/lib/client/controls.js

@@ -0,0 +1,78 @@
+'use strict'
+// mineflayer movement API on top of the simulated player: control states and mouse-like turning.
+
+const conv = require('mineflayer/lib/conversions')
+const { f32, clamp, wrapDegrees } = require('../engine/mth')
+
+const MOUSE_STEP = f32(0.15) // degrees per mouse pixel at default sensitivity
+const RELEASED = Object.freeze({ forward: false, back: false, left: false, right: false, jump: false, sprint: false, sneak: false })
+
+function installControls (ctx) {
+  const { bot, player } = ctx
+  const keys = { ...RELEASED }
+  const turnSpeed = ctx.options.turnSpeed ?? 35
+  let lookWaiters = []
+
+  bot.setControlState = (control, value) => {
+    if (!(control in keys)) throw new Error(`invalid control: ${control}`)
+    keys[control] = !!value
+  }
+  bot.getControlState = (control) => keys[control]
+  bot.clearControlStates = () => { for (const k in keys) keys[k] = false }
+  bot.controlState = {}
+  for (const k of Object.keys(keys)) {
+    Object.defineProperty(bot.controlState, k, { get: () => keys[k], set: (v) => { keys[k] = !!v } })
+  }
+
+  // with a container open the game client stops reading movement keys
+  ctx.keys = () => bot.currentWindow ? RELEASED : keys
+
+  ctx.turn = (maxDegrees = turnSpeed) => {
+    const targetYaw = conv.toNotchianYaw(bot.entity.yaw)
+    const targetPitch = conv.toNotchianPitch(bot.entity.pitch)
+    const limit = maxDegrees / MOUSE_STEP
+    const dx = clamp(Math.round(wrapDegrees(targetYaw - player.yRot) / MOUSE_STEP), -limit, limit)
+    const dy = clamp(Math.round((targetPitch - player.xRot) / MOUSE_STEP), -limit, limit)
+    if (dx !== 0) player.yRot = f32(player.yRot + f32(f32(dx) * MOUSE_STEP))
+    if (dy !== 0) player.xRot = f32(clamp(f32(player.xRot + f32(f32(dy) * MOUSE_STEP)), -90, 90))
+    const reached = Math.abs(wrapDegrees(targetYaw - player.yRot)) < MOUSE_STEP && Math.abs(targetPitch - player.xRot) < MOUSE_STEP
+    if (reached && lookWaiters.length) {
+      const waiters = lookWaiters
+      lookWaiters = []
+      for (const resolve of waiters) resolve()
+    }
+  }
+
+  bot.look = async (yaw, pitch, force) => {
+    bot.entity.yaw = yaw
+    bot.entity.pitch = pitch
+    if (force) {
+      ctx.turn(Infinity)
+      return
+    }
+    await new Promise(resolve => lookWaiters.push(resolve))
+  }
+
+  bot.lookAt = async (point, force) => {
+    const delta = point.minus(bot.entity.position.offset(0, player.eyeHeight(), 0))
+    const yaw = Math.atan2(-delta.x, -delta.z)
+    const pitch = Math.atan2(delta.y, Math.sqrt(delta.x * delta.x + delta.z * delta.z))
+    await bot.look(yaw, pitch, force)
+  }
+
+  bot.waitForTicks = async (ticks) => {
+    if (ticks <= 0) return
+    await new Promise(resolve => {
+      const onTick = () => {
+        if (--ticks > 0) return
+        bot.removeListener('physicsTick', onTick)
+        resolve()
+      }
+      bot.on('physicsTick', onTick)
+    })
+  }
+
+  bot.elytraFly = async () => { throw new Error('elytra flight is not simulated') }
+}
+
+module.exports = { installControls }

package/lib/client/environment.js

@@ -0,0 +1,94 @@
+'use strict'
+// What the movement engine needs to know about the player besides the world.
+
+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 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)
+
+// AttributeInstance#calculateValue, with the sprint modifier owned by the client
+function attributeValue (property, extra = []) {
+  const modifiers = property.modifiers.filter(m => !isSprintModifier(m)).concat(extra)
+  let base = property.value
+  for (const m of modifiers) if (operationOf(m) === 0) base += m.amount
+  let value = base
+  for (const m of modifiers) if (operationOf(m) === 1) value += base * m.amount
+  for (const m of modifiers) if (operationOf(m) === 2) value *= 1 + m.amount
+  return value
+}
+
+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"
+  let attributes = {}
+  const onAttributes = (packet) => {
+    if (packet.entityId !== bot.entity?.id) return
+    for (const p of packet.properties) attributes[attributeName(p.key ?? p.name)] = { value: p.value, modifiers: p.modifiers ?? [] }
+  }
+  bot._client.on('entity_update_attributes', onAttributes)
+  bot._client.on('update_attributes', onAttributes)
+  bot._client.on('login', () => { attributes = {} })
+
+  const findAttribute = (name) => attributes[name] ?? null
+
+  function boots () {
+    return bot.inventory?.slots?.[BOOTS_SLOT] ?? null
+  }
+
+  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
+    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 {
+    attribute (name, fallback) {
+      const property = findAttribute(name)
+      return property ? attributeValue(property) : fallback
+    },
+    movementSpeed (sprinting) {
+      const property = findAttribute('movement_speed') ?? { value: 0.1, modifiers: [] }
+      return attributeValue(property, sprinting ? [{ amount: 0.3, operation: 2 }] : [])
+    },
+    effect (name) {
+      const id = effectId(name)
+      if (id == null) return null
+      const effect = bot.entity?.effects?.[id]
+      return effect ? effect.amplifier : null
+    },
+    bootsEnchant: (name) => enchantmentLevel(boots(), name),
+    bootsItem: () => boots()?.name ?? null,
+    food: () => bot.food ?? 20,
+    usingItem: () => state.using != null,
+    gameMode: () => bot.game?.gameMode,
+    ultraWarm: () => /nether/.test(String(bot.game?.dimension ?? '')),
+    nearbyEntities () {
+      const me = bot.entity?.position
+      if (!me) return []
+      const out = []
+      for (const e of Object.values(bot.entities)) {
+        if (!isPushable(e)) continue
+        const p = e.position
+        if (Math.abs(p.x - me.x) > PUSH_RANGE || Math.abs(p.y - me.y) > PUSH_RANGE || Math.abs(p.z - me.z) > PUSH_RANGE) continue
+        out.push({ x: p.x, y: p.y, z: p.z, width: e.width ?? 0.6, height: e.height ?? 1.8 })
+      }
+      return out
+    }
+  }
+}
+
+module.exports = { createEnvironment }

package/lib/client/index.js

@@ -0,0 +1,81 @@
+'use strict'
+// SpectraPhysics: replacement for mineflayer's `physics` plugin that ticks and reports movement like the game client.
+
+const { versionFlags } = require('../engine/version')
+const WorldView = require('../engine/world')
+const { PlayerPhysics } = require('../engine/player')
+const { createEnvironment } = require('./environment')
+const { installConnection } = require('./connection')
+const { installControls } = require('./controls')
+const { installTeleport } = require('./teleport')
+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')
+
+function debugLogger (option) {
+  if (typeof option === 'function') return option
+  return option ? (...args) => console.log('[spectra]', ...args) : null
+}
+
+function spectraPhysics (options = {}) {
+  return function inject (bot) {
+    const registry = bot.registry
+    const V = versionFlags(registry)
+    const world = new WorldView(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,
+      client: bot._client,
+      registry,
+      V,
+      world,
+      player,
+      options,
+      debug: debugLogger(options.debug),
+      onSend: options.onSend ?? null,
+      outgoing: [],
+      state
+    }
+
+    bot.physicsEnabled = true
+    bot.physics = { gravity: 0.08, yawSpeed: 3, pitchSpeed: 3, stepHeight: 0.6, engine: 'spectra' }
+    bot.spectra = {
+      player,
+      flags: V,
+      world,
+      state: ctx.state,
+      get lastRotationAt () { return ctx.state.lastRotationAt },
+      get onSend () { return ctx.onSend },
+      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)
+  }
+}
+
+module.exports = spectraPhysics

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 }