minecraft-renderer 0.1.45 → 0.1.47

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/documentRenderer.ts

@@ -13,20 +13,15 @@ import * as THREE from 'three'
 import Stats from 'stats.js'
 import StatsGl from 'stats-gl'
 import * as tween from '@tweenjs/tween.js'
-import type { GraphicsInitOptions } from '../graphicsBackend/types'
+import type { GraphicsBackendConfig, GraphicsInitOptions } from '../graphicsBackend/types'
+import { gpuPreferenceToWebGLPowerPreference } from '../three/menuBackground/defaultOptions'
 import { WorldRendererConfig } from '../graphicsBackend'
 
 // ============================================================================
 // Types (co-located with implementation)
 // ============================================================================
 
-export interface GraphicsBackendConfig {
-  fpsLimit?: number
-  powerPreference?: 'high-performance' | 'low-power'
-  statsVisible?: number
-  sceneBackground: string
-  timeoutRendering?: boolean
-}
+export type { GraphicsBackendConfig }
 
 export interface FrameTimingEvent {
   type: 'frameStart' | 'frameEnd' | 'cameraUpdate' | 'frameDisplay'
@@ -207,11 +202,12 @@ export class DocumentRenderer {
     }
 
     try {
+      const gpuPreference = initOptions.getRendererOptions?.()?.gpuPreference ?? 'default'
       this.renderer = new THREE.WebGLRenderer({
         canvas: this.canvas as HTMLCanvasElement,
         preserveDrawingBuffer: true,
         logarithmicDepthBuffer: true,
-        powerPreference: this.config.powerPreference
+        powerPreference: gpuPreferenceToWebGLPowerPreference(gpuPreference)
       })
     } catch (err: any) {
       initOptions.callbacks.displayCriticalError(

package/src/three/graphicsBackendBase.ts

@@ -162,8 +162,6 @@ export const createGraphicsBackendBase = () => {
         mergedOptions,
         !!process.env.SINGLE_FILE_BUILD_MODE
       )
-        ; (globalThis as any).menuBackgroundRenderer = menuBackgroundRenderer
-
       callModsMethod('menuBackgroundCreated', menuBackgroundRenderer)
       await menuBackgroundRenderer.start(mergedOptions)
       callModsMethod('menuBackgroundReady', menuBackgroundRenderer)
@@ -240,6 +238,7 @@ export const createGraphicsBackendBase = () => {
       documentRenderer!.setPaused(!rendering)
       if (worldRenderer) worldRenderer.renderingActive = rendering
     },
+    getMenuBackground: () => menuBackgroundRenderer ?? undefined,
     getDebugOverlay: () => ({
       get entitiesString() {
         return worldRenderer?.entities.getDebugString()

package/src/three/menuBackground/defaultOptions.ts

@@ -22,6 +22,19 @@ export type RendererOptionMeta = {
 
 export type RendererDefaultOptionKey = keyof typeof RENDERER_DEFAULT_OPTIONS
 
+export type RendererMesherPipeline = 'wasm' | 'legacy-js'
+
+export type RendererGpuPreference = 'default' | 'high-performance' | 'low-power'
+
+/** Maps stored `gpuPreference` to WebGL `powerPreference` (undefined = browser default). */
+export function gpuPreferenceToWebGLPowerPreference(
+  preference: RendererGpuPreference
+): 'high-performance' | 'low-power' | undefined {
+  if (preference === 'high-performance') return 'high-performance'
+  if (preference === 'low-power') return 'low-power'
+  return undefined
+}
+
 const MB = MENU_BACKGROUND_OPTION_DEFAULTS
 
 /** Default values for options owned by minecraft-renderer (spread into app `defaultOptions`). */
@@ -39,9 +52,52 @@ export const RENDERER_DEFAULT_OPTIONS = {
   menuBackgroundFuturisticBlockSpeed: MB.futuristicBlockSpeedPercent,
   rendererFuturisticReveal: false,
   rendererPerfDebugOverlay: false,
-  disableBlockEntityTextures: false
+  disableBlockEntityTextures: false,
+  rendererMesher: 'wasm' as RendererMesherPipeline,
+  showChunkBorders: false,
+  renderEntities: true,
+  renderDebug: 'basic' as 'none' | 'basic' | 'advanced',
+  frameLimit: false as number | false,
+  backgroundRendering: '20fps' as 'full' | '20fps' | '5fps',
+  vanillaLook: false,
+  smoothLighting: true,
+  newVersionsLighting: false,
+  vrSupport: true,
+  vrPageGameRendering: false,
+  clipWorldBelowY: undefined as number | undefined,
+  highlightBlockColor: 'auto' as 'auto' | 'blue' | 'classic',
+  loadPlayerSkins: true,
+  renderEars: true,
+  showHand: true,
+  viewBobbing: true,
+  dayCycleAndLighting: true,
+  keepChunksDistance: 1,
+  gpuPreference: 'default' as RendererGpuPreference
 } as const
 
+/** App options storage shape for renderer-owned keys. */
+export type RendererStorageOptions = typeof RENDERER_DEFAULT_OPTIONS
+
+/**
+ * Migrate persisted / legacy option keys into current {@link RENDERER_DEFAULT_OPTIONS} shape.
+ * Call when loading saved settings (safe to run on every load).
+ */
+export function migrateRendererOptions(saved: Record<string, unknown>): void {
+  if (saved.highPerformanceGpu) {
+    saved.gpuPreference = 'high-performance'
+    delete saved.highPerformanceGpu
+  }
+  if (saved.rendererMesher !== 'wasm' && saved.rendererMesher !== 'legacy-js') {
+    if (typeof saved.rendererWasmMesher === 'boolean') {
+      saved.rendererMesher = saved.rendererWasmMesher ? 'wasm' : 'legacy-js'
+    } else if (typeof saved.wasmExperimentalMesher === 'boolean') {
+      saved.rendererMesher = saved.wasmExperimentalMesher ? 'wasm' : 'legacy-js'
+    }
+  }
+  delete saved.wasmExperimentalMesher
+  delete saved.rendererWasmMesher
+}
+
 /** Settings UI metadata for {@link RENDERER_DEFAULT_OPTIONS} keys. */
 export const RENDERER_OPTIONS_META: Partial<Record<RendererDefaultOptionKey, RendererOptionMeta>> = {
   menuBackgroundMode: {
@@ -102,6 +158,83 @@ export const RENDERER_OPTIONS_META: Partial<Record<RendererDefaultOptionKey, Ren
   disableBlockEntityTextures: {
     text: 'Disable block entity textures',
     tooltip: 'Skips signs, banners, heads, maps, etc.'
+  },
+  rendererMesher: {
+    possibleValues: [['wasm', 'WASM'], ['legacy-js', 'Legacy JS']],
+    text: 'Mesher pipeline',
+    tooltip: 'WASM is faster. Use JS if WASM is not working. Requires reload.',
+    requiresRestart: true
+  },
+  showChunkBorders: {
+    text: 'Chunk borders'
+  },
+  renderEntities: {
+    text: 'Render entities'
+  },
+  renderDebug: {
+    possibleValues: ['advanced', 'basic', 'none']
+  },
+  frameLimit: {
+    text: 'Frame limit',
+    tooltip: 'false = VSync / unlimited when focused'
+  },
+  backgroundRendering: {
+    text: 'Background FPS limit',
+    possibleValues: [
+      ['full', 'NO'],
+      ['5fps', '5 FPS'],
+      ['20fps', '20 FPS']
+    ]
+  },
+  vanillaLook: {
+    text: 'Vanilla shading',
+    tooltip: 'On: Minecraft-style face shading. Off: higher-contrast client shading.'
+  },
+  smoothLighting: {},
+  newVersionsLighting: {
+    text: 'Lighting in newer versions'
+  },
+  vrSupport: {
+    text: 'VR support',
+    tooltip: 'Shows VR entry; does not force VR on.'
+  },
+  vrPageGameRendering: {
+    text: 'VR page game rendering'
+  },
+  clipWorldBelowY: {
+    text: 'Clip world below Y'
+  },
+  highlightBlockColor: {
+    possibleValues: [
+      ['auto', 'Auto'],
+      ['blue', 'Blue'],
+      ['classic', 'Classic']
+    ]
+  },
+  loadPlayerSkins: {},
+  renderEars: {
+    tooltip: 'Deadmau5 ears when the skin texture includes them'
+  },
+  showHand: {},
+  viewBobbing: {},
+  dayCycleAndLighting: {
+    text: 'Day cycle'
+  },
+  keepChunksDistance: {
+    text: 'Keep chunks distance',
+    tooltip: 'Extra distance before unloading chunks',
+    max: 5,
+    unit: ''
+  },
+  gpuPreference: {
+    text: 'GPU preference',
+    tooltip: 'WebGL power preference. Requires reload / backend restart to apply.',
+    requiresRestart: true,
+    possibleValues: [
+      ['default', 'Auto'],
+      ['high-performance', 'Dedicated'],
+      ['low-power', 'Low power']
+    ]
   }
 }
 
@@ -110,32 +243,57 @@ export const RENDERER_RENDER_GUI_SECTIONS: ReadonlyArray<{
   title: string
   keys: readonly RendererDefaultOptionKey[]
 }> = [
-  {
-    title: 'Menu background',
-    keys: [
-      'menuBackgroundMode',
-      'menuBackgroundMinecraftTextures',
-      'menuBackgroundFuturisticScene',
-      'menuBackgroundFuturisticCamera',
-      'menuBackgroundFuturisticBlockGroup',
-      'menuBackgroundFuturisticCameraSpeed',
-      'menuBackgroundFuturisticBlockSpeed'
-    ]
-  },
-  {
-    title: 'World rendering',
-    keys: [
-      'rendererWorldPerformance',
-      'starfieldRendering',
-      'defaultSkybox',
-      'disableBlockEntityTextures'
-    ]
-  },
-  {
-    title: 'Renderer debug',
-    keys: [
-      'rendererFuturisticReveal',
-      'rendererPerfDebugOverlay'
-    ]
-  }
-]
+    {
+      title: 'World rendering',
+      keys: [
+        'rendererWorldPerformance',
+        'starfieldRendering',
+        'defaultSkybox',
+        'disableBlockEntityTextures',
+        'showChunkBorders',
+        'renderEntities',
+        'smoothLighting',
+        'vanillaLook',
+        'newVersionsLighting',
+        'dayCycleAndLighting',
+        'loadPlayerSkins',
+        'renderEars',
+        'showHand',
+        'viewBobbing',
+        'keepChunksDistance',
+        'highlightBlockColor',
+        'clipWorldBelowY'
+      ]
+    },
+    {
+      title: 'Frame pacing',
+      keys: ['frameLimit', 'backgroundRendering', 'renderDebug', 'gpuPreference']
+    },
+    {
+      title: 'VR',
+      keys: ['vrSupport', 'vrPageGameRendering']
+    },
+    {
+      title: 'Menu background',
+      keys: [
+        'menuBackgroundMode',
+        'menuBackgroundMinecraftTextures',
+        'menuBackgroundFuturisticScene',
+        'menuBackgroundFuturisticCamera',
+        'menuBackgroundFuturisticBlockGroup',
+        'menuBackgroundFuturisticCameraSpeed',
+        'menuBackgroundFuturisticBlockSpeed'
+      ]
+    },
+    {
+      title: 'Mesher',
+      keys: ['rendererMesher']
+    },
+    {
+      title: 'Renderer debug',
+      keys: [
+        'rendererFuturisticReveal',
+        'rendererPerfDebugOverlay'
+      ]
+    }
+  ]

package/src/three/menuBackground/index.ts

@@ -31,6 +31,14 @@ export {
 export {
   RENDERER_DEFAULT_OPTIONS,
   RENDERER_OPTIONS_META,
-  RENDERER_RENDER_GUI_SECTIONS
+  RENDERER_RENDER_GUI_SECTIONS,
+  migrateRendererOptions
 } from './defaultOptions'
-export type { RendererDefaultOptionKey, RendererOptionMeta } from './defaultOptions'
+export type {
+  RendererDefaultOptionKey,
+  RendererGpuPreference,
+  RendererMesherPipeline,
+  RendererOptionMeta,
+  RendererStorageOptions
+} from './defaultOptions'
+export { gpuPreferenceToWebGLPowerPreference } from './defaultOptions'

package/src/three/worldGeometryExport.ts

@@ -1,32 +1,11 @@
 //@ts-nocheck
 import * as THREE from 'three'
 import type { WorldRendererThree } from './worldRendererThree'
+import type { ExportedSection, ExportedWorldGeometry } from '../mesher-shared/exportedGeometryTypes'
 
-const GEOMETRY_EXPORT_GROUP_NAME = 'geometry-export-root'
-
-// Format for exported world geometry
-export interface ExportedWorldGeometry {
-  version: string
-  exportedAt: string
-  camera: {
-    position: { x: number, y: number, z: number }
-    rotation: { pitch: number, yaw: number }
-  }
-  sections: ExportedSection[]
-  textureAtlasDataUrl?: string
-}
+export type { ExportedSection, ExportedWorldGeometry } from '../mesher-shared/exportedGeometryTypes'
 
-export interface ExportedSection {
-  key: string
-  position: { x: number, y: number, z: number }
-  geometry: {
-    positions: number[]
-    normals: number[]
-    colors: number[]
-    uvs: number[]
-    indices: number[]
-  }
-}
+const GEOMETRY_EXPORT_GROUP_NAME = 'geometry-export-root'
 
 /**
  * Export world geometry to a downloadable file

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

@@ -10,11 +10,12 @@ import MinecraftData from 'minecraft-data'
 import PrismarineBlockLoader from 'prismarine-block'
 import { Vec3 } from 'vec3'
 import { elemFaces, buildRotationMatrix, matmul3, matmulmat3, vecadd3, vecsub3 } from '../../mesher-shared/modelsGeometryCommon'
-import type { ExportedWorldGeometry, ExportedSection } from '../../three/worldGeometryExport'
+import type { ExportedWorldGeometry, ExportedSection } from '../../mesher-shared/exportedGeometryTypes'
 import type { MesherGeometryOutput } from '../../mesher-shared/shared'
 import type { World } from '../../mesher-shared/world'
-import { resolveBlockPropertiesForMeshing } from '../../mesher-shared/models'
+import { resolveBlockPropertiesForMeshing } from '../../mesher-shared/blockPropertiesForMeshing'
 import { getSideShading, vertexLightFromAo } from '../../mesher-shared/vertexShading'
+import tintsJson from 'minecraft-data/minecraft-data/data/pc/1.16.2/tints.json'
 
 // Handle both default and named export
 const worldBlockProvider = (worldBlockProviderModule as any).default || worldBlockProviderModule
@@ -25,14 +26,8 @@ let tintsInitialized = false
 
 function initializeTints() {
   if (tintsInitialized) return
-  let tintsData
-  try {
-    tintsData = require('esbuild-data').tints
-  } catch (err) {
-    tintsData = require('minecraft-data/minecraft-data/data/pc/1.16.2/tints.json')
-  }
-  for (const key of Object.keys(tintsData)) {
-    tints[key] = prepareTints(tintsData[key])
+  for (const key of Object.keys(tintsJson as Record<string, unknown>)) {
+    tints[key] = prepareTints((tintsJson as Record<string, unknown>)[key])
   }
   tintsInitialized = true
 }