# ⛏️ YeetCraft 3.4 — Definitive Game Specification & System Architecture
**Subtitle:** *"Vanilla Depth, Living Settlements, La peice & Industrial Transit"*  
**Authoritative Reference:** Build 3.4.0 (Unified Desktop + Mobile WebGL Engine)

---

## 1. Executive Summary & Design Vision

**YeetCraft** is a high-performance, single-file browser voxel engine inspired by Minecraft, combining classic vanilla survival gameplay with deep industrial expansion, authentic enchanting mechanics, fully modeled vehicular transit (Biplane, Roadster, Turbo Boat), biome-adaptive living villages, subterranean cavern biomes, and inter-realm endgame teleportation.

### Key Pillars
1. **Uncompromised Vanilla Depth**: True-to-source block interactions, mining hardness, tool tiers, hunger, health, mob AI, day-night cycles, and atmospheric lighting.
2. **Living Settlements**: Dynamic procedural villages that adapt their foundations to hilly terrain, avoiding floating or buried structures, populated by patrolling Iron Golems and scheduled villager routines.
3. **"La peice" & Authentic Enchanting**: Deep blue crystalline mineral (formerly Lapis) serving as the catalyst for a full 30-level enchanting table system with bookshelf synergy and animated item glints.
4. **Industrial Transit & Aerodynamics**: High-speed, fuel-consuming vehicles featuring an aerodynamically corrected Biplane with altitude/heading hold, live flight navigation chart, and emergency exit safety locks.
5. **Endgame Progression & Wayfarer Teleportation**: Multi-boss combat expeditions (Ender Dragon, Wither, Elder Guardian, Warden) dropping high-tier aeronautical upgrades, culminating in expensive inter-dimensional Wayfarer Gates fueled by Phase Cells.
6. **Universal Cross-Platform Ergonomics**: Fluid desktop controls with visible keybind labels (`Tab` pause/cursor release) paired with a responsive multi-touch mobile HUD featuring independent touch streams, floating joysticks, and dedicated inventory actions.

---

## 2. World Generation & Biomes

### 2.1 Overworld Surface & Climate Zones
- **Height Matrix**: Sea level fixed at $Y = 62$. Surface terrain spans $Y = 63$ to $Y = 128$. Mountain peaks generate up to $Y = 180$.
- **Biomes**:
  - **Plains**: Rolling grasslands, oak trees, wild flowers, pumpkin patches, passive farm livestock (cows, sheep, pigs).
  - **Desert**: Undulating sand dunes, cacti, dead bushes, sandstone strata, desert temples, and flat-roofed sandstone villages.
  - **Taiga / Snowy Slopes**: Spruce forests, fern undergrowth, snow layer accumulation, ice-covered lakes, steep gabled cabins.
  - **Savanna**: Acacia trees with distinct umbrella canopies, terracotta hills, high plateaus, open-air shade huts.
  - **Deep Ocean**: Expansive water bodies spanning hundreds of voxels, kelp forests, seagrass meadows, underwater trenches, and ocean monuments guarded by Elder Guardians.

### 2.2 Subterranean Overhaul & Cave Biomes
YeetCraft replaces standard hollow spheres with 3D Perlin worm tunnels and distinct cavern biomes:
- **Cliff Face & Ravine Lighting Fix**: Cliff faces in deep chasms are evaluated against the unobstructed air column in front of the voxel rather than the solid ground column above, eliminating pitch-black ravine walls under open skies.
- **Cave Biomes**:
  1. **Glowmoss Grottos ($Y = 10 \dots 50$)**: Bioluminescent lichen covers floor and ceiling slabs. Dripping spore vines cast an ambient green-cyan glow ($Light = 11$). Spawns lush subterranean springs.
  2. **Prism Hollows ($Y = -16 \dots 20$)**: Shimmering crystalline geodes lined with amethyst-like Prism clusters. Mining these geodes drops **Prism Dust**, a required ingredient for advanced telemetry and Phase Cells.
  3. **Dripstone Galleries ($Y = 0 \dots 45$)**: Pointed dripstone stalactites suspend from cavern roofs; stalagmites ascend from floors. Water drips slowly into stone cauldrons. Enhanced acoustic reverberation for steps and mob footsteps.
  4. **Ember Vaults ($Y = -48 \dots 0$)**: Deepslate caverns intercut by glowing magma veins, thermal vents, and lava falls. Stepping onto magma blocks causes persistent thermal friction damage without boots.

