minecraft-renderer 0.1.93 → 0.1.95

package/src/three/entity/interpolationPolicy.ts

@@ -0,0 +1,242 @@
+//@ts-nocheck
+import { versionToNumber } from '../../lib/utils'
+
+export const LOCAL_MOVEMENT_TWEEN_DURATION_MS = 50
+export const ENTITY_TWEEN_DURATION_MS = 120
+export const SPECTATING_CAMERA_TWEEN_DURATION_MS = 150
+export const CAMERA_POSITION_EPSILON = 1e-4
+
+export type CameraMovementMode = 'local-player' | 'server-vehicle' | 'spectating'
+
+export type UpdateCameraOptions = {
+  movementMode?: CameraMovementMode
+  instant?: boolean
+}
+
+export type Vec3Like = { x: number; y: number; z: number }
+
+export type EntityRenderHints = {
+  localVehicle?: boolean
+  localVehicleVerticalCameraLock?: 'horse'
+  /** Render-only: lock locally controlled horse yaw to camera each frame. */
+  localVehicleYawLock?: 'horse'
+  boatWaterPatchVisible?: boolean
+  boatPaddleLeft?: boolean
+  boatPaddleRight?: boolean
+  passengerIds?: number[]
+  passengerLayout?: 'boat' | 'minecart' | 'horse'
+  /** @deprecated Use passengerIds */
+  boatPassengerIds?: number[]
+}
+
+export type EntityWithRenderHints = {
+  renderHints?: EntityRenderHints
+}
+
+export function usesCameraSyncedVehiclePosition(entity: EntityWithRenderHints | undefined): boolean {
+  return !!entity?.renderHints?.localVehicle
+}
+
+export function shouldApplyLocalHorseCameraYawLock(renderHints: EntityRenderHints | undefined): boolean {
+  return renderHints?.localVehicleYawLock === 'horse'
+}
+
+/** Visual-only: align local horse model yaw with camera before head pose and passengers. */
+export function applyLocalHorseCameraYawLock(sceneEntity: { rotation: { y: number }; userData: Record<string, unknown> }, cameraYaw: number): boolean {
+  if (!Number.isFinite(cameraYaw)) return false
+  sceneEntity.rotation.y = cameraYaw
+  sceneEntity.userData._horseBodyYaw = cameraYaw
+  sceneEntity.userData._horseHeadYaw = cameraYaw
+  return true
+}
+
+export function getEntityTweenDurationMs(entity: EntityWithRenderHints | undefined, justAdded: boolean): number {
+  if (justAdded) return 0
+  if (usesCameraSyncedVehiclePosition(entity)) return 0
+  return ENTITY_TWEEN_DURATION_MS
+}
+
+/** Rotation follows the same instant-vs-remote policy as entity position. */
+export function getEntityRotationTweenDurationMs(entity: EntityWithRenderHints | undefined, justAdded: boolean): number {
+  return getEntityTweenDurationMs(entity, justAdded)
+}
+
+export function samePosition(a: Vec3Like, b: Vec3Like, epsilon = CAMERA_POSITION_EPSILON): boolean {
+  return Math.abs(a.x - b.x) < epsilon && Math.abs(a.y - b.y) < epsilon && Math.abs(a.z - b.z) < epsilon
+}
+
+export function getCameraMovementTweenDurationMs(mode: CameraMovementMode, instant = false): number {
+  if (instant) return 0
+  switch (mode) {
+    case 'spectating':
+      return SPECTATING_CAMERA_TWEEN_DURATION_MS
+    case 'server-vehicle':
+      return ENTITY_TWEEN_DURATION_MS
+    case 'local-player':
+    default:
+      return LOCAL_MOVEMENT_TWEEN_DURATION_MS
+  }
+}
+
+export function shouldRestartCameraPositionTween(args: {
+  target: Vec3Like
+  currentTarget: Vec3Like | null
+  movementMode: CameraMovementMode
+  previousMovementMode: CameraMovementMode | null
+  instant: boolean
+}): boolean {
+  if (args.instant) return true
+  if (args.currentTarget == null) return true
+  if (args.movementMode !== args.previousMovementMode) return true
+  return !samePosition(args.target, args.currentTarget)
+}
+
+/** Locally ridden vehicle X/Z follow camera tween; Y uses latest server vehicle height. */
+export function getLocalVehicleWorldPosition(cameraWorldPos: Vec3Like, vehicleY: number): Vec3Like {
+  return {
+    x: cameraWorldPos.x,
+    y: vehicleY,
+    z: cameraWorldPos.z
+  }
+}
+
+export function resolveLocalVehicleWorldPosition(args: {
+  cameraWorldPos: Vec3Like
+  rawVehicleY: number
+  eyeHeight: number
+  vehicleName: string | undefined
+  vehicleHeight: number
+  verticalCameraLock?: 'horse'
+}): Vec3Like {
+  const { cameraWorldPos, rawVehicleY, eyeHeight, vehicleName, vehicleHeight, verticalCameraLock } = args
+  if (verticalCameraLock === 'horse') {
+    const y = cameraWorldPos.y - eyeHeight - getHorsePassengerFeetOffsetY(vehicleName, vehicleHeight)
+    if (Number.isFinite(y)) {
+      return { x: cameraWorldPos.x, y, z: cameraWorldPos.z }
+    }
+  }
+  return getLocalVehicleWorldPosition(cameraWorldPos, rawVehicleY)
+}
+
+const RIDEABLE_MINECART_ENTITY_NAMES = new Set([
+  'minecart',
+  'chest_minecart',
+  'furnace_minecart',
+  'hopper_minecart',
+  'tnt_minecart',
+  'spawner_minecart',
+  'command_block_minecart'
+])
+
+const RIDEABLE_HORSE_ENTITY_NAMES = new Set(['horse', 'donkey', 'mule', 'skeleton_horse', 'zombie_horse'])
+
+export function isRideableHorseEntityName(name?: string): boolean {
+  if (!name) return false
+  return RIDEABLE_HORSE_ENTITY_NAMES.has(name)
+}
+
+export function isRideableMinecartEntityName(name?: string): boolean {
+  if (!name) return false
+  return RIDEABLE_MINECART_ENTITY_NAMES.has(name)
+}
+
+export function getBoatPassengerSeatOffset(passengerIndex: number, passengerCount: number): number {
+  if (passengerCount <= 1) return 0
+  return passengerIndex === 0 ? 0.2 : -0.6
+}
+
+const DEFAULT_BOAT_HEIGHT = 0.5625
+const DEFAULT_MINECART_HEIGHT = 0.7
+
+// <= 1.20.1: Entity#positionRider = y + vehicle.getPassengersRidingOffset() + passenger.getMyRidingOffset()
+// Vanilla 1.17.1 sources: vehicle/Boat#getPassengersRidingOffset() = -0.1,
+// vehicle/AbstractMinecart#getPassengersRidingOffset() = 0, player/Player#getMyRidingOffset() = -0.35.
+const LEGACY_PLAYER_RIDING_OFFSET_Y = -0.35 // Player#getMyRidingOffset(), <= 1.20.1
+const LEGACY_BOAT_RIDING_OFFSET_Y = -0.1 // Boat#getPassengersRidingOffset(), <= 1.20.1
+const LEGACY_MINECART_RIDING_OFFSET_Y = 0 // AbstractMinecart#getPassengersRidingOffset(), <= 1.20.1
+
+// >= 1.20.2: y is based on the vehicle's PASSENGER attachment point.
+// The player's contribution is numerically the same, but the mechanism changed:
+//   1.20.2-1.20.4: PASSENGER.y + Player#ridingOffset() (-0.6)
+//   >= 1.20.5:     PASSENGER.y - Player.DEFAULT_VEHICLE_ATTACHMENT.y (0.6)
+// Vanilla sources: Entity#positionRider, Boat#getPassengerAttachmentPoint,
+// EntityType.*_MINECART#passengerAttachments and Player#ridingOffset / DEFAULT_VEHICLE_ATTACHMENT.
+const MODERN_PLAYER_RIDING_OFFSET_Y = -0.6
+const MODERN_MINECART_PASSENGER_ATTACHMENT_Y = 0.1875 // EntityType.*_MINECART.passengerAttachments()
+const MODERN_BOAT_RIDE_HEIGHT_FACTOR = 1 / 3 // (Abstract)Boat#rideHeight(), >= 1.20.2
+const MODERN_RAFT_RIDE_HEIGHT_FACTOR = 0.8888889 // Raft#rideHeight(), >= 1.21.2
+
+/**
+ * Vanilla seat offset for a player passenger in a boat or minecart.
+ * Rafts before 1.21.2 are intentionally treated as boats because their entity
+ * name is 'boat' and their metadata variant is not read by this project.
+ */
+export function getVehiclePassengerFeetOffsetY(
+  layout: 'boat' | 'minecart',
+  version: string,
+  vehicleName: string | undefined,
+  vehicleHeight: number | undefined
+): number {
+  const height = Number.isFinite(vehicleHeight) ? vehicleHeight! : layout === 'boat' ? DEFAULT_BOAT_HEIGHT : DEFAULT_MINECART_HEIGHT
+
+  if (versionToNumber(version) >= versionToNumber('1.20.2')) {
+    const isRaft = typeof vehicleName === 'string' && vehicleName.toLowerCase().endsWith('_raft')
+    const passengerAttachmentY =
+      layout === 'boat' ? height * (isRaft ? MODERN_RAFT_RIDE_HEIGHT_FACTOR : MODERN_BOAT_RIDE_HEIGHT_FACTOR) : MODERN_MINECART_PASSENGER_ATTACHMENT_Y
+    return passengerAttachmentY + MODERN_PLAYER_RIDING_OFFSET_Y
+  }
+
+  const vehicleRidingOffset = layout === 'boat' ? LEGACY_BOAT_RIDING_OFFSET_Y : LEGACY_MINECART_RIDING_OFFSET_Y
+  return vehicleRidingOffset + LEGACY_PLAYER_RIDING_OFFSET_Y
+}
+
+/** Vanilla Boat#positionRider position, without applying the passenger pose. */
+export function getBoatPassengerWorldPosition(
+  boatWorldPos: Vec3Like,
+  boatYaw: number,
+  passengerIndex: number,
+  passengerCount: number,
+  version: string,
+  vehicleName: string | undefined,
+  vehicleHeight: number | undefined
+): Vec3Like {
+  const seatOffset = getBoatPassengerSeatOffset(passengerIndex, passengerCount)
+  return {
+    x: boatWorldPos.x - Math.sin(boatYaw) * seatOffset,
+    y: boatWorldPos.y + getVehiclePassengerFeetOffsetY('boat', version, vehicleName, vehicleHeight),
+    z: boatWorldPos.z + Math.cos(boatYaw) * seatOffset
+  }
+}
+
+/** Vanilla minecart positionRider for a centered player passenger. */
+export function getMinecartPassengerWorldPosition(
+  minecartWorldPos: Vec3Like,
+  version: string,
+  vehicleName: string | undefined,
+  vehicleHeight: number | undefined
+): Vec3Like {
+  return {
+    x: minecartWorldPos.x,
+    y: minecartWorldPos.y + getVehiclePassengerFeetOffsetY('minecart', version, vehicleName, vehicleHeight),
+    z: minecartWorldPos.z
+  }
+}
+
+function getHorsePassengerFeetOffsetY(name: string | undefined, height: number): number {
+  let variantOffset = 0
+  if (name === 'donkey' || name === 'mule') {
+    variantOffset = 0.25
+  } else if (name === 'skeleton_horse') {
+    variantOffset = 0.1875
+  }
+  return height * 0.75 - variantOffset - 0.35
+}
+
+/** Vanilla 1.17.1 AbstractHorse positionRider feet Y for a centered player passenger. */
+export function getHorsePassengerWorldPosition(vehicleWorldPos: Vec3Like, name: string | undefined, height = 1.6): Vec3Like {
+  return {
+    x: vehicleWorldPos.x,
+    y: vehicleWorldPos.y + getHorsePassengerFeetOffsetY(name, height),
+    z: vehicleWorldPos.z
+  }
+}

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

