minecraft-renderer 0.1.38 → 0.1.40

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "minecraft-renderer",
-  "version": "0.1.38",
+  "version": "0.1.40",
   "description": "The most Modular Minecraft world renderer with Three.js WebGL backend",
   "type": "module",
   "main": "./dist/index.js",
@@ -121,6 +121,8 @@
     "watch:lib": "node scripts/buildLib.mjs -w",
     "build:mesher": "node scripts/buildMesherWorker.mjs",
     "build:wasm": "cd wasm-mesher && ./build.sh web",
+    "test:wasm": "cd wasm-mesher && wasm-pack build --target nodejs --out-dir pkg --dev && node build.mjs && node test-chunk.cjs && node test-section-boundary.cjs",
+    "test:wasm:boundary": "cd wasm-mesher && wasm-pack build --target nodejs --out-dir pkg --dev && node build.mjs && node test-section-boundary.cjs",
     "watch:mesher": "pnpm build:mesher -w",
     "build:threeworker": "node scripts/buildThreeWorker.mjs",
     "watch:threeworker": "pnpm build:threeworker -w",

package/src/graphicsBackend/config.ts

@@ -20,6 +20,7 @@ export const defaultWorldRendererConfig = {
   // Debug settings
   showChunkBorders: false,
   enableDebugOverlay: false,
+  debugWasmPerf: false,
   debugModelVariant: undefined as undefined | number[],
   futuristicReveal: false,
 
@@ -30,6 +31,14 @@ export const defaultWorldRendererConfig = {
   _experimentalSmoothChunkLoading: true,
   _renderByChunks: false,
   autoLowerRenderDistance: false,
+  /** Disable WASM mesher worker-side conversion cache (memory hotfix for
+   * iOS Safari and other low-RAM environments). Trades performance for
+   * lower per-worker RAM. */
+  disableMesherConversionCache: false,
+  /** Whether to dedicate the last worker exclusively to block-update
+   * remeshing (change worker). When true, initial chunk meshing is
+   * distributed only across workers[0 .. n-2]. */
+  dedicatedChangeWorker: false,
 
   // Rendering engine settings
   /** Face shading: vanilla Minecraft vs higher-contrast client look */

package/src/lib/worldrendererCommon.ts

@@ -9,7 +9,7 @@ import { proxy, subscribe } from 'valtio'
 import type { ResourcesManagerTransferred } from '../resourcesManager/resourcesManager'
 import { dynamicMcDataFiles } from './buildSharedConfig.mjs'
 import { DisplayWorldOptions, GraphicsInitOptions, RendererReactiveState, SoundSystem } from '../graphicsBackend/types'
-import { HighestBlockInfo, CustomBlockModels, BlockStateModelInfo, getBlockAssetsCacheKey, MesherConfig, MesherMainEvent, IS_FULL_WORLD_SECTION, SECTION_HEIGHT } from '../mesher/shared'
+import { HighestBlockInfo, CustomBlockModels, BlockStateModelInfo, getBlockAssetsCacheKey, MesherConfig, MesherMainEvent, SECTION_HEIGHT } from '../mesher/shared'
 import { chunkPos } from './simpleUtils'
 import { addNewStat, removeAllStats, updatePanesVisibility, updateStatText } from './ui/newStats'
 import { getPlayerStateUtils } from '../graphicsBackend/playerState'
@@ -70,6 +70,10 @@ export abstract class WorldRendererCommon<WorkerSend = any, WorkerReceive = any>
   customTexturesDataUrl = undefined as string | undefined
   workers: any[] = []
   viewerChunkPosition?: Vec3
+  // Last viewer chunk-grid coords for which `onViewerChunkPositionChanged`
+  // fired — throttles the hook to chunk-grid changes.
+  private lastViewerChunkGridX?: number
+  private lastViewerChunkGridZ?: number
   lastCamUpdate = 0
   droppedFpsPercentage = 0
   initialChunkLoadWasStartedIn: number | undefined
@@ -91,6 +95,20 @@ export abstract class WorldRendererCommon<WorkerSend = any, WorkerReceive = any>
   workersProcessAverageTime = 0
   workersProcessAverageTimeCount = 0
   maxWorkersProcessTime = 0
+  workersPreAverageTime = 0
+  workersWasmAverageTime = 0
+  workersPostAverageTime = 0
+  workersPhaseSampleCount = 0
+  // Pre-stage substage averages (column-mode perf instrumentation).
+  workersPreTargetConvertAverageTime = 0
+  workersPreNeighborConvertAverageTime = 0
+  workersPreNeighborCountAverage = 0
+  workersPreTypedArrayBuildAverageTime = 0
+  workersPreOtherAverageTime = 0
+  // Cumulative cache hit/miss counters (column-mode conversion cache).
+  workersPreCacheHitsTotal = 0
+  workersPreCacheMissesTotal = 0
+  private static readonly PHASE_PERF_LOG_INTERVAL = 64
   geometryReceiveCount = {} as Record<number, number>
   allLoadedIn: undefined | number
   onWorldSwitched = [] as Array<() => void>
@@ -392,18 +410,10 @@ export abstract class WorldRendererCommon<WorkerSend = any, WorkerReceive = any>
       if (this.loadedChunks[chunkKey]) { // ensure chunk data was added, not a neighbor chunk update
         let loaded = true
         const sectionHeight = this.getSectionHeight()
-        if (IS_FULL_WORLD_SECTION) {
-          // Only one section per chunk when full world section
-          const sectionY = this.worldMinYRender
-          if (!this.finishedSections[`${chunkCoords[0]},${sectionY},${chunkCoords[2]}`]) {
+        for (let y = this.worldMinYRender; y < this.worldSizeParams.worldHeight; y += sectionHeight) {
+          if (!this.finishedSections[`${chunkCoords[0]},${y},${chunkCoords[2]}`]) {
             loaded = false
-          }
-        } else {
-          for (let y = this.worldMinYRender; y < this.worldSizeParams.worldHeight; y += sectionHeight) {
-            if (!this.finishedSections[`${chunkCoords[0]},${y},${chunkCoords[2]}`]) {
-              loaded = false
-              break
-            }
+            break
           }
         }
         if (loaded) {
@@ -442,6 +452,46 @@ export abstract class WorldRendererCommon<WorkerSend = any, WorkerReceive = any>
         this.workersProcessAverageTime = ((this.workersProcessAverageTime * (this.workersProcessAverageTimeCount - 1)) + data.processTime) / this.workersProcessAverageTimeCount
         this.maxWorkersProcessTime = Math.max(this.maxWorkersProcessTime, data.processTime)
       }
+      if (typeof data.pre === 'number' && typeof data.wasm === 'number' && typeof data.post === 'number'
+          && (data.pre > 0 || data.wasm > 0 || data.post > 0)) {
+        const n = ++this.workersPhaseSampleCount
+        this.workersPreAverageTime = ((this.workersPreAverageTime * (n - 1)) + data.pre) / n
+        this.workersWasmAverageTime = ((this.workersWasmAverageTime * (n - 1)) + data.wasm) / n
+        this.workersPostAverageTime = ((this.workersPostAverageTime * (n - 1)) + data.post) / n
+        // Pre-stage substages — additive schema; treat undefined as 0 so
+        // events from older mesher builds don't poison the running mean.
+        const ptc = typeof data.preTargetConvert === 'number' ? data.preTargetConvert : 0
+        const pnc = typeof data.preNeighborConvert === 'number' ? data.preNeighborConvert : 0
+        const pncn = typeof data.preNeighborCount === 'number' ? data.preNeighborCount : 0
+        const ptab = typeof data.preTypedArrayBuild === 'number' ? data.preTypedArrayBuild : 0
+        const po = typeof data.preOther === 'number' ? data.preOther : 0
+        const pch = typeof data.preCacheHits === 'number' ? data.preCacheHits : 0
+        const pcm = typeof data.preCacheMisses === 'number' ? data.preCacheMisses : 0
+        this.workersPreTargetConvertAverageTime = ((this.workersPreTargetConvertAverageTime * (n - 1)) + ptc) / n
+        this.workersPreNeighborConvertAverageTime = ((this.workersPreNeighborConvertAverageTime * (n - 1)) + pnc) / n
+        this.workersPreNeighborCountAverage = ((this.workersPreNeighborCountAverage * (n - 1)) + pncn) / n
+        this.workersPreTypedArrayBuildAverageTime = ((this.workersPreTypedArrayBuildAverageTime * (n - 1)) + ptab) / n
+        this.workersPreOtherAverageTime = ((this.workersPreOtherAverageTime * (n - 1)) + po) / n
+        this.workersPreCacheHitsTotal += pch
+        this.workersPreCacheMissesTotal += pcm
+        if (this.worldRendererConfig.debugWasmPerf && n % WorldRendererCommon.PHASE_PERF_LOG_INTERVAL === 0) {
+          const total = this.workersPreAverageTime + this.workersWasmAverageTime + this.workersPostAverageTime
+          const prePct = total > 0 ? (this.workersPreAverageTime / total) * 100 : 0
+          const wasmPct = total > 0 ? (this.workersWasmAverageTime / total) * 100 : 0
+          const postPct = total > 0 ? (this.workersPostAverageTime / total) * 100 : 0
+          const preAvg = this.workersPreAverageTime
+          const tgtPct = preAvg > 0 ? (this.workersPreTargetConvertAverageTime / preAvg) * 100 : 0
+          const nbrPct = preAvg > 0 ? (this.workersPreNeighborConvertAverageTime / preAvg) * 100 : 0
+          const tabPct = preAvg > 0 ? (this.workersPreTypedArrayBuildAverageTime / preAvg) * 100 : 0
+          const othPct = preAvg > 0 ? (this.workersPreOtherAverageTime / preAvg) * 100 : 0
+          const nbrCnt = this.workersPreNeighborCountAverage
+          const nbrPerAvg = nbrCnt > 0 ? this.workersPreNeighborConvertAverageTime / nbrCnt : 0
+          const cacheTotal = this.workersPreCacheHitsTotal + this.workersPreCacheMissesTotal
+          const cacheHitPct = cacheTotal > 0 ? (this.workersPreCacheHitsTotal / cacheTotal) * 100 : 0
+          // eslint-disable-next-line no-console
+          console.log(`[wasm-mesher perf] n=${n} pre=${this.workersPreAverageTime.toFixed(2)}ms (${prePct.toFixed(1)}%) wasm=${this.workersWasmAverageTime.toFixed(2)}ms (${wasmPct.toFixed(1)}%) post=${this.workersPostAverageTime.toFixed(2)}ms (${postPct.toFixed(1)}%) | pre.targetConvert=${this.workersPreTargetConvertAverageTime.toFixed(2)}ms (${tgtPct.toFixed(1)}%) pre.neighborConvert=${this.workersPreNeighborConvertAverageTime.toFixed(2)}ms (${nbrPct.toFixed(1)}%) [n̄=${nbrCnt.toFixed(2)}, per-nbr=${nbrPerAvg.toFixed(2)}ms] pre.typedArrayBuild=${this.workersPreTypedArrayBuildAverageTime.toFixed(2)}ms (${tabPct.toFixed(1)}%) pre.other=${this.workersPreOtherAverageTime.toFixed(2)}ms (${othPct.toFixed(1)}%) | pre.cache hits=${this.workersPreCacheHitsTotal} misses=${this.workersPreCacheMissesTotal} (${cacheHitPct.toFixed(1)}% hit)`)
+        }
+      }
     }
 
     if (data.type === 'blockStateModelInfo') {
@@ -503,6 +553,21 @@ export abstract class WorldRendererCommon<WorkerSend = any, WorkerReceive = any>
       if (!value) continue
       this.updatePosDataChunk?.(key)
     }
+    const gridX = Math.floor(pos.x / 16)
+    const gridZ = Math.floor(pos.z / 16)
+    if (gridX !== this.lastViewerChunkGridX || gridZ !== this.lastViewerChunkGridZ) {
+      this.lastViewerChunkGridX = gridX
+      this.lastViewerChunkGridZ = gridZ
+      this.onViewerChunkPositionChanged()
+    }
+  }
+
+  /**
+   * Fired only when the viewer crosses a chunk-grid boundary.
+   * Three subclass overrides this to refresh the near-first reveal gate.
+   */
+  protected onViewerChunkPositionChanged(): void {
+    // overridden by WorldRendererThree
   }
 
   sendWorkers(message: WorkerSend) {
@@ -562,6 +627,7 @@ export abstract class WorldRendererCommon<WorkerSend = any, WorkerReceive = any>
       disableBlockEntityTextures: !this.worldRendererConfig.extraBlockRenderers,
       worldMinY: this.worldMinYRender,
       worldMaxY: this.worldMinYRender + this.worldSizeParams.worldHeight,
+      disableConversionCache: this.worldRendererConfig.disableMesherConversionCache,
     }
   }
 
@@ -594,9 +660,6 @@ export abstract class WorldRendererCommon<WorkerSend = any, WorkerReceive = any>
   }
 
   getSectionHeight() {
-    if (IS_FULL_WORLD_SECTION) {
-      return this.worldSizeParams.worldHeight
-    }
     return SECTION_HEIGHT
   }
 
@@ -636,19 +699,25 @@ export abstract class WorldRendererCommon<WorkerSend = any, WorkerReceive = any>
         customBlockModels: customBlockModels || undefined
       })
     }
