minecraft-renderer 0.1.39 → 0.1.41

package/src/three/entity/EntityMesh.ts

@@ -57,21 +57,33 @@ interface JsonModel {
   bones: JsonBone[]
 }
 
+export type CustomModelMetadata = {
+  scale?: number
+  offset?: { x?: number, y?: number, z?: number }
+  texture?: string
+  textures?: Record<string, string>
+  animation?: string
+  animationLoop?: boolean
+}
+
+export type CustomModelPart = {
+  modelPath: string | ArrayBuffer
+  modelType: 'obj' | 'bedrock' | 'gltf'
+  metadata?: CustomModelMetadata
+}
+
+/** One part, or several (same idea as `models[]` on the custom-model-overlay). */
+export type EntityCustomModel = CustomModelPart | { parts: CustomModelPart[] }
+
 interface EntityOverrides {
   textures?: Record<string, string>
   rotation?: Record<string, { x?: number; y?: number; z?: number }>
-  customModel?: {
-    modelPath: string | ArrayBuffer
-    modelType: 'obj' | 'bedrock' | 'gltf'
-    metadata?: {
-      scale?: number
-      offset?: { x?: number, y?: number, z?: number }
-      texture?: string
-      textures?: Record<string, string>
-      animation?: string
-      animationLoop?: boolean
-    }
-  }
+  customModel?: EntityCustomModel
+}
+
+function normalizeCustomModelParts (custom: EntityCustomModel): CustomModelPart[] {
+  if ('parts' in custom && Array.isArray(custom.parts)) return custom.parts
+  return [custom as CustomModelPart]
 }
 
 const elemFaces: Record<string, ElemFace> = {
@@ -443,7 +455,7 @@ interface EntityGeometry {
 export type EntityModelType = 'obj' | 'bedrock' | 'gltf'
 
 export type EntityDebugFlags = {
-  type?: 'obj' | 'bedrock' | 'special'
+  type?: 'obj' | 'bedrock' | 'gltf' | 'special'
   tempMap?: string
   textureMap?: boolean
   errors?: string[]
@@ -453,9 +465,7 @@ export type EntityDebugFlags = {
 export class EntityMesh {
   mesh!: THREE.Object3D
   animations?: THREE.AnimationClip[]
-  private animationController?: ReturnType<typeof createAnimatedObject>
-  private initialAnimation?: string
-  private initialLoop?: boolean
+  private animationControllers: Array<ReturnType<typeof createAnimatedObject>> = []
 
   constructor(
     version: string,
@@ -471,145 +481,117 @@ export class EntityMesh {
       debugFlags.tempMap = mappedValue
     }
 
-    // Handle custom model override
+    // Handle custom model override (single or multiple parts)
     if (overrides.customModel) {
-      // empty mesh to allow "handled" entity and not pink box
+      const parts = normalizeCustomModelParts(overrides.customModel)
       this.mesh = new THREE.Object3D()
 
-      const { modelPath, modelType, metadata } = overrides.customModel
-
-      switch (modelType) {
-        case 'gltf': {
-          const loader = new GLTFLoader()
-          const gltfData = loader.parseAsync(modelPath, '')
-
-          gltfData.then(gltf => {
-            this.mesh.add(gltf.scene)
-            this.animations = gltf.animations
-
-            // Apply metadata overrides if available
+      for (let i = 0; i < parts.length; i++) {
+        const { modelPath, modelType, metadata } = parts[i]
+        const partRoot = new THREE.Object3D()
+        partRoot.name = `custom_part_${i}`
+
+        switch (modelType) {
+          case 'gltf': {
+            const loader = new GLTFLoader()
+            void loader.parseAsync(modelPath, '').then(gltf => {
+              partRoot.add(gltf.scene)
+              if (metadata?.scale) {
+                const s = metadata.scale
+                partRoot.scale.set(s, s, s)
+              }
+              if (metadata?.offset) {
+                const { x = 0, y = 0, z = 0 } = metadata.offset
+                partRoot.position.set(x, y, z)
+              }
+              if (metadata?.texture) {
+                const texture = new THREE.TextureLoader().load(metadata.texture)
+                texture.minFilter = THREE.NearestFilter
+                texture.magFilter = THREE.NearestFilter
+                partRoot.traverse((child) => {
+                  if (child instanceof THREE.Mesh) {
+                    child.material = new THREE.MeshBasicMaterial({
+                      map: texture,
+                      transparent: true,
+                      alphaTest: 0.1
+                    })
+                  }
+                })
+              }
+              if (gltf.animations?.length) {
+                this.animations = [...(this.animations ?? []), ...gltf.animations]
+                const controller = createAnimatedObject(partRoot, gltf.animations)
+                this.animationControllers.push(controller)
+                const animationName = metadata?.animation
+                const loop = metadata?.animationLoop ?? true
+                if (animationName) {
+                  controller.playAnimation(animationName, loop)
+                } else {
+                  controller.playAnimation(gltf.animations[0].name, loop)
+                }
+              }
+            }).catch(err => {
+              console.error('Failed to load GLTF model:', err)
+            })
+            break
+          }
+          case 'obj': {
+            const objLoader = new OBJLoader()
+            const obj = objLoader.parse(modelPath as string)
             if (metadata?.scale) {
               const { scale } = metadata
-              this.mesh.scale.set(scale, scale, scale)
+              obj.scale.set(scale, scale, scale)
             }
             if (metadata?.offset) {
               const { x = 0, y = 0, z = 0 } = metadata.offset
-              this.mesh.position.set(x, y, z)
+              obj.position.set(x, y, z)
             }
-
-            // Apply texture if provided
             if (metadata?.texture) {
               const texture = new THREE.TextureLoader().load(metadata.texture)
               texture.minFilter = THREE.NearestFilter
               texture.magFilter = THREE.NearestFilter
-              this.mesh.traverse((child) => {
+              const material = new THREE.MeshBasicMaterial({
+                map: texture,
+                transparent: true,
+                alphaTest: 0.1
+              })
+              obj.traverse((child) => {
                 if (child instanceof THREE.Mesh) {
-                  child.material = new THREE.MeshBasicMaterial({
-                    map: texture,
-                    transparent: true,
-                    alphaTest: 0.1
-                  })
+                  child.material = material
                 }
               })
             }
-
-            // Handle animations: play from config if provided, otherwise play first animation if present
-            if (gltf.animations && gltf.animations.length > 0) {
-              this.animations = gltf.animations
-              const animationName = metadata?.animation
-              const loop = metadata?.animationLoop ?? true
-
-              // Store initial animation settings for later use
-              this.initialAnimation = animationName
-              this.initialLoop = loop
-
-              // Create animation controller with onBeforeRender support
-              this.animationController = createAnimatedObject(this.mesh, gltf.animations)
-
-              if (animationName) {
-                // Play animation from config
-                this.playAnimation(animationName, loop)
-              } else {
-                // Play first animation
-                const clip = gltf.animations[0]
-                this.animationController.playAnimation(clip.name, loop)
-              }
-            }
-          }).catch(err => {
-            console.error('Failed to load GLTF model:', err)
-          })
-
-          // debugFlags.type = 'gltf'
-          return
-        }
-        case 'obj': {
-          const objLoader = new OBJLoader()
-          const obj = objLoader.parse(modelPath as string)
-
-          // Apply metadata overrides if available
-          if (metadata?.scale) {
-            const { scale } = metadata
-            obj.scale.set(scale, scale, scale)
-          }
-          if (metadata?.offset) {
-            const { x = 0, y = 0, z = 0 } = metadata.offset
-            obj.position.set(x, y, z)
-          }
-
-          // Apply texture if provided
-          if (metadata?.texture) {
-            const texture = new THREE.TextureLoader().load(metadata.texture)
-            texture.minFilter = THREE.NearestFilter
-            texture.magFilter = THREE.NearestFilter
-            const material = new THREE.MeshBasicMaterial({
-              map: texture,
-              transparent: true,
-              alphaTest: 0.1
-            })
-            obj.traverse((child) => {
-              if (child instanceof THREE.Mesh) {
-                child.material = material
-              }
-            })
-          }
-
-          this.mesh = obj
-          debugFlags.type = 'obj'
-          return
-        }
-        case 'bedrock': {
-          // Parse bedrock model JSON
-          const modelData = JSON.parse(modelPath as string)
-          this.mesh = new THREE.Object3D()
-
-          // Apply metadata overrides
-          if (metadata?.scale) {
-            this.mesh.scale.set(metadata.scale, metadata.scale, metadata.scale)
+            partRoot.add(obj)
+            break
           }
-          if (metadata?.offset) {
-            const { x = 0, y = 0, z = 0 } = metadata.offset
-            this.mesh.position.set(x, y, z)
-          }
-
-          // Create mesh from bedrock model
-          for (const [name, jsonModel] of Object.entries(modelData.geometry)) {
-            const texture = metadata?.textures?.[name] ?? modelData.textures?.[name]
-            if (!texture) continue
-
-            const mesh = getMesh(worldRenderer,
-              texture.endsWith('.png') || texture.startsWith('data:image/') || texture.startsWith('block:')
-                ? texture : texture + '.png',
-              jsonModel,
-              overrides,
-              debugFlags)
-            mesh.name = `geometry_${name}`
-            this.mesh.add(mesh)
+          case 'bedrock': {
+            const modelData = JSON.parse(modelPath as string)
+            if (metadata?.scale) {
+              partRoot.scale.set(metadata.scale, metadata.scale, metadata.scale)
+            }
+            if (metadata?.offset) {
+              const { x = 0, y = 0, z = 0 } = metadata.offset
+              partRoot.position.set(x, y, z)
+            }
+            for (const [name, jsonModel] of Object.entries(modelData.geometry)) {
+              const texture = metadata?.textures?.[name] ?? modelData.textures?.[name]
+              if (!texture) continue
+              const mesh = getMesh(worldRenderer,
+                texture.endsWith('.png') || texture.startsWith('data:image/') || texture.startsWith('block:')
+                  ? texture : texture + '.png',
+                jsonModel as JsonModel,
+                overrides,
+                debugFlags)
+              mesh.name = `geometry_${name}`
+              partRoot.add(mesh)
+            }
+            break
           }
-          debugFlags.type = 'bedrock'
-          return
         }
-        // No default
+        this.mesh.add(partRoot)
       }
+      debugFlags.type = parts.length === 1 ? parts[0].modelType : 'special'
+      return
     }
 
     if (externalModels[type]) {
@@ -696,15 +678,16 @@ export class EntityMesh {
   }
 
   playAnimation(name: string, loop = false) {
-    if (!this.animationController || !this.animations) {
+    if (!this.animationControllers.length) {
       console.warn('No animation controller available')
       return
     }
-
-    // Play animation using the controller
-    const success = this.animationController.playAnimation(name, loop)
-    if (!success) {
-      console.warn(`Animation "${name}" not found`)
+    let ok = false
+    for (const c of this.animationControllers) {
+      if (c.playAnimation(name, loop)) ok = true
+    }
+    if (!ok) {
+      console.warn(`Animation "${name}" not found on any custom model part`)
     }
   }
 

package/src/three/graphicsBackendBase.ts

@@ -16,6 +16,7 @@ import { WorldRendererThree } from './worldRendererThree'
 import { DocumentRenderer, isWebWorker, ThreeRendererMainData } from './documentRenderer'
 import { PanoramaRenderer } from './panorama'
 import { WorldViewWorker } from '../worldView'
+import type { FeedChunkPacketPayload } from '../worldView/types'
 
 // Disable Three.js color management for compatibility
 THREE.ColorManagement.enabled = false
@@ -80,6 +81,18 @@ export const getBackendMethods = (worldRenderer: WorldRendererThree): any => {
       // Import dynamically to avoid circular dependencies
       const { applyWorldGeometryExport } = await import('./worldGeometryExport')
       return applyWorldGeometryExport(worldRenderer, exportData)
+    },
+    feedChunkPacket(payload: FeedChunkPacketPayload) {
+      // Forward parsed/raw map_chunk + update_light packets from the
+      // web-client to all WASM mesher workers. The fan-out below uses
+      // structured clone (one Uint8Array can only be transferred to a
+      // single recipient); useWorkerProxy still gives zero-copy transfer
+      // from main into the off-thread renderer worker for free.
+      const { kind, ...rest } = payload
+      const message = { type: kind, ...rest }
+      for (const worker of worldRenderer.workers) {
+        worker.postMessage(message)
+      }
     }
   }
 }

package/src/three/holdingBlock.ts

@@ -12,7 +12,7 @@ import { disposeObject } from './threeJsUtils'
 import type { IHoldingBlock } from './holdingBlockTypes'
 import { HandItemBlock, MovementState } from '../playerState/types'
 import { PlayerStateRenderer } from '../playerState/playerState'
-import { getThreeBlockModelGroup } from '../mesher/standaloneRenderer'
+import { getThreeBlockModelGroup } from '../mesher-shared/standaloneRenderer'
 import { IndexedData } from 'minecraft-data'
 import { WorldRendererConfig } from '../graphicsBackend'
 import { computeCameraBob, type CameraBobInput } from '../lib/cameraBobbing'

package/src/three/holdingBlockLegacy.ts

@@ -12,7 +12,7 @@ import { WorldRendererThree } from './worldRendererThree'
 import { disposeObject } from './threeJsUtils'
 import { HandItemBlock, MovementState } from '../playerState/types'
 import { PlayerStateRenderer } from '../playerState/playerState'
-import { getThreeBlockModelGroup } from '../mesher/standaloneRenderer'
+import { getThreeBlockModelGroup } from '../mesher-shared/standaloneRenderer'
 import { IndexedData } from 'minecraft-data'
 import { WorldRendererConfig } from '../graphicsBackend'
 import { IHoldingBlock } from './holdingBlockTypes'

package/src/three/modules/sciFiWorldReveal.ts

@@ -2,7 +2,7 @@
 import * as THREE from 'three'
 import type { WorldRendererThree } from '../worldRendererThree'
 import type { RendererModuleController, RendererModuleManifest } from '../rendererModuleSystem'
-import type { MesherGeometryOutput } from '../../mesher/shared'
+import type { MesherGeometryOutput } from '../../mesher-shared/shared'
 
 const SCI_FI_CYAN = new THREE.Color(13 / 255, 234 / 255, 238 / 255)
 const CHUNKS_THRESHOLD = 9

package/src/three/worldRendererThree.ts

@@ -10,9 +10,9 @@ import { DisplayWorldOptions, GraphicsInitOptions } from '../graphicsBackend/typ
 import { chunkPos, sectionPos } from '../lib/simpleUtils'
 import { WorldRendererCommon } from '../lib/worldrendererCommon'
 import { addNewStat } from '../lib/ui/newStats'
-import { MesherGeometryOutput } from '../mesher/shared'
+import { MesherGeometryOutput } from '../mesher-shared/shared'
 import { ItemSpecificContextProperties } from '../playerState/types'
-import { setBlockPosition } from '../mesher/standaloneRenderer'
+import { setBlockPosition } from '../mesher-shared/standaloneRenderer'
 import { getMyHand } from './hand'
 import { createHoldingBlock } from './holdingBlockFactory'
 import type { IHoldingBlock } from './holdingBlockTypes'

package/src/wasm-mesher/README.md

@@ -0,0 +1,90 @@
+# src/wasm-mesher (JS side of the WASM mesher)
+
+This directory is the JS-side counterpart of the Rust crate at
+`/wasm-mesher/`. It contains everything that runs in the browser/Node:
+the worker, the JS↔Rust bridge, the wasm-pack runtime artefacts, and
+the WASM-only unit tests.
+
+The Rust source itself stays at the repo root (`/wasm-mesher/`); only
+its compiled output is mirrored here.
+
+## Layout
+
+```
+src/wasm-mesher/
+├── runtime-build/   ← wasm-pack output (--target web)
+│   ├── wasm_mesher.js          ← JS shim generated by wasm-bindgen
+│   ├── wasm_mesher_bg.wasm     ← compiled WASM module
+│   └── *.d.ts                  ← typings
+├── bridge/          ← thin JS layer between Rust output and the renderer
+│   ├── convertChunk.ts         ← legacy slow path: prismarine-chunk → typed arrays
+│   └── render-from-wasm.ts     ← geometry → Three.js + section split + heightmap
+├── worker/          ← runs inside the dedicated mesher Web Worker
+│   ├── mesherWasm.ts           ← worker entry; routes by version (1.16/17/18+)
+│   ├── mesherWasmConversionCache.ts
+│   └── mesherWasmRequestTracker.ts
+├── tests/           ← WASM-only vitest tests (run by `pnpm unit-test`)
+│   ├── heightmapParity.test.ts
+│   ├── splitColumnWasmOutput.test.ts
+│   └── mesherWasmConversionCache.test.ts
+└── README.md        ← you are here
+```
+
+Other related directories:
+
+- **`/wasm-mesher/`** (repo root) — the Rust crate (`src/*.rs`,
+  `Cargo.toml`, `build.sh`) and standalone TS test harnesses
+  (`tests/test-chunk.ts`, `tests/test-section-boundary.ts`).
+  See `wasm-mesher/README.md` for the public Rust API.
+- **`src/mesher-shared/`** — modules used by **both** this WASM path and
+  the legacy JS mesher (`models`, `world`, `shared`, `worldConstants`,
+  `computeHeightmap`, …).
+- **`src/mesher-legacy/`** — the original JS mesher, kept until the WASM
+  path proves itself in production. Will be removed in a follow-up PR.
+
+## Building
+
+The worker bundle is built by `scripts/buildMesherWorker.mjs`:
+
+```bash
+pnpm build:mesher          # esbuild → dist/mesherWasm.js (web-client contract)
+pnpm watch:mesher          # incremental rebuild on change
+```
+
+The output filename `dist/mesherWasm.js` is **load-bearing** — the
+web-client imports the worker by that path. `entryNames: '[name]'` in
+the build config keeps the output flat regardless of source-tree depth.
+
+The WASM module itself (`runtime-build/wasm_mesher_bg.wasm`) is rebuilt
+by:
+
+```bash
+pnpm build:wasm            # → runs wasm-mesher/build.sh web (release)
+```
+
+This requires `wasm-pack` on PATH; see `wasm-mesher/README.md` for setup.
+
+## Testing
+
+```bash
+pnpm unit-test --run       # all vitest tests, including this dir's tests/
+pnpm test:wasm             # snapshot + boundary + heightmap (cjs harnesses)
+pnpm test:wasm:boundary    # boundary + heightmap only
+```
+
+The vitest tests in `tests/` exercise the worker logic against real WASM:
+
+- `heightmapParity.test.ts` — JS `computeHeightmap` vs Rust output.
+- `splitColumnWasmOutput.test.ts` — column-split correctness.
+- `mesherWasmConversionCache.test.ts` — cache eviction and column reuse.
+
+## Notes
+
+- `bridge/convertChunk.ts` is the **slow path** (prismarine-chunk → typed
+  arrays in JS). For 1.18+ chunks the worker prefers the fast path:
+  `parseChunkDump118FullColumnAll` (a single Rust call) consumed via
+  `worker/mesherWasm.ts`. See `docs/issues/issue-15-wasm/history.md` for
+  the rationale and benchmarks.
+- Routing of raw `map_chunk` packets (1.16 / 1.17 / 1.18+) lives in
+  `worker/mesherWasm.ts`; per-version Rust parsers are in
+  `wasm-mesher/src/parser_*.rs`.

package/src/{wasm-lib → wasm-mesher/bridge}/convertChunk.ts

@@ -2,7 +2,7 @@
 import { Vec3 } from 'vec3'
 import MinecraftData from 'minecraft-data'
 import PrismarineBlockLoader from 'prismarine-block'
-import moreBlockDataGeneratedJson from '../lib/moreBlockDataGenerated.json'
+import moreBlockDataGeneratedJson from '../../lib/moreBlockDataGenerated.json'
 
 type BlockMeta = {
   invisibleBlocks: Uint16Array
@@ -54,7 +54,7 @@ const isLikelyFullCubeBlockName = (name: string) => {
   return true
 }
 
-const getBlockMeta = (version: string): BlockMeta => {
+export const getBlockMeta = (version: string): BlockMeta => {
   const cached = metaCache.get(version)
   if (cached) return cached
 

package/src/{wasm-lib → wasm-mesher/bridge}/render-from-wasm.ts

@@ -9,10 +9,10 @@ import blockStatesModels from 'mc-assets/dist/blockStatesModels.json'
 import MinecraftData from 'minecraft-data'
 import PrismarineBlockLoader from 'prismarine-block'
 import { Vec3 } from 'vec3'
-import { elemFaces, buildRotationMatrix, matmul3, matmulmat3, vecadd3, vecsub3 } from '../mesher/modelsGeometryCommon'
-import type { ExportedWorldGeometry, ExportedSection } from '../three/worldGeometryExport'
-import type { MesherGeometryOutput } from '../mesher/shared'
-import type { World } from '../mesher/world'
+import { elemFaces, buildRotationMatrix, matmul3, matmulmat3, vecadd3, vecsub3 } from '../../mesher-shared/modelsGeometryCommon'
+import type { ExportedWorldGeometry, ExportedSection } from '../../three/worldGeometryExport'
+import type { MesherGeometryOutput } from '../../mesher-shared/shared'
+import type { World } from '../../mesher-shared/world'
 
 // Handle both default and named export
 const worldBlockProvider = (worldBlockProviderModule as any).default || worldBlockProviderModule