minecraft-renderer 0.1.79 → 0.1.81

package/README.md

@@ -2,7 +2,43 @@
 
 ![Minecraft Renderer](./logo.webp)
 
-A modular Minecraft world renderer with Three.js WebGL 2 backend. Designed for performance testing, experimentation, and integration into Minecraft clients.
+One of the best Minecraft world rendererers implemented from scratch. Uses Three.js WebGL 2 backend. Designed for performance testing, experimentation, and integration into Minecraft clients or other use cases for game world display.
+
+Features:
+
+- 💡 Full-featured: hand, third-person view, entities, debug features and even more!
+- ⚡️ Leverages all available WebGL 2 and WASM world meshing for the maximum performance
+- 📦 Implemented from scratch; small bundle size and runtime footprint
+- ⚙️ Easily customizable: modular architecture with Three.js API
+
+## Implemented Features
+
+- WASM mesher workers (default path) with legacy JS mesher fallback
+- Instanced shader-cube rendering for full blocks (`GlobalBlockBuffer`, one GPU draw)
+- Global legacy geometry buffer for models/stairs/slabs (merged indexed mesh, opaque + blend passes)
+- Block and sky lighting, smooth lighting, and vanilla vs high-contrast (default) face shading (`vanillaLook`)
+- Signs, banners, skulls, and other block-entity overlays
+- Entities: players with skins & animations, mobs, items, armor, text/item display
+- Day cycle, skybox, starfield, rain, fireworks
+- Third-person camera, view bobbing, holding block / hand
+- Optional off-thread graphics backend (render in a worker!)
+- Smooth lighting (lighting data has to be provided)
+
+### Browser support
+
+**Requires WebGL 2.0.** WebGL 1 is not supported as a full-feature path (shader cubes and several block shaders need WebGL2).
+
+| Browser              | Minimum version |
+| -------------------- | --------------- |
+| Chrome / Chromium    | 56+             |
+| Firefox              | 51+             |
+| Edge                 | 79+ (Chromium)  |
+| Safari (macOS / iOS) | 15.3+           |
+| Opera                | 43+             |
+
+**Not supported:** Safari before 15.
+
+Optional extensions (`WEBGL_multi_draw`, instanced base vertex) improve draw-call batching when present; the renderer falls back to capped multi-draw loops when they are missing.
 
 ## Architecture Overview
 
@@ -96,12 +132,12 @@ Renderer-owned options live in `RENDERER_DEFAULT_OPTIONS` and `RENDERER_OPTIONS_
    This updates `inWorldRenderingConfig`, `appViewer.config` (FPS/stats), and live menu-background controls when `currentDisplay === 'menu'`.
 6. **App-only** — keep `volume` and bot/world hooks in the client (`applyRendererEnableLighting`, `applyRendererWorldViewOptions`, weather).
 
-| Change | Live update | Reload required |
-|--------|-------------|-----------------|
-| Menu V2 scene / camera / speeds | Yes (`backend.getMenuBackground`) | Mode switch needs restart |
-| `rendererMesher` (`wasm` / `legacy-js`) | Yes — recreates mesher workers | Chunks reload (`requiresChunksReload`) |
-| `rendererWorldPerformance` | Yes — recreates mesher workers | Chunks reload (`requiresChunksReload`) |
-| Volume | App `watchValue` only | No |
+| Change                                  | Live update                       | Reload required                        |
+| --------------------------------------- | --------------------------------- | -------------------------------------- |
+| Menu V2 scene / camera / speeds         | Yes (`backend.getMenuBackground`) | Mode switch needs restart              |
+| `rendererMesher` (`wasm` / `legacy-js`) | Yes — recreates mesher workers    | Chunks reload (`requiresChunksReload`) |
+| `rendererWorldPerformance`              | Yes — recreates mesher workers    | Chunks reload (`requiresChunksReload`) |
+| Volume                                  | App `watchValue` only             | No                                     |
 
 Sync runs on the **main thread** only; `inWorldRenderingConfig` uses existing valtio `__syncToWorker` for off-thread backends. Do not call `subscribeRendererOptions` from mesher workers.
 
@@ -122,11 +158,13 @@ World Provider → WorldView → GraphicsBackend → Mesher Workers → Three.js
 ### 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)
@@ -139,13 +177,15 @@ 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
+  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>
@@ -194,21 +234,21 @@ Smooth lighting uses ambient occlusion based on neighboring blocks:
 ```typescript
 interface WorldRendererConfig {
   // Performance
-  mesherWorkers: number           // Number of worker threads (default: 4)
-  addChunksBatchWaitTime: number  // Batch delay for chunk loading (ms)
+  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
+  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
+  showChunkBorders: boolean // Show chunk boundary helpers
+  enableDebugOverlay: boolean // Show advanced stats
+  clipWorldBelowY: number | undefined // Don't render below Y level
 }
 ```
 
@@ -223,7 +263,7 @@ The renderer implements several memory optimizations:
 ```typescript
 // Get memory usage
 const { bytes, readable } = worldGeometryHandler.getMemoryUsageReadable()
-console.log(`GPU Memory: ${readable}`)  // e.g., "45.32 MB"
+console.log(`GPU Memory: ${readable}`) // e.g., "45.32 MB"
 ```
 
 ## Performance Tips
@@ -301,7 +341,7 @@ viewer.resourcesManager = {
 await viewer.loadBackend(createGraphicsBackend)
 
 // Start world
-await viewer.startWorld(world, 4)  // 4 chunk render distance
+await viewer.startWorld(world, 4) // 4 chunk render distance
 
 // Initialize world view
 await viewer.worldView!.init(new Vec3(0, 64, 0))