minecraft-renderer 0.1.74 → 0.1.76

package/package.json

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

package/src/lib/utils/skins.ts

@@ -8,6 +8,15 @@ import { createCanvas, loadImageFromUrl } from '../utils'
 export const stevePngUrl = stevePng
 export const steveTexture = loadThreeJsTextureFromUrl(stevePngUrl)
 
+const SKIN_TEXTURE_WIDTHS = [64, 128, 256, 512, 1024] as const
+
+/** Minecraft skin sheets: WxW or Wx(W/2) at standard power-of-two widths. */
+export const isLikelySkinImageSize = (width: number, height: number) => {
+  if (!Number.isFinite(width) || !Number.isFinite(height) || width <= 0 || height <= 0) return false
+  if (!(SKIN_TEXTURE_WIDTHS as readonly number[]).includes(width)) return false
+  return height === width || height === width / 2
+}
+
 const config = {
   apiEnabled: true,
 }

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 {
@@ -74,6 +72,21 @@ export interface SectionObject extends THREE.Group {
   _waitingForChunkDisplay?: boolean
 }
 
+/** Live vs allocated stats for one global GPU buffer (faces or legacy quads). */
+export type GlobalBufferSlotStats = {
+  used: number
+  capacity: number
+  sections: number
+  usedBytes: number
+  capacityBytes: number
+}
+
+export type GlobalBufferStats = {
+  shaderFaces: GlobalBufferSlotStats | null
+  legacyOpaque: GlobalBufferSlotStats | null
+  legacyBlend: GlobalBufferSlotStats | null
+}
+
 export class ChunkMeshManager {
   private static readonly REBASE_THRESHOLD = 65536
 
@@ -1348,8 +1361,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 +1490,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
    */
@@ -1521,6 +1528,34 @@ export class ChunkMeshManager {
   /**
    * Get pool statistics
    */
+  getGlobalBufferStats (): GlobalBufferStats {
+    const snapshotLegacy = (buffer: GlobalLegacyBuffer | null): GlobalBufferSlotStats | null => {
+      if (!buffer) return null
+      return {
+        used: buffer.getHighWatermark(),
+        capacity: buffer.getCapacityQuads(),
+        sections: buffer.getSectionCount(),
+        usedBytes: buffer.getUsedMemoryBytes(),
+        capacityBytes: buffer.getMemoryBytes(),
+      }
+    }
+
+    const cubes = this.globalBlockBuffer
+    return {
+      shaderFaces: cubes
+        ? {
+            used: cubes.getHighWatermark(),
+            capacity: cubes.getCapacityFaces(),
+            sections: cubes.getSectionCount(),
+            usedBytes: cubes.getUsedMemoryBytes(),
+            capacityBytes: cubes.getMemoryBytes(),
+          }
+        : null,
+      legacyOpaque: snapshotLegacy(this.globalLegacyBuffer),
+      legacyBlend: snapshotLegacy(this.globalLegacyBlendBuffer),
+    }
+  }
+
   getStats () {
     const freeCount = this.meshPool.filter(entry => !entry.inUse).length
     const hitRate = this.hits + this.misses > 0 ? (this.hits / (this.hits + this.misses) * 100).toFixed(1) : '0'
@@ -1923,21 +1958,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 +2007,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 +2026,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 +2041,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

@@ -635,6 +635,17 @@ export class Entities {
     }
   }
 
+  /** Local preview override: hand + player model until server skin refresh or reconnect. */
+  async applyTemporaryPlayerSkinOverride (
+    skinUrl: string,
+    entityId: string | number,
+    username?: string,
+    uuid?: string
+  ) {
+    this.worldRenderer.playerStateReactive.playerSkin = skinUrl
+    await this.updatePlayerSkin(entityId, username, uuid, skinUrl, undefined)
+  }
+
   private async loadAndApplySkin(entityId: string | number, skinUrl: string, renderEars: boolean) {
     let playerObject = this.getPlayerObject(entityId)
     if (!playerObject) return

package/src/three/globalBlockBuffer.ts

@@ -35,6 +35,9 @@ const MAX_UPLOAD_FACES_PER_FRAME = 15_000   // face-indexed budget (chunksStorag
 const FRAGMENTATION_THRESHOLD = 0.25
 const EMPTY_W2 = packWord2Empty()
 
+/** CPU bytes per instanced cube face (a_w0..a_w3). */
+export const SHADER_CUBE_BYTES_PER_FACE = 16
+
 type PendingMove = { key: string, oldStart: number, newStart: number, count: number }
 
 export type GlobalBlockBufferShaderData = {
@@ -162,6 +165,22 @@ export class GlobalBlockBuffer {
     return this.highWatermark
   }
 
+  getCapacityFaces (): number {
+    return this.capacityFaces
+  }
+
+  getSectionCount (): number {
+    return this.sectionSlots.size
+  }
+
+  getMemoryBytes (): number {
+    return this.capacityFaces * SHADER_CUBE_BYTES_PER_FACE
+  }
+
+  getUsedMemoryBytes (): number {
+    return this.highWatermark * SHADER_CUBE_BYTES_PER_FACE
+  }
+
   hasPendingUploads (): boolean {
     return this.pendingRanges.length > 0
   }

package/src/three/globalLegacyBuffer.ts

@@ -12,6 +12,11 @@ const DEFAULT_INITIAL_CAPACITY_QUADS = 128_000
 const DEFAULT_GROWTH_INCREMENT_QUADS = 128_000
 const MAX_UPLOAD_QUADS_PER_FRAME = 5_000
 
+/** CPU bytes per allocated quad slot (all legacy vertex/index attrs). */
+export const LEGACY_BYTES_PER_QUAD =
+  VERTS_PER_QUAD * (FLOATS_PER_VERT * 3 + FLOATS_PER_LIGHT_VERT * 2 + FLOATS_PER_UV_VERT) * 4
+  + INDICES_PER_QUAD * 4
+
 export const FULL_DRAW_VISIBLE_FRACTION = 0.75
 export const SPAN_GAP_TOLERANCE_QUADS = 256
 export const MAX_OPAQUE_SPANS = 64
@@ -475,10 +480,24 @@ export class GlobalLegacyBuffer {
     return out
   }
 
+  getHighWatermark (): number {
+    return this.highWatermark
+  }
+
+  getCapacityQuads (): number {
+    return this.capacityQuads
+  }
+
+  getSectionCount (): number {
+    return this.sectionSlots.size
+  }
+
   getMemoryBytes (): number {
-    const verts = this.capacityQuads * VERTS_PER_QUAD
-    return verts * (FLOATS_PER_VERT * 3 + FLOATS_PER_LIGHT_VERT * 2 + FLOATS_PER_UV_VERT) * 4
-      + this.capacityQuads * INDICES_PER_QUAD * 4
+    return this.capacityQuads * LEGACY_BYTES_PER_QUAD
+  }
+
+  getUsedMemoryBytes (): number {
+    return this.highWatermark * LEGACY_BYTES_PER_QUAD
   }
 
   reset (): void {

package/src/three/graphicsBackendBase.ts

@@ -35,6 +35,7 @@ export const getBackendMethods = (worldRenderer: WorldRendererThree): any => {
     playEntityAnimation: worldRenderer.entities.playAnimation.bind(worldRenderer.entities),
     damageEntity: worldRenderer.entities.handleDamageEvent.bind(worldRenderer.entities),
     updatePlayerSkin: worldRenderer.entities.updatePlayerSkin.bind(worldRenderer.entities),
+    applyTemporaryPlayerSkinOverride: worldRenderer.entities.applyTemporaryPlayerSkinOverride.bind(worldRenderer.entities),
     changeHandSwingingState: worldRenderer.changeHandSwingingState.bind(worldRenderer),
     getHighestBlocks: worldRenderer.getHighestBlocks.bind(worldRenderer),
     reloadWorld: worldRenderer.reloadWorld.bind(worldRenderer),

package/src/three/graphicsBackendSingleThread.ts

@@ -19,7 +19,7 @@ const createGraphicsBackendSingleThread: GraphicsBackendLoader = (initOptions: G
 }
 
 createGraphicsBackendSingleThread.id = 'threejs'
-createGraphicsBackendSingleThread.displayName = 'three.js Blocking Beta'
+createGraphicsBackendSingleThread.displayName = 'three.js Blocking'
 createGraphicsBackendSingleThread.description = 'Simple, old and stable main thread graphics backend providing balanced performance on top of WebGL2.'
 
 export default createGraphicsBackendSingleThread

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()
+}

package/src/three/tests/signTextureCache.test.ts

@@ -1,11 +1,6 @@
 //@ts-nocheck
 import { test, expect, vi, beforeEach } from 'vitest'
 import * as THREE from 'three'
-import { Vec3 } from 'vec3'
-
-vi.mock('../entity/EntityMesh', () => ({
-  getMesh: vi.fn(),
-}))
 
 const renderSignMock = vi.fn()
 vi.mock('../../sign-renderer', () => ({
@@ -16,25 +11,11 @@ vi.mock('prismarine-chat', () => ({
   default: () => () => ({}),
 }))
 
-import { ChunkMeshManager } from '../chunkMeshManager'
+import { getSignTexture, releaseSignTexture, disposeAllSignTextures } from '../signTextureCache'
 import type { WorldRendererThree } from '../worldRendererThree'
 
-function createManager (): ChunkMeshManager {
-  const scene = new THREE.Scene()
-  const material = new THREE.MeshBasicMaterial()
-  const worldRenderer = {
-    version: '1.20',
-    shaderCubeBlocksEnabled: () => false,
-    getModule: () => undefined,
-    sceneOrigin: {
-      track: () => {},
-      removeAndUntrack: () => {},
-      removeAndUntrackAll: () => {},
-    },
-    blockEntities: {},
-    worldRendererConfig: {},
-  } as unknown as WorldRendererThree
-  return new ChunkMeshManager(worldRenderer, scene, material, 256, 1)
+function createWorldRenderer (): WorldRendererThree {
+  return { version: '1.20' } as WorldRendererThree
 }
 
 function stubCanvas () {
@@ -44,40 +25,80 @@ function stubCanvas () {
 beforeEach(() => {
   renderSignMock.mockReset()
   renderSignMock.mockImplementation(() => stubCanvas())
+  disposeAllSignTextures()
 })
 
-test('getSignTexture: same blockEntity returns cached texture without re-render', () => {
-  const manager = createManager()
-  const signHeadsRenderer = (manager as unknown as { signHeadsRenderer: { getSignTexture: Function } }).signHeadsRenderer
-  const pos = new Vec3(10, 64, 10)
+test('getSignTexture: same content at different positions shares one texture', () => {
+  const wr = createWorldRenderer()
   const blockEntity = { Text1: '{"text":"Hello"}' }
 
-  const tex1 = signHeadsRenderer.getSignTexture(pos, blockEntity, false)
-  const tex2 = signHeadsRenderer.getSignTexture(pos, blockEntity, false)
+  const tex1 = getSignTexture(wr, blockEntity, false)
+  const tex2 = getSignTexture(wr, { ...blockEntity }, false)
 
   expect(tex1).toBeDefined()
   expect(tex2).toBe(tex1)
   expect(renderSignMock).toHaveBeenCalledTimes(1)
+})
+
+test('getSignTexture: different text yields different textures', () => {
+  const wr = createWorldRenderer()
 
-  manager.dispose()
+  const tex1 = getSignTexture(wr, { Text1: '{"text":"Hello"}' }, false)!
+  const tex2 = getSignTexture(wr, { Text1: '{"text":"World"}' }, false)!
+
+  expect(tex2).not.toBe(tex1)
+  expect(renderSignMock).toHaveBeenCalledTimes(2)
 })
 
-test('getSignTexture: changed blockEntity disposes old texture and renders anew', () => {
-  const manager = createManager()
-  const signHeadsRenderer = (manager as unknown as { signHeadsRenderer: { getSignTexture: Function } }).signHeadsRenderer
-  const pos = new Vec3(10, 64, 10)
+test('releaseSignTexture: partial release keeps texture in cache', () => {
+  const wr = createWorldRenderer()
   const blockEntity = { Text1: '{"text":"Hello"}' }
 
-  const tex1 = signHeadsRenderer.getSignTexture(pos, blockEntity, false)!
+  const tex1 = getSignTexture(wr, blockEntity, false)!
+  const tex2 = getSignTexture(wr, blockEntity, false)!
+  expect(tex1).toBe(tex2)
+
   const disposeSpy = vi.spyOn(tex1, 'dispose')
+  releaseSignTexture(tex1)
+
+  expect(disposeSpy).not.toHaveBeenCalled()
+  expect(getSignTexture(wr, blockEntity, false)).toBe(tex1)
+  expect(renderSignMock).toHaveBeenCalledTimes(1)
+})
 
-  const changed = { Text1: '{"text":"World"}' }
-  const tex2 = signHeadsRenderer.getSignTexture(pos, changed, false)
+test('releaseSignTexture: dispose at zero refcount removes cache entry', () => {
+  const wr = createWorldRenderer()
+  const blockEntity = { Text1: '{"text":"Hello"}' }
 
-  expect(tex2).toBeDefined()
-  expect(tex2).not.toBe(tex1)
+  const tex = getSignTexture(wr, blockEntity, false)!
+  const disposeSpy = vi.spyOn(tex, 'dispose')
+
+  releaseSignTexture(tex)
   expect(disposeSpy).toHaveBeenCalledTimes(1)
+
+  const tex2 = getSignTexture(wr, blockEntity, false)!
+  expect(tex2).not.toBe(tex)
   expect(renderSignMock).toHaveBeenCalledTimes(2)
+})
+
+test('getSignTexture: key ignores irrelevant NBT fields', () => {
+  const wr = createWorldRenderer()
+  const base = { Text1: '{"text":"Hello"}', Color: 'black' }
 
-  manager.dispose()
+  const tex1 = getSignTexture(wr, base, false)!
+  const tex2 = getSignTexture(wr, { ...base, GlowingText: 1, is_waxed: 1 }, false)!
+
+  expect(tex2).toBe(tex1)
+  expect(renderSignMock).toHaveBeenCalledTimes(1)
+})
+
+test('getSignTexture: isHanging is part of cache key', () => {
+  const wr = createWorldRenderer()
+  const blockEntity = { Text1: '{"text":"Hello"}' }
+
+  const standing = getSignTexture(wr, blockEntity, false)!
+  const hanging = getSignTexture(wr, blockEntity, true)!
+
+  expect(hanging).not.toBe(standing)
+  expect(renderSignMock).toHaveBeenCalledTimes(2)
 })