minecraft-renderer 0.1.0

package/README.md

@@ -0,0 +1,297 @@
+# Minecraft Renderer
+
+![Minecraft Renderer](./logo.webp)
+
+A modular Minecraft world renderer with Three.js WebGL backend. Designed for performance testing, experimentation, and integration into Minecraft clients.
+
+## Architecture Overview
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                         AppViewer                                │
+│  - Manages graphics backend lifecycle                            │
+│  - Handles world view and player state                           │
+│  - Coordinates between data and rendering                        │
+└─────────────────────────────────────────────────────────────────┘
+                               │
+                               ▼
+┌─────────────────────────────────────────────────────────────────┐
+│                     GraphicsBackend (Three.js)                   │
+│  - WebGL rendering via Three.js                                  │
+│  - Scene, camera, and lighting management                        │
+│  - Mesher worker coordination                                    │
+└─────────────────────────────────────────────────────────────────┘
+                               │
+          ┌────────────────────┼────────────────────┐
+          ▼                    ▼                    ▼
+┌──────────────────┐  ┌──────────────────┐  ┌──────────────────┐
+│ DocumentRenderer │  │WorldGeometryHandler│ │    StarField     │
+│ - Render loop    │  │ - Chunk meshes    │  │ - Night sky      │
+│ - Canvas sizing  │  │ - GPU memory      │  │ - Twinkling      │
+│ - FPS tracking   │  │ - Signs/banners   │  │   effect         │
+└──────────────────┘  └──────────────────┘  └──────────────────┘
+```
+
+## Core Components
+
+### WorldView (formerly WorldDataEmitter)
+
+Manages chunk loading/unloading and emits world events to the renderer.
+
+```typescript
+import { WorldView } from 'minecraft-renderer'
+
+// Create world view with a world provider
+const worldView = new WorldView(worldProvider, renderDistance, startPosition)
+
+// Initialize and start loading chunks
+await worldView.init(playerPosition)
+
+// Update position (loads/unloads chunks as needed)
+await worldView.updatePosition(newPosition)
+
+// Set block and emit update
+worldView.setBlockStateId(position, stateId)
+```
+
+### AppViewer
+
+Main application entry point for integrating the renderer.
+
+```typescript
+import { AppViewer, createGraphicsBackend } from 'minecraft-renderer'
+
+const viewer = new AppViewer({
+  config: {
+    sceneBackground: 'lightblue',
+    fpsLimit: 60
+  },
+  rendererConfig: {
+    enableLighting: true,
+    smoothLighting: true,
+    showChunkBorders: false
+  }
+})
+
+// Load backend
+await viewer.loadBackend(createGraphicsBackend)
+
+// Start rendering world
+await viewer.startWorld(worldProvider, renderDistance)
+
+// Update camera each frame
+viewer.updateCamera(position, yaw, pitch)
+```
+
+## How Block Rendering Works
+
+### 1. Chunk Data Flow
+
+```
+World Provider → WorldView → GraphicsBackend → Mesher Workers → Three.js Scene
+```
+
+1. **World Provider**: Provides chunk column data (prismarine-chunk format)
+2. **WorldView**: Emits `loadChunk` events with serialized chunk data
+3. **GraphicsBackend**: Receives events and dispatches to mesher workers
+4. **Mesher Workers**: Generate geometry (positions, normals, UVs, colors)
+5. **Three.js Scene**: Creates BufferGeometry meshes from worker output
+
+### 2. Mesher Worker Communication
+
+Workers receive:
+- Block data (chunk JSON with block state IDs)
+- Block models and textures atlas
+- Lighting configuration
+
+Workers produce:
+- Float32Array of vertex positions (x, y, z per vertex)
+- Float32Array of normals
+- Float32Array of colors (vertex colors for lighting)
+- Float32Array of UVs (texture coordinates)
+- Uint16/32Array of indices
+
+### 3. Geometry Structure
+
+Each block face is a quad with 4 vertices and 6 indices:
+
+```typescript
+interface MesherGeometryOutput {
+  positions: Float32Array  // [x1,y1,z1, x2,y2,z2, ...]
+  normals: Float32Array    // [nx,ny,nz, ...]
+  colors: Float32Array     // [r,g,b, r,g,b, ...] (0-1 range, lighting)
+  uvs: Float32Array        // [u1,v1, u2,v2, ...] (texture atlas coords)
+  indices: Uint32Array     // [0,1,2, 2,3,0, ...] (triangles)
+  sx, sy, sz: number       // Section position offset
+  blocksCount: number      // Number of non-air blocks
+  signs: Record<string, SignData>
+  banners: Record<string, BannerData>
+  heads: Record<string, HeadData>
+}
+```
+
+### 4. Block Model Resolution
+
+1. Block state ID → Block state properties
+2. Block state properties → Blockstate JSON
+3. Blockstate JSON → Model variants
+4. Model JSON → Faces with texture references
+5. Texture references → Atlas UV coordinates
+
+### 5. Lighting Calculation
+
+Lighting uses both block light and sky light:
+
+```typescript
+// Light level 0-15 for both block and sky light
+const blockLight = chunk.getBlockLight(pos)
+const skyLight = chunk.getSkyLight(pos)
+
+// Combined light level
+const light = Math.max(blockLight, skyLight * skyLightMultiplier)
+
+// Light level to color multiplier
+const brightness = lightLevelToBrightness[light]
+// Applied as vertex color: [brightness, brightness, brightness]
+```
+
+### 6. Ambient Occlusion
+
+Smooth lighting uses ambient occlusion based on neighboring blocks:
+
+```typescript
+// For each vertex, check 3 neighboring blocks
+// AO value = (side1 + side2 + corner) / 3
+// Applied as vertex color darkening
+```
+
+## Configuration
+
+### WorldRendererConfig
+
+```typescript
+interface WorldRendererConfig {
+  // Performance
+  mesherWorkers: number           // Number of worker threads (default: 4)
+  addChunksBatchWaitTime: number  // Batch delay for chunk loading (ms)
+  _experimentalSmoothChunkLoading: boolean
+
+  // Rendering
+  enableLighting: boolean         // Enable block/sky lighting
+  smoothLighting: boolean         // Enable ambient occlusion
+  dayCycle: boolean              // Enable time-based sky changes
+  starfield: boolean             // Enable star field at night
+  fov: number                    // Camera field of view
+
+  // Debug
+  showChunkBorders: boolean      // Show chunk boundary helpers
+  enableDebugOverlay: boolean    // Show advanced stats
+  clipWorldBelowY: number | undefined  // Don't render below Y level
+}
+```
+
+## Memory Management
+
+The renderer implements several memory optimizations:
+
+1. **CPU Array Disposal**: After GPU upload, CPU-side typed arrays are nulled
+2. **Texture Caching**: Signs and banners share textures via reference counting
+3. **Section Tracking**: Memory usage is tracked per section for debugging
+
+```typescript
+// Get memory usage
+const { bytes, readable } = worldGeometryHandler.getMemoryUsageReadable()
+console.log(`GPU Memory: ${readable}`)  // e.g., "45.32 MB"
+```
+
+## Performance Tips
+
+1. **Mesher Workers**: Increase `mesherWorkers` on multi-core systems
+2. **Smooth Loading**: Enable `_experimentalSmoothChunkLoading` to prevent frame drops
+3. **Clip World**: Use `clipWorldBelowY` to reduce geometry for surface views
+4. **Disable Lighting**: Set `enableLighting: false` for faster meshing
+
+## Development
+
+```bash
+# Install dependencies
+pnpm install
+
+# Run playground
+pnpm dev
+
+# Build library
+pnpm build
+
+# Type check
+pnpm typecheck
+```
+
+## File Structure
+
+```
+src/
+├── index.ts              # Main exports
+├── types.ts              # TypeScript types
+├── config.ts             # Default configurations
+├── appViewer.ts          # Main application viewer
+├── worldView.ts          # Chunk loading/events (WorldDataEmitter)
+├── playerState.ts        # Player state management
+├── three/                # Three.js backend
+│   ├── index.ts          # Backend exports
+│   ├── graphicsBackend.ts    # Main backend entry
+│   ├── documentRenderer.ts   # Render loop management
+│   ├── worldGeometryHandler.ts   # Chunk geometry
+│   └── starField.ts      # Night sky effect
+└── playground/           # Development environment
+    ├── playground.ts     # Main playground entry
+    └── playground.html   # HTML template
+```
+
+## Integration Example
+
+```typescript
+import { AppViewer, createGraphicsBackend, WorldView } from 'minecraft-renderer'
+import ChunkLoader from 'prismarine-chunk'
+import WorldLoader from 'prismarine-world'
+
+// Setup world (using prismarine-world)
+const World = WorldLoader('1.20.4')
+const Chunk = ChunkLoader('1.20.4')
+const world = new World().sync
+
+// Create viewer
+const viewer = new AppViewer()
+
+// Provide resources (textures, models)
+viewer.resourcesManager = {
+  currentConfig: { version: '1.20.4' },
+  currentResources: {
+    blocksAtlasImage: atlasImage,
+    blocksAtlasJson: atlasJson,
+    blockstatesModels: modelsData,
+    allReady: true
+  },
+  on: () => {}
+}
+
+// Load backend
+await viewer.loadBackend(createGraphicsBackend)
+
+// Start world
+await viewer.startWorld(world, 4)  // 4 chunk render distance
+
+// Initialize world view
+await viewer.worldView!.init(new Vec3(0, 64, 0))
+
+// Game loop
+function gameLoop() {
+  viewer.updateCamera(playerPosition, playerYaw, playerPitch)
+  requestAnimationFrame(gameLoop)
+}
+gameLoop()
+```
+
+## License
+
+MIT

package/dist/index.html

@@ -0,0 +1,83 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>Minecraft Renderer Playground</title>
+  <style>
+    * {
+      margin: 0;
+      padding: 0;
+      box-sizing: border-box;
+    }
+
+    html, body {
+      width: 100%;
+      height: 100%;
+      overflow: hidden;
+      background: #1a1a1a;
+    }
+
+    #viewer-canvas {
+      position: fixed;
+      top: 0;
+      left: 0;
+      width: 100%;
+      height: 100%;
+    }
+
+    .lil-gui {
+      position: fixed !important;
+      top: 10px;
+      right: 10px;
+      z-index: 1000;
+    }
+
+    .loading-overlay {
+      position: fixed;
+      top: 0;
+      left: 0;
+      width: 100%;
+      height: 100%;
+      background: #1a1a1a;
+      display: flex;
+      flex-direction: column;
+      justify-content: center;
+      align-items: center;
+      z-index: 10000;
+      color: #fff;
+      font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
+    }
+
+    .loading-overlay.hidden {
+      display: none;
+    }
+
+    .loading-spinner {
+      width: 50px;
+      height: 50px;
+      border: 3px solid #333;
+      border-top-color: #4ade80;
+      border-radius: 50%;
+      animation: spin 1s linear infinite;
+    }
+
+    @keyframes spin {
+      to { transform: rotate(360deg); }
+    }
+
+    .loading-text {
+      margin-top: 16px;
+      font-size: 14px;
+      color: #888;
+    }
+  </style>
+<script defer src="./static/js/lib-polyfill.98986ac5.js"></script><script defer src="./static/js/lib-react.5c9129e0.js"></script><script defer src="./static/js/365.f05233ab.js"></script><script defer src="./static/js/index.092ec5be.js"></script></head>
+<body>
+  <div id="react-root"></div>
+  <div class="loading-overlay" id="loading">
+    <div class="loading-spinner"></div>
+    <div class="loading-text">Loading Minecraft Renderer...</div>
+  </div>
+</body>
+</html>