minecraft-renderer 0.1.55 → 0.1.56

package/package.json

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

package/src/lib/buildWorkerMcDataIndexes.test.ts

@@ -14,6 +14,24 @@ describe('augmentWorkerMcData', () => {
     expect(Array.isArray(mcData.blocksArray)).toBe(true)
   })
 
+  it('keeps *Array sources after indexing (esbuild mc-data plugin reads blocksArray)', () => {
+    const mcData: Record<string, unknown> = {
+      blocks: [{ name: 'stone', id: 3, minStateId: 48, maxStateId: 63, defaultState: 48 }],
+    }
+    augmentWorkerMcData(mcData)
+    expect(Array.isArray(mcData.blocksArray)).toBe(true)
+    expect((mcData.blocksArray as unknown[]).length).toBe(1)
+    expect(Array.isArray(mcData.blocks)).toBe(false)
+  })
+
+  it('coerces valtio-style dense objects into arrays', () => {
+    const mcData: Record<string, unknown> = {
+      entities: { 0: { name: 'bat', id: 1, type: 'mob' } },
+    }
+    augmentWorkerMcData(mcData)
+    expect((mcData.entitiesByName as Record<string, { name: string }>).bat?.name).toBe('bat')
+  })
+
   it('builds entitiesByName and items indexes from arrays', () => {
     const mcData: Record<string, unknown> = {
       entities: [{ name: 'bat', id: 1, type: 'mob' }],

package/src/lib/buildWorkerMcDataIndexes.ts

@@ -1,10 +1,34 @@
 //@ts-nocheck
 type McElement = Record<string, unknown>
 
+function coerceDenseArray (value: unknown): McElement[] | undefined {
+  if (Array.isArray(value)) {
+    return value as McElement[]
+  }
+  if (!value || typeof value !== 'object') {
+    return undefined
+  }
+  const record = value as Record<string, McElement>
+  const keys = Object.keys(record).filter((k) => /^\d+$/.test(k)).map(Number).sort((a, b) => a - b)
+  if (!keys.length || keys[0] !== 0) {
+    return undefined
+  }
+  for (let i = 0; i < keys.length; i++) {
+    if (keys[i] !== i) {
+      return undefined
+    }
+  }
+  return keys.map((k) => record[String(k)])
+}
+
 function buildIndexFromArray<T extends McElement> (
   array: T[],
   field: keyof T
 ): Record<string | number, T> {
+  if (!Array.isArray(array)) {
+    console.warn('[augmentWorkerMcData] buildIndexFromArray expected array, got', typeof array)
+    return {}
+  }
   return array.reduce<Record<string | number, T>>((index, element) => {
     index[element[field] as string | number] = element
     return index
@@ -16,6 +40,10 @@ function buildIndexFromArrayWithRanges<T extends McElement> (
   minField: keyof T,
   maxField: keyof T
 ): Record<number, T> {
+  if (!Array.isArray(array)) {
+    console.warn('[augmentWorkerMcData] buildIndexFromArrayWithRanges expected array, got', typeof array)
+    return {}
+  }
   return array.reduce<Record<number, T>>((index, element) => {
     const min = element[minField] as number
     const max = element[maxField] as number
@@ -42,13 +70,13 @@ function getSourceArray (
   arrayKey: string,
   rawKey: string
 ): McElement[] | undefined {
-  const fromArrayKey = mcData[arrayKey]
-  if (Array.isArray(fromArrayKey)) {
-    return fromArrayKey as McElement[]
+  const fromArrayKey = coerceDenseArray(mcData[arrayKey])
+  if (fromArrayKey?.length) {
+    return fromArrayKey
   }
-  const raw = mcData[rawKey]
-  if (Array.isArray(raw)) {
-    return raw as McElement[]
+  const raw = coerceDenseArray(mcData[rawKey])
+  if (raw?.length) {
+    return raw
   }
   return undefined
 }

package/src/lib/items.ts

@@ -4,7 +4,7 @@ import nbt from 'prismarine-nbt'
 import { fromFormattedString } from '@xmcl/text-component'
 import { getItemSelector } from '../playerState/playerState'
 import { getItemDefinition } from 'mc-assets/dist/itemDefinitions'
-import { ResourcesManagerCommon } from '../resourcesManager'
+import { getItemsDefinitionsStoreForRender, ResourcesManagerCommon } from '../resourcesManager'
 import { ItemSpecificContextProperties } from '../playerState/types'
 import { PlayerStateRenderer } from '../playerState/playerState'
 
@@ -131,9 +131,10 @@ export const getItemModelName = (item: GeneralInputItem, specificProps: ItemSpec
   const itemSelector = getItemSelector(playerState, {
     ...specificProps
   })
-  const modelFromDef = getItemDefinition(resourcesManager.currentResources!.itemsDefinitionsStore, {
+  const resources = resourcesManager.currentResources!
+  const modelFromDef = getItemDefinition(getItemsDefinitionsStoreForRender(resources), {
     name: itemModelName,
-    version: resourcesManager.currentResources!.version,
+    version: resources.version,
     properties: itemSelector
   })?.model
   const model = (modelFromDef === 'minecraft:special' ? undefined : modelFromDef) ?? itemModelName

package/src/lib/utils.ts

@@ -42,7 +42,7 @@ const detectFullOffscreenCanvasSupport = () => {
 const hasFullOffscreenCanvasSupport = detectFullOffscreenCanvasSupport()
 
 export const createCanvas = (width: number, height: number): OffscreenCanvas => {
-  if (hasFullOffscreenCanvasSupport) {
+  if (hasFullOffscreenCanvasSupport || typeof document === 'undefined') {
     return new OffscreenCanvas(width, height)
   }
   const canvas = document.createElement('canvas')

package/src/lib/workerMessageSanitize.test.ts

@@ -0,0 +1,14 @@
+//@ts-nocheck
+import { describe, expect, it } from 'vitest'
+import { sanitizeForWorkerPostMessage } from './workerMessageSanitize'
+
+describe('sanitizeForWorkerPostMessage', () => {
+  it('drops functions such as debug loggers', () => {
+    const debug = Object.assign(() => {}, { enabled: false })
+    const entity = { id: 1, name: 'zombie', debug, position: { x: 1, y: 2, z: 3 } }
+    const sanitized = sanitizeForWorkerPostMessage(entity) as Record<string, unknown>
+    expect(sanitized.debug).toBeUndefined()
+    expect(sanitized.id).toBe(1)
+    expect(() => structuredClone(sanitized)).not.toThrow()
+  })
+})

package/src/lib/workerMessageSanitize.ts

@@ -0,0 +1,48 @@
+//@ts-nocheck
+/**
+ * Strip non–structured-clone values before Worker.postMessage (e.g. mineflayer `debug` on entities).
+ */
+export function sanitizeForWorkerPostMessage (value: unknown, depth = 0): unknown {
+  if (depth > 16) return undefined
+  if (value === null || value === undefined) return value
+
+  const t = typeof value
+  if (t === 'function' || t === 'symbol') return undefined
+  if (t === 'bigint') return value.toString()
+  if (t !== 'object') return value
+
+  if (value instanceof ArrayBuffer) return value
+  if (ArrayBuffer.isView(value)) {
+    const view = value as ArrayBufferView
+    return view.buffer.slice(view.byteOffset, view.byteOffset + view.byteLength)
+  }
+  if (value instanceof Date) return value.toISOString()
+
+  if (Array.isArray(value)) {
+    return value
+      .map((entry) => sanitizeForWorkerPostMessage(entry, depth + 1))
+      .filter((entry) => entry !== undefined)
+  }
+
+  const record = value as Record<string, unknown>
+  if (
+    typeof record.x === 'number'
+    && typeof record.y === 'number'
+    && typeof record.z === 'number'
+    && !('w' in record)
+  ) {
+    return { x: record.x, y: record.y, z: record.z }
+  }
+
+  const out: Record<string, unknown> = {}
+  for (const key of Object.keys(record)) {
+    if (key === '_client' || key === '_events' || key === '_eventsCount') continue
+    const sanitized = sanitizeForWorkerPostMessage(record[key], depth + 1)
+    if (sanitized !== undefined) out[key] = sanitized
+  }
+  return out
+}
+
+export function sanitizeWorkerEventArgs (args: unknown[]): unknown[] {
+  return args.map((arg) => sanitizeForWorkerPostMessage(arg))
+}

package/src/resourcesManager/resourcesManager.ts

@@ -14,7 +14,8 @@ import { AtlasParser, ItemsAtlasesOutputJson } from 'mc-assets/dist/atlasParser'
 import worldBlockProvider, { WorldBlockProvider } from 'mc-assets/dist/worldBlockProvider'
 import { isWebWorker } from '../three/documentRenderer'
 import { ItemsRenderer } from 'mc-assets/dist/itemsRenderer'
-import { getLoadedItemDefinitionsStore } from 'mc-assets'
+import { getLoadedItemDefinitionsStore } from 'mc-assets/dist/stores'
+import { sanitizeWorkerEventArgs } from '../lib/workerMessageSanitize'
 
 type ResourceManagerEvents = {
   assetsTexturesUpdated: () => void
@@ -22,16 +23,43 @@ type ResourceManagerEvents = {
   assetsInventoryReady: () => void
 }
 
+type ItemDefinitionsStore = ReturnType<typeof getLoadedItemDefinitionsStore>
+
+let workerItemDefinitionsStore: ItemDefinitionsStore | null = null
+
+export function getItemsDefinitionsStoreForRender (
+  resources: LoadedResourcesTransferrable
+): ItemDefinitionsStore {
+  if (!isWebWorker) {
+    ensureItemsDefinitionsStore(resources)
+    return resources.itemsDefinitionsStore
+  }
+  if (!workerItemDefinitionsStore || typeof workerItemDefinitionsStore.get !== 'function') {
+    workerItemDefinitionsStore = getLoadedItemDefinitionsStore(itemDefinitionsJson)
+  }
+  return workerItemDefinitionsStore
+}
+
+export function ensureItemsDefinitionsStore (resources: LoadedResourcesTransferrable): void {
+  if (isWebWorker) return
+  const store = resources.itemsDefinitionsStore as { get?: unknown }
+  if (typeof store?.get === 'function') return
+  resources.itemsDefinitionsStore = getLoadedItemDefinitionsStore(
+    resources.sourceItemDefinitionsJson ?? itemDefinitionsJson
+  )
+}
+
 export class LoadedResourcesTransferrable {
   // todo transfer instead!
   readonly sourceItemDefinitionsJson: any = itemDefinitionsJson
-  readonly itemsDefinitionsStore = getLoadedItemDefinitionsStore(this.sourceItemDefinitionsJson)
+  itemsDefinitionsStore = getLoadedItemDefinitionsStore(this.sourceItemDefinitionsJson)
 
   allReady = false
   // Atlas parsers
   itemsAtlasImage!: ImageBitmap
   blocksAtlasImage!: ImageBitmap
   blocksAtlasJson!: ItemsAtlasesOutputJson
+  itemsAtlasJson!: ItemsAtlasesOutputJson
   // User data (specific to current resourcepack/version)
   customBlockStates?: Record<string, any>
   customModels?: Record<string, any>
@@ -55,7 +83,11 @@ export class LoadedResourcesTransferrable {
 
   constructor(data?: any) {
     if (data) {
-      Object.assign(this, data)
+      const safe = { ...data }
+      delete safe.itemsDefinitionsStore
+      delete safe.sourceItemDefinitionsJson
+      Object.assign(this, safe)
+      ensureItemsDefinitionsStore(this)
     }
     if (this.version) {
       const globalMc = (globalThis as { loadedData?: IndexedData, mcData?: IndexedData }).loadedData
@@ -89,6 +121,8 @@ export class LoadedResourcesTransferrable {
     }
 
     cloned.customTextures = {}
+    delete cloned.itemsDefinitionsStore
+    delete cloned.sourceItemDefinitionsJson
     return cloned as LoadedResourcesTransferrable
   }
 
@@ -117,10 +151,36 @@ const STABLE_MODELS_VERSION = '1.21.4'
 export class ResourcesManager extends (EventEmitter as new () => TypedEmitter<ResourceManagerEvents>) {
   static restorerName = 'ResourcesManager'
 
+  rebuildWorkerRenderers (resources: LoadedResourcesTransferrable): void {
+    if (!isWebWorker) return
+    if (!resources.version || !resources.blockstatesModels || !resources.blocksAtlasJson) return
+
+    this.blocksAtlasParser = new AtlasParser({ latest: resources.blocksAtlasJson }, '')
+    if (resources.itemsAtlasJson) {
+      this.itemsAtlasParser = new AtlasParser({ latest: resources.itemsAtlasJson }, '')
+    } else if (!this.itemsAtlasParser?.atlas?.latest) {
+      if (!this.sourceItemsAtlases || Object.keys(this.sourceItemsAtlases).length === 0) return
+      this.itemsAtlasParser = new AtlasParser(this.sourceItemsAtlases, '')
+    }
+
+    resources.itemsRenderer = new ItemsRenderer(
+      resources.version,
+      resources.blockstatesModels,
+      this.itemsAtlasParser,
+      this.blocksAtlasParser
+    )
+    resources.worldBlockProvider = worldBlockProvider(
+      resources.blockstatesModels,
+      this.blocksAtlasParser.atlas,
+      STABLE_MODELS_VERSION
+    )
+  }
+
   static restoreTransferred(data: any, worker?: Worker) {
     const resourcesManager = new ResourcesManager()
-    const upResources = (data) => {
-      resourcesManager.currentResources = new LoadedResourcesTransferrable(data)
+    const upResources = (transferData: LoadedResourcesTransferrable) => {
+      resourcesManager.currentResources = new LoadedResourcesTransferrable(transferData)
+      resourcesManager.rebuildWorkerRenderers(resourcesManager.currentResources)
     }
     upResources(data.currentResources)
     if (worker) {
@@ -139,6 +199,17 @@ export class ResourcesManager extends (EventEmitter as new () => TypedEmitter<Re
     return resourcesManager
   }
 
+  enrichTransferSnapshot (transfer?: LoadedResourcesTransferrable): LoadedResourcesTransferrable | undefined {
+    if (!transfer) return transfer
+    if (this.itemsAtlasParser?.atlas?.latest) {
+      transfer.itemsAtlasJson = this.itemsAtlasParser.atlas.latest
+    }
+    if (this.blocksAtlasParser?.atlas?.latest) {
+      transfer.blocksAtlasJson = this.blocksAtlasParser.atlas.latest
+    }
+    return transfer
+  }
+
   prepareForTransfer(worker?: Worker) {
     if (worker) {
       // todo do it automatically
@@ -149,21 +220,24 @@ export class ResourcesManager extends (EventEmitter as new () => TypedEmitter<Re
           class: ResourcesManager.restorerName,
           type: 'event',
           eventName,
-          args,
+          args: sanitizeWorkerEventArgs(args),
         })
         // todo handle assetsInventoryReady
         if (eventName === 'assetsTexturesUpdated' || eventName === 'assetsInventoryReady') {
+          const currentResources = this.enrichTransferSnapshot(
+            this.currentResources?.prepareForTransfer(),
+          )
           worker.postMessage({
             class: ResourcesManager.restorerName,
             type: 'newResources',
-            currentResources: this.currentResources?.prepareForTransfer(),
+            currentResources,
           })
         }
       }) as any
     }
     return {
       __restorer: ResourcesManager.restorerName,
-      currentResources: this.currentResources?.prepareForTransfer(),
+      currentResources: this.enrichTransferSnapshot(this.currentResources?.prepareForTransfer()),
     }
   }
 
@@ -316,6 +390,7 @@ export class ResourcesManager extends (EventEmitter as new () => TypedEmitter<Re
 
     this.itemsAtlasParser = new AtlasParser({ latest: itemsAtlas }, itemsCanvas.toDataURL())
     resources.itemsAtlasImage = await createImageBitmap(itemsCanvas)
+    resources.itemsAtlasJson = this.itemsAtlasParser.atlas.latest
   }
 
   async generateGuiTextures() {

package/src/resourcesManager/resourcesManager.worker.test.ts

@@ -0,0 +1,61 @@
+//@ts-nocheck
+import { describe, expect, it, vi } from 'vitest'
+import blocksAtlases from 'mc-assets/dist/blocksAtlases.json'
+import itemsAtlases from 'mc-assets/dist/itemsAtlases.json'
+import blockstatesModels from 'mc-assets/dist/blockStatesModels.json'
+import { AtlasParser } from 'mc-assets/dist/atlasParser'
+import {
+  getItemsDefinitionsStoreForRender,
+  LoadedResourcesTransferrable,
+  ResourcesManager,
+} from './resourcesManager'
+
+vi.mock('../three/documentRenderer', () => ({
+  isWebWorker: true,
+}))
+
+describe('ResourcesManager.rebuildWorkerRenderers', () => {
+  it('creates ItemsRenderer with working modelsStore.get in worker context', () => {
+    const blocksAtlasParser = new AtlasParser(blocksAtlases as any, '')
+    const itemsAtlasParser = new AtlasParser(itemsAtlases as any, '')
+    const resources = new LoadedResourcesTransferrable({
+      version: '1.21.4',
+      texturesVersion: '1.21.4',
+      blockstatesModels,
+      blocksAtlasJson: blocksAtlasParser.atlas.latest,
+      itemsAtlasJson: itemsAtlasParser.atlas.latest,
+      allReady: true,
+    })
+
+    const manager = new ResourcesManager()
+    manager.rebuildWorkerRenderers(resources)
+
+    expect(resources.itemsRenderer).toBeDefined()
+    expect(resources.worldBlockProvider).toBeDefined()
+    const tex = resources.itemsRenderer!.getItemTexture('item/missing_texture')
+    expect(tex).toBeDefined()
+  })
+
+  it('getItemsDefinitionsStoreForRender returns store with .get in worker', () => {
+    const resources = new LoadedResourcesTransferrable({
+      version: '1.21.4',
+      blockstatesModels,
+      blocksAtlasJson: (new AtlasParser(blocksAtlases as any, '')).atlas.latest,
+      itemsDefinitionsStore: { data: { latest: {} }, inclusive: false },
+    })
+    const store = getItemsDefinitionsStoreForRender(resources)
+    expect(typeof store.get).toBe('function')
+  })
+
+  it('falls back to bundled items atlas when itemsAtlasJson is missing', () => {
+    const resources = new LoadedResourcesTransferrable({
+      version: '1.21.4',
+      blockstatesModels,
+      blocksAtlasJson: (new AtlasParser(blocksAtlases as any, '')).atlas.latest,
+    })
+    const manager = new ResourcesManager()
+    manager.rebuildWorkerRenderers(resources)
+    expect(resources.itemsRenderer).toBeDefined()
+    expect(resources.itemsRenderer!.getItemTexture('item/missing_texture')).toBeDefined()
+  })
+})

package/src/three/appShared.ts

@@ -3,7 +3,7 @@ import { BlockModel } from 'mc-assets/dist/types'
 import { ItemSpecificContextProperties } from '../playerState/types'
 import { PlayerStateRenderer } from '../playerState/playerState'
 import { GeneralInputItem, getItemModelName } from '../lib/items'
-import { ResourcesManager, ResourcesManagerTransferred } from '../resourcesManager'
+import { ResourcesManagerTransferred } from '../resourcesManager'
 import { renderSlot } from './renderSlot'
 
 export const getItemUv = (item: Record<string, any>, specificProps: ItemSpecificContextProperties, resourcesManager: ResourcesManagerTransferred, playerState: PlayerStateRenderer): {

package/src/three/entities.ts

@@ -22,7 +22,7 @@ import { createItemMesh } from './itemMesh'
 import * as Entity from './entity/EntityMesh'
 import { getMesh } from './entity/EntityMesh'
 import { WalkingGeneralSwing } from './entity/animations'
-import { disposeObject, loadTexture, loadThreeJsTextureFromUrl } from './threeJsUtils'
+import { disposeObject, loadNearestFilterTexture, loadTexture, loadThreeJsTextureFromUrl } from './threeJsUtils'
 import { armorModel, armorTextures, elytraTexture } from './entity/armorModels'
 import { WorldRendererThree } from './worldRendererThree'
 import { IndexedData } from 'minecraft-data'
@@ -213,6 +213,19 @@ const nametags = {}
 
 const isFirstUpperCase = (str) => str.charAt(0) === str.charAt(0).toUpperCase()
 
+function metadataAsArray (metadata: unknown): unknown[] | undefined {
+  if (metadata == null) return undefined
+  if (Array.isArray(metadata)) return metadata
+  if (typeof metadata === 'object') {
+    const record = metadata as Record<string, unknown>
+    const keys = Object.keys(record).filter((k) => /^\d+$/.test(k)).map(Number).sort((a, b) => a - b)
+    if (keys.length && keys[0] === 0 && keys.every((k, i) => k === i)) {
+      return keys.map((k) => record[String(k)])
+    }
+  }
+  return undefined
+}
+
 function getEntityMesh(mcData: IndexedData | undefined, entity: import('prismarine-entity').Entity & { delete?: any; pos?: any; name?: any }, world: WorldRendererThree, options: { fontFamily: string }, overrides) {
   if (entity.name) {
     try {
@@ -1086,7 +1099,7 @@ export class Entities {
           ? { name: entity.name }
           : entity.name === 'falling_block'
             ? { blockState: entity['objectData'] }
-            : entity.metadata?.find((m: any) => typeof m === 'object' && m?.itemCount)
+            : metadataAsArray(entity.metadata)?.find((m: any) => typeof m === 'object' && m?.itemCount)
         if (item) {
           const object = this.getItemMesh(item, {
             'minecraft:display_context': 'ground',
@@ -1177,7 +1190,8 @@ export class Entities {
 
     const meta = getGeneralEntitiesMetadata(entity, this.mcData)
 
-    const isInvisible = ((entity.metadata?.[0] ?? 0) as unknown as number) & 0x20 || (this.worldRenderer.playerStateReactive.cameraSpectatingEntity === entity.id && this.worldRenderer.playerStateUtils.isSpectator())
+    const meta0 = metadataAsArray(entity.metadata)?.[0] ?? (entity.metadata as { 0?: unknown } | undefined)?.[0]
+    const isInvisible = ((meta0 ?? 0) as unknown as number) & 0x20 || (this.worldRenderer.playerStateReactive.cameraSpectatingEntity === entity.id && this.worldRenderer.playerStateUtils.isSpectator())
     for (const child of mesh!.children ?? []) {
       if (child.name !== 'nametag') {
         child.visible = !isInvisible
@@ -1512,12 +1526,8 @@ export class Entities {
   }
 
   loadMap(data: any) {
-    const texture = new THREE.TextureLoader().load(data)
-    if (texture) {
-      texture.magFilter = THREE.NearestFilter
-      texture.minFilter = THREE.NearestFilter
-      texture.needsUpdate = true
-    }
+    const texture = loadNearestFilterTexture(data)
+    texture.needsUpdate = true
     return texture
   }
 

package/src/three/entity/EntityMesh.ts

@@ -8,7 +8,7 @@ import ocelotPng from 'mc-assets/dist/other-textures/latest/entity/cat/ocelot.pn
 import arrowTexture from 'mc-assets/dist/other-textures/1.21.2/entity/projectiles/arrow.png'
 import spectralArrowTexture from 'mc-assets/dist/other-textures/1.21.2/entity/projectiles/spectral_arrow.png'
 import tippedArrowTexture from 'mc-assets/dist/other-textures/1.21.2/entity/projectiles/tipped_arrow.png'
-import { loadTexture } from '../threeJsUtils'
+import { loadNearestFilterTexture, loadTexture } from '../threeJsUtils'
 import { WorldRendererThree } from '../worldRendererThree'
 import entities from './entities.json'
 import { externalModels } from './objModels'
@@ -505,9 +505,7 @@ export class EntityMesh {
                 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
+                const texture = loadNearestFilterTexture(metadata.texture)
                 partRoot.traverse((child) => {
                   if (child instanceof THREE.Mesh) {
                     child.material = new THREE.MeshBasicMaterial({
@@ -547,9 +545,7 @@ export class EntityMesh {
               obj.position.set(x, y, z)
             }
             if (metadata?.texture) {
-              const texture = new THREE.TextureLoader().load(metadata.texture)
-              texture.minFilter = THREE.NearestFilter
-              texture.magFilter = THREE.NearestFilter
+              const texture = loadNearestFilterTexture(metadata.texture)
               const material = new THREE.MeshBasicMaterial({
                 map: texture,
                 transparent: true,
@@ -616,9 +612,7 @@ export class EntityMesh {
         debugFlags.isHardcodedTexture = true
       }
       if (!texturePath) throw new Error(`No texture for ${type}`)
-      const texture = new THREE.TextureLoader().load(texturePath)
-      texture.minFilter = THREE.NearestFilter
-      texture.magFilter = THREE.NearestFilter
+      const texture = loadNearestFilterTexture(texturePath)
       const material = new THREE.MeshBasicMaterial({
         map: texture,
         transparent: true,

package/src/three/itemMesh.ts

@@ -1,6 +1,19 @@
 //@ts-nocheck
 import * as THREE from 'three'
 
+/** Canvas used for item texture extraction (main thread or worker). */
+export type ItemTextureCanvas = HTMLCanvasElement | OffscreenCanvas
+
+function createItemTextureCanvas (width: number, height: number): ItemTextureCanvas {
+  if (typeof document !== 'undefined') {
+    const canvas = document.createElement('canvas')
+    canvas.width = width
+    canvas.height = height
+    return canvas
+  }
+  return new OffscreenCanvas(width, height)
+}
+
 export interface Create3DItemMeshOptions {
   depth: number
   pixelSize?: number
@@ -17,7 +30,7 @@ export interface Create3DItemMeshResult {
  * from a canvas containing the item texture
  */
 export function create3DItemMesh (
-  canvas: HTMLCanvasElement,
+  canvas: ItemTextureCanvas,
   options: Create3DItemMeshOptions
 ): Create3DItemMeshResult {
   const { depth, pixelSize } = options
@@ -246,18 +259,18 @@ export interface ItemMeshResult {
 export function extractItemTextureToCanvas (
   sourceTexture: THREE.Texture,
   textureInfo: ItemTextureInfo
-): HTMLCanvasElement {
+): ItemTextureCanvas {
   const { u, v, sizeX, sizeY } = textureInfo
 
   // Calculate canvas size - fix the calculation
   const canvasWidth = Math.max(1, Math.floor(sizeX * sourceTexture.image.width))
   const canvasHeight = Math.max(1, Math.floor(sizeY * sourceTexture.image.height))
 
-  const canvas = document.createElement('canvas')
-  canvas.width = canvasWidth
-  canvas.height = canvasHeight
-
-  const ctx = canvas.getContext('2d')!
+  const canvas = createItemTextureCanvas(canvasWidth, canvasHeight)
+  const ctx = canvas.getContext('2d') as CanvasRenderingContext2D | OffscreenCanvasRenderingContext2D | null
+  if (!ctx) {
+    throw new Error('Failed to get 2d context for item texture canvas')
+  }
   ctx.imageSmoothingEnabled = false
 
   // Draw the item texture region to canvas

package/src/three/threeJsMedia.ts

@@ -2,6 +2,8 @@
 import * as THREE from 'three'
 import { WorldRendererThree } from './worldRendererThree'
 import { ThreeJsSound } from './threeJsSound'
+import { isWebWorker } from './documentRenderer'
+import { loadThreeJsTextureFromUrlSync } from './threeJsUtils'
 
 type ControlModeConfig = {
   mouseButton: 'both' | 'left' | 'right'
@@ -187,7 +189,11 @@ export class ThreeJsMedia {
 
     let video: HTMLVideoElement | undefined
     let positionalAudio: THREE.PositionalAudio | undefined
-    if (!isImage) {
+    const workerVideoUnsupported = isWebWorker && !isImage
+    if (workerVideoUnsupported) {
+      console.warn(`[addMedia] Video "${id}" skipped in off-thread renderer (no HTMLVideoElement)`)
+    }
+    if (!isImage && !workerVideoUnsupported) {
       video = document.createElement('video')
       video.src = props.src.endsWith('.gif') ? props.src.replace('.gif', '.mp4') : props.src
       video.loop = props.loop ?? true
@@ -268,14 +274,35 @@ export class ThreeJsMedia {
       alphaTest: 0.1
     })
 
-    const texture = video
-      ? new THREE.VideoTexture(video)
-      : new THREE.TextureLoader().load(props.src, () => {
+    let texture: THREE.Texture
+    if (video) {
+      texture = new THREE.VideoTexture(video)
+    } else if (workerVideoUnsupported) {
+      texture = this.createErrorTexture(
+        props.size.width,
+        props.size.height,
+        props.background,
+        'Video unavailable (multi-thread)',
+      )
+    } else if (isWebWorker) {
+      const loaded = loadThreeJsTextureFromUrlSync(props.src)
+      texture = loaded.texture
+      texture.minFilter = THREE.NearestFilter
+      texture.magFilter = THREE.NearestFilter
+      void loaded.promise.then(() => {
+        if (this.customMedia.get(id)?.texture === texture) {
+          material.map = texture
+          material.needsUpdate = true
+        }
+      }).catch(() => handleError())
+    } else {
+      texture = new THREE.TextureLoader().load(props.src, () => {
         if (this.customMedia.get(id)?.texture === texture) {
           material.map = texture
           material.needsUpdate = true
         }
       }, undefined, () => handleError()) // todo cache
+    }
     texture.minFilter = THREE.NearestFilter
     texture.magFilter = THREE.NearestFilter
     // texture.format = THREE.RGBAFormat