minecraft-renderer 0.1.0

package/src/graphicsBackend/appViewer.ts

@@ -0,0 +1,297 @@
+/**
+ * AppViewer - Base application viewer for Minecraft renderer.
+ *
+ * This is the main entry point for integrating the renderer into an application.
+ * It manages:
+ * - Graphics backend loading and lifecycle
+ * - World view management
+ * - Player state
+ * - Renderer state
+ */
+
+import { Vec3 } from 'vec3'
+import { proxy } from 'valtio'
+import type {
+  GraphicsBackend,
+  GraphicsBackendConfig,
+  GraphicsBackendLoader,
+  GraphicsInitOptions,
+  DisplayWorldOptions,
+  RendererReactiveState,
+  NonReactiveState
+} from './types'
+import { WorldView, WorldProvider, WorldViewWorker } from '../worldView'
+import { getInitialPlayerState } from './playerState'
+import { defaultWorldRendererConfig, defaultGraphicsBackendConfig, getDefaultRendererState } from './config'
+import type { WorldRendererConfig } from '../lib/worldrendererCommon'
+import { PlayerStateReactive } from '@/playerState/playerState'
+import { ResourcesManager, ResourcesManagerTransferred } from '@/resourcesManager'
+
+export interface AppViewerOptions {
+  config?: Partial<GraphicsBackendConfig>
+  rendererConfig?: Partial<WorldRendererConfig>
+}
+
+/**
+ * AppViewer - Main application viewer class.
+ *
+ * This is designed to be extended for specific use cases (game client, playground, etc.)
+ */
+export class AppViewer {
+  waitBackendLoadPromises: Promise<void>[] = []
+
+  // World view
+  worldView?: WorldView
+
+  // Configuration
+  readonly config: GraphicsBackendConfig
+  readonly inWorldRenderingConfig: WorldRendererConfig
+
+  // Backend
+  backend?: GraphicsBackend
+  backendLoader?: GraphicsBackendLoader
+  private currentState?: {
+    method: string
+    args: any[]
+  }
+
+  // Display state
+  currentDisplay: 'menu' | 'world' | null = null
+
+  // Player state
+  playerState = {
+    reactive: getInitialPlayerState()
+  }
+
+  // Renderer state
+  rendererState: RendererReactiveState
+  nonReactiveState: NonReactiveState
+
+  // World ready promise
+  worldReady!: Promise<void>
+  private resolveWorldReady!: () => void
+
+  // Timing
+  lastCamUpdate = 0
+
+  constructor(options: AppViewerOptions = {}, public resourcesManager: ResourcesManager = new ResourcesManager()) {
+    this.config = {
+      ...defaultGraphicsBackendConfig,
+      ...options.config
+    }
+
+    this.inWorldRenderingConfig = proxy({
+      ...defaultWorldRendererConfig,
+      ...options.rendererConfig
+    })
+
+    const defaultState = getDefaultRendererState()
+    this.rendererState = defaultState.reactive
+    this.nonReactiveState = defaultState.nonReactive
+
+    this.initWorldReadyPromise()
+  }
+
+  private initWorldReadyPromise(): void {
+    const { promise, resolve } = Promise.withResolvers<void>()
+    this.worldReady = promise
+    this.resolveWorldReady = resolve
+  }
+
+  /**
+   * Load a graphics backend.
+   */
+  async loadBackend(loader: GraphicsBackendLoader): Promise<void> {
+    if (this.backend) {
+      this.disconnectBackend()
+    }
+
+    await Promise.all(this.waitBackendLoadPromises)
+    this.waitBackendLoadPromises = []
+
+    this.backendLoader = loader
+
+    const loaderOptions: GraphicsInitOptions = { // todo!
+      resourcesManager: this.resourcesManager! as unknown as ResourcesManagerTransferred,
+      config: this.config,
+      callbacks: {
+        displayCriticalError: (error) => {
+          console.error('[AppViewer] Critical error:', error)
+        },
+        setRendererSpecificSettings: (key, value) => {
+          // Override in implementation
+        },
+        fireCustomEvent: (eventName, ...args) => {
+          // Override in implementation
+        }
+      },
+      rendererSpecificSettings: {}
+    }
+
+    const backendResult = loader(loaderOptions)
+    this.backend = await Promise.resolve(backendResult)
+
+    // Execute queued action if exists
+    if (this.currentState) {
+      if (this.currentState.method === 'startPanorama') {
+        this.startPanorama()
+      } else {
+        const { method, args } = this.currentState
+          ; (this.backend as any)[method](...args)
+      }
+    }
+  }
+
+  /**
+   * Start the world with a given world provider and render distance.
+   */
+  async startWorld(
+    world: WorldProvider,
+    renderDistance: number,
+    playerStateReactive: PlayerStateReactive = this.playerState.reactive,
+    startPosition?: Vec3
+  ): Promise<boolean> {
+    if (this.currentDisplay === 'world') {
+      throw new Error('World already started')
+    }
+
+    this.currentDisplay = 'world'
+    const finalStartPosition = startPosition ?? new Vec3(0, 64, 0)
+
+    this.worldView = new WorldView(world, renderDistance, finalStartPosition)
+    this.worldView.isPlayground = this.inWorldRenderingConfig.isPlayground
+
+    const displayWorldOptions: DisplayWorldOptions = {
+      version: this.resourcesManager?.currentConfig?.version ?? '1.20.4',
+      worldView: this.worldView as unknown as WorldViewWorker,
+      inWorldRenderingConfig: this.inWorldRenderingConfig,
+      playerStateReactive,
+      rendererState: this.rendererState,
+      nonReactiveState: this.nonReactiveState
+    }
+
+    let promise: Promise<void> | undefined
+    if (this.backend) {
+      const result = this.backend.startWorld(displayWorldOptions)
+      if (result && typeof result.then === 'function') {
+        promise = result
+      }
+    }
+
+    this.currentState = { method: 'startWorld', args: [displayWorldOptions] }
+
+    await promise
+    this.resolveWorldReady()
+    return !!promise
+  }
+
+  /**
+   * Start panorama display (menu background).
+   */
+  startPanorama(): void {
+    if (this.currentDisplay === 'menu') return
+
+    if (this.backend) {
+      this.currentDisplay = 'menu'
+      this.backend.startPanorama()
+    }
+
+    this.currentState = { method: 'startPanorama', args: [] }
+  }
+
+  /**
+   * Reset the backend.
+   */
+  resetBackend(cleanState = false): void {
+    this.disconnectBackend(cleanState)
+    if (this.backendLoader) {
+      void this.loadBackend(this.backendLoader)
+    }
+  }
+
+  /**
+   * Disconnect the backend.
+   */
+  disconnectBackend(cleanState = false): void {
+    if (cleanState) {
+      this.currentState = undefined
+      this.currentDisplay = null
+      this.worldView = undefined
+    }
+
+    if (this.backend) {
+      this.backend.disconnect()
+      this.backend = undefined
+    }
+
+    this.currentDisplay = null
+    this.initWorldReadyPromise()
+    this.rendererState = proxy(getDefaultRendererState().reactive)
+    this.nonReactiveState = getDefaultRendererState().nonReactive
+  }
+
+  /**
+   * Update camera position and rotation.
+   */
+  updateCamera(pos: Vec3 | null, yaw: number, pitch: number): void {
+    this.backend?.updateCamera(pos, yaw, pitch)
+  }
+
+  /**
+   * Set rendering active/paused.
+   */
+  setRendering(rendering: boolean): void {
+    this.backend?.setRendering(rendering)
+  }
+
+  /**
+   * Start world with bot (convenience method).
+   */
+  async startWithBot(bot: any, renderDistance: number): Promise<void> {
+    await this.startWorld(bot.world, renderDistance)
+    if (this.worldView) {
+      // Listen to bot events if worldView supports it
+      if (typeof (this.worldView as any).listenToBot === 'function') {
+        (this.worldView as any).listenToBot(bot)
+      }
+    }
+  }
+
+  /**
+   * Destroy all resources including resource manager.
+   */
+  destroyAll(): void {
+    this.disconnectBackend(true)
+    if (this.resourcesManager && typeof (this.resourcesManager as any).destroy === 'function') {
+      (this.resourcesManager as any).destroy()
+    }
+  }
+
+  /**
+   * Get utility methods.
+   */
+  get utils() {
+    const backend = this.backend
+    return {
+      async waitingForChunks(): Promise<void> {
+        if ((backend as any)?.worldState?.allChunksLoaded) return
+
+        return new Promise<void>((resolve) => {
+          const interval = setInterval(() => {
+            if ((backend as any)?.worldState?.allChunksLoaded) {
+              clearInterval(interval)
+              resolve()
+            }
+          }, 100)
+        })
+      }
+    }
+  }
+
+  /**
+   * Destroy the viewer and cleanup resources.
+   */
+  destroy(): void {
+    this.disconnectBackend(true)
+  }
+}