-    this.workers[0].postMessage({
-      type: 'getHeightmap',
-      x,
-      z,
-    })
+    // WASM mesher pushes heightmaps from `processColumnTick` after each
+    // column tick — the main thread no longer requests them on chunk load
+    // (would double-compute and starve the WASM hot loop). The JS mesher
+    // still needs the explicit request because it has no per-tick column
+    // pass.
+    if (!this.worldRendererConfig.wasmMesher) {
+      this.workers[0].postMessage({
+        type: 'getHeightmap',
+        x,
+        z,
+      })
+    }
     this.logWorkerWork(() => `-> chunk ${JSON.stringify({ x, z, chunkLength: chunk.length, customBlockModelsLength: customBlockModels ? Object.keys(customBlockModels).length : 0 })}`)
     this.mesherLogReader?.chunkReceived(x, z, chunk.length)
     const sectionHeight = this.getSectionHeight()
     const CHUNK_SIZE = 16
 
-    if (IS_FULL_WORLD_SECTION) {
-      // Only one section per chunk when full world section
-      const loc = new Vec3(x, this.worldMinYRender, z)
+    for (let y = this.worldMinYRender; y < this.worldSizeParams.worldHeight; y += sectionHeight) {
+      const loc = new Vec3(x, y, z)
       this.setSectionDirty(loc)
       if (this.neighborChunkUpdates && (!isLightUpdate || this.worldRendererConfig.smoothLighting)) {
         this.setSectionDirty(loc.offset(-CHUNK_SIZE, 0, 0))
@@ -656,17 +725,6 @@ export abstract class WorldRendererCommon<WorkerSend = any, WorkerReceive = any>
         this.setSectionDirty(loc.offset(0, 0, -CHUNK_SIZE))
         this.setSectionDirty(loc.offset(0, 0, CHUNK_SIZE))
       }
-    } else {
-      for (let y = this.worldMinYRender; y < this.worldSizeParams.worldHeight; y += sectionHeight) {
-        const loc = new Vec3(x, y, z)
-        this.setSectionDirty(loc)
-        if (this.neighborChunkUpdates && (!isLightUpdate || this.worldRendererConfig.smoothLighting)) {
-          this.setSectionDirty(loc.offset(-CHUNK_SIZE, 0, 0))
-          this.setSectionDirty(loc.offset(CHUNK_SIZE, 0, 0))
-          this.setSectionDirty(loc.offset(0, 0, -CHUNK_SIZE))
-          this.setSectionDirty(loc.offset(0, 0, CHUNK_SIZE))
-        }
-      }
     }
   }
 
