minecraft-renderer 0.1.43 → 0.1.45

package/package.json

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

package/src/graphicsBackend/appViewer.ts

@@ -27,10 +27,12 @@ import { defaultWorldRendererConfig, defaultGraphicsBackendConfig, getDefaultRen
 import { PlayerStateReactive } from '../playerState/playerState'
 import { ResourcesManager, ResourcesManagerTransferred } from '../resourcesManager'
 import { preloadMesherWorkerScript } from './preloadWorkers'
+import type { MenuBackgroundOptions } from '../three/menuBackground/types'
 
 export interface AppViewerOptions {
   config?: Partial<GraphicsBackendConfig>
   rendererConfig?: Partial<WorldRendererConfig>
+  menuBackground?: MenuBackgroundOptions
 }
 
 /**
@@ -49,6 +51,7 @@ export class AppViewer {
 
   // Configuration
   readonly config: GraphicsBackendConfig
+  readonly menuBackgroundOptions: MenuBackgroundOptions
   readonly inWorldRenderingConfig: WorldRendererConfig
 
   // Backend
@@ -83,7 +86,10 @@ export class AppViewer {
       ...defaultGraphicsBackendConfig,
       ...options.config
     }
-
+    this.menuBackgroundOptions = {
+      ...options.config?.menuBackground,
+      ...options.menuBackground
+    }
     this.inWorldRenderingConfig = proxy({
       ...defaultWorldRendererConfig,
       ...options.rendererConfig
@@ -145,8 +151,8 @@ export class AppViewer {
 
     // Execute queued action if exists
     if (this.currentState) {
-      if (this.currentState.method === 'startPanorama') {
-        this.startPanorama()
+      if (this.currentState.method === 'startMenuBackground') {
+        this.startMenuBackground(...this.currentState.args)
       } else {
         const { method, args } = this.currentState
           ; (this.backend as any)[method](...args)
@@ -202,17 +208,23 @@ export class AppViewer {
   }
 
   /**
-   * Start panorama display (menu background).
+   * Start the main-menu background (3D scene behind UI).
    */
-  startPanorama(): void {
+  startMenuBackground(menuBackgroundOptions?: MenuBackgroundOptions): void {
     if (this.currentDisplay === 'menu') return
 
+    const merged: MenuBackgroundOptions = {
+      ...this.menuBackgroundOptions,
+      ...menuBackgroundOptions,
+      resourcesManager: menuBackgroundOptions?.resourcesManager ?? this.resourcesManager
+    }
+
     if (this.backend) {
       this.currentDisplay = 'menu'
-      this.backend.startPanorama()
+      this.backend.startMenuBackground(merged)
     }
 
-    this.currentState = { method: 'startPanorama', args: [] }
+    this.currentState = { method: 'startMenuBackground', args: [merged] }
   }
 
   /**

package/src/graphicsBackend/types.ts

@@ -22,6 +22,8 @@ export interface SoundSystem {
   destroy: () => void
 }
 
+import type { MenuBackgroundOptions } from '../three/menuBackground/types'
+
 /** Graphics backend configuration */
 export interface GraphicsBackendConfig {
   fpsLimit?: number
@@ -29,6 +31,8 @@ export interface GraphicsBackendConfig {
   statsVisible?: number
   sceneBackground: string
   timeoutRendering?: boolean
+  /** Default options when `startMenuBackground()` is called without arguments */
+  menuBackground?: MenuBackgroundOptions
 }
 
 // ============================================================================
@@ -112,7 +116,7 @@ export interface DisplayWorldOptions {
 export interface GraphicsBackend {
   id: string
   displayName: string
-  startPanorama(): Promise<void>
+  startMenuBackground(options?: MenuBackgroundOptions): Promise<void>
   startWorld(options: DisplayWorldOptions): Promise<void>
   disconnect(): void
   setRendering(rendering: boolean): void

package/src/index.ts

@@ -78,3 +78,36 @@ export {
   addCanvasForWorker,
   isWebWorker
 } from './three/documentRenderer'
+export { MC_RENDERER_DEBUG_OVERLAY_CLASS } from './lib/ui/newStats'
+
+// Main-menu background (title screen backdrop)
+export type {
+  MenuBackgroundMode,
+  MenuBackgroundOptions,
+  MenuBackgroundView,
+  FuturisticSceneId,
+  FuturisticCameraId,
+  FuturisticMenuBackgroundOptions,
+  MinecraftBlockGroupId
+} from './three/menuBackground'
+export {
+  MenuBackgroundRenderer,
+  ClassicMenuBackground,
+  FuturisticMenuBackground,
+  WorldBlocksMenuBackground,
+  MENU_BACKGROUND_MC_VERSION,
+  FUTURISTIC_SCENE_IDS,
+  FUTURISTIC_CAMERA_IDS,
+  FUTURISTIC_SCENE_LABELS,
+  FUTURISTIC_CAMERA_LABELS,
+  MINECRAFT_BLOCK_GROUPS,
+  MINECRAFT_BLOCK_GROUP_IDS,
+  MINECRAFT_BLOCK_GROUP_LABELS,
+  RENDERER_DEFAULT_OPTIONS,
+  RENDERER_OPTIONS_META,
+  RENDERER_RENDER_GUI_SECTIONS,
+  MENU_BACKGROUND_OPTION_DEFAULTS,
+  MENU_BACKGROUND_MOTION_DEFAULTS,
+  menuBackgroundSpeedToMultiplier
+} from './three/menuBackground'
+export type { RendererDefaultOptionKey, RendererOptionMeta } from './three/menuBackground'

package/src/lib/ui/newStats.ts

@@ -7,7 +7,17 @@ const rightOffset = 0
 const stats = {}
 
 let lastY = 40
-export const addNewStat = (id: string, width = 80, x = rightOffset, y = lastY) => {
+
+/** Class for advanced stats pane; host app should set z-index (see integrating app global CSS). */
+export const MC_RENDERER_DEBUG_OVERLAY_CLASS = 'mc-renderer-debug-overlay'
+
+export const addNewStat = (
+  id: string,
+  width = 80,
+  x = rightOffset,
+  y = lastY,
+  opts?: { className?: string },
+) => {
   if (isWebWorker) return { updateText() { }, setVisibility() { } }
 
   const pane = document.createElement('div')
@@ -20,7 +30,11 @@ export const addNewStat = (id: string, width = 80, x = rightOffset, y = lastY) =
   pane.style.padding = '2px'
   pane.style.fontFamily = 'monospace'
   pane.style.fontSize = '12px'
-  pane.style.zIndex = '100'
+  if (opts?.className) {
+    pane.className = opts.className
+  } else {
+    pane.style.zIndex = '100'
+  }
   pane.style.pointerEvents = 'none'
   document.body.appendChild(pane)
   stats[id] = pane

package/src/lib/worldrendererCommon.ts

@@ -11,7 +11,7 @@ import { dynamicMcDataFiles } from './buildSharedConfig.mjs'
 import { DisplayWorldOptions, GraphicsInitOptions, RendererReactiveState, SoundSystem } from '../graphicsBackend/types'
 import { HighestBlockInfo, CustomBlockModels, BlockStateModelInfo, getBlockAssetsCacheKey, MesherConfig, MesherMainEvent, SECTION_HEIGHT } from '../mesher-shared/shared'
 import { chunkPos } from './simpleUtils'
-import { addNewStat, removeAllStats, updatePanesVisibility, updateStatText } from './ui/newStats'
+import { addNewStat, MC_RENDERER_DEBUG_OVERLAY_CLASS, removeAllStats, updatePanesVisibility, updateStatText } from './ui/newStats'
 import { getPlayerStateUtils } from '../graphicsBackend/playerState'
 // TODO: Fix PlayerStateRenderer and PlayerStateUtils imports
 type PlayerStateUtils = ReturnType<typeof getPlayerStateUtils>
@@ -194,7 +194,7 @@ export abstract class WorldRendererCommon<WorkerSend = any, WorkerReceive = any>
       updateStatText('loaded-chunks', `${loadedChunks}/${this.chunksLength} chunks (${this.lastChunkDistance}/${this.viewDistance})`)
     })
 
-    addNewStat('downloaded-chunks', 100, 140, 20)
+    addNewStat('downloaded-chunks', 100, 140, 20, { className: MC_RENDERER_DEBUG_OVERLAY_CLASS })
 
     this.connect(this.displayOptions.worldView as any)
 

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/three/entities.ts

@@ -108,6 +108,14 @@ function poseToEuler(pose: any, defaultValue?: THREE.Euler) {
   return defaultValue ?? new THREE.Euler()
 }
 
+const TAU_YAW = Math.PI * 2
+
+/** Prismarine yaw in radians → shortest delta from→to in (-π, π]. */
+function shortestYawRadians(fromYawRad: number, toYawRad: number): number {
+  const norm = ((toYawRad - fromYawRad) % TAU_YAW + TAU_YAW) % TAU_YAW
+  return norm > Math.PI ? norm - TAU_YAW : norm
+}
+
 function getUsernameTexture({
   username,
   nameTagBackgroundColor = 'rgba(0, 0, 0, 0.3)',
@@ -1366,17 +1374,25 @@ export class Entities {
         })
         .start()
     }
-    if (entity.yaw) {
-      const da = (entity.yaw - e.rotation.y) % (Math.PI * 2)
-      const dy = 2 * da % (Math.PI * 2) - da
+    if (typeof entity.yaw === 'number' && Number.isFinite(entity.yaw)) {
+      const dy = shortestYawRadians(e.rotation.y, entity.yaw)
       new TWEEN.Tween(e.rotation).to({ y: e.rotation.y + dy }, ANIMATION_DURATION).start()
     }
 
     if (e?.playerObject && overrides?.rotation?.head) {
       const { playerObject } = e
-      const headRotationDiff = overrides.rotation.head.y ? overrides.rotation.head.y - entity.yaw : 0
-      playerObject.skin.head.rotation.y = -headRotationDiff
-      playerObject.skin.head.rotation.x = overrides.rotation.head.x ? - overrides.rotation.head.x : 0
+      const hy = overrides.rotation.head.y
+      const headYawWorld =
+        typeof hy === 'number' && Number.isFinite(hy) ? hy : entity.yaw
+      const headYawOffset =
+        typeof headYawWorld === 'number' && typeof entity.yaw === 'number' && Number.isFinite(headYawWorld) && Number.isFinite(entity.yaw)
+          ? shortestYawRadians(entity.yaw, headYawWorld)
+          : 0
+      playerObject.skin.head.rotation.y = headYawOffset
+
+      const hp = overrides.rotation.head.x
+      playerObject.skin.head.rotation.x =
+        typeof hp === 'number' && Number.isFinite(hp) ? -hp : 0
     }
   }
 

package/src/three/graphicsBackendBase.ts

@@ -14,7 +14,8 @@ import { ResourcesManager } from '../resourcesManager'
 import { FrameTimingCollector } from '../lib/frameTimingCollector'
 import { WorldRendererThree } from './worldRendererThree'
 import { DocumentRenderer, isWebWorker, ThreeRendererMainData } from './documentRenderer'
-import { PanoramaRenderer } from './panorama'
+import { MenuBackgroundRenderer } from './menuBackground'
+import type { MenuBackgroundOptions } from './menuBackground/types'
 import { WorldViewWorker } from '../worldView'
 import type { FeedChunkPacketPayload } from '../worldView/types'
 
@@ -127,7 +128,7 @@ export const createGraphicsBackendBase = () => {
   // Private state
   let initOptions!: GraphicsInitOptions
   let documentRenderer: DocumentRenderer | null = null
-  let panoramaRenderer: PanoramaRenderer | null = null
+  let menuBackgroundRenderer: MenuBackgroundRenderer | null = null
   let worldRenderer: WorldRendererThree | null = null
   let frameTimingCollector: FrameTimingCollector | null = null
 
@@ -146,19 +147,26 @@ export const createGraphicsBackendBase = () => {
     callModsMethod('default', backend)
   }
 
-  const startPanorama = async () => {
+  const startMenuBackground = async (menuBackgroundStartOptions?: MenuBackgroundOptions) => {
     if (!documentRenderer) throw new Error('Document renderer not initialized')
     if (worldRenderer) return
 
-    if (!panoramaRenderer) {
-      // Create panorama-specific init options with resourcesManager
-      const panoramaInitOptions = { ...initOptions }
-      panoramaRenderer = new PanoramaRenderer(documentRenderer, panoramaInitOptions, !!process.env.SINGLE_FILE_BUILD_MODE)
-        ; (globalThis as any).panoramaRenderer = panoramaRenderer
-
-      callModsMethod('panoramaCreated', panoramaRenderer)
-      await panoramaRenderer.start()
-      callModsMethod('panoramaReady', panoramaRenderer)
+    if (!menuBackgroundRenderer) {
+      const mergedOptions: MenuBackgroundOptions = {
+        ...initOptions.config.menuBackground,
+        ...menuBackgroundStartOptions
+      }
+      menuBackgroundRenderer = new MenuBackgroundRenderer(
+        documentRenderer,
+        { ...initOptions },
+        mergedOptions,
+        !!process.env.SINGLE_FILE_BUILD_MODE
+      )
+        ; (globalThis as any).menuBackgroundRenderer = menuBackgroundRenderer
+
+      callModsMethod('menuBackgroundCreated', menuBackgroundRenderer)
+      await menuBackgroundRenderer.start(mergedOptions)
+      callModsMethod('menuBackgroundReady', menuBackgroundRenderer)
     }
   }
 
@@ -172,9 +180,9 @@ export const createGraphicsBackendBase = () => {
       // Set resourcesManager globally for world rendering
       ; (globalThis as any).resourcesManager = displayOptions.resourcesManager
 
-    if (panoramaRenderer) {
-      panoramaRenderer.dispose()
-      panoramaRenderer = null
+    if (menuBackgroundRenderer) {
+      menuBackgroundRenderer.dispose()
+      menuBackgroundRenderer = null
     }
 
     worldRenderer = new WorldRendererThree(documentRenderer.renderer, initOptions, displayOptions)
@@ -206,9 +214,9 @@ export const createGraphicsBackendBase = () => {
   }
 
   const disconnect = () => {
-    if (panoramaRenderer) {
-      panoramaRenderer.dispose()
-      panoramaRenderer = null
+    if (menuBackgroundRenderer) {
+      menuBackgroundRenderer.dispose()
+      menuBackgroundRenderer = null
     }
 
     if (documentRenderer) {
@@ -225,7 +233,7 @@ export const createGraphicsBackendBase = () => {
   const backend: GraphicsBackend = {
     id: 'threejs',
     displayName: `three.js ${THREE.REVISION}`,
-    startPanorama,
+    startMenuBackground,
     startWorld,
     disconnect,
     setRendering(rendering) {
@@ -269,7 +277,7 @@ export const createGraphicsBackendBase = () => {
         updateSizeExternal(width: number, height: number, pixelRatio: number) {
           documentRenderer?.updateSizeExternal(width, height, pixelRatio)
         },
-        startPanorama,
+        startMenuBackground,
         startWorld,
         disconnect,
         setRendering: backend.setRendering,

package/src/three/graphicsBackendOffThread.ts

@@ -58,8 +58,7 @@ export const createGraphicsBackendOffThread: GraphicsBackendLoader = async (init
   const backend: GraphicsBackend = {
     id: 'threejs',
     displayName: `three.js ${THREE.REVISION}`,
-    // startPanorama: proxy.startPanorama,
-    async startPanorama() { },
+    async startMenuBackground() { },
     async startWorld(options) {
       const workerThreeSendData = {
         ...dynamicMcDataFiles,

package/src/three/menuBackground/activeView.ts

@@ -0,0 +1,19 @@
+//@ts-nocheck
+import * as THREE from 'three'
+
+/** Contract for a main-menu background implementation (classic cubemap, futuristic scene, etc.). */
+export interface MenuBackgroundView {
+  readonly scene: THREE.Scene
+  readonly camera: THREE.PerspectiveCamera
+  init(): Promise<void>
+  update(dt: number, sizeChanged: boolean): void
+  dispose(): void
+}
+
+export function resizeMenuBackgroundCamera(
+  camera: THREE.PerspectiveCamera,
+  canvas: { width: number, height: number }
+) {
+  camera.aspect = canvas.width / canvas.height
+  camera.updateProjectionMatrix()
+}

package/src/three/menuBackground/classic.ts

@@ -0,0 +1,148 @@
+//@ts-nocheck
+import { join } from 'path'
+import * as THREE from 'three'
+import { EntityMesh } from '../entity/EntityMesh'
+import type { DocumentRenderer } from '../documentRenderer'
+import { loadThreeJsTextureFromUrl, loadThreeJsTextureFromUrlSync } from '../threeJsUtils'
+import type { MenuBackgroundView } from './activeView'
+import { resizeMenuBackgroundCamera } from './activeView'
+
+const date = new Date()
+const isChristmas = date.getMonth() === 11 && date.getDate() >= 24 && date.getDate() <= 26
+
+const panoramaFiles = [
+  'panorama_3.webp', // right (+x)
+  'panorama_1.webp', // left (-x)
+  'panorama_4.webp', // top (+y)
+  'panorama_5.webp', // bottom (-y)
+  'panorama_0.webp', // front (+z)
+  'panorama_2.webp', // back (-z)
+]
+
+const FADE_IN_DURATION_MS = 200
+
+/**
+ * Vanilla-style rotating cubemap (Minecraft title-screen style) with optional squids.
+ */
+export class ClassicMenuBackground implements MenuBackgroundView {
+  readonly scene: THREE.Scene
+  readonly camera: THREE.PerspectiveCamera
+
+  private readonly startTimes = new Map<THREE.MeshBasicMaterial, number>()
+  private time = 0
+  private panoramaGroup: THREE.Object3D | null = null
+
+  constructor(private readonly documentRenderer: DocumentRenderer) {
+    this.scene = new THREE.Scene()
+    this.scene.background = new THREE.Color(0x32_45_68)
+
+    const ambient = new THREE.AmbientLight(0xcc_cc_cc)
+    this.scene.add(ambient)
+    const directional = new THREE.DirectionalLight(0xff_ff_ff, 0.5)
+    directional.position.set(1, 1, 0.5).normalize()
+    directional.castShadow = true
+    this.scene.add(directional)
+
+    this.camera = new THREE.PerspectiveCamera(
+      85,
+      documentRenderer.canvas.width / documentRenderer.canvas.height,
+      0.05,
+      1000
+    )
+    this.camera.position.set(0, 0, 0)
+    this.camera.rotation.set(0, 0, 0)
+  }
+
+  async init() {
+    this.buildCubemap()
+  }
+
+  update(_dt: number, sizeChanged: boolean) {
+    if (sizeChanged) {
+      resizeMenuBackgroundCamera(this.camera, this.documentRenderer.canvas)
+    }
+  }
+
+  dispose() {
+    this.scene.clear()
+    this.panoramaGroup = null
+    this.startTimes.clear()
+  }
+
+  private buildCubemap() {
+    const panorGeo = new THREE.BoxGeometry(1000, 1000, 1000)
+    const panorMaterials: THREE.MeshBasicMaterial[] = []
+
+    for (const file of panoramaFiles) {
+      const load = async () => {
+        const { texture } = loadThreeJsTextureFromUrlSync(join('background', isChristmas ? 'christmas' : '', file))
+
+        texture.matrixAutoUpdate = false
+        texture.matrix.set(-1, 0, 1, 0, 1, 0, 0, 0, 1)
+        texture.wrapS = THREE.ClampToEdgeWrapping
+        texture.wrapT = THREE.ClampToEdgeWrapping
+        texture.minFilter = THREE.LinearFilter
+        texture.magFilter = THREE.LinearFilter
+
+        const material = new THREE.MeshBasicMaterial({
+          map: texture,
+          transparent: true,
+          side: THREE.DoubleSide,
+          depthWrite: false,
+          opacity: 0
+        })
+
+        this.startTimes.set(material, Date.now())
+        panorMaterials.push(material)
+      }
+
+      void load()
+    }
+
+    const panoramaBox = new THREE.Mesh(panorGeo, panorMaterials)
+    panoramaBox.onBeforeRender = () => {
+      this.time += 0.01
+      panoramaBox.rotation.y = Math.PI + this.time * 0.01
+      panoramaBox.rotation.z = Math.sin(-this.time * 0.001) * 0.001
+
+      for (const material of panorMaterials) {
+        const startTime = this.startTimes.get(material)
+        if (startTime) {
+          const elapsed = Date.now() - startTime
+          material.opacity = Math.min(1, elapsed / FADE_IN_DURATION_MS)
+        }
+      }
+    }
+
+    const group = new THREE.Object3D()
+    group.add(panoramaBox)
+
+    if (!isChristmas) {
+      for (let i = 0; i < 20; i++) {
+        const m = new EntityMesh('1.16.4', 'squid').mesh
+        m.position.set(Math.random() * 30 - 15, Math.random() * 20 - 10, Math.random() * 10 - 17)
+        m.rotation.set(0, Math.PI + Math.random(), -Math.PI / 4, 'ZYX')
+        const v = Math.random() * 0.01
+        m.children[0].onBeforeRender = () => {
+          m.rotation.y += v
+          m.rotation.z = Math.cos(panoramaBox.rotation.y * 3) * Math.PI / 4 - Math.PI / 2
+        }
+        group.add(m)
+      }
+    }
+
+    this.scene.add(group)
+    this.panoramaGroup = group
+  }
+
+  /** Debug helper: flat cubemap face in front of the camera. */
+  async debugImageInFrontOfCamera() {
+    const image = await loadThreeJsTextureFromUrl(join('background', 'panorama_0.webp'))
+    const mesh = new THREE.Mesh(
+      new THREE.PlaneGeometry(1000, 1000),
+      new THREE.MeshBasicMaterial({ map: image })
+    )
+    mesh.position.set(0, 0, -500)
+    this.scene.add(mesh)
+  }
+}

package/src/three/menuBackground/config.ts

@@ -0,0 +1,23 @@
+//@ts-nocheck
+import type { MenuBackgroundMode } from './types'
+import type { FuturisticCameraId, FuturisticSceneId, MinecraftBlockGroupId } from './futuristic'
+
+/** Single source of truth for menu-background defaults (settings + runtime fallbacks). */
+export const MENU_BACKGROUND_OPTION_DEFAULTS = {
+  mode: 'futuristic' as MenuBackgroundMode,
+  minecraftTextures: true,
+  futuristicScene: 'light' as FuturisticSceneId,
+  futuristicCamera: 'dive' as FuturisticCameraId,
+  futuristicBlockGroup: 'stainedGlass' as MinecraftBlockGroupId,
+  /** 0–200 (%). 100 = 1× motion. */
+  futuristicCameraSpeedPercent: 80,
+  futuristicBlockSpeedPercent: 40
+} as const
+
+export const menuBackgroundSpeedToMultiplier = (percent: number) => percent / 100
+
+/** Default camera / block motion multipliers (1 = 100%). */
+export const MENU_BACKGROUND_MOTION_DEFAULTS = {
+  camera: menuBackgroundSpeedToMultiplier(MENU_BACKGROUND_OPTION_DEFAULTS.futuristicCameraSpeedPercent),
+  block: menuBackgroundSpeedToMultiplier(MENU_BACKGROUND_OPTION_DEFAULTS.futuristicBlockSpeedPercent)
+} as const