minecraft-renderer 0.1.36 → 0.1.38

package/package.json

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

package/src/graphicsBackend/config.ts

@@ -19,7 +19,7 @@ export const defaultWorldRendererConfig = {
 
   // Debug settings
   showChunkBorders: false,
-  enableDebugOverlay: true,
+  enableDebugOverlay: false,
   debugModelVariant: undefined as undefined | number[],
   futuristicReveal: false,
 

package/src/three/chunkMeshManager.ts

@@ -28,17 +28,46 @@ export interface SectionObject extends THREE.Group {
   headsContainer?: THREE.Group
   bannersContainer?: THREE.Group
   boxHelper?: THREE.BoxHelper
+  /**
+   * World-space coordinates of the section origin. Cached so that
+   * {@link ChunkMeshManager.updateBoxHelper} can position lazily-created
+   * border helpers correctly under camera-relative rendering, where
+   * `mesh.position` is proxied to (world - sceneOrigin) and cannot be
+   * reused directly for objects that are tracked separately.
+   */
+  worldX?: number
+  worldY?: number
+  worldZ?: number
   foutain?: boolean
+  /**
+   * True while the section is held invisible by the "Batch Chunks Display"
+   * (`_renderByChunks`) feature, waiting for the parent chunk to finish meshing
+   * before being shown together with the rest of the chunk.
+   */
+  _waitingForChunkDisplay?: boolean
 }
 
 export class ChunkMeshManager {
   private readonly meshPool: ChunkMeshPool[] = []
   private readonly activeSections = new Map<string, ChunkMeshPool>()
   readonly sectionObjects: Record<string, SectionObject> = {}
+  /**
+   * Sections kept invisible because the "Batch Chunks Display" option is on
+   * and their parent chunk hasn't finished meshing yet. Keyed by chunk key
+   * (`x,z`); flushed by `WorldRendererThree.finishChunk(chunkKey)`.
+   */
+  readonly waitingChunksToDisplay: Record<string, string[]> = {}
   private poolSize!: number
   private maxPoolSize!: number
   private minPoolSize!: number
   private readonly signHeadsRenderer: SignHeadsRenderer
+  /**
+   * Shared transparent material used as the basis for the wireframe chunk
+   * border `BoxHelper` created lazily in {@link updateBoxHelper}. Kept on the
+   * manager so the BoxHelper machinery doesn't allocate a new material per
+   * section.
+   */
+  private readonly chunkBoxMaterial = new THREE.MeshBasicMaterial({ color: 0x00_00_00, transparent: true, opacity: 0 })
 
   // Performance tracking
   private hits = 0
@@ -64,7 +93,7 @@ export class ChunkMeshManager {
 
   constructor (
     public worldRenderer: WorldRendererThree,
-    public scene: THREE.Group,
+    public scene: THREE.Object3D,
     public material: THREE.Material,
     public worldHeight: number,
     viewDistance = 3,
@@ -156,6 +185,17 @@ export class ChunkMeshManager {
     // Store metadata
     sectionObject.tilesCount = geometryData.positions.length / 3 / 4
     sectionObject.blocksCount = geometryData.blocksCount
+    sectionObject.worldX = geometryData.sx
+    sectionObject.worldY = geometryData.sy
+    sectionObject.worldZ = geometryData.sz
+    // Stamp the section key so modules (e.g. sciFiWorldReveal) can resolve
+    // mesh -> section without falling back to sceneOrigin world-position math.
+    ;(sectionObject as any).sectionKey = sectionKey
+    // Tag the group so `WorldRendererThree.getThirdPersonCamera` raycast can
+    // still find chunk meshes — the old `WorldBlockGeometry` set this name
+    // unconditionally; the pooling port lost that and only the border-helper
+    // path used to restore it.
+    sectionObject.name = 'chunk'
 
     try {
       // Add signs container
@@ -218,13 +258,64 @@ export class ChunkMeshManager {
     this.scene.add(sectionObject)
     sectionObject.matrixAutoUpdate = false
 
+    // Create chunk border helper eagerly when the option is on so freshly
+    // streamed sections immediately get the F3+G yellow wireframe instead of
+    // appearing only on the next toggle.
+    if (this.worldRenderer.displayOptions?.inWorldRenderingConfig?.showChunkBorders) {
+      this.updateBoxHelper(sectionKey, true)
+    }
+
+    // Honor "Batch Chunks Display" (`_renderByChunks`): keep this section's
+    // mesh hidden until the whole chunk has finished meshing, so users see a
+    // chunk appear as a single 16xHx16 tile instead of streaming per-section.
+    // Updates to chunks that are already finished bypass batching to avoid
+    // flickering on block changes / lighting updates.
+    const chunkCoords = sectionKey.split(',')
+    const chunkKey = `${chunkCoords[0]},${chunkCoords[2]}`
+    const renderByChunks = !!this.worldRenderer.displayOptions
+      ?.inWorldRenderingConfig?._renderByChunks
+    if (renderByChunks && !this.worldRenderer.finishedChunks[chunkKey]) {
+      sectionObject.visible = false
+      sectionObject._waitingForChunkDisplay = true
+      const list = this.waitingChunksToDisplay[chunkKey] ?? (this.waitingChunksToDisplay[chunkKey] = [])
+      if (!list.includes(sectionKey)) list.push(sectionKey)
+    }
+
     return sectionObject
   }
 
+  /**
+   * Reveal all sections of a chunk that were held invisible by the
+   * "Batch Chunks Display" option. Called from `WorldRendererThree.finishChunk`.
+   */
+  finishChunkDisplay (chunkKey: string): void {
+    const sectionKeys = this.waitingChunksToDisplay[chunkKey]
+    if (!sectionKeys) return
+    for (const sectionKey of sectionKeys) {
+      const sectionObject = this.sectionObjects[sectionKey]
+      if (!sectionObject) continue
+      sectionObject._waitingForChunkDisplay = false
+      sectionObject.visible = true
+    }
+    delete this.waitingChunksToDisplay[chunkKey]
+  }
+
   cleanupSection (sectionKey: string) {
     // Remove section object from scene
     const sectionObject = this.sectionObjects[sectionKey]
     if (sectionObject) {
+      // Drop from any pending "batch display" queue so we don't try to flip
+      // visibility on a stale (released) object later.
+      if (sectionObject._waitingForChunkDisplay) {
+        const chunkCoords = sectionKey.split(',')
+        const chunkKey = `${chunkCoords[0]},${chunkCoords[2]}`
+        const list = this.waitingChunksToDisplay[chunkKey]
+        if (list) {
+          const idx = list.indexOf(sectionKey)
+          if (idx !== -1) list.splice(idx, 1)
+          if (list.length === 0) delete this.waitingChunksToDisplay[chunkKey]
+        }
+      }
       // Cleanup banner textures before disposing
       if (sectionObject.bannersContainer) {
         sectionObject.bannersContainer.traverse((child) => {
@@ -243,6 +334,21 @@ export class ChunkMeshManager {
       }
       this.worldRenderer.sceneOrigin.removeAndUntrackAll(sectionObject)
       this.scene.remove(sectionObject)
+      // boxHelper lives directly on the scene (so it stays world-anchored
+      // under camera-relative rendering), so it must be cleaned up explicitly
+      // — `removeAndUntrackAll` above only walks `sectionObject` descendants.
+      if (sectionObject.boxHelper) {
+        this.worldRenderer.sceneOrigin.removeAndUntrack(sectionObject.boxHelper)
+        this.scene.remove(sectionObject.boxHelper)
+        sectionObject.boxHelper.geometry.dispose()
+        const helperMat = sectionObject.boxHelper.material as THREE.Material | THREE.Material[]
+        if (Array.isArray(helperMat)) {
+          for (const m of helperMat) m.dispose()
+        } else {
+          helperMat.dispose()
+        }
+        sectionObject.boxHelper = undefined
+      }
       delete this.sectionObjects[sectionKey]
     }
   }
@@ -285,19 +391,28 @@ export class ChunkMeshManager {
   /**
    * Update box helper for a section
    */
-  updateBoxHelper (sectionKey: string, showChunkBorders: boolean, chunkBoxMaterial: THREE.Material) {
+  updateBoxHelper (sectionKey: string, showChunkBorders: boolean, chunkBoxMaterial: THREE.Material = this.chunkBoxMaterial) {
     const sectionObject = this.sectionObjects[sectionKey]
     if (!sectionObject?.mesh) return
 
     if (showChunkBorders) {
       if (!sectionObject.boxHelper) {
-        // mesh with static dimensions: 16x16x16
+        // Build a 16x16x16 reference mesh in world coordinates so BoxHelper's
+        // `setFromObject` produces the correct geometry. The reference mesh is
+        // not added to the scene; only the resulting BoxHelper is.
         const staticChunkMesh = new THREE.Mesh(new THREE.BoxGeometry(16, 16, 16), chunkBoxMaterial)
-        staticChunkMesh.position.copy(sectionObject.mesh.position)
         const boxHelper = new THREE.BoxHelper(staticChunkMesh, 0xff_ff_00)
         boxHelper.name = 'helper'
-        sectionObject.add(boxHelper)
-        sectionObject.name = 'chunk'
+        // Add directly to the scene and track it through sceneOrigin so that
+        // camera-relative rendering (floating origin) keeps the helper pinned
+        // to its world coordinates instead of following the camera.
+        const sx = sectionObject.worldX ?? 0
+        const sy = sectionObject.worldY ?? 0
+        const sz = sectionObject.worldZ ?? 0
+        this.worldRenderer.sceneOrigin.track(boxHelper, { updateMatrix: true })
+        boxHelper.position.set(sx, sy, sz)
+        boxHelper.updateMatrix()
+        this.scene.add(boxHelper)
         sectionObject.boxHelper = boxHelper
       }
       sectionObject.boxHelper.visible = true
@@ -306,6 +421,28 @@ export class ChunkMeshManager {
     }
   }
 
+  /**
+   * Create / toggle chunk border helpers for every active section. Used by
+   * `WorldRendererThree.updateShowChunksBorder` so the F3+G hotkey works
+   * after the move from `WorldBlockGeometry` (which created the helpers
+   * eagerly per section) to the pooled `ChunkMeshManager`.
+   */
+  updateAllBoxHelpers (showChunkBorders: boolean) {
+    for (const sectionKey of Object.keys(this.sectionObjects)) {
+      this.updateBoxHelper(sectionKey, showChunkBorders)
+    }
+  }
+
+  /**
+   * Forward to {@link SignHeadsRenderer.cleanChunkTextures} so callers in
+   * `WorldRendererThree` (which historically owned the sign-texture cache)
+   * can invalidate cached sign textures when a section is marked dirty,
+   * without reaching into the manager's private members.
+   */
+  cleanSignChunkTextures (x: number, z: number) {
+    this.signHeadsRenderer.cleanChunkTextures(x, z)
+  }
+
   /**
    * Get mesh for section if it exists
    */
@@ -459,6 +596,7 @@ export class ChunkMeshManager {
 
     this.meshPool.length = 0
     this.activeSections.clear()
+    this.chunkBoxMaterial.dispose()
   }
 
   // Private helper methods
@@ -667,6 +805,12 @@ export class ChunkMeshManager {
   updateSectionsVisibility (): void {
     const cameraPos = this.worldRenderer.cameraSectionPos
     for (const [sectionKey, sectionObject] of Object.entries(this.sectionObjects)) {
+      // Don't override "Batch Chunks Display" hiding — those sections must
+      // stay invisible until their chunk finishes meshing.
+      if (sectionObject._waitingForChunkDisplay) {
+        sectionObject.visible = false
+        continue
+      }
       if (!this.performanceOverrideDistance) {
         sectionObject.visible = true
         continue
@@ -805,4 +949,21 @@ class SignHeadsRenderer {
     textures[texturekey] = tex
     return tex
   }
+
+  /**
+   * Dispose all cached sign textures for the chunk containing world coords
+   * (x, z). Called from `WorldRendererThree.cleanChunkTextures` so that
+   * re-meshes triggered by `setSectionDirty` (e.g. a player edits a sign)
+   * pick up fresh block-entity NBT instead of returning the stale cached
+   * texture from {@link SignHeadsRenderer.getSignTexture}.
+   */
+  cleanChunkTextures (x: number, z: number) {
+    const key = `${Math.floor(x / 16)},${Math.floor(z / 16)}`
+    const textures = this.chunkTextures.get(key)
+    if (!textures) return
+    for (const k of Object.keys(textures)) {
+      textures[k].dispose()
+      delete textures[k]
+    }
+  }
 }

package/src/three/holdingBlock.ts

@@ -1,7 +1,6 @@
 //@ts-nocheck
 import * as THREE from 'three'
 import * as tweenJs from '@tweenjs/tween.js'
-import PrismarineItem from 'prismarine-item'
 import { WorldBlockProvider } from 'mc-assets/dist/worldBlockProvider'
 import { BlockModel } from 'mc-assets'
 import { DebugGui } from '../lib/DebugGui'
@@ -17,8 +16,14 @@ import { getThreeBlockModelGroup } from '../mesher/standaloneRenderer'
 import { IndexedData } from 'minecraft-data'
 import { WorldRendererConfig } from '../graphicsBackend'
 import { computeCameraBob, type CameraBobInput } from '../lib/cameraBobbing'
+import { getFirstPersonItemSpecificProps, getHandItemRenderKey } from './holdingBlockItemIdentity'
 
 const _tempMat = new THREE.Matrix4()
+const wrapPi = (a: number) => {
+  a = (a + Math.PI) % (Math.PI * 2)
+  if (a < 0) a += Math.PI * 2
+  return a - Math.PI
+}
 
 // Vanilla renderPlayerArm transform chain
 function buildBareHandMatrix(swingProgress: number, equipProgress: number): THREE.Matrix4 {
@@ -94,6 +99,7 @@ export default class HoldingBlock implements IHoldingBlock {
   equipProgress = 0 // 0 = fully visible, 1 = hidden
   stopUpdate = false
   lastHeldItem: HandItemBlock | undefined
+  lastHeldItemRenderKey: string | undefined
   currentDisplayType: 'hand' | 'item' | 'block' = 'hand'
   isSwinging = false
   nextIterStopCallbacks: Array<() => void> | undefined
@@ -116,6 +122,7 @@ export default class HoldingBlock implements IHoldingBlock {
 
   constructor(public worldRenderer: WorldRendererThree, public offHand = false) {
     this.initCameraGroup()
+    this.swingAnimator = new HandSwingAnimator()
     this.unsubs.push(
       this.worldRenderer.onReactivePlayerStateUpdated('heldItemMain', () => {
         if (!this.offHand) {
@@ -332,44 +339,32 @@ export default class HoldingBlock implements IHoldingBlock {
   }
 
   isDifferentItem(block: HandItemBlock | undefined) {
-    const Item = PrismarineItem(this.worldRenderer.version)
-    if (!this.lastHeldItem) {
-      return true
-    }
-    if (this.lastHeldItem.name !== block?.name) {
-      return true
-    }
-    // eslint-disable-next-line sonarjs/prefer-single-boolean-return
-    if (!Item.equal(this.lastHeldItem.fullItem, block?.fullItem ?? {}) || JSON.stringify(this.lastHeldItem.fullItem.components) !== JSON.stringify(block?.fullItem?.components)) {
-      return true
-    }
-
-    return false
+    return this.lastHeldItemRenderKey !== getHandItemRenderKey(this.worldRenderer, block)
   }
 
   updateCameraGroup() {
     if (this.stopUpdate) return
     const { camera } = this
 
-    // Hand rotation momentum (xBob/yBob) — vanilla Minecraft inertia effect
-    // Use base rotation from CameraShake (actual player view angles)
     const now = performance.now()
     const baseRotation = this.worldRenderer.cameraShake.getBaseRotation()
     const actualPitch = baseRotation.pitch
     const actualYaw = baseRotation.yaw
+
     if (this.lastBobUpdateTime === 0) {
       this.xBob = actualPitch
       this.yBob = actualYaw
-      this.lastBobUpdateTime = now
     } else {
       const dt = Math.min((now - this.lastBobUpdateTime) / 1000, 0.1)
-      this.lastBobUpdateTime = now
-      const factor = 1 - Math.pow(0.5, dt * 20)
-      this.xBob += (actualPitch - this.xBob) * factor
-      this.yBob += (actualYaw - this.yBob) * factor
+      const pitchFactor = 1 - Math.pow(0.5, dt * 28)
+      const yawFactor = 1 - Math.pow(0.5, dt * 36)
+      this.xBob += (actualPitch - this.xBob) * pitchFactor
+      this.yBob += wrapPi(actualYaw - this.yBob) * yawFactor
     }
-    const pitchOffset = (actualPitch - this.xBob) * -0.1
-    const yawOffset = (actualYaw - this.yBob) * -0.1
+
+    this.lastBobUpdateTime = now
+    const pitchOffset = (actualPitch - this.xBob) * -0.05
+    const yawOffset = wrapPi(actualYaw - this.yBob) * -0.035
 
     this.cameraGroup.position.copy(camera.position)
     this.cameraGroup.rotation.copy(camera.rotation)
@@ -431,11 +426,7 @@ export default class HoldingBlock implements IHoldingBlock {
       const result = this.worldRenderer.entities.getItemMesh({
         ...handItem.fullItem,
         itemId: handItem.id,
-      }, {
-        'minecraft:display_context': 'firstperson',
-        'minecraft:use_duration': this.worldRenderer.playerStateReactive.itemUsageTicks,
-        'minecraft:using_item': !!this.worldRenderer.playerStateReactive.itemUsageTicks,
-      }, false, this.lastItemModelName)
+      }, getFirstPersonItemSpecificProps(this.worldRenderer), false, this.lastItemModelName)
       if (result) {
         const { mesh: itemMesh, isBlock, modelName } = result
         if (isBlock) {
@@ -487,8 +478,11 @@ export default class HoldingBlock implements IHoldingBlock {
       this.holdingBlock?.removeFromParent()
       this.holdingBlock = undefined
       this.currentDisplayType = 'hand'
-      this.swingAnimator?.stopSwing()
-      this.swingAnimator = undefined
+      const swingAnimator = this.swingAnimator
+      swingAnimator?.stopSwing()
+      if (swingAnimator) {
+        swingAnimator.type = 'hand'
+      }
       this.idleAnimator = undefined
       return
     }
@@ -516,10 +510,14 @@ export default class HoldingBlock implements IHoldingBlock {
 
   switchRequest = 0
   async setNewItem(handItem?: HandItemBlock) {
-    if (!this.isDifferentItem(handItem)) return
+    const nextRenderKey = getHandItemRenderKey(this.worldRenderer, handItem)
+    const itemChanged = this.lastHeldItemRenderKey !== nextRenderKey
+    this.lastHeldItem = handItem
+    if (!itemChanged) return
+
+    this.lastHeldItemRenderKey = nextRenderKey
     this.lastItemModelName = undefined
     const switchRequest = ++this.switchRequest
-    this.lastHeldItem = handItem
 
     let playAppearAnimation = false
     if (this.holdingBlock) {
@@ -535,7 +533,11 @@ export default class HoldingBlock implements IHoldingBlock {
 
     if (!handItem) {
       this.currentDisplayType = 'hand'
-      this.swingAnimator = undefined
+      const swingAnimator = this.swingAnimator
+      swingAnimator?.stopSwing()
+      if (swingAnimator) {
+        swingAnimator.type = 'hand'
+      }
       this.idleAnimator = undefined
       this.blockSwapAnimation = undefined
       return
@@ -553,8 +555,10 @@ export default class HoldingBlock implements IHoldingBlock {
       await this.playBlockSwapAnimation('appeared')
     }
 
-    this.swingAnimator = new HandSwingAnimator()
-    this.swingAnimator.type = result.type
+    const swingAnimator = this.swingAnimator
+    if (swingAnimator) {
+      swingAnimator.type = result.type
+    }
     // Idle animation disabled — walking bob is handled by vanilla bobView applied to cameraGroup
     this.idleAnimator = undefined
   }

package/src/three/holdingBlockItemIdentity.test.ts

@@ -0,0 +1,43 @@
+//@ts-nocheck
+import { expect, test, vi } from 'vitest'
+import { getHandItemRenderKey } from './holdingBlockItemIdentity'
+
+test('hand item render key ignores live use state but keeps first-person display context', () => {
+  const getItemRenderData = vi.fn(() => ({ modelName: 'item/bow' }))
+  const worldRenderer = {
+    playerStateReactive: {
+      itemUsageTicks: 20,
+    },
+    resourcesManager: {
+      currentResources: {},
+    },
+    getItemRenderData,
+  } as any
+
+  const handItem = {
+    type: 'item',
+    id: 261,
+    name: 'minecraft:bow',
+    fullItem: {
+      count: 1,
+    },
+  } as const
+
+  const activeKey = getHandItemRenderKey(worldRenderer, handItem)
+  worldRenderer.playerStateReactive.itemUsageTicks = 0
+  const idleKey = getHandItemRenderKey(worldRenderer, handItem)
+
+  expect(activeKey).toBe(idleKey)
+  expect(getItemRenderData).toHaveBeenNthCalledWith(1, {
+    ...handItem.fullItem,
+    itemId: handItem.id,
+  }, {
+    'minecraft:display_context': 'firstperson',
+  })
+  expect(getItemRenderData).toHaveBeenNthCalledWith(2, {
+    ...handItem.fullItem,
+    itemId: handItem.id,
+  }, {
+    'minecraft:display_context': 'firstperson',
+  })
+})

package/src/three/holdingBlockItemIdentity.ts

@@ -0,0 +1,30 @@
+//@ts-nocheck
+import type { HandItemBlock, ItemSpecificContextProperties } from '../playerState/types'
+import type { WorldRendererThree } from './worldRendererThree'
+
+export const getFirstPersonItemSpecificProps = (worldRenderer: WorldRendererThree): ItemSpecificContextProperties => ({
+  'minecraft:display_context': 'firstperson',
+  'minecraft:use_duration': worldRenderer.playerStateReactive.itemUsageTicks,
+  'minecraft:using_item': !!worldRenderer.playerStateReactive.itemUsageTicks,
+})
+
+const getFirstPersonItemIdentityProps = (): ItemSpecificContextProperties => ({
+  'minecraft:display_context': 'firstperson',
+})
+
+export const getHandItemRenderKey = (worldRenderer: WorldRendererThree, handItem?: HandItemBlock) => {
+  if (!handItem) return 'empty'
+  if (handItem.type === 'hand') return 'hand'
+
+  const itemIdentifier = handItem.name ?? (handItem.id !== undefined ? `#${handItem.id}` : 'unknown')
+  if (!worldRenderer.resourcesManager.currentResources) {
+    return `${handItem.type}:${itemIdentifier}`
+  }
+
+  const renderData = worldRenderer.getItemRenderData({
+    ...handItem.fullItem,
+    itemId: handItem.id,
+  }, getFirstPersonItemIdentityProps())
+
+  return `${handItem.type}:${itemIdentifier}:${renderData.modelName}`
+}

package/src/three/holdingBlockLegacy.ts

@@ -1,7 +1,6 @@
 //@ts-nocheck
 import * as THREE from 'three'
 import * as tweenJs from '@tweenjs/tween.js'
-import PrismarineItem from 'prismarine-item'
 import { WorldBlockProvider } from 'mc-assets/dist/worldBlockProvider'
 import { BlockModel } from 'mc-assets'
 import { DebugGui } from '../lib/DebugGui'
@@ -17,6 +16,7 @@ import { getThreeBlockModelGroup } from '../mesher/standaloneRenderer'
 import { IndexedData } from 'minecraft-data'
 import { WorldRendererConfig } from '../graphicsBackend'
 import { IHoldingBlock } from './holdingBlockTypes'
+import { getFirstPersonItemSpecificProps, getHandItemRenderKey } from './holdingBlockItemIdentity'
 
 const rotationPositionData = {
   itemRight: {
@@ -103,6 +103,7 @@ export default class HoldingBlockLegacy implements IHoldingBlock {
   camera = new THREE.PerspectiveCamera(75, 1, 0.1, 100)
   stopUpdate = false
   lastHeldItem: HandItemBlock | undefined
+  lastHeldItemRenderKey: string | undefined
   isSwinging = false
   nextIterStopCallbacks: Array<() => void> | undefined
   idleAnimator: HandIdleAnimator | undefined
@@ -304,19 +305,7 @@ export default class HoldingBlockLegacy implements IHoldingBlock {
   }
 
   isDifferentItem(block: HandItemBlock | undefined) {
-    const Item = PrismarineItem(this.worldRenderer.version)
-    if (!this.lastHeldItem) {
-      return true
-    }
-    if (this.lastHeldItem.name !== block?.name) {
-      return true
-    }
-    // eslint-disable-next-line sonarjs/prefer-single-boolean-return
-    if (!Item.equal(this.lastHeldItem.fullItem, block?.fullItem ?? {}) || JSON.stringify(this.lastHeldItem.fullItem.components) !== JSON.stringify(block?.fullItem?.components)) {
-      return true
-    }
-
-    return false
+    return this.lastHeldItemRenderKey !== getHandItemRenderKey(this.worldRenderer, block)
   }
 
   updateCameraGroup() {
@@ -355,11 +344,7 @@ export default class HoldingBlockLegacy implements IHoldingBlock {
       const result = this.worldRenderer.entities.getItemMesh({
         ...handItem.fullItem,
         itemId: handItem.id,
-      }, {
-        'minecraft:display_context': 'firstperson',
-        'minecraft:use_duration': this.worldRenderer.playerStateReactive.itemUsageTicks,
-        'minecraft:using_item': !!this.worldRenderer.playerStateReactive.itemUsageTicks,
-      }, false, this.lastItemModelName)
+      }, getFirstPersonItemSpecificProps(this.worldRenderer), false, this.lastItemModelName)
       if (result) {
         const { mesh: itemMesh, isBlock, modelName } = result
         if (isBlock) {
@@ -421,10 +406,14 @@ export default class HoldingBlockLegacy implements IHoldingBlock {
 
   switchRequest = 0
   async setNewItem(handItem?: HandItemBlock) {
-    if (!this.isDifferentItem(handItem)) return
+    const nextRenderKey = getHandItemRenderKey(this.worldRenderer, handItem)
+    const itemChanged = this.lastHeldItemRenderKey !== nextRenderKey
+    this.lastHeldItem = handItem
+    if (!itemChanged) return
+
+    this.lastHeldItemRenderKey = nextRenderKey
     this.lastItemModelName = undefined
     const switchRequest = ++this.switchRequest
-    this.lastHeldItem = handItem
     let playAppearAnimation = false
     if (this.holdingBlock) {
       // play disappear animation
@@ -472,7 +461,8 @@ export default class HoldingBlockLegacy implements IHoldingBlock {
       await this.playBlockSwapAnimation('appeared')
     }
 
-    this.swingAnimator = new HandSwingAnimator(this.holdingBlockInnerGroup)
+    this.swingAnimator ??= new HandSwingAnimator(this.holdingBlockInnerGroup)
+    this.swingAnimator.setHandMesh(this.holdingBlockInnerGroup)
     this.swingAnimator.type = result.type
     if (this.config.viewBobbing) {
       this.idleAnimator = new HandIdleAnimator(this.holdingBlockInnerGroup, this.worldRenderer.playerStateReactive)
@@ -783,9 +773,9 @@ class HandSwingAnimator {
   private lastTime = 0
   private isAnimating = false
   private stopRequested = false
-  private readonly originalRotation: THREE.Euler
-  private readonly originalPosition: THREE.Vector3
-  private readonly originalScale: THREE.Vector3
+  private originalRotation: THREE.Euler
+  private originalPosition: THREE.Vector3
+  private originalScale: THREE.Vector3
 
   readonly debugParams = {
     // Animation timing
@@ -849,6 +839,13 @@ class HandSwingAnimator {
     // this.debugGui.activate()
   }
 
+  setHandMesh(handMesh: THREE.Object3D) {
+    this.handMesh = handMesh
+    this.originalRotation.copy(handMesh.rotation)
+    this.originalPosition.copy(handMesh.position)
+    this.originalScale.copy(handMesh.scale)
+  }
+
   update() {
     if (!this.isAnimating && !this.debugParams.animationStage) {
       // If not animating, ensure we're at original position

package/src/three/modules/sciFiWorldReveal.ts

@@ -58,7 +58,7 @@ export class SciFiWorldRevealModule implements RendererModuleController {
   // Store original methods for patching
   private originalFinishChunk: ((chunkKey: string) => void) | null = null
   private originalDestroy: (() => void) | null = null
-  private originalSceneAdd: ((...object: THREE.Object3D[]) => THREE.Group) | null = null
+  private originalSceneAdd: ((...object: THREE.Object3D[]) => THREE.Scene) | null = null
   private originalHandleWorkerMessage: ((data: { geometry: MesherGeometryOutput; key: string; type: string }) => void) | null = null
 
   private configEnabled = true
@@ -163,7 +163,7 @@ export class SciFiWorldRevealModule implements RendererModuleController {
 
     // Patch scene.add to intercept mesh additions
     this.originalSceneAdd = wr.scene.add.bind(wr.scene)
-    wr.scene.add = (...objects: THREE.Object3D[]): THREE.Group => {
+    wr.scene.add = (...objects: THREE.Object3D[]): THREE.Scene => {
       // Call original add first
       const result = this.originalSceneAdd!(...objects)
 

package/src/three/sceneOrigin.ts

@@ -174,7 +174,7 @@ export class SceneOrigin {
   /** Untrack an Object3D and remove it from the scene */
   removeAndUntrack(obj: Object3D): void {
     this.untrack(obj)
-    this.scene.remove(obj)
+    obj.removeFromParent()
   }
 
   /** Untrack an Object3D and all its descendants, then remove from the scene */
@@ -182,7 +182,7 @@ export class SceneOrigin {
     obj.traverse((child) => {
       this.untrack(child)
     })
-    this.scene.remove(obj)
+    obj.removeFromParent()
   }
 
   /** Get stored world position for a tracked object */