minecraft-renderer 0.1.0

package/src/index.ts

@@ -0,0 +1,97 @@
+/**
+ * Minecraft Renderer
+ *
+ * A modular Minecraft world renderer with Three.js WebGL backend.
+ *
+ * ## Quick Start
+ *
+ * ```typescript
+ * import { AppViewer, createGraphicsBackend } from 'minecraft-renderer'
+ * import { WorldView } from 'minecraft-renderer'
+ *
+ * // Create viewer
+ * const viewer = new AppViewer()
+ *
+ * // Load backend
+ * await viewer.loadBackend(createGraphicsBackend)
+ *
+ * // Start world
+ * await viewer.startWorld(world, renderDistance)
+ * ```
+ *
+ * ## Architecture
+ *
+ * The renderer is split into several modules:
+ *
+ * - **Core**: Types, configuration, player state, world view
+ * - **Three.js Backend**: WebGL rendering using Three.js
+ * - **Playground**: Testing and development environment
+ */
+
+// ============================================================================
+// Graphics Backend (Core)
+// ============================================================================
+export * from './graphicsBackend'
+
+// ============================================================================
+// World View
+// ============================================================================
+export {
+  WorldView,
+  WorldViewWorker,
+  chunkPos,
+  sectionPos,
+  generateSpiralMatrix,
+  delayedIterator
+} from './worldView'
+export type { WorldProvider } from './worldView'
+
+// ============================================================================
+// Player State
+// ============================================================================
+export {
+  getInitialPlayerState,
+  getPlayerStateUtils,
+  getInitialPlayerStateRenderer
+} from './playerState/playerState'
+
+// ============================================================================
+// Resource Manager
+// ============================================================================
+export {
+  ResourcesManager,
+  LoadedResourcesTransferrable
+} from './resourcesManager'
+
+// ============================================================================
+// Modules System
+// ============================================================================
+export * from './modules'
+
+// ============================================================================
+// Three.js Backend (re-exported for convenience)
+// ============================================================================
+export {
+  createGraphicsBackend,
+  createGraphicsBackendBase
+} from './three/graphicsBackend'
+
+export {
+  DocumentRenderer,
+  addCanvasForWorker,
+  isWebWorker
+} from './three/documentRenderer'
+
+// export {
+//   WorldGeometryHandler,
+//   estimateGeometryMemoryUsage,
+//   disposeObject
+// } from './three/worldGeometryHandler'
+
+export { StarField } from './three/starField'
+
+// ============================================================================
+// Examples (for reference and testing)
+// ============================================================================
+export { AppViewerExample, runExample } from './examples/appViewerExample'
+export { appViewer, initialMenuStart, initialize } from './examples/initialMenuStart'

package/src/lib/DebugGui.ts

