minecraft-renderer 0.1.92 → 0.1.94

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

@@ -0,0 +1,15 @@
+//@ts-nocheck
+import { expect, test } from 'vitest'
+import { resolveEntityHeadPose } from './entityHeadPose'
+
+test('uses entity pitch and network head yaw as separate angles', () => {
+  expect(resolveEntityHeadPose({ pitch: 0.25, yaw: 1, headYaw: -0.5 })).toEqual({ pitch: 0.25, headYaw: -0.5 })
+})
+
+test('falls back to body yaw when head yaw is unavailable', () => {
+  expect(resolveEntityHeadPose({ pitch: -0.2, yaw: 1.25 })).toEqual({ pitch: -0.2, headYaw: 1.25 })
+})
+
+test('does not propagate missing or non-finite rotations', () => {
+  expect(resolveEntityHeadPose({ pitch: Number.NaN, yaw: Number.POSITIVE_INFINITY, headYaw: undefined })).toEqual({ pitch: 0, headYaw: 0 })
+})

package/src/three/entity/entityHeadPose.ts

@@ -0,0 +1,22 @@
+//@ts-nocheck
+export type EntityHeadPoseInput = {
+  pitch?: unknown
+  yaw?: unknown
+  headYaw?: unknown
+}
+
+export type EntityHeadPose = {
+  pitch: number
+  headYaw: number
+}
+
+export function resolveEntityHeadPose(entity: EntityHeadPoseInput): EntityHeadPose {
+  const pitch = typeof entity.pitch === 'number' && Number.isFinite(entity.pitch) ? entity.pitch : 0
+  const headYaw =
+    typeof entity.headYaw === 'number' && Number.isFinite(entity.headYaw)
+      ? entity.headYaw
+      : typeof entity.yaw === 'number' && Number.isFinite(entity.yaw)
+        ? entity.yaw
+        : 0
+  return { pitch, headYaw }
+}

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

@@ -0,0 +1,11 @@
+//@ts-nocheck
+import { expect, test } from 'vitest'
+import { VANILLA_117_HORSE_ENTITY_SCALES } from './horseEntityScale'
+
+test('vanilla 1.17.1 horse family entity scales', () => {
+  expect(VANILLA_117_HORSE_ENTITY_SCALES.horse).toBe(1.1)
+  expect(VANILLA_117_HORSE_ENTITY_SCALES.donkey).toBe(0.87)
+  expect(VANILLA_117_HORSE_ENTITY_SCALES.mule).toBe(0.92)
+  expect(VANILLA_117_HORSE_ENTITY_SCALES.skeleton_horse).toBe(1.0)
+  expect(VANILLA_117_HORSE_ENTITY_SCALES.zombie_horse).toBe(1.0)
+})

package/src/three/entity/horseEntityScale.ts

@@ -0,0 +1,9 @@
+//@ts-nocheck
+/** Vanilla 1.17.1 AbstractHorseRenderer entity scales (model OBJ root only). */
+export const VANILLA_117_HORSE_ENTITY_SCALES: Record<string, number> = {
+  horse: 1.1,
+  donkey: 0.87,
+  mule: 0.92,
+  skeleton_horse: 1.0,
+  zombie_horse: 1.0
+}

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