---

## 3. Living Settlements ("Living Villages")

### 3.1 Terrain-Adaptive Foundation Generator
Traditional flat stamping is replaced by a two-pass terrain conforming algorithm:
1. **Raycast Anchor Assessment**: A structure's bounding box $[X_1, Z_1] \times [X_2, Z_2]$ casts 4 corner rays and 1 center ray to probe ground height $Y_{ground}$.
2. **Foundation Stilt Extrusion**:
   - If ground elevation falls below the structure's base plane $Y_{base}$, cobblestone or stone-brick foundation stilts extrude downwards into the terrain until solid bedrock or dense stone is reached (max depth: 16 blocks).
   - This completely eliminates floating structures on ridges, ravines, and hillsides.
3. **Step & Threshold Grading**: The entrance door coordinates calculate the delta to the nearest road voxel:
   $$\Delta Y = Y_{door} - Y_{road}$$
   - If $\Delta Y > 0$, cobblestone stairs and stone slabs dynamically generate a contoured entryway staircase.
   - If $\Delta Y < 0$, the immediate doorstep is terraced with stone retainers.
4. **Contoured Roads**: Village roads (gravel and dirt paths) snake along terrain elevation contours using smooth stepping rather than shearing terrain into artificial vertical cliffs.

### 3.2 Biome-Specific Architectural Profiles
| Biome | Wall Primary | Roof / Trim | Windows | Decorative Features |
| :--- | :--- | :--- | :--- | :--- |
| **Plains** | Oak Logs & Planks | Cobblestone overhangs | Glass Panes | Cobblestone chimney, flower window boxes, torch sconces |
| **Desert** | Cut Sandstone | Smooth Sandstone & Terracotta | Iron Bars / Slits | Rooftop canopies, interior water basins, clay pots |
| **Taiga / Snow** | Spruce Logs | Spruce Wood Steep Gables | Glass Panes | Cozy campfire hearth, lantern posts, haybale lofts |
| **Savanna** | Stripped Acacia | Acacia Wood Slabs | Open Openings | Open-air sun shades, perimeter log fencing, water troughs |

### 3.3 Modular Village Buildings & Loot
- **The Blacksmith**:
  - Dual functional blast furnaces and an iron anvil.
  - Lava quenching trough encased in smooth stone.
  - High-tier chest loot table: 2–5 Iron Ingots, 1–3 Obsidian, 1 Iron Sword/Pickaxe, 1–2 Gold Ingots, 3–5 Red Apples, 1–2 Diamonds (5% chance).
- **The Library**:
  - High walls lined with Bookshelves ($B \ge 12$).
  - Central Enchanting Table station with web decor and lectern.
- **The Church / Watchtower**:
  - 3-story cobblestone steeple with interior climbing ladder.
  - Top vantage deck outfitted with high-intensity soul lantern / roof beacon visible up to 12 chunks away.
- **Farms, Pastures & Aqueducts**:
  - Segmented 9x9 crop beds supporting Wheat, Carrots, Potatoes, and Beetroot.
  - Irrigated by centralized stone aqueducts fed from a natural spring or well.
  - Fenced animal pastures sheltering Sheep and Cows.

### 3.4 Community Defense & Behaviors
- **Iron Golems**:
  - Spawn naturally: 1 per 10 active villagers in a settlement.
  - Player Construction: 4 Iron Blocks arranged in a 'T' shape ($1 \text{ base} + 3 \text{ top}$), topped with 1 Carved Pumpkin.
  - Stats: $100\text{ HP}$, $7\text{–}21\text{ Damage}$, high knockback toss, immune to fall and drowning damage.
  - AI: Patrols perimeter, prioritizes targeting hostile mobs (Zombies, Skeletons, Spiders, Creepers) within a 16-block radius.
- **Meeting Center & Town Bell**:
  - Centrally generated stone well with a brass Town Bell.
  - Villager Gathering: Daily routine brings villagers to the well between game ticks $6000$ and $9000$ (midday).
  - Ringing the Bell: Interacting with the bell issues a settlement-wide alarm: all villagers immediately sprint into the nearest building and shut doors for 60 seconds.

---

## 4. Mineralogy & Authentic Enchanting ("La peice")