@@ -0,0 +1,190 @@
+// eslint-disable-next-line import/no-named-as-default
+import GUI from 'lil-gui'
+import { isWebWorker } from '../three/documentRenderer'
+
+export interface ParamMeta {
+  min?: number
+  max?: number
+  step?: number
+}
+
+export class DebugGui {
+  private gui: GUI | null = null
+  private readonly storageKey: string = ''
+  private target: any
+  private readonly params: string[] = []
+  private readonly paramsMeta: Record<string, ParamMeta> = {}
+  private _visible = false // Default to not visible
+  private readonly initialValues: Record<string, any> = {} // Store initial values
+  private initialized = false
+
+  constructor (id: string, target: any, params?: string[], paramsMeta?: Record<string, ParamMeta>) {
+    // If in web worker, don't initialize anything
+    if (isWebWorker) return
+
+    this.gui = new GUI()
+    this.storageKey = `debug_params_${id}`
+    this.target = target
+    this.paramsMeta = paramsMeta ?? {}
+    this.params = params ?? Object.keys(target)
+
+    // Store initial values
+    for (const param of this.params) {
+      this.initialValues[param] = target[param]
+    }
+
+    // Hide by default
+    this.gui.domElement.style.display = 'none'
+  }
+
+  // Initialize and show the GUI
+  activate () {
+    if (isWebWorker) return this
+
+    if (!this.initialized && this.gui) {
+      this.loadSavedValues()
+      this.setupControls()
+      this.initialized = true
+    }
+    this.show()
+    return this
+  }
+
+  // Getter for visibility
+  get visible (): boolean {
+    if (isWebWorker) return false
+    return this._visible
+  }
+
+  // Setter for visibility
+  set visible (value: boolean) {
+    if (isWebWorker || !this.gui) return
+    this._visible = value
+    this.gui.domElement.style.display = value ? 'block' : 'none'
+    this.saveVisibility()
+  }
+
+  private loadSavedValues () {
+    if (isWebWorker) return
+    try {
+      const saved = localStorage.getItem(this.storageKey)
+      if (saved) {
+        const values = JSON.parse(saved)
+        // Apply saved values to target
+        for (const param of this.params) {
+          if (param in values) {
+            const value = values[param]
+            if (value !== null) {
+              this.target[param] = value
+            }
+          }
+        }
+      }
+    } catch (e) {
+      console.warn('Failed to load debug values:', e)
+    }
+  }
+
+  private saveValues (deleteKey = false) {
+    if (isWebWorker) return
+    try {
+      const values = {}
+      for (const param of this.params) {
+        values[param] = this.target[param]
+      }
+      if (deleteKey) {
+        localStorage.removeItem(this.storageKey)
+      } else {
+        localStorage.setItem(this.storageKey, JSON.stringify(values))
+      }
+    } catch (e) {
+      console.warn('Failed to save debug values:', e)
+    }
+  }
+
+  private saveVisibility () {
+    if (isWebWorker) return
+    try {
+      localStorage.setItem(`${this.storageKey}_visible`, this._visible.toString())
+    } catch (e) {
+      console.warn('Failed to save debug visibility:', e)
+    }
+  }
+
+  private setupControls () {
+    if (isWebWorker || !this.gui) return
+
+    // Add visibility toggle at the top
+    this.gui.add(this, 'visible').name('Show Controls')
+    this.gui.add({ resetAll: () => {
+      if (!this.gui) return
+      for (const param of this.params) {
+        this.target[param] = this.initialValues[param]
+      }
+      this.saveValues(true)
+      this.gui.destroy()
+      this.gui = new GUI()
+      this.setupControls()
+    } }, 'resetAll').name('Reset All Parameters')
+
+    for (const param of this.params) {
+      const value = this.target[param]
+      const meta = this.paramsMeta[param] ?? {}
+
+      if (typeof value === 'number') {
+        // For numbers, use meta values or calculate reasonable defaults
+        const min = meta.min ?? value - Math.abs(value * 2)
+        const max = meta.max ?? value + Math.abs(value * 2)
+        const step = meta.step ?? Math.abs(value) / 100
+
+        this.gui.add(this.target, param, min, max, step)
+          .onChange(() => this.saveValues())
+      } else if (typeof value === 'boolean') {
+        // For booleans, create a checkbox
+        this.gui.add(this.target, param)
+          .onChange(() => this.saveValues())
+      } else if (typeof value === 'string' && ['x', 'y', 'z'].includes(param)) {
+        // Special case for xyz coordinates
+        const min = meta.min ?? -10
+        const max = meta.max ?? 10
+        const step = meta.step ?? 0.1
+
+        this.gui.add(this.target, param, min, max, step)
+          .onChange(() => this.saveValues())
+      } else if (Array.isArray(value)) {
+        // For arrays, create a dropdown
+        this.gui.add(this.target, param, value)
+          .onChange(() => this.saveValues())
+      }
+    }
+  }
+
+  // Method to manually trigger save
+  save () {
+    if (isWebWorker) return
+    this.saveValues()
+    this.saveVisibility()
+  }
+
+  // Method to destroy the GUI and clean up
+  destroy () {
+    if (isWebWorker || !this.gui) return
+    this.saveVisibility()
+    this.gui.destroy()
+  }
+
+  // Toggle visibility
+  toggle () {
+    this.visible = !this.visible
+  }
+
+  // Show the GUI
+  show () {
+    this.visible = true
+  }
+
+  // Hide the GUI
+  hide () {
+    this.visible = false
+  }
+}

package/src/lib/animationController.ts

@@ -0,0 +1,85 @@
+import * as tweenJs from '@tweenjs/tween.js'
+
+export class AnimationController {
+  private currentAnimation: tweenJs.Group | null = null
+  private isAnimating = false
+  private cancelRequested = false
+  private completionCallbacks: Array<() => void> = []
+  private currentCancelCallback: (() => void) | null = null
+
+  /** Main method */
+  async startAnimation (createAnimation: () => tweenJs.Group, onCancelled?: () => void): Promise<void> {
+    if (this.isAnimating) {
+      await this.cancelCurrentAnimation()
+    }
+
+    return new Promise((resolve) => {
+      this.isAnimating = true
+      this.cancelRequested = false
+      this.currentCancelCallback = onCancelled ?? null
+      this.currentAnimation = createAnimation()
+
+      this.completionCallbacks.push(() => {
+        this.isAnimating = false
+        this.currentAnimation = null
+        resolve()
+      })
+    })
+  }
+
+  /** Main method */
+  async cancelCurrentAnimation (): Promise<void> {
+    if (!this.isAnimating) return
+
+    if (this.currentCancelCallback) {
+      const callback = this.currentCancelCallback
+      this.currentCancelCallback = null
+      callback()
+    }
+
+    return new Promise((resolve) => {
+      this.cancelRequested = true
+      this.completionCallbacks.push(() => {
+        resolve()
+      })
+    })
+  }
+
+  animationCycleFinish () {
+    if (this.cancelRequested) this.forceFinish()
+  }
+
+  forceFinish (callComplete = true) {
+    if (!this.isAnimating) return
+
+    if (this.currentAnimation) {
+      for (const tween of this.currentAnimation.getAll()) tween.stop()
+      this.currentAnimation.removeAll()
+      this.currentAnimation = null
+    }
+
+    this.isAnimating = false
+    this.cancelRequested = false
+
+    const callbacks = [...this.completionCallbacks]
+    this.completionCallbacks = []
+    if (callComplete) {
+      for (const cb of callbacks) cb()
+    }
+  }
+
+  /** Required method */
+  update () {
+    if (this.currentAnimation) {
+      this.currentAnimation.update()
+    }
+  }
+
+  get isActive () {
+    return this.isAnimating
+  }
+
+  get shouldCancel () {
+    return this.cancelRequested
+  }
+}

