minecraft-renderer 0.1.93 → 0.1.95

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'

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

@@ -0,0 +1,166 @@
+//@ts-nocheck
+import { expect, test } from 'vitest'
+import {
+  BOAT_PASSENGER_MAX_HEAD_YAW_RAD,
+  clampBoatPassengerRelativeHeadYaw,
+  getClampedBoatPassengerYaw,
+  normalizeYaw,
+  normalizeYawDelta,
+  resolveBoatPassengerThirdPersonRotation,
+  shouldApplyBoatPassengerRotation,
+  shouldApplyBoatPassengerThirdPersonRotation
+} from './boatPassengerRotation'
+
+const BOAT_YAW = -0.5645049299419149
+
+test('clamp relative head yaw at ±105° boundaries', () => {
+  expect(clampBoatPassengerRelativeHeadYaw(BOAT_PASSENGER_MAX_HEAD_YAW_RAD)).toBeCloseTo(BOAT_PASSENGER_MAX_HEAD_YAW_RAD)
+  expect(clampBoatPassengerRelativeHeadYaw(-BOAT_PASSENGER_MAX_HEAD_YAW_RAD)).toBeCloseTo(-BOAT_PASSENGER_MAX_HEAD_YAW_RAD)
+})
+
+test('clamp relative head yaw beyond both boundaries', () => {
+  const over = BOAT_PASSENGER_MAX_HEAD_YAW_RAD + 0.5
+  const under = -BOAT_PASSENGER_MAX_HEAD_YAW_RAD - 0.5
+  expect(clampBoatPassengerRelativeHeadYaw(over)).toBeCloseTo(BOAT_PASSENGER_MAX_HEAD_YAW_RAD)
+  expect(clampBoatPassengerRelativeHeadYaw(under)).toBeCloseTo(-BOAT_PASSENGER_MAX_HEAD_YAW_RAD)
+})
+
+test('normalizeYawDelta handles π/-π seam', () => {
+  expect(normalizeYawDelta(Math.PI, -Math.PI)).toBeCloseTo(0)
+  expect(normalizeYawDelta(-Math.PI, Math.PI)).toBeCloseTo(0)
+  expect(normalizeYawDelta(0.1, 2 * Math.PI + 0.1)).toBeCloseTo(0)
+})
+
+test('normalizeYaw wraps 2π to 0', () => {
+  expect(normalizeYaw(2 * Math.PI)).toBeCloseTo(0)
+  expect(normalizeYaw(-2 * Math.PI)).toBeCloseTo(0)
+})
+
+test('getClampedBoatPassengerYaw clamps absolute look beyond 105° from boat', () => {
+  const requested = BOAT_YAW + 2.5
+  const clamped = getClampedBoatPassengerYaw(requested, BOAT_YAW)
+  expect(normalizeYawDelta(BOAT_YAW, clamped)).toBeCloseTo(BOAT_PASSENGER_MAX_HEAD_YAW_RAD)
+})
+
+test('renderer and camera share the same effective yaw', () => {
+  const cameraYaw = BOAT_YAW + 1.9
+  const clampedLook = getClampedBoatPassengerYaw(cameraYaw, BOAT_YAW)
+  const resolved = resolveBoatPassengerThirdPersonRotation({
+    cameraYaw,
+    cameraPitch: 0.2,
+    vehicleYaw: BOAT_YAW
+  })
+  expect(resolved.effectiveCameraYaw).toBeCloseTo(clampedLook)
+  expect(normalizeYaw(BOAT_YAW + resolved.headYaw)).toBeCloseTo(clampedLook)
+})
+
+test('positive camera delta yields positive local head yaw', () => {
+  const cameraYaw = BOAT_YAW + 0.5
+  const resolved = resolveBoatPassengerThirdPersonRotation({
+    cameraYaw,
+    cameraPitch: 0,
+    vehicleYaw: BOAT_YAW
+  })
+  expect(resolved.headYaw).toBeGreaterThan(0)
+  expect(resolved.headYaw).toBeCloseTo(normalizeYawDelta(BOAT_YAW, cameraYaw))
+})
+
+test('head yaw sign follows normalize(cameraYaw - vehicleYaw) without inversion', () => {
+  const positive = resolveBoatPassengerThirdPersonRotation({
+    cameraYaw: BOAT_YAW + 0.3,
+    cameraPitch: 0,
+    vehicleYaw: BOAT_YAW
+  })
+  const negative = resolveBoatPassengerThirdPersonRotation({
+    cameraYaw: BOAT_YAW - 0.3,
+    cameraPitch: 0,
+    vehicleYaw: BOAT_YAW
+  })
+  expect(positive.headYaw).toBeCloseTo(0.3)
+  expect(negative.headYaw).toBeCloseTo(-0.3)
+})
+
+test('shouldApplyBoatPassengerRotation excludes minecart and horse without third-person requirement', () => {
+  const base = {
+    isAnchoredPassenger: true,
+    vehicleYaw: BOAT_YAW
+  }
+  expect(shouldApplyBoatPassengerRotation({ ...base, vehicleName: 'boat' })).toBe(true)
+  expect(shouldApplyBoatPassengerRotation({ ...base, vehicleName: 'minecart' })).toBe(false)
+  expect(shouldApplyBoatPassengerRotation({ ...base, vehicleName: 'horse' })).toBe(false)
+})
+
+test('shouldApplyBoatPassengerThirdPersonRotation excludes minecart and horse', () => {
+  const base = {
+    isThirdPerson: true,
+    isAnchoredPassenger: true,
+    vehicleYaw: BOAT_YAW
+  }
+  expect(shouldApplyBoatPassengerThirdPersonRotation({ ...base, vehicleName: 'boat' })).toBe(true)
+  expect(shouldApplyBoatPassengerThirdPersonRotation({ ...base, vehicleName: 'minecart' })).toBe(false)
+  expect(shouldApplyBoatPassengerThirdPersonRotation({ ...base, vehicleName: 'horse' })).toBe(false)
+})
+
+test('first mount frame without anchor uses camera fallback gate', () => {
+  expect(
+    shouldApplyBoatPassengerThirdPersonRotation({
+      isThirdPerson: true,
+      isAnchoredPassenger: false,
+      vehicleName: 'boat',
+      vehicleYaw: BOAT_YAW
+    })
+  ).toBe(false)
+})
+
+test('first dismount frame without anchor uses camera fallback gate', () => {
+  expect(
+    shouldApplyBoatPassengerThirdPersonRotation({
+      isThirdPerson: true,
+      isAnchoredPassenger: false,
+      vehicleName: undefined,
+      vehicleYaw: undefined
+    })
+  ).toBe(false)
+})
+
+test('non-finite or missing vehicle yaw disables boat branch', () => {
+  expect(
+    shouldApplyBoatPassengerThirdPersonRotation({
+      isThirdPerson: true,
+      isAnchoredPassenger: true,
+      vehicleName: 'boat',
+      vehicleYaw: Number.NaN
+    })
+  ).toBe(false)
+  expect(getClampedBoatPassengerYaw(1.2, Number.NaN)).toBe(1.2)
+  expect(getClampedBoatPassengerYaw(Number.NaN, BOAT_YAW)).toBeNaN()
+})
+
+test('acceptance identity: headYaw ≈ clamp(normalize(cameraYaw - boatYaw))', () => {
+  const cameraYaw = BOAT_YAW + 1.1
+  const resolved = resolveBoatPassengerThirdPersonRotation({
+    cameraYaw,
+    cameraPitch: -0.4,
+    vehicleYaw: BOAT_YAW
+  })
+  const expectedHead = clampBoatPassengerRelativeHeadYaw(normalizeYawDelta(BOAT_YAW, cameraYaw))
+  expect(resolved.bodyYaw).toBeCloseTo(BOAT_YAW)
+  expect(resolved.headYaw).toBeCloseTo(expectedHead)
+  expect(resolved.effectiveCameraYaw).toBeCloseTo(normalizeYaw(BOAT_YAW + expectedHead))
+  expect(resolved.headPitch).toBeCloseTo(0.4)
+})
+
+test('helmet head armor copies skin head yaw after boat passenger rotation', () => {
+  const resolved = resolveBoatPassengerThirdPersonRotation({
+    cameraYaw: BOAT_YAW + 0.45,
+    cameraPitch: -0.2,
+    vehicleYaw: BOAT_YAW
+  })
+  const skinHead = { x: resolved.headPitch, y: resolved.headYaw, z: 0 }
+  const helmet = { x: 0, y: 0, z: 0 }
+  helmet.x = -skinHead.x
+  helmet.y = skinHead.y
+  helmet.z = skinHead.z
+  expect(helmet.y).toBeCloseTo(resolved.headYaw)
+  expect(helmet.x).toBeCloseTo(-resolved.headPitch)
+})