### 4.1 The Blue Mineral: "La peice"
- **Identity**: Permanently designated as **La peice** (formerly Lapis Lazuli). Represents a mystical ultramarine silicate rich in resonance energy.
- **Vein Generation**:
  - Height Range: $Y = 5$ to $Y = 32$ (most dense at $Y = 16$).
  - Frequency: 4 veins per chunk; vein cluster size spans 4–9 ore blocks embedded in Stone or Deepslate.
- **Mining Mechanics**:
  - Tool Requirement: Stone Pickaxe or higher.
  - Drop Quantity: $4\text{–}8$ raw **La peice gems** per block. Scaled by Fortune enchantment:
    $$\text{Drops} = \text{Base} \times (1 + \text{Random}(0, \text{Fortune Level}))$$
- **Procedural Texture**: Deep cobalt-blue background studded with lapis-matrix inclusions and brilliant specular light points that twinkle under direct sunlight or torchlight.

### 4.2 Enchanting Table & Bookshelf Synergy
- **Crafting Recipe**:
  $$\text{Enchanting Table} = 1\times \text{Book} + 2\times \text{Diamonds} + 4\times \text{Obsidian}$$
- **Surrounding Bookshelf Dynamics**:
  - Bookshelves must be placed within a 2-block radius at the same level or 1 block higher than the table, separated by 1 block of air.
  - Max Effective Bookshelves: $15$.
  - Maximum Available Enchantment Level:
    $$\text{MaxLevel} = \min\left(30, \left\lfloor \frac{\text{Bookshelves}}{15} \times 30 \right\rfloor\right)$$
- **Enchantment Catalysts**:
  - Tier 1: 1 XP Level + 1 La peice gem
  - Tier 2: 2 XP Levels + 2 La peice gems
  - Tier 3: 3 XP Levels + 3 La peice gems (Unlocks Level 30 apex enchants when 15 bookshelves surround table)

### 4.3 Enchantment Roster & Effects
| Enchantment | Applicable Gear | Max Tier | Mechanical Effect |
| :--- | :--- | :--- | :--- |
| **Sharpness** | Swords, Axes | V | $+1.25$ Melee damage per tier |
| **Power** | Bows | V | $+25\%$ Arrow kinetic damage per tier |
| **Efficiency** | Pickaxes, Shovels, Axes | V | Mining speed multiplier: $+(\text{Level}^2 + 1) \times 0.2$ |
| **Unbreaking** | All Durable Gear | III | Chance to ignore durability loss: $\frac{100}{\text{Level} + 1}\%$ |
| **Protection** | All Armor Pieces | IV | $-4\%$ all incoming damage per tier (capped at $80\%$ total) |
| **Fortune** | Pickaxes, Shovels | III | Increases maximum drop yield of ores (including La peice) |

### 4.4 Shimmering Glint Shader
Enchanted items dynamically render an animated translucent purple sine-wave glint (`#a855f7` to `#ec4899`) traversing diagonally at $45^\circ$ across both inventory slot icons and in-hand 3D models.

---

## 5. Industrial Transit & Vehicle Systems

### 5.1 BIPLANE (Aviation Mechanics & Pitch Fix)
- **Aerodynamic Correction**: Previous builds inverted the aircraft pitch control. The 3.4 engine correctly maps:
  - **Pull Up (Pitch Up / Nose Up)**: Elevators deflect upward, shifting aerodynamic angle of attack positive, climbing in altitude while decaying forward velocity if throttle is under $60\%$.
  - **Push Down (Pitch Down / Nose Down)**: Elevators deflect downward, decreasing altitude and increasing airspeed due to gravitational acceleration.
  - **Aileron Roll & Yaw**: Banking into a turn induces coordinated rudder turn yaw without slipping.
- **Flight Envelope**:
  - Stall Speed: $V_{stall} = 12\text{ m/s}$. Airspeed falling below this induces stall buffeting and altitude loss.
  - Cruise Speed: $28\text{ m/s}$.
  - Top Speed (Vanilla): $38\text{ m/s}$.
  - Top Speed (with Turbocharger Module): $62\text{ m/s}$.
- **Instruments & HUD**:
  - Real-time airspeed indicator (knots / m/s), barometric altimeter, artificial horizon pitch indicator, compass heading, and fuel quantity gauge.
