minecraft-renderer 0.1.40 → 0.1.42

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "minecraft-renderer",
-  "version": "0.1.40",
+  "version": "0.1.42",
   "description": "The most Modular Minecraft world renderer with Three.js WebGL backend",
   "type": "module",
   "main": "./dist/index.js",
@@ -9,7 +9,6 @@
   "files": [
     "dist",
     "src",
-    "wasm",
     "logo.webp"
   ],
   "browserslist": {
@@ -121,8 +120,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",
+    "test:wasm": "cd wasm-mesher && wasm-pack build --target nodejs --out-dir pkg --dev && node build.mjs && node tests/test-chunk.cjs && node tests/test-section-boundary.cjs",
+    "test:wasm:boundary": "cd wasm-mesher && wasm-pack build --target nodejs --out-dir pkg --dev && node build.mjs && node tests/test-section-boundary.cjs",
     "watch:mesher": "pnpm build:mesher -w",
     "build:threeworker": "node scripts/buildThreeWorker.mjs",
     "watch:threeworker": "pnpm build:threeworker -w",

package/src/bundler/bundlePrepare.ts

@@ -0,0 +1,56 @@
+//@ts-nocheck
+import { cp, mkdir, stat } from 'node:fs/promises'
+import { createRequire } from 'node:module'
+import path from 'node:path'
+
+/** Worker-related basenames inside `minecraft-renderer`/`dist`; skipped if missing. */
+export const MESHER_DIST_FILES = [
+  'mesher.js',
+  'mesher.js.map',
+  'mesherWasm.js',
+  'mesherWasm.js.map',
+] as const
+
+export type BundlePrepareMesherOptions = {
+  cwd?: string
+  packageName?: string
+  outDir?: string
+  mesherDistDir?: string
+  files?: readonly string[]
+}
+
+function resolveSrcDist (opts: BundlePrepareMesherOptions | undefined, cwd: string): string {
+  if (opts?.mesherDistDir) return path.resolve(cwd, opts.mesherDistDir)
+  const pkg = opts?.packageName ?? 'minecraft-renderer'
+  const req = createRequire(path.join(cwd, 'package.json'))
+  return path.join(path.dirname(req.resolve(`${pkg}/package.json`)), 'dist')
+}
+
+export async function bundlePrepareMesherWorkers (opts?: BundlePrepareMesherOptions): Promise<string[]> {
+  const cwd = opts?.cwd ?? process.cwd()
+  const outDir = path.resolve(cwd, opts?.outDir ?? 'dist')
+  const srcDist = resolveSrcDist(opts, cwd)
+  const names = opts?.files ?? MESHER_DIST_FILES
+
+  await stat(srcDist).catch(() => {
+    throw new Error(`[bundlePrepareMesherWorkers] missing dist: ${srcDist}`)
+  })
+  await mkdir(outDir, { recursive: true })
+
+  const copied: string[] = []
+  for (const name of names) {
+    const from = path.join(srcDist, name)
+    let st
+    try {
+      st = await stat(from)
+    } catch {
+      continue
+    }
+    if (!st.isFile()) continue
+    const to = path.join(outDir, name)
+    await mkdir(path.dirname(to), { recursive: true })
+    await cp(from, to)
+    copied.push(path.relative(process.cwd(), to) || to)
+  }
+  return copied
+}

package/src/graphicsBackend/appViewer.ts

@@ -26,6 +26,7 @@ import { getInitialPlayerState } from './playerState'
 import { defaultWorldRendererConfig, defaultGraphicsBackendConfig, getDefaultRendererState, WorldRendererConfig } from './config'
 import { PlayerStateReactive } from '../playerState/playerState'
 import { ResourcesManager, ResourcesManagerTransferred } from '../resourcesManager'
+import { preloadMesherWorkerScript } from './preloadWorkers'
 
 export interface AppViewerOptions {
   config?: Partial<GraphicsBackendConfig>
@@ -101,6 +102,15 @@ export class AppViewer {
     this.resolveWorldReady = resolve
   }
 
+  /**
+   * Preload mesher worker script (HTTP validate + ephemeral Worker + `mc-web-ping` / `mc-web-pong`).
+   * Chooses `/mesherWasm.js` vs `/mesher.js` from `inWorldRenderingConfig.wasmMesher`.
+   */
+  preloadWorkers (): Promise<void> {
+    const script = this.inWorldRenderingConfig.wasmMesher ? 'mesherWasm.js' : 'mesher.js'
+    return preloadMesherWorkerScript({ script })
+  }
+
   /**
    * Load a graphics backend.
    */

package/src/graphicsBackend/config.ts

@@ -25,7 +25,7 @@ export const defaultWorldRendererConfig = {
   futuristicReveal: false,
 
   // Performance settings
-  wasmMesher: false,
+  wasmMesher: true,
   mesherWorkers: 1,
   addChunksBatchWaitTime: 200,
   _experimentalSmoothChunkLoading: true,

package/src/graphicsBackend/preloadWorkers.ts

@@ -0,0 +1,187 @@
+//@ts-nocheck
+/** Structured reason so logs / support can tell fetch vs worker vs ping failures apart. */
+export type MesherWorkerPreloadFailure =
+  | { phase: 'fetch'; code: 'timeout' | 'network' | 'bad-status'; status?: number; detail?: string }
+  | { phase: 'fetch'; code: 'invalid-body'; hint: 'empty' | 'html' }
+  | { phase: 'worker'; code: 'construct-failed'; message: string }
+  | { phase: 'worker'; code: 'script-error'; message: string }
+  | { phase: 'ping'; code: 'timeout' | 'messageerror' | 'post-failed'; detail?: string }
+
+export class MesherWorkerPreloadError extends Error {
+  readonly failure: MesherWorkerPreloadFailure
+
+  constructor(message: string, failure: MesherWorkerPreloadFailure) {
+    super(message)
+    this.name = 'MesherWorkerPreloadError'
+    this.failure = failure
+    console.error('[mesher preload]', failure, message)
+  }
+}
+
+function isMcWebPong(data: unknown): boolean {
+  if (!data || typeof data !== 'object') return false
+  if ((data as { type?: string }).type === 'mc-web-pong') return true
+  if (Array.isArray(data)) {
+    return data.some(d => d && typeof d === 'object' && (d as { type?: string }).type === 'mc-web-pong')
+  }
+  return false
+}
+
+const DEFAULT_FETCH_MS = 45_000
+const DEFAULT_PING_MS = 10_000
+
+/**
+ * Validates a mesher worker script over HTTP (not HTML/error page), instantiates a Worker, and waits for `mc-web-pong`.
+ * Use `mesher.js` for the legacy mesher bundle and `mesherWasm.js` for the WASM mesher bundle.
+ * Single-file builds skip (blob worker).
+ */
+export async function preloadMesherWorkerScript(opts?: {
+  fetchTimeoutMs?: number
+  pingTimeoutMs?: number
+  /** Worker script basename relative to `document.baseURI`. Defaults to `mesher.js`. */
+  script?: string
+}): Promise<void> {
+  if (process.env.SINGLE_FILE_BUILD) return
+
+  const fetchTimeoutMs = opts?.fetchTimeoutMs ?? DEFAULT_FETCH_MS
+  const pingTimeoutMs = opts?.pingTimeoutMs ?? DEFAULT_PING_MS
+  const scriptBasename = opts?.script ?? 'mesher.js'
+  const scriptUrl = new URL(scriptBasename, document.baseURI).href
+
+  let res: Response
+  try {
+    const ctrl = new AbortController()
+    const t = window.setTimeout(() => ctrl.abort(), fetchTimeoutMs)
+    try {
+      res = await fetch(scriptUrl, {
+        credentials: 'same-origin',
+        cache: 'force-cache',
+        signal: ctrl.signal,
+      })
+    } finally {
+      clearTimeout(t)
+    }
+  } catch (e: unknown) {
+    const err = e as { name?: string; message?: string }
+    if (err?.name === 'AbortError') {
+      throw new MesherWorkerPreloadError(
+        `Mesher script fetch timed out after ${fetchTimeoutMs}ms (${scriptUrl}).`,
+        { phase: 'fetch', code: 'timeout' }
+      )
+    }
+    throw new MesherWorkerPreloadError(
+      `Mesher script fetch failed (network): ${err?.message ?? e}. URL: ${scriptUrl}`,
+      { phase: 'fetch', code: 'network', detail: String(err?.message ?? e) }
+    )
+  }
+
+  if (!res.ok) {
+    throw new MesherWorkerPreloadError(
+      `Mesher script HTTP ${res.status} ${res.statusText}: ${scriptUrl}`,
+      { phase: 'fetch', code: 'bad-status', status: res.status }
+    )
+  }
+
+  const contentType = res.headers.get('content-type') ?? ''
+  const buf = await res.arrayBuffer()
+  if (buf.byteLength === 0) {
+    throw new MesherWorkerPreloadError(
+      `Mesher script response was empty: ${scriptUrl}`,
+      { phase: 'fetch', code: 'invalid-body', hint: 'empty' }
+    )
+  }
+
+  const headSize = Math.min(1024, buf.byteLength)
+  const head = new TextDecoder().decode(buf.slice(0, headSize)).trimStart()
+  if (head.startsWith('<!DOCTYPE') || head.startsWith('<html') || head.startsWith('<HTML')) {
+    throw new MesherWorkerPreloadError(
+      `Mesher URL returned HTML (wrong path, redirect, or SPA fallback), not JavaScript: ${scriptUrl}`,
+      { phase: 'fetch', code: 'invalid-body', hint: 'html' }
+    )
+  }
+
+  if (contentType.length > 0 && !/javascript|ecmascript/i.test(contentType)) {
+    console.warn('[mesher preload] Unexpected Content-Type for mesher worker script:', contentType, scriptUrl)
+  }
+
+  let worker: Worker | undefined
+  try {
+    worker = new Worker(scriptUrl)
+  } catch (e: unknown) {
+    const msg = e instanceof Error ? e.message : String(e)
+    throw new MesherWorkerPreloadError(
+      `Could not construct Worker for mesher (${scriptUrl}): ${msg}`,
+      { phase: 'worker', code: 'construct-failed', message: msg }
+    )
+  }
+
+  await new Promise<void>((resolve, reject) => {
+    let settled = false
+    const pingTimer = window.setTimeout(() => {
+      if (settled) return
+      settled = true
+      cleanup()
+      reject(new MesherWorkerPreloadError(
+        `Mesher worker did not reply with mc-web-pong within ${pingTimeoutMs}ms (wrong script, SW stale cache, worker blocked, or COEP/CORP). URL: ${scriptUrl}`,
+        { phase: 'ping', code: 'timeout' }
+      ))
+    }, pingTimeoutMs)
+
+    const cleanup = () => {
+      clearTimeout(pingTimer)
+      const w = worker
+      worker = undefined
+      if (!w) return
+      w.removeEventListener('message', onMessage)
+      w.removeEventListener('error', onError)
+      w.removeEventListener('messageerror', onMessageError)
+      w.terminate()
+    }
+
+    const done = () => {
+      if (settled) return
+      settled = true
+      cleanup()
+      resolve()
+    }
+
+    const fail = (err: Error) => {
+      if (settled) return
+      settled = true
+      cleanup()
+      reject(err)
+    }
+
+    function onMessage(ev: MessageEvent) {
+      if (isMcWebPong(ev.data)) done()
+    }
+
+    function onError(ev: ErrorEvent) {
+      fail(new MesherWorkerPreloadError(
+        `Mesher worker script failed to load or threw during startup: ${ev.message || 'unknown'} @ ${scriptUrl}`,
+        { phase: 'worker', code: 'script-error', message: ev.message }
+      ))
+    }
+
+    function onMessageError() {
+      fail(new MesherWorkerPreloadError(
+        `Mesher worker message channel error (structured clone / deserialization). URL: ${scriptUrl}`,
+        { phase: 'ping', code: 'messageerror' }
+      ))
+    }
+
+    worker!.addEventListener('message', onMessage)
+    worker!.addEventListener('error', onError)
+    worker!.addEventListener('messageerror', onMessageError)
+
+    try {
+      worker!.postMessage({ type: 'mc-web-ping', t: performance.now(), workerIndex: 0 })
+    } catch (e: unknown) {
+      const detail = e instanceof Error ? e.message : String(e)
+      fail(new MesherWorkerPreloadError(
+        `Failed to post mc-web-ping to mesher worker: ${detail}`,
+        { phase: 'ping', code: 'post-failed', detail }
+      ))
+    }
+  })
+}

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, SECTION_HEIGHT } from '../mesher/shared'
+import { HighestBlockInfo, CustomBlockModels, BlockStateModelInfo, getBlockAssetsCacheKey, MesherConfig, MesherMainEvent, SECTION_HEIGHT } from '../mesher-shared/shared'
 import { chunkPos } from './simpleUtils'
 import { addNewStat, removeAllStats, updatePanesVisibility, updateStatText } from './ui/newStats'
 import { getPlayerStateUtils } from '../graphicsBackend/playerState'

package/src/{mesher → mesher-legacy}/mesher.ts

@@ -1,9 +1,9 @@
 //@ts-nocheck
 import { Vec3 } from 'vec3'
-import { World } from './world'
-import { getSectionGeometry, setBlockStatesData as setMesherData } from './models'
-import { BlockStateModelInfo } from './shared'
-import { handleGetHeightmap, EMPTY_COLUMN_HEIGHTMAP_SENTINEL } from './computeHeightmap'
+import { World } from '../mesher-shared/world'
+import { getSectionGeometry, setBlockStatesData as setMesherData } from '../mesher-shared/models'
+import { BlockStateModelInfo } from '../mesher-shared/shared'
+import { handleGetHeightmap, EMPTY_COLUMN_HEIGHTMAP_SENTINEL } from '../mesher-shared/computeHeightmap'
 
 globalThis.structuredClone ??= (value) => JSON.parse(JSON.stringify(value))
 
@@ -169,6 +169,16 @@ const handleMessage = data => {
 
       break
     }
+    case 'mc-web-ping': {
+      const replyWorkerIndex = typeof data.workerIndex === 'number' ? data.workerIndex : workerIndex
+      global.postMessage({
+        type: 'mc-web-pong',
+        workerIndex: replyWorkerIndex,
+        t: data.t,
+        recvAt: typeof performance !== 'undefined' ? performance.now() : undefined,
+      })
+      break
+    }
     // No default
   }
 }

