minecraft-renderer 0.1.35 → 0.1.37

package/package.json

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

package/src/graphicsBackend/config.ts

@@ -32,6 +32,10 @@ export const defaultWorldRendererConfig = {
   autoLowerRenderDistance: false,
 
   // Rendering engine settings
+  /** Face shading: vanilla Minecraft vs higher-contrast client look */
+  shadingTheme: 'high-contrast' as 'vanilla' | 'high-contrast',
+  /** Synced from player reactive state (dimension / nether) — consumed by mesher */
+  cardinalLight: 'default' as string,
   dayCycle: true,
   smoothLighting: true,
   enableLighting: true,

package/src/graphicsBackend/playerState.ts

@@ -32,6 +32,7 @@ export const getInitialPlayerState = (): PlayerStateReactive => proxy({
   itemUsageTicks: 0,
   username: '',
   onlineMode: false,
+  cardinalLight: 'default',
   lightingDisabled: false,
   shouldHideHand: false,
   heldItemMain: undefined,

package/src/lib/worldrendererCommon.ts

@@ -124,6 +124,7 @@ export abstract class WorldRendererCommon<WorkerSend = any, WorkerReceive = any>
   soundSystem: SoundSystem | undefined
 
   abstract changeBackgroundColor(color: [number, number, number]): void
+  abstract changeCardinalLight(cardinalLight: string): void
 
   /** Override in subclass to check if any enabled module requires heightmap data */
   protected anyModuleRequiresHeightmap(): boolean {
@@ -310,6 +311,9 @@ export abstract class WorldRendererCommon<WorkerSend = any, WorkerReceive = any>
     this.onReactivePlayerStateUpdated('backgroundColor', (value) => {
       this.changeBackgroundColor(value)
     })
+    this.onReactivePlayerStateUpdated('cardinalLight', (value) => {
+      this.changeCardinalLight(value)
+    })
   }
 
   watchReactiveConfig() {
@@ -549,6 +553,8 @@ export abstract class WorldRendererCommon<WorkerSend = any, WorkerReceive = any>
       enableLighting: this.worldRendererConfig.enableLighting,
       skyLight,
       smoothLighting: this.worldRendererConfig.smoothLighting,
+      shadingTheme: this.worldRendererConfig.shadingTheme,
+      cardinalLight: this.worldRendererConfig.cardinalLight,
       outputFormat: this.outputFormat,
       // textureSize: this.resourcesManager.currentResources!.blocksAtlasParser.atlas.latest.width,
       debugModelVariant: this.worldRendererConfig.debugModelVariant,

package/src/mesher/models.ts

@@ -395,7 +395,16 @@ function renderElement(world: World, cursor: Vec3, element: BlockElement, doAO:
     const aos: number[] = []
     const neighborPos = position.plus(new Vec3(...dir))
     // 10%
-    const baseLight = world.getLight(neighborPos, undefined, undefined, block.name) / 15
+    const { smoothLighting, shadingTheme, cardinalLight } = world.config
+    const faceLight = world.getLight(neighborPos, undefined, undefined, block.name)
+    const sideShading = (shadingTheme === 'high-contrast')
+      ? (0.8 + 0.5 * Math.max(0, 0.66 * dir[0] + 0.66 * dir[1] + 0.33 * dir[2])) // old directional light behavior
+      : (
+          cardinalLight === 'nether'
+            ? (0.5 + Math.abs(0.1 * dir[0] + 0.4 * dir[1] + 0.3 * dir[2]))
+            : (0.75 + 0.25 * dir[1] + 0.05 * (Math.abs(dir[2]) - 3 * Math.abs(dir[0])))
+        )
+    const baseLight = sideShading * faceLight / 15
     for (const pos of corners) {
       let vertex = [
         (pos[0] ? maxx : minx),
@@ -429,8 +438,6 @@ function renderElement(world: World, cursor: Vec3, element: BlockElement, doAO:
       }
 
       let light = 1
-      const { smoothLighting } = world.config
-      // const smoothLighting = true
       if (doAO) {
         const dx = pos[0] * 2 - 1
         const dy = pos[1] * 2 - 1
@@ -442,7 +449,7 @@ function renderElement(world: World, cursor: Vec3, element: BlockElement, doAO:
         const side2 = world.getBlock(cursor.offset(...side2Dir))
         const corner = world.getBlock(cursor.offset(...cornerDir))
 
-        let cornerLightResult = baseLight * 15
+        let cornerLightResult = faceLight
 
         if (smoothLighting) {
           const dirVec = new Vec3(...dir)
@@ -459,7 +466,7 @@ function renderElement(world: World, cursor: Vec3, element: BlockElement, doAO:
           const cornerLightDir = getVec(new Vec3(...cornerDir))
           const cornerLight = world.getLight(cursor.plus(cornerLightDir))
           // interpolate
-          const lights = [side1Light, side2Light, cornerLight, baseLight * 15]
+          const lights = [side1Light, side2Light, cornerLight, faceLight]
           cornerLightResult = lights.reduce((acc, cur) => acc + cur, 0) / lights.length
         }
 
@@ -470,8 +477,10 @@ function renderElement(world: World, cursor: Vec3, element: BlockElement, doAO:
         // TODO: correctly interpolate ao light based on pos (evaluate once for each corner of the block)
 
         const ao = (side1Block && side2Block) ? 0 : (3 - (side1Block + side2Block + cornerBlock))
+        const ao_bias = (shadingTheme === 'high-contrast') ? 0.25 : 0.4
+        const ao_scale = (shadingTheme === 'high-contrast') ? 0.25 : 0.2
         // todo light should go upper on lower blocks
-        light = (ao + 1) / 4 * (cornerLightResult / 15)
+        light = sideShading * (ao * ao_scale + ao_bias) * (cornerLightResult / 15)
         aos.push(ao)
 
         // Log AO and light for this corner (corner index is aos.length - 1)

package/src/mesher/shared.ts

@@ -11,7 +11,9 @@ export const defaultMesherConfig = {
   worldMinY: 0,
   enableLighting: true,
   skyLight: 15,
-  smoothLighting: false,
+  smoothLighting: true,
+  shadingTheme: 'high-contrast' as 'vanilla' | 'high-contrast',
+  cardinalLight: 'default' as string,
   outputFormat: 'threeJs' as 'threeJs' | 'webgpu',
   // textureSize: 1024, // for testing
   debugModelVariant: undefined as undefined | number[],

package/src/playerState/playerState.ts

@@ -39,6 +39,8 @@ export const getInitialPlayerState = () => proxy({
   itemUsageTicks: 0,
   username: '',
   onlineMode: false,
+  /** Dimension ambient lighting preset (e.g. nether) — from login/respawn dimension data when available */
+  cardinalLight: 'default' as string,
   lightingDisabled: false,
   shouldHideHand: false,
   heldItemMain: undefined as HandItemBlock | undefined,

package/src/three/chunkMeshManager.ts

@@ -64,7 +64,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,

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 */