minecraft-renderer 0.1.92 → 0.1.94

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)
+})

package/src/three/entity/boatPassengerRotation.ts

@@ -0,0 +1,71 @@
+//@ts-nocheck
+import { isBoatEntityName } from './boatModelRotation'
+
+/** Vanilla 1.17.1 `Boat.clampRotation` limit (degrees → radians). */
+export const BOAT_PASSENGER_MAX_HEAD_YAW_RAD = (105 * Math.PI) / 180
+
+export function normalizeYawDelta(from: number, to: number): number {
+  let delta = to - from
+  while (delta > Math.PI) delta -= Math.PI * 2
+  while (delta < -Math.PI) delta += Math.PI * 2
+  return delta
+}
+
+export function normalizeYaw(yaw: number): number {
+  return normalizeYawDelta(0, yaw)
+}
+
+export function clampBoatPassengerRelativeHeadYaw(relativeYaw: number): number {
+  return Math.max(-BOAT_PASSENGER_MAX_HEAD_YAW_RAD, Math.min(BOAT_PASSENGER_MAX_HEAD_YAW_RAD, relativeYaw))
+}
+
+/** Clamp absolute look yaw for a boat passenger (vanilla `Boat.clampRotation`). */
+export function getClampedBoatPassengerYaw(requestedYaw: number, boatYaw: number): number {
+  if (!Number.isFinite(requestedYaw) || !Number.isFinite(boatYaw)) return requestedYaw
+  const relative = normalizeYawDelta(boatYaw, requestedYaw)
+  const clampedRelative = clampBoatPassengerRelativeHeadYaw(relative)
+  return normalizeYaw(boatYaw + clampedRelative)
+}
+
+export type BoatPassengerThirdPersonRotation = {
+  bodyYaw: number
+  headYaw: number
+  headPitch: number
+  effectiveCameraYaw: number
+}
+
+export function resolveBoatPassengerThirdPersonRotation(params: {
+  cameraYaw: number
+  cameraPitch: number
+  vehicleYaw: number
+}): BoatPassengerThirdPersonRotation {
+  const { cameraYaw, cameraPitch, vehicleYaw } = params
+  const relativeHeadYaw = normalizeYawDelta(vehicleYaw, cameraYaw)
+  const headYaw = clampBoatPassengerRelativeHeadYaw(relativeHeadYaw)
+  const effectiveCameraYaw = normalizeYaw(vehicleYaw + headYaw)
+  return {
+    bodyYaw: vehicleYaw,
+    headYaw,
+    headPitch: -cameraPitch,
+    effectiveCameraYaw
+  }
+}
+
+export function shouldApplyBoatPassengerRotation(params: {
+  isAnchoredPassenger: boolean
+  vehicleName: string | undefined
+  vehicleYaw: number | undefined
+}): boolean {
+  return params.isAnchoredPassenger && isBoatEntityName(params.vehicleName) && typeof params.vehicleYaw === 'number' && Number.isFinite(params.vehicleYaw)
+}
+
+export function shouldApplyBoatPassengerThirdPersonRotation(params: {
+  isThirdPerson: boolean
+  isAnchoredPassenger: boolean
+  vehicleName: string | undefined
+  vehicleYaw: number | undefined
+}): boolean {
+  return params.isThirdPerson && shouldApplyBoatPassengerRotation(params)
+}
+
+export { isBoatEntityName }

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