- **Flight Autopilot Hold (`P` Key / Touch Hold)**:
  - Engages heading and barometric altitude hold lock.
  - Real-time PID loop adjusts elevator and rudder trims to maintain current altitude $\pm 0.5\text{m}$.
  - Instantly disengages if pilot applies manual stick inputs.
  - Continues consuming fuel; does not navigate around mountains (pilot situational awareness required).
- **Live Flight Navigation Chart (`M` Key / Touch Chart)**:
  - Displays a transparent topological mini-chart overlaying the cockpit without pausing flight physics or freezing control.
  - Pressing `Shift + M` pauses the game and opens the comprehensive full-screen world atlas.
- **Ejection Safety Lock**:
  - Pressing Exit while airborne above $Y = 70$ requires double-tap confirmation (`Press Shift again to Bail Out`), preventing fatal mid-air accidental falls.

### 5.2 ROADSTER (Overland Transit)
- **Chassis Physics**: 4-wheel independent spring-damper suspension raycasting 1.2 blocks below axles.
- **Roadwork Synergy**: On Cobblestone, Smooth Stone, Gravel, and Asphalt blocks, rolling resistance drops by $60\%$, accelerating the Roadster to its top speed of $45\text{ m/s}$.
- **Headlights**: Twin directional light cones illuminate voxels up to 32 blocks ahead during night cycles.

### 5.3 TURBO_BOAT (Oceanic Exploration)
- **Hydrodynamic Physics**: Surface buoyancy forces oscillate with ocean surface waves. Low turning radius with water spray particle emissions.
- **Speed**: $32\text{ m/s}$ in deep ocean waters. Immune to breakage from lily pads or minor shoreline collisions.

### 5.4 The Biofuel Refinery Loop
Vehicles require fuel to operate. Leaving throttle engaged depletes fuel tanks:
$$\text{Fuel Burn Rate} = \text{BaseRate} \times \left(\frac{\text{Throttle}\%}{100}\right) \times \text{EngineEfficiency}$$
- **The Biofuel Refinery Machine**:
  - Recipe: 4 Iron Ingots, 2 Furnaces, 1 Glass Block, 2 Copper Ingots.
  - Input Hopper: Accepts agricultural surplus:
    - 16 Sugar Cane $\to 1$ Ethanol Flask
    - 24 Potatoes / Wheat $\to 1$ Bio-Mass Slug
  - Refining Process: Combines 1 Ethanol Flask + 1 Bio-Mass Slug + 1 Coal/Charcoal in the Refinery chamber to synthesize $1\times$ **Biofuel Canister**.
  - 1 Biofuel Canister delivers 500 seconds of continuous flight or driving time.

---

## 6. Subterranean Boss Expeditions & Aeronautical Loot

### 6.1 Minecraft Bosses Recreated
1. **The Ender Dragon**:
   - Spawns in End Dimension arena ringed by 10 Obsidian Pillars topped with healing End Crystals.
   - Routines: Circling flight pattern, dive bomb strafing runs with dragon breath acid clouds, perching on central Bedrock Fountain.
   - Victory: Slaying the dragon yields the Dragon Egg, an explosion of 12,000 XP, and opens the return portal to the Overworld.
2. **The Wither**:
   - Summoning: 4 Soul Sand blocks in a T-shape topped with 3 Wither Skeleton Skulls.
   - Attack Phases: Shoots homing explosive Wither Skulls inflicting the Wither effect. At $50\%\text{ HP}$, activates Wither Armor (immune to projectile attacks, requires melee combat).
   - Drop: Guaranteed $1\times$ **Nether Star**.
3. **The Elder Guardian**:
   - Stationed inside Deep Ocean Monument throne rooms.
   - Inflicts Mining Fatigue III on approaching players; charges high-damage laser beam.
   - Drop: Wet Sponges, Prismarine Shards, and the rare **Abyssal Heart**.
4. **The Warden**:
   - Lurks in Deep Dark caverns; summoned if 3 Sculk Shriekers are activated by vibration.
   - Blind mechanics: Detects sound waves and vibrations. High-velocity ranged Sonic Boom piercing through obstacles.
   - Drop: Sculk Catalyst, Echo Shards, and **Sonic Core**.