@@ -0,0 +1,72 @@
+//@ts-nocheck
+import * as THREE from 'three'
+import { expect, test } from 'vitest'
+import { applyLocalHorseCameraYawLock, shouldApplyLocalHorseCameraYawLock, type EntityRenderHints } from './interpolationPolicy'
+
+function makeHorseSceneEntity(initialYaw = 0) {
+  const entity = new THREE.Group()
+  entity.rotation.y = initialYaw
+  entity.userData = {
+    _horseBodyYaw: initialYaw,
+    _horseHeadYaw: initialYaw
+  }
+  return entity
+}
+
+test('local controlled horse yaw equals camera yaw without entityMoved', () => {
+  const entity = makeHorseSceneEntity(1.2)
+  const cameraYaw = 2.5
+
+  expect(applyLocalHorseCameraYawLock(entity, cameraYaw)).toBe(true)
+  expect(entity.rotation.y).toBe(cameraYaw)
+  expect(entity.userData._horseBodyYaw).toBe(cameraYaw)
+  expect(entity.userData._horseHeadYaw).toBe(cameraYaw)
+})
+
+test('two sequential camera yaw changes immediately update the model', () => {
+  const entity = makeHorseSceneEntity(0)
+
+  applyLocalHorseCameraYawLock(entity, 1.0)
+  expect(entity.rotation.y).toBe(1.0)
+
+  applyLocalHorseCameraYawLock(entity, 1.5)
+  expect(entity.rotation.y).toBe(1.5)
+  expect(entity.userData._horseBodyYaw).toBe(1.5)
+  expect(entity.userData._horseHeadYaw).toBe(1.5)
+})
+
+test('wrap ±π assigns camera yaw directly without shortest-path adjustment', () => {
+  const entity = makeHorseSceneEntity(Math.PI - 0.01)
+  const cameraYaw = -Math.PI + 0.01
+
+  applyLocalHorseCameraYawLock(entity, cameraYaw)
+
+  expect(entity.rotation.y).toBeCloseTo(cameraYaw, 5)
+  expect(entity.userData._horseBodyYaw).toBeCloseTo(cameraYaw, 5)
+  expect(entity.userData._horseHeadYaw).toBeCloseTo(cameraYaw, 5)
+})
+
+test('non-finite camera yaw is ignored', () => {
+  const entity = makeHorseSceneEntity(1.25)
+
+  expect(applyLocalHorseCameraYawLock(entity, Number.NaN)).toBe(false)
+  expect(applyLocalHorseCameraYawLock(entity, Number.POSITIVE_INFINITY)).toBe(false)
+  expect(entity.rotation.y).toBe(1.25)
+  expect(entity.userData._horseBodyYaw).toBe(1.25)
+  expect(entity.userData._horseHeadYaw).toBe(1.25)
+})
+
+test('shouldApplyLocalHorseCameraYawLock is true only for local horse yaw lock hint', () => {
+  expect(shouldApplyLocalHorseCameraYawLock({ localVehicleYawLock: 'horse' })).toBe(true)
+  expect(shouldApplyLocalHorseCameraYawLock({ localVehicle: true, passengerLayout: 'horse' })).toBe(false)
+  expect(shouldApplyLocalHorseCameraYawLock({ localVehicle: true, localVehicleVerticalCameraLock: 'horse' })).toBe(false)
+  expect(shouldApplyLocalHorseCameraYawLock(undefined)).toBe(false)
+})
+
+test.each([
+  ['remote horse', { passengerLayout: 'horse' } satisfies EntityRenderHints],
+  ['local boat', { localVehicle: true, passengerLayout: 'boat' } satisfies EntityRenderHints],
+  ['local minecart', { localVehicle: true, passengerLayout: 'minecart' } satisfies EntityRenderHints]
+])('%s does not receive yaw lock', (_label, renderHints) => {
+  expect(shouldApplyLocalHorseCameraYawLock(renderHints)).toBe(false)
+})

