minecraft-renderer 0.1.93 → 0.1.94

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

package/src/three/entity/vehiclePassengerUpdate.ts

@@ -0,0 +1,82 @@
+//@ts-nocheck
+import { isBoatEntityName } from './boatModelRotation'
+import {
+  getBoatPassengerWorldPosition,
+  getHorsePassengerWorldPosition,
+  getMinecartPassengerWorldPosition,
+  isRideableHorseEntityName,
+  isRideableMinecartEntityName,
+  type EntityRenderHints,
+  type Vec3Like
+} from './interpolationPolicy'
+import {
+  anchorVehiclePassengerPosition,
+  isFiniteVec3,
+  releaseVehiclePassengerPosition,
+  shouldSkipLocalPassengerAnchoring,
+  type VehiclePassengerRenderState
+} from './vehiclePassengerRendering'
+
+export type VehiclePassengerSceneEntity = VehiclePassengerRenderState & {
+  playerObject?: unknown
+  originalEntity: { id: number }
+}
+
+export type VehiclePassengerVehicle = {
+  originalEntity: { id: number | string; name: string; height?: number }
+  userData: { renderHints?: EntityRenderHints }
+  rotation: { y: number }
+  realName?: string
+}
+
+export function updateVehiclePassengerPositions(args: {
+  entities: Record<string, VehiclePassengerSceneEntity | VehiclePassengerVehicle>
+  localPlayer: VehiclePassengerSceneEntity | null
+  getWorldPosition: (target: unknown) => Vec3Like | undefined
+}): Set<VehiclePassengerSceneEntity> {
+  const attachedPassengers = new Set<VehiclePassengerSceneEntity>()
+
+  for (const entity of Object.values(args.entities)) {
+    const vehicle = entity as VehiclePassengerVehicle
+    const renderHints = vehicle.userData.renderHints
+    const passengerIds = renderHints?.passengerIds ?? renderHints?.boatPassengerIds
+    if (!Array.isArray(passengerIds) || passengerIds.length === 0) continue
+
+    const vehicleName = vehicle.realName ?? vehicle.originalEntity.name
+    const layout = renderHints?.passengerLayout ?? (isBoatEntityName(vehicleName) ? 'boat' : undefined)
+    if (layout !== 'boat' && layout !== 'minecart' && layout !== 'horse') continue
+    if (layout === 'boat' && !isBoatEntityName(vehicleName)) continue
+    if (layout === 'minecart' && !isRideableMinecartEntityName(vehicleName)) continue
+    if (layout === 'horse' && !isRideableHorseEntityName(vehicleName)) continue
+
+    const vehicleWorldPos = args.getWorldPosition(vehicle)
+    if (!isFiniteVec3(vehicleWorldPos)) continue
+    const vehicleId = String(vehicle.originalEntity.id)
+
+    for (const [passengerIndex, passengerId] of passengerIds.entries()) {
+      const isLocalPassenger = passengerId === args.localPlayer?.originalEntity.id
+      const passenger = isLocalPassenger ? args.localPlayer : (args.entities[passengerId] as VehiclePassengerSceneEntity | undefined)
+      if (!passenger?.playerObject) continue
+      if (passenger === args.localPlayer && shouldSkipLocalPassengerAnchoring(layout)) continue
+
+      const passengerWorldPos =
+        layout === 'minecart'
+          ? getMinecartPassengerWorldPosition(vehicleWorldPos)
+          : layout === 'horse'
+            ? getHorsePassengerWorldPosition(vehicleWorldPos, vehicleName, vehicle.originalEntity.height ?? 1.6)
+            : getBoatPassengerWorldPosition(vehicleWorldPos, vehicle.rotation.y, passengerIndex, passengerIds.length)
+
+      if (!isFiniteVec3(passengerWorldPos)) continue
+      anchorVehiclePassengerPosition(passenger, passengerWorldPos, vehicleId)
+      attachedPassengers.add(passenger)
+    }
+  }
+
+  for (const passenger of [...Object.values(args.entities), ...(args.localPlayer ? [args.localPlayer] : [])] as VehiclePassengerSceneEntity[]) {
+    const vehicleId = passenger.userData._passengerVehicleId ?? (passenger.userData._boatPassengerVehicleId as string | undefined)
+    if (vehicleId === undefined || attachedPassengers.has(passenger)) continue
+    releaseVehiclePassengerPosition(passenger, vehicleId, args.getWorldPosition(passenger))
+  }
+
+  return attachedPassengers
+}