### 6.2 Boss-Tier Vehicle Upgrades
| Boss Trophy | Engineered Module | Crafting Recipe | Vehicle Stat Transformation |
| :--- | :--- | :--- | :--- |
| **Nether Star** | **Turbocharger Module** | $1\times \text{Nether Star} + 4\times \text{Riftmetal Ingots} + 2\times \text{Pistons}$ | Biplane top speed $+100\%$ ($38 \to 76\text{ m/s}$); accelerates instantaneously |
| **Dragon Breath** | **Dragonwing Glider Sails** | $4\times \text{Dragon Breath Flasks} + 2\times \text{Phantom Membranes} + 1\times \text{Biplane}$ | Reduces stall speed to $6\text{ m/s}$; $-50\%$ fuel consumption rate |
| **Sonic Core** | **Sonic Thruster** | $1\times \text{Sonic Core} + 4\times \text{Echo Shards} + 4\times \text{Obsidian}$ | Adds secondary 'Boost' key: 5-second rocket burst allowing vertical 90° climb |
| **Abyssal Heart** | **Abyssal Propeller** | $1\times \text{Abyssal Heart} + 4\times \text{Prismarine Crystals} + 1\times \text{Turbo Boat}$ | Converts Turbo Boat into an amphibious submersible vessel capable of underwater navigation |

---

## 7. Endgame Transit: The Wayfarer Gate

### 7.1 Concept & Balance
The **Wayfarer Gate** satisfies the demand for long-distance teleportation without compromising the survival exploration loop. It is deliberately the most expensive survival structure in YeetCraft.

### 7.2 Bill of Materials (Per Gate Node)
To establish a functional teleportation link, two synchronized Wayfarer Gates must be constructed:
- $36\times$ **Diamonds** ($4\times \text{Diamond Blocks}$)
- $2\times$ **Netherite Ingots** ($8\times \text{Ancient Debris} + 8\times \text{Gold Ingots}$)
- $2\times$ **Riftmetal Ingots** (Refined from ultra-rare Riftmetal Veins found at Nether $Y \le 12$)
- $1\times$ **Nether Star** (Earned exclusively by defeating the Wither)
- $12\times$ **Prism Dust** (Harvested from underground Prism Hollow geodes)

### 7.3 Operational Logistics & Phase Cells
- Ordinary map markers and pins are **not** free teleport destinations.
- Stepping through a Wayfarer Gate activates an instantaneous inter-realm wormhole connecting linked nodes.
- **Phase Cells**: Every teleportation jump consumes $1\times$ **Phase Cell**:
  $$\text{Phase Cell Recipe} = 1\times \text{Ender Pearl} + 2\times \text{Prism Dust} + 1\times \text{La peice Gem}$$
- Dimension Traversal: Supports seamless transit between Overworld, Nether, and The End.

---

## 8. User Interface, Controls & Recipe Book

### 8.1 Toolbar & Keyboard Architecture
Every toolbar icon features a visible, legible shortcut key badge underneath its sprite.

- **The `Tab` Universal Safe Pause**:
  - Pressing `Tab` immediately pauses game simulation, halts vehicle fuel consumption, and unlocks the system cursor from PointerLock, allowing direct clicking on UI buttons, inventory slots, and maps.
  - Pressing `Tab` or `Esc` again relocks pointer and seamlessly resumes play.

| Key | Primary Function | Modal / Window Activated |
| :---: | :--- | :--- |
| **`E`** | Inventory | 36-slot Player Inventory + 3x3 Crafting Grid + Armor Slots |
| **`B`** | Recipe & Item Book | Searchable 400+ recipe catalog with recursive ingredient tree |
| **`O`** | Transit Workshop | Vehicle fabrication, fuel status, engine modifications |
| **`M`** | Flight Navigation Chart | Live transparent compass/topological overlay (does not pause plane) |
| **`Shift+M`**| World Atlas | Paused full-screen multi-biome map with custom waypoint markers |
| **`N`** | Boss Expeditions | Waypoints to Strongholds, Nether Fortresses, and Monuments |
| **`J`** | Survival Progression | Achievement tree, quest milestones, and exploration journal |
| **`H`** | Field Manual | Interactive How-to-Play tutorial, flight school, combat guide |
| **`K`** | Video Settings | FOV, Render Distance, Shadow Presets, AO toggle, Mobile UI scale |
| **`V`** | Camera Perspective | Cycles: 1st Person $\to$ 3rd Person Back $\to$ 3rd Person Front $\to$ Chase Cam |
| **`P`** | Autopilot Lock | Engages Heading & Altitude Hold on Biplane |
| **`Esc`**| System Menu | Pause screen, World Save, JSON Export/Import, Quit |