package/src/{mesher → mesher-legacy}/test/mesherTester.ts

@@ -3,8 +3,8 @@ import ChunkLoader, { PCChunk } from 'prismarine-chunk'
 import { Vec3 } from 'vec3'
 import MinecraftData from 'minecraft-data'
 import blocksAtlasesJson from 'mc-assets/dist/blocksAtlases.json'
-import { World as MesherWorld } from '../world'
-import { setBlockStatesData, getSectionGeometry } from '../models'
+import { World as MesherWorld } from '../../mesher-shared/world'
+import { setBlockStatesData, getSectionGeometry } from '../../mesher-shared/models'
 
 interface Options {
   chunkOverride?: PCChunk

package/src/{mesher → mesher-legacy}/test/run/test-js.ts

@@ -3,7 +3,7 @@ import ChunkLoader from 'prismarine-chunk'
 import { setup } from '../mesherTester'
 import { compareOrWriteSnapshot } from '../snapshotUtils'
 import { getChunk, VERSION } from './chunk'
-import { mesherGeometryToExportFormat } from '../../../wasm-lib/render-from-wasm'
+import { mesherGeometryToExportFormat } from '../../../wasm-mesher/bridge/render-from-wasm'
 import fs from 'fs'
 import { join } from 'path'
 

package/src/{mesher → mesher-legacy}/test/test-perf.ts

@@ -3,7 +3,7 @@ import PrismarineWorld from 'prismarine-world'
 import PrismarineChunk from 'prismarine-chunk'
 import { Vec3 } from 'vec3'
 import MinecraftData from 'minecraft-data'
-import { defaultMesherConfig } from '../shared'
+import { defaultMesherConfig } from '../../mesher-shared/shared'
 import { setup } from './mesherTester.js'
 import { generateSpiralMatrix } from '../../lib/spiral'
 

package/src/{mesher → mesher-legacy}/test/tests.test.ts

@@ -1,7 +1,7 @@
 //@ts-nocheck
 import { test, expect } from 'vitest'
 import { versions } from 'minecraft-data'
-import { INVISIBLE_BLOCKS } from '../worldConstants'
+import { INVISIBLE_BLOCKS } from '../../mesher-shared/worldConstants'
 import { setup } from './mesherTester'
 
 const lastVersion = versions.pc.map(x => x.minecraftVersion).filter(version => !version.includes('w'))[0]

package/src/{mesher → mesher-shared}/shared.ts

@@ -87,6 +87,8 @@ export interface MesherMainEvents {
   };
   blockStateModelInfo: { type: 'blockStateModelInfo'; info: Record<string, BlockStateModelInfo> };
   heightmap: { type: 'heightmap'; key: string; heightmap: Int16Array };
+  /** Reply to `{ type: 'mc-web-ping', t?, workerIndex? }` from the main thread (not batched in worker). */
+  mcWebPong: { type: 'mc-web-pong'; workerIndex: number; t?: number; recvAt?: number };
 }
 
 export type MesherMainEvent = MesherMainEvents[keyof MesherMainEvents]

