spectra-physics 1.0.0 → 1.1.0

package/README.md

@@ -22,21 +22,31 @@ 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, after travel along the path from 1.21.2 |
 | 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 |
 | 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.
+
+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.
 
 ## Installation
 
@@ -131,16 +141,18 @@ 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
 - 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 +160,17 @@ 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
-
-Releases are published to [npm](https://www.npmjs.com/package/spectra-physics) by GitHub Actions.
+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.
 
-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`).
+## Layout
 
-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, pose, pushing
+lib/client          mineflayer integration: controls, teleports, server packets, position reporting, riding, tick loop
+```
 
 ## 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/connection.js

@@ -0,0 +1,83 @@
+'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.
+
+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) => {
+    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 }
+  }
+
+  client.write = function (name, params) {
+    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 })
+
+  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,125 @@
+'use strict'
+// What the movement engine needs to know about the player besides the world.
+
+const { PV } = require('../engine/version')
+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 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)
+
+// 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) {
+  const effectIds = {}
+  for (const [name, effect] of Object.entries(bot.registry.effectsByName ?? {})) effectIds[name.toLowerCase()] = effect.id
+  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
+    return LIVING_TYPES.has(e.type) || 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 = effectIds[name.replace(/_/g, '')]
+      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
+    },
+    bootsItem: () => boots()?.name ?? null,
+    food: () => bot.food ?? 20,
+    usingItem: () => !!bot.usingHeldItem,
+    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,72 @@
+'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')
+
+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 player = new PlayerPhysics(world, V, createEnvironment(bot))
+
+    const ctx = {
+      bot,
+      client: bot._client,
+      registry,
+      V,
+      world,
+      player,
+      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
+      }
+    }
+
+    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 }
+    }
+
+    installConnection(ctx)
+    installControls(ctx)
+    installReporter(ctx)
+    installTicker(ctx)
+    installTeleport(ctx)
+    installServerHandlers(ctx)
+    installRiding(ctx)
+  }
+}
+
+module.exports = spectraPhysics

package/lib/client/reporter.js

@@ -0,0 +1,91 @@
+'use strict'
+// LocalPlayer#sendPosition and the state packets around it.
+
+const { Vec3 } = require('vec3')
+const { PV } = require('../engine/version')
+
+const POINT_THREE_SQ = 9.0e-4 // 0.03, before 1.18.2
+const MODERN_SQ = 4.0000000000000003e-8 // 2.0E-4 squared
+const REMINDER_TICKS = 20
+
+function installReporter (ctx) {
+  const { bot, V, player, state } = ctx
+  const moveThresholdSq = V.pointThree ? POINT_THREE_SQ : MODERN_SQ
+  const groundFlags = () => ({ onGround: player.onGround, hasHorizontalCollision: player.horizontalCollision })
+
+  ctx.sendSprinting = () => {
+    if (player.sprinting === state.wasSprinting) return
+    ctx.send('entity_action', { entityId: bot.entity.id, actionId: player.sprinting ? 'start_sprinting' : 'stop_sprinting', jumpBoost: 0 })
+    state.wasSprinting = player.sprinting
+  }
+
+  ctx.sendShift = () => {
+    if (V.shiftInInput) return
+    const shift = player.input.shift
+    if (shift === state.wasShift) return
+    ctx.send('entity_action', { entityId: bot.entity.id, actionId: shift ? 'start_sneaking' : 'stop_sneaking', jumpBoost: 0 })
+    state.wasShift = shift
+  }
+
+  ctx.sendInput = () => {
+    const k = ctx.keys()
+    const current = { forward: k.forward, backward: k.back, left: k.left, right: k.right, jump: k.jump, shift: k.sneak, sprint: k.sprint }
+    const last = state.lastInput
+    if (!Object.keys(current).some(key => current[key] !== last[key])) return
+    ctx.send('player_input', { inputs: current })
+    state.lastInput = current
+  }
+
+  ctx.sendLook = () => {
+    ctx.send('look', { yaw: player.yRot, pitch: player.xRot, onGround: player.onGround, flags: groundFlags() })
+    state.lastRotationAt = Date.now()
+  }
+
+  ctx.sendVehicleMove = () => {
+    const boat = state.boat
+    ctx.send('vehicle_move', { x: boat.pos.x, y: boat.pos.y, z: boat.pos.z, yaw: boat.yRot, pitch: boat.xRot, onGround: boat.onGround })
+  }
+
+  ctx.sendPosition = () => {
+    ctx.sendSprinting()
+    if (!V.playerInputPacket) ctx.sendShift()
+    const last = state.last
+    const { pos } = player
+    const dx = pos.x - last.x
+    const dy = pos.y - last.y
+    const dz = pos.z - last.z
+    state.positionReminder++
+    const rotated = player.yRot !== last.yRot || player.xRot !== last.xRot
+    // Grim drops the vertical 0.03 slack for skipped airborne and landing ticks, so those are always reported;
+    // 1.17+ position_look packets under 0.03 would be taken for the item-use duplicate and ignored
+    const airborne = !player.onGround || !last.onGround
+    const reportSmall = V.pointThree && airborne && dy !== 0 && !(rotated && V.protocol >= PV['1.17'])
+    const distanceSq = dx * dx + dy * dy + dz * dz
+    const moved = distanceSq > (reportSmall ? MODERN_SQ : moveThresholdSq) || state.positionReminder >= REMINDER_TICKS
+    state.creeping = V.pointThree && V.protocol >= PV['1.17'] && airborne && dy !== 0 && distanceSq <= POINT_THREE_SQ
+    const flags = { onGround: player.onGround, flags: groundFlags() }
+    const previous = new Vec3(last.x, last.y, last.z)
+
+    if (moved && rotated) ctx.send('position_look', { x: pos.x, y: pos.y, z: pos.z, yaw: player.yRot, pitch: player.xRot, ...flags })
+    else if (moved) ctx.send('position', { x: pos.x, y: pos.y, z: pos.z, ...flags })
+    else if (rotated) ctx.send('look', { yaw: player.yRot, pitch: player.xRot, ...flags })
+    else if (last.onGround !== player.onGround || (V.movementFlags && last.horizontalCollision !== player.horizontalCollision)) ctx.send('flying', flags)
+
+    if (moved) {
+      last.x = pos.x
+      last.y = pos.y
+      last.z = pos.z
+      state.positionReminder = 0
+    }
+    if (rotated) {
+      last.yRot = player.yRot
+      last.xRot = player.xRot
+      state.lastRotationAt = Date.now()
+    }
+    last.onGround = player.onGround
+    last.horizontalCollision = player.horizontalCollision
+    if (moved || rotated) bot.emit('move', previous)
+  }
+}
+
+module.exports = { installReporter }

