minecraft-renderer 0.1.92 → 0.1.94

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

@@ -0,0 +1,259 @@
+//@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,
+  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 }).y).toBeCloseTo(63.65, 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)
+})

package/src/three/entity/interpolationPolicy.ts

@@ -0,0 +1,187 @@
+//@ts-nocheck
+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 BOAT_PASSENGER_RIDING_OFFSET_Y = -0.1
+const PLAYER_RIDING_OFFSET_Y = -0.35
+/** Vanilla 1.17.1 AbstractMinecart#getPassengersRidingOffset() */
+const MINECART_PASSENGER_RIDING_OFFSET_Y = 0
+
+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
+}
+
+/** Vanilla 1.17.1 Boat#positionRider position, without applying the passenger pose. */
+export function getBoatPassengerWorldPosition(boatWorldPos: Vec3Like, boatYaw: number, passengerIndex: number, passengerCount: number): Vec3Like {
+  const seatOffset = getBoatPassengerSeatOffset(passengerIndex, passengerCount)
+  return {
+    x: boatWorldPos.x - Math.sin(boatYaw) * seatOffset,
+    y: boatWorldPos.y + BOAT_PASSENGER_RIDING_OFFSET_Y + PLAYER_RIDING_OFFSET_Y,
+    z: boatWorldPos.z + Math.cos(boatYaw) * seatOffset
+  }
+}
+
+/** Vanilla 1.17.1 minecart positionRider for a centered player passenger. */
+export function getMinecartPassengerWorldPosition(minecartWorldPos: Vec3Like): Vec3Like {
+  return {
+    x: minecartWorldPos.x,
+    y: minecartWorldPos.y + MINECART_PASSENGER_RIDING_OFFSET_Y + PLAYER_RIDING_OFFSET_Y,
+    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)
+})