minecraft-renderer 0.1.92 → 0.1.94

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

@@ -0,0 +1,227 @@
+//@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
+
+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)
+    })
+
+  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)
+})

package/src/three/entity/remoteBoatPassengerRotation.ts

@@ -0,0 +1,128 @@
+//@ts-nocheck
+import type * as THREE from 'three'
+import type { PlayerObjectType } from '../../lib/createPlayerObject'
+import { resolveBoatPassengerThirdPersonRotation, shouldApplyBoatPassengerRotation } from './boatPassengerRotation'
+import { getNetworkHeadPitch, restoreGenericRemotePlayerHeadRotation, type NetworkHeadRotationState } from './networkHeadPitchRendering'
+
+export type RemoteBoatPassengerEntity = {
+  rotation: { y: number; set: (x: number, y: number, z: number) => unknown }
+  visible: boolean
+  playerObject?: PlayerObjectType
+  userData: NetworkHeadRotationState & {
+    _passengerVehicleId?: string
+    _boatPassengerVehicleId?: string
+    _rotTween?: { stop: () => unknown }
+  }
+}
+
+export type RemoteBoatPassengerVehicle = {
+  rotation: { y: number }
+  realName?: string
+  originalEntity: { name: string }
+}
+
+export function getAnchoredVehicleId(userData: RemoteBoatPassengerEntity['userData']): string | undefined {
+  return userData._passengerVehicleId ?? userData._boatPassengerVehicleId
+}
+
+export function stopRemotePassengerRotationTween(userData: RemoteBoatPassengerEntity['userData']): void {
+  userData._rotTween?.stop()
+  userData._rotTween = undefined
+}
+
+export function applyRemoteBoatPassengerRotation(params: {
+  passenger: RemoteBoatPassengerEntity
+  vehicle: RemoteBoatPassengerVehicle
+  vehicleYaw: number
+  networkHeadYaw: number
+}): void {
+  const { passenger, networkHeadYaw, vehicleYaw } = params
+  const playerObject = passenger.playerObject
+  if (!playerObject) return
+
+  stopRemotePassengerRotationTween(passenger.userData)
+
+  const resolved = resolveBoatPassengerThirdPersonRotation({
+    cameraYaw: networkHeadYaw,
+    cameraPitch: getNetworkHeadPitch(passenger.userData),
+    vehicleYaw
+  })
+
+  passenger.rotation.set(0, resolved.bodyYaw, 0)
+  playerObject.skin.head.rotation.set(resolved.headPitch, resolved.headYaw, 0)
+  passenger.userData._remoteBoatRotationApplied = true
+}
+
+export function restoreGenericRemotePassengerRotation(passenger: RemoteBoatPassengerEntity): void {
+  const playerObject = passenger.playerObject
+  if (!playerObject) return
+
+  stopRemotePassengerRotationTween(passenger.userData)
+
+  const networkHeadYaw = passenger.userData._networkHeadYaw
+  if (typeof networkHeadYaw === 'number' && Number.isFinite(networkHeadYaw)) {
+    passenger.rotation.set(0, networkHeadYaw, 0)
+  }
+
+  restoreGenericRemotePlayerHeadRotation(playerObject, passenger.userData)
+  passenger.userData._remoteBoatRotationApplied = false
+}
+
+export function processRemoteBoatPassengerRotation(params: {
+  passenger: RemoteBoatPassengerEntity
+  vehicle: RemoteBoatPassengerVehicle | undefined
+  syncArmor?: () => void
+}): void {
+  const { passenger, vehicle, syncArmor } = params
+  if (!passenger.playerObject) return
+
+  const userData = passenger.userData
+  const wasApplied = userData._remoteBoatRotationApplied === true
+  const anchoredVehicleId = getAnchoredVehicleId(userData)
+  const vehicleName = vehicle?.realName ?? vehicle?.originalEntity.name
+  const vehicleYaw = vehicle?.rotation.y
+  const gatePasses = shouldApplyBoatPassengerRotation({
+    isAnchoredPassenger: anchoredVehicleId != null && vehicle != null,
+    vehicleName,
+    vehicleYaw
+  })
+
+  if (!gatePasses) {
+    if (wasApplied) {
+      restoreGenericRemotePassengerRotation(passenger)
+      syncArmor?.()
+    }
+    return
+  }
+
+  const networkHeadYaw = userData._networkHeadYaw
+  if (typeof networkHeadYaw !== 'number' || !Number.isFinite(networkHeadYaw)) {
+    return
+  }
+
+  applyRemoteBoatPassengerRotation({
+    passenger,
+    vehicle: vehicle!,
+    vehicleYaw: vehicleYaw!,
+    networkHeadYaw
+  })
+  syncArmor?.()
+}
+
+export function processRemoteBoatPassengerRotations(params: {
+  entities: Record<string, RemoteBoatPassengerEntity | undefined>
+  syncArmor: (passenger: RemoteBoatPassengerEntity) => void
+}): void {
+  for (const entity of Object.values(params.entities)) {
+    if (!entity?.playerObject) continue
+
+    const anchoredVehicleId = getAnchoredVehicleId(entity.userData)
+    const vehicle = anchoredVehicleId != null ? (params.entities[anchoredVehicleId] as RemoteBoatPassengerVehicle | undefined) : undefined
+
+    processRemoteBoatPassengerRotation({
+      passenger: entity,
+      vehicle,
+      syncArmor: entity.visible ? () => params.syncArmor(entity) : undefined
+    })
+  }
+}

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

