minecraft-renderer 0.1.44 → 0.1.46

package/package.json

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

package/src/graphicsBackend/config.ts

@@ -4,6 +4,7 @@
  */
 
 import { proxy } from 'valtio'
+import { defaultPerformanceInstabilityFactors } from '../performanceMonitor'
 import type {
   GraphicsBackendConfig,
   RendererReactiveState,
@@ -117,6 +118,7 @@ export const getDefaultRendererState = (): {
         heightmaps: new Map<string, Int16Array>(),
         allChunksLoaded: false,
         mesherWork: false,
+        instabilityFactors: defaultPerformanceInstabilityFactors(),
         intersectMedia: null
       },
       renderer: '...',

package/src/graphicsBackend/index.ts

@@ -9,3 +9,4 @@ export * from './types'
 export * from './config'
 export * from './playerState'
 export * from './appViewer'
+export * from '../performanceMonitor'

package/src/graphicsBackend/types.ts

@@ -23,6 +23,7 @@ export interface SoundSystem {
 }
 
 import type { MenuBackgroundOptions } from '../three/menuBackground/types'
+import type { PerformanceInstabilityFactors } from '../performanceMonitor'
 
 /** Graphics backend configuration */
 export interface GraphicsBackendConfig {
@@ -76,6 +77,8 @@ export interface RendererReactiveState {
     heightmaps: Map<string, Int16Array>
     allChunksLoaded: boolean
     mesherWork: boolean
+    /** Low-FPS / render instability factors (see `performanceMonitor`). */
+    instabilityFactors: PerformanceInstabilityFactors
     intersectMedia: any | null
   }
   renderer: string

package/src/mesher-shared/models.ts

@@ -6,6 +6,7 @@ import legacyJson from '../lib/preflatMap.json'
 import { BlockType } from '../playground/shared'
 import { World, BlockModelPartsResolved, WorldBlock as Block, WorldBlock, worldColumnKey } from './world'
 import { BlockElement, buildRotationMatrix, elemFaces, matmul3, matmulmat3, vecadd3, vecsub3 } from './modelsGeometryCommon'
+import { getSideShading, vertexLightFromAo } from './vertexShading'
 import { INVISIBLE_BLOCKS } from './worldConstants'
 import { MesherGeometryOutput, HighestBlockInfo } from './shared'
 import { collectBlockEntityMetadata } from './blockEntityMetadata'
@@ -51,6 +52,31 @@ function prepareTints(tints) {
 }
 
 const calculatedBlocksEntries = Object.entries(legacyJson.clientCalculatedBlocks)
+
+/**
+ * Block name + properties for model lookup. Only runs neighbor/preflat work when
+ * `world.preflat` (legacy); modern block-state worlds use `fromStateId` only.
+ */
+export function resolveBlockPropertiesForMeshing(
+  world: World | undefined,
+  cursor: Vec3,
+  blockProvider: WorldBlockProvider,
+  blockStateId: number,
+  PrismarineBlockCtor: { fromStateId: (id: number, biome: number) => Block }
+): { name: string, properties: Record<string, unknown> } {
+  if (world?.preflat) {
+    const block = world.getBlock(cursor, blockProvider, {})
+    if (block) {
+      let properties: Record<string, unknown> = { ...block.getProperties() }
+      const patch = preflatBlockCalculation(block, world, cursor)
+      if (patch) properties = { ...properties, ...patch }
+      return { name: block.name, properties }
+    }
+  }
+  const fromState = PrismarineBlockCtor.fromStateId(blockStateId, 1)
+  return { name: fromState.name, properties: fromState.getProperties() }
+}
+
 export function preflatBlockCalculation(block: Block, world: World, position: Vec3) {
   const type = calculatedBlocksEntries.find(([name, blocks]) => blocks.includes(block.name))?.[0]
   if (!type) return
@@ -398,13 +424,7 @@ function renderElement(world: World, cursor: Vec3, element: BlockElement, doAO:
     // 10%
     const { smoothLighting, shadingTheme, cardinalLight } = world.config
     const faceLight = world.getLight(neighborPos, undefined, undefined, block.name)
-    const sideShading = (shadingTheme === 'high-contrast')
-      ? (0.8 + 0.5 * Math.max(0, 0.66 * dir[0] + 0.66 * dir[1] + 0.33 * dir[2])) // old directional light behavior
-      : (
-          cardinalLight === 'nether'
-            ? (0.5 + Math.abs(0.1 * dir[0] + 0.4 * dir[1] + 0.3 * dir[2]))
-            : (0.75 + 0.25 * dir[1] + 0.05 * (Math.abs(dir[2]) - 3 * Math.abs(dir[0])))
-        )
+    const sideShading = getSideShading(dir, shadingTheme, cardinalLight)
     const baseLight = sideShading * faceLight / 15
     for (const pos of corners) {
       let vertex = [
@@ -478,10 +498,7 @@ function renderElement(world: World, cursor: Vec3, element: BlockElement, doAO:
         // TODO: correctly interpolate ao light based on pos (evaluate once for each corner of the block)
 
         const ao = (side1Block && side2Block) ? 0 : (3 - (side1Block + side2Block + cornerBlock))
-        const ao_bias = (shadingTheme === 'high-contrast') ? 0.25 : 0.4
-        const ao_scale = (shadingTheme === 'high-contrast') ? 0.25 : 0.2
-        // todo light should go upper on lower blocks
-        light = sideShading * (ao * ao_scale + ao_bias) * (cornerLightResult / 15)
+        light = vertexLightFromAo(ao, cornerLightResult, sideShading, shadingTheme)
         aos.push(ao)
 
         // Log AO and light for this corner (corner index is aos.length - 1)

package/src/mesher-shared/vertexShading.ts

@@ -0,0 +1,35 @@
+//@ts-nocheck
+import type { MesherConfig } from './shared'
+
+export type FaceDirection = readonly [number, number, number]
+
+/** Directional face darkening (matches legacy `renderElement` in models.ts). */
+export function getSideShading(
+  dir: FaceDirection,
+  shadingTheme: MesherConfig['shadingTheme'],
+  cardinalLight: MesherConfig['cardinalLight']
+): number {
+  if (shadingTheme === 'high-contrast') {
+    return 0.8 + 0.5 * Math.max(0, 0.66 * dir[0] + 0.66 * dir[1] + 0.33 * dir[2])
+  }
+  if (cardinalLight === 'nether') {
+    return 0.5 + Math.abs(0.1 * dir[0] + 0.4 * dir[1] + 0.3 * dir[2])
+  }
+  return 0.75 + 0.25 * dir[1] + 0.05 * (Math.abs(dir[2]) - 3 * Math.abs(dir[0]))
+}
+
+/** Per-vertex brightness from AO (0–3) and corner light (0–15). */
+export function vertexLightFromAo(
+  ao: number,
+  cornerLight15: number,
+  sideShading: number,
+  shadingTheme: MesherConfig['shadingTheme']
+): number {
+  const lightNorm = cornerLight15 / 15
+  if (shadingTheme === 'high-contrast') {
+    return sideShading * ((ao + 1) / 4) * lightNorm
+  }
+  const aoBias = 0.4
+  const aoScale = 0.2
+  return sideShading * (ao * aoScale + aoBias) * lightNorm
+}

package/src/performanceMonitor/PerformanceMonitor.ts

@@ -0,0 +1,77 @@
+//@ts-nocheck
+import {
+  CONSTANT_LONG_RENDER_FRACTION,
+  CONSTANT_LONG_RENDER_MIN_SAMPLES,
+  FAST_SCENE_WITHOUT_ENTITIES_MS,
+  HIGH_TEXTURE_COUNT,
+  LONG_RENDER_TIME_MS,
+  LOW_FPS_THRESHOLD,
+  RENDER_TIME_HISTORY_SIZE,
+  SLOW_ENTITIES_RENDER_MS,
+} from './constants'
+import type { FramePerformanceSample, PerformanceInstabilityFactors } from './types'
+
+/**
+ * Tracks render/FPS signals and writes instability factors into reactive state
+ * (alongside `mesherWork`).
+ */
+export class PerformanceMonitor {
+  private readonly renderTimeHistory: number[] = []
+
+  constructor(private readonly factors: PerformanceInstabilityFactors) {}
+
+  onFrame(sample: FramePerformanceSample): void {
+    this.pushRenderTime(sample.totalMs)
+    this.recompute(sample)
+  }
+
+  private pushRenderTime(ms: number): void {
+    this.renderTimeHistory.push(ms)
+    if (this.renderTimeHistory.length > RENDER_TIME_HISTORY_SIZE) {
+      this.renderTimeHistory.shift()
+    }
+  }
+
+  private recompute(sample: FramePerformanceSample): void {
+    const lowFps = sample.fps > 0 && sample.fps <= LOW_FPS_THRESHOLD
+    const sceneWithoutEntitiesMs = Math.max(0, sample.totalMs - sample.entitiesMs)
+
+    const longRenderTime = sample.totalMs >= LONG_RENDER_TIME_MS
+
+    const historyLen = this.renderTimeHistory.length
+    const longFrames = this.renderTimeHistory.filter(t => t >= LONG_RENDER_TIME_MS).length
+    const constantLongRenderTime =
+      historyLen >= CONSTANT_LONG_RENDER_MIN_SAMPLES &&
+      longFrames / historyLen >= CONSTANT_LONG_RENDER_FRACTION
+
+    const tooManyTextures = sample.loadedTextureCount >= HIGH_TEXTURE_COUNT
+
+    const tooManyEntities =
+      lowFps &&
+      sample.entitiesMs >= SLOW_ENTITIES_RENDER_MS &&
+      sceneWithoutEntitiesMs <= FAST_SCENE_WITHOUT_ENTITIES_MS
+
+    const hasKnownCause =
+      longRenderTime ||
+      constantLongRenderTime ||
+      tooManyEntities ||
+      tooManyTextures
+
+    const unknownReason = lowFps && !hasKnownCause
+
+    this.factors.longRenderTime = longRenderTime
+    this.factors.constantLongRenderTime = constantLongRenderTime
+    this.factors.tooManyEntities = tooManyEntities
+    this.factors.tooManyTextures = tooManyTextures
+    this.factors.unknownReason = unknownReason
+  }
+
+  reset(): void {
+    this.renderTimeHistory.length = 0
+    this.factors.longRenderTime = false
+    this.factors.constantLongRenderTime = false
+    this.factors.tooManyEntities = false
+    this.factors.tooManyTextures = false
+    this.factors.unknownReason = false
+  }
+}

package/src/performanceMonitor/constants.ts

@@ -0,0 +1,24 @@
+//@ts-nocheck
+/** Recent frame exceeded this → `longRenderTime`. */
+export const LONG_RENDER_TIME_MS = 30
+
+/** Scene pass without entities faster than this → candidate for entity bottleneck. */
+export const FAST_SCENE_WITHOUT_ENTITIES_MS = 20
+
+/** Entity pass slower than this (with low FPS) → `tooManyEntities`. */
+export const SLOW_ENTITIES_RENDER_MS = 8
+
+/** FPS at or below this is treated as low performance. */
+export const LOW_FPS_THRESHOLD = 45
+
+/** Loaded WebGL textures at or above this → `tooManyTextures` (labels, signs, iOS). */
+export const HIGH_TEXTURE_COUNT = 100
+
+/** Ring buffer length for sustained render-time analysis. */
+export const RENDER_TIME_HISTORY_SIZE = 24
+
+/** Fraction of recent frames over `LONG_RENDER_TIME_MS` → `constantLongRenderTime`. */
+export const CONSTANT_LONG_RENDER_FRACTION = 0.65
+
+/** Minimum frames in history before `constantLongRenderTime` can trigger. */
+export const CONSTANT_LONG_RENDER_MIN_SAMPLES = 8

package/src/performanceMonitor/formatPerformanceFactorsDebug.ts

@@ -0,0 +1,16 @@
+//@ts-nocheck
+import type { PerformanceInstabilityFactors } from './types'
+
+const FACTOR_CODES: Array<{ key: keyof PerformanceInstabilityFactors, code: string }> = [
+  { key: 'longRenderTime', code: 'LR' },
+  { key: 'constantLongRenderTime', code: 'CLR' },
+  { key: 'tooManyEntities', code: 'ENT' },
+  { key: 'tooManyTextures', code: 'TEX' },
+  { key: 'unknownReason', code: 'UNK' },
+]
+
+/** Compact debug overlay fragment, e.g. `LR+ENT` or empty string. */
+export function formatPerformanceFactorsDebug(factors: PerformanceInstabilityFactors): string {
+  const active = FACTOR_CODES.filter(({ key }) => factors[key]).map(({ code }) => code)
+  return active.length > 0 ? active.join('+') : ''
+}

package/src/performanceMonitor/index.ts

@@ -0,0 +1,10 @@
+//@ts-nocheck
+export type { FramePerformanceSample, PerformanceInstabilityFactors } from './types'
+export { defaultPerformanceInstabilityFactors } from './types'
+export {
+  LONG_RENDER_TIME_MS,
+  LOW_FPS_THRESHOLD,
+  HIGH_TEXTURE_COUNT,
+} from './constants'
+export { PerformanceMonitor } from './PerformanceMonitor'
+export { formatPerformanceFactorsDebug } from './formatPerformanceFactorsDebug'

package/src/performanceMonitor/types.ts

@@ -0,0 +1,27 @@
+//@ts-nocheck
+/** Low-FPS / instability factors written to reactive renderer state. */
+export interface PerformanceInstabilityFactors {
+  longRenderTime: boolean
+  constantLongRenderTime: boolean
+  tooManyEntities: boolean
+  tooManyTextures: boolean
+  unknownReason: boolean
+}
+
+export const defaultPerformanceInstabilityFactors = (): PerformanceInstabilityFactors => ({
+  longRenderTime: false,
+  constantLongRenderTime: false,
+  tooManyEntities: false,
+  tooManyTextures: false,
+  unknownReason: false,
+})
+
+export interface FramePerformanceSample {
+  /** Full `WorldRendererThree.render()` duration in ms. */
+  totalMs: number
+  /** Time spent in `entities.render()` this frame (0 if skipped). */
+  entitiesMs: number
+  loadedTextureCount: number
+  /** FPS from the last completed 1s window (0 before first sample). */
+  fps: number
+}

package/src/three/modules/rain.ts

@@ -58,7 +58,9 @@ export class RainModule implements RendererModuleController {
   }
 
   render?: (deltaTime: number) => void = (deltaTime) => {
-    if (!this.enabled || !this.instancedMesh) return
+    if (!this.enabled || !this.instancedMesh || !this.material) return
+
+    this.syncMaterialToSceneFog()
 
     const cameraPos = this.worldRenderer.getCameraPosition()
     this.instancedMesh.position.set(0, 0, 0)
@@ -135,16 +137,32 @@ export class RainModule implements RendererModuleController {
     this.particles = []
   }
 
+  /** Match scene fog so rain fades with distance instead of a flat blue sheet. */
+  private syncMaterialToSceneFog(): 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
+  }
+
   private createRain(): void {
     this.geometry = new THREE.BoxGeometry(0.03, 0.3, 0.03)
     this.material = new THREE.MeshBasicMaterial({
-      color: 0x44_66_99,
+      color: 0xcc_dd_ee,
       transparent: true,
-      opacity: 0.6,
+      opacity: 0.35,
+      depthWrite: false,
+      fog: true,
     })
 
     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/worldRendererThree.ts

@@ -36,6 +36,7 @@ import { downloadWorldGeometry } from './worldGeometryExport'
 import { ChunkMeshManager } from './chunkMeshManager'
 import type { RendererModuleManifest, RegisteredModule, RendererModuleController } from './rendererModuleSystem'
 import { BUILTIN_MODULES } from './modules/index'
+import { formatPerformanceFactorsDebug, PerformanceMonitor } from '../performanceMonitor'
 
 type SectionKey = string
 
@@ -57,6 +58,7 @@ export class WorldRendererThree extends WorldRendererCommon {
   ambientLight = new THREE.AmbientLight(0xcc_cc_cc)
   directionalLight = new THREE.DirectionalLight(0xff_ff_ff, 0.5)
   entities = new Entities(this, (globalThis as any).mcData)
+  performanceMonitor!: PerformanceMonitor
   cameraGroupVr?: THREE.Object3D
   material = new THREE.MeshBasicMaterial({ vertexColors: true, transparent: true, alphaTest: 0.1 })
   itemsTexture!: THREE.Texture
@@ -154,6 +156,8 @@ export class WorldRendererThree extends WorldRendererCommon {
     if (!displayOptions.resourcesManager) throw new Error('resourcesManager is required in displayOptions')
     super(displayOptions.resourcesManager, displayOptions, initOptions)
 
+    this.performanceMonitor = new PerformanceMonitor(this.reactiveState.world.instabilityFactors)
+
     this.renderer = renderer
     displayOptions.rendererState.renderer = WorldRendererThree.getRendererInfo(renderer) ?? '...'
 
@@ -713,7 +717,10 @@ export class WorldRendererThree extends WorldRendererCommon {
         text += `B: ${formatCompact(this.blocksRendered)} `
         text += `MEM: ${this.chunkMeshManager.getEstimatedMemoryUsage().total} `
         const poolStats = this.chunkMeshManager.getStats()
-        text += `POOL: ${poolStats.activeCount}/${poolStats.poolSize}`
+        text += `POOL: ${poolStats.activeCount}/${poolStats.poolSize} `
+        const pf = formatPerformanceFactorsDebug(this.reactiveState.world.instabilityFactors)
+        if (pf) text += `PF: ${pf} `
+        // entities can be seen in F3
         pane.updateText(text)
         this.backendInfoReport = text
       }
@@ -1201,8 +1208,11 @@ export class WorldRendererThree extends WorldRendererCommon {
       this.camera.updateProjectionMatrix()
     }
 
+    let entitiesRenderMs = 0
     if (!this.reactiveDebugParams.disableEntities) {
+      const entitiesStart = performance.now()
       this.entities.render()
+      entitiesRenderMs = performance.now() - entitiesStart
     }
 
     // eslint-disable-next-line @typescript-eslint/non-nullable-type-assertion-style
@@ -1243,6 +1253,13 @@ export class WorldRendererThree extends WorldRendererCommon {
     this.renderTimeAvgCount++
     this.renderTimeAvg = ((this.renderTimeAvg * (this.renderTimeAvgCount - 1)) + totalTime) / this.renderTimeAvgCount
     this.renderTimeMax = Math.max(this.renderTimeMax, totalTime)
+
+    this.performanceMonitor.onFrame({
+      totalMs: totalTime,
+      entitiesMs: entitiesRenderMs,
+      loadedTextureCount: this.renderer.info.memory.textures,
+      fps: this.lastFps,
+    })
   }
 
   renderHead(position: Vec3, rotation: number, isWall: boolean, blockEntity) {
@@ -1450,6 +1467,7 @@ export class WorldRendererThree extends WorldRendererCommon {
   }
 
   destroy(): void {
+    this.performanceMonitor?.reset()
     this.pendingSectionUpdates.clear()
     this.pendingSectionBufferStartTimes.clear()
     this.chunkMeshManager.dispose()

package/src/wasm-mesher/bridge/render-from-wasm.ts

@@ -13,6 +13,8 @@ import { elemFaces, buildRotationMatrix, matmul3, matmulmat3, vecadd3, vecsub3 }
 import type { ExportedWorldGeometry, ExportedSection } from '../../three/worldGeometryExport'
 import type { MesherGeometryOutput } from '../../mesher-shared/shared'
 import type { World } from '../../mesher-shared/world'
+import { resolveBlockPropertiesForMeshing } from '../../mesher-shared/models'
+import { getSideShading, vertexLightFromAo } from '../../mesher-shared/vertexShading'
 
 // Handle both default and named export
 const worldBlockProvider = (worldBlockProviderModule as any).default || worldBlockProviderModule
@@ -134,6 +136,18 @@ export function extractColumnHeightmap(
   return out
 }
 
+function computeMesherVertexLight(
+  world: World | undefined,
+  ao: number,
+  cornerLight15: number,
+  faceDir: [number, number, number]
+): number {
+  const shadingTheme = world?.config.shadingTheme ?? 'high-contrast'
+  const cardinalLight = world?.config.cardinalLight ?? 'default'
+  const sideShading = getSideShading(faceDir, shadingTheme, cardinalLight)
+  return vertexLightFromAo(ao, cornerLight15, sideShading, shadingTheme)
+}
+
 /**
  * Get or create cached block model with precomputed matrices
  */
@@ -141,10 +155,32 @@ function getCachedBlockModel(
   blockStateId: number,
   version: string,
   blockProvider: WorldBlockProvider,
-  PrismarineBlock: any
+  PrismarineBlock: any,
+  world?: World,
+  blockPos?: { x: number, y: number, z: number }
 ): CachedBlockModel | null {
-  // Use a module-level cache
-  const cacheKey = `${version}:${blockStateId}`
+  const usePreflat = !!(world?.preflat && blockPos)
+  let blockName: string
+  let blockProps: Record<string, unknown>
+  if (usePreflat) {
+    const resolved = resolveBlockPropertiesForMeshing(
+      world,
+      new Vec3(blockPos!.x, blockPos!.y, blockPos!.z),
+      blockProvider,
+      blockStateId,
+      PrismarineBlock
+    )
+    blockName = resolved.name
+    blockProps = resolved.properties
+  } else {
+    const blockObj = PrismarineBlock.fromStateId(blockStateId, 1)
+    blockName = blockObj.name
+    blockProps = blockObj.getProperties()
+  }
+
+  const cacheKey = usePreflat
+    ? `${version}:${blockStateId}:${blockName}:${JSON.stringify(blockProps)}`
+    : `${version}:${blockStateId}`
   if (!(globalThis as any).__wasmBlockModelCache) {
     (globalThis as any).__wasmBlockModelCache = new Map()
   }
@@ -156,11 +192,13 @@ function getCachedBlockModel(
 
   try {
     const blockObj = PrismarineBlock.fromStateId(blockStateId, 1)
-    const blockName = blockObj.name
-    const blockProps = blockObj.getProperties()
+    if (!usePreflat) {
+      blockName = blockObj.name
+      blockProps = blockObj.getProperties()
+    }
 
     const models = blockProvider.getAllResolvedModels0_1(
-      { name: blockName, properties: blockProps },
+      { name: blockName, properties: blockProps as Record<string, string | number | boolean> },
       false
     )
 
@@ -505,7 +543,14 @@ export function renderWasmOutputToGeometry(
       }
     }
 
-    const cachedModel = getCachedBlockModel(blockStateId, version, blockProvider, PrismarineBlock)
+    const cachedModel = getCachedBlockModel(
+      blockStateId,
+      version,
+      blockProvider,
+      PrismarineBlock,
+      world,
+      { x: bx, y: by, z: bz }
+    )
     if (!cachedModel) continue
 
     if (false) {
@@ -654,10 +699,9 @@ export function renderWasmOutputToGeometry(
             // But WASM light calculation seems to return 0.0, so we need to handle that
             // In the test case, TypeScript gets baseLight = 1.0 (full brightness)
             // So we should use 1.0 as the base light value when WASM returns 0
-            const baseLight = lightValues[cornerIdx]
-            const cornerLightResult = baseLight * 15
-
-            const light = (ao + 1) / 4 * (cornerLightResult / 15)
+            const cornerLight15 = (lightValues[cornerIdx] ?? 1) * 15
+            const faceDir = transformedDir as [number, number, number]
+            const light = computeMesherVertexLight(world, ao, cornerLight15, faceDir)
 
             colors.push(tint[0] * light, tint[1] * light, tint[2] * light)
 
@@ -907,7 +951,8 @@ export function renderWasmOutputToGeometry(
             }
 
             if (doAO) {
-              light = (ao + 1) / 4 * (cornerLightResult / 15)
+              const faceDir = transformedDirI as [number, number, number]
+              light = computeMesherVertexLight(world, ao, cornerLightResult, faceDir)
             }
 
             colors.push(tint[0] * light!, tint[1] * light!, tint[2] * light!)