livingWorld/README.md

# Living World

A NeoForge 1.21.1 ecosystem simulation mod that turns every region of your world into a living, breathing environment. Pollution, soil quality, water cycles, vegetation succession, climate events, tidal systems, and river erosion interact in a fully simulated pipeline — all visible as real block changes and player effects in-game.

---

## Overview

The world is divided into **regions** (configurable chunk-grid cells, default 16×16 chunks). Each region is independently simulated through a 9-stage pipeline every tick cycle. Everything from a single furnace firing to a multi-region wildfire can alter the ecological trajectory of the land you stand on.

---

## Simulation Pipeline

Modules run in this fixed order each cycle so each stage reads fully updated data from the stage before it:

| # | Module | Role |
|---|--------|------|
| 1 | **Pollution** | Decays air/ground/water pollution; leaches ground → water |
| 2 | **Soil** | Updates fertility, moisture, contamination, compaction, erosion |
| 3 | **Water** | Tracks availability, purification, drought/flood risk |
| 4 | **Vegetation** | Succession: grass → flowers → shrubs → trees; die-off under stress |
| 5 | **Resource Depletion** | Tracks mining, logging, farming pressure |
| 6 | **Recovery** | Manages ecological succession stage (BARREN → MATURE_FOREST) |
| 7 | **Ecosystem** | Synthesises overall health, stress, resilience |
| 8 | **World Effects** | Translates simulation state into visible block changes |
| 9 | **Atmosphere** | Per-region weather (rain/thunder/acid rain) driven by health |

---

## Feature Status

### Core Ecosystem — **Complete**

- **Pollution system** — air, ground, and water pollution tracked independently; natural decay rates; tree canopy scrubs air pollution; ground leaches into water
- **Soil dynamics** — fertility, moisture, contamination, compaction, erosion; spring snowmelt and autumn leaf decomposition cycle
- **Water simulation** — availability, drought risk, flood risk, purification capacity; runoff flows downhill between regions carrying pollution downstream
- **Vegetation succession** — grass → flowers → shrubs → trees; each tier requires the tier below; severe stress kills trees before shrubs before grass
- **Recovery & succession** — six ecological stages (BARREN → SPARSE_GRASS → GRASSLAND → SCRUBLAND → YOUNG_WOODLAND → MATURE_FOREST); progress/damage system; biome-derived succession ceiling
- **Resource depletion** — logging, mining, farming each drain their respective region metrics
- **Ecosystem health** — synthesised score (0–100) based on all module outputs; feeds spawn suppression, player effects, ambient sounds

### Visible World Effects — **Complete**

All effects are real block changes players can see:

| Effect | Trigger | What You See |
|--------|---------|--------------|
| Grass degrades to dirt | Pollution > 15, soil < 75 | Grass → dirt → coarse dirt |
| Vegetation spreads | Veg pressure > 60, soil > 50 | Dirt → grass, flowers, short grass |
| Vegetation dies | Soil < 20 OR pollution > 30 | Leaves and upper trunks removed; stumps left |
| Saplings boosted | Stage ≥ YOUNG_WOODLAND | Oak/birch/spruce/dark-oak/cherry saplings placed |
| Wildfire | Drought > 70, thunder > 0.5 | Fire placed on surface vegetation |
| Water pools form | Rain + barren/sparse terrain | Water source blocks in surface depressions |
| **River carve** | High accumulated water runoff | Water channels carved through natural terrain; gradually deepens |
| **Ground spring** | Saturated aquifer in valley floor | Permanent water source placed; river flows downhill naturally |
| **Hydraulic erosion** | Flowing water adjacent to rock | Stone → gravel → sand → air; valley walls slowly widen |
| **Lava flow** | Volcanic eruption | Lava source blocks placed at summit; flows and reshapes terrain |
| **Ash deposit** | Active eruption or nearby blast | Grass → tuff, soil → gravel; surface plants killed over wide area |
| **Cobblestone forms** | Lava cooling | Lava + water → cobblestone; lava in air → basalt; new permanent land |
| Pollution particles | Pollution > 10 | Smoke particles in degraded regions |

