minecraft-renderer 0.1.29 → 0.1.31

package/package.json

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

package/src/graphicsBackend/playerState.ts

@@ -25,6 +25,10 @@ export const getInitialPlayerState = (): PlayerStateReactive => proxy({
   sneaking: false,
   flying: false,
   sprinting: false,
+  walkDist: 0,
+  prevWalkDist: 0,
+  bob: 0,
+  prevBob: 0,
   itemUsageTicks: 0,
   username: '',
   onlineMode: false,

package/src/lib/cameraBobbing.ts

@@ -1,95 +1,39 @@
 //@ts-nocheck
-export class CameraBobbing {
-  private walkDistance = 0
-  private prevWalkDistance = 0
-  private bobAmount = 0
-  private prevBobAmount = 0
-  private readonly gameTimer = new GameTimer()
-
-  // eslint-disable-next-line max-params
-  constructor (
-    private readonly BOB_FREQUENCY: number = Math.PI, // How fast the bob cycles
-    private readonly BOB_BASE_AMPLITUDE: number = 0.5, // Base amplitude of the bob
-    private readonly VERTICAL_MULTIPLIER: number = 1, // Vertical movement multiplier
-    private readonly ROTATION_MULTIPLIER_Z: number = 3, // Roll rotation multiplier
-    private readonly ROTATION_MULTIPLIER_X: number = 5 // Pitch rotation multiplier
-  ) {}
-
-  // Call this when player is moving
-  public updateWalkDistance (distance: number): void {
-    this.prevWalkDistance = this.walkDistance
-    this.walkDistance = distance
-  }
-
-  // Call this when player is moving to update bob amount
-  public updateBobAmount (isMoving: boolean): void {
-    const targetBob = isMoving ? 1 : 0
-    this.prevBobAmount = this.bobAmount
-
-    // Update timing
-    const ticks = this.gameTimer.update()
-    const deltaTime = ticks / 20 // Convert ticks to seconds assuming 20 TPS
-
-    // Smooth transition for bob amount
-    const bobDelta = (targetBob - this.bobAmount) * Math.min(1, deltaTime * 10)
-    this.bobAmount += bobDelta
-  }
-
-  // Call this in your render/animation loop
-  public getBobbing (): { position: { x: number, y: number }, rotation: { x: number, z: number } } {
-    // Interpolate walk distance
-    const walkDist = this.prevWalkDistance +
-      (this.walkDistance - this.prevWalkDistance) * this.gameTimer.partialTick
-
-    // Interpolate bob amount
-    const bob = this.prevBobAmount +
-      (this.bobAmount - this.prevBobAmount) * this.gameTimer.partialTick
-
-    // Calculate total distance for bob cycle
-    const totalDist = -(walkDist * this.BOB_FREQUENCY)
-
-    // Calculate offsets
-    const xOffset = Math.sin(totalDist) * bob * this.BOB_BASE_AMPLITUDE
-    const yOffset = -Math.abs(Math.cos(totalDist) * bob) * this.VERTICAL_MULTIPLIER
-
-    // Calculate rotations (in radians)
-    const zRot = (Math.sin(totalDist) * bob * this.ROTATION_MULTIPLIER_Z) * (Math.PI / 180)
-    const xRot = (Math.abs(Math.cos(totalDist - 0.2) * bob) * this.ROTATION_MULTIPLIER_X) * (Math.PI / 180)
-
-    return {
-      position: { x: xOffset, y: yOffset },
-      rotation: { x: xRot, z: zRot }
-    }
-  }
+export interface CameraBobResult {
+  position: { x: number; y: number }
+  rotation: { x: number; z: number }
 }
 
-class GameTimer {
-  private readonly msPerTick: number
-  private lastMs: number
-  public partialTick = 0
-
-  constructor (tickRate = 20) {
-    this.msPerTick = 1000 / tickRate
-    this.lastMs = performance.now()
-  }
-
-  update (): number {
-    const currentMs = performance.now()
-    const deltaSinceLastTick = currentMs - this.lastMs
+export interface CameraBobInput {
+  walkDist: number
+  prevWalkDist: number
+  bob: number
+  prevBob: number
+  partialTick: number
+}
 
-    // Calculate how much of a tick has passed
-    const tickDelta = deltaSinceLastTick / this.msPerTick
-    this.lastMs = currentMs
+const DEG_TO_RAD = Math.PI / 180
 
-    // Add to accumulated partial ticks
-    this.partialTick += tickDelta
+export function computeCameraBob (input: CameraBobInput): CameraBobResult {
+  const { walkDist, prevWalkDist, bob, prevBob, partialTick } = input
 
-    // Get whole number of ticks that should occur
-    const wholeTicks = Math.floor(this.partialTick)
+  // Vanilla uses "backwards interpolation": -(walkDist + delta * partialTick)
+  // See ClientAvatarState.getBackwardsInterpolatedWalkDistance()
+  const walkDelta = walkDist - prevWalkDist
+  const interpolatedWalkDist = -(walkDist + walkDelta * partialTick)
+  const interpolatedBob = prevBob + (bob - prevBob) * partialTick
 
-    // Keep the remainder as the new partial tick
-    this.partialTick -= wholeTicks
+  const sinWalk = Math.sin(interpolatedWalkDist * Math.PI)
+  const cosWalk = Math.cos(interpolatedWalkDist * Math.PI)
 
-    return wholeTicks
+  return {
+    position: {
+      x: sinWalk * interpolatedBob * 0.5,
+      y: -Math.abs(cosWalk * interpolatedBob)
+    },
+    rotation: {
+      x: Math.abs(Math.cos(interpolatedWalkDist * Math.PI - 0.2) * interpolatedBob) * 5 * DEG_TO_RAD,
+      z: sinWalk * interpolatedBob * 3 * DEG_TO_RAD
+    }
   }
 }

package/src/playerState/playerState.ts

@@ -32,6 +32,10 @@ export const getInitialPlayerState = () => proxy({
   sneaking: false,
   flying: false,
   sprinting: false,
+  walkDist: 0,
+  prevWalkDist: 0,
+  bob: 0,
+  prevBob: 0,
   itemUsageTicks: 0,
   username: '',
   onlineMode: false,

package/src/three/cameraShake.ts

@@ -1,5 +1,6 @@
 //@ts-nocheck
 import * as THREE from 'three'
+import { computeCameraBob, type CameraBobInput } from '../lib/cameraBobbing'
 import { WorldRendererThree } from './worldRendererThree'
 
 export class CameraShake {
@@ -9,6 +10,11 @@ export class CameraShake {
   private rollAnimation?: { startTime: number, startRoll: number, targetRoll: number, duration: number, returnToZero?: boolean }
   private basePitch = 0
   private baseYaw = 0
+  private cameraBobInput: CameraBobInput | null = null
+
+  setCameraBobInput(input: CameraBobInput | null) {
+    this.cameraBobInput = input
+  }
 
   constructor(public worldRenderer: WorldRendererThree, public onRenderCallbacks: Array<(deltaTime: number) => void>) {
     onRenderCallbacks.push(() => {
@@ -88,8 +94,26 @@ export class CameraShake {
       const pitchQuat = new THREE.Quaternion().setFromAxisAngle(new THREE.Vector3(1, 0, 0), pitchOffset)
       const yawQuat = new THREE.Quaternion().setFromAxisAngle(new THREE.Vector3(0, 1, 0), yawOffset)
       const rollQuat = new THREE.Quaternion().setFromAxisAngle(new THREE.Vector3(0, 0, 1), THREE.MathUtils.degToRad(this.rollAngle))
-      // Combine rotations in the correct order: pitch -> yaw -> roll
-      const finalQuat = yawQuat.multiply(pitchQuat).multiply(rollQuat)
+
+      // Camera bobbing rotation
+      let bobRollQuat = new THREE.Quaternion()
+      let bobPitchQuat = new THREE.Quaternion()
+      const perspective = this.worldRenderer.playerStateReactive.perspective
+      if (this.cameraBobInput) {
+        const bob = computeCameraBob(this.cameraBobInput)
+        bobRollQuat = new THREE.Quaternion().setFromAxisAngle(new THREE.Vector3(0, 0, 1), bob.rotation.z)
+        bobPitchQuat = new THREE.Quaternion().setFromAxisAngle(new THREE.Vector3(1, 0, 0), bob.rotation.x)
+
+        // Apply position bobbing to the camera child (not cameraContainer) in first-person only
+        if (perspective === 'first_person') {
+          this.worldRenderer.camera.position.set(bob.position.x, bob.position.y, 0)
+        }
+      } else if (perspective === 'first_person') {
+        this.worldRenderer.camera.position.set(0, 0, 0)
+      }
+
+      // Combine: yaw * pitch * damageRoll * bobRoll(Z) * bobPitch(X) — vanilla applies Z then X
+      const finalQuat = yawQuat.multiply(pitchQuat).multiply(rollQuat).multiply(bobRollQuat).multiply(bobPitchQuat)
       camera.setRotationFromQuaternion(finalQuat)
     }
   }

package/src/three/modules/cameraBobbing.ts

@@ -0,0 +1,59 @@
+//@ts-nocheck
+import type { WorldRendererThree } from '../worldRendererThree'
+import type { RendererModuleController, RendererModuleManifest } from '../rendererModuleSystem'
+
+export class CameraBobbingModule implements RendererModuleController {
+  private enabled = false
+  private lastBobWalkDist = 0
+  private lastBobTickTime = 0
+
+  constructor(private readonly worldRenderer: WorldRendererThree) { }
+
+  enable(): void {
+    this.enabled = true
+  }
+
+  disable(): void {
+    this.enabled = false
+    this.worldRenderer.cameraShake.setCameraBobInput(null)
+    const { perspective } = this.worldRenderer.playerStateReactive
+    if (perspective === 'first_person') {
+      this.worldRenderer.camera.position.set(0, 0, 0)
+    }
+  }
+
+  render?: (deltaTime: number) => void = () => {
+    if (!this.enabled) return
+    const config = this.worldRenderer.displayOptions.inWorldRenderingConfig
+    const { perspective } = this.worldRenderer.playerStateReactive
+
+    if (config.viewBobbing && perspective === 'first_person') {
+      if (this.worldRenderer.playerStateReactive.walkDist !== this.lastBobWalkDist) {
+        this.lastBobTickTime = performance.now()
+        this.lastBobWalkDist = this.worldRenderer.playerStateReactive.walkDist
+      }
+      const partialTick = Math.min((performance.now() - this.lastBobTickTime) / 50, 1)
+
+      this.worldRenderer.cameraShake.setCameraBobInput({
+        walkDist: this.worldRenderer.playerStateReactive.walkDist,
+        prevWalkDist: this.worldRenderer.playerStateReactive.prevWalkDist,
+        bob: this.worldRenderer.playerStateReactive.bob,
+        prevBob: this.worldRenderer.playerStateReactive.prevBob,
+        partialTick
+      })
+    } else {
+      this.worldRenderer.cameraShake.setCameraBobInput(null)
+    }
+  }
+
+  dispose(): void {
+    this.disable()
+  }
+}
+
+export const cameraBobbingManifest: RendererModuleManifest = {
+  id: 'cameraBobbing',
+  controller: CameraBobbingModule,
+  enabledDefault: true,
+  cannotBeDisabled: true,
+}

package/src/three/modules/index.ts

@@ -1,4 +1,5 @@
 //@ts-nocheck
+import { cameraBobbingManifest } from './cameraBobbing'
 import { rainManifest } from './rain'
 import { sciFiWorldRevealManifest } from './sciFiWorldReveal'
 import { starfieldManifest } from './starfield'
@@ -7,4 +8,5 @@ export const BUILTIN_MODULES = {
   starfield: starfieldManifest,
   futuristicReveal: sciFiWorldRevealManifest,
   rain: rainManifest,
+  cameraBobbing: cameraBobbingManifest,
 }

package/src/three/worldBlockGeometry.ts

@@ -4,7 +4,6 @@ import { Vec3 } from 'vec3'
 import nbt from 'prismarine-nbt'
 import { MesherGeometryOutput, IS_FULL_WORLD_SECTION } from '../mesher/shared'
 import { getBannerTexture, createBannerMesh, releaseBannerTexture } from './bannerRenderer'
-import { disposeObject } from './threeJsUtils'
 import type { WorldRendererThree } from './worldRendererThree'
 
 export interface SectionObject extends THREE.Object3D {
@@ -17,6 +16,9 @@ export class WorldBlockGeometry {
   sectionObjects: Record<string, SectionObject> = {}
   waitingChunksToDisplay: { [chunkKey: string]: string[] } = {}
   estimatedMemoryUsage = 0
+  private pendingUpdates: Map<string, { geometry: MesherGeometryOutput; key: string; type: string }> = new Map()
+  private pendingBufferStartTime: number | null = null
+  private static readonly MAX_BUFFER_MS = 500
 
   constructor(
     private readonly worldRenderer: WorldRendererThree,
@@ -26,21 +28,84 @@ export class WorldBlockGeometry {
   ) { }
 
   handleWorkerGeometryMessage(data: { geometry: MesherGeometryOutput; key: string; type: string }): void {
-    let object: THREE.Object3D = this.sectionObjects[data.key]
-    if (object) {
-      // Track memory usage removal for existing section
-      this.removeSectionMemoryUsage(object)
-      // Cleanup banner textures before disposing
-      object.traverse((child) => {
-        if ((child as any).bannerTexture) {
-          releaseBannerTexture((child as any).bannerTexture)
+    const isUpdate = !!this.sectionObjects[data.key]
+
+    if (isUpdate) {
+      // Buffer updates for existing sections — keep old mesh visible
+      this.pendingUpdates.set(data.key, data)
+      if (this.pendingBufferStartTime === null) {
+        this.pendingBufferStartTime = performance.now()
+      }
+      return
+    }
+
+    // Initial load — apply immediately
+    this._applySectionGeometry(data)
+  }
+
+  applyPendingUpdates(): void {
+    if (this.pendingUpdates.size === 0) return
+
+    const now = performance.now()
+    const sinceFirst = now - (this.pendingBufferStartTime ?? now)
+
+    // Wait for neighboring sections still being meshed (unless max timeout reached)
+    if (sinceFirst < WorldBlockGeometry.MAX_BUFFER_MS) {
+      const sectionHeight = this.worldRenderer.getSectionHeight()
+      for (const key of this.pendingUpdates.keys()) {
+        const [sx, sy, sz] = key.split(',').map(Number)
+        const neighborKeys = [
+          `${sx - 16},${sy},${sz}`, `${sx + 16},${sy},${sz}`,
+          `${sx},${sy - sectionHeight},${sz}`, `${sx},${sy + sectionHeight},${sz}`,
+          `${sx},${sy},${sz - 16}`, `${sx},${sy},${sz + 16}`,
+        ]
+        for (const neighborKey of neighborKeys) {
+          // Wait if neighbor is being meshed, hasn't arrived yet, and has a loaded mesh
+          if (this.worldRenderer.sectionsWaiting.has(neighborKey) &&
+              !this.pendingUpdates.has(neighborKey) &&
+              this.sectionObjects[neighborKey]) {
+            return
+          }
         }
-      })
-      this.worldRenderer.sceneOrigin.removeAndUntrackAll(object)
-      disposeObject(object)
-      delete this.sectionObjects[data.key]
+      }
     }
 
+    // Flush all pending updates atomically
+    for (const [key, data] of this.pendingUpdates) {
+      this._removeSectionSafely(key)
+      this._applySectionGeometry(data)
+    }
+
+    this.pendingUpdates.clear()
+    this.pendingBufferStartTime = null
+  }
+
+  private disposeSectionObject(obj: THREE.Object3D): void {
+    if (obj instanceof THREE.Mesh) {
+      obj.geometry?.dispose?.()
+      // Don't dispose material - it's shared across all sections
+    }
+    if (obj.children) {
+      obj.children.forEach(child => this.disposeSectionObject(child))
+    }
+  }
+
+  private _removeSectionSafely(key: string): void {
+    const object = this.sectionObjects[key]
+    if (!object) return
+
+    this.removeSectionMemoryUsage(object)
+    object.traverse((child) => {
+      if ((child as any).bannerTexture) {
+        releaseBannerTexture((child as any).bannerTexture)
+      }
+    })
+    this.worldRenderer.sceneOrigin.removeAndUntrackAll(object)
+    this.disposeSectionObject(object)
+    delete this.sectionObjects[key]
+  }
+
+  private _applySectionGeometry(data: { geometry: MesherGeometryOutput; key: string; type: string }): void {
     const chunkCoords = data.key.split(',')
     if (
       !this.worldRenderer.loadedChunks[chunkCoords[0] + ',' + chunkCoords[2]] ||
@@ -69,7 +134,7 @@ export class WorldBlockGeometry {
     this.worldRenderer.sceneOrigin.track(mesh, { updateMatrix: true })
     mesh.position.set(data.geometry.sx, data.geometry.sy, data.geometry.sz)
     mesh.name = 'mesh'
-    object = new THREE.Group()
+    const object: THREE.Object3D = new THREE.Group()
     object.add(mesh)
     // mesh with static dimensions: 16x16xsectionHeight
     const sectionHeight = data.geometry.sectionEndY - data.geometry.sectionStartY
@@ -238,6 +303,8 @@ export class WorldBlockGeometry {
 
     // Reset memory tracking since all sections are cleared
     this.estimatedMemoryUsage = 0
+    this.pendingUpdates.clear()
+    this.pendingBufferStartTime = null
   }
 
   removeColumn(x: number, z: number) {
@@ -259,9 +326,10 @@ export class WorldBlockGeometry {
           }
         })
         this.worldRenderer.sceneOrigin.removeAndUntrackAll(mesh)
-        disposeObject(mesh)
+        this.disposeSectionObject(mesh)
       }
       delete this.sectionObjects[key]
+      this.pendingUpdates.delete(key)
     } else {
       for (let y = worldMinY; y < this.worldRenderer.worldSizeParams.worldHeight; y += sectionHeight) {
         this.worldRenderer.setSectionDirty(new Vec3(x, y, z), false)
@@ -277,9 +345,10 @@ export class WorldBlockGeometry {
             }
           })
           this.worldRenderer.sceneOrigin.removeAndUntrackAll(mesh)
-          disposeObject(mesh)
+          this.disposeSectionObject(mesh)
         }
         delete this.sectionObjects[key]
+        this.pendingUpdates.delete(key)
       }
     }
   }

package/src/three/worldRendererThree.ts

@@ -985,7 +985,8 @@ export class WorldRendererThree extends WorldRendererCommon {
           this.camera.rotation.set(0, 0, 0)
         }
       } else {
-        this.camera.position.set(0, 0, 0)
+        // Only reset z (clears third-person offset); x/y are managed by CameraShake for bobbing
+        this.camera.position.z = 0
         this.camera.rotation.set(0, 0, 0)
 
         // remove any debug raycasting
@@ -1065,6 +1066,8 @@ export class WorldRendererThree extends WorldRendererCommon {
 
     // eslint-disable-next-line @typescript-eslint/non-nullable-type-assertion-style
     const cam = this.cameraGroupVr instanceof THREE.Group ? this.cameraGroupVr.children.find(child => child instanceof THREE.PerspectiveCamera) as THREE.PerspectiveCamera : this.camera
+    // Flush buffered geometry updates atomically before rendering
+    this.worldBlockGeometry.applyPendingUpdates()
     this.renderer.render(this.scene, cam)
 
     if (