minecraft-renderer 0.1.42 → 0.1.44

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "minecraft-renderer",
-  "version": "0.1.42",
+  "version": "0.1.44",
   "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)
 
@@ -628,6 +628,7 @@ export abstract class WorldRendererCommon<WorkerSend = any, WorkerReceive = any>
       worldMinY: this.worldMinYRender,
       worldMaxY: this.worldMinYRender + this.worldSizeParams.worldHeight,
       disableConversionCache: this.worldRendererConfig.disableMesherConversionCache,
+      computeWireframeEdges: this.worldRendererConfig.futuristicReveal === true,
     }
   }
 

package/src/mesher-legacy/mesher.ts

@@ -1,7 +1,7 @@
 //@ts-nocheck
 import { Vec3 } from 'vec3'
 import { World } from '../mesher-shared/world'
-import { getSectionGeometry, setBlockStatesData as setMesherData } from '../mesher-shared/models'
+import { getSectionGeometry, setBlockStatesData as setMesherData, computeWireframeEdgesJS } from '../mesher-shared/models'
 import { BlockStateModelInfo } from '../mesher-shared/shared'
 import { handleGetHeightmap, EMPTY_COLUMN_HEIGHTMAP_SENTINEL } from '../mesher-shared/computeHeightmap'
 
@@ -208,7 +208,16 @@ setInterval(() => {
     if (chunk?.getSection(new Vec3(x, y, z))) {
       const start = performance.now()
       const geometry = getSectionGeometry(x, y, z, world)
+      if (geometry.positions.length > 0 && geometry.indices.length > 0 && world.config.computeWireframeEdges) {
+        const wireframeF32 = computeWireframeEdgesJS(geometry.positions as number[], geometry.indices as number[])
+        if (wireframeF32.length > 0) {
+          geometry.wireframePositions = wireframeF32
+        }
+      }
       const transferable = [geometry.positions?.buffer, geometry.normals?.buffer, geometry.colors?.buffer, geometry.uvs?.buffer].filter(Boolean)
+      if (geometry.wireframePositions) {
+        transferable.push(geometry.wireframePositions.buffer)
+      }
       //@ts-expect-error
       postMessage({ type: 'geometry', key, geometry, workerIndex }, transferable)
       processTime = performance.now() - start

package/src/mesher-shared/models.ts

@@ -794,3 +794,44 @@ export const setBlockStatesData = (blockstatesModels, blocksAtlas: any, _needTil
     }
   }
 }
+
+export function computeWireframeEdgesJS(positions: Float32Array | number[], indices: Uint32Array | Uint16Array | number[]): Float32Array {
+  const pos = positions instanceof Float32Array ? positions : new Float32Array(positions as number[])
+  const idx = indices instanceof Uint32Array ? indices : (indices instanceof Uint16Array ? new Uint32Array(indices) : new Uint32Array(indices as number[]))
+
+  const linePositions: number[] = []
+  const edgeSet = new Set<number>()
+
+  for (let i = 0; i < idx.length; i += 3) {
+    const i0 = idx[i]!
+    const i1 = idx[i + 1]!
+    const i2 = idx[i + 2]!
+
+    addEdgeJS(pos, i0, i1, linePositions, edgeSet)
+    addEdgeJS(pos, i1, i2, linePositions, edgeSet)
+    addEdgeJS(pos, i2, i0, linePositions, edgeSet)
+  }
+
+  return new Float32Array(linePositions)
+}
+
+function addEdgeJS(
+  positions: Float32Array,
+  i0: number,
+  i1: number,
+  linePositions: number[],
+  edgeSet: Set<number>
+): void {
+  const minI = i0 < i1 ? i0 : i1
+  const maxI = i0 < i1 ? i1 : i0
+  // Pack two indices into a single number (safe while indices < 2^24 — far above per-section vertex counts).
+  const key = minI * 0x1000000 + maxI
+
+  if (edgeSet.has(key)) return
+  edgeSet.add(key)
+
+  linePositions.push(
+    positions[i0 * 3]!, positions[i0 * 3 + 1]!, positions[i0 * 3 + 2]!,
+    positions[i1 * 3]!, positions[i1 * 3 + 1]!, positions[i1 * 3 + 2]!
+  )
+}

package/src/mesher-shared/shared.ts

@@ -19,6 +19,7 @@ export const defaultMesherConfig = {
   clipWorldBelowY: undefined as undefined | number,
   disableBlockEntityTextures: false,
   disableConversionCache: false,
+  computeWireframeEdges: false,
 }
 
 export type CustomBlockModels = {
@@ -60,6 +61,7 @@ export type MesherGeometryOutput = {
   // isFull: boolean
   hadErrors: boolean
   blocksCount: number
+  wireframePositions?: Float32Array
   customBlockModels?: CustomBlockModels
 }
 

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