### Player Feedback — **Complete**

- **Compass HUD** — hold a compass (or `/lw hud`) to see the action-bar HUD:
  `[LW] (0,0)↑ Eco:72 Poll:3.2 Soil:61 Wat:58 Rain:42% Seeds:1.8`
  - Trend arrow (↑↓→) shows whether the region is recovering or declining
  - Seed rain displayed when active
  - Colour-coded (green/yellow/red) for each metric
- **Pollution effects** — nausea > 40, slowness > 60, weakness > 80 pollution; smoke fog particles
- **Mob spawn feedback** — passive mobs suppressed in regions below 30 health; hostile mobs suppressed above 60 health
- **Regional weather** — per-player rain/thunder packets matching region atmosphere; storm sends lightning visuals
- **Ambient sounds** — forest: rustling azalea leaves; barren: shifting sand; heavy pollution: basalt deltas mood
- **Climate event broadcasts** — drought, wildfire, flood events announced to all players

### Seasons — **Complete**

32-day year (8 days per season). Seasons affect all simulation layers:

| Season | Soil | Water | Vegetation | Drought |
|--------|------|-------|------------|---------|
| **Spring** | Fertility +, moisture ++ | Availability ++ | Grass/flower surge | Eases |
| **Summer** | Moisture — | Availability — (evaporation) | Mild growth (if moist) | Worsens |
| **Autumn** | Fertility + (decomposition) | — | Senescence, dead litter | Neutral |
| **Winter** | Moisture — (frost) | Availability — (freeze) | Die-back, shrubs retreat | Creeps up |

### Ecological Corridors & Seed Dispersal — **Complete**

- Healthy regions (YOUNG_WOODLAND+) emit seed rain each cycle to adjacent regions
- **Corridor boost**: ≥2 healthy neighbours → 3.5× seed effectiveness
- Pollution in target region blocks germination (proportional)
- Sufficient accumulated seed rain pioneers the succession cap one stage ahead of physical conditions
- Seed rain accumulation visible in HUD and `/lw atmosphere`

### Pollution Spreading — **Complete**

- Air pollution spreads to adjacent regions each cycle based on wind direction
- Wind drifts realistically (±0.05 rad per cycle); `/lw wind` shows direction and spread rate
- Downwind spread is boosted; upwind transfer is reduced
- Water runoff also carries ground pollution downstream (15% of runoff × ground pollution)

### Climate Events — **Complete** (multi-region)

Automatically triggered when regional conditions reach critical thresholds. All have visible in-world effects.

#### Drought
- **Trigger**: water availability < 20, drought risk > 65, with 2+ dry neighbours
- **Effect**: further drains water availability and raises drought risk across affected regions; spreads to adjacent dry regions every 5 cycles
- **Resolution**: epicentre water availability recovers above 45

#### Wildfire
- **Trigger**: YOUNG_WOODLAND+ region, drought risk > 65, no rain, air pollution > 25 (stochastic)
- **Effect**: `VEGETATION_DIES` and `WILDFIRE` block effects (actual fire!) on affected regions; air pollution spike; spreads to adjacent drought-stressed forest
- **Resolution**: rain level > 0.4 in epicentre

#### Flood
- **Trigger**: water availability > 92, rain > 0.72, with a lower-elevation downstream neighbour
- **Effect**: `WATER_POOL_FORMS` in downstream regions; soil contamination from silt
- **Resolution**: water availability drops below 70 or rain eases

### Desertification Permanence — **Complete**

- Regions with sustained heavy damage (damage accumulation > 65, health < 20) have their succession cap **lowered** by one stage
- This means a desertified region can no longer recover to forest on its own — player intervention (removing pollution, adding water, bone meal, replanting) is required
- Players are notified via chat when desertification lowers a cap