@@ -0,0 +1,159 @@
+//@ts-nocheck
+import * as THREE from 'three'
+import { expect, test } from 'vitest'
+import {
+  HORSE_HEAD_MAX_YAW,
+  applyHorseHeadPose,
+  calculateHorseHeadPose,
+  createHorseHeadAnimationState,
+  createHorseHeadRig,
+  getInterpolatedHorseHeadAnimation,
+  HORSE_HEAD_TICK_SECONDS,
+  setHorseHeadAnimationPosition,
+  updateHorseHeadAnimationFrame
+} from './horseHeadAnimation'
+
+test('head rig keeps world bounds and includes duplicate head parts', () => {
+  const root = new THREE.Group()
+  const body = new THREE.Mesh(new THREE.BoxGeometry(1, 1, 1))
+  body.name = 'Body'
+  const head = new THREE.Mesh(new THREE.BoxGeometry(1, 1, 1))
+  head.name = 'Head'
+  head.position.set(0, 2, -1)
+  const headSaddleA = new THREE.Mesh(new THREE.BoxGeometry(1, 1, 1))
+  headSaddleA.name = 'HeadSaddle'
+  headSaddleA.position.set(0, 1.5, -1)
+  const headSaddleB = new THREE.Mesh(new THREE.BoxGeometry(1, 1, 1))
+  headSaddleB.name = 'HeadSaddle'
+  headSaddleB.position.set(0, 1.8, -1)
+  root.add(body, head, headSaddleA, headSaddleB)
+  root.updateMatrixWorld(true)
+  const before = new THREE.Box3().setFromObject(root)
+
+  const rig = createHorseHeadRig(root)
+  root.updateMatrixWorld(true)
+  const after = new THREE.Box3().setFromObject(root)
+
+  expect(rig.userData.horseHeadParts).toHaveLength(3)
+  expect(rig.userData.horseHeadParts).toContain(head)
+  expect(rig.userData.horseHeadParts.filter(part => part.name === 'HeadSaddle')).toHaveLength(2)
+  expect(after.min.toArray()).toEqual(before.min.toArray())
+  expect(after.max.toArray()).toEqual(before.max.toArray())
+  expect(root.children.filter(child => child.name === 'horse_head_rig')).toHaveLength(1)
+  expect(createHorseHeadRig(root)).toBe(rig)
+})
+
+test('horse head pitch follows entity pitch in radians', () => {
+  const pose = calculateHorseHeadPose({
+    entityPitch: -Math.PI / 6,
+    headYaw: 0,
+    bodyYaw: 0,
+    limbSwing: 0,
+    limbSwingAmount: 0
+  })
+  expect(pose.pitch).toBeCloseTo(-Math.PI / 6)
+  expect(pose.yaw).toBe(0)
+})
+
+test('horse gait subtracts from pitch at full limb amount', () => {
+  const pose = calculateHorseHeadPose({
+    entityPitch: 0,
+    headYaw: 0,
+    bodyYaw: 0,
+    limbSwing: 0,
+    limbSwingAmount: 1
+  })
+  expect(pose.pitch).toBeCloseTo(-0.15)
+})
+
+test('horse gait is disabled for a small limb amount', () => {
+  expect(
+    calculateHorseHeadPose({
+      entityPitch: 0.3,
+      headYaw: 0,
+      bodyYaw: 0,
+      limbSwing: Math.PI,
+      limbSwingAmount: 0.2
+    }).pitch
+  ).toBeCloseTo(0.3)
+})
+
+test('relative head yaw is shortest-path and limited to twenty degrees', () => {
+  expect(
+    calculateHorseHeadPose({
+      entityPitch: 0,
+      headYaw: -Math.PI + 0.1,
+      bodyYaw: Math.PI - 0.1,
+      limbSwing: 0,
+      limbSwingAmount: 0
+    }).yaw
+  ).toBeCloseTo(0.2)
+  expect(
+    calculateHorseHeadPose({
+      entityPitch: 0,
+      headYaw: Math.PI / 2,
+      bodyYaw: 0,
+      limbSwing: 0,
+      limbSwingAmount: 0
+    }).yaw
+  ).toBeCloseTo(HORSE_HEAD_MAX_YAW)
+})
+
+test('animation phase uses authoritative horizontal distance and interpolates between ticks', () => {
+  const state = createHorseHeadAnimationState()
+  setHorseHeadAnimationPosition(state, { x: 10, z: 10 })
+  updateHorseHeadAnimationFrame(state, HORSE_HEAD_TICK_SECONDS)
+  setHorseHeadAnimationPosition(state, { x: 10.1, z: 10 })
+  updateHorseHeadAnimationFrame(state, HORSE_HEAD_TICK_SECONDS)
+  expect(state.limbSwingAmount).toBeCloseTo(0.16)
+  expect(getInterpolatedHorseHeadAnimation(state, 0).limbSwingAmount).toBe(0)
+  expect(getInterpolatedHorseHeadAnimation(state, 1).limbSwingAmount).toBeCloseTo(0.16)
+})
+
+test('movement position is consumed once per render tick', () => {
+  const state = createHorseHeadAnimationState()
+  setHorseHeadAnimationPosition(state, { x: 10, z: 10 })
+  updateHorseHeadAnimationFrame(state, HORSE_HEAD_TICK_SECONDS)
+  setHorseHeadAnimationPosition(state, { x: 10.1, z: 10 })
+  updateHorseHeadAnimationFrame(state, HORSE_HEAD_TICK_SECONDS)
+  expect(state.limbSwingAmount).toBeCloseTo(0.16)
+
+  setHorseHeadAnimationPosition(state, { x: 10.2, z: 10 })
+  expect(state.limbSwingAmount).toBeCloseTo(0.16)
+  updateHorseHeadAnimationFrame(state, HORSE_HEAD_TICK_SECONDS)
+  expect(state.limbSwingAmount).toBeCloseTo(0.256)
+  expect(state.limbSwing).toBeCloseTo(0.416)
+})
+
+test('render frames decay gait when a remote horse stops sending movement updates', () => {
+  const state = createHorseHeadAnimationState()
+  setHorseHeadAnimationPosition(state, { x: 10, z: 10 })
+  updateHorseHeadAnimationFrame(state, HORSE_HEAD_TICK_SECONDS)
+  setHorseHeadAnimationPosition(state, { x: 10.1, z: 10 })
+  updateHorseHeadAnimationFrame(state, HORSE_HEAD_TICK_SECONDS)
+  updateHorseHeadAnimationFrame(state, HORSE_HEAD_TICK_SECONDS)
+  expect(state.limbSwingAmount).toBeCloseTo(0.096)
+  expect(state.limbSwing).toBeCloseTo(0.256)
+})
+
+test('interpolates the leftover time after a tick at 30 FPS', () => {
+  const state = createHorseHeadAnimationState()
+  setHorseHeadAnimationPosition(state, { x: 10, z: 10 })
+  updateHorseHeadAnimationFrame(state, HORSE_HEAD_TICK_SECONDS)
+  setHorseHeadAnimationPosition(state, { x: 10.1, z: 10 })
+
+  updateHorseHeadAnimationFrame(state, 0.033)
+  const interpolated = updateHorseHeadAnimationFrame(state, 0.033)
+
+  expect(state.tickAccumulatorSeconds).toBeCloseTo(0.016)
+  expect(state.elapsedSeconds / HORSE_HEAD_TICK_SECONDS).toBeCloseTo(0.32)
+  expect(interpolated.limbSwingAmount).toBeCloseTo(0.16 * 0.32)
+})
+
+test('applying a pose changes only the runtime rig', () => {
+  const rig = new THREE.Group()
+  applyHorseHeadPose(rig, { pitch: 0.4, yaw: -0.2 })
+  expect(rig.rotation.x).toBeCloseTo(0.4)
+  expect(rig.rotation.y).toBeCloseTo(-0.2)
+  expect(rig.rotation.z).toBe(0)
+})

