minecraft-renderer 0.1.92 → 0.1.94

package/src/three/entity/animations.js

@@ -32,6 +32,7 @@ export class WalkingGeneralSwing extends PlayerAnimation {
   isRunning = false
   isMoving = true
   isCrouched = false
+  isRiding = false
 
   _dt = 0
   _phase = 0
@@ -127,7 +128,7 @@ export class WalkingGeneralSwing extends PlayerAnimation {
     if (!this._defaults) this._captureDefaults(player)
     this._applyDefaults(player)
 
-    const targetMove = this.isMoving ? 1 : 0
+    const targetMove = this.isRiding ? 0 : this.isMoving ? 1 : 0
     const kMove = Math.min(1, dt * 20)
     this._moveBlend += (targetMove - this._moveBlend) * kMove
 
@@ -139,35 +140,46 @@ export class WalkingGeneralSwing extends PlayerAnimation {
 
     applyCrouchPose(player, this.isCrouched ? 1 : 0)
 
-    const boundary = this.isRunning ? Math.cos(t) : Math.sin(t)
-    if (Math.abs(boundary) < 0.02) {
-      if (this.switchAnimationCallback) {
-        reset = true
-      }
-    }
+    if (this.isRiding) {
+      player.skin.rightArm.rotation.x -= Math.PI / 5
+      player.skin.leftArm.rotation.x -= Math.PI / 5
 
-    if (this.isRunning) {
-      player.skin.leftLeg.rotation.x += Math.cos(t + Math.PI) * 1.3 * this._moveBlend
-      player.skin.rightLeg.rotation.x += Math.cos(t) * 1.3 * this._moveBlend
+      // Vanilla HumanoidModel uses ModelPart Z→Y→X order with yRot/zRot signs as in Java.
+      // skinview3d Y/Z axes are opposite the Java model, so ZYX plus inverted Y/Z signs
+      // matches vanilla Rz × Ry × Rx (see BOAT_RIDING_LEG_SPREAD.md).
+      player.skin.rightLeg.rotation.set(-1.4137167, -Math.PI / 10, -Math.PI / 40, 'ZYX')
+      player.skin.leftLeg.rotation.set(-1.4137167, Math.PI / 10, Math.PI / 40, 'ZYX')
     } else {
-      player.skin.leftLeg.rotation.x += Math.sin(t) * 0.5 * this._moveBlend
-      player.skin.rightLeg.rotation.x += Math.sin(t + Math.PI) * 0.5 * this._moveBlend
-    }
+      const boundary = this.isRunning ? Math.cos(t) : Math.sin(t)
+      if (Math.abs(boundary) < 0.02) {
+        if (this.switchAnimationCallback) {
+          reset = true
+        }
+      }
 
-    if (this.isRunning) {
-      player.skin.leftArm.rotation.x += Math.cos(t) * 1.5 * this._moveBlend
-      player.skin.rightArm.rotation.x += Math.cos(t + Math.PI) * 1.5 * this._moveBlend
+      if (this.isRunning) {
+        player.skin.leftLeg.rotation.x += Math.cos(t + Math.PI) * 1.3 * this._moveBlend
+        player.skin.rightLeg.rotation.x += Math.cos(t) * 1.3 * this._moveBlend
+      } else {
+        player.skin.leftLeg.rotation.x += Math.sin(t) * 0.5 * this._moveBlend
+        player.skin.rightLeg.rotation.x += Math.sin(t + Math.PI) * 0.5 * this._moveBlend
+      }
 
-      const basicArmRotationZ = Math.PI * 0.1
-      player.skin.leftArm.rotation.z += (Math.cos(t) * 0.1 + basicArmRotationZ) * this._moveBlend
-      player.skin.rightArm.rotation.z += (Math.cos(t + Math.PI) * 0.1 - basicArmRotationZ) * this._moveBlend
-    } else {
-      player.skin.leftArm.rotation.x += Math.sin(t + Math.PI) * 0.5 * this._moveBlend
-      player.skin.rightArm.rotation.x += Math.sin(t) * 0.5 * this._moveBlend
+      if (this.isRunning) {
+        player.skin.leftArm.rotation.x += Math.cos(t) * 1.5 * this._moveBlend
+        player.skin.rightArm.rotation.x += Math.cos(t + Math.PI) * 1.5 * this._moveBlend
 
-      const basicArmRotationZ = Math.PI * 0.02
-      player.skin.leftArm.rotation.z += (Math.cos(t) * 0.03 + basicArmRotationZ) * this._moveBlend
-      player.skin.rightArm.rotation.z += (Math.cos(t + Math.PI) * 0.03 - basicArmRotationZ) * this._moveBlend
+        const basicArmRotationZ = Math.PI * 0.1
+        player.skin.leftArm.rotation.z += (Math.cos(t) * 0.1 + basicArmRotationZ) * this._moveBlend
+        player.skin.rightArm.rotation.z += (Math.cos(t + Math.PI) * 0.1 - basicArmRotationZ) * this._moveBlend
+      } else {
+        player.skin.leftArm.rotation.x += Math.sin(t + Math.PI) * 0.5 * this._moveBlend
+        player.skin.rightArm.rotation.x += Math.sin(t) * 0.5 * this._moveBlend
+
+        const basicArmRotationZ = Math.PI * 0.02
+        player.skin.leftArm.rotation.z += (Math.cos(t) * 0.03 + basicArmRotationZ) * this._moveBlend
+        player.skin.rightArm.rotation.z += (Math.cos(t + Math.PI) * 0.03 - basicArmRotationZ) * this._moveBlend
+      }
     }
 
     if (this._swingTime !== null) {

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

@@ -0,0 +1,249 @@
+//@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'
+
+const RIDING_LEG_X = -1.4137167
+const VANILLA_RIDING_LEG_Y = Math.PI / 10
+const VANILLA_RIDING_LEG_Z = Math.PI / 40
+const SKINVIEW_RIDING_LEG_Y = -VANILLA_RIDING_LEG_Y
+const SKINVIEW_RIDING_LEG_Z = -VANILLA_RIDING_LEG_Z
+const RIDING_LEG_ORDER = 'ZYX'
+const RIDING_ARM_DELTA = Math.PI / 5
+
+const YZ_AXIS_FLIP = new THREE.Matrix4().makeScale(1, -1, -1)
+
+function makePlayerObject(): PlayerObjectType {
+  const playerObject = new PlayerObject() as PlayerObjectType
+  playerObject.skin.leftLeg.rotation.set(0.1, 0.05, -0.02)
+  playerObject.skin.rightLeg.rotation.set(-0.08, -0.04, 0.03)
+  playerObject.skin.leftArm.rotation.set(0.2, 0, 0.01)
+  playerObject.skin.rightArm.rotation.set(-0.15, 0, -0.01)
+  return playerObject
+}
+
+function captureRotations(playerObject: PlayerObjectType) {
+  const { leftArm, rightArm, leftLeg, rightLeg } = playerObject.skin
+  return {
+    leftArm: leftArm.rotation.clone(),
+    rightArm: rightArm.rotation.clone(),
+    leftLeg: leftLeg.rotation.clone(),
+    rightLeg: rightLeg.rotation.clone()
+  }
+}
+
+function runAnimationFrame(animation: WalkingGeneralSwing, playerObject: PlayerObjectType, dt = 0.05) {
+  animation.update(playerObject, dt)
+}
+
+function makeJavaRidingLegMatrix(ySign: 1 | -1): THREE.Matrix4 {
+  return new THREE.Matrix4().makeRotationFromEuler(new THREE.Euler(RIDING_LEG_X, ySign * VANILLA_RIDING_LEG_Y, ySign * VANILLA_RIDING_LEG_Z, RIDING_LEG_ORDER))
+}
+
+function makeSkinviewRidingLegMatrix(y: number, z: number): THREE.Matrix4 {
+  return new THREE.Matrix4().makeRotationFromEuler(new THREE.Euler(RIDING_LEG_X, y, z, RIDING_LEG_ORDER))
+}
+
+function conjugateYzAxisFlip(rotationMatrix: THREE.Matrix4): THREE.Matrix4 {
+  return YZ_AXIS_FLIP.clone().multiply(rotationMatrix).multiply(YZ_AXIS_FLIP.clone())
+}
+
+function expectMatrixNear(a: THREE.Matrix4, b: THREE.Matrix4) {
+  for (let i = 0; i < 16; i++) {
+    expect(a.elements[i]).toBeCloseTo(b.elements[i])
+  }
+}
+
+function expectRidingLegPose(playerObject: PlayerObjectType) {
+  expect(playerObject.skin.rightLeg.rotation.order).toBe(RIDING_LEG_ORDER)
+  expect(playerObject.skin.rightLeg.rotation.x).toBeCloseTo(RIDING_LEG_X)
+  expect(playerObject.skin.rightLeg.rotation.y).toBeCloseTo(SKINVIEW_RIDING_LEG_Y)
+  expect(playerObject.skin.rightLeg.rotation.z).toBeCloseTo(SKINVIEW_RIDING_LEG_Z)
+
+  expect(playerObject.skin.leftLeg.rotation.order).toBe(RIDING_LEG_ORDER)
+  expect(playerObject.skin.leftLeg.rotation.x).toBeCloseTo(RIDING_LEG_X)
+  expect(playerObject.skin.leftLeg.rotation.y).toBeCloseTo(-SKINVIEW_RIDING_LEG_Y)
+  expect(playerObject.skin.leftLeg.rotation.z).toBeCloseTo(-SKINVIEW_RIDING_LEG_Z)
+}
+
+test('riding sets ZYX leg rotations with inverted Y/Z signs for skinview3d axes', () => {
+  const playerObject = makePlayerObject()
+  const animation = new WalkingGeneralSwing()
+  animation._captureDefaults(playerObject)
+  animation.isRiding = true
+
+  runAnimationFrame(animation, playerObject)
+
+  expectRidingLegPose(playerObject)
+})
+
+test('riding leg rotation matrix matches vanilla after Y/Z axis conversion', () => {
+  const javaRight = makeJavaRidingLegMatrix(1)
+  const skinviewRight = makeSkinviewRidingLegMatrix(SKINVIEW_RIDING_LEG_Y, SKINVIEW_RIDING_LEG_Z)
+  expectMatrixNear(conjugateYzAxisFlip(skinviewRight), javaRight)
+
+  const javaLeft = makeJavaRidingLegMatrix(-1)
+  const skinviewLeft = makeSkinviewRidingLegMatrix(-SKINVIEW_RIDING_LEG_Y, -SKINVIEW_RIDING_LEG_Z)
+  expectMatrixNear(conjugateYzAxisFlip(skinviewLeft), javaLeft)
+})
+
+test('animated riding legs match expected rotation matrices', () => {
+  const playerObject = makePlayerObject()
+  const animation = new WalkingGeneralSwing()
+  animation._captureDefaults(playerObject)
+  animation.isRiding = true
+  runAnimationFrame(animation, playerObject)
+
+  playerObject.skin.rightLeg.updateMatrix()
+  playerObject.skin.leftLeg.updateMatrix()
+
+  const rightRot = new THREE.Matrix4().extractRotation(playerObject.skin.rightLeg.matrix)
+  const leftRot = new THREE.Matrix4().extractRotation(playerObject.skin.leftLeg.matrix)
+
+  expectMatrixNear(rightRot, makeSkinviewRidingLegMatrix(SKINVIEW_RIDING_LEG_Y, SKINVIEW_RIDING_LEG_Z))
+  expectMatrixNear(leftRot, makeSkinviewRidingLegMatrix(-SKINVIEW_RIDING_LEG_Y, -SKINVIEW_RIDING_LEG_Z))
+})
+
+test('riding applies arm X delta relative to defaults', () => {
+  const playerObject = makePlayerObject()
+  const defaults = captureRotations(playerObject)
+  const animation = new WalkingGeneralSwing()
+  animation._captureDefaults(playerObject)
+  animation.isRiding = true
+
+  runAnimationFrame(animation, playerObject)
+
+  expect(playerObject.skin.rightArm.rotation.x).toBeCloseTo(defaults.rightArm.x - RIDING_ARM_DELTA)
+  expect(playerObject.skin.leftArm.rotation.x).toBeCloseTo(defaults.leftArm.x - RIDING_ARM_DELTA)
+})
+
+test('riding does not apply old arm Z spread', () => {
+  const playerObject = makePlayerObject()
+  const defaults = captureRotations(playerObject)
+  const animation = new WalkingGeneralSwing()
+  animation._captureDefaults(playerObject)
+  animation.isRiding = true
+
+  runAnimationFrame(animation, playerObject)
+
+  expect(playerObject.skin.leftArm.rotation.z).toBeCloseTo(defaults.leftArm.z)
+  expect(playerObject.skin.rightArm.rotation.z).toBeCloseTo(defaults.rightArm.z)
+})
+
+test('idle to riding to idle restores limb rotations including order', () => {
+  const playerObject = makePlayerObject()
+  const animation = new WalkingGeneralSwing()
+  animation._captureDefaults(playerObject)
+  const defaults = captureRotations(playerObject)
+
+  animation.isMoving = false
+  runAnimationFrame(animation, playerObject)
+  const idleRotations = captureRotations(playerObject)
+
+  animation.isRiding = true
+  runAnimationFrame(animation, playerObject)
+  expectRidingLegPose(playerObject)
+
+  animation.isRiding = false
+  animation.isMoving = false
+  runAnimationFrame(animation, playerObject)
+  const restored = captureRotations(playerObject)
+
+  expect(restored.leftArm.x).toBeCloseTo(idleRotations.leftArm.x)
+  expect(restored.leftArm.y).toBeCloseTo(idleRotations.leftArm.y)
+  expect(restored.leftArm.z).toBeCloseTo(idleRotations.leftArm.z)
+  expect(restored.leftArm.order).toBe(idleRotations.leftArm.order)
+  expect(restored.rightArm.x).toBeCloseTo(idleRotations.rightArm.x)
+  expect(restored.rightArm.y).toBeCloseTo(idleRotations.rightArm.y)
+  expect(restored.rightArm.z).toBeCloseTo(idleRotations.rightArm.z)
+  expect(restored.rightArm.order).toBe(idleRotations.rightArm.order)
+  expect(restored.leftLeg.x).toBeCloseTo(defaults.leftLeg.x)
+  expect(restored.leftLeg.y).toBeCloseTo(defaults.leftLeg.y)
+  expect(restored.leftLeg.z).toBeCloseTo(defaults.leftLeg.z)
+  expect(restored.leftLeg.order).toBe(defaults.leftLeg.order)
+  expect(restored.rightLeg.x).toBeCloseTo(defaults.rightLeg.x)
+  expect(restored.rightLeg.y).toBeCloseTo(defaults.rightLeg.y)
+  expect(restored.rightLeg.z).toBeCloseTo(defaults.rightLeg.z)
+  expect(restored.rightLeg.order).toBe(defaults.rightLeg.order)
+})
+
+test('multiple riding frames do not accumulate angles', () => {
+  const playerObject = makePlayerObject()
+  const animation = new WalkingGeneralSwing()
+  animation._captureDefaults(playerObject)
+  animation.isRiding = true
+
+  runAnimationFrame(animation, playerObject)
+  const firstFrame = captureRotations(playerObject)
+
+  for (let i = 0; i < 10; i++) {
+    runAnimationFrame(animation, playerObject)
+  }
+  const lastFrame = captureRotations(playerObject)
+
+  expect(lastFrame.leftLeg.x).toBeCloseTo(firstFrame.leftLeg.x)
+  expect(lastFrame.leftLeg.y).toBeCloseTo(firstFrame.leftLeg.y)
+  expect(lastFrame.leftLeg.z).toBeCloseTo(firstFrame.leftLeg.z)
+  expect(lastFrame.leftLeg.order).toBe(firstFrame.leftLeg.order)
+  expect(lastFrame.rightLeg.x).toBeCloseTo(firstFrame.rightLeg.x)
+  expect(lastFrame.rightLeg.y).toBeCloseTo(firstFrame.rightLeg.y)
+  expect(lastFrame.rightLeg.z).toBeCloseTo(firstFrame.rightLeg.z)
+  expect(lastFrame.rightLeg.order).toBe(firstFrame.rightLeg.order)
+  expect(lastFrame.leftArm.x).toBeCloseTo(firstFrame.leftArm.x)
+  expect(lastFrame.rightArm.x).toBeCloseTo(firstFrame.rightArm.x)
+})
+
+test('oneSwing during riding keeps isRiding enabled', () => {
+  const playerObject = makePlayerObject()
+  const animation = new WalkingGeneralSwing()
+  animation._captureDefaults(playerObject)
+  animation.isRiding = true
+
+  animation.swingArm()
+  runAnimationFrame(animation, playerObject)
+
+  expect(animation.isRiding).toBe(true)
+})
+
+test('oneSwing during riding keeps legs in riding pose', () => {
+  const playerObject = makePlayerObject()
+  const animation = new WalkingGeneralSwing()
+  animation._captureDefaults(playerObject)
+  animation.isRiding = true
+
+  animation.swingArm()
+  runAnimationFrame(animation, playerObject)
+
+  expectRidingLegPose(playerObject)
+})
+
+test('leg armor attached to legs follows riding Y/Z rotations', () => {
+  const playerObject = makePlayerObject()
+  const leftLegArmor = new THREE.Group()
+  const rightLegArmor = new THREE.Group()
+  playerObject.skin.leftLeg.add(leftLegArmor)
+  playerObject.skin.rightLeg.add(rightLegArmor)
+
+  const animation = new WalkingGeneralSwing()
+  animation._captureDefaults(playerObject)
+  animation.isRiding = true
+  runAnimationFrame(animation, playerObject)
+
+  expectRidingLegPose(playerObject)
+
+  leftLegArmor.updateMatrixWorld(true)
+  rightLegArmor.updateMatrixWorld(true)
+  const leftWorldQuat = new THREE.Quaternion()
+  const rightWorldQuat = new THREE.Quaternion()
+  leftLegArmor.getWorldQuaternion(leftWorldQuat)
+  rightLegArmor.getWorldQuaternion(rightWorldQuat)
+  const leftWorldEuler = new THREE.Euler().setFromQuaternion(leftWorldQuat, 'XYZ')
+  const rightWorldEuler = new THREE.Euler().setFromQuaternion(rightWorldQuat, 'XYZ')
+
+  expect(leftWorldEuler.y).not.toBeCloseTo(0)
+  expect(leftWorldEuler.z).not.toBeCloseTo(0)
+  expect(rightWorldEuler.y).not.toBeCloseTo(0)
+  expect(rightWorldEuler.z).not.toBeCloseTo(0)
+})

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

@@ -0,0 +1,29 @@
+//@ts-nocheck
+import { expect, test } from 'vitest'
+import { BOAT_MESH_YAW_OFFSET, getBoatMeshYawOffset, isBoatEntityName } from './boatModelRotation'
+
+test('boat mesh yaw offset is -90°', () => {
+  expect(BOAT_MESH_YAW_OFFSET).toBe(-Math.PI / 2)
+})
+
+test.each([
+  'boat',
+  'chest_boat',
+  'oak_boat',
+  'spruce_boat',
+  'birch_boat',
+  'jungle_boat',
+  'acacia_boat',
+  'dark_oak_boat',
+  'mangrove_boat',
+  'cherry_boat',
+  'bamboo_raft'
+])('detects boat entity %s', name => {
+  expect(isBoatEntityName(name)).toBe(true)
+  expect(getBoatMeshYawOffset(name)).toBe(BOAT_MESH_YAW_OFFSET)
+})
+
+test.each(['minecart', 'horse', 'player', 'item', 'oak_boat_with_chest'])('ignores non-boat entity %s', name => {
+  expect(isBoatEntityName(name)).toBe(false)
+  expect(getBoatMeshYawOffset(name)).toBeNull()
+})

package/src/three/entity/boatModelRotation.ts

@@ -0,0 +1,14 @@
+//@ts-nocheck
+/** OBJ boat models face -X at yaw=0; physics forward is -Z → rotate mesh locally. */
+export const BOAT_MESH_YAW_OFFSET = -Math.PI / 2
+
+export function isBoatEntityName(entityName: string | undefined): boolean {
+  if (!entityName) return false
+  const name = entityName.toLowerCase()
+  if (name === 'boat' || name === 'chest_boat') return true
+  return name.endsWith('_boat') || name.endsWith('_raft')
+}
+
+export function getBoatMeshYawOffset(entityName: string | undefined): number | null {
+  return isBoatEntityName(entityName) ? BOAT_MESH_YAW_OFFSET : null
+}

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

@@ -0,0 +1,108 @@
+//@ts-nocheck
+import * as THREE from 'three'
+import { expect, test } from 'vitest'
+import {
+  BOAT_PADDLE_RADIANS_PER_SECOND,
+  BOAT_PADDLE_STEP,
+  advanceBoatPaddlePhase,
+  createBoatPaddlePivotScratch,
+  getBoatPaddleRelativeQuaternion,
+  getVanillaBoatPaddleAngles,
+  syncBoatPaddleAnimationTargets,
+  updateBoatPaddleAnimationState,
+  createBoatPaddleAnimationState
+} from './boatPaddleAnimation'
+
+test('50ms active advancement equals pi/8', () => {
+  expect(advanceBoatPaddlePhase(0, true, 0.05)).toBeCloseTo(BOAT_PADDLE_STEP, 5)
+})
+
+test('equal elapsed time split across frame sizes gives the same phase', () => {
+  const total = 0.1
+  const single = advanceBoatPaddlePhase(0, true, total)
+  const split = advanceBoatPaddlePhase(advanceBoatPaddlePhase(0, true, total / 2), true, total / 2)
+  expect(split).toBeCloseTo(single, 5)
+})
+
+test('inactive paddle resets phase to zero', () => {
+  expect(advanceBoatPaddlePhase(Math.PI, false, 0.05)).toBe(0)
+})
+
+test('active phase remains within [0, 2pi)', () => {
+  let phase = 0
+  for (let i = 0; i < 200; i++) {
+    phase = advanceBoatPaddlePhase(phase, true, 0.016)
+    expect(phase).toBeGreaterThanOrEqual(0)
+    expect(phase).toBeLessThan(Math.PI * 2)
+    expect(Number.isFinite(phase)).toBe(true)
+  }
+})
+
+test('vanilla angles at phase 0, pi/4, and pi/2 match extracted formulas', () => {
+  const phases = [0, Math.PI / 4, Math.PI / 2] as const
+  for (const phase of phases) {
+    const angles = getVanillaBoatPaddleAngles(phase, 0)
+    const tX = (Math.sin(-phase) + 1) / 2
+    const tY = (Math.sin(-phase + 1) + 1) / 2
+    expect(angles.xRot).toBeCloseTo(-Math.PI / 3 + (-Math.PI / 12 - -Math.PI / 3) * tX, 5)
+    expect(angles.yRot).toBeCloseTo(-Math.PI / 4 + (Math.PI / 2) * tY, 5)
+    expect(angles.zRot).toBeCloseTo(Math.PI / 16, 5)
+  }
+})
+
+test('right-side Y is mirrored', () => {
+  const left = getVanillaBoatPaddleAngles(Math.PI / 3, 0)
+  const right = getVanillaBoatPaddleAngles(Math.PI / 3, 1)
+  expect(right.yRot).toBeCloseTo(Math.PI - left.yRot, 5)
+  expect(right.xRot).toBeCloseTo(left.xRot, 5)
+})
+
+test('relative quaternion at phase zero is identity', () => {
+  const scratch = createBoatPaddlePivotScratch()
+  const quat = getBoatPaddleRelativeQuaternion(0, 0, scratch)
+  expect(quat.x).toBeCloseTo(0, 5)
+  expect(quat.y).toBeCloseTo(0, 5)
+  expect(quat.z).toBeCloseTo(0, 5)
+  expect(quat.w).toBeCloseTo(1, 5)
+})
+
+test('returned phases and quaternions are finite', () => {
+  const scratch = createBoatPaddlePivotScratch()
+  const phase = advanceBoatPaddlePhase(0, true, 0.05)
+  const quat = getBoatPaddleRelativeQuaternion(phase, 1, scratch)
+  expect(Number.isFinite(phase)).toBe(true)
+  expect(Number.isFinite(quat.x)).toBe(true)
+  expect(Number.isFinite(quat.y)).toBe(true)
+  expect(Number.isFinite(quat.z)).toBe(true)
+  expect(Number.isFinite(quat.w)).toBe(true)
+})
+
+test('syncBoatPaddleAnimationTargets resets phase when activity changes', () => {
+  const state = createBoatPaddleAnimationState()
+  state.leftPhase = 1.2
+  state.leftActive = true
+
+  syncBoatPaddleAnimationTargets(state, false, false)
+  expect(state.leftActive).toBe(false)
+  expect(state.leftPhase).toBe(0)
+})
+
+test('updateBoatPaddleAnimationState advances active paddles and rotates pivots', () => {
+  const state = createBoatPaddleAnimationState()
+  state.leftActive = true
+  const leftPivot = new THREE.Object3D()
+  const scratch = createBoatPaddlePivotScratch()
+
+  updateBoatPaddleAnimationState(state, 0.05, leftPivot, undefined, scratch)
+  expect(state.leftPhase).toBeCloseTo(BOAT_PADDLE_STEP, 5)
+  expect(leftPivot.quaternion.w).not.toBeCloseTo(1, 3)
+})
+
+test('negative or non-finite dt is treated as zero advancement', () => {
+  expect(advanceBoatPaddlePhase(0.5, true, Number.NaN)).toBe(0.5)
+  expect(advanceBoatPaddlePhase(0.5, true, -1)).toBe(0.5)
+})
+
+test('boat paddle radians per second matches vanilla tick rate', () => {
+  expect(BOAT_PADDLE_RADIANS_PER_SECOND).toBeCloseTo((Math.PI / 8) * 20, 5)
+})

package/src/three/entity/boatPaddleAnimation.ts

@@ -0,0 +1,104 @@
+//@ts-nocheck
+import * as THREE from 'three'
+
+export const BOAT_PADDLE_STEP = Math.PI / 8
+export const BOAT_TICKS_PER_SECOND = 20
+export const BOAT_PADDLE_RADIANS_PER_SECOND = BOAT_PADDLE_STEP * BOAT_TICKS_PER_SECOND
+
+export type BoatPaddleAnimationState = {
+  leftActive: boolean
+  rightActive: boolean
+  leftPhase: number
+  rightPhase: number
+}
+
+export type BoatPaddlePivotScratch = {
+  current: THREE.Quaternion
+  rest: THREE.Quaternion
+  delta: THREE.Quaternion
+  euler: THREE.Euler
+}
+
+export function createBoatPaddlePivotScratch(): BoatPaddlePivotScratch {
+  return {
+    current: new THREE.Quaternion(),
+    rest: new THREE.Quaternion(),
+    delta: new THREE.Quaternion(),
+    euler: new THREE.Euler(0, 0, 0, 'ZYX')
+  }
+}
+
+export function createBoatPaddleAnimationState(): BoatPaddleAnimationState {
+  return {
+    leftActive: false,
+    rightActive: false,
+    leftPhase: 0,
+    rightPhase: 0
+  }
+}
+
+function lerp(a: number, b: number, t: number): number {
+  return a + (b - a) * t
+}
+
+export function advanceBoatPaddlePhase(phase: number, active: boolean, dt: number): number {
+  if (!active) return 0
+  const safeDt = Number.isFinite(dt) && dt >= 0 ? dt : 0
+  const twoPi = Math.PI * 2
+  return (phase + safeDt * BOAT_PADDLE_RADIANS_PER_SECOND) % twoPi
+}
+
+export function getVanillaBoatPaddleAngles(phase: number, side: 0 | 1): { xRot: number; yRot: number; zRot: number } {
+  const xRot = lerp(-Math.PI / 3, -Math.PI / 12, (Math.sin(-phase) + 1) / 2)
+  let yRot = lerp(-Math.PI / 4, Math.PI / 4, (Math.sin(-phase + 1) + 1) / 2)
+  if (side === 1) yRot = Math.PI - yRot
+  const zRot = Math.PI / 16
+  return { xRot, yRot, zRot }
+}
+
+function vanillaAnglesToQuaternion(angles: { xRot: number; yRot: number; zRot: number }, target: THREE.Quaternion, euler: THREE.Euler): THREE.Quaternion {
+  euler.set(-angles.xRot, angles.yRot, -angles.zRot, 'ZYX')
+  return target.setFromEuler(euler)
+}
+
+export function getBoatPaddleRelativeQuaternion(phase: number, side: 0 | 1, scratch: BoatPaddlePivotScratch): THREE.Quaternion {
+  if (phase === 0) {
+    return scratch.delta.identity()
+  }
+  vanillaAnglesToQuaternion(getVanillaBoatPaddleAngles(phase, side), scratch.current, scratch.euler)
+  vanillaAnglesToQuaternion(getVanillaBoatPaddleAngles(0, side), scratch.rest, scratch.euler)
+  return scratch.delta.copy(scratch.current).multiply(scratch.rest.invert())
+}
+
+export function applyBoatPaddlePivotRotation(pivot: THREE.Object3D, phase: number, side: 0 | 1, scratch: BoatPaddlePivotScratch): void {
+  pivot.quaternion.copy(getBoatPaddleRelativeQuaternion(phase, side, scratch))
+}
+
+export function syncBoatPaddleAnimationTargets(state: BoatPaddleAnimationState, leftActive: boolean, rightActive: boolean): void {
+  if (state.leftActive !== leftActive) {
+    state.leftActive = leftActive
+    state.leftPhase = 0
+  }
+  if (state.rightActive !== rightActive) {
+    state.rightActive = rightActive
+    state.rightPhase = 0
+  }
+}
+
+export function updateBoatPaddleAnimationState(
+  state: BoatPaddleAnimationState,
+  dt: number,
+  leftPivot: THREE.Object3D | undefined,
+  rightPivot: THREE.Object3D | undefined,
+  scratch: BoatPaddlePivotScratch
+): void {
+  state.leftPhase = advanceBoatPaddlePhase(state.leftPhase, state.leftActive, dt)
+  state.rightPhase = advanceBoatPaddlePhase(state.rightPhase, state.rightActive, dt)
+
+  if (leftPivot) {
+    applyBoatPaddlePivotRotation(leftPivot, state.leftPhase, 0, scratch)
+  }
+  if (rightPivot) {
+    applyBoatPaddlePivotRotation(rightPivot, state.rightPhase, 1, scratch)
+  }
+}

package/src/three/entity/boatPassengerRendering.ts

@@ -0,0 +1,20 @@
+//@ts-nocheck
+import type { Vec3Like } from './interpolationPolicy'
+
+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 {
+  anchorVehiclePassengerPosition as anchorBoatPassengerPosition,
+  releaseVehiclePassengerPosition as releaseBoatPassengerPosition
+} from './vehiclePassengerRendering'