minecraft-renderer 0.1.93 → 0.1.95

package/src/three/entity/horseHeadAnimation.test.ts

@@ -0,0 +1,159 @@
+//@ts-nocheck
+import * as THREE from 'three'
+import { expect, test } from 'vitest'
+import {
+  HORSE_HEAD_MAX_YAW,
+  applyHorseHeadPose,
+  calculateHorseHeadPose,
+  createHorseHeadAnimationState,
+  createHorseHeadRig,
+  getInterpolatedHorseHeadAnimation,
+  HORSE_HEAD_TICK_SECONDS,
+  setHorseHeadAnimationPosition,
+  updateHorseHeadAnimationFrame
+} from './horseHeadAnimation'
+
+test('head rig keeps world bounds and includes duplicate head parts', () => {
+  const root = new THREE.Group()
+  const body = new THREE.Mesh(new THREE.BoxGeometry(1, 1, 1))
+  body.name = 'Body'
+  const head = new THREE.Mesh(new THREE.BoxGeometry(1, 1, 1))
+  head.name = 'Head'
+  head.position.set(0, 2, -1)
+  const headSaddleA = new THREE.Mesh(new THREE.BoxGeometry(1, 1, 1))
+  headSaddleA.name = 'HeadSaddle'
+  headSaddleA.position.set(0, 1.5, -1)
+  const headSaddleB = new THREE.Mesh(new THREE.BoxGeometry(1, 1, 1))
+  headSaddleB.name = 'HeadSaddle'
+  headSaddleB.position.set(0, 1.8, -1)
+  root.add(body, head, headSaddleA, headSaddleB)
+  root.updateMatrixWorld(true)
+  const before = new THREE.Box3().setFromObject(root)
+
+  const rig = createHorseHeadRig(root)
+  root.updateMatrixWorld(true)
+  const after = new THREE.Box3().setFromObject(root)
+
+  expect(rig.userData.horseHeadParts).toHaveLength(3)
+  expect(rig.userData.horseHeadParts).toContain(head)
+  expect(rig.userData.horseHeadParts.filter(part => part.name === 'HeadSaddle')).toHaveLength(2)
+  expect(after.min.toArray()).toEqual(before.min.toArray())
+  expect(after.max.toArray()).toEqual(before.max.toArray())
+  expect(root.children.filter(child => child.name === 'horse_head_rig')).toHaveLength(1)
+  expect(createHorseHeadRig(root)).toBe(rig)
+})
+
+test('horse head pitch follows entity pitch in radians', () => {
+  const pose = calculateHorseHeadPose({
+    entityPitch: -Math.PI / 6,
+    headYaw: 0,
+    bodyYaw: 0,
+    limbSwing: 0,
+    limbSwingAmount: 0
+  })
+  expect(pose.pitch).toBeCloseTo(-Math.PI / 6)
+  expect(pose.yaw).toBe(0)
+})
+
+test('horse gait subtracts from pitch at full limb amount', () => {
+  const pose = calculateHorseHeadPose({
+    entityPitch: 0,
+    headYaw: 0,
+    bodyYaw: 0,
+    limbSwing: 0,
+    limbSwingAmount: 1
+  })
+  expect(pose.pitch).toBeCloseTo(-0.15)
+})
+
+test('horse gait is disabled for a small limb amount', () => {
+  expect(
+    calculateHorseHeadPose({
+      entityPitch: 0.3,
+      headYaw: 0,
+      bodyYaw: 0,
+      limbSwing: Math.PI,
+      limbSwingAmount: 0.2
+    }).pitch
+  ).toBeCloseTo(0.3)
+})
+
+test('relative head yaw is shortest-path and limited to twenty degrees', () => {
+  expect(
+    calculateHorseHeadPose({
+      entityPitch: 0,
+      headYaw: -Math.PI + 0.1,
+      bodyYaw: Math.PI - 0.1,
+      limbSwing: 0,
+      limbSwingAmount: 0
+    }).yaw
+  ).toBeCloseTo(0.2)
+  expect(
+    calculateHorseHeadPose({
+      entityPitch: 0,
+      headYaw: Math.PI / 2,
+      bodyYaw: 0,
+      limbSwing: 0,
+      limbSwingAmount: 0
+    }).yaw
+  ).toBeCloseTo(HORSE_HEAD_MAX_YAW)
+})
+
+test('animation phase uses authoritative horizontal distance and interpolates between ticks', () => {
+  const state = createHorseHeadAnimationState()
+  setHorseHeadAnimationPosition(state, { x: 10, z: 10 })
+  updateHorseHeadAnimationFrame(state, HORSE_HEAD_TICK_SECONDS)
+  setHorseHeadAnimationPosition(state, { x: 10.1, z: 10 })
+  updateHorseHeadAnimationFrame(state, HORSE_HEAD_TICK_SECONDS)
+  expect(state.limbSwingAmount).toBeCloseTo(0.16)
+  expect(getInterpolatedHorseHeadAnimation(state, 0).limbSwingAmount).toBe(0)
+  expect(getInterpolatedHorseHeadAnimation(state, 1).limbSwingAmount).toBeCloseTo(0.16)
+})
+
+test('movement position is consumed once per render tick', () => {
+  const state = createHorseHeadAnimationState()
+  setHorseHeadAnimationPosition(state, { x: 10, z: 10 })
+  updateHorseHeadAnimationFrame(state, HORSE_HEAD_TICK_SECONDS)
+  setHorseHeadAnimationPosition(state, { x: 10.1, z: 10 })
+  updateHorseHeadAnimationFrame(state, HORSE_HEAD_TICK_SECONDS)
+  expect(state.limbSwingAmount).toBeCloseTo(0.16)
+
+  setHorseHeadAnimationPosition(state, { x: 10.2, z: 10 })
+  expect(state.limbSwingAmount).toBeCloseTo(0.16)
+  updateHorseHeadAnimationFrame(state, HORSE_HEAD_TICK_SECONDS)
+  expect(state.limbSwingAmount).toBeCloseTo(0.256)
+  expect(state.limbSwing).toBeCloseTo(0.416)
+})
+
+test('render frames decay gait when a remote horse stops sending movement updates', () => {
+  const state = createHorseHeadAnimationState()
+  setHorseHeadAnimationPosition(state, { x: 10, z: 10 })
+  updateHorseHeadAnimationFrame(state, HORSE_HEAD_TICK_SECONDS)
+  setHorseHeadAnimationPosition(state, { x: 10.1, z: 10 })
+  updateHorseHeadAnimationFrame(state, HORSE_HEAD_TICK_SECONDS)
+  updateHorseHeadAnimationFrame(state, HORSE_HEAD_TICK_SECONDS)
+  expect(state.limbSwingAmount).toBeCloseTo(0.096)
+  expect(state.limbSwing).toBeCloseTo(0.256)
+})
+
+test('interpolates the leftover time after a tick at 30 FPS', () => {
+  const state = createHorseHeadAnimationState()
+  setHorseHeadAnimationPosition(state, { x: 10, z: 10 })
+  updateHorseHeadAnimationFrame(state, HORSE_HEAD_TICK_SECONDS)
+  setHorseHeadAnimationPosition(state, { x: 10.1, z: 10 })
+
+  updateHorseHeadAnimationFrame(state, 0.033)
+  const interpolated = updateHorseHeadAnimationFrame(state, 0.033)
+
+  expect(state.tickAccumulatorSeconds).toBeCloseTo(0.016)
+  expect(state.elapsedSeconds / HORSE_HEAD_TICK_SECONDS).toBeCloseTo(0.32)
+  expect(interpolated.limbSwingAmount).toBeCloseTo(0.16 * 0.32)
+})
+
+test('applying a pose changes only the runtime rig', () => {
+  const rig = new THREE.Group()
+  applyHorseHeadPose(rig, { pitch: 0.4, yaw: -0.2 })
+  expect(rig.rotation.x).toBeCloseTo(0.4)
+  expect(rig.rotation.y).toBeCloseTo(-0.2)
+  expect(rig.rotation.z).toBe(0)
+})