@@ -0,0 +1,214 @@
+//@ts-nocheck
+import * as THREE from 'three'
+import { expect, test } from 'vitest'
+import { SceneOrigin } from '../sceneOrigin'
+import { getBoatPassengerWorldPosition, getMinecartPassengerWorldPosition } from './interpolationPolicy'
+import { anchorVehiclePassengerPosition, shouldSkipLocalPassengerAnchoring } from './vehiclePassengerRendering'
+import { updateVehiclePassengerPositions, type VehiclePassengerSceneEntity, type VehiclePassengerVehicle } from './vehiclePassengerUpdate'
+
+const LOCAL_PLAYER_ID = 7
+const REMOTE_PLAYER_ID = 8
+
+type PassengerLike = THREE.Group & VehiclePassengerSceneEntity
+
+function makePassenger(id: number): PassengerLike {
+  const passenger = new THREE.Group() as PassengerLike
+  passenger.playerObject = {}
+  passenger.originalEntity = { id }
+  passenger.userData = {}
+  passenger.rotation.y = 0
+  return passenger
+}
+
+function makeVehicle(id: number, name: string, renderHints: Record<string, unknown>): VehiclePassengerVehicle & THREE.Group {
+  const vehicle = new THREE.Group() as VehiclePassengerVehicle & THREE.Group
+  vehicle.originalEntity = { id, name, height: name === 'donkey' ? 1.5 : 1.6 }
+  vehicle.userData = { renderHints }
+  vehicle.realName = name
+  vehicle.rotation.y = 0
+  return vehicle
+}
+
+function createHarness() {
+  const sceneOrigin = new SceneOrigin(new THREE.Scene())
+  sceneOrigin.update(96, 60, 192)
+
+  const localPlayer = makePassenger(LOCAL_PLAYER_ID)
+  sceneOrigin.track(localPlayer)
+
+  const entities: Record<string, VehiclePassengerSceneEntity | VehiclePassengerVehicle> = {}
+  const cameraWorldPos = { x: 100, y: 65.62, z: 200 }
+
+  const runUpdate = () =>
+    updateVehiclePassengerPositions({
+      entities,
+      localPlayer,
+      getWorldPosition: target => sceneOrigin.getWorldPosition(target as THREE.Object3D)
+    })
+
+  return { sceneOrigin, localPlayer, entities, cameraWorldPos, runUpdate }
+}
+
+test('shouldSkipLocalPassengerAnchoring keeps horse on camera path', () => {
+  expect(shouldSkipLocalPassengerAnchoring('boat')).toBe(false)
+  expect(shouldSkipLocalPassengerAnchoring('minecart')).toBe(false)
+  expect(shouldSkipLocalPassengerAnchoring('horse')).toBe(true)
+})
+
+test('updateVehiclePassengerPositions anchors local boat and minecart passengers', () => {
+  const { sceneOrigin, localPlayer, entities, runUpdate } = createHarness()
+
+  const boat = makeVehicle(10, 'oak_boat', { passengerLayout: 'boat', passengerIds: [LOCAL_PLAYER_ID] })
+  sceneOrigin.track(boat)
+  boat.position.set(100, 64, 200)
+  entities['10'] = boat
+
+  runUpdate()
+
+  const expectedBoatSeat = getBoatPassengerWorldPosition(sceneOrigin.getWorldPosition(boat)!, boat.rotation.y, 0, 1)
+  expect(localPlayer.userData._passengerVehicleId).toBe('10')
+  expect(sceneOrigin.getWorldPosition(localPlayer)).toEqual(expectedBoatSeat)
+
+  const minecart = makeVehicle(42, 'minecart', { passengerLayout: 'minecart', passengerIds: [LOCAL_PLAYER_ID] })
+  sceneOrigin.track(minecart)
+  minecart.position.set(103, 64.5, 205)
+  entities['42'] = minecart
+  boat.userData.renderHints = { passengerLayout: 'boat', passengerIds: [] }
+
+  runUpdate()
+
+  const expectedMinecartSeat = getMinecartPassengerWorldPosition(sceneOrigin.getWorldPosition(minecart)!)
+  expect(localPlayer.userData._passengerVehicleId).toBe('42')
+  expect(sceneOrigin.getWorldPosition(localPlayer)).toEqual(expectedMinecartSeat)
+})
+
+test('updateVehiclePassengerPositions keeps local horse on existing skip path', () => {
+  const { sceneOrigin, localPlayer, entities, cameraWorldPos, runUpdate } = createHarness()
+  const eyeHeight = 1.62
+  localPlayer.position.set(cameraWorldPos.x, cameraWorldPos.y - eyeHeight, cameraWorldPos.z)
+
+  const horse = makeVehicle(42, 'horse', {
+    passengerLayout: 'horse',
+    passengerIds: [LOCAL_PLAYER_ID],
+    localVehicle: true,
+    localVehicleVerticalCameraLock: 'horse'
+  })
+  sceneOrigin.track(horse)
+  horse.position.set(100, 64, 200)
+  entities['42'] = horse
+
+  runUpdate()
+
+  expect(localPlayer.userData._passengerVehicleId).toBeUndefined()
+  expect(sceneOrigin.getWorldPosition(localPlayer)?.y).toBeCloseTo(cameraWorldPos.y - eyeHeight, 5)
+})
+
+test('local and remote boat passengers use the same seat algorithm per index', () => {
+  const { sceneOrigin, localPlayer, entities, runUpdate } = createHarness()
+  const remotePlayer = makePassenger(REMOTE_PLAYER_ID)
+  sceneOrigin.track(remotePlayer)
+  entities[String(REMOTE_PLAYER_ID)] = remotePlayer
+
+  const boat = makeVehicle(10, 'oak_boat', { passengerLayout: 'boat', passengerIds: [LOCAL_PLAYER_ID, REMOTE_PLAYER_ID] })
+  sceneOrigin.track(boat)
+  boat.position.set(100, 64, 200)
+  entities['10'] = boat
+
+  runUpdate()
+
+  const vehicleWorldPos = sceneOrigin.getWorldPosition(boat)!
+  const localWorld = sceneOrigin.getWorldPosition(localPlayer)!
+  const remoteWorld = sceneOrigin.getWorldPosition(remotePlayer)!
+  expect(localWorld).toEqual(getBoatPassengerWorldPosition(vehicleWorldPos, boat.rotation.y, 0, 2))
+  expect(remoteWorld).toEqual(getBoatPassengerWorldPosition(vehicleWorldPos, boat.rotation.y, 1, 2))
+  expect(localWorld.y).toBeCloseTo(63.55, 5)
+  expect(remoteWorld.y).toBeCloseTo(63.55, 5)
+})
+
+test('vehicle movement updates body anchor without horizontal jitter across frames', () => {
+  const { sceneOrigin, localPlayer, entities, runUpdate } = createHarness()
+
+  const boat = makeVehicle(10, 'oak_boat', { passengerLayout: 'boat', passengerIds: [LOCAL_PLAYER_ID], localVehicle: true })
+  sceneOrigin.track(boat)
+  entities['10'] = boat
+
+  const xs = [100, 100.4, 100.9, 101.1, 100.8]
+  const deltas: number[] = []
+  let previousX: number | undefined
+
+  for (const x of xs) {
+    boat.position.set(x, 64, 200)
+    runUpdate()
+    const world = sceneOrigin.getWorldPosition(localPlayer)!
+    if (previousX !== undefined) {
+      deltas.push(world.x - previousX)
+    }
+    previousX = world.x
+  }
+
+  for (const delta of deltas) {
+    expect(delta).toBeCloseTo(Math.round(delta * 10) / 10, 5)
+  }
+  expect(deltas.map(delta => Math.round(delta * 10) / 10)).toEqual([0.4, 0.5, 0.2, -0.3])
+})
+
+test('dismount and vehicle removal release local passenger anchor', () => {
+  const { sceneOrigin, localPlayer, entities, cameraWorldPos, runUpdate } = createHarness()
+  const eyeHeight = 1.62
+  localPlayer.position.set(cameraWorldPos.x, cameraWorldPos.y - eyeHeight, cameraWorldPos.z)
+
+  const boat = makeVehicle(10, 'oak_boat', { passengerLayout: 'boat', passengerIds: [LOCAL_PLAYER_ID] })
+  sceneOrigin.track(boat)
+  boat.position.set(100, 64, 200)
+  entities['10'] = boat
+
+  runUpdate()
+  expect(localPlayer.userData._passengerVehicleId).toBe('10')
+
+  boat.userData.renderHints = { passengerLayout: 'boat', passengerIds: [] }
+  runUpdate()
+  expect(localPlayer.userData._passengerVehicleId).toBeUndefined()
+
+  localPlayer.position.set(cameraWorldPos.x, cameraWorldPos.y - eyeHeight, cameraWorldPos.z)
+  const releasedWorld = sceneOrigin.getWorldPosition(localPlayer)!
+  expect(releasedWorld.y).toBeCloseTo(cameraWorldPos.y - eyeHeight, 5)
+
+  delete entities['10']
+  runUpdate()
+  expect(localPlayer.userData._passengerVehicleId).toBeUndefined()
+})
+
+test('scene origin rebase preserves passenger world position', () => {
+  const { sceneOrigin, localPlayer, entities, runUpdate } = createHarness()
+
+  const boat = makeVehicle(10, 'oak_boat', { passengerLayout: 'boat', passengerIds: [LOCAL_PLAYER_ID] })
+  sceneOrigin.track(boat)
+  boat.position.set(100, 64, 200)
+  entities['10'] = boat
+
+  runUpdate()
+  const beforeRebase = { ...sceneOrigin.getWorldPosition(localPlayer)! }
+
+  sceneOrigin.update(112, 70, 208)
+  runUpdate()
+  const afterRebase = sceneOrigin.getWorldPosition(localPlayer)!
+
+  expect(afterRebase).toEqual(beforeRebase)
+})
+
+test('non-finite vehicle position does not create passenger anchor', () => {
+  const { localPlayer, entities, runUpdate } = createHarness()
+
+  const boat = makeVehicle(10, 'oak_boat', { passengerLayout: 'boat', passengerIds: [LOCAL_PLAYER_ID] })
+  boat.position.set(Number.NaN, 64, 200)
+  entities['10'] = boat
+
+  runUpdate()
+  expect(localPlayer.userData._passengerVehicleId).toBeUndefined()
+})
+
+test('anchorVehiclePassengerPosition ignores non-finite coordinates', () => {
+  const passenger = makePassenger(LOCAL_PLAYER_ID)
+  anchorVehiclePassengerPosition(passenger, { x: 1, y: Number.NaN, z: 2 }, '10')
+  expect(passenger.userData._passengerVehicleId).toBeUndefined()
+})