### 8.2 The Interactive Recipe Book ('B')
- **Search & Filter**: Real-time substring filter across item names, tags, and categories (Building, Combat, Tools, Transit, Refining, Magic).
- **Clickable Ingredient Graph**: Clicking any ingredient in an active recipe automatically recurses backwards through its dependency tree (e.g., clicking *Biofuel Canister* shows *Ethanol Flask*, clicking *Ethanol* displays *Sugar Cane* farm harvest).
- **HUD Pinboard**: Players can click "Pin to HUD" on any recipe to render a translucent material shopping list in the corner of their screen while mining.

---

## 9. Mobile Multi-Touch Architecture

### 9.1 Touch Stream Separation & No-Cancel Finger Tracking
Mobile devices track multiple distinct touch identifiers (`touch.identifier`):
- **Aiming vs Action Independence**: Moving or lifting an aiming finger never interrupts or cancels an active mining or attack touch hold.
- **Analog Joystick**: Dynamic floating virtual thumbstick on the left screen half. Measures normalized deflection vector $(\Delta x, \Delta y)$ for analog walking, running, and swimming.

### 9.2 Mobile Action Layout & Ergonomics
- **Right Screen Cluster**:
  - `MINE / ATK` (Hold to mine block, tap to attack)
  - `PLACE / USE` (Hold to interact, place block, open chest)
  - `JUMP` (Tap to leap, hold to swim upward)
  - `SPRINT` (Toggle double-speed run)
  - `SNEAK` (Crouch, prevents stepping off edge of voxels)
- **Mobile Vehicle Dashboard**:
  - Positioned strategically along the bottom flanks in landscape view to prevent cockpit obstruction.
  - Buttons: `Steer Left`, `Steer Right`, `Throttle Up/Down Lever`, `Pitch Nose-Up`, `Pitch Nose-Down`, `Fire Gun`, `Cruise`, and `Hold Autopilot`.
- **Touch Inventory Management**:
  - Replaces mouse-drag mechanics with dedicated action buttons:
    - `Move Stack`: Transfers selected 64-item stack directly to target container.
    - `Split / 1`: Drops exactly 1 item into tapped slot.
    - `Quick Move`: Shifts item directly between hotbar and storage chest.
- **Fail-Safe Orientation Handling**:
  - Device orientation changes and application blur events automatically pause the simulation to prevent runaway vehicle motion or accidental player death.

---

## 10. Engine Stabilization & Performance Budget

### 10.1 Pure WebGL Pipeline
- All legacy CPU software raycasters (`initSoftware`, `renderSoftware`) have been eradicated.
- The pipeline utilizes hardware-accelerated WebGL 2.0 with custom GLSL shaders:
  - Per-vertex Ambient Occlusion evaluated from neighbor voxel occupancy:
    $$AO = 1.0 - 0.22 \times (\text{Side}_1 + \text{Side}_2 + \text{Corner})$$
  - Sun angle vector calculation providing soft directional daylight falloff.
  - Chunk mesh face culling: Interior occluded voxel faces are discarded during buffer compilation, reducing vertex count by $>80\%$.

### 10.2 Zero-Allocation Scratch Pipeline
To maintain 60 FPS without garbage collection pause spikes:
- Bounding-box collision checks and raycasts re-use persistent global scratch structs:
  ```js
  const SCRATCH_BOX = { minX:0, minY:0, minZ:0, maxX:0, maxY:0, maxZ:0 };
  const SCRATCH_VEC = { x:0, y:0, z:0 };
  const SCRATCH_RAY = { origin: {x:0,y:0,z:0}, dir: {x:0,y:0,z:0} };
  ```
- Physics loops operate on raw Float32Arrays and Int32Arrays for block coordinates.

### 10.3 Save Format & Backward Compatibility
- Save data serializes to compressed JSON stored in `localStorage` or exported as `.yeetcraft` files.
- Backward Compatibility: Build 3.4 automatically migrates Build 3.0, 3.2, and 3.3 worlds, upgrading Lapis ore blocks (`id: 21`) to La peice (`id: 42`) and generating subterranean Grottos in newly generated chunks without disturbing existing player builds.

---

## 11. 42-Point Automated QA & Verification Matrix

