minecraft-renderer 0.1.45 → 0.1.47

package/package.json

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

package/src/graphicsBackend/appViewer.ts

@@ -28,6 +28,7 @@ import { PlayerStateReactive } from '../playerState/playerState'
 import { ResourcesManager, ResourcesManagerTransferred } from '../resourcesManager'
 import { preloadMesherWorkerScript } from './preloadWorkers'
 import type { MenuBackgroundOptions } from '../three/menuBackground/types'
+import type { RendererStorageOptions } from '../three/menuBackground/defaultOptions'
 
 export interface AppViewerOptions {
   config?: Partial<GraphicsBackendConfig>
@@ -81,6 +82,9 @@ export class AppViewer {
   // Timing
   lastCamUpdate = 0
 
+  /** Bound by `subscribeRendererOptions` / `bindRendererOptions` — source of truth for renderer-owned settings. */
+  private getRendererOptions?: () => RendererStorageOptions
+
   constructor(options: AppViewerOptions = {}, public resourcesManager: ResourcesManager = new ResourcesManager()) {
     this.config = {
       ...defaultGraphicsBackendConfig,
@@ -117,6 +121,11 @@ export class AppViewer {
     return preloadMesherWorkerScript({ script })
   }
 
+  /** Wire app options storage (valtio proxy) for backend init (WebGL gpuPreference, etc.). */
+  bindRendererOptions(getOptions: () => RendererStorageOptions): void {
+    this.getRendererOptions = getOptions
+  }
+
   /**
    * Load a graphics backend.
    */
@@ -132,6 +141,7 @@ export class AppViewer {
 
     const loaderOptions: GraphicsInitOptions = {
       config: this.config,
+      getRendererOptions: this.getRendererOptions,
       callbacks: {
         displayCriticalError: (error) => {
           console.error('[AppViewer] Critical error:', error)

package/src/graphicsBackend/config.ts

@@ -4,6 +4,7 @@
  */
 
 import { proxy } from 'valtio'
+import { defaultPerformanceInstabilityFactors } from '../performanceMonitor'
 import type {
   GraphicsBackendConfig,
   RendererReactiveState,
@@ -88,7 +89,6 @@ export type WorldRendererConfig = typeof defaultWorldRendererConfig
  */
 export const defaultGraphicsBackendConfig: GraphicsBackendConfig = {
   fpsLimit: undefined,
-  powerPreference: undefined,
   sceneBackground: 'lightblue',
   timeoutRendering: false
 }
@@ -117,6 +117,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,5 @@ export * from './types'
 export * from './config'
 export * from './playerState'
 export * from './appViewer'
+export * from './rendererOptionsSync'
+export * from '../performanceMonitor'

package/src/graphicsBackend/rendererOptionsSync.ts

@@ -0,0 +1,243 @@
+//@ts-nocheck
+/**
+ * Maps app options storage → AppViewer runtime (in-world config, graphics config, menu background).
+ * Call `subscribeRendererOptions` once after viewer init; keep volume sync in the app.
+ */
+
+import { subscribe } from 'valtio/vanilla'
+import type { AppViewer } from './appViewer'
+import type { RendererStorageOptions } from '../three/menuBackground/defaultOptions'
+import type { MenuBackgroundOptions } from '../three/menuBackground/types'
+import type { MenuBackgroundRenderer } from '../three/menuBackground/renderer'
+import { menuBackgroundSpeedToMultiplier } from '../three/menuBackground/config'
+import type { FuturisticCameraId, FuturisticSceneId, MinecraftBlockGroupId } from '../three/menuBackground/futuristic'
+import { setSkinsConfig } from '../lib/utils/skins'
+
+export type { RendererStorageOptions } from '../three/menuBackground/defaultOptions'
+
+export interface ApplyRendererOptionsContext {
+  isSafari?: boolean
+  isCypress?: boolean
+  windowFocused?: boolean
+}
+
+export interface RendererOptionsSubscribeHooks {
+  isSafari?: boolean
+  isCypress?: boolean
+  getWindowFocused?: () => boolean
+  onRegisterFocusHandlers?: (handlers: { onFocus: () => void, onBlur: () => void }) => void
+}
+
+export interface RendererWorldViewLike {
+  keepChunksDistance: number
+}
+
+export function menuBackgroundOptionsFromStorage(o: Pick<
+  RendererStorageOptions,
+  | 'menuBackgroundMode'
+  | 'menuBackgroundMinecraftTextures'
+  | 'menuBackgroundFuturisticScene'
+  | 'menuBackgroundFuturisticCamera'
+  | 'menuBackgroundFuturisticBlockGroup'
+  | 'menuBackgroundFuturisticCameraSpeed'
+  | 'menuBackgroundFuturisticBlockSpeed'
+>): MenuBackgroundOptions {
+  return {
+    mode: o.menuBackgroundMode as MenuBackgroundOptions['mode'],
+    useMinecraftTextures: o.menuBackgroundMinecraftTextures,
+    futuristicScene: o.menuBackgroundFuturisticScene as FuturisticSceneId,
+    futuristicCamera: o.menuBackgroundFuturisticCamera as FuturisticCameraId,
+    futuristicBlockGroup: o.menuBackgroundFuturisticBlockGroup as MinecraftBlockGroupId,
+    futuristicCameraSpeed: menuBackgroundSpeedToMultiplier(o.menuBackgroundFuturisticCameraSpeed),
+    futuristicBlockSpeed: menuBackgroundSpeedToMultiplier(o.menuBackgroundFuturisticBlockSpeed),
+  }
+}
+
+export function applyMenuBackgroundLiveOptions(
+  menu: MenuBackgroundRenderer,
+  o: Pick<
+    RendererStorageOptions,
+    | 'menuBackgroundFuturisticScene'
+    | 'menuBackgroundFuturisticCamera'
+    | 'menuBackgroundFuturisticBlockGroup'
+    | 'menuBackgroundFuturisticCameraSpeed'
+    | 'menuBackgroundFuturisticBlockSpeed'
+  >
+): void {
+  const futuristic = menu.futuristic
+  if (!futuristic) return
+  futuristic.setScene?.(o.menuBackgroundFuturisticScene)
+  futuristic.setCamera?.(o.menuBackgroundFuturisticCamera)
+  void futuristic.setBlockGroup?.(o.menuBackgroundFuturisticBlockGroup)
+  futuristic.setCameraSpeed?.(menuBackgroundSpeedToMultiplier(o.menuBackgroundFuturisticCameraSpeed))
+  futuristic.setBlockSpeed?.(menuBackgroundSpeedToMultiplier(o.menuBackgroundFuturisticBlockSpeed))
+}
+
+function resolveWasmMesherActive(o: RendererStorageOptions): boolean {
+  return o.rendererMesher !== 'legacy-js'
+}
+
+function applyMesherWorkersPreset(
+  appViewer: AppViewer,
+  o: RendererStorageOptions,
+  wasmActive: boolean
+): void {
+  const cfg = appViewer.inWorldRenderingConfig
+  const override = o.rendererMeshersCountOverride
+  const applyMesherWorkers = (workers: number) => {
+    cfg.mesherWorkers = override ?? workers
+  }
+  switch (o.rendererWorldPerformance) {
+    case 'low-energy':
+      applyMesherWorkers(1)
+      cfg.dedicatedChangeWorker = false
+      break
+    case 'normal':
+      applyMesherWorkers(2)
+      cfg.dedicatedChangeWorker = !wasmActive
+      break
+    case 'maximum':
+      applyMesherWorkers(Math.max(3, Math.min(navigator.hardwareConcurrency ?? 0, 8)))
+      cfg.dedicatedChangeWorker = !wasmActive
+      break
+  }
+}
+
+function applyFpsLimit(
+  appViewer: AppViewer,
+  o: RendererStorageOptions,
+  windowFocused: boolean
+): void {
+  const backgroundFpsLimit = o.backgroundRendering
+  const normalFpsLimit = o.frameLimit
+
+  if (windowFocused) {
+    appViewer.config.fpsLimit = normalFpsLimit || undefined
+  } else if (backgroundFpsLimit === '5fps') {
+    appViewer.config.fpsLimit = 5
+  } else if (backgroundFpsLimit === '20fps') {
+    appViewer.config.fpsLimit = 20
+  } else {
+    appViewer.config.fpsLimit = undefined
+  }
+}
+
+function applyStatsVisible(
+  appViewer: AppViewer,
+  o: RendererStorageOptions,
+  ctx: ApplyRendererOptionsContext
+): void {
+  const { renderDebug } = o
+  if (renderDebug === 'none' || ctx.isCypress) {
+    appViewer.config.statsVisible = 0
+  } else if (renderDebug === 'basic') {
+    appViewer.config.statsVisible = 1
+  } else if (renderDebug === 'advanced') {
+    appViewer.config.statsVisible = 2
+  }
+}
+
+// ensure no object assigns to the config
+export function applyRendererOptions(
+  appViewer: AppViewer,
+  o: RendererStorageOptions,
+  ctx: ApplyRendererOptionsContext = {}
+): void {
+  const cfg = appViewer.inWorldRenderingConfig
+  const wasmActive = resolveWasmMesherActive(o)
+
+  cfg.showChunkBorders = o.showChunkBorders
+  cfg.futuristicReveal = o.rendererFuturisticReveal
+  applyMesherWorkersPreset(appViewer, o, wasmActive)
+  cfg.renderEntities = o.renderEntities
+  applyStatsVisible(appViewer, o, ctx)
+  applyFpsLimit(appViewer, o, ctx.windowFocused !== false)
+
+  cfg.vrSupport = o.vrSupport
+  cfg.vrPageGameRendering = o.vrPageGameRendering
+  cfg.enableDebugOverlay = o.rendererPerfDebugOverlay
+
+  cfg.clipWorldBelowY = o.clipWorldBelowY
+  cfg.extraBlockRenderers = !o.disableBlockEntityTextures
+  cfg.fetchPlayerSkins = o.loadPlayerSkins
+  cfg.highlightBlockColor = o.highlightBlockColor
+  cfg.wasmMesher = wasmActive
+  cfg.disableMesherConversionCache = !!ctx.isSafari
+
+  setSkinsConfig({ apiEnabled: o.loadPlayerSkins })
+
+  cfg.smoothLighting = o.smoothLighting
+  cfg.shadingTheme = o.vanillaLook ? 'vanilla' : 'high-contrast'
+  cfg.starfield = o.starfieldRendering
+  cfg.defaultSkybox = o.defaultSkybox
+}
+
+/** World-view + hand/camera options (call when WorldView is ready). */
+export function applyRendererWorldViewOptions(
+  appViewer: AppViewer,
+  worldView: RendererWorldViewLike,
+  o: Pick<
+    RendererStorageOptions,
+    'keepChunksDistance' | 'renderEars' | 'showHand' | 'viewBobbing' | 'dayCycleAndLighting'
+  >
+): void {
+  worldView.keepChunksDistance = o.keepChunksDistance
+  const cfg = appViewer.inWorldRenderingConfig
+  cfg.renderEars = o.renderEars
+  cfg.showHand = o.showHand
+  cfg.viewBobbing = o.viewBobbing
+  cfg.dayCycle = o.dayCycleAndLighting
+}
+
+/**
+ * Subscribe to options changes and sync renderer runtime.
+ * Returns unsubscribe. Volume is intentionally excluded — wire it in the app.
+ */
+export function subscribeRendererOptions<T extends RendererStorageOptions>(
+  appViewer: AppViewer,
+  optionsProxy: T,
+  hooks: RendererOptionsSubscribeHooks = {}
+): () => void {
+  appViewer.bindRendererOptions(() => optionsProxy as RendererStorageOptions)
+
+  let windowFocused = hooks.getWindowFocused?.() ?? true
+
+  const run = () => {
+    const snapshot = optionsProxy as RendererStorageOptions
+    applyRendererOptions(appViewer, snapshot, {
+      isSafari: hooks.isSafari,
+      isCypress: hooks.isCypress,
+      windowFocused,
+    })
+
+    if (appViewer.currentDisplay === 'menu') {
+      const menu = appViewer.backend?.getMenuBackground?.()
+      if (menu) applyMenuBackgroundLiveOptions(menu, snapshot)
+    }
+  }
+
+  run()
+
+  hooks.onRegisterFocusHandlers?.({
+    onFocus: () => {
+      windowFocused = true
+      run()
+    },
+    onBlur: () => {
+      windowFocused = false
+      run()
+    },
+  })
+
+  return subscribe(optionsProxy, run)
+}
+
+/** Call when mineflayer bot is created (lighting depends on protocol features). */
+export function applyRendererEnableLighting(
+  appViewer: AppViewer,
+  newVersionsLighting: boolean,
+  blockStateIdSupported: boolean
+): void {
+  appViewer.inWorldRenderingConfig.enableLighting =
+    !blockStateIdSupported || newVersionsLighting
+}

package/src/graphicsBackend/types.ts

@@ -23,11 +23,13 @@ export interface SoundSystem {
 }
 
 import type { MenuBackgroundOptions } from '../three/menuBackground/types'
+import type { RendererStorageOptions } from '../three/menuBackground/defaultOptions'
+import type { MenuBackgroundRenderer } from '../three/menuBackground/renderer'
+import type { PerformanceInstabilityFactors } from '../performanceMonitor'
 
 /** Graphics backend configuration */
 export interface GraphicsBackendConfig {
   fpsLimit?: number
-  powerPreference?: 'high-performance' | 'low-power'
   statsVisible?: number
   sceneBackground: string
   timeoutRendering?: boolean
@@ -76,6 +78,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
@@ -93,6 +97,8 @@ export interface RendererReactiveState {
 /** Graphics initialization options */
 export interface GraphicsInitOptions<S = any> {
   config: GraphicsBackendConfig
+  /** Live app options (e.g. valtio proxy); used for WebGL `gpuPreference` at context creation. */
+  getRendererOptions?: () => RendererStorageOptions
   rendererSpecificSettings: S
   callbacks: {
     displayCriticalError: (error: Error) => void
@@ -124,6 +130,8 @@ export interface GraphicsBackend {
   soundSystem?: any
   backendMethods?: any
   getDebugOverlay?(): { entitiesString?: string, left?: Record<string, string>, right?: Record<string, string> }
+  /** Active main-menu background, when `currentDisplay === 'menu'`. */
+  getMenuBackground?(): MenuBackgroundRenderer | undefined
 }
 
 /** Graphics backend loader function type */

package/src/mesher-shared/blockPropertiesForMeshing.ts

@@ -0,0 +1,79 @@
+//@ts-nocheck
+import { Vec3 } from 'vec3'
+import type { WorldBlockProvider } from 'mc-assets/dist/worldBlockProvider'
+import legacyJson from '../lib/preflatMap.json'
+import type { World, WorldBlock as Block } from './world'
+
+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
+  switch (type) {
+    case 'directional': {
+      const isSolidConnection = !block.name.includes('redstone') && !block.name.includes('tripwire')
+      const neighbors = [
+        world.getBlock(position.offset(0, 0, 1)),
+        world.getBlock(position.offset(0, 0, -1)),
+        world.getBlock(position.offset(1, 0, 0)),
+        world.getBlock(position.offset(-1, 0, 0))
+      ]
+      const props = {}
+      let changed = false
+      for (const [i, neighbor] of neighbors.entries()) {
+        const isConnectedToSolid = isSolidConnection ? (neighbor && !neighbor.transparent) : false
+        if (isConnectedToSolid || neighbor?.name === block.name) {
+          props[['south', 'north', 'east', 'west'][i]] = 'true'
+          changed = true
+        }
+      }
+      return changed ? props : undefined
+    }
+    case 'block_snowy': {
+      const aboveIsSnow = world.getBlock(position.offset(0, 1, 0))?.name === 'snow'
+      if (aboveIsSnow) {
+        return {
+          snowy: `${aboveIsSnow}`
+        }
+      } else {
+        return
+      }
+    }
+    case 'door': {
+      const { half } = block.getProperties()
+      if (half === 'upper') {
+        const lower = world.getBlock(position.offset(0, -1, 0))
+        if (lower?.name === block.name) {
+          return {
+            ...lower.getProperties(),
+            half: 'upper'
+          }
+        }
+      }
+    }
+  }
+}

package/src/mesher-shared/exportedGeometryTypes.ts

@@ -0,0 +1,26 @@
+//@ts-nocheck
+/** Shared geometry export shapes (worker bridge + main-thread viewer). */
+
+export interface ExportedSection {
+  key: string
+  position: { x: number, y: number, z: number }
+  geometry: {
+    positions: number[]
+    normals: number[]
+    colors: number[]
+    uvs: number[]
+    indices: number[]
+  }
+  shaderCubes?: unknown
+}
+
+export interface ExportedWorldGeometry {
+  version: string
+  exportedAt: string
+  camera: {
+    position: { x: number, y: number, z: number }
+    rotation: { pitch: number, yaw: number }
+  }
+  sections: ExportedSection[]
+  textureAtlasDataUrl?: string
+}

package/src/mesher-shared/models.ts

@@ -2,7 +2,6 @@
 import { Vec3 } from 'vec3'
 import worldBlockProvider, { WorldBlockProvider } from 'mc-assets/dist/worldBlockProvider'
 import moreBlockDataGeneratedJson from '../lib/moreBlockDataGenerated.json'
-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'
@@ -10,6 +9,9 @@ import { getSideShading, vertexLightFromAo } from './vertexShading'
 import { INVISIBLE_BLOCKS } from './worldConstants'
 import { MesherGeometryOutput, HighestBlockInfo } from './shared'
 import { collectBlockEntityMetadata } from './blockEntityMetadata'
+import { preflatBlockCalculation, resolveBlockPropertiesForMeshing } from './blockPropertiesForMeshing'
+
+export { preflatBlockCalculation, resolveBlockPropertiesForMeshing } from './blockPropertiesForMeshing'
 
 // Log function disabled by default for zero overhead in production hot loops
 const ENABLE_TS_LOGS = false
@@ -51,84 +53,6 @@ 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
-  switch (type) {
-    case 'directional': {
-      const isSolidConnection = !block.name.includes('redstone') && !block.name.includes('tripwire')
-      const neighbors = [
-        world.getBlock(position.offset(0, 0, 1)),
-        world.getBlock(position.offset(0, 0, -1)),
-        world.getBlock(position.offset(1, 0, 0)),
-        world.getBlock(position.offset(-1, 0, 0))
-      ]
-      // set needed props to true: east:'false',north:'false',south:'false',west:'false'
-      const props = {}
-      let changed = false
-      for (const [i, neighbor] of neighbors.entries()) {
-        const isConnectedToSolid = isSolidConnection ? (neighbor && !neighbor.transparent) : false
-        if (isConnectedToSolid || neighbor?.name === block.name) {
-          props[['south', 'north', 'east', 'west'][i]] = 'true'
-          changed = true
-        }
-      }
-      return changed ? props : undefined
-    }
-    // case 'gate_in_wall': {}
-    case 'block_snowy': {
-      const aboveIsSnow = world.getBlock(position.offset(0, 1, 0))?.name === 'snow'
-      if (aboveIsSnow) {
-        return {
-          snowy: `${aboveIsSnow}`
-        }
-      } else {
-        return
-      }
-    }
-    case 'door': {
-      // upper half matches lower in
-      const { half } = block.getProperties()
-      if (half === 'upper') {
-        // copy other properties
-        const lower = world.getBlock(position.offset(0, -1, 0))
-        if (lower?.name === block.name) {
-          return {
-            ...lower.getProperties(),
-            half: 'upper'
-          }
-        }
-      }
-    }
-  }
-}
-
 function tintToGl(tint) {
   const r = (tint >> 16) & 0xff
   const g = (tint >> 8) & 0xff

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