minecraft-renderer 0.1.92 → 0.1.94

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

@@ -0,0 +1,247 @@
+//@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 }
+
+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)).toEqual({
+    x: 10,
+    y: 63.55,
+    z: 20
+  })
+  expect(getBoatPassengerWorldPosition(boat, 0, 0, 2)).toEqual({
+    x: 10,
+    y: 63.55,
+    z: 20.2
+  })
+  expect(getBoatPassengerWorldPosition(boat, 0, 1, 2)).toEqual({
+    x: 10,
+    y: 63.55,
+    z: 19.4
+  })
+
+  const rotated = getBoatPassengerWorldPosition(boat, Math.PI / 2, 0, 2)
+  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)
+  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)
+  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)).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)!)
+  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)!)
+  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)
+    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)
+  }
+})

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

@@ -0,0 +1,208 @@
+//@ts-nocheck
+import * as THREE from 'three'
+import { expect, test } from 'vitest'
+import { SceneOrigin } from '../sceneOrigin'
+import { anchorVehiclePassengerPosition, releaseVehiclePassengerPosition } from './vehiclePassengerRendering'
+import { getBoatPassengerWorldPosition, getMinecartPassengerWorldPosition } from './interpolationPolicy'
+
+const LOCAL_PLAYER_ID = 7
+const REMOTE_PLAYER_ID = 8
+const MINECART_ID = '42'
+const EYE_HEIGHT = 1.62
+const PLAYER_HEIGHT = 1.8
+
+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
+}
+
+function resolveMinecartPassenger(
+  passengerId: number,
+  localPlayer: PassengerLike | null,
+  remotePlayers: Record<number, PassengerLike>
+): PassengerLike | undefined {
+  const isLocalPassenger = passengerId === localPlayer?.originalEntity.id
+  return isLocalPassenger ? (localPlayer ?? undefined) : remotePlayers[passengerId]
+}
+
+function anchorMinecartPassengers(
+  minecart: THREE.Group,
+  sceneOrigin: SceneOrigin,
+  passengerIds: number[],
+  localPlayer: PassengerLike | null,
+  remotePlayers: Record<number, PassengerLike>
+) {
+  const vehicleWorldPos = sceneOrigin.getWorldPosition(minecart)!
+  const seatPosition = getMinecartPassengerWorldPosition(vehicleWorldPos)
+  for (const passengerId of passengerIds) {
+    const passenger = resolveMinecartPassenger(passengerId, localPlayer, remotePlayers)
+    if (!passenger?.playerObject) continue
+    anchorVehiclePassengerPosition(passenger, seatPosition, MINECART_ID)
+  }
+  return seatPosition
+}
+
+test('local and remote minecart passengers share the same seat Y', () => {
+  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)
+
+  const localPlayer = makePassenger(LOCAL_PLAYER_ID)
+  const remotePlayer = makePassenger(REMOTE_PLAYER_ID)
+  sceneOrigin.track(localPlayer)
+  sceneOrigin.track(remotePlayer)
+
+  const seatPosition = anchorMinecartPassengers(minecart, sceneOrigin, [LOCAL_PLAYER_ID, REMOTE_PLAYER_ID], localPlayer, { [REMOTE_PLAYER_ID]: remotePlayer })
+
+  const localWorld = sceneOrigin.getWorldPosition(localPlayer)
+  const remoteWorld = sceneOrigin.getWorldPosition(remotePlayer)
+  expect(localWorld?.y).toBe(seatPosition.y)
+  expect(remoteWorld?.y).toBe(seatPosition.y)
+  expect(localWorld).toEqual(remoteWorld)
+})
+
+test('local third-person player follows interpolated minecart world position', () => {
+  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)
+
+  const localPlayer = makePassenger(LOCAL_PLAYER_ID)
+  sceneOrigin.track(localPlayer)
+
+  anchorMinecartPassengers(minecart, sceneOrigin, [LOCAL_PLAYER_ID], localPlayer, {})
+
+  minecart.position.set(103, 64.5, 205)
+  sceneOrigin.update(112, 70, 208)
+  const movedSeat = anchorMinecartPassengers(minecart, sceneOrigin, [LOCAL_PLAYER_ID], localPlayer, {})
+
+  expect(sceneOrigin.getWorldPosition(localPlayer)).toEqual(movedSeat)
+  expect(movedSeat.x).toBe(103)
+  expect(movedSeat.y).toBeCloseTo(64.15)
+})
+
+test('minecart seat places player waist-up inside the cart instead of on camera feet', () => {
+  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)
+
+  const localPlayer = makePassenger(LOCAL_PLAYER_ID)
+  sceneOrigin.track(localPlayer)
+
+  const cameraWorldPos = { x: 100, y: 64 + 0.7 + EYE_HEIGHT, z: 200 }
+  localPlayer.position.set(cameraWorldPos.x, cameraWorldPos.y - EYE_HEIGHT, cameraWorldPos.z)
+
+  const seatPosition = anchorMinecartPassengers(minecart, sceneOrigin, [LOCAL_PLAYER_ID], localPlayer, {})
+  const anchoredWorld = sceneOrigin.getWorldPosition(localPlayer)!
+
+  const minecartWorld = sceneOrigin.getWorldPosition(minecart)!
+  const cameraFeetY = cameraWorldPos.y - EYE_HEIGHT
+
+  expect(anchoredWorld.y).toBeLessThan(cameraFeetY)
+  expect(anchoredWorld.y).toBe(seatPosition.y)
+  const waistY = anchoredWorld.y + PLAYER_HEIGHT * 0.5
+  expect(waistY).toBeGreaterThan(minecartWorld.y)
+  expect(waistY).toBeGreaterThan(minecartWorld.y + 0.3)
+  expect(waistY).toBeLessThan(minecartWorld.y + 0.85)
+})
+
+test('first and third person keep the same minecart passenger anchor', () => {
+  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)
+
+  const localPlayer = makePassenger(LOCAL_PLAYER_ID)
+  sceneOrigin.track(localPlayer)
+
+  anchorMinecartPassengers(minecart, sceneOrigin, [LOCAL_PLAYER_ID], localPlayer, {})
+  const thirdPersonAnchor = { ...sceneOrigin.getWorldPosition(localPlayer)! }
+
+  localPlayer.visible = false
+  anchorMinecartPassengers(minecart, sceneOrigin, [LOCAL_PLAYER_ID], localPlayer, {})
+
+  expect(sceneOrigin.getWorldPosition(localPlayer)).toEqual(thirdPersonAnchor)
+  expect(localPlayer.userData._passengerVehicleId).toBe(MINECART_ID)
+})
+
+test('minecart dismount releases local player anchor without snapping back', () => {
+  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)
+
+  const localPlayer = makePassenger(LOCAL_PLAYER_ID)
+  sceneOrigin.track(localPlayer)
+
+  anchorMinecartPassengers(minecart, sceneOrigin, [LOCAL_PLAYER_ID], localPlayer, {})
+  minecart.position.set(105, 65, 210)
+  sceneOrigin.update(112, 70, 208)
+  anchorMinecartPassengers(minecart, sceneOrigin, [LOCAL_PLAYER_ID], localPlayer, {})
+
+  const detachedWorldPosition = sceneOrigin.getWorldPosition(localPlayer)
+  expect(releaseVehiclePassengerPosition(localPlayer, MINECART_ID, detachedWorldPosition)).toBe(true)
+  expect(localPlayer.userData._passengerVehicleId).toBeUndefined()
+  expect(sceneOrigin.getWorldPosition(localPlayer)).toEqual(detachedWorldPosition)
+
+  minecart.position.set(120, 66, 220)
+  sceneOrigin.update(128, 76, 228)
+  expect(sceneOrigin.getWorldPosition(localPlayer)).toEqual(detachedWorldPosition)
+})
+
+function shouldAnchorPassenger(passenger: PassengerLike | null | undefined, layout: 'boat' | 'minecart' | 'horse', isLocalPassenger: boolean): boolean {
+  if (!passenger?.playerObject) return false
+  if (isLocalPassenger && layout === 'horse') return false
+  return true
+}
+
+test('local player is anchored for boat and minecart but skipped for horse', () => {
+  const localPlayer = makePassenger(LOCAL_PLAYER_ID)
+  expect(shouldAnchorPassenger(localPlayer, 'boat', true)).toBe(true)
+  expect(shouldAnchorPassenger(localPlayer, 'minecart', true)).toBe(true)
+  expect(shouldAnchorPassenger(localPlayer, 'horse', true)).toBe(false)
+})
+
+test('local boat passenger uses the same anchor as remote passenger', () => {
+  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 localPlayer = makePassenger(LOCAL_PLAYER_ID)
+  const remotePlayer = makePassenger(REMOTE_PLAYER_ID)
+  sceneOrigin.track(localPlayer)
+  sceneOrigin.track(remotePlayer)
+
+  const boatSeat = getBoatPassengerWorldPosition(sceneOrigin.getWorldPosition(boat)!, boat.rotation.y, 0, 1)
+  if (shouldAnchorPassenger(localPlayer, 'boat', true)) {
+    anchorVehiclePassengerPosition(localPlayer, boatSeat, '10')
+  }
+  anchorVehiclePassengerPosition(remotePlayer, boatSeat, '10')
+
+  expect(localPlayer.userData._passengerVehicleId).toBe('10')
+  expect(sceneOrigin.getWorldPosition(localPlayer)).toEqual(sceneOrigin.getWorldPosition(remotePlayer))
+  expect(sceneOrigin.getWorldPosition(localPlayer)?.y).toBeCloseTo(63.55)
+})

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