package/src/three/entity/horseHeadAnimation.ts

@@ -0,0 +1,151 @@
+//@ts-nocheck
+import * as THREE from 'three'
+
+export const HORSE_HEAD_PIVOT = { x: 0, y: 1.25, z: -0.75 } as const
+export const HORSE_HEAD_MAX_YAW = THREE.MathUtils.degToRad(20)
+export const HORSE_HEAD_TICK_SECONDS = 0.05
+
+const HORSE_HEAD_PART_NAMES = new Set([
+  'Head',
+  'UMouth',
+  'Ear1',
+  'Ear2',
+  'MuleEarL',
+  'MuleEarR',
+  'Neck',
+  'Mane',
+  'SaddleMouthL',
+  'SaddleMouthR',
+  'SaddleMouthLine',
+  'SaddleMouthLineR',
+  'HeadSaddle'
+])
+
+export type HorseHeadRig = THREE.Group & {
+  userData: THREE.Group['userData'] & { horseHeadParts: THREE.Object3D[] }
+}
+
+export const HORSE_HEAD_RIG_USER_DATA_KEY = '_horseHeadRig'
+export const HORSE_HEAD_ANIMATION_USER_DATA_KEY = '_horseHeadAnimation'
+
+/**
+ * Reparents every horse head-related OBJ object under the vanilla head_parts
+ * pivot while retaining each object's world transform.
+ */
+export function createHorseHeadRig(root: THREE.Object3D): HorseHeadRig {
+  const existing = root.userData[HORSE_HEAD_RIG_USER_DATA_KEY] as HorseHeadRig | undefined
+  if (existing) return existing
+
+  const parts: THREE.Object3D[] = []
+  root.traverse(child => {
+    if (child !== root && HORSE_HEAD_PART_NAMES.has(child.name)) parts.push(child)
+  })
+
+  const rig = new THREE.Group() as HorseHeadRig
+  rig.name = 'horse_head_rig'
+  rig.position.set(HORSE_HEAD_PIVOT.x, HORSE_HEAD_PIVOT.y, HORSE_HEAD_PIVOT.z)
+  rig.userData.horseHeadParts = parts
+  root.add(rig)
+
+  for (const part of parts) rig.attach(part)
+
+  root.userData[HORSE_HEAD_RIG_USER_DATA_KEY] = rig
+  return rig
+}
+
+export type HorseHeadPoseInput = {
+  entityPitch: number
+  headYaw: number
+  bodyYaw: number
+  limbSwing: number
+  limbSwingAmount: number
+}
+
+export type HorseHeadPose = {
+  pitch: number
+  yaw: number
+}
+
+export function normalizeYawDelta(fromYaw: number, toYaw: number): number {
+  const tau = Math.PI * 2
+  const delta = ((((toYaw - fromYaw + Math.PI) % tau) + tau) % tau) - Math.PI
+  return delta === -Math.PI ? Math.PI : delta
+}
+
+export function calculateHorseHeadPose(input: HorseHeadPoseInput): HorseHeadPose {
+  const { entityPitch, headYaw, bodyYaw, limbSwing, limbSwingAmount } = input
+  const safeAmount = Number.isFinite(limbSwingAmount) ? Math.max(0, limbSwingAmount) : 0
+  const gait = safeAmount > 0.2 ? Math.cos(limbSwing * 0.4) * 0.15 * safeAmount : 0
+  const relativeYaw = THREE.MathUtils.clamp(normalizeYawDelta(bodyYaw, headYaw), -HORSE_HEAD_MAX_YAW, HORSE_HEAD_MAX_YAW)
+  return {
+    pitch: (Number.isFinite(entityPitch) ? entityPitch : 0) - gait,
+    yaw: relativeYaw
+  }
+}
+
+export type HorseHeadAnimationState = {
+  lastPosition?: { x: number; z: number }
+  pendingPosition?: { x: number; z: number }
+  prevLimbSwing: number
+  limbSwing: number
+  prevLimbSwingAmount: number
+  limbSwingAmount: number
+  elapsedSeconds: number
+  tickAccumulatorSeconds: number
+}
+
+export function createHorseHeadAnimationState(): HorseHeadAnimationState {
+  return {
+    prevLimbSwing: 0,
+    limbSwing: 0,
+    prevLimbSwingAmount: 0,
+    limbSwingAmount: 0,
+    elapsedSeconds: HORSE_HEAD_TICK_SECONDS,
+    tickAccumulatorSeconds: 0
+  }
+}
+
+/** Save authoritative entity coordinates until the next animation tick. */
+export function setHorseHeadAnimationPosition(state: HorseHeadAnimationState, position: { x: number; z: number }): void {
+  state.pendingPosition = { x: position.x, z: position.z }
+}
+
+/** Advance using authoritative entity coordinates, before camera transforms. */
+export function advanceHorseHeadAnimation(state: HorseHeadAnimationState, position: { x: number; z: number }): void {
+  state.prevLimbSwing = state.limbSwing
+  state.prevLimbSwingAmount = state.limbSwingAmount
+
+  const distance = state.lastPosition == null ? 0 : Math.hypot(position.x - state.lastPosition.x, position.z - state.lastPosition.z)
+  const targetAmount = Math.min(1, distance * 4)
+  state.limbSwingAmount += (targetAmount - state.limbSwingAmount) * 0.4
+  state.limbSwing += state.limbSwingAmount
+  state.lastPosition = { x: position.x, z: position.z }
+}
+
+export function getInterpolatedHorseHeadAnimation(state: HorseHeadAnimationState, partialTick: number): { limbSwing: number; limbSwingAmount: number } {
+  const alpha = THREE.MathUtils.clamp(partialTick, 0, 1)
+  return {
+    limbSwing: state.prevLimbSwing + (state.limbSwing - state.prevLimbSwing) * alpha,
+    limbSwingAmount: state.prevLimbSwingAmount + (state.limbSwingAmount - state.prevLimbSwingAmount) * alpha
+  }
+}
+
+export function updateHorseHeadAnimationFrame(state: HorseHeadAnimationState, deltaSeconds: number): { limbSwing: number; limbSwingAmount: number } {
+  const safeDeltaSeconds = Math.max(0, deltaSeconds)
+  state.elapsedSeconds = Math.min(HORSE_HEAD_TICK_SECONDS, state.elapsedSeconds + safeDeltaSeconds)
+  state.tickAccumulatorSeconds += safeDeltaSeconds
+
+  while (state.tickAccumulatorSeconds >= HORSE_HEAD_TICK_SECONDS) {
+    const position = state.pendingPosition ?? state.lastPosition
+    if (position) advanceHorseHeadAnimation(state, position)
+    state.pendingPosition = undefined
+    state.tickAccumulatorSeconds -= HORSE_HEAD_TICK_SECONDS
+  }
+
+  state.elapsedSeconds = state.tickAccumulatorSeconds
+  return getInterpolatedHorseHeadAnimation(state, state.elapsedSeconds / HORSE_HEAD_TICK_SECONDS)
+}
+
+export function applyHorseHeadPose(rig: THREE.Object3D, pose: HorseHeadPose): void {
+  rig.rotation.set(pose.pitch, pose.yaw, 0)
+}

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

