minecraft-renderer 0.1.90 → 0.1.91

package/package.json

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

package/src/graphicsBackend/types.ts

@@ -18,7 +18,14 @@ import { WorldRendererConfig } from './config'
 export type MaybePromise<T> = Promise<T> | T
 
 export interface SoundSystem {
-  playSound: (position: { x: number; y: number; z: number }, path: string, volume?: number, pitch?: number, timeout?: number) => void
+  playSound: (
+    position: { x: number; y: number; z: number },
+    path: string,
+    volume?: number,
+    pitch?: number,
+    timeout?: number,
+    attenuationDistance?: number
+  ) => void
   destroy: () => void
 }
 

package/src/three/positionalAudioAttenuation.ts

@@ -0,0 +1,35 @@
+//@ts-nocheck
+export const DEFAULT_ATTENUATION_DISTANCE = 16
+
+export function computeEffectiveVolume(soundEntryVolume: number, packetVolume: number): number {
+  return soundEntryVolume * Math.max(packetVolume, 0)
+}
+
+export function computeIndividualGain(effectiveVolume: number): number {
+  return Math.min(Math.max(effectiveVolume, 0), 1)
+}
+
+export function computePositionalAudioParams(effectiveVolume: number, attenuationDistance: number): { individualGain: number; maxDistance: number } {
+  return {
+    individualGain: computeIndividualGain(effectiveVolume),
+    maxDistance: Math.max(effectiveVolume, 1) * attenuationDistance
+  }
+}
+
+export function applyVanillaLinearPanner(panner: PannerNode, maxDistance: number): void {
+  panner.distanceModel = 'linear'
+  panner.refDistance = 0
+  panner.rolloffFactor = 1
+  panner.maxDistance = maxDistance
+}
+
+export function setPannerPositionImmediate(panner: PannerNode, audioContext: AudioContext, x: number, y: number, z: number): void {
+  const t = audioContext.currentTime
+  if (panner.positionX) {
+    panner.positionX.setValueAtTime(x, t)
+    panner.positionY.setValueAtTime(y, t)
+    panner.positionZ.setValueAtTime(z, t)
+  } else {
+    panner.setPosition(x, y, z)
+  }
+}

package/src/three/tests/positionalAudioAttenuation.test.ts

@@ -0,0 +1,51 @@
+//@ts-nocheck
+import { describe, expect, it } from 'vitest'
+import { computeEffectiveVolume, computeIndividualGain, computePositionalAudioParams, DEFAULT_ATTENUATION_DISTANCE } from '../positionalAudioAttenuation'
+
+describe('computeEffectiveVolume', () => {
+  it('multiplies entry volume by non-negative packet volume', () => {
+    expect(computeEffectiveVolume(1, 1)).toBe(1)
+    expect(computeEffectiveVolume(12, 2)).toBe(24)
+    expect(computeEffectiveVolume(1, 0.5)).toBe(0.5)
+  })
+
+  it('does not clamp packet volume above 1', () => {
+    expect(computeEffectiveVolume(1, 2)).toBe(2)
+    expect(computeEffectiveVolume(12, 2)).toBe(24)
+  })
+
+  it('treats negative packet volume as zero', () => {
+    expect(computeEffectiveVolume(1, -1)).toBe(0)
+  })
+})
+
+describe('computePositionalAudioParams', () => {
+  it('uses default attenuation distance semantics', () => {
+    expect(computePositionalAudioParams(1, DEFAULT_ATTENUATION_DISTANCE)).toEqual({
+      individualGain: 1,
+      maxDistance: 16
+    })
+  })
+
+  it('clamps individual gain to [0, 1] while extending range for volume > 1', () => {
+    expect(computePositionalAudioParams(24, 16)).toEqual({
+      individualGain: 1,
+      maxDistance: 384
+    })
+  })
+
+  it('keeps individual gain independent of master volume', () => {
+    expect(computeIndividualGain(1)).toBe(1)
+    expect(computeIndividualGain(2)).toBe(1)
+    expect(computeIndividualGain(0.5)).toBe(0.5)
+  })
+
+  it('matches vanilla linear falloff checkpoints at distance 0/8/16', () => {
+    const { individualGain, maxDistance } = computePositionalAudioParams(1, 16)
+    const linearMultiplier = (distance: number) => 1 - distance / maxDistance
+    expect(individualGain * linearMultiplier(0)).toBe(1)
+    expect(individualGain * linearMultiplier(8)).toBe(0.5)
+    expect(individualGain * linearMultiplier(16)).toBe(0)
+    expect(individualGain * linearMultiplier(24)).toBeLessThanOrEqual(0)
+  })
+})