@@ -0,0 +1,102 @@
+//@ts-nocheck
+import * as THREE from 'three'
+import { PlayerObject } from 'skinview3d'
+import { expect, test } from 'vitest'
+import type { PlayerObjectType } from '../../lib/createPlayerObject'
+import { WalkingGeneralSwing } from './animations'
+import { anchorVehiclePassengerPosition } from './vehiclePassengerRendering'
+import { applyNetworkHeadPitch, storeNetworkHeadPitch, storeNetworkHeadYaw, type NetworkHeadRotationState } from './networkHeadPitchRendering'
+import { getMinecartPassengerWorldPosition } from './interpolationPolicy'
+
+function makePlayerObject(): PlayerObjectType {
+  const playerObject = new PlayerObject() as PlayerObjectType
+  playerObject.skin.head.rotation.set(0, 0, 0)
+  return playerObject
+}
+
+function simulateAnimationFrames(playerObject: PlayerObjectType, userData: NetworkHeadRotationState, frames: number, dt = 0.05) {
+  const animation = new WalkingGeneralSwing()
+  animation._captureDefaults(playerObject)
+  for (let i = 0; i < frames; i++) {
+    animation.update(playerObject, dt)
+    applyNetworkHeadPitch(playerObject, userData)
+  }
+}
+
+test('remote head pitch persists across animation frames', () => {
+  const playerObject = makePlayerObject()
+  const userData: NetworkHeadRotationState = {}
+  storeNetworkHeadPitch(userData, 0.6)
+
+  simulateAnimationFrames(playerObject, userData, 5)
+
+  expect(playerObject.skin.head.rotation.x).toBeCloseTo(-0.6)
+  expect(playerObject.skin.head.rotation.y).toBe(0)
+})
+
+test('remote head pitch updates when network pitch changes', () => {
+  const playerObject = makePlayerObject()
+  const userData: NetworkHeadRotationState = {}
+  storeNetworkHeadPitch(userData, 0.4)
+  simulateAnimationFrames(playerObject, userData, 2)
+  expect(playerObject.skin.head.rotation.x).toBeCloseTo(-0.4)
+
+  storeNetworkHeadPitch(userData, -0.2)
+  simulateAnimationFrames(playerObject, userData, 2)
+  expect(playerObject.skin.head.rotation.x).toBeCloseTo(0.2)
+})
+
+test('remote head pitch supports looking straight ahead', () => {
+  const playerObject = makePlayerObject()
+  const userData: NetworkHeadRotationState = {}
+  storeNetworkHeadPitch(userData, 0)
+  simulateAnimationFrames(playerObject, userData, 3)
+  expect(playerObject.skin.head.rotation.x).toBeCloseTo(0)
+})
+
+test('local player keeps camera pitch authoritative', () => {
+  const playerObject = makePlayerObject()
+  const userData: NetworkHeadRotationState = {}
+  storeNetworkHeadPitch(userData, 0.8)
+
+  const cameraPitch = -0.35
+  playerObject.skin.head.rotation.x = -cameraPitch
+
+  expect(playerObject.skin.head.rotation.x).toBeCloseTo(0.35)
+})
+
+test('minecart passenger anchor preserves head rotation', () => {
+  const playerObject = makePlayerObject()
+  const userData: NetworkHeadRotationState = {}
+  const passenger = new THREE.Group()
+  passenger.userData = userData
+
+  storeNetworkHeadPitch(userData, 0.45)
+  applyNetworkHeadPitch(playerObject, userData)
+
+  const seat = getMinecartPassengerWorldPosition({ x: 10, y: 64, z: 20 })
+  anchorVehiclePassengerPosition(passenger, seat, '42')
+  simulateAnimationFrames(playerObject, userData, 4)
+
+  expect(passenger.position.x).toBe(10)
+  expect(passenger.position.y).toBeCloseTo(63.65)
+  expect(playerObject.skin.head.rotation.x).toBeCloseTo(-0.45)
+})
+
+test('storeNetworkHeadYaw keeps last finite head yaw and ignores invalid updates', () => {
+  const userData: NetworkHeadRotationState = {}
+  storeNetworkHeadYaw(userData, 1.2)
+  expect(userData._networkHeadYaw).toBeCloseTo(1.2)
+
+  storeNetworkHeadYaw(userData, Number.NaN, undefined)
+  expect(userData._networkHeadYaw).toBeCloseTo(1.2)
+
+  storeNetworkHeadYaw(userData, undefined, 0.8)
+  expect(userData._networkHeadYaw).toBeCloseTo(0.8)
+})
+
+test('storeNetworkHeadYaw prefers explicit head yaw over fallback', () => {
+  const userData: NetworkHeadRotationState = {}
+  storeNetworkHeadYaw(userData, 0.5, 1.5)
+  expect(userData._networkHeadYaw).toBeCloseTo(0.5)
+})