package/src/graphicsBackend/config.ts

@@ -0,0 +1,119 @@
+/**
+ * Default configurations for the graphics backend and world renderer.
+ */
+
+import { proxy } from 'valtio'
+import type {
+  WorldRendererConfig,
+  GraphicsBackendConfig,
+  RendererReactiveState,
+  NonReactiveState
+} from './types'
+
+/**
+ * Default world renderer configuration.
+ * These settings control rendering behavior and visual options.
+ */
+export const defaultWorldRendererConfig: WorldRendererConfig = {
+  paused: false,
+
+  // Debug settings
+  showChunkBorders: false,
+  enableDebugOverlay: false,
+  debugModelVariant: undefined,
+
+  // Performance settings
+  mesherWorkers: 4,
+  addChunksBatchWaitTime: 200,
+  _experimentalSmoothChunkLoading: true,
+  _renderByChunks: false,
+
+  // Rendering engine settings
+  dayCycle: true,
+  smoothLighting: true,
+  enableLighting: true,
+  starfield: true,
+  defaultSkybox: true,
+  renderEntities: true,
+  extraBlockRenderers: true,
+  foreground: true,
+  fov: 75,
+  volume: 1,
+
+  // Camera visual related settings
+  showHand: false,
+  viewBobbing: false,
+  renderEars: true,
+  highlightBlockColor: 'blue',
+
+  // Player models
+  fetchPlayerSkins: true,
+  skinTexturesProxy: undefined,
+
+  // VR settings
+  vrSupport: true,
+  vrPageGameRendering: true,
+
+  // World settings
+  clipWorldBelowY: undefined,
+  isPlayground: false,
+  instantCameraUpdate: false
+}
+
+/**
+ * Default graphics backend configuration.
+ */
+export const defaultGraphicsBackendConfig: GraphicsBackendConfig = {
+  fpsLimit: undefined,
+  powerPreference: undefined,
+  sceneBackground: 'lightblue',
+  timeoutRendering: false
+}
+
+/**
+ * Creates a new proxied world renderer config with default values.
+ */
+export const createWorldRendererConfig = (overrides: Partial<WorldRendererConfig> = {}): WorldRendererConfig => {
+  return proxy({
+    ...defaultWorldRendererConfig,
+    ...overrides
+  })
+}
+
+/**
+ * Get default renderer reactive state.
+ */
+export const getDefaultRendererState = (): {
+  reactive: RendererReactiveState
+  nonReactive: NonReactiveState
+} => {
+  return {
+    reactive: proxy({
+      world: {
+        chunksLoaded: new Set<string>(),
+        heightmaps: new Map<string, Uint8Array>(),
+        allChunksLoaded: false,
+        mesherWork: false,
+        intersectMedia: null
+      },
+      renderer: '...',
+      preventEscapeMenu: false
+    }),
+    nonReactive: {
+      fps: 0,
+      worstRenderTime: 0,
+      avgRenderTime: 0,
+      world: {
+        chunksLoaded: new Set(),
+        chunksTotalNumber: 0
+      },
+      renderer: {
+        timeline: {
+          live: [],
+          frozen: [],
+          lastSecond: []
+        }
+      }
+    }
+  }
+}