### Region Trend Tracking — **Complete**

- Last 5 health samples per region stored each post-sim cycle
- Trend arrow (↑↓→) computed from recent vs older average
- Visible in the compass HUD next to the region coordinates
- Full trend detail in `/lw atmosphere`

### Groundwater & Springs — **Complete**

- Every region tracks a subsurface aquifer level that recharges slowly from rainfall
- Underground seepage: high-elevation neighbours drain laterally into the aquifer of lower regions (water flows underground even between sim cycles)
- When the aquifer is saturated in a **valley floor** (≥2 higher neighbours), a `GROUND_SPRING_EMERGES` effect fires — a water source block is placed at the lowest natural terrain point
- The spring flows downhill under Minecraft's own fluid physics, forming a permanent river without further simulation involvement
- Active springs contribute to river erosion intensity even without rain

### River Erosion & Hydraulic Erosion — **Complete**

- Accumulated water runoff intensity tracked per region (flow from higher → lower elevation)
- When flow intensity crosses the threshold (80 units), a `RIVER_CARVE` world effect fires
- Block effect: water source placed on natural terrain; at high intensity the block below is removed (deepening channel)
- **Hydraulic erosion** fires independently of rainfall whenever significant flow intensity is present: flowing water (level 1–7) adjacent to soft rock softens it — stone → gravel → sand → air — progressively widening river valleys
- Rivers form gradually over many sim cycles — permanent terrain changes

### River Current Physics — **Complete** (real player forces)

- Every 4 ticks, all players standing in **flowing** water (level 1–7) receive a directional velocity push
- Force direction: `FluidState.getFlow()` — the exact vector Minecraft already computes for its own flow rendering; currents always point the same way the water visually flows
- Force magnitude: scales with flow level — level 7 (one block from a spring, fastest) pushes hard; level 1 (distant, slow lowland river) barely nudges
- Mountain rivers are genuinely dangerous to wade against; lowland rivers are gentle enough to cross
- Boats are naturally carried by vanilla water physics; swimming players and mobs now feel the additional push

### Volcanic System — **Complete** (new land formation)

Four-phase lifecycle per high-elevation region (average surface Y ≥ 85):

| Phase | What Happens |
|-------|-------------|
| **DORMANT** | Normal state; rare stochastic chance to awaken (~0.2% per check) |
| **BUILDING** | Seismic venting — mild pollution spike; player broadcast warns of imminent eruption |
| **ERUPTING** | `LAVA_FLOW` places source blocks at the summit; `ASH_DEPOSIT` covers surrounding terrain; ash clouds spread to adjacent regions; vegetation dies in the eruption zone; air pollution spikes; lasts ~40 sim cycles |
| **COOLING** | `COBBLESTONE_FORMS` converts lava adjacent to water → cobblestone; lava in air → basalt; permanent new terrain created where none existed before |
| **FERTILE** | Volcanic minerals boost soil fertility +30, contamination −20; pollution decays rapidly; succession cap can rise; then returns DORMANT |

Visible effects:
- Lava flows downhill under vanilla physics, permanently reshaping terrain
- Ash converts grass → tuff, loose soil → gravel; kills surface plants across a wide area
- New cobblestone and basalt islands form where lava met water
- Players in active eruption zones hear fire crackle ambience; building-phase rumble in BUILDING regions

### Tidal Simulation — **Complete** (physical blocks)

- Two tidal cycles per Minecraft day (24 000 ticks) using a sine wave
- Every 1 200 ticks (~1 real minute):
  - **Coastal regions** (elevation ≤ sea level + 6) receive water-availability adjustments
  - **Physical block changes**: on rising tide, water sources are placed on natural shoreline blocks (sand/gravel/stone) at sea level; on falling tide, those sources are removed
- Result: visible waterline that rises and falls on beaches and ocean shores

### Biome-Aware Initialisation — **Complete**