package/src/lib/buildSharedConfig.mjs

@@ -0,0 +1 @@
+export const dynamicMcDataFiles = ['blocks', 'blockCollisionShapes', 'biomes', 'version']

package/src/lib/cameraBobbing.ts

@@ -0,0 +1,94 @@
+export class CameraBobbing {
+  private walkDistance = 0
+  private prevWalkDistance = 0
+  private bobAmount = 0
+  private prevBobAmount = 0
+  private readonly gameTimer = new GameTimer()
+
+  // eslint-disable-next-line max-params
+  constructor (
+    private readonly BOB_FREQUENCY: number = Math.PI, // How fast the bob cycles
+    private readonly BOB_BASE_AMPLITUDE: number = 0.5, // Base amplitude of the bob
+    private readonly VERTICAL_MULTIPLIER: number = 1, // Vertical movement multiplier
+    private readonly ROTATION_MULTIPLIER_Z: number = 3, // Roll rotation multiplier
+    private readonly ROTATION_MULTIPLIER_X: number = 5 // Pitch rotation multiplier
+  ) {}
+
+  // Call this when player is moving
+  public updateWalkDistance (distance: number): void {
+    this.prevWalkDistance = this.walkDistance
+    this.walkDistance = distance
+  }
+
+  // Call this when player is moving to update bob amount
+  public updateBobAmount (isMoving: boolean): void {
+    const targetBob = isMoving ? 1 : 0
+    this.prevBobAmount = this.bobAmount
+
+    // Update timing
+    const ticks = this.gameTimer.update()
+    const deltaTime = ticks / 20 // Convert ticks to seconds assuming 20 TPS
+
+    // Smooth transition for bob amount
+    const bobDelta = (targetBob - this.bobAmount) * Math.min(1, deltaTime * 10)
+    this.bobAmount += bobDelta
+  }
+
+  // Call this in your render/animation loop
+  public getBobbing (): { position: { x: number, y: number }, rotation: { x: number, z: number } } {
+    // Interpolate walk distance
+    const walkDist = this.prevWalkDistance +
+      (this.walkDistance - this.prevWalkDistance) * this.gameTimer.partialTick
+
+    // Interpolate bob amount
+    const bob = this.prevBobAmount +
+      (this.bobAmount - this.prevBobAmount) * this.gameTimer.partialTick
+
+    // Calculate total distance for bob cycle
+    const totalDist = -(walkDist * this.BOB_FREQUENCY)
+
+    // Calculate offsets
+    const xOffset = Math.sin(totalDist) * bob * this.BOB_BASE_AMPLITUDE
+    const yOffset = -Math.abs(Math.cos(totalDist) * bob) * this.VERTICAL_MULTIPLIER
+
+    // Calculate rotations (in radians)
+    const zRot = (Math.sin(totalDist) * bob * this.ROTATION_MULTIPLIER_Z) * (Math.PI / 180)
+    const xRot = (Math.abs(Math.cos(totalDist - 0.2) * bob) * this.ROTATION_MULTIPLIER_X) * (Math.PI / 180)
+
+    return {
+      position: { x: xOffset, y: yOffset },
+      rotation: { x: xRot, z: zRot }
+    }
+  }
+}
+
+class GameTimer {
+  private readonly msPerTick: number
+  private lastMs: number
+  public partialTick = 0
+
+  constructor (tickRate = 20) {
+    this.msPerTick = 1000 / tickRate
+    this.lastMs = performance.now()
+  }
+
+  update (): number {
+    const currentMs = performance.now()
+    const deltaSinceLastTick = currentMs - this.lastMs
+
+    // Calculate how much of a tick has passed
+    const tickDelta = deltaSinceLastTick / this.msPerTick
+    this.lastMs = currentMs
+
+    // Add to accumulated partial ticks
+    this.partialTick += tickDelta
+
+    // Get whole number of ticks that should occur
+    const wholeTicks = Math.floor(this.partialTick)
+
+    // Keep the remainder as the new partial tick
+    this.partialTick -= wholeTicks
+
+    return wholeTicks
+  }
+}