minecraft-renderer 0.1.45 → 0.1.46

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "minecraft-renderer",
-  "version": "0.1.45",
+  "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/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/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()