package/src/three/tests/threeJsSound.test.ts

@@ -0,0 +1,110 @@
+//@ts-nocheck
+import { describe, expect, it, vi, beforeEach } from 'vitest'
+
+const mockSetVolume = vi.fn()
+const mockPlay = vi.fn()
+const loadAsyncDeferreds: Array<{ resolve: (buffer: unknown) => void }> = []
+
+vi.mock('three', () => {
+  class MockPositionalAudio {
+    panner = {
+      distanceModel: '',
+      refDistance: 0,
+      rolloffFactor: 0,
+      maxDistance: 0,
+      positionX: { setValueAtTime: vi.fn() },
+      positionY: { setValueAtTime: vi.fn() },
+      positionZ: { setValueAtTime: vi.fn() }
+    }
+
+    position = { set: vi.fn() }
+    matrixWorld = { decompose: vi.fn() }
+    setBuffer = vi.fn()
+    setVolume = mockSetVolume
+    setPlaybackRate = vi.fn()
+    play = mockPlay
+    updateMatrixWorld = vi.fn()
+    onEnded: (() => void) | undefined
+    source = null
+    disconnect = vi.fn()
+  }
+
+  class MockAudioListener {
+    context = { currentTime: 0 }
+    removeFromParent = vi.fn()
+  }
+
+  class MockAudioLoader {
+    manager = { itemEnd: vi.fn() }
+    loadAsync() {
+      return new Promise(resolve => {
+        loadAsyncDeferreds.push({ resolve })
+      })
+    }
+  }
+
+  class MockVector3 {
+    x = 0
+    y = 0
+    z = 0
+    set = vi.fn()
+  }
+
+  return {
+    PositionalAudio: MockPositionalAudio,
+    AudioListener: MockAudioListener,
+    AudioLoader: MockAudioLoader,
+    Vector3: MockVector3,
+    Quaternion: class {}
+  }
+})
+
+import { ThreeJsSound } from '../threeJsSound'
+
+function makeWorldRenderer() {
+  return {
+    onWorldSwitched: [] as Array<() => void>,
+    onReactiveConfigUpdated: vi.fn(),
+    camera: { add: vi.fn() },
+    cameraWorldPos: { x: 0, y: 64, z: 0 },
+    sceneOrigin: {
+      addAndTrack: vi.fn(),
+      removeAndUntrack: vi.fn()
+    }
+  }
+}
+
+describe('ThreeJsSound', () => {
+  beforeEach(() => {
+    mockSetVolume.mockClear()
+    mockPlay.mockClear()
+    loadAsyncDeferreds.length = 0
+  })
+
+  it('applies master volume 0 then unmute without NaN', async () => {
+    const soundSystem = new ThreeJsSound(makeWorldRenderer() as any)
+    soundSystem.baseVolume = 0
+    soundSystem.playSound({ x: 1, y: 2, z: 3 }, '/test.mp3', 1)
+
+    loadAsyncDeferreds[0].resolve({})
+    await Promise.resolve()
+
+    expect(mockSetVolume).toHaveBeenLastCalledWith(0)
+
+    soundSystem.changeVolume(1)
+    expect(mockSetVolume).toHaveBeenLastCalledWith(1)
+    expect(Number.isNaN(mockSetVolume.mock.calls.at(-1)?.[0])).toBe(false)
+  })
+
+  it('uses current master volume after async load completes', async () => {
+    const soundSystem = new ThreeJsSound(makeWorldRenderer() as any)
+    soundSystem.baseVolume = 1
+    soundSystem.playSound({ x: 0, y: 0, z: 0 }, '/test.mp3', 0.8)
+
+    soundSystem.changeVolume(0.25)
+    loadAsyncDeferreds[0].resolve({})
+    await Promise.resolve()
+
+    expect(mockSetVolume).toHaveBeenLastCalledWith(0.2)
+  })
+})

package/src/three/threeJsSound.ts

