minecraft-renderer 0.1.93 → 0.1.95

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

@@ -0,0 +1,210 @@
+//@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
+const TEST_VERSION = '1.17.1'
+const MINECART_HEIGHT = 0.7
+
+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, TEST_VERSION, 'minecart', MINECART_HEIGHT)
+  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, TEST_VERSION, 'oak_boat', 0.5625)
+  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 }, '1.17.1', 'minecart', 0.7)
+  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)
+}

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

@@ -0,0 +1,229 @@
+//@ts-nocheck
+import * as THREE from 'three'
+import { PlayerObject } from 'skinview3d'
+import { expect, test } from 'vitest'
+import type { PlayerObjectType } from '../../lib/createPlayerObject'
+import { BOAT_PASSENGER_MAX_HEAD_YAW_RAD, clampBoatPassengerRelativeHeadYaw, normalizeYawDelta } from './boatPassengerRotation'
+import { storeNetworkHeadPitch, storeNetworkHeadYaw } from './networkHeadPitchRendering'
+import {
+  applyRemoteBoatPassengerRotation,
+  processRemoteBoatPassengerRotation,
+  processRemoteBoatPassengerRotations,
+  restoreGenericRemotePassengerRotation,
+  type RemoteBoatPassengerEntity,
+  type RemoteBoatPassengerVehicle
+} from './remoteBoatPassengerRotation'
+import { anchorVehiclePassengerPosition } from './vehiclePassengerRendering'
+import { updateVehiclePassengerPositions } from './vehiclePassengerUpdate'
+import { SceneOrigin } from '../sceneOrigin'
+
+const BOAT_YAW = -0.5645049299419149
+const REMOTE_PLAYER_A = 8
+const REMOTE_PLAYER_B = 9
+const BOAT_ID = 10
+const TEST_VERSION = '1.17.1'
+
+function makePlayerObject(): PlayerObjectType {
+  return new PlayerObject() as PlayerObjectType
+}
+
+function makeRemotePassenger(id: number, lookYaw = BOAT_YAW) {
+  const passenger = new THREE.Group() as RemoteBoatPassengerEntity & THREE.Group & { originalEntity: { id: number } }
+  passenger.playerObject = makePlayerObject()
+  passenger.originalEntity = { id }
+  passenger.userData = {}
+  passenger.visible = true
+  passenger.rotation.y = lookYaw
+  storeNetworkHeadYaw(passenger.userData, lookYaw)
+  return passenger
+}
+
+function makeBoat(passengerIds: number[], yaw = BOAT_YAW) {
+  const boat = new THREE.Group() as RemoteBoatPassengerVehicle & THREE.Group & { originalEntity: { id: number; name: string; height: number } }
+  boat.originalEntity = { id: BOAT_ID, name: 'oak_boat', height: 1.6 }
+  boat.userData = {
+    renderHints: {
+      passengerLayout: 'boat',
+      passengerIds
+    }
+  }
+  boat.realName = 'oak_boat'
+  boat.rotation.y = yaw
+  return boat
+}
+
+function createHarness(passengerIds: number[]) {
+  const sceneOrigin = new SceneOrigin(new THREE.Scene())
+  sceneOrigin.update(96, 60, 192)
+
+  const entities: Record<string, RemoteBoatPassengerEntity & THREE.Group & { originalEntity: { id: number } }> = {}
+  for (const id of passengerIds) {
+    const passenger = makeRemotePassenger(id)
+    sceneOrigin.track(passenger)
+    entities[String(id)] = passenger
+  }
+
+  const boat = makeBoat(passengerIds)
+  sceneOrigin.track(boat)
+  boat.position.set(100, 64, 200)
+  entities[String(BOAT_ID)] = boat
+
+  const runPassengerUpdate = () =>
+    updateVehiclePassengerPositions({
+      entities: entities as Parameters<typeof updateVehiclePassengerPositions>[0]['entities'],
+      localPlayer: null,
+      getWorldPosition: target => sceneOrigin.getWorldPosition(target as THREE.Object3D),
+      version: TEST_VERSION
+    })
+
+  const runRemoteRotation = () =>
+    processRemoteBoatPassengerRotations({
+      entities,
+      syncArmor: () => undefined
+    })
+
+  return { sceneOrigin, entities, boat, runPassengerUpdate, runRemoteRotation }
+}
+
+test('remote anchored boat passenger uses boat yaw for body and relative head yaw', () => {
+  const lookYaw = BOAT_YAW + 0.6
+  const { entities, boat, runPassengerUpdate, runRemoteRotation } = createHarness([REMOTE_PLAYER_A])
+  const passenger = entities[String(REMOTE_PLAYER_A)]!
+  storeNetworkHeadYaw(passenger.userData, lookYaw)
+  passenger.rotation.y = lookYaw
+
+  runPassengerUpdate()
+  runRemoteRotation()
+
+  expect(passenger.userData._remoteBoatRotationApplied).toBe(true)
+  expect(passenger.rotation.y).toBeCloseTo(BOAT_YAW)
+  expect(passenger.playerObject!.skin.head.rotation.y).toBeCloseTo(clampBoatPassengerRelativeHeadYaw(normalizeYawDelta(BOAT_YAW, lookYaw)))
+  expect(boat.rotation.y).toBeCloseTo(BOAT_YAW)
+})
+
+test('remote boat passenger head yaw updates when boat turns without new look packet', () => {
+  const lookYaw = BOAT_YAW + 0.4
+  const { entities, boat, runPassengerUpdate, runRemoteRotation } = createHarness([REMOTE_PLAYER_A])
+  const passenger = entities[String(REMOTE_PLAYER_A)]!
+  storeNetworkHeadYaw(passenger.userData, lookYaw)
+
+  runPassengerUpdate()
+  runRemoteRotation()
+  expect(passenger.rotation.y).toBeCloseTo(BOAT_YAW)
+
+  boat.rotation.y = BOAT_YAW + 0.7
+  runPassengerUpdate()
+  runRemoteRotation()
+
+  expect(passenger.rotation.y).toBeCloseTo(BOAT_YAW + 0.7)
+  expect(passenger.playerObject!.skin.head.rotation.y).toBeCloseTo(clampBoatPassengerRelativeHeadYaw(normalizeYawDelta(BOAT_YAW + 0.7, lookYaw)))
+})
+
+test('two remote passengers keep independent head yaw on the same boat', () => {
+  const lookA = BOAT_YAW + 0.3
+  const lookB = BOAT_YAW - 0.5
+  const { entities, runPassengerUpdate, runRemoteRotation } = createHarness([REMOTE_PLAYER_A, REMOTE_PLAYER_B])
+  const passengerA = entities[String(REMOTE_PLAYER_A)]!
+  const passengerB = entities[String(REMOTE_PLAYER_B)]!
+
+  storeNetworkHeadYaw(passengerA.userData, lookA)
+  storeNetworkHeadYaw(passengerB.userData, lookB)
+
+  runPassengerUpdate()
+  runRemoteRotation()
+
+  expect(passengerA.playerObject!.skin.head.rotation.y).toBeCloseTo(clampBoatPassengerRelativeHeadYaw(normalizeYawDelta(BOAT_YAW, lookA)))
+  expect(passengerB.playerObject!.skin.head.rotation.y).toBeCloseTo(clampBoatPassengerRelativeHeadYaw(normalizeYawDelta(BOAT_YAW, lookB)))
+})
+
+test('dismount restores generic remote body yaw and zero head yaw', () => {
+  const lookYaw = BOAT_YAW + 0.55
+  const { entities, boat, runPassengerUpdate, runRemoteRotation } = createHarness([REMOTE_PLAYER_A])
+  const passenger = entities[String(REMOTE_PLAYER_A)]!
+  storeNetworkHeadYaw(passenger.userData, lookYaw)
+  storeNetworkHeadPitch(passenger.userData, 0.25)
+
+  runPassengerUpdate()
+  runRemoteRotation()
+  expect(passenger.rotation.y).toBeCloseTo(BOAT_YAW)
+  expect(passenger.userData._remoteBoatRotationApplied).toBe(true)
+
+  boat.userData.renderHints = { passengerLayout: 'boat', passengerIds: [] }
+  runPassengerUpdate()
+  runRemoteRotation()
+
+  expect(passenger.userData._remoteBoatRotationApplied).toBe(false)
+  expect(passenger.rotation.y).toBeCloseTo(lookYaw)
+  expect(passenger.playerObject!.skin.head.rotation.y).toBe(0)
+  expect(passenger.playerObject!.skin.head.rotation.x).toBeCloseTo(-0.25)
+})
+
+test('missing network yaw on first frame keeps generic pose until look arrives', () => {
+  const passenger = makeRemotePassenger(REMOTE_PLAYER_A, BOAT_YAW + 0.9)
+  delete passenger.userData._networkHeadYaw
+  const boat = makeBoat([REMOTE_PLAYER_A])
+  anchorVehiclePassengerPosition(passenger, { x: 0, y: 0, z: 0 }, String(BOAT_ID))
+
+  processRemoteBoatPassengerRotation({
+    passenger,
+    vehicle: boat,
+    syncArmor: () => undefined
+  })
+
+  expect(passenger.userData._remoteBoatRotationApplied).toBeUndefined()
+  expect(passenger.rotation.y).toBeCloseTo(BOAT_YAW + 0.9)
+  expect(passenger.playerObject!.skin.head.rotation.y).toBe(0)
+})
+
+test('restoreGenericRemotePassengerRotation uses stored network yaw', () => {
+  const lookYaw = BOAT_YAW + 1.1
+  const passenger = makeRemotePassenger(REMOTE_PLAYER_A, BOAT_YAW)
+  storeNetworkHeadYaw(passenger.userData, lookYaw)
+  storeNetworkHeadPitch(passenger.userData, -0.15)
+  passenger.userData._remoteBoatRotationApplied = true
+
+  restoreGenericRemotePassengerRotation(passenger)
+
+  expect(passenger.rotation.y).toBeCloseTo(lookYaw)
+  expect(passenger.playerObject!.skin.head.rotation.y).toBe(0)
+  expect(passenger.playerObject!.skin.head.rotation.x).toBeCloseTo(0.15)
+  expect(passenger.userData._remoteBoatRotationApplied).toBe(false)
+})
+
+test('applyRemoteBoatPassengerRotation stops active rotation tween', () => {
+  const lookYaw = BOAT_YAW + 0.2
+  const passenger = makeRemotePassenger(REMOTE_PLAYER_A, lookYaw)
+  const boat = makeBoat([REMOTE_PLAYER_A])
+  let tweenStopped = false
+  passenger.userData._rotTween = {
+    stop: () => {
+      tweenStopped = true
+    }
+  }
+
+  applyRemoteBoatPassengerRotation({
+    passenger,
+    vehicle: boat,
+    vehicleYaw: BOAT_YAW,
+    networkHeadYaw: lookYaw
+  })
+
+  expect(tweenStopped).toBe(true)
+  expect(passenger.userData._rotTween).toBeUndefined()
+})
+
+test('remote boat rotation clamps beyond ±105°', () => {
+  const lookYaw = BOAT_YAW + 2.0
+  const passenger = makeRemotePassenger(REMOTE_PLAYER_A, lookYaw)
+  const boat = makeBoat([REMOTE_PLAYER_A])
+  storeNetworkHeadYaw(passenger.userData, lookYaw)
+
+  applyRemoteBoatPassengerRotation({
+    passenger,
+    vehicle: boat,
+    vehicleYaw: BOAT_YAW,
+    networkHeadYaw: lookYaw
+  })
+
+  expect(passenger.playerObject!.skin.head.rotation.y).toBeCloseTo(BOAT_PASSENGER_MAX_HEAD_YAW_RAD)
+})