@@ -0,0 +1,236 @@
+//@ts-nocheck
+import * as THREE from 'three'
+import { expect, test } from 'vitest'
+import {
+  BOAT_HULL_RENDER_ORDER,
+  BOAT_OBJ_OFFSET_Y,
+  BOAT_PADDLE_GEOMETRY_DELTA,
+  BOAT_PADDLE_LEFT_PIVOT,
+  BOAT_PADDLE_PIVOT_LEFT_NAME,
+  BOAT_PADDLE_PIVOT_RIGHT_NAME,
+  BOAT_PADDLE_RIGHT_PIVOT,
+  BOAT_PADDLE_SOURCE_LEFT,
+  BOAT_WATER_PATCH_CENTER_Y,
+  BOAT_WATER_PATCH_CENTER_Z,
+  BOAT_WATER_PATCH_DEPTH,
+  BOAT_WATER_PATCH_HEIGHT,
+  BOAT_WATER_PATCH_NAME,
+  BOAT_WATER_PATCH_RENDER_ORDER,
+  BOAT_WATER_PATCH_WIDTH,
+  BOAT_WATER_PATCH_WORLD_BOUNDS,
+  applyBoatHullRenderSettings,
+  boatObjLocalToEntitySpace,
+  createBoatWaterPatchMesh,
+  getBoatWaterPatchEntitySpaceBounds,
+  setupBoatMesh,
+  setupBoatPaddlePivots
+} from './boatRenderSetup'
+
+test('water patch uses vanilla dimensions in blocks', () => {
+  const patch = createBoatWaterPatchMesh()
+  const size = new THREE.Vector3()
+  patch.geometry.computeBoundingBox()
+  patch.geometry.boundingBox!.getSize(size)
+  expect(size.x).toBeCloseTo(BOAT_WATER_PATCH_WIDTH, 5)
+  expect(size.y).toBeCloseTo(BOAT_WATER_PATCH_HEIGHT, 5)
+  expect(size.z).toBeCloseTo(BOAT_WATER_PATCH_DEPTH, 5)
+})
+
+test('water patch local center matches vanilla OBJ placement', () => {
+  const patch = createBoatWaterPatchMesh()
+  expect(patch.position.x).toBe(0)
+  expect(patch.position.y).toBeCloseTo(BOAT_WATER_PATCH_CENTER_Y, 5)
+  expect(patch.position.z).toBeCloseTo(BOAT_WATER_PATCH_CENTER_Z, 5)
+})
+
+test('water patch entity-space bounds match vanilla world-relative bounds', () => {
+  const bounds = getBoatWaterPatchEntitySpaceBounds(BOAT_OBJ_OFFSET_Y)
+  expect(bounds.minX).toBeCloseTo(BOAT_WATER_PATCH_WORLD_BOUNDS.minX, 5)
+  expect(bounds.maxX).toBeCloseTo(BOAT_WATER_PATCH_WORLD_BOUNDS.maxX, 5)
+  expect(bounds.minY).toBeCloseTo(BOAT_WATER_PATCH_WORLD_BOUNDS.minY, 5)
+  expect(bounds.maxY).toBeCloseTo(BOAT_WATER_PATCH_WORLD_BOUNDS.maxY, 5)
+  expect(bounds.minZ).toBeCloseTo(BOAT_WATER_PATCH_WORLD_BOUNDS.minZ, 5)
+  expect(bounds.maxZ).toBeCloseTo(BOAT_WATER_PATCH_WORLD_BOUNDS.maxZ, 5)
+})
+
+test('water patch material is depth-only', () => {
+  const patch = createBoatWaterPatchMesh()
+  const material = patch.material as THREE.MeshBasicMaterial
+  expect(material.colorWrite).toBe(false)
+  expect(material.depthWrite).toBe(true)
+  expect(material.depthTest).toBe(true)
+})
+
+test('boat hull renders in opaque list before depth-only patch', () => {
+  const root = new THREE.Object3D()
+  const hull = new THREE.Mesh(new THREE.BoxGeometry(1, 1, 1), new THREE.MeshBasicMaterial({ transparent: true, alphaTest: 0.1 }))
+  hull.name = 'bottom'
+  root.add(hull)
+  const { waterPatch } = setupBoatMesh(root)
+
+  expect(hull.renderOrder).toBe(BOAT_HULL_RENDER_ORDER)
+  expect(waterPatch.renderOrder).toBe(BOAT_WATER_PATCH_RENDER_ORDER)
+  expect(waterPatch.renderOrder).toBeGreaterThan(hull.renderOrder)
+  expect(waterPatch.name).toBe(BOAT_WATER_PATCH_NAME)
+})
+
+test('boat hull material is alpha-tested opaque with depth write', () => {
+  const root = new THREE.Object3D()
+  const hull = new THREE.Mesh(new THREE.BoxGeometry(1, 1, 1), new THREE.MeshBasicMaterial({ transparent: true, alphaTest: 0.05 }))
+  root.add(hull)
+  applyBoatHullRenderSettings(root)
+  const material = hull.material as THREE.MeshBasicMaterial
+  expect(material.transparent).toBe(false)
+  expect(material.alphaTest).toBeGreaterThanOrEqual(0.1)
+  expect(material.depthWrite).toBe(true)
+  expect(material.depthTest).toBe(true)
+})
+
+test('boat OBJ hull entity-space Y bounds after BOAT_OBJ_OFFSET_Y', () => {
+  const fs = require('node:fs')
+  const path = require('node:path')
+  const objPath = path.join(__dirname, 'models/boat.obj')
+  const txt = fs.readFileSync(objPath, 'utf8') as string
+  const groups: Record<string, { min: number; max: number }> = {}
+  let current = ''
+  for (const line of txt.split('\n')) {
+    if (line.startsWith('o ')) current = line.slice(2).trim()
+    if (!line.startsWith('v ')) continue
+    const y = Number(line.split(/\s+/)[2])
+    groups[current] ??= { min: Infinity, max: -Infinity }
+    groups[current].min = Math.min(groups[current].min, y + BOAT_OBJ_OFFSET_Y)
+    groups[current].max = Math.max(groups[current].max, y + BOAT_OBJ_OFFSET_Y)
+  }
+
+  expect(groups.bottom.min).toBeCloseTo(0, 5)
+  expect(groups.bottom.max).toBeCloseTo(0.1875, 5)
+  for (const name of ['front', 'back', 'left', 'right'] as const) {
+    expect(groups[name].min).toBeCloseTo(0.1875, 5)
+    expect(groups[name].max).toBeCloseTo(0.5625, 5)
+  }
+
+  const patch = getBoatWaterPatchEntitySpaceBounds(BOAT_OBJ_OFFSET_Y)
+  expect(patch.minY).toBeCloseTo(0.375, 5)
+  expect(patch.maxY).toBeCloseTo(0.5625, 5)
+})
+
+function makeBoatRootWithPaddles(): THREE.Object3D {
+  const root = new THREE.Object3D()
+  const leftShaft = new THREE.Mesh(new THREE.BoxGeometry(0.1, 0.1, 0.5))
+  leftShaft.name = 'paddle_left'
+  leftShaft.position.set(0.2, 1.5, 1.0)
+  const leftBlade = new THREE.Mesh(new THREE.BoxGeometry(0.1, 0.1, 0.2))
+  leftBlade.name = 'paddle_left'
+  leftBlade.position.set(0.15, 1.4, 1.2)
+  const rightShaft = new THREE.Mesh(new THREE.BoxGeometry(0.1, 0.1, 0.5))
+  rightShaft.name = 'paddle_right'
+  rightShaft.position.set(0.2, 1.5, -1.0)
+  const rightBlade = new THREE.Mesh(new THREE.BoxGeometry(0.1, 0.1, 0.2))
+  rightBlade.name = 'paddle_right'
+  rightBlade.position.set(0.15, 1.4, -1.2)
+  root.add(leftShaft, leftBlade, rightShaft, rightBlade)
+  return root
+}
+
+test('setupBoatPaddlePivots groups both paddle pieces by side', () => {
+  const root = makeBoatRootWithPaddles()
+  const { leftPivot, rightPivot } = setupBoatPaddlePivots(root)
+
+  expect(leftPivot?.children.length).toBe(2)
+  expect(rightPivot?.children.length).toBe(2)
+  expect(leftPivot?.name).toBe(BOAT_PADDLE_PIVOT_LEFT_NAME)
+  expect(rightPivot?.name).toBe(BOAT_PADDLE_PIVOT_RIGHT_NAME)
+})
+
+function getMeshRootLocalPosition(root: THREE.Object3D, mesh: THREE.Object3D): THREE.Vector3 {
+  const rootLocal = new THREE.Vector3()
+  let current: THREE.Object3D | null = mesh
+  while (current && current !== root) {
+    rootLocal.add(current.position)
+    current = current.parent
+  }
+  return rootLocal
+}
+
+test('setupBoatPaddlePivots uses corrected vanilla attachment positions', () => {
+  const root = makeBoatRootWithPaddles()
+  const { leftPivot, rightPivot } = setupBoatPaddlePivots(root)
+
+  expect(leftPivot?.position.toArray()).toEqual(BOAT_PADDLE_LEFT_PIVOT.toArray())
+  expect(rightPivot?.position.toArray()).toEqual(BOAT_PADDLE_RIGHT_PIVOT.toArray())
+})
+
+test('setupBoatPaddlePivots shifts root-local paddle geometry by geometry delta', () => {
+  const root = makeBoatRootWithPaddles()
+  const before = root.children.map(child => child.position.clone())
+  setupBoatPaddlePivots(root)
+
+  const afterPositions: THREE.Vector3[] = []
+  root.traverse(child => {
+    if (child instanceof THREE.Mesh && (child.name === 'paddle_left' || child.name === 'paddle_right')) {
+      afterPositions.push(getMeshRootLocalPosition(root, child))
+    }
+  })
+
+  expect(afterPositions.length).toBe(4)
+  for (let i = 0; i < before.length; i++) {
+    expect(afterPositions[i].x).toBeCloseTo(before[i].x + BOAT_PADDLE_GEOMETRY_DELTA.x, 5)
+    expect(afterPositions[i].y).toBeCloseTo(before[i].y + BOAT_PADDLE_GEOMETRY_DELTA.y, 5)
+    expect(afterPositions[i].z).toBeCloseTo(before[i].z + BOAT_PADDLE_GEOMETRY_DELTA.z, 5)
+  }
+})
+
+test('corrected paddle pivots map to vanilla entity Z with mesh yaw −π/2', () => {
+  const left = boatObjLocalToEntitySpace(BOAT_PADDLE_LEFT_PIVOT.x, BOAT_PADDLE_LEFT_PIVOT.y, BOAT_PADDLE_LEFT_PIVOT.z)
+  const right = boatObjLocalToEntitySpace(BOAT_PADDLE_RIGHT_PIVOT.x, BOAT_PADDLE_RIGHT_PIVOT.y, BOAT_PADDLE_RIGHT_PIVOT.z)
+
+  expect(left.z).toBeCloseTo(-3 / 16, 5)
+  expect(right.z).toBeCloseTo(-3 / 16, 5)
+  expect(left.y).toBeCloseTo(0.6875, 5)
+  expect(right.y).toBeCloseTo(0.6875, 5)
+  expect(left.x).toBeCloseTo(-9 / 16, 5)
+  expect(right.x).toBeCloseTo(9 / 16, 5)
+})
+
+test('setupBoatPaddlePivots offsets child geometry from source pivot for rotation', () => {
+  const root = makeBoatRootWithPaddles()
+  const { leftPivot } = setupBoatPaddlePivots(root)
+  expect(leftPivot).toBeDefined()
+
+  const shaft = leftPivot!.children[0]
+  const rootLocalBefore = new THREE.Vector3(0.2, 1.5, 1.0)
+  expect(shaft.position.x).toBeCloseTo(rootLocalBefore.x - BOAT_PADDLE_SOURCE_LEFT.x, 5)
+  expect(shaft.position.y).toBeCloseTo(rootLocalBefore.y - BOAT_PADDLE_SOURCE_LEFT.y, 5)
+  expect(shaft.position.z).toBeCloseTo(rootLocalBefore.z - BOAT_PADDLE_SOURCE_LEFT.z, 5)
+})
+
+test('rotating a pivot moves both paddle pieces rigidly', () => {
+  const root = makeBoatRootWithPaddles()
+  const { leftPivot } = setupBoatPaddlePivots(root)
+  expect(leftPivot).toBeDefined()
+
+  const childOffsetsBefore = leftPivot!.children.map(child => child.position.clone())
+  leftPivot!.rotation.y = Math.PI / 4
+  leftPivot!.updateMatrixWorld(true)
+
+  leftPivot!.children.forEach((child, index) => {
+    expect(child.position.x).toBeCloseTo(childOffsetsBefore[index].x, 5)
+    expect(child.position.y).toBeCloseTo(childOffsetsBefore[index].y, 5)
+    expect(child.position.z).toBeCloseTo(childOffsetsBefore[index].z, 5)
+  })
+  expect(leftPivot!.position.toArray()).toEqual(BOAT_PADDLE_LEFT_PIVOT.toArray())
+})
+
+test('setupBoatMesh is idempotent for paddle pivots and water patch', () => {
+  const root = makeBoatRootWithPaddles()
+  setupBoatMesh(root)
+  const leftPivot = root.userData.boatPaddleLeftPivot as THREE.Object3D
+  const waterPatchCountBefore = root.children.filter(child => child.name === BOAT_WATER_PATCH_NAME).length
+
+  setupBoatMesh(root)
+
+  expect(root.userData.boatPaddleLeftPivot).toBe(leftPivot)
+  expect(root.children.filter(child => child.name === BOAT_WATER_PATCH_NAME).length).toBe(waterPatchCountBefore)
+  expect(root.children.filter(child => child.name === BOAT_PADDLE_PIVOT_LEFT_NAME).length).toBe(1)
+  expect(root.children.filter(child => child.name === BOAT_PADDLE_PIVOT_RIGHT_NAME).length).toBe(1)
+})