@@ -674,6 +732,9 @@ export abstract class WorldRendererCommon<WorkerSend = any, WorkerReceive = any>
     this.loadedChunks[`${x},${z}`] = true
     this.finishedChunks[`${x},${z}`] = true
     this.logWorkerWork(`-> markAsLoaded ${JSON.stringify({ x, z })}`)
+    // Mirror the main meshing path so the near-first reveal gate can
+    // re-evaluate any farther chunks blocked by this column.
+    this.renderUpdateEmitter.emit('chunkFinished', `${x},${z}`)
     this.checkAllFinished()
   }
 
@@ -706,15 +767,9 @@ export abstract class WorldRendererCommon<WorkerSend = any, WorkerReceive = any>
       this.initialChunkLoadWasStartedIn = undefined
     }
     const sectionHeight = this.getSectionHeight()
-    if (IS_FULL_WORLD_SECTION) {
-      const sectionY = this.worldMinYRender
-      this.setSectionDirty(new Vec3(x, sectionY, z), false)
-      delete this.finishedSections[`${x},${sectionY},${z}`]
-    } else {
-      for (let y = this.worldSizeParams.minY; y < this.worldSizeParams.worldHeight; y += sectionHeight) {
-        this.setSectionDirty(new Vec3(x, y, z), false)
-        delete this.finishedSections[`${x},${y},${z}`]
-      }
+    for (let y = this.worldSizeParams.minY; y < this.worldSizeParams.worldHeight; y += sectionHeight) {
+      this.setSectionDirty(new Vec3(x, y, z), false)
+      delete this.finishedSections[`${x},${y},${z}`]
     }
     this.highestBlocksByChunks.delete(`${x},${z}`)
     this.reactiveState.world.heightmaps.delete(`${Math.floor(x / 16)},${Math.floor(z / 16)}`)
@@ -885,12 +940,17 @@ export abstract class WorldRendererCommon<WorkerSend = any, WorkerReceive = any>
       const chunkCornerX = Math.floor(pos.x / CHUNK_SIZE) * CHUNK_SIZE
       const chunkCornerZ = Math.floor(pos.z / CHUNK_SIZE) * CHUNK_SIZE
       const chunkKey2 = `${chunkCornerX},${chunkCornerZ}`
-      const existing = this.heightmapDebounceTimers.get(chunkKey2)
-      if (existing) clearTimeout(existing)
-      this.heightmapDebounceTimers.set(chunkKey2, setTimeout(() => {
-        this.heightmapDebounceTimers.delete(chunkKey2)
-        this.workers[0]?.postMessage({ type: 'getHeightmap', x: chunkCornerX, z: chunkCornerZ })
-      }, 100))
+      // WASM mesher pushes heightmaps from `processColumnTick`, so the
+      // block-update path doesn't need an explicit re-request — the next
+      // column tick will repush the recomputed heightmap.
+      if (!this.worldRendererConfig.wasmMesher) {
+        const existing = this.heightmapDebounceTimers.get(chunkKey2)
+        if (existing) clearTimeout(existing)
+        this.heightmapDebounceTimers.set(chunkKey2, setTimeout(() => {
+          this.heightmapDebounceTimers.delete(chunkKey2)
+          this.workers[0]?.postMessage({ type: 'getHeightmap', x: chunkCornerX, z: chunkCornerZ })
+        }, 100))
+      }
     }
     this.logWorkerWork(`-> blockUpdate ${JSON.stringify({ pos, stateId, customBlockModels })}`)
     this.setSectionDirty(pos, true, true)
