minecraft-renderer 0.1.92 → 0.1.94

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "minecraft-renderer",
-  "version": "0.1.92",
+  "version": "0.1.94",
   "description": "The most Modular Minecraft world renderer with Three.js WebGL backend",
   "type": "module",
   "main": "./dist/index.js",

package/src/graphicsBackend/appViewer.ts

@@ -19,7 +19,8 @@ import type {
   GraphicsInitOptions,
   DisplayWorldOptions,
   RendererReactiveState,
-  NonReactiveState
+  NonReactiveState,
+  UpdateCameraOptions
 } from './types'
 import { WorldView, WorldProvider, WorldViewWorker } from '../worldView'
 import { getInitialPlayerState } from './playerState'
@@ -274,8 +275,8 @@ export class AppViewer {
   /**
    * Update camera position and rotation.
    */
-  updateCamera(pos: Vec3 | null, yaw: number, pitch: number): void {
-    this.backend?.updateCamera(pos, yaw, pitch)
+  updateCamera(pos: Vec3 | null, yaw: number, pitch: number, options?: UpdateCameraOptions): void {
+    this.backend?.updateCamera(pos, yaw, pitch, options)
   }
 
   /**

package/src/graphicsBackend/config.ts

@@ -22,7 +22,7 @@ export const defaultWorldRendererConfig = {
   futuristicReveal: false,
 
   /** Master toggle for section occlusion graph (smart / cave cull). Disabled in spectator. */
-  smartCull: true,
+  smartCull: false,
 
   // Performance settings
   wasmMesher: true,

package/src/graphicsBackend/types.ts

@@ -10,6 +10,9 @@ import { ResourcesManagerTransferred } from '../resourcesManager'
 import { WorldViewWorker } from '../worldView'
 import { Vec3 } from 'vec3'
 import { WorldRendererConfig } from './config'
+import type { UpdateCameraOptions } from '../three/entity/interpolationPolicy'
+
+export type { CameraMovementMode, UpdateCameraOptions } from '../three/entity/interpolationPolicy'
 
 // ============================================================================
 // Graphics Backend Configuration
@@ -135,7 +138,7 @@ export interface GraphicsBackend {
   startWorld(options: DisplayWorldOptions): Promise<void>
   disconnect(): void
   setRendering(rendering: boolean): void
-  updateCamera(pos: Vec3 | null, yaw: number, pitch: number): void
+  updateCamera(pos: Vec3 | null, yaw: number, pitch: number, options?: UpdateCameraOptions): void
   soundSystem?: any
   backendMethods?: any
   getDebugOverlay?(): { entitiesString?: string; left?: Record<string, string>; right?: Record<string, string> }

package/src/lib/worldrendererCommon.ts

@@ -8,7 +8,7 @@ import { subscribeKey } from 'valtio/utils'
 import { proxy, subscribe } from 'valtio'
 import type { ResourcesManagerTransferred } from '../resourcesManager/resourcesManager'
 import { dynamicMcDataFiles } from './buildSharedConfig.mjs'
-import { DisplayWorldOptions, GraphicsInitOptions, RendererReactiveState, SoundSystem } from '../graphicsBackend/types'
+import { DisplayWorldOptions, GraphicsInitOptions, RendererReactiveState, SoundSystem, UpdateCameraOptions } from '../graphicsBackend/types'
 import {
   HighestBlockInfo,
   CustomBlockModels,
@@ -57,7 +57,7 @@ export abstract class WorldRendererCommon<WorkerSend = any, WorkerReceive = any>
     disableEntities: false,
     /** Tint section borders by occlusion BFS step (perf debug overlay). */
     caveCullingDebug: false,
-    smartCull: true
+    smartCull: false
     // disableParticles: false
   })
 
@@ -713,7 +713,7 @@ export abstract class WorldRendererCommon<WorkerSend = any, WorkerReceive = any>
 
   abstract handleWorkerMessage(data: WorkerReceive): void
 
-  abstract updateCamera(pos: Vec3 | null, yaw: number, pitch: number): void
+  abstract updateCamera(pos: Vec3 | null, yaw: number, pitch: number, options?: UpdateCameraOptions): void
 
   abstract render(): void
 

package/src/three/entities.ts

@@ -20,7 +20,44 @@ import { configurePlayerSkinMaterials, PlayerObjectType } from '../lib/createPla
 import { getBlockMeshFromModel } from './holdingBlock'
 import { createItemMesh } from './itemMesh'
 import * as Entity from './entity/EntityMesh'
+import { setupBoatMesh, disposeBoatWaterPatch } from './entity/boatRenderSetup'
+import { getBoatMeshYawOffset, isBoatEntityName } from './entity/boatModelRotation'
+import { resolveBoatPassengerThirdPersonRotation, shouldApplyBoatPassengerThirdPersonRotation } from './entity/boatPassengerRotation'
+import {
+  createBoatPaddleAnimationState,
+  createBoatPaddlePivotScratch,
+  syncBoatPaddleAnimationTargets,
+  updateBoatPaddleAnimationState,
+  type BoatPaddleAnimationState
+} from './entity/boatPaddleAnimation'
+import { releaseVehiclePassengerPosition } from './entity/vehiclePassengerRendering'
+import { updateVehiclePassengerPositions as applyVehiclePassengerPositions } from './entity/vehiclePassengerUpdate'
+import { applyNetworkHeadPitch, storeNetworkHeadPitch, storeNetworkHeadYaw } from './entity/networkHeadPitchRendering'
+import { processRemoteBoatPassengerRotations, type RemoteBoatPassengerEntity } from './entity/remoteBoatPassengerRotation'
+import {
+  ENTITY_TWEEN_DURATION_MS,
+  applyLocalHorseCameraYawLock,
+  getEntityTweenDurationMs,
+  getEntityRotationTweenDurationMs,
+  resolveLocalVehicleWorldPosition,
+  shouldApplyLocalHorseCameraYawLock,
+  type EntityRenderHints,
+  type Vec3Like,
+  usesCameraSyncedVehiclePosition,
+  isRideableMinecartEntityName
+} from './entity/interpolationPolicy'
 import { getMesh } from './entity/EntityMesh'
+import {
+  HORSE_HEAD_ANIMATION_USER_DATA_KEY,
+  HORSE_HEAD_RIG_USER_DATA_KEY,
+  applyHorseHeadPose,
+  calculateHorseHeadPose,
+  createHorseHeadAnimationState,
+  setHorseHeadAnimationPosition,
+  updateHorseHeadAnimationFrame,
+  type HorseHeadAnimationState,
+  type HorseHeadRig
+} from './entity/horseHeadAnimation'
 import { WalkingGeneralSwing } from './entity/animations'
 import { disposeObject, loadNearestFilterTexture, loadTexture, loadThreeJsTextureFromUrl } from './threeJsUtils'
 import { armorModel, armorTextures, elytraTexture } from './entity/armorModels'
@@ -41,7 +78,7 @@ type EntityMetadataVersions = {
 
 export const steveTexture = loadThreeJsTextureFromUrl(stevePngUrl)
 
-export const TWEEN_DURATION = 120
+export const TWEEN_DURATION = ENTITY_TWEEN_DURATION_MS
 
 const degreesToRadians = (degrees: number) => degrees * (Math.PI / 180)
 
@@ -265,7 +302,7 @@ export type SceneEntity = THREE.Object3D & {
   username?: string
   uuid?: string
   additionalCleanup?: () => void
-  originalEntity: import('prismarine-entity').Entity & { delete?; pos?; name; team?: Team }
+  originalEntity: import('prismarine-entity').Entity & { delete?; pos?; name; team?: Team; renderHints?: EntityRenderHints }
 }
 
 export class Entities {
@@ -281,6 +318,7 @@ export class Entities {
   cachedMapsImages = {} as Record<number, string>
   itemFrameMaps = {} as Record<number, Array<THREE.Mesh<THREE.PlaneGeometry, THREE.MeshLambertMaterial>>>
   pendingModelOverrides = new Map<string, { parts: EntityModelOverridePart[] }>()
+  private boatPaddleScratch = createBoatPaddlePivotScratch()
 
   get entitiesByName(): Record<string, SceneEntity[]> {
     const byName: Record<string, SceneEntity[]> = {}
@@ -316,6 +354,7 @@ export class Entities {
   }
 
   handlePlayerEntity(playerData: SceneEntity['originalEntity']) {
+    if (!this.isRenderingAllowed()) return
     // Create player entity if it doesn't exist
     if (!this.playerEntity) {
       // Create the player entity similar to how normal entities are created
@@ -329,7 +368,7 @@ export class Entities {
 
       group.name = 'player_entity'
       this.playerEntity = group
-      this.worldRenderer.scene.add(group)
+      this.syncSceneAttachment(group)
 
       void this.updatePlayerSkin(playerData.id, playerData.username, playerData.uuid ?? undefined, stevePngUrl)
     }
@@ -392,9 +431,27 @@ export class Entities {
   }
 
   setRendering(rendering: boolean, entity: THREE.Object3D | null = null) {
-    this.currentlyRendering = rendering
-    for (const ent of entity ? [entity] : Object.values(this.entities)) {
-      if (rendering) {
+    this.currentlyRendering = rendering && this.isRenderingAllowed()
+    this.setSceneAttached(this.currentlyRendering, entity)
+  }
+
+  isRenderingAllowed(): boolean {
+    return this.worldRenderer.worldRendererConfig.renderEntities !== false && !this.worldRenderer.reactiveDebugParams.disableEntities
+  }
+
+  /** Add or remove entity meshes from the scene (including third-person player). */
+  syncSceneAttachment(entity: THREE.Object3D | null = null): void {
+    const attached = this.isRenderingAllowed()
+    this.currentlyRendering = attached
+    this.setSceneAttached(attached, entity)
+  }
+
+  private setSceneAttached(attached: boolean, entity: THREE.Object3D | null = null): void {
+    const targets = entity
+      ? [entity]
+      : [...Object.values(this.entities), ...(this.playerEntity ? [this.playerEntity] : [])]
+    for (const ent of targets) {
+      if (attached) {
         if (!this.worldRenderer.scene.children.includes(ent)) this.worldRenderer.scene.add(ent)
       } else {
         this.worldRenderer.scene.remove(ent)
@@ -414,10 +471,8 @@ export class Entities {
   }
 
   render() {
-    const renderEntitiesConfig = this.worldRenderer.worldRendererConfig.renderEntities
-    if (renderEntitiesConfig !== this.currentlyRendering) {
-      this.setRendering(renderEntitiesConfig)
-    }
+    this.syncSceneAttachment()
+    if (!this.isRenderingAllowed()) return
 
     this.clock.update(performance.now())
     const dt = Math.min(this.clock.getDelta(), 1 / 30)
@@ -433,7 +488,8 @@ export class Entities {
         const thirdPerson = this.worldRenderer.playerStateUtils.isThirdPerson()
         entity.visible = thirdPerson
 
-        if (thirdPerson) {
+        const isAnchoredPassenger = entity.userData._passengerVehicleId != null || entity.userData._boatPassengerVehicleId != null
+        if (thirdPerson && !isAnchoredPassenger) {
           const yOffset = this.worldRenderer.playerStateReactive.eyeHeight
           entity.position.set(this.worldRenderer.cameraWorldPos.x, this.worldRenderer.cameraWorldPos.y - yOffset, this.worldRenderer.cameraWorldPos.z)
         }
@@ -445,6 +501,31 @@ export class Entities {
         playerObject.animation.update(playerObject, dt)
       }
 
+      if (!isPlayerEntity) {
+        const renderHints = entity.userData.renderHints as EntityRenderHints | undefined
+        if (shouldApplyLocalHorseCameraYawLock(renderHints)) {
+          applyLocalHorseCameraYawLock(entity, this.worldRenderer.cameraShake.getBaseRotation().yaw)
+        }
+      }
+
+      const horseHeadRig = entity.userData[HORSE_HEAD_RIG_USER_DATA_KEY] as HorseHeadRig | undefined
+      const horseAnimation = entity.userData[HORSE_HEAD_ANIMATION_USER_DATA_KEY] as HorseHeadAnimationState | undefined
+      if (horseHeadRig && horseAnimation) {
+        const animation = updateHorseHeadAnimationFrame(horseAnimation, dt)
+        const pose = calculateHorseHeadPose({
+          entityPitch: entity.userData._horseHeadPitch ?? 0,
+          headYaw: entity.userData._horseHeadYaw ?? entity.userData._horseBodyYaw ?? 0,
+          bodyYaw: entity.userData._horseBodyYaw ?? 0,
+          limbSwing: animation.limbSwing,
+          limbSwingAmount: animation.limbSwingAmount
+        })
+        applyHorseHeadPose(horseHeadRig, pose)
+      }
+
+      if (!isPlayerEntity && playerObject) {
+        applyNetworkHeadPitch(playerObject, entity.userData)
+      }
+
       entity.traverse(child => {
         if (child instanceof Entity.EntityMesh) {
           child.update(dt)
@@ -465,23 +546,124 @@ export class Entities {
         this.maybeRenderPlayerSkin(entityIdRaw)
       }
 
-      if (entity.visible) {
+      if (entity.userData.renderHints?.localVehicle) {
+        const worldPos = this.resolveLocalVehicleRenderWorldPos(entity)
+        entity.position.set(worldPos.x, worldPos.y, worldPos.z)
+      }
+
+      if (entity.visible && !isPlayerEntity) {
         this.syncArmorPositions(entity)
       }
+    }
 
-      if (isPlayerEntity && entity.visible) {
-        const rotation = this.worldRenderer.cameraShake.getBaseRotation()
-        entity.rotation.set(0, rotation.yaw, 0)
+    this.updateVehiclePassengerPositions()
+    this.applyRemoteBoatPassengerRotations()
+    this.applyLocalThirdPersonPlayerRotation()
+    this.updateBoatPaddleAnimations(dt)
+  }
 
-        entity.traverse(c => {
-          if (c.name === 'head') {
-            c.rotation.set(-rotation.pitch, 0, 0)
-          }
-        })
-      }
+  private applyRemoteBoatPassengerRotations() {
+    processRemoteBoatPassengerRotations({
+      entities: this.entities as Record<string, RemoteBoatPassengerEntity>,
+      syncArmor: entity => this.syncArmorPositions(entity as SceneEntity)
+    })
+  }
+
+  private updateBoatPaddleAnimations(dt: number) {
+    for (const entity of Object.values(this.entities)) {
+      if (!entity) continue
+      if (!isBoatEntityName(entity['realName'] as string | undefined)) continue
+
+      const mesh = entity.children.find(child => child.name === 'mesh')
+      if (!mesh) continue
+
+      let animState = mesh.userData.boatPaddleAnimation as BoatPaddleAnimationState | undefined
+      if (!animState) continue
+
+      updateBoatPaddleAnimationState(
+        animState,
+        dt,
+        mesh.userData.boatPaddleLeftPivot as THREE.Object3D | undefined,
+        mesh.userData.boatPaddleRightPivot as THREE.Object3D | undefined,
+        this.boatPaddleScratch
+      )
     }
   }
 
+  private applyLocalThirdPersonPlayerRotation() {
+    const entity = this.playerEntity
+    if (!entity?.visible || !entity.playerObject) return
+
+    const rotation = this.worldRenderer.cameraShake.getBaseRotation()
+    const isAnchoredPassenger = entity.userData._passengerVehicleId != null || entity.userData._boatPassengerVehicleId != null
+    const anchoredVehicleId = entity.userData._passengerVehicleId ?? entity.userData._boatPassengerVehicleId
+    const vehicle = anchoredVehicleId != null ? this.entities[anchoredVehicleId] : undefined
+    const vehicleName = vehicle?.['realName'] ?? vehicle?.originalEntity.name
+    const vehicleYaw = vehicle?.rotation.y
+
+    if (
+      shouldApplyBoatPassengerThirdPersonRotation({
+        isThirdPerson: true,
+        isAnchoredPassenger,
+        vehicleName,
+        vehicleYaw
+      })
+    ) {
+      const resolved = resolveBoatPassengerThirdPersonRotation({
+        cameraYaw: rotation.yaw,
+        cameraPitch: rotation.pitch,
+        vehicleYaw: vehicleYaw!
+      })
+      entity.rotation.set(0, resolved.bodyYaw, 0)
+      entity.traverse(child => {
+        if (child.name !== 'head') return
+        child.rotation.set(resolved.headPitch, resolved.headYaw, 0)
+      })
+    } else {
+      entity.rotation.set(0, rotation.yaw, 0)
+      entity.traverse(child => {
+        if (child.name !== 'head') return
+        child.rotation.set(-rotation.pitch, 0, 0)
+      })
+    }
+
+    this.syncArmorPositions(entity)
+  }
+
+  private resolvePassengerEntity(passengerId: number): SceneEntity | undefined {
+    if (this.playerEntity?.originalEntity.id === passengerId) {
+      return this.playerEntity
+    }
+    return this.entities[passengerId]
+  }
+
+  private resolveLocalVehicleRenderWorldPos(sceneEntity: SceneEntity): Vec3Like {
+    const originalEntity = sceneEntity.originalEntity
+    const renderHints = sceneEntity.userData.renderHints as EntityRenderHints | undefined
+    const rawVehicleY = sceneEntity.userData._localVehicleY ?? originalEntity.position?.y ?? sceneEntity.position.y
+    return resolveLocalVehicleWorldPosition({
+      cameraWorldPos: this.worldRenderer.cameraWorldPos,
+      rawVehicleY,
+      eyeHeight: this.worldRenderer.playerStateReactive.eyeHeight,
+      vehicleName: sceneEntity['realName'] ?? originalEntity.name,
+      vehicleHeight: originalEntity.height ?? 1.6,
+      verticalCameraLock: renderHints?.localVehicleVerticalCameraLock
+    })
+  }
+
+  updateVehiclePassengerPositions() {
+    applyVehiclePassengerPositions({
+      entities: this.entities,
+      localPlayer: this.playerEntity,
+      getWorldPosition: target => this.worldRenderer.sceneOrigin.getWorldPosition(target as SceneEntity)
+    })
+  }
+
+  /** @deprecated Use updateVehiclePassengerPositions */
+  updateBoatPassengerPositions() {
+    this.updateVehiclePassengerPositions()
+  }
+
   private syncArmorPositions(entity: SceneEntity) {
     if (!entity.playerObject) return
 
@@ -746,7 +928,10 @@ export class Entities {
     }
   }
 
-  private applyMovementAnimation(playerObject: PlayerObjectType, animation: 'walking' | 'running' | 'oneSwing' | 'idle' | 'crouch' | 'crouchWalking'): void {
+  private applyMovementAnimation(
+    playerObject: PlayerObjectType,
+    animation: 'walking' | 'running' | 'oneSwing' | 'idle' | 'crouch' | 'crouchWalking' | 'riding'
+  ): void {
     const anim = playerObject.animation as WalkingGeneralSwing | undefined
     if (!anim) return
 
@@ -756,12 +941,21 @@ export class Entities {
     }
 
     anim.switchAnimationCallback = null
+    if (animation === 'riding') {
+      anim.isMoving = false
+      anim.isRunning = false
+      anim.isCrouched = false
+      anim.isRiding = true
+      return
+    }
+
+    anim.isRiding = false
     anim.isMoving = animation === 'walking' || animation === 'running' || animation === 'crouchWalking'
     anim.isRunning = animation === 'running'
     anim.isCrouched = animation === 'crouch' || animation === 'crouchWalking'
   }
 
-  playAnimation(entityPlayerId, animation: 'walking' | 'running' | 'oneSwing' | 'idle' | 'crouch' | 'crouchWalking') {
+  playAnimation(entityPlayerId, animation: 'walking' | 'running' | 'oneSwing' | 'idle' | 'crouch' | 'crouchWalking' | 'riding') {
     const playerObject =
       entityPlayerId === 'player_entity' ? this.playerEntity?.playerObject : (this.getPlayerObject(entityPlayerId) ?? this.playerEntity?.playerObject)
 
@@ -881,6 +1075,10 @@ export class Entities {
       if (!e) return
       e.userData._posTween?.stop()
       e.userData._rotTween?.stop()
+      e.userData[HORSE_HEAD_ANIMATION_USER_DATA_KEY] = undefined
+      e.userData[HORSE_HEAD_RIG_USER_DATA_KEY] = undefined
+      const boatMesh = e.children.find(c => c.name === 'mesh')
+      if (boatMesh) disposeBoatWaterPatch(boatMesh)
       if (e.additionalCleanup) e.additionalCleanup()
       e.traverse(c => {
         if (c['additionalCleanup']) c['additionalCleanup']()
@@ -892,6 +1090,7 @@ export class Entities {
       delete this.entities[entity.id]
       return
     }
+    if (!this.isRenderingAllowed()) return
 
     let mesh: THREE.Object3D | undefined
     if (e === undefined) {
@@ -971,6 +1170,11 @@ export class Entities {
       }
       if (!mesh) return
       mesh.name = 'mesh'
+      const boatMeshYawOffset = getBoatMeshYawOffset(entity.name)
+      if (boatMeshYawOffset != null) {
+        mesh.rotation.y = boatMeshYawOffset
+        setupBoatMesh(mesh)
+      }
       // set initial position so there are no weird jumps update after
       const pos = entity.pos ?? entity.position
       this.worldRenderer.sceneOrigin.track(group)
@@ -985,7 +1189,6 @@ export class Entities {
       group.add(mesh)
       group.add(boxHelper)
       boxHelper.visible = false
-      this.worldRenderer.scene.add(group)
 
       e = group
       e.name = 'entity'
@@ -996,13 +1199,23 @@ export class Entities {
         void this.updatePlayerSkin(entity.id, entity.username, overrides?.texture ? entity.uuid : undefined, overrides?.texture || stevePngUrl)
       }
       this.setDebugMode(this.debugMode, group)
-      this.setRendering(this.currentlyRendering, group)
+      this.syncSceneAttachment(group)
 
       this.afterAddEntity(entity)
+      const horseHeadRig = mesh.userData[HORSE_HEAD_RIG_USER_DATA_KEY] as HorseHeadRig | undefined
+      if (horseHeadRig) {
+        e.userData[HORSE_HEAD_RIG_USER_DATA_KEY] = horseHeadRig
+        e.userData[HORSE_HEAD_ANIMATION_USER_DATA_KEY] = createHorseHeadAnimationState()
+      }
     } else {
       mesh = e.children.find(c => c.name === 'mesh')
+      if (entity.renderHints) {
+        e.originalEntity.renderHints = entity.renderHints
+      }
     }
 
+    this.applyEntityRenderHints(e, entity)
+
     // Update equipment
     this.updateEntityEquipment(e, entity)
 
@@ -1194,26 +1407,88 @@ export class Entities {
     this.updateEntityPosition(entity, justAdded, overrides)
   }
 
-  updateEntityPosition(entity: import('prismarine-entity').Entity, justAdded: boolean, overrides: { rotation?: { head?: { y: number; x: number } } }) {
+  applyEntityRenderHints(e: SceneEntity, entity: SceneEntity['originalEntity']) {
+    if (entity.renderHints) {
+      const hints = entity.renderHints as EntityRenderHints
+      const nextPassengerIds = new Set(hints.passengerIds ?? hints.boatPassengerIds ?? [])
+      const previousPassengerIds = e.userData.renderHints?.passengerIds ?? e.userData.renderHints?.boatPassengerIds ?? []
+      const isPassengerVehicle = isBoatEntityName(entity.name) || isRideableMinecartEntityName(entity.name)
+      if (isPassengerVehicle) {
+        for (const previousPassengerId of previousPassengerIds) {
+          if (nextPassengerIds.has(previousPassengerId)) continue
+          const previousPassenger = this.resolvePassengerEntity(previousPassengerId)
+          if (previousPassenger) {
+            releaseVehiclePassengerPosition(previousPassenger, String(entity.id), this.worldRenderer.sceneOrigin.getWorldPosition(previousPassenger))
+          }
+        }
+      }
+      e.userData.renderHints = entity.renderHints
+    }
+    if (!isBoatEntityName(entity.name)) return
+    const mesh = e.children.find(c => c.name === 'mesh')
+    if (!mesh) return
+    const waterPatch = mesh.userData.boatWaterPatch as THREE.Object3D | undefined
+    if (waterPatch) {
+      waterPatch.visible = entity.renderHints?.boatWaterPatchVisible === true
+    }
+
+    const hints = (e.userData.renderHints ?? entity.renderHints) as EntityRenderHints | undefined
+    const leftActive = hints?.boatPaddleLeft === true
+    const rightActive = hints?.boatPaddleRight === true
+    let animState = mesh.userData.boatPaddleAnimation as BoatPaddleAnimationState | undefined
+    if (!animState) {
+      animState = createBoatPaddleAnimationState()
+      mesh.userData.boatPaddleAnimation = animState
+    }
+    syncBoatPaddleAnimationTargets(animState, leftActive, rightActive)
+  }
+
+  updateEntityPosition(
+    entity: SceneEntity['originalEntity'],
+    justAdded: boolean,
+    overrides: { rotation?: { head?: { y: number; x: number } } },
+    headRotationOnly = false
+  ) {
     const e = this.entities[entity.id]
     if (!e) return
-    const ANIMATION_DURATION = justAdded ? 0 : TWEEN_DURATION
+    this.applyEntityRenderHints(e, entity)
+    if (e.userData[HORSE_HEAD_RIG_USER_DATA_KEY]) {
+      e.userData._horseHeadPitch = typeof entity.pitch === 'number' && Number.isFinite(entity.pitch) ? entity.pitch : 0
+      const headYaw = (entity as any).headYaw
+      e.userData._horseHeadYaw = typeof headYaw === 'number' && Number.isFinite(headYaw) ? headYaw : entity.yaw
+      e.userData._horseBodyYaw = typeof entity.yaw === 'number' && Number.isFinite(entity.yaw) ? entity.yaw : 0
+    }
+    const cameraSynced = usesCameraSyncedVehiclePosition(entity)
     if (entity.position) {
-      // Initialize tween target from current world position
-      const currentWorld = this.worldRenderer.sceneOrigin.getWorldPosition(e) ?? { x: entity.position.x, y: entity.position.y, z: entity.position.z }
-      if (!e.userData._tweenTarget) {
-        e.userData._tweenTarget = { x: currentWorld.x, y: currentWorld.y, z: currentWorld.z }
+      if (cameraSynced) {
+        e.userData._localVehicleY = entity.position.y
+        e.userData._posTween?.stop()
+        e.userData._posTween = undefined
+        const worldPos = this.resolveLocalVehicleRenderWorldPos(e)
+        e.position.set(worldPos.x, worldPos.y, worldPos.z)
+      } else {
+        const ANIMATION_DURATION = getEntityTweenDurationMs(entity, justAdded)
+        // Initialize tween target from current world position
+        const currentWorld = this.worldRenderer.sceneOrigin.getWorldPosition(e) ?? { x: entity.position.x, y: entity.position.y, z: entity.position.z }
+        if (!e.userData._tweenTarget) {
+          e.userData._tweenTarget = { x: currentWorld.x, y: currentWorld.y, z: currentWorld.z }
+        }
+        // Stop previous position tween to prevent accumulation
+        e.userData._posTween?.stop()
+        // Tween a separate target object, apply via proxy on each update
+        e.userData._posTween = new TWEEN.Tween(e.userData._tweenTarget)
+          .to({ x: entity.position.x, y: entity.position.y, z: entity.position.z }, ANIMATION_DURATION)
+          .onUpdate(() => {
+            e.position.set(e.userData._tweenTarget.x, e.userData._tweenTarget.y, e.userData._tweenTarget.z)
+          })
+          .start()
+      }
+      const horseAnimation = e.userData[HORSE_HEAD_ANIMATION_USER_DATA_KEY] as HorseHeadAnimationState | undefined
+      if (!headRotationOnly && horseAnimation && Number.isFinite(entity.position.x) && Number.isFinite(entity.position.z)) {
+        setHorseHeadAnimationPosition(horseAnimation, entity.position)
       }
-      // Stop previous position tween to prevent accumulation
-      e.userData._posTween?.stop()
-      // Tween a separate target object, apply via proxy on each update
-      e.userData._posTween = new TWEEN.Tween(e.userData._tweenTarget)
-        .to({ x: entity.position.x, y: entity.position.y, z: entity.position.z }, ANIMATION_DURATION)
-        .onUpdate(() => {
-          e.position.set(e.userData._tweenTarget.x, e.userData._tweenTarget.y, e.userData._tweenTarget.z)
-        })
-        .start()
     }
+    const rotationTweenDuration = getEntityRotationTweenDurationMs(entity, justAdded)
     /** World yaw for the whole model: for PlayerObject skins, rotate body to head look dir; head mesh stays yaw-fixed (pitch only). */
     let targetYaw: number | undefined
     if (e.playerObject && overrides?.rotation?.head) {
@@ -1226,18 +1501,29 @@ export class Entities {
       targetYaw = entity.yaw
     }
     if (typeof targetYaw === 'number' && Number.isFinite(targetYaw)) {
-      const dy = shortestYawRadians(e.rotation.y, targetYaw)
       // Stop previous rotation tween to prevent accumulation (mirror _posTween)
       e.userData._rotTween?.stop()
-      e.userData._rotTween = new TWEEN.Tween(e.rotation).to({ y: e.rotation.y + dy }, ANIMATION_DURATION).start()
+      e.userData._rotTween = undefined
+      const currentYaw = Number.isFinite(e.rotation.y) ? e.rotation.y : 0
+      const dy = shortestYawRadians(currentYaw, targetYaw)
+      if (rotationTweenDuration === 0) {
+        e.rotation.y = currentYaw + dy
+      } else {
+        e.userData._rotTween = new TWEEN.Tween(e.rotation).to({ y: currentYaw + dy }, rotationTweenDuration).start()
+      }
     }
 
     if (e?.playerObject && overrides?.rotation?.head) {
       const { playerObject } = e
+      const hy = overrides.rotation.head.y
+      storeNetworkHeadYaw(e.userData, hy, entity.yaw)
       playerObject.skin.head.rotation.y = 0
 
       const hp = overrides.rotation.head.x
-      playerObject.skin.head.rotation.x = typeof hp === 'number' && Number.isFinite(hp) ? -hp : 0
+      storeNetworkHeadPitch(e.userData, hp)
+      applyNetworkHeadPitch(playerObject, e.userData)
+    } else if (e?.playerObject && typeof entity.yaw === 'number' && Number.isFinite(entity.yaw)) {
+      storeNetworkHeadYaw(e.userData, undefined, entity.yaw)
     }
   }
 

package/src/three/entity/EntityMesh.ts

@@ -14,6 +14,9 @@ import entities from './entities.json'
 import { externalModels } from './objModels'
 import externalTexturesJson from './externalTextures.json'
 import { createAnimatedObject } from './gltfAnimationUtils'
+import { BOAT_OBJ_OFFSET_Y } from './boatRenderSetup'
+import { VANILLA_117_HORSE_ENTITY_SCALES } from './horseEntityScale'
+import { createHorseHeadRig } from './horseHeadAnimation'
 
 interface ElemFace {
   dir: [number, number, number]
@@ -441,6 +444,7 @@ const getEntity = (name: string) => {
 }
 
 const scaleEntity: Record<string, number> = {
+  ...VANILLA_117_HORSE_ENTITY_SCALES,
   zombie: 1.85,
   husk: 1.85,
   arrow: 0.0025
@@ -449,7 +453,7 @@ const scaleEntity: Record<string, number> = {
 const offsetEntity: Record<string, Vec3> = {
   zombie: new Vec3(0, 1, 0),
   husk: new Vec3(0, 1, 0),
-  boat: new Vec3(0, -1, 0),
+  boat: new Vec3(0, BOAT_OBJ_OFFSET_Y, 0),
   arrow: new Vec3(0, -0.9, 0)
 }
 
@@ -627,14 +631,14 @@ export class EntityMesh {
       const obj = objLoader.parse(externalModels[type])
       const scale = scaleEntity[originalType] || scaleEntity[type]
       if (scale) obj.scale.set(scale, scale, scale)
-      const offset = offsetEntity[originalType]
+      const offset = offsetEntity[originalType] ?? offsetEntity[type]
       if (offset) obj.position.set(offset.x, offset.y, offset.z)
       obj.traverse(child => {
         if (child instanceof THREE.Mesh) {
           child.material = material
           // todo
           if (child.name === 'Head layer') child.visible = false
-          if (child.name === 'Head' && overrides.rotation?.head) {
+          if (type !== 'horse' && child.name === 'Head' && overrides.rotation?.head) {
             // todo
             child.rotation.x -= ((overrides.rotation.head.x ?? 0) * Math.PI) / 180
             child.rotation.y -= ((overrides.rotation.head.y ?? 0) * Math.PI) / 180
@@ -642,6 +646,7 @@ export class EntityMesh {
           }
         }
       })
+      if (type === 'horse') createHorseHeadRig(obj)
       this.mesh = obj
       debugFlags.type = 'obj'
       return