package/src/three/entity/localVehicleRendering.integration.test.ts

@@ -0,0 +1,267 @@
+//@ts-nocheck
+import * as THREE from 'three'
+import { expect, test, vi } from 'vitest'
+import { SceneOrigin } from '../sceneOrigin'
+import { anchorVehiclePassengerPosition, releaseVehiclePassengerPosition } from './vehiclePassengerRendering'
+import {
+  ENTITY_TWEEN_DURATION_MS,
+  getBoatPassengerWorldPosition,
+  getEntityTweenDurationMs,
+  getLocalVehicleWorldPosition,
+  getMinecartPassengerWorldPosition,
+  usesCameraSyncedVehiclePosition
+} from './interpolationPolicy'
+
+type Vec3 = { x: number; y: number; z: number }
+
+const TEST_VERSION = '1.17.1'
+const BOAT_HEIGHT = 0.5625
+const MINECART_HEIGHT = 0.7
+
+function staleOffsetVehiclePosition(cameraWorldPos: Vec3, vehiclePosition: Vec3, stalePassengerPosition: Vec3): Vec3 {
+  return {
+    x: cameraWorldPos.x + (vehiclePosition.x - stalePassengerPosition.x),
+    y: cameraWorldPos.y + (vehiclePosition.y - stalePassengerPosition.y),
+    z: cameraWorldPos.z + (vehiclePosition.z - stalePassengerPosition.z)
+  }
+}
+
+test('stale passenger snapshot does not shift rendered locally ridden vehicle X/Z relative to camera', () => {
+  const stalePassenger = { x: 0, y: 63, z: 0 }
+  const newVehicle = { x: 1, y: 63.2, z: 2 }
+  const cameraWorldPos = { x: 0.4, y: 63.5, z: 0.8 }
+
+  // 1. Vehicle position updates before passenger sync.
+  // 2. Renderer receives vehicle snapshot while passenger is still stale.
+  const broken = staleOffsetVehiclePosition(cameraWorldPos, newVehicle, stalePassenger)
+  const rendered = getLocalVehicleWorldPosition(cameraWorldPos, newVehicle.y)
+
+  expect(rendered.x).toBe(cameraWorldPos.x)
+  expect(rendered.z).toBe(cameraWorldPos.z)
+  expect(rendered.y).toBe(newVehicle.y)
+  expect(broken.x).not.toBe(cameraWorldPos.x)
+  expect(broken.z).not.toBe(cameraWorldPos.z)
+
+  // 3. Passenger synchronizes to vehicle.
+  const syncedPassenger = { ...newVehicle, y: 63 }
+  const syncedCamera = { x: 0.8, y: 63.5, z: 1.6 }
+
+  // 4. Boat X/Z remain fixed relative to the player/camera on intermediate frames.
+  const afterSync = getLocalVehicleWorldPosition(syncedCamera, newVehicle.y)
+  expect(afterSync.x - syncedCamera.x).toBe(0)
+  expect(afterSync.z - syncedCamera.z).toBe(0)
+  expect(afterSync.y).toBe(newVehicle.y)
+  expect(syncedPassenger.x).toBe(newVehicle.x)
+  expect(syncedPassenger.z).toBe(newVehicle.z)
+})
+
+test('render frames between press and release keep zero horizontal delta to camera for local boat', () => {
+  const vehicleY = 62.75
+  const frames = [
+    { x: 0, y: 63.4, z: 0 },
+    { x: 0.2, y: 63.4, z: 0 },
+    { x: 0.45, y: 63.4, z: 0 },
+    { x: 0.7, y: 63.4, z: 0 },
+    { x: 0.7, y: 63.4, z: 0 },
+    { x: 0.55, y: 63.4, z: 0 }
+  ]
+
+  for (const camera of frames) {
+    const boat = getLocalVehicleWorldPosition(camera, vehicleY)
+    expect(boat.x - camera.x).toBe(0)
+    expect(boat.z - camera.z).toBe(0)
+    expect(boat.y).toBe(vehicleY)
+    expect(boat.y).not.toBe(camera.y)
+  }
+})
+
+test('boat passenger positions use vanilla 1.17.1 riding and seat offsets', () => {
+  const boat = { x: 10, y: 64, z: 20 }
+
+  expect(getBoatPassengerWorldPosition(boat, 0, 0, 1, TEST_VERSION, 'oak_boat', BOAT_HEIGHT)).toEqual({
+    x: 10,
+    y: 63.55,
+    z: 20
+  })
+  expect(getBoatPassengerWorldPosition(boat, 0, 0, 2, TEST_VERSION, 'oak_boat', BOAT_HEIGHT)).toEqual({
+    x: 10,
+    y: 63.55,
+    z: 20.2
+  })
+  expect(getBoatPassengerWorldPosition(boat, 0, 1, 2, TEST_VERSION, 'oak_boat', BOAT_HEIGHT)).toEqual({
+    x: 10,
+    y: 63.55,
+    z: 19.4
+  })
+
+  const rotated = getBoatPassengerWorldPosition(boat, Math.PI / 2, 0, 2, TEST_VERSION, 'oak_boat', BOAT_HEIGHT)
+  expect(rotated.x).toBeCloseTo(9.8)
+  expect(rotated.y).toBe(63.55)
+  expect(rotated.z).toBeCloseTo(20)
+})
+
+test('remote player follows the tracked boat each frame and releases from an empty passenger list', () => {
+  const sceneOrigin = new SceneOrigin(new THREE.Scene())
+  sceneOrigin.update(96, 60, 192)
+
+  const boat = new THREE.Group()
+  sceneOrigin.track(boat)
+  boat.position.set(100, 64, 200)
+
+  const passenger = new THREE.Group()
+  const stopPositionTween = vi.fn()
+  passenger.userData._posTween = { stop: stopPositionTween }
+  sceneOrigin.track(passenger)
+  passenger.position.set(90, 64, 190)
+
+  const firstPassengerPosition = getBoatPassengerWorldPosition(
+    sceneOrigin.getWorldPosition(boat)!,
+    boat.rotation.y,
+    0,
+    1,
+    TEST_VERSION,
+    'oak_boat',
+    BOAT_HEIGHT
+  )
+  anchorVehiclePassengerPosition(passenger, firstPassengerPosition, '10')
+
+  expect(stopPositionTween).toHaveBeenCalledOnce()
+  expect(sceneOrigin.getWorldPosition(passenger)).toEqual({ x: 100, y: 63.55, z: 200 })
+  expect(passenger.userData._tweenTarget).toEqual({ x: 100, y: 63.55, z: 200 })
+
+  boat.position.set(102, 64.2, 203)
+  boat.rotation.y = Math.PI / 2
+  const movedPassengerPosition = getBoatPassengerWorldPosition(
+    sceneOrigin.getWorldPosition(boat)!,
+    boat.rotation.y,
+    0,
+    1,
+    TEST_VERSION,
+    'oak_boat',
+    BOAT_HEIGHT
+  )
+  anchorVehiclePassengerPosition(passenger, movedPassengerPosition, '10')
+  expect(sceneOrigin.getWorldPosition(passenger)?.x).toBe(102)
+  expect(sceneOrigin.getWorldPosition(passenger)?.y).toBeCloseTo(63.75)
+  expect(sceneOrigin.getWorldPosition(passenger)?.z).toBe(203)
+
+  sceneOrigin.update(112, 70, 208)
+  expect(sceneOrigin.getWorldPosition(passenger)?.x).toBe(102)
+  expect(sceneOrigin.getWorldPosition(passenger)?.y).toBeCloseTo(63.75)
+  expect(sceneOrigin.getWorldPosition(passenger)?.z).toBe(203)
+
+  const detachedWorldPosition = sceneOrigin.getWorldPosition(passenger)
+  expect(releaseVehiclePassengerPosition(passenger, '10', detachedWorldPosition)).toBe(true)
+  expect(passenger.userData._passengerVehicleId).toBeUndefined()
+  expect(passenger.userData._boatPassengerVehicleId).toBeUndefined()
+  expect(passenger.userData._tweenTarget).toEqual(detachedWorldPosition)
+
+  boat.position.set(110, 65, 210)
+  expect(sceneOrigin.getWorldPosition(passenger)).toEqual(detachedWorldPosition)
+})
+
+test('minecart passenger uses vanilla 1.17.1 riding Y offset', () => {
+  const minecart = { x: 10, y: 64, z: 20 }
+  expect(getMinecartPassengerWorldPosition(minecart, TEST_VERSION, 'minecart', MINECART_HEIGHT)).toEqual({
+    x: 10,
+    y: 63.65,
+    z: 20
+  })
+})
+
+test('minecart passenger anchor follows vehicle world position without inheriting vehicle yaw', () => {
+  const sceneOrigin = new SceneOrigin(new THREE.Scene())
+  sceneOrigin.update(96, 60, 192)
+
+  const minecart = new THREE.Group()
+  sceneOrigin.track(minecart)
+  minecart.position.set(100, 64, 200)
+  minecart.rotation.y = Math.PI / 2
+
+  const passenger = new THREE.Group()
+  passenger.rotation.y = 1.25
+  sceneOrigin.track(passenger)
+  passenger.position.set(90, 64, 190)
+
+  const firstPosition = getMinecartPassengerWorldPosition(sceneOrigin.getWorldPosition(minecart)!, TEST_VERSION, 'minecart', MINECART_HEIGHT)
+  anchorVehiclePassengerPosition(passenger, firstPosition, '42')
+  const anchoredYaw = passenger.rotation.y
+
+  minecart.position.set(103, 64.5, 205)
+  minecart.rotation.y = Math.PI
+  const movedPosition = getMinecartPassengerWorldPosition(sceneOrigin.getWorldPosition(minecart)!, TEST_VERSION, 'minecart', MINECART_HEIGHT)
+  anchorVehiclePassengerPosition(passenger, movedPosition, '42')
+
+  expect(sceneOrigin.getWorldPosition(passenger)).toEqual({
+    x: 103,
+    y: 64.15,
+    z: 205
+  })
+  expect(passenger.rotation.y).toBe(anchoredYaw)
+
+  const detachedWorldPosition = sceneOrigin.getWorldPosition(passenger)
+  expect(releaseVehiclePassengerPosition(passenger, '42', detachedWorldPosition)).toBe(true)
+  expect(sceneOrigin.getWorldPosition(passenger)).toEqual(detachedWorldPosition)
+
+  minecart.position.set(120, 66, 220)
+  expect(sceneOrigin.getWorldPosition(passenger)).toEqual(detachedWorldPosition)
+})
+
+test('local minecart with localVehicle uses camera-synced positioning', () => {
+  expect(usesCameraSyncedVehiclePosition({ renderHints: { localVehicle: true, passengerLayout: 'minecart' } })).toBe(true)
+  expect(getEntityTweenDurationMs({ renderHints: { localVehicle: true, passengerLayout: 'minecart' } }, false)).toBe(0)
+})
+
+test('remote minecart keeps ordinary entity interpolation', () => {
+  expect(usesCameraSyncedVehiclePosition({ renderHints: { passengerLayout: 'minecart' } })).toBe(false)
+  expect(getEntityTweenDurationMs({ renderHints: { passengerLayout: 'minecart' } }, false)).toBe(ENTITY_TWEEN_DURATION_MS)
+})
+
+test('local minecart X/Z stay aligned with camera on intermediate frames between server targets', () => {
+  const vehicleY = 63.7
+  const cameraFrames = [
+    { x: 0, y: 64.3, z: 0 },
+    { x: 1.2, y: 64.3, z: 0.6 },
+    { x: 5, y: 64.3, z: 3 },
+    { x: 4.1, y: 64.3, z: 2.5 }
+  ]
+
+  for (const camera of cameraFrames) {
+    const minecart = getLocalVehicleWorldPosition(camera, vehicleY)
+    expect(minecart.x - camera.x).toBeCloseTo(0, 5)
+    expect(minecart.z - camera.z).toBeCloseTo(0, 5)
+    expect(minecart.y).toBe(vehicleY)
+  }
+})
+
+test('local minecart passenger anchors to camera-synced vehicle position', () => {
+  const sceneOrigin = new SceneOrigin(new THREE.Scene())
+  sceneOrigin.update(96, 60, 192)
+
+  const minecart = new THREE.Group()
+  sceneOrigin.track(minecart)
+
+  const passenger = new THREE.Group()
+  sceneOrigin.track(passenger)
+
+  const vehicleY = 64
+  const cameraFrames = [
+    { x: 100, y: 64.7, z: 200 },
+    { x: 101.4, y: 64.7, z: 200.8 },
+    { x: 103, y: 64.7, z: 202 }
+  ]
+
+  for (const camera of cameraFrames) {
+    const syncedMinecart = getLocalVehicleWorldPosition(camera, vehicleY)
+    minecart.position.set(syncedMinecart.x, syncedMinecart.y, syncedMinecart.z)
+    const seatPosition = getMinecartPassengerWorldPosition(syncedMinecart, TEST_VERSION, 'minecart', MINECART_HEIGHT)
+    anchorVehiclePassengerPosition(passenger, seatPosition, '42')
+    const passengerWorld = sceneOrigin.getWorldPosition(passenger)!
+
+    expect(syncedMinecart.x - camera.x).toBeCloseTo(0, 5)
+    expect(syncedMinecart.z - camera.z).toBeCloseTo(0, 5)
+    expect(passengerWorld.x).toBe(syncedMinecart.x)
+    expect(passengerWorld.z).toBe(syncedMinecart.z)
+    expect(passengerWorld.y).toBeCloseTo(63.65)
+  }
+})