package/src/three/graphicsBackendBase.ts

@@ -8,7 +8,7 @@
 
 import * as THREE from 'three'
 import { Vec3 } from 'vec3'
-import type { GraphicsBackend, GraphicsInitOptions, DisplayWorldOptions } from '../graphicsBackend'
+import type { GraphicsBackend, GraphicsInitOptions, DisplayWorldOptions, UpdateCameraOptions } from '../graphicsBackend'
 import { createWorkerProxy, restoreTransferred } from '../lib/workerProxy'
 import { ResourcesManager } from '../resourcesManager'
 import { FrameTimingCollector } from '../lib/frameTimingCollector'
@@ -280,10 +280,10 @@ export const createGraphicsBackendBase = () => {
         }
       }
     }),
-    updateCamera(pos: Vec3 | null, yaw: number, pitch: number) {
+    updateCamera(pos: Vec3 | null, yaw: number, pitch: number, options?: UpdateCameraOptions) {
       // Mark camera update event for frame timing visualization
       frameTimingCollector?.markCameraUpdate(!pos)
-      worldRenderer?.setFirstPersonCamera(pos, yaw, pitch)
+      worldRenderer?.setFirstPersonCamera(pos, yaw, pitch, options)
     },
     get soundSystem() {
       return worldRenderer?.soundSystem
@@ -311,10 +311,10 @@ export const createGraphicsBackendBase = () => {
         startWorld,
         disconnect,
         setRendering: backend.setRendering,
-        updateCamera(pos, yaw, pitch) {
+        updateCamera(pos, yaw, pitch, options?: UpdateCameraOptions) {
           const posVec = pos ? new Vec3(pos.x, pos.y, pos.z) : null
           frameTimingCollector?.markCameraUpdate(!posVec)
-          backend.updateCamera(posVec, yaw, pitch)
+          backend.updateCamera(posVec, yaw, pitch, options)
         },
         async callBackendMethod<K extends keyof ThreeJsBackendMethods>(
           method: K,

package/src/three/graphicsBackendOffThread.ts

@@ -154,8 +154,8 @@ export const createGraphicsBackendOffThread: GraphicsBackendLoader = async initO
     setRendering(rendering) {
       proxy.setRendering(rendering)
     },
-    updateCamera(pos, yaw, pitch) {
-      proxy.updateCamera(pos ? { x: pos.x, y: pos.y, z: pos.z } : null, yaw, pitch)
+    updateCamera(pos, yaw, pitch, options) {
+      proxy.updateCamera(pos ? { x: pos.x, y: pos.y, z: pos.z } : null, yaw, pitch, options)
     },
     soundSystem: undefined,
     backendMethods: backendMethodsProxy

package/src/three/worldRendererThree.ts

@@ -16,11 +16,18 @@ import { getMyHand } from './hand'
 import { createHoldingBlock } from './holdingBlockFactory'
 import type { IHoldingBlock } from './holdingBlockTypes'
 import { getMesh } from './entity/EntityMesh'
+import { resolveEntityHeadPose } from './entity/entityHeadPose'
 import { armorModel } from './entity/armorModels'
 import { disposeObject, loadThreeJsTextureFromBitmap } from './threeJsUtils'
 import { CursorBlock } from './world/cursorBlock'
 import { getItemUv } from './appShared'
 import { Entities } from './entities'
+import {
+  getCameraMovementTweenDurationMs,
+  shouldRestartCameraPositionTween,
+  type CameraMovementMode,
+  type UpdateCameraOptions
+} from './entity/interpolationPolicy'
 import { ThreeJsSound } from './threeJsSound'
 import { CameraShake } from './cameraShake'
 import { ThreeJsMedia } from './threeJsMedia'
@@ -160,6 +167,8 @@ export class WorldRendererThree extends WorldRendererCommon {
 
   private currentPosTween?: tweenJs.Tween<{ x: number; y: number; z: number }>
   private currentRotTween?: tweenJs.Tween<{ pitch: number; yaw: number }>
+  private currentCameraTarget: { x: number; y: number; z: number } | null = null
+  private currentCameraMovementMode: CameraMovementMode | null = null
 
   // Pre-allocated objects for getThirdPersonCamera (avoid per-frame allocs)
   private readonly _tpDirection = new THREE.Vector3()
@@ -492,17 +501,18 @@ export class WorldRendererThree extends WorldRendererCommon {
   }
 
   updateEntity(e, isPosUpdate = false) {
+    const headPose = resolveEntityHeadPose(e)
     const overrides = {
       rotation: {
         head: {
-          x: e.headPitch ?? e.pitch,
-          y: e.headYaw,
+          x: headPose.pitch,
+          y: headPose.headYaw,
           z: 0
         }
       }
     }
     if (isPosUpdate) {
-      this.entities.updateEntityPosition(e, false, overrides)
+      this.entities.updateEntityPosition(e, false, overrides, e.headRotationOnly === true)
     } else {
       this.entities.update(e, overrides)
     }
@@ -993,10 +1003,10 @@ export class WorldRendererThree extends WorldRendererCommon {
     }
   }
 
-  setFirstPersonCamera(pos: Vec3 | null, yaw: number, pitch: number) {
+  setFirstPersonCamera(pos: Vec3 | null, yaw: number, pitch: number, options?: UpdateCameraOptions) {
     const yOffset = this.playerStateReactive.eyeHeight
 
-    this.updateCamera(pos?.offset(0, yOffset, 0) ?? null, yaw, pitch)
+    this.updateCamera(pos?.offset(0, yOffset, 0) ?? null, yaw, pitch, options)
     // this.media.tryIntersectMedia()
     this.updateCameraSectionPos()
   }
@@ -1152,34 +1162,50 @@ export class WorldRendererThree extends WorldRendererCommon {
     }
   }
 
-  updateCamera(pos: Vec3 | null, yaw: number, pitch: number): void {
+  updateCamera(pos: Vec3 | null, yaw: number, pitch: number, options?: UpdateCameraOptions): void {
     // Skip position/rotation updates if cinematic script is running
     if (this.cinimaticScript.running) {
       return
     }
 
-    // if (this.freeFlyMode) {
-    //   pos = this.freeFlyState.position
-    //   pitch = this.freeFlyState.pitch
-    //   yaw = this.freeFlyState.yaw
-    // }
-
     if (pos) {
       if (this.renderer.xr.isPresenting) {
         pos.y -= this.camera.position.y // Fix Y position of camera in world
       }
 
-      this.currentPosTween?.stop()
-      // Use instant camera updates (0 delay) in playground mode when camera controls are enabled
-      const tweenDelay = this.displayOptions.inWorldRenderingConfig.instantCameraUpdate ? 0 : this.playerStateUtils.isSpectatingEntity() ? 150 : 50
-      this.currentPosTween = new tweenJs.Tween(this.cameraWorldPos)
-        .to({ x: pos.x, y: pos.y, z: pos.z }, tweenDelay)
-        .onUpdate(() => {
-          this.sceneOrigin.update(this.cameraWorldPos.x, this.cameraWorldPos.y, this.cameraWorldPos.z)
+      const movementMode: CameraMovementMode = this.playerStateUtils.isSpectatingEntity() ? 'spectating' : (options?.movementMode ?? 'local-player')
+      const instant = options?.instant === true || this.displayOptions.inWorldRenderingConfig.instantCameraUpdate === true
+      const target = { x: pos.x, y: pos.y, z: pos.z }
+      const restartTween = shouldRestartCameraPositionTween({
+        target,
+        currentTarget: this.currentCameraTarget,
+        movementMode,
+        previousMovementMode: this.currentCameraMovementMode,
+        instant
+      })
+      const tweenDelay = getCameraMovementTweenDurationMs(movementMode, instant)
+
+      if (restartTween) {
+        this.currentCameraTarget = { ...target }
+        this.currentCameraMovementMode = movementMode
+        this.currentPosTween?.stop()
+        if (instant || tweenDelay === 0) {
+          this.cameraWorldPos.x = target.x
+          this.cameraWorldPos.y = target.y
+          this.cameraWorldPos.z = target.z
+          this.sceneOrigin.update(target.x, target.y, target.z)
           this.cameraObject.position.set(0, 0, 0)
-        })
-        .start()
-      // this.freeFlyState.position = pos
+          this.currentPosTween = undefined
+        } else {
+          this.currentPosTween = new tweenJs.Tween(this.cameraWorldPos)
+            .to(target, tweenDelay)
+            .onUpdate(() => {
+              this.sceneOrigin.update(this.cameraWorldPos.x, this.cameraWorldPos.y, this.cameraWorldPos.z)
+              this.cameraObject.position.set(0, 0, 0)
+            })
+            .start()
+        }
+      }
     }
 
     if (this.playerStateUtils.isSpectatingEntity()) {