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:

[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

./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)