package/lib/client/riding.js

@@ -0,0 +1,65 @@
+'use strict'
+// Passenger tick: the boat moves first (client controlled), then the rider sends rotation, input and vehicle move.
+
+const conv = require('mineflayer/lib/conversions')
+const BoatPhysics = require('../engine/boat')
+const { f32, clamp, wrapDegrees } = require('../engine/mth')
+const { readKeys } = require('../engine/player/input')
+
+const isBoat = (entity) => /boat|raft/.test(entity?.name ?? '')
+
+function riderOffset (vehicle) {
+  if (isBoat(vehicle)) return f32(-0.1 + -0.35)
+  if (/minecart/.test(vehicle?.name ?? '')) return f32(-0.35)
+  return (vehicle?.height ?? 1) * 0.75 - 0.35
+}
+
+function installRiding (ctx) {
+  const { bot, V, player, state, world } = ctx
+
+  function tickBoat (vehicle, keys) {
+    if (!state.boat || state.boat.entityId !== vehicle.id) {
+      state.boat = new BoatPhysics(world, V, { position: vehicle.position, yawDegrees: f32(conv.toNotchianYaw(vehicle.yaw)) })
+      state.boat.entityId = vehicle.id
+    }
+    state.boat.tick({ forward: keys.forward, back: keys.back, left: keys.left, right: keys.right })
+    ctx.send('steer_boat', { leftPaddle: state.boat.paddle[0], rightPaddle: state.boat.paddle[1] })
+    vehicle.position.set(state.boat.pos.x, state.boat.pos.y, state.boat.pos.z)
+  }
+
+  ctx.ridingTick = (vehicle) => {
+    const keys = ctx.keys()
+    const controlling = vehicle.passengers?.[0] === bot.entity
+    if (isBoat(vehicle) && controlling) tickBoat(vehicle, keys)
+    else state.boat = null
+
+    player.riding = true
+    player.vel = { x: 0, y: 0, z: 0 }
+    readKeys(player, keys, false)
+    player.pos = { x: vehicle.position.x, y: vehicle.position.y + riderOffset(vehicle), z: vehicle.position.z }
+    ctx.turn()
+    if (isBoat(vehicle)) {
+      const boatYaw = state.boat ? state.boat.yRot : f32(conv.toNotchianYaw(vehicle.yaw))
+      const offset = wrapDegrees(player.yRot - boatYaw)
+      player.yRot = f32(player.yRot + clamp(offset, -105, 105) - offset)
+    }
+    ctx.syncEntity()
+
+    if (!V.playerInputPacket) {
+      ctx.sendLook()
+      const flags = (player.input.jumping ? 1 : 0) | (player.input.shift ? 2 : 0)
+      ctx.send('steer_vehicle', { sideways: player.input.left, forward: player.input.forward, jump: flags })
+      if (state.boat) ctx.sendVehicleMove()
+      return
+    }
+    ctx.sendShift()
+    ctx.sendInput()
+    ctx.sendLook()
+    if (state.boat) {
+      ctx.sendVehicleMove()
+      ctx.sendSprinting()
+    }
+  }
+}
+
+module.exports = { installRiding }