package/src/three/entity/networkHeadPitchRendering.ts

@@ -0,0 +1,44 @@
+//@ts-nocheck
+import type { PlayerObjectType } from '../../lib/createPlayerObject'
+
+export type NetworkHeadRotationState = {
+  _networkHeadPitch?: number
+  _networkHeadYaw?: number
+  _remoteBoatRotationApplied?: boolean
+}
+
+/** @deprecated Use NetworkHeadRotationState */
+export type NetworkHeadPitchState = NetworkHeadRotationState
+
+export function storeNetworkHeadPitch(userData: NetworkHeadRotationState, pitch: unknown): void {
+  if (typeof pitch === 'number' && Number.isFinite(pitch)) {
+    userData._networkHeadPitch = pitch
+  }
+}
+
+export function storeNetworkHeadYaw(userData: NetworkHeadRotationState, headYaw: unknown, fallbackYaw?: unknown): void {
+  if (typeof headYaw === 'number' && Number.isFinite(headYaw)) {
+    userData._networkHeadYaw = headYaw
+    return
+  }
+  if (typeof fallbackYaw === 'number' && Number.isFinite(fallbackYaw)) {
+    userData._networkHeadYaw = fallbackYaw
+  }
+}
+
+export function getNetworkHeadPitch(userData: NetworkHeadRotationState): number {
+  const pitch = userData._networkHeadPitch
+  return typeof pitch === 'number' && Number.isFinite(pitch) ? pitch : 0
+}
+
+export function applyNetworkHeadPitch(playerObject: PlayerObjectType, userData: NetworkHeadRotationState): void {
+  const pitch = userData._networkHeadPitch
+  if (typeof pitch !== 'number' || !Number.isFinite(pitch)) return
+  playerObject.skin.head.rotation.y = 0
+  playerObject.skin.head.rotation.x = -pitch
+}
+
+export function restoreGenericRemotePlayerHeadRotation(playerObject: PlayerObjectType, userData: NetworkHeadRotationState): void {
+  playerObject.skin.head.rotation.y = 0
+  applyNetworkHeadPitch(playerObject, userData)
+}