- When a player first enters a region, the biome temperature and downfall (wetness) are read
- Soil fertility, soil moisture, water availability, and drought risk are initialised to biome-appropriate starting values
- Deserts start arid and nutrient-poor; jungles/swamps start moist and fertile; mountains start cool and dry
- Biome-derived succession ceiling set simultaneously (desert = SPARSE_GRASS cap; forest = MATURE_FOREST cap)

### Config File — **Complete**

Server-side TOML: `world/serverconfig/livingworld-server.toml`

Tunable at runtime without recompiling:

```toml
[pollution]
  decay_rate = 0.002
  ground_to_water_leach = 0.0005
  spread_rate = 0.02
  wind_boost = 0.5

[vegetation]
  grass_growth_rate = 0.06
  flower_growth_rate = 0.04
  shrub_growth_rate = 0.03
  tree_growth_rate = 0.02
  # ... dieoff rates

[recovery]
  base_progress_per_tick = 2.0
  damage_per_bad_tick = 1.5
  damage_decay_rate = 0.05

[seed_dispersal]
  seed_emission_rate = 0.01
  corridor_boost_multiplier = 3.5
  seed_pollution_block = 0.015
```

### Persistence — **Complete**

All 8 data-bearing modules use a Properties-based codec system. Region data survives server restart correctly. Global climate tracker (carbon ppm, warming level, biodiversity index) saved separately to `living_world/global_climate.dat`.

### Region Border Visualiser — **Complete**

`/lw region borders` — sends cyan dust particles along all 4 edges of the region at surface height. Optional `[regionX regionZ]` args to visualise a specific region.

---

## Commands

All commands require permission level 2.

| Command | Description |
|---------|-------------|
| `/lw status` | Show active regions, enabled modules, simulation tick |
| `/lw region info [x z]` | Full diagnostics for current or specified region |
| `/lw region borders [rx rz]` | Visualise region boundary with particles |
| `/lw region force-update` | Force an immediate simulation cycle on current region |
| `/lw region set <stat> <value>` | Manually override a region metric (debug) |
| `/lw map [radius]` | ASCII coloured region map (1–7 radius, default 3) |
| `/lw atmosphere` | Region atmosphere: season, rain, storm, succession, trend, seeds |
| `/lw climate` | Global climate: CO₂ ppm, warming °C, biodiversity, rain penalty |
| `/lw wind` | Wind direction, angle, spread rate, speed multiplier |
| `/lw hud` | Toggle persistent HUD without holding compass |
| `/lw speed <1–100>` | Accelerate simulation (100x = very fast testing) |
| `/lw speed reset` | Return to real-time speed (1x) |
| `/lw simulate <ticks>` | Force N simulation cycles on all active regions |
| `/lw stats` | Simulation profiler statistics |
| `/lw modules list` | List all registered modules and their enabled state |
| `/lw events` | List all active climate events (drought/wildfire/flood/eruption) with epicentre, severity, affected regions |
| `/lw volcanoes` | List all tracked volcanic regions and their current lifecycle phase |
| `/lw demo degrade` | One-command demo: degrade current region to barren |
| `/lw demo recover` | One-command demo: restore current region to mature forest |

### /lw map Output Example

```
[LW] Map 7×7 around (0,0) | [X]=you, ↑N ↓S ←W →E
 F  F  W  W  s  ·  ·
 F  F  W  s  G  G  ·
 F  W [X] G  G  g  ·
 W  G  G  G  g  B  ·
 s  G  g  B  B  ·  ·
 ·  ·  ·  ·  ·  ·  ·
 ·  ·  ·  ·  ·  ·  ·
F=Forest W=Woodland s=Scrub G=Grass g=Sparse B=Barren ·=Unknown
```

---

## Compass HUD Reference

Hold a compass (or `/lw hud`) to see the action-bar HUD:

```
[LW] (0,0)↑ Eco:72 Poll:3.2 Soil:61 Wat:58 Rain:42% Storm:8% Seeds:1.8
```

