minecraft-renderer 0.1.73 → 0.1.75

package/package.json

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

package/src/graphicsBackend/config.ts

@@ -81,6 +81,10 @@ export const defaultWorldRendererConfig = {
   isPlayground: false,
   instantCameraUpdate: false,
   isRaining: false,
+  // rainColor: 'rgb(64, 87, 148)', // original minecraft blue
+  rainColor: 'rgb(118, 148, 226)',
+  /** Rain particle opacity 0–1. */
+  rainOpacity: 0.5,
 
   // Module states: 'enabled' = force on, 'disabled' = force off, 'auto' = use autoEnableCheck
   moduleStates: {} as Record<string, 'enabled' | 'disabled' | 'auto'>

package/src/graphicsBackend/types.ts

@@ -101,6 +101,7 @@ export interface GraphicsInitOptions<S = any> {
   /** Live app options (e.g. valtio proxy); used for WebGL `gpuPreference` at context creation. */
   getRendererOptions?: () => RendererStorageOptions
   rendererSpecificSettings: S
+  hello?: boolean
   callbacks: {
     displayCriticalError: (error: Error) => void
     setRendererSpecificSettings: (key: string, value: any) => void

package/src/lib/bindAbortableListener.ts

@@ -10,7 +10,7 @@ import type { WorldViewWorker } from '../worldView'
 export function bindAbortableListener<E extends keyof WorldViewEvents>(
   emitter: Pick<WorldViewWorker, 'on' | 'off'>,
   event: E,
-  handler: (...args: WorldViewEvents[E]) => void,
+  handler: (...args: Parameters<WorldViewEvents[E]>) => void,
   signal: AbortSignal
 ): void {
   emitter.on(event, handler as (...args: any[]) => void)

package/src/lib/createPlayerObject.ts

@@ -12,7 +12,7 @@ export type PlayerObjectType = PlayerObject & {
 
 /** Starfield + log-depth world: cutout skin mats need alphaTest and depthWrite (not mesh traverse). */
 export function configurePlayerSkinMaterials (playerObject: PlayerObject): void {
-  const skin = playerObject.skin
+  const skin = playerObject.skin as any
   const materials = [
     skin.layer1Material,
     skin.layer1MaterialBiased,

package/src/lib/worldrendererCommon.reconfigure.test.ts

@@ -6,6 +6,7 @@ import { proxy } from 'valtio'
 import * as worldRendererModule from './worldrendererCommon'
 import { WorldRendererCommon } from './worldrendererCommon'
 import { defaultWorldRendererConfig } from '../graphicsBackend/config'
+import { defaultPerformanceInstabilityFactors } from '../performanceMonitor'
 import { getInitialPlayerState } from '../playerState/playerState'
 import type { DisplayWorldOptions, GraphicsInitOptions } from '../graphicsBackend/types'
 
@@ -46,6 +47,8 @@ class TestWorldRenderer extends WorldRendererCommon {
   updateCamera() {}
   render() {}
   updateShowChunksBorder() {}
+  updatePlayerEntity() {}
+  worldStop() {}
 }
 
 function createRenderer(workerCount = 2, worldView?: DisplayWorldOptions['worldView']) {
@@ -56,7 +59,7 @@ function createRenderer(workerCount = 2, worldView?: DisplayWorldOptions['worldV
       heightmaps: {} as Record<string, Int16Array>,
       allChunksLoaded: false,
       mesherWork: false,
-      instabilityFactors: {},
+      instabilityFactors: defaultPerformanceInstabilityFactors(),
       intersectMedia: null,
     },
     renderer: '',

package/src/lib/worldrendererCommon.removeColumn.test.ts

@@ -5,6 +5,7 @@ import { Vec3 } from 'vec3'
 import { proxy } from 'valtio'
 import { WorldRendererCommon } from './worldrendererCommon'
 import { defaultWorldRendererConfig } from '../graphicsBackend/config'
+import { defaultPerformanceInstabilityFactors } from '../performanceMonitor'
 import { getInitialPlayerState } from '../playerState/playerState'
 import type { DisplayWorldOptions, GraphicsInitOptions } from '../graphicsBackend/types'
 
@@ -45,16 +46,18 @@ class TestWorldRenderer extends WorldRendererCommon {
   updateCamera() {}
   render() {}
   updateShowChunksBorder() {}
+  updatePlayerEntity() {}
+  worldStop() {}
 }
 
 function createRenderer() {
   const rendererState = proxy({
     world: {
-      chunksLoaded: new Set<string>(),
-      heightmaps: new Map<string, Int16Array>(),
+      chunksLoaded: {} as Record<string, true>,
+      heightmaps: {} as Record<string, Int16Array>,
       allChunksLoaded: false,
       mesherWork: false,
-      instabilityFactors: {},
+      instabilityFactors: defaultPerformanceInstabilityFactors(),
       intersectMedia: null,
     },
     renderer: '',
@@ -73,6 +76,7 @@ function createRenderer() {
       avgRenderTime: 0,
       world: {
         chunksLoaded: new Set<string>(),
+        chunksLoadedCount: 0,
         chunksTotalNumber: 0,
         chunksFullInfo: '',
       },
@@ -93,7 +97,7 @@ function createRenderer() {
     },
   }
 
-  const renderer = new TestWorldRenderer(displayOptions.resourcesManager, displayOptions, initOptions)
+  const renderer = new TestWorldRenderer(displayOptions.resourcesManager, displayOptions as DisplayWorldOptions, initOptions)
   renderer.active = true
   renderer.workers = [{ postMessage: vi.fn() }, { postMessage: vi.fn() }]
   renderer.viewDistance = 16

package/src/lib/worldrendererCommon.ts

@@ -1443,7 +1443,7 @@ export const initMesherWorker = (onGotMessage: (data: any) => void, workerName =
 let mesherMcDataTintsMissingWarned = false
 
 export const meshersSendMcData = (workers: Worker[], version: string, mcDataKeys = dynamicMcDataFiles, mcDataFull: IndexedData) => {
-  const mcData = {
+  const mcData: { version: IndexedData['version']; tints?: unknown; [key: string]: unknown } = {
     version: JSON.parse(JSON.stringify(mcDataFull.version))
   }
   for (const [finalKey, sourceKey] of Object.entries(mcDataKeys)) {

package/src/three/bannerRenderer.ts

@@ -270,7 +270,10 @@ export function createBannerMesh(
     mesh.position.set(clothXOffset, clothYOffset, clothZPosition + thickness / 2 + 0.004)
   }
 
-  const group = new THREE.Group() as THREE.Group & { bannerTexture?: THREE.Texture }
+  const group = new THREE.Group() as THREE.Group & {
+    bannerTexture?: THREE.Texture
+    bannerMaterial?: THREE.MeshBasicMaterial
+  }
   group.rotation.set(
     0,
     -THREE.MathUtils.degToRad(rotation * (isWall ? 90 : 45 / 2)),

package/src/three/chunkMeshManager.ts

@@ -1,5 +1,4 @@
 //@ts-nocheck
-import PrismarineChatLoader from 'prismarine-chat'
 import * as THREE from 'three'
 import * as nbt from 'prismarine-nbt'
 import { Vec3 } from 'vec3'
@@ -20,13 +19,12 @@ import {
   sectionAabbIntersectsRay,
   type ShaderSectionRaycastEntry,
 } from './sectionRaycastAabb'
-import { chunkPos } from '../lib/simpleUtils'
-import { renderSign } from '../sign-renderer'
 import { getMesh } from './entity/EntityMesh'
 import type { WorldRendererThree } from './worldRendererThree'
 import { armorModel } from './entity/armorModels'
 import { disposeObject } from './threeJsUtils'
 import { getBannerTexture, createBannerMesh, releaseBannerTexture } from './bannerRenderer'
+import { getSignTexture, releaseSignTexture, disposeAllSignTextures } from './signTextureCache'
 import { BlockEntityLightRegistry } from '../lib/blockEntityLightRegistry'
 
 export interface ChunkMeshPool {
@@ -1348,8 +1346,12 @@ export class ChunkMeshManager {
         sectionObject.shaderMesh = undefined
       }
       delete sectionObject.deferredShaderCubes
-      // Dispose signs and heads containers
+      // Release shared sign textures (refcount) before disposing meshes
       if (sectionObject.signsContainer) {
+        for (const child of sectionObject.signsContainer.children) {
+          const sign = child as THREE.Group & { signTexture?: THREE.Texture }
+          if (sign.signTexture) releaseSignTexture(sign.signTexture)
+        }
         this.disposeContainer(sectionObject.signsContainer, false)
       }
       if (sectionObject.headsContainer) {
@@ -1473,16 +1475,6 @@ export class ChunkMeshManager {
     }
   }
 
-  /**
-   * Forward to {@link SignHeadsRenderer.cleanChunkTextures} so callers in
-   * `WorldRendererThree` (which historically owned the sign-texture cache)
-   * can invalidate cached sign textures when a section is marked dirty,
-   * without reaching into the manager's private members.
-   */
-  cleanSignChunkTextures (x: number, z: number) {
-    this.signHeadsRenderer.cleanChunkTextures(x, z)
-  }
-
   /**
    * Get mesh for section if it exists
    */
@@ -1923,21 +1915,12 @@ export class ChunkMeshManager {
 }
 
 
-type SignTextureCacheEntry = { tex: THREE.Texture, signature: string }
-
 class SignHeadsRenderer {
-  chunkTextures = new Map<string, { [pos: string]: SignTextureCacheEntry }>()
-
   constructor (public worldRendererThree: WorldRendererThree) {
   }
 
   dispose () {
-    for (const [, textures] of this.chunkTextures) {
-      for (const key of Object.keys(textures)) {
-        textures[key]!.tex.dispose()
-      }
-    }
-    this.chunkTextures.clear()
+    disposeAllSignTextures()
   }
 
   renderHead (position: Vec3, rotation: number, isWall: boolean, blockEntity) {
@@ -1981,18 +1964,10 @@ class SignHeadsRenderer {
   }
 
   renderSign (position: Vec3, rotation: number, isWall: boolean, isHanging: boolean, blockEntity) {
-    const tex = this.getSignTexture(position, blockEntity, isHanging)
+    const tex = getSignTexture(this.worldRendererThree, blockEntity, isHanging)
 
     if (!tex) return
 
-    // todo implement
-    // const key = JSON.stringify({ position, rotation, isWall })
-    // if (this.signsCache.has(key)) {
-    //   console.log('cached', key)
-    // } else {
-    //   this.signsCache.set(key, tex)
-    // }
-
     const mesh = new THREE.Mesh(new THREE.PlaneGeometry(1, 1), new THREE.MeshBasicMaterial({ map: tex, transparent: true }))
     mesh.renderOrder = 999
 
@@ -2008,13 +1983,14 @@ class SignHeadsRenderer {
       mesh.position.set(0, 0, thickness / 2 + 0.0001)
     }
 
-    const group = new THREE.Group()
+    const group = new THREE.Group() as THREE.Group & { signTexture?: THREE.Texture }
     group.rotation.set(
       0,
       -THREE.MathUtils.degToRad(rotation * (isWall ? 90 : 45 / 2)),
       0
     )
     group.add(mesh)
+    group.signTexture = tex
     const height = (isHanging ? 10 : 8) / 16
     const heightOffset = (isHanging ? 0 : isWall ? 4.333 : 9.333) / 16
     const textPosition = height / 2 + heightOffset
@@ -2022,47 +1998,4 @@ class SignHeadsRenderer {
     group.position.set(position.x + 0.5, position.y + textPosition, position.z + 0.5)
     return group
   }
-
-  getSignTexture (position: Vec3, blockEntity, isHanging, backSide = false) {
-    const chunk = chunkPos(position)
-    let textures = this.chunkTextures.get(`${chunk[0]},${chunk[1]}`)
-    if (!textures) {
-      textures = {}
-      this.chunkTextures.set(`${chunk[0]},${chunk[1]}`, textures)
-    }
-    const texturekey = `${position.x},${position.y},${position.z}`
-    const signature = JSON.stringify(blockEntity) + '|' + isHanging + '|' + backSide
-    const cached = textures[texturekey]
-    if (cached && cached.signature === signature) return cached.tex
-
-    if (cached?.tex) cached.tex.dispose()
-
-    const PrismarineChat = PrismarineChatLoader(this.worldRendererThree.version)
-    const canvas = renderSign(blockEntity, isHanging, PrismarineChat)
-    if (!canvas) return
-    const tex = new THREE.Texture(canvas)
-    tex.magFilter = THREE.NearestFilter
-    tex.minFilter = THREE.NearestFilter
-    tex.needsUpdate = true
-    textures[texturekey] = { tex, signature }
-    return tex
-  }
-
-  /**
-   * Dispose all cached sign textures for the chunk containing world coords
-   * (x, z). Called from `WorldRendererThree.cleanChunkTextures` so that
-   * re-meshes triggered by `setSectionDirty` (e.g. a player edits a sign)
-   * pick up fresh block-entity NBT instead of returning the stale cached
-   * texture from {@link SignHeadsRenderer.getSignTexture}.
-   */
-  cleanChunkTextures (x: number, z: number) {
-    const key = `${Math.floor(x / 16)},${Math.floor(z / 16)}`
-    const textures = this.chunkTextures.get(key)
-    if (!textures) return
-    const disposedKeys = Object.keys(textures)
-    for (const k of disposedKeys) {
-      textures[k]!.tex.dispose()
-      delete textures[k]
-    }
-  }
 }

package/src/three/entities.ts

@@ -552,7 +552,8 @@ export class Entities {
   currentSkinUrls = {} as Record<string, string>
 
   private isCanvasBlank(canvas: HTMLCanvasElement | OffscreenCanvas): boolean {
-    return !canvas.getContext('2d')
+    const ctx = canvas.getContext('2d') as CanvasRenderingContext2D | OffscreenCanvasRenderingContext2D | null
+    return !ctx
       ?.getImageData(0, 0, canvas.width, canvas.height).data
       .some(channel => channel !== 0)
   }

package/src/three/graphicsBackendBase.ts

@@ -69,7 +69,7 @@ export const getBackendMethods = (worldRenderer: WorldRendererThree): any => {
     // New method for updating skybox
     setSkyboxImage: worldRenderer.skyboxRenderer.setSkyboxImage.bind(worldRenderer.skyboxRenderer),
     // Rain methods
-    setRain: (newState: boolean) => worldRenderer.toggleModule('rain', newState),
+    setRain: worldRenderer.setRain.bind(worldRenderer),
     spawnBlockBreakParticles(x: number, y: number, z: number, blockName: string, floorMap: number[], biomeName?: string) {
       const module = worldRenderer.getModule<import('./modules/blockBreakParticles').BlockBreakParticlesModule>('blockBreakParticles')
       module?.spawnBlockBreakParticles(x, y, z, blockName, floorMap, biomeName)
@@ -145,6 +145,10 @@ export const createGraphicsBackendBase = () => {
   let frameTimingCollector: FrameTimingCollector | null = null
 
   const init = (initOptionsArg: GraphicsInitOptions, mainData?: ThreeRendererMainData) => {
+    if (initOptionsArg.hello) {
+      console.log('Thanks for using minecraft-renderer project: one of the most performant Minecraft world renderers for the web!')
+    }
+
     if (isWebWorker) {
       initOptions = restoreTransferred(initOptionsArg, initOptionsRestorers, globalThis as unknown as Worker)
     } else {
@@ -166,8 +170,8 @@ export const createGraphicsBackendBase = () => {
       worldRenderer.destroy()
       worldRenderer = null
       frameTimingCollector = null
-      ;(globalThis as any).world = undefined
-      ;(globalThis as any).frameTimingCollector = undefined
+        ; (globalThis as any).world = undefined
+        ; (globalThis as any).frameTimingCollector = undefined
     }
 
     if (menuBackgroundRenderer) {
@@ -202,8 +206,8 @@ export const createGraphicsBackendBase = () => {
       worldRenderer.destroy()
       worldRenderer = null
       frameTimingCollector = null
-      ;(globalThis as any).world = undefined
-      ;(globalThis as any).frameTimingCollector = undefined
+        ; (globalThis as any).world = undefined
+        ; (globalThis as any).frameTimingCollector = undefined
     }
 
     const displayOptionsRestorers = [ResourcesManager, WorldViewWorker]

package/src/three/itemMesh.ts

@@ -40,7 +40,7 @@ export function create3DItemMesh (
     throw new Error(`Invalid canvas dimensions: ${canvas.width}x${canvas.height}`)
   }
 
-  const ctx = canvas.getContext('2d')!
+  const ctx = canvas.getContext('2d') as CanvasRenderingContext2D | OffscreenCanvasRenderingContext2D
   const imageData = ctx.getImageData(0, 0, canvas.width, canvas.height)
   const { data } = imageData
 

package/src/three/modules/rain.ts

@@ -17,11 +17,6 @@ const FALL_SPEED_MAX = 24
 const HORIZONTAL_DRIFT = 1.2
 const RESPAWN_BELOW = -5
 
-const moduleOptions = {
-  particleCount: 2000,
-  speedFactor: 1,
-}
-
 export class RainModule implements RendererModuleController {
   private instancedMesh?: THREE.InstancedMesh
   private geometry?: THREE.BoxGeometry
@@ -32,8 +27,14 @@ export class RainModule implements RendererModuleController {
   private readonly tempPosition = new THREE.Vector3()
   private readonly tempQuaternion = new THREE.Quaternion()
   private readonly tempScale = new THREE.Vector3()
+  private readonly configUnsubs: Array<() => void> = []
 
-  constructor(private readonly worldRenderer: WorldRendererThree) { }
+  constructor(private readonly worldRenderer: WorldRendererThree) {
+    this.configUnsubs.push(
+      this.worldRenderer.onReactiveConfigUpdated('rainColor', () => this.syncRainAppearance()),
+      this.worldRenderer.onReactiveConfigUpdated('rainOpacity', () => this.syncRainAppearance()),
+    )
+  }
 
   enable(): void {
     if (this.enabled) return
@@ -42,6 +43,7 @@ export class RainModule implements RendererModuleController {
       this.createRain()
     } else {
       this.instancedMesh.visible = true
+      this.syncRainAppearance()
     }
   }
 
@@ -60,8 +62,6 @@ export class RainModule implements RendererModuleController {
   render?: (deltaTime: number) => void = (deltaTime) => {
     if (!this.enabled || !this.instancedMesh || !this.material) return
 
-    this.syncMaterialToSceneFog()
-
     const cameraPos = this.worldRenderer.getCameraPosition()
     this.instancedMesh.position.set(0, 0, 0)
 
@@ -126,6 +126,9 @@ export class RainModule implements RendererModuleController {
   }
 
   dispose(): void {
+    for (const unsub of this.configUnsubs) unsub()
+    this.configUnsubs.length = 0
+
     if (this.instancedMesh) {
       this.worldRenderer.scene.remove(this.instancedMesh)
     }
@@ -137,33 +140,31 @@ export class RainModule implements RendererModuleController {
     this.particles = []
   }
 
-  /** Match scene fog so rain fades with distance instead of a flat blue sheet. */
-  private syncMaterialToSceneFog(): void {
+  private syncRainAppearance(): void {
     if (!this.material) return
-    const fog = this.worldRenderer.scene.fog
-    if (fog instanceof THREE.Fog || fog instanceof THREE.FogExp2) {
-      this.material.color.copy(fog.color)
-    } else {
-      this.material.color.set(0xcc_dd_ee)
-    }
-    this.material.fog = true
+
+    const { rainColor, rainOpacity } = this.worldRenderer.worldRendererConfig
+    this.material.color.set(rainColor)
+    this.material.opacity = Math.max(0, Math.min(1, rainOpacity))
+    this.material.needsUpdate = true
   }
 
   private createRain(): void {
+    const { rainColor, rainOpacity } = this.worldRenderer.worldRendererConfig
+
     this.geometry = new THREE.BoxGeometry(0.03, 0.3, 0.03)
     this.material = new THREE.MeshBasicMaterial({
-      color: 0xcc_dd_ee,
+      color: rainColor,
       transparent: true,
-      opacity: 0.35,
+      opacity: Math.max(0, Math.min(1, rainOpacity)),
       // Must write depth so log-depth blocks occlude rain correctly (see cubeBlockShader).
       depthWrite: true,
-      fog: true,
+      fog: false,
     })
 
     this.instancedMesh = new THREE.InstancedMesh(this.geometry, this.material, PARTICLE_COUNT)
     this.instancedMesh.name = 'rain-particles'
     this.instancedMesh.frustumCulled = false
-    this.syncMaterialToSceneFog()
 
     const dummy = new THREE.Matrix4()
     const position = new THREE.Vector3()

package/src/three/modules/starfield.ts

@@ -26,8 +26,10 @@ class StarfieldMaterial extends THREE.ShaderMaterial {
         uniform float fade;
         varying vec3 vColor;
         void main() {
-          float opacity = 1.0;
-          gl_FragColor = vec4(vColor, 1.0);
+          // fade scales star brightness (0 = invisible). With additive blending this is
+          // the only way to dim stars — scene fog never reaches this shader. Driven by the
+          // rain state so stars disappear in rain like in vanilla.
+          gl_FragColor = vec4(vColor * fade, 1.0);
 
           #include <tonemapping_fragment>
           #include <${threeVersion >= 154 ? 'colorspace_fragment' : 'encodings_fragment'}>
@@ -41,6 +43,8 @@ export class StarfieldModule implements RendererModuleController {
   private timer = new THREE.Timer()
   private enabled = false
   private currentTime?: number
+  /** Current star brightness multiplier; lerps toward 0 while raining, 1 otherwise. */
+  private fade = 1
 
   constructor(private readonly worldRenderer: WorldRendererThree) { }
 
@@ -72,12 +76,20 @@ export class StarfieldModule implements RendererModuleController {
     return this.currentTime > nightTime && this.currentTime < morningStart
   }
 
-  render?: (deltaTime: number) => void = (_deltaTime) => {
+  render?: (deltaTime: number) => void = (deltaTime) => {
     if (!this.points) return
     this.points.position.set(0, 0, 0)
+
+    const material = this.points.material as StarfieldMaterial
     this.timer.update(performance.now())
-      ; (this.points.material as StarfieldMaterial).uniforms.time.value =
-        this.timer.getElapsed() * 0.2
+    material.uniforms.time.value = this.timer.getElapsed() * 0.2
+
+    // Fade stars out while raining (vanilla scales star brightness by 1 - rainLevel).
+    // isRaining is a boolean here, so ease toward the target instead of snapping.
+    const target = this.worldRenderer.worldRendererConfig.isRaining ? 0 : 1
+    const t = Math.min(1, deltaTime * 2)
+    this.fade += (target - this.fade) * t
+    material.uniforms.fade.value = this.fade
   }
 
   /**

package/src/three/signTextureCache.ts

@@ -0,0 +1,64 @@
+//@ts-nocheck
+import * as THREE from 'three'
+import PrismarineChatLoader from 'prismarine-chat'
+import { renderSign } from '../sign-renderer'
+import type { WorldRendererThree } from './worldRendererThree'
+
+const signTextureCache = new Map<string, { texture: THREE.Texture, refCount: number }>()
+
+// Build the key ONLY from fields that change rendered pixels, so two signs
+// with identical visible text share a texture even if other NBT differs.
+function createSignCacheKey (blockEntity: any, isHanging: boolean, backSide: boolean): string {
+  let lines: string[]
+  let color: string
+  if (blockEntity && 'front_text' in blockEntity) { // 1.20+
+    lines = blockEntity.front_text?.messages ?? []
+    color = blockEntity.front_text?.color || 'black'
+  } else { // legacy
+    lines = [blockEntity?.Text1, blockEntity?.Text2, blockEntity?.Text3, blockEntity?.Text4]
+    color = blockEntity?.Color || 'black'
+  }
+  // \0 separator: cannot appear in JSON text components, so no key collisions
+  return `${isHanging ? 1 : 0}|${backSide ? 1 : 0}|${color}|${lines.join('\0')}`
+}
+
+export function getSignTexture (
+  worldRenderer: WorldRendererThree,
+  blockEntity: any,
+  isHanging: boolean,
+  backSide = false
+): THREE.Texture | undefined {
+  const cacheKey = createSignCacheKey(blockEntity, isHanging, backSide)
+  const cached = signTextureCache.get(cacheKey)
+  if (cached) {
+    cached.refCount++
+    return cached.texture
+  }
+  const PrismarineChat = PrismarineChatLoader(worldRenderer.version)
+  const canvas = renderSign(blockEntity, isHanging, PrismarineChat)
+  if (!canvas) return undefined
+  const tex = new THREE.Texture(canvas)
+  tex.magFilter = THREE.NearestFilter
+  tex.minFilter = THREE.NearestFilter
+  tex.needsUpdate = true
+  signTextureCache.set(cacheKey, { texture: tex, refCount: 1 })
+  return tex
+}
+
+export function releaseSignTexture (texture: THREE.Texture): void {
+  for (const [key, cached] of signTextureCache.entries()) {
+    if (cached.texture === texture) {
+      cached.refCount--
+      if (cached.refCount <= 0) {
+        cached.texture.dispose()
+        signTextureCache.delete(key)
+      }
+      return
+    }
+  }
+}
+
+export function disposeAllSignTextures (): void {
+  for (const [, cached] of signTextureCache) cached.texture.dispose()
+  signTextureCache.clear()
+}