~/content/01-about.mdโผ
No pages yet. In Files, use "Set as Page" on a markdown or HTML file.
Frontmatter
{
"title": "Chapter 1: Architecture & Procedural Engine",
"created": "1970-01-01T00:00:00Z",
"updated": "1970-01-01T00:00:00Z",
"slug": "about"
}๐ Chapter 1: Architecture & Procedural Engine
Welcome to Chapter 1 of the Block Garden Knowledge Hub! This chapter provides a deep architectural breakdown of how Block Garden operates under the hood โ from worker-threaded terrain synthesis to volumetric light propagation and zero-framework signal reactivity.
๐ Project Links & Resources
- ๐ฎ Live Web Game: block-garden
- โก Unbundled Live Runtime: block-garden/index_unbundled.html
- ๏ฟฝ๏ธ Angular Integration: kherrick.github.io/apps
- ๐น๏ธ Itch.io Hub: karlherrick.itch.io/block-garden
- ๐ฆ GitHub Repository: github.com/kherrick/block-garden
- ๐ Public API Examples: block-garden/src/api/examples/
- ๐ฅ YouTube Demos:
๐๏ธ 1. Procedural Noise & Multi-Threaded Chunk Generation
Block Garden generates infinite, deterministic 3D voxel landscapes from a single seed value using multi-layered noise functions in src/core/world/generation/chunk.mjs.
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ Seed Value & PRNG (alea) โ
โโโโโโโโโโโโโโโโฌโโโโโโโโโโโโโโโโ
โ
โผ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ 3D Simplex Noise (initNoise) โ
โโโโโโโโฌโโโโโโโโฌโโโโโโโโฌโโโโโโโโ
โ โ โ
โผ โผ โผ
โโโโโโโโ โโโโโโโโ โโโโโโโโ
โ Base โ โ Cave โ โ Ore โ
โNoise โ โNoise โ โNoise โ
โโโโฌโโโโ โโโโฌโโโโ โโโโฌโโโโ
โ โ โ
โโโโโโโโโโผโโโโโโโโโ
โผ
โโโโโโโโโโโโโโโโโโโโโโ
โ Chunk Assembler โ
โโโโโโโโโโโโฌโโโโโโโโโโ
โ
โผ
โโโโโโโโโโโโโโโโโโโโโโ
โ Worker Pool Thread โ
โโโโโโโโโโโโฌโโโโโโโโโโ
โ
โผ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ Main Thread Render Queue โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
Key Generation Mechanics:
- Seeded Noise Pipeline: Seeded 3D Simplex noise (
src/utils/noise.mjsusingaleaPRNG) ensures world seeds are 100% reproducible and shareable across devices. - Layered Terrain Topography: Blends base terrain noise, 3D mountain shaping, hilliness octaves, and lake depressions to create organic cliffs, valleys, and deep lakes.
- Subterranean Cavern Carving: Carves complex tunnel networks and caverns while evaluating surface depth heuristics and enforcing a Lava Protection Zone (
Y = LAVA_HEIGHT + LAVA_PROTECTION_ZONE = 3 + 12 = 15), ensuring caves never breach the deep lava layer. - Y-Level Mineral Veins: Ores are evaluated strictly by Y-level depth in order of rarity:
- Gold: Depths 30โ70 blocks, requiring high noise threshold (
oreNoise > 0.8). - Iron: Depths 20โ60 blocks (
oreNoise > 0.65). - Coal: Depths 10โ50 blocks (
oreNoise > 0.55). - Also includes Diamond, Silver, and Copper veins.
- Gold: Depths 30โ70 blocks, requiring high noise threshold (
- Off-Thread Worker Pool:
ChunkManagerdelegates chunk synthesis off the main UI thread to a dedicated pool of Web Workers (terrain.worker.mjs), sized dynamically tonavigator.hardwareConcurrency.
๐ก 2. Volumetric BFS Flood-Fill Lighting System
Lighting in Block Garden (src/core/world/lighting/lightSystem.mjs) is calculated dynamically using a voxel-based Breadth-First Search (BFS) engine backed by a flat Uint8Array (LightMap).
- Emissive Light Sources: Torches, Lanterns, and Lightstones register as light sources with initial intensity levels.
- 3D Attenuation: Light attenuates by 1 unit per voxel, traveling up to
MAX_LIGHT_LEVELthrough non-solid blocks. - Cross-Chunk Propagation: When a block changes near a chunk boundary (
localXorlocalZwithinMAX_LIGHT_RADIUS),updateLightOnBlockChangeautomatically recalculates light levels for neighboring chunks for seamless lighting across chunk borders.
๐จ 3. Greedy Meshing, Ambient Occlusion & Shader Pipelines
To achieve high rendering performance, the chunk mesher (src/core/world/meshing/chunkMesher.mjs) transforms raw block arrays into optimized GPU geometry:
- Greedy Quad Merging: Scans adjacent block faces and merges contiguous coplanar faces into single quads, reducing vertex counts dramatically.
- Per-Vertex Ambient Occlusion: Evaluates corner and edge occlusion around every face vertex to compute smooth ambient shadows without extra shadow mapping overhead.
- Three-Pass WebGL Renderer:
- Opaque Pass: Renders dirt, stone, ores, and solid terrain blocks.
- Transparent Pass: Handles depth-sorted leaves, glass, and semi-transparent foliage.
- Water Pass: Executes custom WebGL fragment shaders for wave motion and surface reflection effects.
โก 4. Fine-Grained Signal Reactivity (No Framework Overhead)
Rather than relying on heavy VDOM diffing frameworks (React, Vue), Block Garden uses standard Web Standards paired with TC39 signal-polyfill (Signal.State and Signal.Computed).
- Surgical Updates: Every state change (player inventory, camera coordinates, selected hotbar item, dialog visibility) mutates a
Signal.State. - Zero VDOM Cost: Web Components subscribe directly to computed signals, triggering microscopic DOM updates only where needed.
- Unbundled Philosophy: Available as unbundled raw ES6 modules (
index_unbundled.html), allowing live runtime editing without transpilation or webpack compilation!
โฌ ๏ธ Previous Page | โก๏ธ Next Page