package/src/three/entity/horseHeadAnimation.ts

@@ -0,0 +1,151 @@
+//@ts-nocheck
+import * as THREE from 'three'
+
+export const HORSE_HEAD_PIVOT = { x: 0, y: 1.25, z: -0.75 } as const
+export const HORSE_HEAD_MAX_YAW = THREE.MathUtils.degToRad(20)
+export const HORSE_HEAD_TICK_SECONDS = 0.05
+
+const HORSE_HEAD_PART_NAMES = new Set([
+  'Head',
+  'UMouth',
+  'Ear1',
+  'Ear2',
+  'MuleEarL',
+  'MuleEarR',
+  'Neck',
+  'Mane',
+  'SaddleMouthL',
+  'SaddleMouthR',
+  'SaddleMouthLine',
+  'SaddleMouthLineR',
+  'HeadSaddle'
+])
+
+export type HorseHeadRig = THREE.Group & {
+  userData: THREE.Group['userData'] & { horseHeadParts: THREE.Object3D[] }
+}
+
+export const HORSE_HEAD_RIG_USER_DATA_KEY = '_horseHeadRig'
+export const HORSE_HEAD_ANIMATION_USER_DATA_KEY = '_horseHeadAnimation'
+
+/**
+ * Reparents every horse head-related OBJ object under the vanilla head_parts
+ * pivot while retaining each object's world transform.
+ */
+export function createHorseHeadRig(root: THREE.Object3D): HorseHeadRig {
+  const existing = root.userData[HORSE_HEAD_RIG_USER_DATA_KEY] as HorseHeadRig | undefined
+  if (existing) return existing
+
+  const parts: THREE.Object3D[] = []
+  root.traverse(child => {
+    if (child !== root && HORSE_HEAD_PART_NAMES.has(child.name)) parts.push(child)
+  })
+
+  const rig = new THREE.Group() as HorseHeadRig
+  rig.name = 'horse_head_rig'
+  rig.position.set(HORSE_HEAD_PIVOT.x, HORSE_HEAD_PIVOT.y, HORSE_HEAD_PIVOT.z)
+  rig.userData.horseHeadParts = parts
+  root.add(rig)
+
+  for (const part of parts) rig.attach(part)
+
+  root.userData[HORSE_HEAD_RIG_USER_DATA_KEY] = rig
+  return rig
+}
+
+export type HorseHeadPoseInput = {
+  entityPitch: number
+  headYaw: number
+  bodyYaw: number
+  limbSwing: number
+  limbSwingAmount: number
+}
+
+export type HorseHeadPose = {
+  pitch: number
+  yaw: number
+}
+
+export function normalizeYawDelta(fromYaw: number, toYaw: number): number {
+  const tau = Math.PI * 2
+  const delta = ((((toYaw - fromYaw + Math.PI) % tau) + tau) % tau) - Math.PI
+  return delta === -Math.PI ? Math.PI : delta
+}
+
+export function calculateHorseHeadPose(input: HorseHeadPoseInput): HorseHeadPose {
+  const { entityPitch, headYaw, bodyYaw, limbSwing, limbSwingAmount } = input
+  const safeAmount = Number.isFinite(limbSwingAmount) ? Math.max(0, limbSwingAmount) : 0
+  const gait = safeAmount > 0.2 ? Math.cos(limbSwing * 0.4) * 0.15 * safeAmount : 0
+  const relativeYaw = THREE.MathUtils.clamp(normalizeYawDelta(bodyYaw, headYaw), -HORSE_HEAD_MAX_YAW, HORSE_HEAD_MAX_YAW)
+  return {
+    pitch: (Number.isFinite(entityPitch) ? entityPitch : 0) - gait,
+    yaw: relativeYaw
+  }
+}
+
+export type HorseHeadAnimationState = {
+  lastPosition?: { x: number; z: number }
+  pendingPosition?: { x: number; z: number }
+  prevLimbSwing: number
+  limbSwing: number
+  prevLimbSwingAmount: number
+  limbSwingAmount: number
+  elapsedSeconds: number
+  tickAccumulatorSeconds: number
+}
+
+export function createHorseHeadAnimationState(): HorseHeadAnimationState {
+  return {
+    prevLimbSwing: 0,
+    limbSwing: 0,
+    prevLimbSwingAmount: 0,
+    limbSwingAmount: 0,
+    elapsedSeconds: HORSE_HEAD_TICK_SECONDS,
+    tickAccumulatorSeconds: 0
+  }
+}
+
+/** Save authoritative entity coordinates until the next animation tick. */
+export function setHorseHeadAnimationPosition(state: HorseHeadAnimationState, position: { x: number; z: number }): void {
+  state.pendingPosition = { x: position.x, z: position.z }
+}
+
+/** Advance using authoritative entity coordinates, before camera transforms. */
+export function advanceHorseHeadAnimation(state: HorseHeadAnimationState, position: { x: number; z: number }): void {
+  state.prevLimbSwing = state.limbSwing
+  state.prevLimbSwingAmount = state.limbSwingAmount
+
+  const distance = state.lastPosition == null ? 0 : Math.hypot(position.x - state.lastPosition.x, position.z - state.lastPosition.z)
+  const targetAmount = Math.min(1, distance * 4)
+  state.limbSwingAmount += (targetAmount - state.limbSwingAmount) * 0.4
+  state.limbSwing += state.limbSwingAmount
+  state.lastPosition = { x: position.x, z: position.z }
+}
+
+export function getInterpolatedHorseHeadAnimation(state: HorseHeadAnimationState, partialTick: number): { limbSwing: number; limbSwingAmount: number } {
+  const alpha = THREE.MathUtils.clamp(partialTick, 0, 1)
+  return {
+    limbSwing: state.prevLimbSwing + (state.limbSwing - state.prevLimbSwing) * alpha,
+    limbSwingAmount: state.prevLimbSwingAmount + (state.limbSwingAmount - state.prevLimbSwingAmount) * alpha
+  }
+}
+
+export function updateHorseHeadAnimationFrame(state: HorseHeadAnimationState, deltaSeconds: number): { limbSwing: number; limbSwingAmount: number } {
+  const safeDeltaSeconds = Math.max(0, deltaSeconds)
+  state.elapsedSeconds = Math.min(HORSE_HEAD_TICK_SECONDS, state.elapsedSeconds + safeDeltaSeconds)
+  state.tickAccumulatorSeconds += safeDeltaSeconds
+
+  while (state.tickAccumulatorSeconds >= HORSE_HEAD_TICK_SECONDS) {
+    const position = state.pendingPosition ?? state.lastPosition
+    if (position) advanceHorseHeadAnimation(state, position)
+    state.pendingPosition = undefined
+    state.tickAccumulatorSeconds -= HORSE_HEAD_TICK_SECONDS
+  }
+
+  state.elapsedSeconds = state.tickAccumulatorSeconds
+  return getInterpolatedHorseHeadAnimation(state, state.elapsedSeconds / HORSE_HEAD_TICK_SECONDS)
+}
+
+export function applyHorseHeadPose(rig: THREE.Object3D, pose: HorseHeadPose): void {
+  rig.rotation.set(pose.pitch, pose.yaw, 0)
+}