@@ -2,11 +2,17 @@
 import * as THREE from 'three'
 import { WorldRendererThree } from './worldRendererThree'
 import { SoundSystem } from '../graphicsBackend/types'
+import { applyVanillaLinearPanner, computePositionalAudioParams, DEFAULT_ATTENUATION_DISTANCE, setPannerPositionImmediate } from './positionalAudioAttenuation'
+
+const _pannerPosition = /*@__PURE__*/ new THREE.Vector3()
+const _pannerQuaternion = /*@__PURE__*/ new THREE.Quaternion()
+const _pannerScale = /*@__PURE__*/ new THREE.Vector3()
 
 export class ThreeJsSound implements SoundSystem {
   audioListener: THREE.AudioListener | undefined
   private readonly activeSounds = new Set<THREE.PositionalAudio>()
   private readonly audioContext: AudioContext | undefined
+  /** Normalized individual gain (clamped to [0, 1], excluding master volume). */
   private readonly soundVolumes = new Map<THREE.PositionalAudio, number>()
   baseVolume = 1
 
@@ -26,28 +32,40 @@ export class ThreeJsSound implements SoundSystem {
     this.worldRenderer.camera.add(this.audioListener)
   }
 
-  playSound(position: { x: number; y: number; z: number }, path: string, volume = 1, pitch = 1, timeout = 500) {
+  playSound(
+    position: { x: number; y: number; z: number },
+    path: string,
+    volume = 1,
+    pitch = 1,
+    timeout = 500,
+    attenuationDistance = DEFAULT_ATTENUATION_DISTANCE
+  ) {
     this.initAudioListener()
 
     const sound = new THREE.PositionalAudio(this.audioListener!)
     this.activeSounds.add(sound)
-    this.soundVolumes.set(sound, volume)
+
+    const { individualGain, maxDistance } = computePositionalAudioParams(volume, attenuationDistance)
+    this.soundVolumes.set(sound, individualGain)
 
     const audioLoader = new THREE.AudioLoader()
     const start = Date.now()
     void audioLoader.loadAsync(path).then(buffer => {
       if (Date.now() - start > timeout) {
         console.warn('Ignored playing sound', path, 'due to timeout:', timeout, 'ms <', Date.now() - start, 'ms')
+        this.activeSounds.delete(sound)
+        this.soundVolumes.delete(sound)
         return
       }
-      // play
       sound.setBuffer(buffer)
-      sound.setRefDistance(20)
-      sound.setVolume(volume * this.baseVolume)
-      sound.setPlaybackRate(pitch) // set the pitch
-      // set sound position
+      applyVanillaLinearPanner(sound.panner, maxDistance)
+      sound.setVolume(individualGain * this.baseVolume)
+      sound.setPlaybackRate(pitch)
       this.worldRenderer.sceneOrigin.addAndTrack(sound)
       sound.position.set(position.x, position.y, position.z)
+      sound.updateMatrixWorld(true)
+      sound.matrixWorld.decompose(_pannerPosition, _pannerQuaternion, _pannerScale)
+      setPannerPositionImmediate(sound.panner, this.audioListener!.context, _pannerPosition.x, _pannerPosition.y, _pannerPosition.z)
       sound.onEnded = () => {
         this.worldRenderer.sceneOrigin.removeAndUntrack(sound)
         if (sound.source) {
@@ -76,14 +94,13 @@ export class ThreeJsSound implements SoundSystem {
 
   changeVolume(volume: number) {
     this.baseVolume = volume
-    for (const [sound, individualVolume] of this.soundVolumes) {
-      sound.setVolume(individualVolume * this.baseVolume)
+    for (const [sound, individualGain] of this.soundVolumes) {
+      sound.setVolume(individualGain * this.baseVolume)
     }
   }
 
   destroy() {
     this.stopAll()
-    // Remove and cleanup audio listener
     if (this.audioListener) {
       this.audioListener.removeFromParent()
       this.audioListener = undefined
@@ -91,6 +108,7 @@ export class ThreeJsSound implements SoundSystem {
   }
 
   playTestSound() {
-    this.playSound(this.worldRenderer.camera.position, '/sound.mp3')
+    const { x, y, z } = this.worldRenderer.cameraWorldPos
+    this.playSound({ x, y, z }, '/sound.mp3')
   }
 }