minecraft-renderer 0.1.94 → 0.1.96

package/package.json

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

package/src/mesher-shared/exportedGeometryTypes.ts

@@ -1,6 +1,8 @@
 //@ts-nocheck
 /** Shared geometry export shapes (worker bridge + main-thread viewer). */
 
+import { SHADER_CUBES_FORMAT_VERSION } from './shaderCubeFormat'
+
 export interface ExportedSection {
   key: string
   position: { x: number; y: number; z: number }
@@ -25,7 +27,7 @@ export interface ExportedSection {
   shaderCubes?: {
     words: Uint32Array
     count: number
-    formatVersion: 3
+    formatVersion: typeof SHADER_CUBES_FORMAT_VERSION
   }
   visibilitySet?: number
 }

package/src/mesher-shared/shaderCubeFormat.ts

@@ -0,0 +1,3 @@
+//@ts-nocheck
+export const SHADER_CUBES_FORMAT_VERSION = 4 as const
+export const SHADER_CUBES_WORDS_PER_FACE = 4 as const

package/src/mesher-shared/shared.ts

@@ -1,5 +1,6 @@
 //@ts-nocheck
 import { BlockType } from '../playground/shared'
+import { SHADER_CUBES_FORMAT_VERSION } from './shaderCubeFormat'
 
 export const SECTION_HEIGHT = 16
 
@@ -80,7 +81,7 @@ export type MesherGeometryOutput = {
   shaderCubes?: {
     words: Uint32Array
     count: number
-    formatVersion: 3
+    formatVersion: typeof SHADER_CUBES_FORMAT_VERSION
   }
   /** Packed VisibilitySet (36 bits) for section occlusion / smart cull. */
   visibilitySet?: number

package/src/three/entities.ts

@@ -447,9 +447,7 @@ export class Entities {
   }
 
   private setSceneAttached(attached: boolean, entity: THREE.Object3D | null = null): void {
-    const targets = entity
-      ? [entity]
-      : [...Object.values(this.entities), ...(this.playerEntity ? [this.playerEntity] : [])]
+    const targets = entity ? [entity] : [...Object.values(this.entities), ...(this.playerEntity ? [this.playerEntity] : [])]
     for (const ent of targets) {
       if (attached) {
         if (!this.worldRenderer.scene.children.includes(ent)) this.worldRenderer.scene.add(ent)
@@ -655,7 +653,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)

package/src/three/shaders/cubeBlockShader.ts

@@ -7,6 +7,64 @@ export type { BlockLightmapParams }
 // Face order: UP=0, DOWN=1, EAST=2, WEST=3, SOUTH=4, NORTH=5
 // matches WASM mesher face order (mesher.rs FACE_NAMES)
 
+/** Term of tile-local UV in quad-corner coordinates (u, v ∈ {0,1}). */
+type FaceUvTerm = 'u' | '1-u' | 'v' | '1-v'
+
+/**
+ * Canonical tile-local UV per face for su>0, sv>0. Matches legacy elemFaces
+ * (+ implicit +180° on down; see render-from-wasm.ts `r += 180`).
+ * Index = faceId: UP, DOWN, EAST, WEST, SOUTH, NORTH.
+ * Single source of truth — GLSL and shaderCubeFaceUv() are generated from this.
+ */
+export const FACE_UV_TERMS: ReadonlyArray<readonly [FaceUvTerm, FaceUvTerm]> = [
+  ['u', '1-v'], // UP
+  ['1-u', 'v'], // DOWN
+  ['v', 'u'], // EAST
+  ['v', 'u'], // WEST
+  ['u', 'v'], // SOUTH
+  ['1-u', 'v'] // NORTH
+]
+
+const glslTerm = (t: FaceUvTerm) =>
+  ({
+    u: 'u',
+    v: 'v',
+    '1-u': '1.0 - u',
+    '1-v': '1.0 - v'
+  })[t]
+
+/** GLSL if/else-if chain for per-face UV — must stay in sync with FACE_UV_TERMS. */
+export function buildFaceUvGlsl(): string {
+  return FACE_UV_TERMS.map(([ut, vt], i) => `    ${i === 0 ? 'if' : 'else if'} (faceId == ${i}u) uv = vec2(${glslTerm(ut)}, ${glslTerm(vt)});`).join('\n')
+}
+
+function evalFaceUvTerm(t: FaceUvTerm, cu: number, cv: number): number {
+  switch (t) {
+    case 'u':
+      return cu
+    case '1-u':
+      return 1 - cu
+    case 'v':
+      return cv
+    case '1-v':
+      return 1 - cv
+  }
+}
+
+/** vi — quad corner in shader order (0..3): u = vi & 1, v = (vi >> 1) & 1. */
+export function shaderCubeFaceUv(faceId: number, vi: number, flipU: boolean, flipV: boolean): [number, number] {
+  const [ut, vt] = FACE_UV_TERMS[faceId] ?? FACE_UV_TERMS[0]
+  const cu = vi & 1
+  const cv = (vi >> 1) & 1
+  let uLocal = evalFaceUvTerm(ut, cu, cv)
+  let vLocal = evalFaceUvTerm(vt, cu, cv)
+  if (flipU) uLocal = 1 - uLocal
+  if (flipV) vLocal = 1 - vLocal
+  return [uLocal, vLocal]
+}
+
+const faceUvGlsl = buildFaceUvGlsl()
+
 const vertexShader = /* glsl */ `
 precision highp float;
 precision highp int;
@@ -143,18 +201,16 @@ void main() {
     v_tintIndex = int(tint);
     v_faceId = int(faceId);
 
-    // --- Per-face UV transform (legacy elemFaces + down +180°) ---
-    if (faceId == 0u) {
-        v_uv = vec2(u, 1.0 - v);
-    } else if (faceId == 1u) {
-        v_uv = vec2(1.0 - u, 1.0 - v);
-    } else if (faceId == 2u || faceId == 3u) {
-        v_uv = vec2(v, u);
-    } else if (faceId == 4u) {
-        v_uv = vec2(u, v);
-    } else { // faceId == 5u
-        v_uv = vec2(1.0 - u, v);
-    }
+    // --- Per-face UV: canonical tile-local UV (su>0, sv>0), generated from
+    // FACE_UV_TERMS — same source as shaderCubeFaceUv() ---
+    vec2 uv;
+${faceUvGlsl}
+
+    // su/sv sign from resolved model: negative scale = mirror on axis.
+    // Bit offsets mirror WORD2.FLIP_U_SHIFT / WORD0.FLIP_V_SHIFT (GLSL cannot import TS).
+    if (((a_w2 >> 31u) & 0x1u) != 0u) uv.x = 1.0 - uv.x;
+    if (((a_w0 >> 31u) & 0x1u) != 0u) uv.y = 1.0 - uv.y;
+    v_uv = uv;
 
     // --- Position: section base (multiples of 16) + face quad + block-local 0..15 ---
     // Must mirror WORD2/WORD3 constants in TS (GLSL cannot import them).
@@ -321,6 +377,9 @@ void main() {
 }
 `
 
+/** Vertex shader source (includes generated face UV table). Exported for parity tests. */
+export const cubeBlockVertexShader = vertexShader
+
 export function createCubeBlockMaterial(): THREE.ShaderMaterial {
   return new THREE.ShaderMaterial({
     vertexShader,
@@ -417,7 +476,8 @@ export const WORD0 = {
   FACE_SHIFT: 12,
   TINT_SHIFT: 15,
   AO_SHIFT: 23,
-  TRANSPARENT_SHIFT: 31
+  /** sv<0 mirror flag — no free bits remain in word0 after this. */
+  FLIP_V_SHIFT: 31
 } as const
 
 export const WORD1 = {
@@ -434,7 +494,8 @@ export const WORD2 = {
   SECTION_X_HI_SHIFT: 19,
   SECTION_Z_HI_SHIFT: 25,
   SECTION_HI_BITS: 6,
-  SPARE_BITS: 1
+  /** su<0 mirror flag — no free bits remain in word2 after this. */
+  FLIP_U_SHIFT: 31
 } as const
 
 /** Section base X/Z: low 16 bits in a_w3, high 6 in a_w2 (22-bit biased section index). */

package/src/three/worldGeometryExport.ts

@@ -5,6 +5,7 @@ import type { ExportedSection, ExportedWorldGeometry } from '../mesher-shared/ex
 import { calculateSkyLightSimple } from '../lib/skyLight'
 import { bakeLegacyVertexColors } from '../lib/bakeLegacyLight'
 import { getShaderCubeResources } from '../wasm-mesher/bridge/shaderCubeBridge'
+import { SHADER_CUBES_FORMAT_VERSION } from '../mesher-shared/shaderCubeFormat'
 import { createCubeBlockMaterial, setCubeSkyLevel } from './shaders/cubeBlockShader'
 import { createShaderCubeMesh } from './shaderCubeMesh'
 
@@ -181,6 +182,8 @@ export function createMeshesFromExport(
 ): THREE.Group[] {
   const groups: THREE.Group[] = []
   const resolvedShaderMat = shaderMaterial ?? shaderMaterialForExport(material, skyLevel)
+  let skippedShaderCubeSections = 0
+  let skippedShaderCubeFormatVersion: number | undefined
 
   for (const section of exportData.sections) {
     const group = new THREE.Group()
@@ -213,9 +216,14 @@ export function createMeshesFromExport(
 
     const shaderCubes = section.shaderCubes
     if (shaderCubes && shaderCubes.count > 0 && resolvedShaderMat) {
-      const shaderMesh = createShaderCubeMesh(shaderCubes, resolvedShaderMat)
-      shaderMesh.position.set(section.position.x, section.position.y, section.position.z)
-      group.add(shaderMesh)
+      if (shaderCubes.formatVersion !== SHADER_CUBES_FORMAT_VERSION) {
+        skippedShaderCubeSections++
+        skippedShaderCubeFormatVersion ??= shaderCubes.formatVersion
+      } else {
+        const shaderMesh = createShaderCubeMesh(shaderCubes, resolvedShaderMat)
+        shaderMesh.position.set(section.position.x, section.position.y, section.position.z)
+        group.add(shaderMesh)
+      }
     }
 
     if (group.children.length > 0) {
@@ -223,6 +231,13 @@ export function createMeshesFromExport(
     }
   }
 
+  if (skippedShaderCubeSections > 0) {
+    console.warn(
+      `[worldGeometryExport] Skipped ${skippedShaderCubeSections} shader-cube section(s): ` +
+        `export format ${skippedShaderCubeFormatVersion} ≠ current ${SHADER_CUBES_FORMAT_VERSION}`
+    )
+  }
+
   return groups
 }