package/src/three/entity/horsePassengerRendering.test.ts

@@ -0,0 +1,77 @@
+//@ts-nocheck
+import * as THREE from 'three'
+import { expect, test } from 'vitest'
+import { SceneOrigin } from '../sceneOrigin'
+import { anchorVehiclePassengerPosition, releaseVehiclePassengerPosition } from './vehiclePassengerRendering'
+import { getHorsePassengerWorldPosition } from './interpolationPolicy'
+
+const LOCAL_PLAYER_ID = 7
+const REMOTE_PLAYER_ID = 8
+const HORSE_ID = '42'
+const HORSE_HEIGHT = 1.6
+
+type PassengerLike = THREE.Group & {
+  playerObject: Record<string, unknown>
+  originalEntity: { id: number }
+  userData: Record<string, unknown>
+}
+
+function makePassenger(id: number): PassengerLike {
+  const passenger = new THREE.Group() as PassengerLike
+  passenger.playerObject = {}
+  passenger.originalEntity = { id }
+  passenger.userData = {}
+  return passenger
+}
+
+test.each([
+  ['horse', 1.6, 0.85],
+  ['zombie_horse', 1.6, 0.85],
+  ['donkey', 1.5, 0.525],
+  ['mule', 1.6, 0.6],
+  ['skeleton_horse', 1.6, 0.6625]
+])('horse variant %s seat Y uses vanilla offset', (name, height, expectedFeetOffset) => {
+  const seat = getHorsePassengerWorldPosition({ x: 0, y: 64, z: 0 }, name, height)
+  expect(seat.y).toBeCloseTo(64 + expectedFeetOffset, 5)
+})
+
+test('local and remote horse passengers share the same anchor', () => {
+  const sceneOrigin = new SceneOrigin(new THREE.Scene())
+  sceneOrigin.update(96, 60, 192)
+
+  const horse = new THREE.Group()
+  sceneOrigin.track(horse)
+  horse.position.set(100, 64, 200)
+
+  const localPlayer = makePassenger(LOCAL_PLAYER_ID)
+  const remotePlayer = makePassenger(REMOTE_PLAYER_ID)
+  sceneOrigin.track(localPlayer)
+  sceneOrigin.track(remotePlayer)
+
+  const vehicleWorldPos = sceneOrigin.getWorldPosition(horse)!
+  const seatPosition = getHorsePassengerWorldPosition(vehicleWorldPos, 'horse', HORSE_HEIGHT)
+
+  anchorVehiclePassengerPosition(localPlayer, seatPosition, HORSE_ID)
+  anchorVehiclePassengerPosition(remotePlayer, seatPosition, HORSE_ID)
+
+  const localWorld = sceneOrigin.getWorldPosition(localPlayer)
+  const remoteWorld = sceneOrigin.getWorldPosition(remotePlayer)
+  expect(localWorld).toEqual(remoteWorld)
+})
+
+test('passenger anchor releases after detach', () => {
+  const sceneOrigin = new SceneOrigin(new THREE.Scene())
+  sceneOrigin.update(0, 0, 0)
+
+  const horse = new THREE.Group()
+  sceneOrigin.track(horse)
+  horse.position.set(0, 64, 0)
+
+  const passenger = makePassenger(LOCAL_PLAYER_ID)
+  sceneOrigin.track(passenger)
+
+  const seatPosition = getHorsePassengerWorldPosition({ x: 0, y: 64, z: 0 }, 'horse', HORSE_HEIGHT)
+  anchorVehiclePassengerPosition(passenger, seatPosition, HORSE_ID)
+  releaseVehiclePassengerPosition(passenger, HORSE_ID, sceneOrigin.getWorldPosition(passenger))
+  expect(passenger.userData._passengerVehicleId).toBeUndefined()
+})