The engine includes 42 automated self-tests executing on boot or via test suites:
1. `TEST_CHUNK_INIT`: Voxel array allocations and memory footprint.
2. `TEST_LIGHTING_SUN`: Vertical sunray propagation to surface voxels.
3. `TEST_LIGHTING_CLIFF`: Air-column illumination fix on steep ravine cliff faces.
4. `TEST_LA_PEICE_GEN`: Ore vein clustering and $Y=5\dots 32$ depth distribution.
5. `TEST_LA_PEICE_DROPS`: Drop yield validation (4–8 gems, Fortune scaling).
6. `TEST_ENCHANT_RECIPE`: Enchanting table crafting recipe validation.
7. `TEST_BOOKSHELF_SYNERGY`: Max level calculation with 0 to 15 bookshelves.
8. `TEST_ENCHANT_GLINT`: Purple shader glint state flag assignment.
9. `TEST_VILLAGE_FOUNDATION`: Stilt extrusion logic over downward slopes.
10. `TEST_VILLAGE_DOORSTEP`: Step and slab grading at house entryways.
11. `TEST_VILLAGE_BIOMES`: Biome material palette mapping (Plains, Desert, Taiga, Savanna).
12. `TEST_BLACKSMITH_LOOT`: Verification of furnace, anvil, and high-tier chest contents.
13. `TEST_IRON_GOLEM_SPAWN`: T-shape block build detection and health pool ($100\text{ HP}$).
14. `TEST_TOWN_BELL`: Alarm broadcast and villager pathing to shelter.
15. `TEST_BIPLANE_PITCH`: Non-inverted elevator control surface physics.
16. `TEST_BIPLANE_STALL`: Lift decay below $12\text{ m/s}$ airspeed.
17. `TEST_BIPLANE_AUTOPILOT`: Heading and altitude hold PID convergence.
18. `TEST_BIPLANE_CHART`: Live navigation chart non-pausing operation.
19. `TEST_BIPLANE_EJECT`: Bail-out confirmation modal at high altitude.
20. `TEST_ROADSTER_SUSPENSION`: 4-wheel spring-damper compression.
21. `TEST_ROADSTER_SPEED`: Speed boost on paved roads ($45\text{ m/s}$).
22. `TEST_TURBO_BOAT_BUOYANCY`: Water displacement and ocean cruising ($32\text{ m/s}$).
23. `TEST_BIOFUEL_REFINERY`: Sugar cane/potato to Ethanol to Biofuel Canister conversion.
24. `TEST_FUEL_DEPLETION`: Vehicle engine cut-off on zero fuel.
25. `TEST_DRAGON_ARENA`: End Crystal regeneration beams and victory portal spawn.
26. `TEST_WITHER_SPAWN`: Soul sand T-shape + skulls summon and Wither Armor threshold.
27. `TEST_ELDER_GUARDIAN`: Mining Fatigue effect aura and Abyssal Heart drop.
28. `TEST_WARDEN_VIBRATION`: Sculk sensor trigger and sonic boom damage.
29. `TEST_TURBOCHARGER_MOD`: Speed multiplier application on Biplane.
30. `TEST_DRAGONWING_SAILS`: Stall speed reduction to $6\text{ m/s}$.
31. `TEST_WAYFARER_RECIPE`: Material cost verification ($36\text{ Diamonds}, 2\text{ Netherite}, 2\text{ Riftmetal}, 1\text{ Star}, 12\text{ Dust}$).
32. `TEST_PHASE_CELL_CONSUME`: Dimension transit cell deduction.
33. `TEST_TAB_SAFE_PAUSE`: Cursor unlock and world freeze on `Tab`.
34. `TEST_KEYBIND_ROSTER`: Key registrations for E, B, O, M, N, J, H, K, V, P, Esc.
35. `TEST_RECIPE_BOOK_SEARCH`: Substring matching across 414 recipes.
36. `TEST_RECIPE_TREE_NAV`: Recursive ingredient click exploration.
37. `TEST_HUD_PINBOARD`: Material checklist persistence on HUD.
38. `TEST_TOUCH_MULTI_POINTER`: Independent aiming and mining touch IDs.
39. `TEST_TOUCH_JOYSTICK`: Normalized vector calculation and deadzone.
40. `TEST_MOBILE_INVENTORY`: Move Stack, Split 1, and Quick Move touch operations.
41. `TEST_SAVE_MIGRATION_32`: Upgrade of Build 3.2 worlds without data loss.
42. `TEST_SAVE_INTEGRITY`: Round-trip JSON export and import serialization.