package/src/three/entity/boatRenderSetup.ts

@@ -0,0 +1,214 @@
+//@ts-nocheck
+import * as THREE from 'three'
+import { BOAT_MESH_YAW_OFFSET } from './boatModelRotation'
+
+/** Vanilla BoatModel.createWaterPatch() size in blocks (after X rotation). */
+export const BOAT_WATER_PATCH_WIDTH = 28 / 16
+export const BOAT_WATER_PATCH_HEIGHT = 3 / 16
+export const BOAT_WATER_PATCH_DEPTH = 16 / 16
+
+/** OBJ boat root offset applied in EntityMesh (single source — import from here, do not duplicate). */
+export const BOAT_OBJ_OFFSET_Y = -1.125
+
+/**
+ * Vanilla 1.17.1 water patch center in OBJ-local space.
+ * Tuned with BOAT_OBJ_OFFSET_Y so entity-space bounds stay Y [0.375, 0.5625].
+ */
+export const BOAT_WATER_PATCH_CENTER_Y = 1.59375
+export const BOAT_WATER_PATCH_CENTER_Z = 0
+
+export const BOAT_WATER_PATCH_WORLD_BOUNDS = {
+  minX: -0.875,
+  maxX: 0.875,
+  minY: 0.375,
+  maxY: 0.5625,
+  minZ: -0.5,
+  maxZ: 0.5
+} as const
+
+export const BOAT_HULL_RENDER_ORDER = 0
+export const BOAT_WATER_PATCH_RENDER_ORDER = 1
+
+export const BOAT_WATER_PATCH_NAME = 'boat_water_patch'
+
+export const BOAT_PADDLE_PIVOT_LEFT_NAME = 'boat_paddle_pivot_left'
+export const BOAT_PADDLE_PIVOT_RIGHT_NAME = 'boat_paddle_pivot_right'
+
+/** Original handoff pivot (rotation center only — geometry stays aft if used alone). */
+export const BOAT_PADDLE_SOURCE_LEFT = new THREE.Vector3(3 / 16, 28 / 16, 9 / 16)
+export const BOAT_PADDLE_SOURCE_RIGHT = new THREE.Vector3(3 / 16, 28 / 16, -9 / 16)
+
+/** Root-local shift applied to paddle mesh together with the pivot move. */
+export const BOAT_PADDLE_GEOMETRY_DELTA = new THREE.Vector3(-6 / 16, 1 / 16, 0)
+
+/** Vanilla 1.17.1 oarlock positions in OBJ-local blocks (after geometry delta). */
+export const BOAT_PADDLE_LEFT_PIVOT = new THREE.Vector3(-3 / 16, 29 / 16, 9 / 16)
+export const BOAT_PADDLE_RIGHT_PIVOT = new THREE.Vector3(-3 / 16, 29 / 16, -9 / 16)
+
+/** Entity-space mapping for OBJ-local points (mesh `rotation.y = −π/2`, `BOAT_OBJ_OFFSET_Y`). */
+export function boatObjLocalToEntitySpace(objX: number, objY: number, objZ: number): THREE.Vector3 {
+  return new THREE.Vector3(-objZ, objY + BOAT_OBJ_OFFSET_Y, objX)
+}
+
+const _rootLocalPos = new THREE.Vector3()
+
+function getRootLocalPosition(object: THREE.Object3D, root: THREE.Object3D): THREE.Vector3 {
+  _rootLocalPos.set(0, 0, 0)
+  let current: THREE.Object3D | null = object
+  while (current && current !== root) {
+    _rootLocalPos.add(current.position)
+    current = current.parent
+  }
+  return _rootLocalPos
+}
+
+function createBoatPaddlePivot(
+  root: THREE.Object3D,
+  pivotName: string,
+  sourcePivot: THREE.Vector3,
+  targetPivot: THREE.Vector3,
+  paddleMeshes: THREE.Object3D[]
+): THREE.Object3D | undefined {
+  if (paddleMeshes.length === 0) return undefined
+
+  const pivot = new THREE.Object3D()
+  pivot.name = pivotName
+  pivot.position.copy(targetPivot)
+  root.add(pivot)
+
+  for (const mesh of paddleMeshes) {
+    const parent = mesh.parent
+    if (!parent) continue
+    const rootLocal = getRootLocalPosition(mesh, root)
+    parent.remove(mesh)
+    // Offset from source oarlock; pivot sits at target so root-local geometry shifts by delta.
+    mesh.position.copy(rootLocal).sub(sourcePivot)
+    pivot.add(mesh)
+  }
+
+  return pivot
+}
+
+function collectBoatPaddleMeshes(root: THREE.Object3D, sideName: 'paddle_left' | 'paddle_right'): THREE.Object3D[] {
+  const meshes: THREE.Object3D[] = []
+  root.traverse(child => {
+    if (child === root) return
+    if (child.name === BOAT_WATER_PATCH_NAME) return
+    if (child.name === BOAT_PADDLE_PIVOT_LEFT_NAME || child.name === BOAT_PADDLE_PIVOT_RIGHT_NAME) return
+    if (child.name === sideName) meshes.push(child)
+  })
+  return meshes
+}
+
+export function setupBoatPaddlePivots(root: THREE.Object3D): {
+  leftPivot?: THREE.Object3D
+  rightPivot?: THREE.Object3D
+} {
+  if (root.userData.boatPaddleLeftPivot || root.userData.boatPaddleRightPivot) {
+    return {
+      leftPivot: root.userData.boatPaddleLeftPivot as THREE.Object3D | undefined,
+      rightPivot: root.userData.boatPaddleRightPivot as THREE.Object3D | undefined
+    }
+  }
+
+  const leftPivot = createBoatPaddlePivot(
+    root,
+    BOAT_PADDLE_PIVOT_LEFT_NAME,
+    BOAT_PADDLE_SOURCE_LEFT,
+    BOAT_PADDLE_LEFT_PIVOT,
+    collectBoatPaddleMeshes(root, 'paddle_left')
+  )
+  const rightPivot = createBoatPaddlePivot(
+    root,
+    BOAT_PADDLE_PIVOT_RIGHT_NAME,
+    BOAT_PADDLE_SOURCE_RIGHT,
+    BOAT_PADDLE_RIGHT_PIVOT,
+    collectBoatPaddleMeshes(root, 'paddle_right')
+  )
+
+  if (leftPivot) root.userData.boatPaddleLeftPivot = leftPivot
+  if (rightPivot) root.userData.boatPaddleRightPivot = rightPivot
+
+  return { leftPivot, rightPivot }
+}
+
+export function getBoatMeshYawOffset(): number {
+  return BOAT_MESH_YAW_OFFSET
+}
+
+export function createBoatWaterPatchGeometry(): THREE.BoxGeometry {
+  return new THREE.BoxGeometry(BOAT_WATER_PATCH_WIDTH, BOAT_WATER_PATCH_HEIGHT, BOAT_WATER_PATCH_DEPTH)
+}
+
+export function createBoatWaterPatchMaterial(): THREE.MeshBasicMaterial {
+  return new THREE.MeshBasicMaterial({
+    colorWrite: false,
+    depthWrite: true,
+    depthTest: true
+  })
+}
+
+export function createBoatWaterPatchMesh(): THREE.Mesh {
+  const mesh = new THREE.Mesh(createBoatWaterPatchGeometry(), createBoatWaterPatchMaterial())
+  mesh.name = BOAT_WATER_PATCH_NAME
+  mesh.position.set(0, BOAT_WATER_PATCH_CENTER_Y, BOAT_WATER_PATCH_CENTER_Z)
+  mesh.renderOrder = BOAT_WATER_PATCH_RENDER_ORDER
+  return mesh
+}
+
+export function applyBoatHullRenderSettings(root: THREE.Object3D): void {
+  root.traverse(child => {
+    if (!(child instanceof THREE.Mesh)) return
+    if (child.name === BOAT_WATER_PATCH_NAME) return
+    const materials = Array.isArray(child.material) ? child.material : [child.material]
+    for (const material of materials) {
+      if (!(material instanceof THREE.Material)) continue
+      material.transparent = false
+      material.depthWrite = true
+      material.depthTest = true
+      if ('alphaTest' in material) {
+        material.alphaTest = Math.max(material.alphaTest ?? 0, 0.1)
+      }
+      material.needsUpdate = true
+    }
+    child.renderOrder = BOAT_HULL_RENDER_ORDER
+  })
+}
+
+export function getBoatWaterPatchEntitySpaceBounds(objOffsetY = BOAT_OBJ_OFFSET_Y) {
+  const centerY = objOffsetY + BOAT_WATER_PATCH_CENTER_Y
+  const halfHeight = BOAT_WATER_PATCH_HEIGHT / 2
+  const halfWidth = BOAT_WATER_PATCH_WIDTH / 2
+  const halfDepth = BOAT_WATER_PATCH_DEPTH / 2
+  return {
+    minX: -halfWidth,
+    maxX: halfWidth,
+    minY: centerY - halfHeight,
+    maxY: centerY + halfHeight,
+    minZ: BOAT_WATER_PATCH_CENTER_Z - halfDepth,
+    maxZ: BOAT_WATER_PATCH_CENTER_Z + halfDepth
+  }
+}
+
+export function setupBoatMesh(root: THREE.Object3D): { waterPatch: THREE.Mesh } {
+  applyBoatHullRenderSettings(root)
+  setupBoatPaddlePivots(root)
+  let waterPatch = root.userData.boatWaterPatch as THREE.Mesh | undefined
+  if (!waterPatch) {
+    waterPatch = createBoatWaterPatchMesh()
+    waterPatch.visible = false
+    root.add(waterPatch)
+    root.userData.boatWaterPatch = waterPatch
+  }
+  return { waterPatch }
+}
+
+export function disposeBoatWaterPatch(root: THREE.Object3D): void {
+  const patch = root.userData.boatWaterPatch as THREE.Mesh | undefined
+  if (!patch) return
+  patch.geometry.dispose()
+  if (patch.material instanceof THREE.Material) {
+    patch.material.dispose()
+  }
+  delete root.userData.boatWaterPatch
+}