package/src/graphicsBackend/index.ts

@@ -0,0 +1,10 @@
+/**
+ * Graphics Backend Module
+ *
+ * Main entry point for the graphics backend system.
+ */
+
+export * from './types'
+export * from './config'
+export * from './playerState'
+export * from './appViewer'

package/src/graphicsBackend/playerState.ts

@@ -0,0 +1,61 @@
+/**
+ * Player State - Initial player state for renderer.
+ */
+
+import { proxy } from 'valtio'
+import type { PlayerStateReactive } from './types'
+
+/**
+ * Get initial player state with default values.
+ */
+export const getInitialPlayerState = (): PlayerStateReactive => proxy({
+  playerSkin: undefined,
+  inWater: false,
+  waterBreathing: false,
+  backgroundColor: [0, 0, 0] as [number, number, number],
+  ambientLight: 0,
+  directionalLight: 0,
+  eyeHeight: 0,
+  gameMode: undefined,
+  lookingAtBlock: undefined,
+  diggingBlock: undefined,
+  movementState: 'NOT_MOVING',
+  onGround: true,
+  sneaking: false,
+  flying: false,
+  sprinting: false,
+  itemUsageTicks: 0,
+  username: '',
+  onlineMode: false,
+  lightingDisabled: false,
+  shouldHideHand: false,
+  heldItemMain: undefined,
+  heldItemOff: undefined,
+  perspective: 'first_person',
+  onFire: false,
+  cameraSpectatingEntity: undefined,
+  team: undefined,
+})
+
+/**
+ * Get player state utils.
+ */
+export const getPlayerStateUtils = (reactive: PlayerStateReactive) => ({
+  isSpectator() {
+    return reactive.gameMode === 'spectator'
+  },
+  isSpectatingEntity() {
+    return reactive.cameraSpectatingEntity !== undefined && reactive.gameMode === 'spectator'
+  },
+  isThirdPerson() {
+    if (this.isSpectatingEntity()) return false
+    return reactive.perspective === 'third_person_back' || reactive.perspective === 'third_person_front'
+  }
+})
+
+/**
+ * Get initial player state for renderer.
+ */
+export const getInitialPlayerStateRenderer = () => ({
+  reactive: getInitialPlayerState()
+})