package/src/three/entity/vehiclePassengerRendering.ts

@@ -0,0 +1,56 @@
+//@ts-nocheck
+import type { Vec3Like } from './interpolationPolicy'
+
+export type PassengerLayout = 'boat' | 'minecart' | 'horse'
+
+export function shouldSkipLocalPassengerAnchoring(layout: PassengerLayout): boolean {
+  return layout === 'horse'
+}
+
+export function isFiniteVec3(value: Vec3Like | undefined | null): value is Vec3Like {
+  return value != null && Number.isFinite(value.x) && Number.isFinite(value.y) && Number.isFinite(value.z)
+}
+
+export type VehiclePassengerRenderState = {
+  position: {
+    set: (x: number, y: number, z: number) => unknown
+  }
+  userData: {
+    _posTween?: { stop: () => unknown }
+    _tweenTarget?: Vec3Like
+    _passengerVehicleId?: string
+    /** @deprecated Use _passengerVehicleId */
+    _boatPassengerVehicleId?: string
+  }
+}
+
+export function anchorVehiclePassengerPosition(passenger: VehiclePassengerRenderState, passengerWorldPos: Vec3Like, vehicleId: string): void {
+  if (!isFiniteVec3(passengerWorldPos)) return
+  passenger.userData._posTween?.stop()
+  passenger.userData._posTween = undefined
+  passenger.userData._tweenTarget ??= { ...passengerWorldPos }
+  Object.assign(passenger.userData._tweenTarget, passengerWorldPos)
+  passenger.position.set(passengerWorldPos.x, passengerWorldPos.y, passengerWorldPos.z)
+  passenger.userData._passengerVehicleId = vehicleId
+  delete passenger.userData._boatPassengerVehicleId
+}
+
+export function releaseVehiclePassengerPosition(passenger: VehiclePassengerRenderState, vehicleId: string, currentWorldPos: Vec3Like | undefined): boolean {
+  const anchoredVehicleId = passenger.userData._passengerVehicleId ?? passenger.userData._boatPassengerVehicleId
+  if (anchoredVehicleId !== vehicleId) return false
+  passenger.userData._posTween?.stop()
+  passenger.userData._posTween = undefined
+  if (currentWorldPos) {
+    passenger.userData._tweenTarget ??= { ...currentWorldPos }
+    Object.assign(passenger.userData._tweenTarget, currentWorldPos)
+  }
+  delete passenger.userData._passengerVehicleId
+  delete passenger.userData._boatPassengerVehicleId
+  return true
+}
+
+/** @deprecated Use anchorVehiclePassengerPosition */
+export const anchorBoatPassengerPosition = anchorVehiclePassengerPosition
+
+/** @deprecated Use releaseVehiclePassengerPosition */
+export const releaseBoatPassengerPosition = releaseVehiclePassengerPosition