minecraft-renderer 0.1.94 → 0.1.95

package/package.json

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

package/src/three/entities.ts

@@ -655,7 +655,8 @@ export class Entities {
     applyVehiclePassengerPositions({
       entities: this.entities,
       localPlayer: this.playerEntity,
-      getWorldPosition: target => this.worldRenderer.sceneOrigin.getWorldPosition(target as SceneEntity)
+      getWorldPosition: target => this.worldRenderer.sceneOrigin.getWorldPosition(target as SceneEntity),
+      version: this.worldRenderer.version
     })
   }
 

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

@@ -10,6 +10,7 @@ import {
   getHorsePassengerWorldPosition,
   getLocalVehicleWorldPosition,
   getMinecartPassengerWorldPosition,
+  getVehiclePassengerFeetOffsetY,
   resolveLocalVehicleWorldPosition,
   samePosition,
   shouldRestartCameraPositionTween,
@@ -244,7 +245,28 @@ test('horse vertical camera lock falls back to raw Y when result is non-finite',
 })
 
 test('minecart passenger feet Y is vehicleY - 0.35', () => {
-  expect(getMinecartPassengerWorldPosition({ x: 0, y: 64, z: 0 }).y).toBeCloseTo(63.65, 5)
+  expect(getMinecartPassengerWorldPosition({ x: 0, y: 64, z: 0 }, '1.17.1', 'minecart', 0.7).y).toBeCloseTo(63.65, 5)
+})
+
+test.each([
+  ['1.17.1', 'boat', -0.45],
+  ['1.20.1', 'boat', -0.45],
+  ['1.20.2', 'boat', -0.4125],
+  ['1.21.4', 'boat', -0.4125],
+  ['1.17.1', 'minecart', -0.35],
+  ['1.20.1', 'minecart', -0.35],
+  ['1.20.2', 'minecart', -0.4125],
+  ['1.21.4', 'minecart', -0.4125],
+  ['1.21.4', 'bamboo_raft', -0.1]
+])('vehicle %s %s seat offset matches vanilla', (version, vehicleName, expected) => {
+  const layout = vehicleName === 'minecart' ? 'minecart' : 'boat'
+  const height = layout === 'boat' ? 0.5625 : 0.7
+  expect(getVehiclePassengerFeetOffsetY(layout, version, vehicleName, height)).toBeCloseTo(expected, 5)
+})
+
+test('vehicle seat offset falls back to the default vehicle height', () => {
+  expect(getVehiclePassengerFeetOffsetY('boat', '1.20.2', 'oak_boat', undefined)).toBeCloseTo(-0.4125, 5)
+  expect(getVehiclePassengerFeetOffsetY('minecart', '1.20.2', 'minecart', undefined)).toBeCloseTo(-0.4125, 5)
 })
 
 test.each([

package/src/three/entity/interpolationPolicy.ts

@@ -1,4 +1,6 @@
 //@ts-nocheck
+import { versionToNumber } from '../../lib/utils'
+
 export const LOCAL_MOVEMENT_TWEEN_DURATION_MS = 50
 export const ENTITY_TWEEN_DURATION_MS = 120
 export const SPECTATING_CAMERA_TWEEN_DURATION_MS = 150
@@ -116,11 +118,6 @@ export function resolveLocalVehicleWorldPosition(args: {
   return getLocalVehicleWorldPosition(cameraWorldPos, rawVehicleY)
 }
 
-const BOAT_PASSENGER_RIDING_OFFSET_Y = -0.1
-const PLAYER_RIDING_OFFSET_Y = -0.35
-/** Vanilla 1.17.1 AbstractMinecart#getPassengersRidingOffset() */
-const MINECART_PASSENGER_RIDING_OFFSET_Y = 0
-
 const RIDEABLE_MINECART_ENTITY_NAMES = new Set([
   'minecart',
   'chest_minecart',
@@ -148,21 +145,79 @@ export function getBoatPassengerSeatOffset(passengerIndex: number, passengerCoun
   return passengerIndex === 0 ? 0.2 : -0.6
 }
 
-/** Vanilla 1.17.1 Boat#positionRider position, without applying the passenger pose. */
-export function getBoatPassengerWorldPosition(boatWorldPos: Vec3Like, boatYaw: number, passengerIndex: number, passengerCount: number): Vec3Like {
+const DEFAULT_BOAT_HEIGHT = 0.5625
+const DEFAULT_MINECART_HEIGHT = 0.7
+
+// <= 1.20.1: Entity#positionRider = y + vehicle.getPassengersRidingOffset() + passenger.getMyRidingOffset()
+// Vanilla 1.17.1 sources: vehicle/Boat#getPassengersRidingOffset() = -0.1,
+// vehicle/AbstractMinecart#getPassengersRidingOffset() = 0, player/Player#getMyRidingOffset() = -0.35.
+const LEGACY_PLAYER_RIDING_OFFSET_Y = -0.35 // Player#getMyRidingOffset(), <= 1.20.1
+const LEGACY_BOAT_RIDING_OFFSET_Y = -0.1 // Boat#getPassengersRidingOffset(), <= 1.20.1
+const LEGACY_MINECART_RIDING_OFFSET_Y = 0 // AbstractMinecart#getPassengersRidingOffset(), <= 1.20.1
+
+// >= 1.20.2: y is based on the vehicle's PASSENGER attachment point.
+// The player's contribution is numerically the same, but the mechanism changed:
+//   1.20.2-1.20.4: PASSENGER.y + Player#ridingOffset() (-0.6)
+//   >= 1.20.5:     PASSENGER.y - Player.DEFAULT_VEHICLE_ATTACHMENT.y (0.6)
+// Vanilla sources: Entity#positionRider, Boat#getPassengerAttachmentPoint,
+// EntityType.*_MINECART#passengerAttachments and Player#ridingOffset / DEFAULT_VEHICLE_ATTACHMENT.
+const MODERN_PLAYER_RIDING_OFFSET_Y = -0.6
+const MODERN_MINECART_PASSENGER_ATTACHMENT_Y = 0.1875 // EntityType.*_MINECART.passengerAttachments()
+const MODERN_BOAT_RIDE_HEIGHT_FACTOR = 1 / 3 // (Abstract)Boat#rideHeight(), >= 1.20.2
+const MODERN_RAFT_RIDE_HEIGHT_FACTOR = 0.8888889 // Raft#rideHeight(), >= 1.21.2
+
+/**
+ * Vanilla seat offset for a player passenger in a boat or minecart.
+ * Rafts before 1.21.2 are intentionally treated as boats because their entity
+ * name is 'boat' and their metadata variant is not read by this project.
+ */
+export function getVehiclePassengerFeetOffsetY(
+  layout: 'boat' | 'minecart',
+  version: string,
+  vehicleName: string | undefined,
+  vehicleHeight: number | undefined
+): number {
+  const height = Number.isFinite(vehicleHeight) ? vehicleHeight! : layout === 'boat' ? DEFAULT_BOAT_HEIGHT : DEFAULT_MINECART_HEIGHT
+
+  if (versionToNumber(version) >= versionToNumber('1.20.2')) {
+    const isRaft = typeof vehicleName === 'string' && vehicleName.toLowerCase().endsWith('_raft')
+    const passengerAttachmentY =
+      layout === 'boat' ? height * (isRaft ? MODERN_RAFT_RIDE_HEIGHT_FACTOR : MODERN_BOAT_RIDE_HEIGHT_FACTOR) : MODERN_MINECART_PASSENGER_ATTACHMENT_Y
+    return passengerAttachmentY + MODERN_PLAYER_RIDING_OFFSET_Y
+  }
+
+  const vehicleRidingOffset = layout === 'boat' ? LEGACY_BOAT_RIDING_OFFSET_Y : LEGACY_MINECART_RIDING_OFFSET_Y
+  return vehicleRidingOffset + LEGACY_PLAYER_RIDING_OFFSET_Y
+}
+
+/** Vanilla Boat#positionRider position, without applying the passenger pose. */
+export function getBoatPassengerWorldPosition(
+  boatWorldPos: Vec3Like,
+  boatYaw: number,
+  passengerIndex: number,
+  passengerCount: number,
+  version: string,
+  vehicleName: string | undefined,
+  vehicleHeight: number | undefined
+): Vec3Like {
   const seatOffset = getBoatPassengerSeatOffset(passengerIndex, passengerCount)
   return {
     x: boatWorldPos.x - Math.sin(boatYaw) * seatOffset,
-    y: boatWorldPos.y + BOAT_PASSENGER_RIDING_OFFSET_Y + PLAYER_RIDING_OFFSET_Y,
+    y: boatWorldPos.y + getVehiclePassengerFeetOffsetY('boat', version, vehicleName, vehicleHeight),
     z: boatWorldPos.z + Math.cos(boatYaw) * seatOffset
   }
 }
 
-/** Vanilla 1.17.1 minecart positionRider for a centered player passenger. */
-export function getMinecartPassengerWorldPosition(minecartWorldPos: Vec3Like): Vec3Like {
+/** Vanilla minecart positionRider for a centered player passenger. */
+export function getMinecartPassengerWorldPosition(
+  minecartWorldPos: Vec3Like,
+  version: string,
+  vehicleName: string | undefined,
+  vehicleHeight: number | undefined
+): Vec3Like {
   return {
     x: minecartWorldPos.x,
-    y: minecartWorldPos.y + MINECART_PASSENGER_RIDING_OFFSET_Y + PLAYER_RIDING_OFFSET_Y,
+    y: minecartWorldPos.y + getVehiclePassengerFeetOffsetY('minecart', version, vehicleName, vehicleHeight),
     z: minecartWorldPos.z
   }
 }

package/src/three/entity/localVehicleRendering.integration.test.ts

@@ -14,6 +14,10 @@ import {
 
 type Vec3 = { x: number; y: number; z: number }
 
+const TEST_VERSION = '1.17.1'
+const BOAT_HEIGHT = 0.5625
+const MINECART_HEIGHT = 0.7
+
 function staleOffsetVehiclePosition(cameraWorldPos: Vec3, vehiclePosition: Vec3, stalePassengerPosition: Vec3): Vec3 {
   return {
     x: cameraWorldPos.x + (vehiclePosition.x - stalePassengerPosition.x),
@@ -74,23 +78,23 @@ test('render frames between press and release keep zero horizontal delta to came
 test('boat passenger positions use vanilla 1.17.1 riding and seat offsets', () => {
   const boat = { x: 10, y: 64, z: 20 }
 
-  expect(getBoatPassengerWorldPosition(boat, 0, 0, 1)).toEqual({
+  expect(getBoatPassengerWorldPosition(boat, 0, 0, 1, TEST_VERSION, 'oak_boat', BOAT_HEIGHT)).toEqual({
     x: 10,
     y: 63.55,
     z: 20
   })
-  expect(getBoatPassengerWorldPosition(boat, 0, 0, 2)).toEqual({
+  expect(getBoatPassengerWorldPosition(boat, 0, 0, 2, TEST_VERSION, 'oak_boat', BOAT_HEIGHT)).toEqual({
     x: 10,
     y: 63.55,
     z: 20.2
   })
-  expect(getBoatPassengerWorldPosition(boat, 0, 1, 2)).toEqual({
+  expect(getBoatPassengerWorldPosition(boat, 0, 1, 2, TEST_VERSION, 'oak_boat', BOAT_HEIGHT)).toEqual({
     x: 10,
     y: 63.55,
     z: 19.4
   })
 
-  const rotated = getBoatPassengerWorldPosition(boat, Math.PI / 2, 0, 2)
+  const rotated = getBoatPassengerWorldPosition(boat, Math.PI / 2, 0, 2, TEST_VERSION, 'oak_boat', BOAT_HEIGHT)
   expect(rotated.x).toBeCloseTo(9.8)
   expect(rotated.y).toBe(63.55)
   expect(rotated.z).toBeCloseTo(20)
@@ -110,7 +114,15 @@ test('remote player follows the tracked boat each frame and releases from an emp
   sceneOrigin.track(passenger)
   passenger.position.set(90, 64, 190)
 
-  const firstPassengerPosition = getBoatPassengerWorldPosition(sceneOrigin.getWorldPosition(boat)!, boat.rotation.y, 0, 1)
+  const firstPassengerPosition = getBoatPassengerWorldPosition(
+    sceneOrigin.getWorldPosition(boat)!,
+    boat.rotation.y,
+    0,
+    1,
+    TEST_VERSION,
+    'oak_boat',
+    BOAT_HEIGHT
+  )
   anchorVehiclePassengerPosition(passenger, firstPassengerPosition, '10')
 
   expect(stopPositionTween).toHaveBeenCalledOnce()
@@ -119,7 +131,15 @@ test('remote player follows the tracked boat each frame and releases from an emp
 
   boat.position.set(102, 64.2, 203)
   boat.rotation.y = Math.PI / 2
-  const movedPassengerPosition = getBoatPassengerWorldPosition(sceneOrigin.getWorldPosition(boat)!, boat.rotation.y, 0, 1)
+  const movedPassengerPosition = getBoatPassengerWorldPosition(
+    sceneOrigin.getWorldPosition(boat)!,
+    boat.rotation.y,
+    0,
+    1,
+    TEST_VERSION,
+    'oak_boat',
+    BOAT_HEIGHT
+  )
   anchorVehiclePassengerPosition(passenger, movedPassengerPosition, '10')
   expect(sceneOrigin.getWorldPosition(passenger)?.x).toBe(102)
   expect(sceneOrigin.getWorldPosition(passenger)?.y).toBeCloseTo(63.75)
@@ -142,7 +162,7 @@ test('remote player follows the tracked boat each frame and releases from an emp
 
 test('minecart passenger uses vanilla 1.17.1 riding Y offset', () => {
   const minecart = { x: 10, y: 64, z: 20 }
-  expect(getMinecartPassengerWorldPosition(minecart)).toEqual({
+  expect(getMinecartPassengerWorldPosition(minecart, TEST_VERSION, 'minecart', MINECART_HEIGHT)).toEqual({
     x: 10,
     y: 63.65,
     z: 20
@@ -163,13 +183,13 @@ test('minecart passenger anchor follows vehicle world position without inheritin
   sceneOrigin.track(passenger)
   passenger.position.set(90, 64, 190)
 
-  const firstPosition = getMinecartPassengerWorldPosition(sceneOrigin.getWorldPosition(minecart)!)
+  const firstPosition = getMinecartPassengerWorldPosition(sceneOrigin.getWorldPosition(minecart)!, TEST_VERSION, 'minecart', MINECART_HEIGHT)
   anchorVehiclePassengerPosition(passenger, firstPosition, '42')
   const anchoredYaw = passenger.rotation.y
 
   minecart.position.set(103, 64.5, 205)
   minecart.rotation.y = Math.PI
-  const movedPosition = getMinecartPassengerWorldPosition(sceneOrigin.getWorldPosition(minecart)!)
+  const movedPosition = getMinecartPassengerWorldPosition(sceneOrigin.getWorldPosition(minecart)!, TEST_VERSION, 'minecart', MINECART_HEIGHT)
   anchorVehiclePassengerPosition(passenger, movedPosition, '42')
 
   expect(sceneOrigin.getWorldPosition(passenger)).toEqual({
@@ -234,7 +254,7 @@ test('local minecart passenger anchors to camera-synced vehicle position', () =>
   for (const camera of cameraFrames) {
     const syncedMinecart = getLocalVehicleWorldPosition(camera, vehicleY)
     minecart.position.set(syncedMinecart.x, syncedMinecart.y, syncedMinecart.z)
-    const seatPosition = getMinecartPassengerWorldPosition(syncedMinecart)
+    const seatPosition = getMinecartPassengerWorldPosition(syncedMinecart, TEST_VERSION, 'minecart', MINECART_HEIGHT)
     anchorVehiclePassengerPosition(passenger, seatPosition, '42')
     const passengerWorld = sceneOrigin.getWorldPosition(passenger)!
 

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

@@ -10,6 +10,8 @@ const REMOTE_PLAYER_ID = 8
 const MINECART_ID = '42'
 const EYE_HEIGHT = 1.62
 const PLAYER_HEIGHT = 1.8
+const TEST_VERSION = '1.17.1'
+const MINECART_HEIGHT = 0.7
 
 type PassengerLike = THREE.Group & {
   playerObject: Record<string, unknown>
@@ -42,7 +44,7 @@ function anchorMinecartPassengers(
   remotePlayers: Record<number, PassengerLike>
 ) {
   const vehicleWorldPos = sceneOrigin.getWorldPosition(minecart)!
-  const seatPosition = getMinecartPassengerWorldPosition(vehicleWorldPos)
+  const seatPosition = getMinecartPassengerWorldPosition(vehicleWorldPos, TEST_VERSION, 'minecart', MINECART_HEIGHT)
   for (const passengerId of passengerIds) {
     const passenger = resolveMinecartPassenger(passengerId, localPlayer, remotePlayers)
     if (!passenger?.playerObject) continue
@@ -196,7 +198,7 @@ test('local boat passenger uses the same anchor as remote passenger', () => {
   sceneOrigin.track(localPlayer)
   sceneOrigin.track(remotePlayer)
 
-  const boatSeat = getBoatPassengerWorldPosition(sceneOrigin.getWorldPosition(boat)!, boat.rotation.y, 0, 1)
+  const boatSeat = getBoatPassengerWorldPosition(sceneOrigin.getWorldPosition(boat)!, boat.rotation.y, 0, 1, TEST_VERSION, 'oak_boat', 0.5625)
   if (shouldAnchorPassenger(localPlayer, 'boat', true)) {
     anchorVehiclePassengerPosition(localPlayer, boatSeat, '10')
   }

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

@@ -74,7 +74,7 @@ test('minecart passenger anchor preserves head rotation', () => {
   storeNetworkHeadPitch(userData, 0.45)
   applyNetworkHeadPitch(playerObject, userData)
 
-  const seat = getMinecartPassengerWorldPosition({ x: 10, y: 64, z: 20 })
+  const seat = getMinecartPassengerWorldPosition({ x: 10, y: 64, z: 20 }, '1.17.1', 'minecart', 0.7)
   anchorVehiclePassengerPosition(passenger, seat, '42')
   simulateAnimationFrames(playerObject, userData, 4)
 

package/src/three/entity/remoteBoatPassengerRotation.integration.test.ts

@@ -21,6 +21,7 @@ const BOAT_YAW = -0.5645049299419149
 const REMOTE_PLAYER_A = 8
 const REMOTE_PLAYER_B = 9
 const BOAT_ID = 10
+const TEST_VERSION = '1.17.1'
 
 function makePlayerObject(): PlayerObjectType {
   return new PlayerObject() as PlayerObjectType
@@ -71,7 +72,8 @@ function createHarness(passengerIds: number[]) {
     updateVehiclePassengerPositions({
       entities: entities as Parameters<typeof updateVehiclePassengerPositions>[0]['entities'],
       localPlayer: null,
-      getWorldPosition: target => sceneOrigin.getWorldPosition(target as THREE.Object3D)
+      getWorldPosition: target => sceneOrigin.getWorldPosition(target as THREE.Object3D),
+      version: TEST_VERSION
     })
 
   const runRemoteRotation = () =>

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

@@ -8,6 +8,7 @@ import { updateVehiclePassengerPositions, type VehiclePassengerSceneEntity, type
 
 const LOCAL_PLAYER_ID = 7
 const REMOTE_PLAYER_ID = 8
+const TEST_VERSION = '1.17.1'
 
 type PassengerLike = THREE.Group & VehiclePassengerSceneEntity
 
@@ -43,7 +44,8 @@ function createHarness() {
     updateVehiclePassengerPositions({
       entities,
       localPlayer,
-      getWorldPosition: target => sceneOrigin.getWorldPosition(target as THREE.Object3D)
+      getWorldPosition: target => sceneOrigin.getWorldPosition(target as THREE.Object3D),
+      version: TEST_VERSION
     })
 
   return { sceneOrigin, localPlayer, entities, cameraWorldPos, runUpdate }
@@ -65,7 +67,15 @@ test('updateVehiclePassengerPositions anchors local boat and minecart passengers
 
   runUpdate()
 
-  const expectedBoatSeat = getBoatPassengerWorldPosition(sceneOrigin.getWorldPosition(boat)!, boat.rotation.y, 0, 1)
+  const expectedBoatSeat = getBoatPassengerWorldPosition(
+    sceneOrigin.getWorldPosition(boat)!,
+    boat.rotation.y,
+    0,
+    1,
+    TEST_VERSION,
+    'oak_boat',
+    boat.originalEntity.height
+  )
   expect(localPlayer.userData._passengerVehicleId).toBe('10')
   expect(sceneOrigin.getWorldPosition(localPlayer)).toEqual(expectedBoatSeat)
 
@@ -77,7 +87,12 @@ test('updateVehiclePassengerPositions anchors local boat and minecart passengers
 
   runUpdate()
 
-  const expectedMinecartSeat = getMinecartPassengerWorldPosition(sceneOrigin.getWorldPosition(minecart)!)
+  const expectedMinecartSeat = getMinecartPassengerWorldPosition(
+    sceneOrigin.getWorldPosition(minecart)!,
+    TEST_VERSION,
+    'minecart',
+    minecart.originalEntity.height
+  )
   expect(localPlayer.userData._passengerVehicleId).toBe('42')
   expect(sceneOrigin.getWorldPosition(localPlayer)).toEqual(expectedMinecartSeat)
 })
@@ -119,8 +134,8 @@ test('local and remote boat passengers use the same seat algorithm per index', (
   const vehicleWorldPos = sceneOrigin.getWorldPosition(boat)!
   const localWorld = sceneOrigin.getWorldPosition(localPlayer)!
   const remoteWorld = sceneOrigin.getWorldPosition(remotePlayer)!
-  expect(localWorld).toEqual(getBoatPassengerWorldPosition(vehicleWorldPos, boat.rotation.y, 0, 2))
-  expect(remoteWorld).toEqual(getBoatPassengerWorldPosition(vehicleWorldPos, boat.rotation.y, 1, 2))
+  expect(localWorld).toEqual(getBoatPassengerWorldPosition(vehicleWorldPos, boat.rotation.y, 0, 2, TEST_VERSION, 'oak_boat', boat.originalEntity.height))
+  expect(remoteWorld).toEqual(getBoatPassengerWorldPosition(vehicleWorldPos, boat.rotation.y, 1, 2, TEST_VERSION, 'oak_boat', boat.originalEntity.height))
   expect(localWorld.y).toBeCloseTo(63.55, 5)
   expect(remoteWorld.y).toBeCloseTo(63.55, 5)
 })

package/src/three/entity/vehiclePassengerUpdate.ts

@@ -33,6 +33,7 @@ export function updateVehiclePassengerPositions(args: {
   entities: Record<string, VehiclePassengerSceneEntity | VehiclePassengerVehicle>
   localPlayer: VehiclePassengerSceneEntity | null
   getWorldPosition: (target: unknown) => Vec3Like | undefined
+  version: string
 }): Set<VehiclePassengerSceneEntity> {
   const attachedPassengers = new Set<VehiclePassengerSceneEntity>()
 
@@ -61,10 +62,18 @@ export function updateVehiclePassengerPositions(args: {
 
       const passengerWorldPos =
         layout === 'minecart'
-          ? getMinecartPassengerWorldPosition(vehicleWorldPos)
+          ? getMinecartPassengerWorldPosition(vehicleWorldPos, args.version, vehicleName, vehicle.originalEntity.height)
           : layout === 'horse'
             ? getHorsePassengerWorldPosition(vehicleWorldPos, vehicleName, vehicle.originalEntity.height ?? 1.6)
-            : getBoatPassengerWorldPosition(vehicleWorldPos, vehicle.rotation.y, passengerIndex, passengerIds.length)
+            : getBoatPassengerWorldPosition(
+                vehicleWorldPos,
+                vehicle.rotation.y,
+                passengerIndex,
+                passengerIds.length,
+                args.version,
+                vehicleName,
+                vehicle.originalEntity.height
+              )
 
       if (!isFiniteVec3(passengerWorldPos)) continue
       anchorVehiclePassengerPosition(passenger, passengerWorldPos, vehicleId)