package/src/graphicsBackend/types.ts

@@ -0,0 +1,143 @@
+/**
+ * Graphics Backend Types
+ *
+ * Core types for the graphics backend system.
+ */
+
+import { WorldRendererConfig } from '@/lib/worldrendererCommon'
+import { PlayerStateReactive } from '@/playerState/playerState'
+import { ResourcesManagerTransferred } from '@/resourcesManager'
+import { WorldViewWorker } from '@/worldView'
+import { Vec3 } from 'vec3'
+
+// ============================================================================
+// Graphics Backend Configuration
+// ============================================================================
+
+export type MaybePromise<T> = Promise<T> | T
+
+export interface SoundSystem {
+  playSound: (position: { x: number, y: number, z: number }, path: string, volume?: number, pitch?: number, timeout?: number) => void
+  destroy: () => void
+}
+
+/** Graphics backend configuration */
+export interface GraphicsBackendConfig {
+  fpsLimit?: number
+  powerPreference?: 'high-performance' | 'low-power'
+  statsVisible?: number
+  sceneBackground: string
+  timeoutRendering?: boolean
+}
+
+// ============================================================================
+// World Renderer Configuration
+// ============================================================================
+
+// ============================================================================
+// State Types
+// ============================================================================
+
+/** Frame timing event for performance monitoring */
+export interface FrameTimingEvent {
+  type: 'frameStart' | 'frameEnd' | 'cameraUpdate' | 'frameDisplay'
+  timestamp: number
+  duration?: number
+}
+
+/** Non-reactive state for performance data */
+export interface NonReactiveState {
+  fps: number
+  worstRenderTime: number
+  avgRenderTime: number
+  world: {
+    chunksLoaded: Set<string>
+    chunksTotalNumber: number
+    allChunksLoaded?: boolean
+  }
+  renderer: {
+    timeline: {
+      live: FrameTimingEvent[]
+      frozen: FrameTimingEvent[]
+      lastSecond: FrameTimingEvent[]
+    }
+  }
+}
+
+/** Renderer reactive state */
+export interface RendererReactiveState {
+  world: {
+    chunksLoaded: Set<string>
+    heightmaps: Map<string, Uint8Array>
+    allChunksLoaded: boolean
+    mesherWork: boolean
+    intersectMedia: any | null
+  }
+  renderer: string
+  preventEscapeMenu: boolean
+}
+
+// ============================================================================
+// Player State Types
+// ============================================================================
+
+// ============================================================================
+// Graphics Backend Interfaces
+// ============================================================================
+
+/** Graphics initialization options */
+export interface GraphicsInitOptions<S = any> {
+  resourcesManager: ResourcesManagerTransferred
+  config: GraphicsBackendConfig
+  rendererSpecificSettings: S
+  callbacks: {
+    displayCriticalError: (error: Error) => void
+    setRendererSpecificSettings: (key: string, value: any) => void
+    fireCustomEvent: (eventName: string, ...args: any[]) => void
+  }
+}
+
+/** Display world options for starting world rendering */
+export interface DisplayWorldOptions {
+  version: string
+  worldView: WorldViewWorker
+  inWorldRenderingConfig: WorldRendererConfig
+  playerStateReactive: PlayerStateReactive
+  rendererState: RendererReactiveState
+  nonReactiveState: NonReactiveState
+}
+
+/** Graphics backend interface */
+export interface GraphicsBackend {
+  id: string
+  displayName: string
+  startPanorama(): Promise<void>
+  startWorld(options: DisplayWorldOptions): Promise<void>
+  disconnect(): void
+  setRendering(rendering: boolean): void
+  updateCamera(pos: Vec3 | null, yaw: number, pitch: number): void
+  soundSystem?: any
+  backendMethods?: any
+  getDebugOverlay?(): { entitiesString?: string }
+}
+
+/** Graphics backend loader function type */
+export type GraphicsBackendLoader = ((options: GraphicsInitOptions) => MaybePromise<GraphicsBackend>) & {
+  id: string
+}
+
+// ============================================================================
+// World View Interface
+// ============================================================================
+
+/** World view interface for type compatibility */
+export interface WorldViewLike {
+  isPlayground?: boolean
+  addWaitTime?: number
+  loadedChunks: Record<string, boolean>
+  init(pos: Vec3): Promise<void>
+  setBlockStateId(pos: Vec3, stateId: number): void
+  unloadAllChunks(): void
+  emit(event: string, ...args: any[]): boolean
+  on(event: string, callback: (...args: any[]) => void): void
+}