@@ -937,14 +997,43 @@ export abstract class WorldRendererCommon<WorkerSend = any, WorkerReceive = any>
   getWorkerNumber(pos: Vec3, updateAction = false) {
     const CHUNK_SIZE = 16
     const sectionHeight = this.getSectionHeight()
+    const dedicated = this.worldRendererConfig.dedicatedChangeWorker
+
+    if (dedicated && this.workers.length > 1) {
+      // WASM column meshing must keep all vertical sections of a chunk
+      // column on one worker — skip dedicated change worker to avoid
+      // concurrent column meshing across different workers.
+      if (this.worldRendererConfig.wasmMesher) {
+        return mod(Math.floor(pos.x / CHUNK_SIZE) + Math.floor(pos.z / CHUNK_SIZE), this.workers.length)
+      }
+      if (updateAction) {
+        const key = `${Math.floor(pos.x / CHUNK_SIZE) * CHUNK_SIZE},${Math.floor(pos.y / sectionHeight) * sectionHeight},${Math.floor(pos.z / CHUNK_SIZE) * CHUNK_SIZE}`
+        const busy = this.sectionsWaiting.get(key) && !this.finishedSections[key]
+        if (busy) {
+          // Section is already being meshed by a general worker — route
+          // the update to the same worker to avoid concurrent meshing.
+          const generalWorkers = this.workers.length - 1
+          return mod(Math.floor(pos.x / CHUNK_SIZE) + Math.floor(pos.y / sectionHeight) + Math.floor(pos.z / CHUNK_SIZE), generalWorkers)
+        }
+        return this.workers.length - 1
+      }
+      const generalWorkers = this.workers.length - 1
+      return mod(Math.floor(pos.x / CHUNK_SIZE) + Math.floor(pos.y / sectionHeight) + Math.floor(pos.z / CHUNK_SIZE), generalWorkers)
+    }
+
+    if (this.worldRendererConfig.wasmMesher) {
+      // WASM column meshing must keep all vertical sections of a chunk column
+      // on one worker. Hash by x/z only and bypass the change-worker shortcut
+      // so block edits cannot remesh the same column concurrently on worker 0.
+      return mod(Math.floor(pos.x / CHUNK_SIZE) + Math.floor(pos.z / CHUNK_SIZE), this.workers.length)
+    }
     if (updateAction) {
       const key = `${Math.floor(pos.x / CHUNK_SIZE) * CHUNK_SIZE},${Math.floor(pos.y / sectionHeight) * sectionHeight},${Math.floor(pos.z / CHUNK_SIZE) * CHUNK_SIZE}`
       const cantUseChangeWorker = this.sectionsWaiting.get(key) && !this.finishedSections[key]
       if (!cantUseChangeWorker) return 0
     }
 
-    const hash = mod(Math.floor(pos.x / CHUNK_SIZE) + Math.floor(pos.y / sectionHeight) + Math.floor(pos.z / CHUNK_SIZE), this.workers.length)
-    return hash + 0
+    return mod(Math.floor(pos.x / CHUNK_SIZE) + Math.floor(pos.y / sectionHeight) + Math.floor(pos.z / CHUNK_SIZE), this.workers.length)
   }
 
   async debugGetWorkerCustomBlockModel(pos: Vec3) {
@@ -1032,7 +1121,7 @@ export abstract class WorldRendererCommon<WorkerSend = any, WorkerReceive = any>
     // Dispatch sections to workers based on position
     // This guarantees uniformity accross workers and that a given section
     // is always dispatched to the same worker
-    const hash = this.getWorkerNumber(pos, useChangeWorker && this.mesherLogger.active)
+    const hash = this.getWorkerNumber(pos, useChangeWorker && (this.mesherLogger.active || this.worldRendererConfig.dedicatedChangeWorker))
     this.sectionsWaiting.set(key, (this.sectionsWaiting.get(key) ?? 0) + 1)
     if (this.forceCallFromMesherReplayer) {
       this.workers[hash].postMessage({
@@ -1064,8 +1153,9 @@ export abstract class WorldRendererCommon<WorkerSend = any, WorkerReceive = any>
       // group messages and send as one
       for (const workerIndex in this.toWorkerMessagesQueue) {
         const worker = this.workers[Number(workerIndex)]
-        worker.postMessage(this.toWorkerMessagesQueue[workerIndex])
-        for (const message of this.toWorkerMessagesQueue[workerIndex]) {
+        const messages = this.toWorkerMessagesQueue[workerIndex]
+        worker.postMessage(messages)
+        for (const message of messages) {
           this.logWorkerWork(`-> ${workerIndex} dispatchMessages ${message.type} ${JSON.stringify({ x: message.x, y: message.y, z: message.z, value: message.value })}`)
         }
       }

package/src/mesher/blockEntityMetadata.ts

@@ -0,0 +1,70 @@
+//@ts-nocheck
+export interface SignMeta { isWall: boolean; isHanging: boolean; rotation: number }
+export interface HeadMeta { isWall: boolean; rotation: number }
+export interface BannerMeta { isWall: boolean; blockName: string; rotation: number }
+
+export interface BlockEntityMetadataTarget {
+  signs: Record<string, SignMeta>
+  heads: Record<string, HeadMeta>
+  banners: Record<string, BannerMeta>
+}
+
+export interface BlockEntityMetadataOptions {
+  disableBlockEntityTextures?: boolean
+}
+
+type BlockLike = { name: string; getProperties(): any }
+
+export function collectBlockEntityMetadata(
+  block: BlockLike,
+  x: number, y: number, z: number,
+  target: BlockEntityMetadataTarget,
+  options: BlockEntityMetadataOptions
+): void {
+  if ((block.name.includes('_sign') || block.name === 'sign') && !options.disableBlockEntityTextures) {
+    const key = `${x},${y},${z}`
+    const props: any = block.getProperties()
+    const facingRotationMap = {
+      'north': 2,
+      'south': 0,
+      'west': 1,
+      'east': 3
+    }
+    const isWall = block.name.endsWith('wall_sign') || block.name.endsWith('wall_hanging_sign')
+    const isHanging = block.name.endsWith('hanging_sign')
+    target.signs[key] = {
+      isWall,
+      isHanging,
+      rotation: isWall ? facingRotationMap[props.facing] : +props.rotation
+    }
+  } else if (block.name === 'player_head' || block.name === 'player_wall_head') {
+    const key = `${x},${y},${z}`
+    const props: any = block.getProperties()
+    const facingRotationMap = {
+      'north': 0,
+      'south': 2,
+      'west': 3,
+      'east': 1
+    }
+    const isWall = block.name === 'player_wall_head'
+    target.heads[key] = {
+      isWall,
+      rotation: isWall ? facingRotationMap[props.facing] : +props.rotation
+    }
+  } else if (block.name.includes('_banner') && !options.disableBlockEntityTextures) {
+    const key = `${x},${y},${z}`
+    const props: any = block.getProperties()
+    const facingRotationMap = {
+      'north': 2,
+      'south': 0,
+      'west': 1,
+      'east': 3
+    }
+    const isWall = block.name.endsWith('_wall_banner')
+    target.banners[key] = {
+      isWall,
+      blockName: block.name, // Pass block name for base color extraction
+      rotation: isWall ? facingRotationMap[props.facing] : (props.rotation === undefined ? 0 : +props.rotation)
+    }
+  }
+}

package/src/mesher/computeHeightmap.ts

@@ -0,0 +1,66 @@
+//@ts-nocheck
+import { Vec3 } from 'vec3'
+import { World } from './world'
+import { INVISIBLE_BLOCKS } from './worldConstants'
+
+/**
+ * Sentinel value written to the heightmap for any column that contains no
+ * non-INVISIBLE block in `[worldMinY, worldMaxY]`. Matches the value that
+ * Rust's `wasm-mesher` writes for empty columns in its `Vec<i16>` heightmap,
+ * so JS and Rust heightmaps are element-wise comparable.
+ *
+ * Downstream consumers (e.g. `src/three/modules/rain.ts`) MUST treat this
+ * value as "no surface" rather than as a real Y coordinate.
+ */
+export const EMPTY_COLUMN_HEIGHTMAP_SENTINEL = -32768
+
+/**
+ * Compute the surface heightmap for one 16x16 chunk column.
+ *
+ * Returns a 256-entry Int16Array indexed as `z * 16 + x`, where each entry is
+ * the world-Y of the highest non-INVISIBLE block in that column, or
+ * `EMPTY_COLUMN_HEIGHTMAP_SENTINEL` (-32768) if no such block exists.
+ *
+ * Shared by the JS-mode mesher (`mesher.ts`) and WASM-mode mesher
+ * (`mesherWasm.ts`) `getHeightmap` handlers to guarantee element-wise parity.
+ */
+export function computeHeightmap(world: World, chunkX: number, chunkZ: number): Int16Array {
+  const heightmap = new Int16Array(256)
+
+  const blockPos = new Vec3(0, 0, 0)
+  for (let z = 0; z < 16; z++) {
+    for (let x = 0; x < 16; x++) {
+      blockPos.x = x + chunkX
+      blockPos.z = z + chunkZ
+      blockPos.y = world.config.worldMaxY
+      let block = world.getBlock(blockPos)
+      while (block && INVISIBLE_BLOCKS.has(block.name) && blockPos.y > world.config.worldMinY) {
+        blockPos.y -= 1
+        block = world.getBlock(blockPos)
+      }
+      const index = z * 16 + x
+      // Loop exits either when we found a visible (non-INVISIBLE) block, or
+      // when we hit worldMinY with the column still entirely invisible/empty.
+      // Only the former is a real surface; the latter is the empty-column
+      // case and must use the sentinel to match Rust's encoding.
+      heightmap[index] = block && !INVISIBLE_BLOCKS.has(block.name)
+        ? blockPos.y
+        : EMPTY_COLUMN_HEIGHTMAP_SENTINEL
+    }
+  }
+  return heightmap
+}
+
+/**
+ * Shared `getHeightmap` worker-handler logic.
+ *
+ * Both `mesher.ts` and `mesherWasm.ts` route their `case 'getHeightmap'` here so
+ * the post-message payload (key + heightmap) is computed in exactly one place.
+ * Test fixtures (see `wasm-mesher/test-section-boundary.ts`) invoke this helper
+ * directly to exercise the real handler path end-to-end.
+ */
+export function handleGetHeightmap(world: World, x: number, z: number): { key: string, heightmap: Int16Array } {
+  const heightmap = computeHeightmap(world, x, z)
+  const key = `${Math.floor(x / 16)},${Math.floor(z / 16)}`
+  return { key, heightmap }
+}

package/src/mesher/mesher.ts

@@ -3,7 +3,7 @@ import { Vec3 } from 'vec3'
 import { World } from './world'
 import { getSectionGeometry, setBlockStatesData as setMesherData } from './models'
 import { BlockStateModelInfo } from './shared'
-import { INVISIBLE_BLOCKS } from './worldConstants'
+import { handleGetHeightmap, EMPTY_COLUMN_HEIGHTMAP_SENTINEL } from './computeHeightmap'
 
 globalThis.structuredClone ??= (value) => JSON.parse(JSON.stringify(value))
 
@@ -109,6 +109,7 @@ const handleMessage = data => {
       break
     }
     case 'chunk': {
+      if (!world) break
       world.addColumn(data.x, data.z, data.chunk)
       if (data.customBlockModels) {
         const chunkKey = `${data.x},${data.z}`
@@ -117,6 +118,7 @@ const handleMessage = data => {
       break
     }
     case 'unloadChunk': {
+      if (!world) break
       world.removeColumn(data.x, data.z)
       world.customBlockModels.delete(`${data.x},${data.z}`)
       if (Object.keys(world.columns).length === 0) softCleanup()
@@ -146,6 +148,10 @@ const handleMessage = data => {
       break
     }
     case 'getCustomBlockModel': {
+      if (!world) {
+        global.postMessage({ type: 'customBlockModel', chunkKey: '', customBlockModel: undefined })
+        break
+      }
       const pos = new Vec3(data.pos.x, data.pos.y, data.pos.z)
       const chunkKey = `${Math.floor(pos.x / 16) * 16},${Math.floor(pos.z / 16) * 16}`
       const customBlockModel = world.customBlockModels.get(chunkKey)?.[`${pos.x},${pos.y},${pos.z}`]
@@ -153,26 +159,13 @@ const handleMessage = data => {
       break
     }
     case 'getHeightmap': {
-      const heightmap = new Int16Array(256)
-
-      const blockPos = new Vec3(0, 0, 0)
-      for (let z = 0; z < 16; z++) {
-        for (let x = 0; x < 16; x++) {
-          const blockX = x + data.x
-          const blockZ = z + data.z
-          blockPos.x = blockX
-          blockPos.z = blockZ
-          blockPos.y = world.config.worldMaxY
-          let block = world.getBlock(blockPos)
-          while (block && INVISIBLE_BLOCKS.has(block.name) && blockPos.y > world.config.worldMinY) {
-            blockPos.y -= 1
-            block = world.getBlock(blockPos)
-          }
-          const index = z * 16 + x
-          heightmap[index] = block ? blockPos.y : -32768
-        }
+      if (!world) {
+        const emptyHeightmap = new Int16Array(256).fill(EMPTY_COLUMN_HEIGHTMAP_SENTINEL)
+        postMessage({ type: 'heightmap', key: `${Math.floor(data.x / 16)},${Math.floor(data.z / 16)}`, heightmap: emptyHeightmap })
+        break
       }
-      postMessage({ type: 'heightmap', key: `${Math.floor(data.x / 16)},${Math.floor(data.z / 16)}`, heightmap })
+      const { key, heightmap } = handleGetHeightmap(world, data.x, data.z)
+      postMessage({ type: 'heightmap', key, heightmap })
 
       break
     }