minecraft-renderer 0.1.63 → 0.1.64

package/package.json

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

package/src/graphicsBackend/rendererDefaultOptions.ts

@@ -1,12 +1,12 @@
 //@ts-nocheck
 import {
-  FUTURISTIC_CAMERA_IDS,
-  FUTURISTIC_CAMERA_LABELS,
-  FUTURISTIC_SCENE_IDS,
-  FUTURISTIC_SCENE_LABELS,
+  V2_CAMERA_IDS,
+  V2_CAMERA_LABELS,
+  V2_SCENE_IDS,
+  V2_SCENE_LABELS,
   MINECRAFT_BLOCK_GROUP_IDS,
   MINECRAFT_BLOCK_GROUP_LABELS
-} from '../three/menuBackground/futuristicMeta'
+} from '../three/menuBackground/v2Meta'
 import { MENU_BACKGROUND_OPTION_DEFAULTS } from '../three/menuBackground/config'
 import type { RendererGpuPreference } from '../three/menuBackground/gpuPreference'
 
@@ -54,11 +54,11 @@ export const RENDERER_DEFAULT_OPTIONS = {
   defaultSkybox: true as boolean,
   menuBackgroundMode: MB.mode,
   menuBackgroundMinecraftTextures: MB.minecraftTextures as boolean,
-  menuBackgroundFuturisticScene: MB.futuristicScene,
-  menuBackgroundFuturisticCamera: MB.futuristicCamera,
-  menuBackgroundFuturisticBlockGroup: MB.futuristicBlockGroup,
-  menuBackgroundFuturisticCameraSpeed: MB.futuristicCameraSpeedPercent,
-  menuBackgroundFuturisticBlockSpeed: MB.futuristicBlockSpeedPercent,
+  menuBackgroundV2Scene: MB.v2Scene,
+  menuBackgroundV2Camera: MB.v2Camera,
+  menuBackgroundV2BlockGroup: MB.v2BlockGroup,
+  menuBackgroundV2CameraSpeed: MB.v2CameraSpeedPercent,
+  menuBackgroundV2BlockSpeed: MB.v2BlockSpeedPercent,
   rendererFuturisticReveal: false as boolean,
   rendererPerfDebugOverlay: false as boolean,
   disableBlockEntityTextures: false as boolean,
@@ -110,37 +110,54 @@ export function migrateRendererOptions(saved: Record<string, unknown>): void {
   }
   delete saved.wasmExperimentalMesher
   delete saved.rendererWasmMesher
+
+  if (saved.menuBackgroundMode === 'futuristic') {
+    saved.menuBackgroundMode = 'v2'
+  }
+  const futuristicToV2: Array<[string, string]> = [
+    ['menuBackgroundFuturisticScene', 'menuBackgroundV2Scene'],
+    ['menuBackgroundFuturisticCamera', 'menuBackgroundV2Camera'],
+    ['menuBackgroundFuturisticBlockGroup', 'menuBackgroundV2BlockGroup'],
+    ['menuBackgroundFuturisticCameraSpeed', 'menuBackgroundV2CameraSpeed'],
+    ['menuBackgroundFuturisticBlockSpeed', 'menuBackgroundV2BlockSpeed'],
+  ]
+  for (const [oldKey, newKey] of futuristicToV2) {
+    if (saved[oldKey] !== undefined && saved[newKey] === undefined) {
+      saved[newKey] = saved[oldKey]
+    }
+    delete saved[oldKey]
+  }
 }
 
 /** Settings UI metadata for {@link RENDERER_DEFAULT_OPTIONS} keys. */
 export const RENDERER_OPTIONS_META: Partial<Record<RendererDefaultOptionKey, RendererOptionMeta>> = {
   menuBackgroundMode: {
-    possibleValues: [['classic', 'Classic'], ['futuristic', 'Futuristic']],
+    possibleValues: [['classic', 'Classic'], ['v2', 'V2']],
     requiresRestart: true
   },
   menuBackgroundMinecraftTextures: {
     text: 'Minecraft block textures',
-    tooltip: 'Use block atlas on futuristic menu cubes (loads assets on menu)'
+    tooltip: 'Use block atlas on V2 menu cubes (loads assets on menu)'
   },
-  menuBackgroundFuturisticScene: {
-    possibleValues: FUTURISTIC_SCENE_IDS.map(id => [id, FUTURISTIC_SCENE_LABELS[id]] as [string, string])
+  menuBackgroundV2Scene: {
+    possibleValues: V2_SCENE_IDS.map(id => [id, V2_SCENE_LABELS[id]] as [string, string])
   },
-  menuBackgroundFuturisticCamera: {
-    possibleValues: FUTURISTIC_CAMERA_IDS.map(id => [id, FUTURISTIC_CAMERA_LABELS[id]] as [string, string])
+  menuBackgroundV2Camera: {
+    possibleValues: V2_CAMERA_IDS.map(id => [id, V2_CAMERA_LABELS[id]] as [string, string])
   },
-  menuBackgroundFuturisticBlockGroup: {
+  menuBackgroundV2BlockGroup: {
     possibleValues: MINECRAFT_BLOCK_GROUP_IDS.map(id => [id, MINECRAFT_BLOCK_GROUP_LABELS[id]] as [string, string]),
     text: 'Block pool',
     tooltip: 'Block set for textured menu cubes (requires Minecraft textures)'
   },
-  menuBackgroundFuturisticCameraSpeed: {
+  menuBackgroundV2CameraSpeed: {
     text: 'Camera speed',
     tooltip: 'Orbit / fly-through camera path speed. 0 freezes the path; mouse parallax still works.',
     min: 0,
     max: 200,
     unit: '%'
   },
-  menuBackgroundFuturisticBlockSpeed: {
+  menuBackgroundV2BlockSpeed: {
     text: 'Block speed',
     tooltip: 'Floating blocks and sky rotation. Independent of camera path speed.',
     min: 0,
@@ -315,11 +332,11 @@ export const RENDERER_RENDER_GUI_SECTIONS: ReadonlyArray<{
       keys: [
         'menuBackgroundMode',
         'menuBackgroundMinecraftTextures',
-        'menuBackgroundFuturisticScene',
-        'menuBackgroundFuturisticCamera',
-        'menuBackgroundFuturisticBlockGroup',
-        'menuBackgroundFuturisticCameraSpeed',
-        'menuBackgroundFuturisticBlockSpeed'
+        'menuBackgroundV2Scene',
+        'menuBackgroundV2Camera',
+        'menuBackgroundV2BlockGroup',
+        'menuBackgroundV2CameraSpeed',
+        'menuBackgroundV2BlockSpeed'
       ]
     },
     {

package/src/graphicsBackend/rendererOptionsSync.ts

@@ -11,7 +11,7 @@ import { rendererShaderCubeDebugModeToValue } from './rendererDefaultOptions'
 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 type { V2CameraId, V2SceneId, MinecraftBlockGroupId } from '../three/menuBackground/v2'
 import { setSkinsConfig } from '../lib/utils/skins'
 
 export type { RendererStorageOptions } from './rendererDefaultOptions'
@@ -37,20 +37,20 @@ export function menuBackgroundOptionsFromStorage(o: Pick<
   RendererStorageOptions,
   | 'menuBackgroundMode'
   | 'menuBackgroundMinecraftTextures'
-  | 'menuBackgroundFuturisticScene'
-  | 'menuBackgroundFuturisticCamera'
-  | 'menuBackgroundFuturisticBlockGroup'
-  | 'menuBackgroundFuturisticCameraSpeed'
-  | 'menuBackgroundFuturisticBlockSpeed'
+  | 'menuBackgroundV2Scene'
+  | 'menuBackgroundV2Camera'
+  | 'menuBackgroundV2BlockGroup'
+  | 'menuBackgroundV2CameraSpeed'
+  | 'menuBackgroundV2BlockSpeed'
 >): 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),
+    v2Scene: o.menuBackgroundV2Scene as V2SceneId,
+    v2Camera: o.menuBackgroundV2Camera as V2CameraId,
+    v2BlockGroup: o.menuBackgroundV2BlockGroup as MinecraftBlockGroupId,
+    v2CameraSpeed: menuBackgroundSpeedToMultiplier(o.menuBackgroundV2CameraSpeed),
+    v2BlockSpeed: menuBackgroundSpeedToMultiplier(o.menuBackgroundV2BlockSpeed),
   }
 }
 
@@ -58,20 +58,20 @@ export function applyMenuBackgroundLiveOptions(
   menu: MenuBackgroundRenderer,
   o: Pick<
     RendererStorageOptions,
-    | 'menuBackgroundFuturisticScene'
-    | 'menuBackgroundFuturisticCamera'
-    | 'menuBackgroundFuturisticBlockGroup'
-    | 'menuBackgroundFuturisticCameraSpeed'
-    | 'menuBackgroundFuturisticBlockSpeed'
+    | 'menuBackgroundV2Scene'
+    | 'menuBackgroundV2Camera'
+    | 'menuBackgroundV2BlockGroup'
+    | 'menuBackgroundV2CameraSpeed'
+    | 'menuBackgroundV2BlockSpeed'
   >
 ): 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))
+  const v2 = menu.v2
+  if (!v2) return
+  v2.setScene?.(o.menuBackgroundV2Scene)
+  v2.setCamera?.(o.menuBackgroundV2Camera)
+  void v2.setBlockGroup?.(o.menuBackgroundV2BlockGroup)
+  v2.setCameraSpeed?.(menuBackgroundSpeedToMultiplier(o.menuBackgroundV2CameraSpeed))
+  v2.setBlockSpeed?.(menuBackgroundSpeedToMultiplier(o.menuBackgroundV2BlockSpeed))
 }
 
 function resolveWasmMesherActive(o: RendererStorageOptions): boolean {

package/src/index.ts

@@ -85,21 +85,21 @@ export type {
   MenuBackgroundMode,
   MenuBackgroundOptions,
   MenuBackgroundView,
-  FuturisticSceneId,
-  FuturisticCameraId,
-  FuturisticMenuBackgroundOptions,
+  V2SceneId,
+  V2CameraId,
+  V2MenuBackgroundOptions,
   MinecraftBlockGroupId
 } from './three/menuBackground'
 export {
   MenuBackgroundRenderer,
   ClassicMenuBackground,
-  FuturisticMenuBackground,
+  V2MenuBackground,
   WorldBlocksMenuBackground,
   MENU_BACKGROUND_MC_VERSION,
-  FUTURISTIC_SCENE_IDS,
-  FUTURISTIC_CAMERA_IDS,
-  FUTURISTIC_SCENE_LABELS,
-  FUTURISTIC_CAMERA_LABELS,
+  V2_SCENE_IDS,
+  V2_CAMERA_IDS,
+  V2_SCENE_LABELS,
+  V2_CAMERA_LABELS,
   MINECRAFT_BLOCK_GROUPS,
   MINECRAFT_BLOCK_GROUP_IDS,
   MINECRAFT_BLOCK_GROUP_LABELS,

package/src/lib/worldrendererCommon.removeColumn.test.ts

@@ -0,0 +1,182 @@
+//@ts-nocheck
+import { EventEmitter } from 'events'
+import { afterEach, beforeEach, describe, expect, test, vi } from 'vitest'
+import { Vec3 } from 'vec3'
+import { proxy } from 'valtio'
+import { WorldRendererCommon } from './worldrendererCommon'
+import { defaultWorldRendererConfig } from '../graphicsBackend/config'
+import { getInitialPlayerState } from '../playerState/playerState'
+import type { DisplayWorldOptions, GraphicsInitOptions } from '../graphicsBackend/types'
+
+vi.mock('./ui/newStats', () => ({
+  addNewStat: vi.fn(() => ({ updateText: vi.fn(), setVisibility: vi.fn() })),
+  updateStatText: vi.fn(),
+  removeAllStats: vi.fn(),
+  updatePanesVisibility: vi.fn(),
+  MC_RENDERER_DEBUG_OVERLAY_CLASS: 'mc-renderer-debug-overlay',
+}))
+
+vi.mock('./utils/skins', () => ({
+  setSkinsConfig: vi.fn(),
+  steveTexture: {},
+  stevePngUrl: '',
+}))
+
+function ensurePromiseWithResolvers() {
+  if (!Promise.withResolvers) {
+    Promise.withResolvers = function <T>() {
+      let resolve!: (value: T | PromiseLike<T>) => void
+      let reject!: (reason?: unknown) => void
+      const promise = new Promise<T>((res, rej) => {
+        resolve = res
+        reject = rej
+      })
+      return { promise, resolve, reject }
+    }
+  }
+}
+
+class TestWorldRenderer extends WorldRendererCommon {
+  outputFormat = 'threeJs' as const
+
+  changeBackgroundColor() {}
+  changeCardinalLight() {}
+  handleWorkerMessage() {}
+  updateCamera() {}
+  render() {}
+  updateShowChunksBorder() {}
+}
+
+function createRenderer() {
+  const rendererState = proxy({
+    world: {
+      chunksLoaded: new Set<string>(),
+      heightmaps: new Map<string, Int16Array>(),
+      allChunksLoaded: false,
+      mesherWork: false,
+      instabilityFactors: {},
+      intersectMedia: null,
+    },
+    renderer: '',
+    preventEscapeMenu: false,
+  })
+
+  const displayOptions = {
+    version: '1.21.1',
+    worldView: new EventEmitter() as DisplayWorldOptions['worldView'],
+    inWorldRenderingConfig: { ...defaultWorldRendererConfig },
+    playerStateReactive: getInitialPlayerState(),
+    rendererState,
+    nonReactiveState: {
+      fps: 0,
+      worstRenderTime: 0,
+      avgRenderTime: 0,
+      world: {
+        chunksLoaded: new Set<string>(),
+        chunksTotalNumber: 0,
+        chunksFullInfo: '',
+      },
+      renderer: {
+        timeline: { live: [], frozen: [], lastSecond: [] },
+      },
+    },
+    resourcesManager: {} as DisplayWorldOptions['resourcesManager'],
+  }
+
+  const initOptions: GraphicsInitOptions = {
+    config: { sceneBackground: '#000' },
+    rendererSpecificSettings: {},
+    callbacks: {
+      displayCriticalError: vi.fn(),
+      setRendererSpecificSettings: vi.fn(),
+      fireCustomEvent: vi.fn(),
+    },
+  }
+
+  const renderer = new TestWorldRenderer(displayOptions.resourcesManager, displayOptions, initOptions)
+  renderer.active = true
+  renderer.workers = [{ postMessage: vi.fn() }, { postMessage: vi.fn() }]
+  renderer.viewDistance = 16
+  renderer.viewerChunkPosition = new Vec3(0, 64, 0)
+  renderer.worldSizeParams = { minY: 0, worldHeight: 256 }
+  renderer.loadedChunks['160,0'] = true
+  return renderer
+}
+
+function sectionKeysForColumn(renderer: TestWorldRenderer, x: number, z: number): string[] {
+  const keys: string[] = []
+  const sectionHeight = renderer.getSectionHeight()
+  for (let y = renderer.worldMinYRender; y < renderer.worldSizeParams.worldHeight; y += sectionHeight) {
+    keys.push(`${x},${y},${z}`)
+  }
+  return keys
+}
+
+describe('WorldRendererCommon.removeColumn sectionsWaiting reconciliation', () => {
+  beforeEach(() => {
+    ensurePromiseWithResolvers()
+    vi.useFakeTimers()
+    vi.stubGlobal('location', { href: 'http://localhost/' })
+  })
+
+  afterEach(() => {
+    vi.useRealTimers()
+    vi.unstubAllGlobals()
+  })
+
+  test('clears sectionsWaiting when viewDistance gate blocks setSectionDirty(false)', () => {
+    const renderer = createRenderer()
+    const columnX = 160
+    const columnZ = 0
+    const sectionPos = new Vec3(columnX, 64, columnZ)
+
+    renderer.setSectionDirty(sectionPos, true)
+    expect(renderer.sectionsWaiting.get(`${columnX},64,${columnZ}`)).toBe(1)
+
+    renderer.viewDistance = 4
+    renderer.removeColumn(columnX, columnZ)
+
+    for (const key of sectionKeysForColumn(renderer, columnX, columnZ)) {
+      expect(renderer.sectionsWaiting.has(key)).toBe(false)
+    }
+  })
+
+  test('treats late sectionFinished as a no-op after removeColumn', () => {
+    const renderer = createRenderer()
+    const sectionKey = '160,64,0'
+    const debugSpy = vi.spyOn(console, 'debug').mockImplementation(() => {})
+
+    renderer.sectionsWaiting.set(sectionKey, 1)
+    renderer.viewDistance = 4
+    renderer.removeColumn(160, 0)
+
+    expect(() => {
+      renderer.handleMessage({ type: 'sectionFinished', key: sectionKey, workerIndex: 0 })
+    }).not.toThrow()
+
+    expect(renderer.sectionsWaiting.has(sectionKey)).toBe(false)
+    expect(debugSpy).toHaveBeenCalledWith(
+      expect.stringContaining('sectionFinished for non-outstanding section'),
+    )
+
+    debugSpy.mockRestore()
+  })
+
+  test('clears sectionsWaiting when unload happens before batched dirty flush', () => {
+    const renderer = createRenderer()
+    renderer.forceCallFromMesherReplayer = false
+    const columnX = 160
+    const columnZ = 0
+
+    renderer.setSectionDirty(new Vec3(columnX, 64, columnZ), true)
+    expect(renderer.sectionsWaiting.get(`${columnX},64,${columnZ}`)).toBe(1)
+
+    renderer.viewDistance = 4
+    renderer.removeColumn(columnX, columnZ)
+    vi.advanceTimersByTime(0)
+
+    for (const key of sectionKeysForColumn(renderer, columnX, columnZ)) {
+      expect(renderer.sectionsWaiting.has(key)).toBe(false)
+    }
+  })
+})

package/src/lib/worldrendererCommon.ts

@@ -424,7 +424,10 @@ export abstract class WorldRendererCommon<WorkerSend = any, WorkerReceive = any>
     }
     if (data.type === 'sectionFinished') { // on after load & unload section
       this.logWorkerWork(`<- ${data.workerIndex} sectionFinished ${data.key} ${JSON.stringify({ processTime: data.processTime })}`)
-      if (!this.sectionsWaiting.has(data.key)) throw new Error(`sectionFinished event for non-outstanding section ${data.key}`)
+      if (!this.sectionsWaiting.has(data.key)) {
+        console.debug(`sectionFinished for non-outstanding section ${data.key} (viewDistance=${this.viewDistance})`)
+        return
+      }
       this.sectionsWaiting.set(data.key, this.sectionsWaiting.get(data.key)! - 1)
       if (this.sectionsWaiting.get(data.key) === 0) {
         this.sectionsWaiting.delete(data.key)
@@ -787,9 +790,11 @@ export abstract class WorldRendererCommon<WorkerSend = any, WorkerReceive = any>
         this.sectionDirtyPendingArgs.delete(key)
       }
     }
-    for (const worker of this.workers) {
-      worker.postMessage({ type: 'unloadChunk', x, z })
+    for (let i = 0; i < this.workers.length; i++) {
+      this.toWorkerMessagesQueue[i] ??= []
+      this.toWorkerMessagesQueue[i].push({ type: 'unloadChunk', x, z })
     }
+    this.dispatchMessages()
     this.logWorkerWork(`-> unloadChunk ${JSON.stringify({ x, z })}`)
     delete this.finishedChunks[`${x},${z}`]
     this.allChunksFinished = Object.keys(this.finishedChunks).length === this.chunksLength
@@ -798,9 +803,14 @@ export abstract class WorldRendererCommon<WorkerSend = any, WorkerReceive = any>
       this.initialChunkLoadWasStartedIn = undefined
     }
     const sectionHeight = this.getSectionHeight()
-    for (let y = this.worldSizeParams.minY; y < this.worldSizeParams.worldHeight; y += sectionHeight) {
-      this.setSectionDirty(new Vec3(x, y, z), false)
-      delete this.finishedSections[`${x},${y},${z}`]
+    for (let y = this.worldMinYRender; y < this.worldSizeParams.worldHeight; y += sectionHeight) {
+      const sectionKey = `${x},${y},${z}`
+      const waitingCount = this.sectionsWaiting.get(sectionKey)
+      if (waitingCount !== undefined && waitingCount > 0) {
+        console.debug(`[removeColumn] clearing non-zero sectionsWaiting for ${sectionKey}: ${waitingCount} (chunk ${x},${z}, viewDistance=${this.viewDistance})`)
+      }
+      this.sectionsWaiting.delete(sectionKey)
+      delete this.finishedSections[sectionKey]
     }
     this.highestBlocksByChunks.delete(`${x},${z}`)
     const heightmapKey = `${Math.floor(x / 16)},${Math.floor(z / 16)}`

package/src/three/entities.ts

@@ -1393,8 +1393,20 @@ export class Entities {
         })
         .start()
     }
-    if (typeof entity.yaw === 'number' && Number.isFinite(entity.yaw)) {
-      const dy = shortestYawRadians(e.rotation.y, entity.yaw)
+    /** World yaw for the whole model: for PlayerObject skins, rotate body to head look dir; head mesh stays yaw-fixed (pitch only). */
+    let targetYaw: number | undefined
+    if (e.playerObject && overrides?.rotation?.head) {
+      const hy = overrides.rotation.head.y
+      const headYawWorld =
+        typeof hy === 'number' && Number.isFinite(hy) ? hy : entity.yaw
+      if (typeof headYawWorld === 'number' && Number.isFinite(headYawWorld)) {
+        targetYaw = headYawWorld
+      }
+    } else if (typeof entity.yaw === 'number' && Number.isFinite(entity.yaw)) {
+      targetYaw = entity.yaw
+    }
+    if (typeof targetYaw === 'number' && Number.isFinite(targetYaw)) {
+      const dy = shortestYawRadians(e.rotation.y, targetYaw)
       // Stop previous rotation tween to prevent accumulation (mirror _posTween)
       e.userData._rotTween?.stop()
       e.userData._rotTween = new TWEEN.Tween(e.rotation)
@@ -1404,14 +1416,7 @@ export class Entities {
 
     if (e?.playerObject && overrides?.rotation?.head) {
       const { playerObject } = e
-      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
+      playerObject.skin.head.rotation.y = 0
 
       const hp = overrides.rotation.head.x
       playerObject.skin.head.rotation.x =

package/src/three/menuBackground/activeView.ts

@@ -1,7 +1,7 @@
 //@ts-nocheck
 import * as THREE from 'three'
 
-/** Contract for a main-menu background implementation (classic cubemap, futuristic scene, etc.). */
+/** Contract for a main-menu background implementation (classic cubemap, v2 scene, etc.). */
 export interface MenuBackgroundView {
   readonly scene: THREE.Scene
   readonly camera: THREE.PerspectiveCamera

package/src/three/menuBackground/config.ts

@@ -1,23 +1,23 @@
 //@ts-nocheck
 import type { MenuBackgroundMode } from './types'
-import type { FuturisticCameraId, FuturisticSceneId, MinecraftBlockGroupId } from './futuristic'
+import type { V2CameraId, V2SceneId, MinecraftBlockGroupId } from './v2'
 
 /** Single source of truth for menu-background defaults (settings + runtime fallbacks). */
 export const MENU_BACKGROUND_OPTION_DEFAULTS = {
-  mode: 'futuristic' as MenuBackgroundMode,
+  mode: 'v2' as MenuBackgroundMode,
   minecraftTextures: true as boolean,
-  futuristicScene: 'light' as FuturisticSceneId,
-  futuristicCamera: 'dive' as FuturisticCameraId,
-  futuristicBlockGroup: 'stainedGlass' as MinecraftBlockGroupId,
+  v2Scene: 'light' as V2SceneId,
+  v2Camera: 'dive' as V2CameraId,
+  v2BlockGroup: 'stainedGlass' as MinecraftBlockGroupId,
   /** 0–200 (%). 100 = 1× motion. */
-  futuristicCameraSpeedPercent: 80,
-  futuristicBlockSpeedPercent: 40
+  v2CameraSpeedPercent: 80,
+  v2BlockSpeedPercent: 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)
+  camera: menuBackgroundSpeedToMultiplier(MENU_BACKGROUND_OPTION_DEFAULTS.v2CameraSpeedPercent),
+  block: menuBackgroundSpeedToMultiplier(MENU_BACKGROUND_OPTION_DEFAULTS.v2BlockSpeedPercent)
 } as const

package/src/three/menuBackground/index.ts

@@ -6,21 +6,21 @@ export type { MenuBackgroundMode, MenuBackgroundOptions } from './types'
 export { resolveMenuBackgroundMode } from './types'
 export { ClassicMenuBackground } from './classic'
 export type {
-  FuturisticSceneId,
-  FuturisticCameraId,
-  FuturisticMenuBackgroundOptions,
+  V2SceneId,
+  V2CameraId,
+  V2MenuBackgroundOptions,
   MinecraftBlockGroupId
-} from './futuristic'
+} from './v2'
 export {
-  FuturisticMenuBackground,
-  FUTURISTIC_SCENE_IDS,
-  FUTURISTIC_CAMERA_IDS,
-  FUTURISTIC_SCENE_LABELS,
-  FUTURISTIC_CAMERA_LABELS,
+  V2MenuBackground,
+  V2_SCENE_IDS,
+  V2_CAMERA_IDS,
+  V2_SCENE_LABELS,
+  V2_CAMERA_LABELS,
   MINECRAFT_BLOCK_GROUPS,
   MINECRAFT_BLOCK_GROUP_IDS,
   MINECRAFT_BLOCK_GROUP_LABELS
-} from './futuristic'
+} from './v2'
 export { WorldBlocksMenuBackground } from './worldBlocks'
 export { MenuBackgroundRenderer } from './renderer'
 export {

package/src/three/menuBackground/renderer.ts

@@ -3,14 +3,14 @@ import * as THREE from 'three'
 import type { GraphicsInitOptions } from '../../graphicsBackend/types'
 import type { DocumentRenderer } from '../documentRenderer'
 import { ClassicMenuBackground } from './classic'
-import { FuturisticMenuBackground } from './futuristic'
+import { V2MenuBackground } from './v2'
 import { WorldBlocksMenuBackground } from './worldBlocks'
 import type { MenuBackgroundView } from './activeView'
 import type { MenuBackgroundOptions } from './types'
 import { resolveMenuBackgroundMode } from './types'
 
 /**
- * Orchestrates main-menu background rendering (dispatches to classic / futuristic / world-blocks).
+ * Orchestrates main-menu background rendering (dispatches to classic / v2 / world-blocks).
  */
 export class MenuBackgroundRenderer {
   private active?: MenuBackgroundView
@@ -27,9 +27,9 @@ export class MenuBackgroundRenderer {
     this.mode = resolveMenuBackgroundMode(menuBackgroundOptions, singleFileBuild)
   }
 
-  /** Active futuristic instance when that style is running. */
-  get futuristic(): FuturisticMenuBackground | undefined {
-    return this.active instanceof FuturisticMenuBackground ? this.active : undefined
+  /** Active v2 instance when that style is running. */
+  get v2(): V2MenuBackground | undefined {
+    return this.active instanceof V2MenuBackground ? this.active : undefined
   }
 
   get scene(): THREE.Scene | undefined {
@@ -64,16 +64,16 @@ export class MenuBackgroundRenderer {
 
   private createImplementation(options: MenuBackgroundOptions): MenuBackgroundView {
     switch (this.mode) {
-      case 'futuristic':
-        return new FuturisticMenuBackground(
+      case 'v2':
+        return new V2MenuBackground(
           this.documentRenderer,
           {
             useMinecraftTextures: options.useMinecraftTextures,
-            initialScene: options.futuristicScene,
-            initialCamera: options.futuristicCamera,
-            initialBlockGroup: options.futuristicBlockGroup,
-            initialCameraSpeed: options.futuristicCameraSpeed,
-            initialBlockSpeed: options.futuristicBlockSpeed,
+            initialScene: options.v2Scene,
+            initialCamera: options.v2Camera,
+            initialBlockGroup: options.v2BlockGroup,
+            initialCameraSpeed: options.v2CameraSpeed,
+            initialBlockSpeed: options.v2BlockSpeed,
             resourcesManager: options.resourcesManager
           },
           this.abortController.signal

package/src/three/menuBackground/types.ts

@@ -1,25 +1,25 @@
 //@ts-nocheck
 import type { ResourcesManager } from '../../resourcesManager/resourcesManager'
-import type { FuturisticCameraId, FuturisticSceneId, MinecraftBlockGroupId } from './futuristic'
+import type { V2CameraId, V2SceneId, MinecraftBlockGroupId } from './v2'
 import { MENU_BACKGROUND_OPTION_DEFAULTS } from './config'
 
-export type { FuturisticCameraId, FuturisticSceneId, MinecraftBlockGroupId } from './futuristic'
+export type { V2CameraId, V2SceneId, MinecraftBlockGroupId } from './v2'
 
-export type MenuBackgroundMode = 'classic' | 'futuristic' | 'worldBlocks'
+export type MenuBackgroundMode = 'classic' | 'v2' | 'worldBlocks'
 
 export interface MenuBackgroundOptions {
   /** Visual style. Defaults to {@link MENU_BACKGROUND_OPTION_DEFAULTS.mode}, or `worldBlocks` in single-file build. */
   mode?: MenuBackgroundMode
-  /** Futuristic style: load block atlas and render textured cubes (requires assets / mcData). */
+  /** V2 style: load block atlas and render textured cubes (requires assets / mcData). */
   useMinecraftTextures?: boolean
-  futuristicScene?: FuturisticSceneId
-  futuristicCamera?: FuturisticCameraId
+  v2Scene?: V2SceneId
+  v2Camera?: V2CameraId
   /** Block pool when {@link useMinecraftTextures} is enabled. */
-  futuristicBlockGroup?: MinecraftBlockGroupId
+  v2BlockGroup?: MinecraftBlockGroupId
   /** Camera path speed (1 = 100%). */
-  futuristicCameraSpeed?: number
+  v2CameraSpeed?: number
   /** Block fly-through + sky drift speed (1 = 100%). */
-  futuristicBlockSpeed?: number
+  v2BlockSpeed?: number
   /**
    * Optional shared resource manager (e.g. appViewer.resourcesManager).
    * Caller should run `updateAssetsData` after mcData is loaded when using textured cubes.