package/src/three/entity/interpolationPolicy.test.ts

@@ -0,0 +1,281 @@
+//@ts-nocheck
+import { expect, test } from 'vitest'
+import {
+  ENTITY_TWEEN_DURATION_MS,
+  LOCAL_MOVEMENT_TWEEN_DURATION_MS,
+  SPECTATING_CAMERA_TWEEN_DURATION_MS,
+  getCameraMovementTweenDurationMs,
+  getEntityRotationTweenDurationMs,
+  getEntityTweenDurationMs,
+  getHorsePassengerWorldPosition,
+  getLocalVehicleWorldPosition,
+  getMinecartPassengerWorldPosition,
+  getVehiclePassengerFeetOffsetY,
+  resolveLocalVehicleWorldPosition,
+  samePosition,
+  shouldRestartCameraPositionTween,
+  usesCameraSyncedVehiclePosition
+} from './interpolationPolicy'
+
+test('local movement tween matches camera tween duration', () => {
+  expect(LOCAL_MOVEMENT_TWEEN_DURATION_MS).toBe(50)
+})
+
+test('ordinary entity tween stays at 120 ms', () => {
+  expect(ENTITY_TWEEN_DURATION_MS).toBe(120)
+})
+
+test('server-vehicle camera uses entity tween duration', () => {
+  expect(getCameraMovementTweenDurationMs('server-vehicle')).toBe(120)
+  expect(getCameraMovementTweenDurationMs('local-player')).toBe(50)
+  expect(getCameraMovementTweenDurationMs('spectating')).toBe(SPECTATING_CAMERA_TWEEN_DURATION_MS)
+})
+
+test('forced teleport camera update is instant', () => {
+  expect(getCameraMovementTweenDurationMs('server-vehicle', true)).toBe(0)
+  expect(getCameraMovementTweenDurationMs('local-player', true)).toBe(0)
+})
+
+test('same target does not restart camera tween', () => {
+  const target = { x: 1, y: 63.7, z: 2 }
+  expect(
+    shouldRestartCameraPositionTween({
+      target,
+      currentTarget: { ...target },
+      movementMode: 'server-vehicle',
+      previousMovementMode: 'server-vehicle',
+      instant: false
+    })
+  ).toBe(false)
+})
+
+test('dismount switches camera tween mode back to local-player', () => {
+  const target = { x: 1, y: 63.7, z: 2 }
+  expect(
+    shouldRestartCameraPositionTween({
+      target,
+      currentTarget: { ...target },
+      movementMode: 'local-player',
+      previousMovementMode: 'server-vehicle',
+      instant: false
+    })
+  ).toBe(true)
+  expect(getCameraMovementTweenDurationMs('local-player')).toBe(50)
+})
+
+test('sequential minecart targets restart tween only when position changes', () => {
+  const first = { x: 0, y: 63.7, z: 0 }
+  const second = { x: 1, y: 63.7, z: 0 }
+  expect(
+    shouldRestartCameraPositionTween({
+      target: first,
+      currentTarget: null,
+      movementMode: 'server-vehicle',
+      previousMovementMode: null,
+      instant: false
+    })
+  ).toBe(true)
+  expect(
+    shouldRestartCameraPositionTween({
+      target: first,
+      currentTarget: first,
+      movementMode: 'server-vehicle',
+      previousMovementMode: 'server-vehicle',
+      instant: false
+    })
+  ).toBe(false)
+  expect(
+    shouldRestartCameraPositionTween({
+      target: second,
+      currentTarget: first,
+      movementMode: 'server-vehicle',
+      previousMovementMode: 'server-vehicle',
+      instant: false
+    })
+  ).toBe(true)
+  expect(second.x).toBeGreaterThan(first.x)
+})
+
+test('samePosition uses epsilon comparison', () => {
+  expect(samePosition({ x: 1, y: 2, z: 3 }, { x: 1.00001, y: 2.00001, z: 3.00001 })).toBe(true)
+  expect(samePosition({ x: 1, y: 2, z: 3 }, { x: 1.01, y: 2, z: 3 })).toBe(false)
+})
+
+test('local vehicle skips position tween', () => {
+  expect(usesCameraSyncedVehiclePosition({ renderHints: { localVehicle: true } })).toBe(true)
+  expect(getEntityTweenDurationMs({ renderHints: { localVehicle: true } }, false)).toBe(0)
+  expect(getEntityTweenDurationMs({ renderHints: { localVehicle: true } }, true)).toBe(0)
+})
+
+test('local vehicle skips rotation tween while remote vehicles keep it', () => {
+  expect(getEntityRotationTweenDurationMs({ renderHints: { localVehicle: true } }, false)).toBe(0)
+  expect(getEntityRotationTweenDurationMs({ renderHints: { localVehicle: false } }, false)).toBe(ENTITY_TWEEN_DURATION_MS)
+  expect(getEntityRotationTweenDurationMs(undefined, true)).toBe(0)
+})
+
+test('locally ridden vehicle camera-sync policy stays separate from server-vehicle mode', () => {
+  expect(usesCameraSyncedVehiclePosition({ renderHints: { localVehicle: true } })).toBe(true)
+  expect(usesCameraSyncedVehiclePosition({ renderHints: { localVehicle: true, passengerLayout: 'minecart' } })).toBe(true)
+  expect(usesCameraSyncedVehiclePosition({ renderHints: { passengerLayout: 'minecart' } })).toBe(false)
+  expect(getCameraMovementTweenDurationMs('local-player')).toBe(50)
+})
+
+test('remote entities keep ordinary tween duration', () => {
+  expect(usesCameraSyncedVehiclePosition({ renderHints: { localVehicle: false } })).toBe(false)
+  expect(getEntityTweenDurationMs({ renderHints: { localVehicle: false } }, false)).toBe(120)
+  expect(getEntityTweenDurationMs({}, false)).toBe(120)
+  expect(getEntityTweenDurationMs(undefined, false)).toBe(120)
+})
+
+test('local vehicle world position uses camera X/Z and vehicle Y', () => {
+  const camera = { x: 10, y: 64.5, z: -3 }
+  expect(getLocalVehicleWorldPosition(camera, 63.2)).toEqual({
+    x: 10,
+    y: 63.2,
+    z: -3
+  })
+})
+
+test('intermediate camera frames keep boat X/Z aligned with player', () => {
+  const vehicleY = 63.2
+  const start = getLocalVehicleWorldPosition({ x: 0, y: 64, z: 0 }, vehicleY)
+  const mid = getLocalVehicleWorldPosition({ x: 0.5, y: 64, z: 0 }, vehicleY)
+  const end = getLocalVehicleWorldPosition({ x: 1, y: 64, z: 0 }, vehicleY)
+
+  expect(start.x).toBe(0)
+  expect(mid.x).toBe(0.5)
+  expect(end.x).toBe(1)
+  expect(start.z).toBe(mid.z)
+  expect(mid.z).toBe(end.z)
+  expect(start.y).toBe(vehicleY)
+  expect(mid.y).toBe(vehicleY)
+  expect(end.y).toBe(vehicleY)
+})
+
+test('horse vertical camera lock keeps constant offset from camera across tween progress', () => {
+  const eyeHeight = 1.62
+  const feetOffset = 0.85
+  const expectedGap = -(eyeHeight + feetOffset)
+  const rawVehicleY = 64
+  const cameraStartY = rawVehicleY + feetOffset + eyeHeight
+  const tweenProgress = [0, 0.25, 0.5, 0.75, 1]
+
+  for (const progress of tweenProgress) {
+    const cameraY = cameraStartY + progress * 0.8
+    const resolved = resolveLocalVehicleWorldPosition({
+      cameraWorldPos: { x: 1 + progress, y: cameraY, z: 2 },
+      rawVehicleY,
+      eyeHeight,
+      vehicleName: 'horse',
+      vehicleHeight: 1.6,
+      verticalCameraLock: 'horse'
+    })
+    expect(resolved.y - cameraY).toBeCloseTo(expectedGap, 5)
+    expect(resolved.x).toBe(1 + progress)
+    expect(resolved.z).toBe(2)
+  }
+})
+
+test('horse vertical camera lock uses vanilla feet offset value', () => {
+  const eyeHeight = 1.62
+  const cameraY = 66.47
+  const resolved = resolveLocalVehicleWorldPosition({
+    cameraWorldPos: { x: 0, y: cameraY, z: 0 },
+    rawVehicleY: 64,
+    eyeHeight,
+    vehicleName: 'horse',
+    vehicleHeight: 1.6,
+    verticalCameraLock: 'horse'
+  })
+  expect(resolved.y).toBeCloseTo(cameraY - 2.47, 5)
+})
+
+test('horse vertical camera lock is variant-aware for donkey and skeleton_horse', () => {
+  const eyeHeight = 1.62
+  const cameraY = 65
+
+  const donkey = resolveLocalVehicleWorldPosition({
+    cameraWorldPos: { x: 0, y: cameraY, z: 0 },
+    rawVehicleY: 64,
+    eyeHeight,
+    vehicleName: 'donkey',
+    vehicleHeight: 1.6,
+    verticalCameraLock: 'horse'
+  })
+  expect(donkey.y).toBeCloseTo(cameraY - eyeHeight - 0.6, 5)
+
+  const skeleton = resolveLocalVehicleWorldPosition({
+    cameraWorldPos: { x: 0, y: cameraY, z: 0 },
+    rawVehicleY: 64,
+    eyeHeight,
+    vehicleName: 'skeleton_horse',
+    vehicleHeight: 1.6,
+    verticalCameraLock: 'horse'
+  })
+  expect(skeleton.y).toBeCloseTo(cameraY - eyeHeight - 0.6625, 5)
+})
+
+test('without vertical camera lock resolver keeps raw vehicle Y', () => {
+  const camera = { x: 10, y: 64.5, z: -3 }
+  const rawVehicleY = 63.2
+  expect(
+    resolveLocalVehicleWorldPosition({
+      cameraWorldPos: camera,
+      rawVehicleY,
+      eyeHeight: 1.62,
+      vehicleName: 'horse',
+      vehicleHeight: 1.6
+    })
+  ).toEqual(getLocalVehicleWorldPosition(camera, rawVehicleY))
+})
+
+test('horse vertical camera lock falls back to raw Y when result is non-finite', () => {
+  const camera = { x: 1, y: 64, z: 2 }
+  const rawVehicleY = 63.5
+  expect(
+    resolveLocalVehicleWorldPosition({
+      cameraWorldPos: camera,
+      rawVehicleY,
+      eyeHeight: Number.NaN,
+      vehicleName: 'horse',
+      vehicleHeight: 1.6,
+      verticalCameraLock: 'horse'
+    })
+  ).toEqual(getLocalVehicleWorldPosition(camera, rawVehicleY))
+})
+
+test('minecart passenger feet Y is vehicleY - 0.35', () => {
+  expect(getMinecartPassengerWorldPosition({ x: 0, y: 64, z: 0 }, '1.17.1', 'minecart', 0.7).y).toBeCloseTo(63.65, 5)
+})
+
+test.each([
+  ['1.17.1', 'boat', -0.45],
+  ['1.20.1', 'boat', -0.45],
+  ['1.20.2', 'boat', -0.4125],
+  ['1.21.4', 'boat', -0.4125],
+  ['1.17.1', 'minecart', -0.35],
+  ['1.20.1', 'minecart', -0.35],
+  ['1.20.2', 'minecart', -0.4125],
+  ['1.21.4', 'minecart', -0.4125],
+  ['1.21.4', 'bamboo_raft', -0.1]
+])('vehicle %s %s seat offset matches vanilla', (version, vehicleName, expected) => {
+  const layout = vehicleName === 'minecart' ? 'minecart' : 'boat'
+  const height = layout === 'boat' ? 0.5625 : 0.7
+  expect(getVehiclePassengerFeetOffsetY(layout, version, vehicleName, height)).toBeCloseTo(expected, 5)
+})
+
+test('vehicle seat offset falls back to the default vehicle height', () => {
+  expect(getVehiclePassengerFeetOffsetY('boat', '1.20.2', 'oak_boat', undefined)).toBeCloseTo(-0.4125, 5)
+  expect(getVehiclePassengerFeetOffsetY('minecart', '1.20.2', 'minecart', undefined)).toBeCloseTo(-0.4125, 5)
+})
+
+test.each([
+  ['horse', 1.6, 0.85],
+  ['zombie_horse', 1.6, 0.85],
+  ['donkey', 1.5, 0.525],
+  ['mule', 1.6, 0.6],
+  ['skeleton_horse', 1.6, 0.6625]
+])('horse variant %s feet offset matches vanilla 1.17.1', (name, height, expectedFeetOffset) => {
+  const seat = getHorsePassengerWorldPosition({ x: 0, y: 64, z: 0 }, name, height)
+  expect(seat.y).toBeCloseTo(64 + expectedFeetOffset, 5)
+})