@@ -0,0 +1,77 @@
+//@ts-nocheck
+import * as THREE from 'three'
+import { expect, test } from 'vitest'
+import { SceneOrigin } from '../sceneOrigin'
+import { anchorVehiclePassengerPosition, releaseVehiclePassengerPosition } from './vehiclePassengerRendering'
+import { getHorsePassengerWorldPosition } from './interpolationPolicy'
+
+const LOCAL_PLAYER_ID = 7
+const REMOTE_PLAYER_ID = 8
+const HORSE_ID = '42'
+const HORSE_HEIGHT = 1.6
+
+type PassengerLike = THREE.Group & {
+  playerObject: Record<string, unknown>
+  originalEntity: { id: number }
+  userData: Record<string, unknown>
+}
+
+function makePassenger(id: number): PassengerLike {
+  const passenger = new THREE.Group() as PassengerLike
+  passenger.playerObject = {}
+  passenger.originalEntity = { id }
+  passenger.userData = {}
+  return passenger
+}
+
+test.each([
+  ['horse', 1.6, 0.85],
+  ['zombie_horse', 1.6, 0.85],
+  ['donkey', 1.5, 0.525],
+  ['mule', 1.6, 0.6],
+  ['skeleton_horse', 1.6, 0.6625]
+])('horse variant %s seat Y uses vanilla offset', (name, height, expectedFeetOffset) => {
+  const seat = getHorsePassengerWorldPosition({ x: 0, y: 64, z: 0 }, name, height)
+  expect(seat.y).toBeCloseTo(64 + expectedFeetOffset, 5)
+})
+
+test('local and remote horse passengers share the same anchor', () => {
+  const sceneOrigin = new SceneOrigin(new THREE.Scene())
+  sceneOrigin.update(96, 60, 192)
+
+  const horse = new THREE.Group()
+  sceneOrigin.track(horse)
+  horse.position.set(100, 64, 200)
+
+  const localPlayer = makePassenger(LOCAL_PLAYER_ID)
+  const remotePlayer = makePassenger(REMOTE_PLAYER_ID)
+  sceneOrigin.track(localPlayer)
+  sceneOrigin.track(remotePlayer)
+
+  const vehicleWorldPos = sceneOrigin.getWorldPosition(horse)!
+  const seatPosition = getHorsePassengerWorldPosition(vehicleWorldPos, 'horse', HORSE_HEIGHT)
+
+  anchorVehiclePassengerPosition(localPlayer, seatPosition, HORSE_ID)
+  anchorVehiclePassengerPosition(remotePlayer, seatPosition, HORSE_ID)
+
+  const localWorld = sceneOrigin.getWorldPosition(localPlayer)
+  const remoteWorld = sceneOrigin.getWorldPosition(remotePlayer)
+  expect(localWorld).toEqual(remoteWorld)
+})
+
+test('passenger anchor releases after detach', () => {
+  const sceneOrigin = new SceneOrigin(new THREE.Scene())
+  sceneOrigin.update(0, 0, 0)
+
+  const horse = new THREE.Group()
+  sceneOrigin.track(horse)
+  horse.position.set(0, 64, 0)
+
+  const passenger = makePassenger(LOCAL_PLAYER_ID)
+  sceneOrigin.track(passenger)
+
+  const seatPosition = getHorsePassengerWorldPosition({ x: 0, y: 64, z: 0 }, 'horse', HORSE_HEIGHT)
+  anchorVehiclePassengerPosition(passenger, seatPosition, HORSE_ID)
+  releaseVehiclePassengerPosition(passenger, HORSE_ID, sceneOrigin.getWorldPosition(passenger))
+  expect(passenger.userData._passengerVehicleId).toBeUndefined()
+})