package/src/playground/allEntitiesDebug.ts

@@ -34,7 +34,7 @@ export const displayEntitiesDebugList = (mcData: IndexedData) => {
   const results: Array<{
     entity: string;
     supported: boolean;
-    type?: 'obj' | 'bedrock' | 'special';
+    type?: 'obj' | 'bedrock' | 'gltf' | 'special';
     mappedFrom?: string;
     textureMap?: boolean;
     errors?: string[];

package/src/three/chunkMeshManager.ts

@@ -3,7 +3,7 @@ import PrismarineChatLoader from 'prismarine-chat'
 import * as THREE from 'three'
 import * as nbt from 'prismarine-nbt'
 import { Vec3 } from 'vec3'
-import { MesherGeometryOutput } from '../mesher/shared'
+import { MesherGeometryOutput } from '../mesher-shared/shared'
 import { chunkPos } from '../lib/simpleUtils'
 import { renderSign } from '../sign-renderer'
 import { getMesh } from './entity/EntityMesh'

package/src/three/entities.ts

@@ -28,6 +28,12 @@ import { WorldRendererThree } from './worldRendererThree'
 import { IndexedData } from 'minecraft-data'
 import { ItemSpecificContextProperties } from '../playerState/types'
 
+export type EntityModelOverridePart = {
+  modelPath: string | ArrayBuffer
+  modelType: Entity.EntityModelType
+  metadata?: any
+}
+
 // Type for entity metadata - simplified version
 type EntityMetadataVersions = {
   [key: string]: any
@@ -250,7 +256,7 @@ export class Entities {
   currentlyRendering = true
   cachedMapsImages = {} as Record<number, string>
   itemFrameMaps = {} as Record<number, Array<THREE.Mesh<THREE.PlaneGeometry, THREE.MeshLambertMaterial>>>
-  pendingModelOverrides = new Map<string, { modelPath: string, modelType: Entity.EntityModelType, metadata: any }>()
+  pendingModelOverrides = new Map<string, { parts: EntityModelOverridePart[] }>()
 
   private motionCache = new Map<string, { pos: THREE.Vector3, speed: number }>()
   private _wasThirdPerson = false
@@ -1380,8 +1386,8 @@ export class Entities {
   beforeEntityAdded(entity: import('prismarine-entity').Entity) {
     const override = this.pendingModelOverrides.get(entity.id.toString())
     if (override) {
-      const { modelPath, modelType, metadata } = override
-      entity['customModel'] = { modelPath, modelType, metadata }
+      const { parts } = override
+      entity['customModel'] = parts.length === 1 ? parts[0]! : { parts }
       this.pendingModelOverrides.delete(entity.id.toString())
     }
   }
@@ -1580,9 +1586,16 @@ export class Entities {
     return intersects[0]?.object
   }
 
-  updateEntityModel(entityId: string, modelPath: string, modelType: Entity.EntityModelType, metadata?: any) {
-    // Store override data for future entities
-    this.pendingModelOverrides.set(entityId, { modelPath, modelType, metadata })
+  updateEntityModel(
+    entityId: string,
+    modelPathOrParts: string | EntityModelOverridePart[],
+    modelType?: Entity.EntityModelType,
+    metadata?: any
+  ) {
+    const parts: EntityModelOverridePart[] = Array.isArray(modelPathOrParts)
+      ? modelPathOrParts
+      : [{ modelPath: modelPathOrParts, modelType: modelType!, metadata }]
+    this.pendingModelOverrides.set(entityId, { parts })
 
     // Force entity recreation if it exists
     const entity = this.entities[entityId]