| Field | Meaning |
|-------|---------|
| `(0,0)` | Region coordinates |
| `↑↓→` | Ecosystem health trend (recovering / declining / stable) |
| `Eco` | Ecosystem health 0–100 (green >60, yellow >30, red ≤30) |
| `Poll` | Pollution score 0–100 (green <15, yellow <40, red ≥40) |
| `Soil` | Soil quality 0–100 |
| `Wat` | Water quality 0–100 |
| `Rain` | Regional rain level % |
| `Storm` | Thunder/storm level % (shown only when >15%) |
| `Seeds` | Accumulated seed rain (shown only when active) |

---

## Succession Stages

| Stage | Symbol | Conditions Required |
|-------|--------|---------------------|
| BARREN | `B` | — |
| SPARSE_GRASS | `g` | Soil ≥ 10, pollution ≤ 80, veg ≥ 10 |
| GRASSLAND | `G` | Soil ≥ 25, pollution ≤ 70, veg ≥ 20 |
| SCRUBLAND | `s` | Soil ≥ 40, pollution ≤ 60, veg ≥ 35 |
| YOUNG_WOODLAND | `W` | Soil ≥ 50, pollution ≤ 50, veg ≥ 45 |
| MATURE_FOREST | `F` | Soil ≥ 60, pollution ≤ 40, veg ≥ 55 |

Biome caps prevent a desert from reaching MATURE_FOREST naturally. Sustained damage (damage accumulation > 65, health < 20) can lower the cap permanently — **desertification**. Player intervention is required to restore the potential.

---

## Player Effects from Pollution

| Pollution Level | Effect |
|----------------|--------|
| > 40 | Nausea (Confusion) + smoke fog particles |
| > 60 | Slowness |
| > 80 | Weakness |

---

## Architecture

```
LivingWorldMod (NeoForge event wiring)
  └─ LivingWorldBootstrap (lifecycle, post-sim hooks)
       ├─ SimulationManager → SimulationScheduler → RegionUpdateJob
       ├─ RegionManager → RegionStorage → FileRegionPersistenceService
       ├─ ModuleRegistry (9 modules, pipeline order)
       ├─ GlobalClimateTracker (CO₂, warming, biodiversity)
       ├─ EcosystemTuning (config-loaded tuning constants)
       └─ Post-sim hooks:
            spreadPollutionAcrossRegions()  [wind-driven]
            applySeasonalEffects()          [soil/water/veg seasonal]
            applyClimateWarmingEffects()    [drought pressure from CO₂]
            applyWaterRunoff()              [elevation-based; river erosion]
            applyGroundwaterAndSprings()    [aquifer recharge; valley springs]
            applyDynamicCapUpdate()         [raise/lower succession ceiling]
            applySeedDispersal()            [corridor-boosted recolonisation]
            recordHealthTrend()             [↑↓→ trend tracking]
            applyClimateEvents()            [drought/wildfire/flood events]
            applyVolcanicActivity()         [volcano lifecycle; lava/ash/new land]

LivingWorldMod platform hooks:
    updateTidalEffects()                    [block-level tidal simulation]
    applyRiverCurrents()                    [player/entity velocity in flowing water]
    initializeRegionFromBiome()             [biome-aware starting values]
    checkPlayerRegions()                    [HUD, effects, ambient sounds]
    scanAndRecordFurnaceActivity()          [pollution from lit furnaces]
```

---

## Building

```bash
./gradlew build
```

Output: `build/libs/living_world-*.jar`

Requires NeoForge 21.1.172 / Minecraft 1.21.1.

---

## Planned / In Progress

- Full worldgen integration (custom biome distribution, terrain shaping beyond post-load modification)
- Persistence for river flow intensity, groundwater level, and volcanic state across restarts
- Multiplayer region ownership / notification system
- More succession stages (wetland, alpine, volcanic basalt plain)
- Snowmelt rivers: winter snow accumulation releases as meltwater in spring
- Player damage in active eruption zones (lava proximity heat)