minecraft-renderer 0.1.89 → 0.1.91

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "minecraft-renderer",
-  "version": "0.1.89",
+  "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')
   }
 }

package/src/wasm-mesher/bridge/render-from-wasm.ts

@@ -642,7 +642,7 @@ export function renderWasmOutputToGeometry(
         const doAO = (model as { ao?: boolean }).ao ?? cachedModel.boundingBox !== 'empty'
 
         let forceCullMask = 0
-        if (world) {
+        if (world && cachedModel.isCube) {
           const shaderCubeFaceNameToIndex: Record<string, number> = {
             up: 0,
             down: 1,
@@ -787,7 +787,11 @@ export function renderWasmOutputToGeometry(
           const maxy = element.to[1]
           const maxz = element.to[2]
 
-          if (faceIdx !== undefined && (block.visible_faces & (1 << faceIdx)) === 0) {
+          // `visible_faces` is a cell-boundary occlusion mask, so it may only cull faces
+          // that vanilla considers cullable at all — i.e. faces that declare `cullface`.
+          // Inset faces without it (a stair riser) are always drawn. Removing this guard
+          // is what broke issue #81 in 7ce1ebb.
+          if (matchingEFace.cullface && faceIdx !== undefined && (block.visible_faces & (1 << faceIdx)) === 0) {
             continue
           }
 

package/src/wasm-mesher/tests/cullingRegression.test.ts

@@ -14,6 +14,7 @@ import { setBlockStatesData, getSectionGeometry } from '../../mesher-shared/mode
 import { resetFaceOcclusionCache } from '../../mesher-shared/faceOcclusion'
 import { convertChunkToWasm } from '../bridge/convertChunk'
 import { renderWasmOutputToGeometry } from '../bridge/render-from-wasm'
+import type { ExportedSection } from '../../mesher-shared/exportedGeometryTypes'
 
 const VERSION = '1.18.2'
 const SECTION_Y = 0
@@ -130,6 +131,81 @@ function assertMesherParity(world: World, expectedQuads: number) {
   expect(wasmShader).toBe(expectedQuads)
 }
 
+function renderWasmSection(world: World, shaderCubes = false): ExportedSection {
+  const column = world.getColumn(0, 0)!
+  const conversion = convertChunkToWasm(column, VERSION, 0, 0, SECTION_Y, SECTION_Y + SECTION_HEIGHT, SECTION_Y, SECTION_HEIGHT)
+  const wasmResult = wasmModule.generate_geometry(
+    0,
+    SECTION_Y,
+    0,
+    SECTION_HEIGHT,
+    SECTION_Y,
+    SECTION_Y + SECTION_HEIGHT,
+    SECTION_Y,
+    conversion.blockStates,
+    conversion.blockLight,
+    conversion.skyLight,
+    conversion.biomesArray,
+    conversion.invisibleBlocks,
+    conversion.transparentBlocks,
+    conversion.noAoBlocks,
+    conversion.cullIdenticalBlocks,
+    conversion.occludingBlocks,
+    true,
+    false,
+    15
+  )
+  return renderWasmOutputToGeometry(wasmResult, VERSION, '0,0,0', { x: 8, y: 8, z: 8 }, world, {
+    sectionHeight: SECTION_HEIGHT,
+    shaderCubes
+  })
+}
+
+/** Inset stair riser in cell (bx, by, bz): normal along expectedNx, all four verts on the cell mid-x-plane and within the cell AABB. */
+function hasInsetHorizontalRiser(section: ExportedSection, bx: number, by: number, bz: number, expectedNx: 1 | -1): boolean {
+  const pos = section.geometry.positions
+  const norm = section.geometry.normals
+  const idx = section.geometry.indices
+  const eps = 1e-3
+  const minX = (bx & 15) - 8
+  const maxX = minX + 1
+  const minY = (by & 15) - 8
+  const maxY = minY + 1
+  const minZ = (bz & 15) - 8
+  const maxZ = minZ + 1
+  const riserX = minX + 0.5
+
+  for (let i = 0; i < idx.length; i += 6) {
+    const vertIndices = [...new Set([idx[i], idx[i + 1], idx[i + 2], idx[i + 3], idx[i + 4], idx[i + 5]])]
+    if (vertIndices.length !== 4) continue
+
+    const nx = norm[vertIndices[0]! * 3]!
+    const ny = norm[vertIndices[0]! * 3 + 1]!
+    const nz = norm[vertIndices[0]! * 3 + 2]!
+    if (Math.abs(ny) > eps || Math.abs(nz) > eps) continue
+    if (Math.abs(nx - expectedNx) > eps) continue
+
+    const onRiserPlane = vertIndices.every(vi => Math.abs(pos[vi * 3]! - riserX) < eps)
+    if (!onRiserPlane) continue
+
+    const inCell = vertIndices.every(vi => {
+      const px = pos[vi * 3]!
+      const py = pos[vi * 3 + 1]!
+      const pz = pos[vi * 3 + 2]!
+      return px >= minX - eps && px <= maxX + eps && py >= minY - eps && py <= maxY + eps && pz >= minZ - eps && pz <= maxZ + eps
+    })
+    if (inCell) return true
+  }
+  return false
+}
+
+function stairWithStoneNeighbor(facing: 'east' | 'west' | 'south' | 'north', stone: { x: number; y: number; z: number }): BlockSpec[] {
+  return [
+    { x: 0, y: 0, z: 0, name: 'cut_copper_stairs', props: { facing, half: 'bottom', shape: 'straight', waterlogged: false } },
+    { x: stone.x, y: stone.y, z: stone.z, name: 'stone' }
+  ]
+}
+
 function farmlandFieldBlocks(): BlockSpec[] {
   const blocks: BlockSpec[] = []
   for (let z = 0; z < 16; z++) {
@@ -331,3 +407,59 @@ test('shader cubes: dirt side not culled beside bottom slab', () => {
   expect(wasmShader).toBe(legacy)
   expect(wasmShader).toBeGreaterThan(5)
 })
+
+test('culling regression: east-facing stair + stone to east — full silhouette, no inset riser drop (issue #81)', () => {
+  const world = buildWorld(stairWithStoneNeighbor('east', { x: 1, y: 0, z: 0 }))
+  assertMesherParity(world, 14)
+})
+
+test('culling regression: west-facing stair + stone to east — inset riser kept (issue #81)', () => {
+  const world = buildWorld(stairWithStoneNeighbor('west', { x: 1, y: 0, z: 0 }))
+  assertMesherParity(world, 16)
+  expect(hasInsetHorizontalRiser(renderWasmSection(world), 0, 0, 0, 1)).toBe(true)
+})
+
+test('culling regression: south-facing stair + stone to south — inset riser kept (issue #81)', () => {
+  const world = buildWorld(stairWithStoneNeighbor('south', { x: 0, y: 0, z: 1 }))
+  // Tall half faces south toward stone (east/west analog); stone's north face is culled.
+  assertMesherParity(world, 14)
+})
+
+test('culling regression: north-facing stair + stone to south — inset riser kept (issue #81)', () => {
+  const world = buildWorld([
+    { x: 0, y: 0, z: 0, name: 'cut_copper_stairs', props: { facing: 'north', half: 'bottom', shape: 'straight', waterlogged: false } },
+    { x: 0, y: 0, z: 1, name: 'stone' }
+  ])
+  assertMesherParity(world, 16)
+})
+
+test('culling regression: all horizontal facings beside occluding cube — parity table (issue #81)', () => {
+  const cases: Array<{ blocks: BlockSpec[]; quads: number }> = [
+    { blocks: stairWithStoneNeighbor('east', { x: 1, y: 0, z: 0 }), quads: 14 },
+    { blocks: stairWithStoneNeighbor('west', { x: 1, y: 0, z: 0 }), quads: 16 },
+    { blocks: stairWithStoneNeighbor('south', { x: 0, y: 0, z: 1 }), quads: 14 },
+    {
+      blocks: [
+        { x: 0, y: 0, z: 0, name: 'cut_copper_stairs', props: { facing: 'north', half: 'bottom', shape: 'straight', waterlogged: false } },
+        { x: 0, y: 0, z: 1, name: 'stone' }
+      ],
+      quads: 16
+    }
+  ]
+  for (const { blocks, quads } of cases) {
+    assertMesherParity(buildWorld(blocks), quads)
+  }
+})
+
+test('culling regression: sofa scene — acacia stairs risers beside stripped log (issue #81)', () => {
+  const world = buildWorld([
+    { x: 1, y: 0, z: 0, name: 'stripped_acacia_log' },
+    { x: 1, y: 1, z: 0, name: 'acacia_pressure_plate' },
+    { x: 0, y: 0, z: 0, name: 'acacia_stairs', props: { facing: 'west', half: 'bottom', shape: 'straight', waterlogged: false } },
+    { x: 2, y: 0, z: 0, name: 'acacia_stairs', props: { facing: 'east', half: 'bottom', shape: 'straight', waterlogged: false } }
+  ])
+  assertMesherParity(world, 31)
+  const section = renderWasmSection(world)
+  expect(hasInsetHorizontalRiser(section, 0, 0, 0, 1)).toBe(true)
+  expect(hasInsetHorizontalRiser(section, 2, 0, 0, -1)).toBe(true)
+})