planetsim/docs/fauna-flora-plan.md

Next step — Fauna & Flora (derived carrying-capacity densities)

Status: planned, not yet implemented. This is the next World-Creation stage after climate. Approved design captured here so it can be picked up verbatim (e.g. after the project moves to another machine — the auto-memory does not travel, this doc does).

Decision summary

• Derived carrying-capacity map, not a live simulation: vegetation + wildlife density scalars recomputed each tick from the climate fields + terrain, exactly like biomes/climate. It answers "what could live here", not "what is living/evolving here".
• The actual time-evolving ecosystem (population growth, migration, predator-prey, extinction, seasons, species) is reserved for the future Live World real-time mode (year/season timescales — not the My geological clock).
• Fauna uses a herbivore + carnivore food-chain split.
• Fields are derived / not saved (deterministic functions of climate) → no save-format change. New config knobs ride the v6 self-describing save with no break.

Part A — Biosphere fields (src/sim/, raylib-free)

• Planet.hpp: declare void computeBiosphere(); + accessors const std::vector<double>& vegetation()/herbivores()/carnivores() const. Add scratch members std::vector<double> sVeg, sHerb, sCarn; (not saved).
• New src/sim/PlanetBiosphere.cpp — Planet::computeBiosphere() (run after computeClimate(); reads sTemp + sMoist):
  • Vegetation (flora) sVeg[i] ∈ [0,1]: 0 on water (elev ≤ seaLevel). On land, an NPP-style Liebig minimum of a temperature factor and a moisture factor:
    • tF = clamp((sTemp[i] − bioVegTempMin)/(bioVegTempOpt − bioVegTempMin), 0, 1)
    • mF = clamp(sMoist[i]/bioVegMoistRef, 0, 1)
    • sVeg = min(tF, mF) → lush warm-wet, ~0 in ice/desert/alpine (cold- or water-limited), matching the biomes.
  • Herbivores sHerb[i] = clamp(sVeg[i] · bioHerbProductivity, 0, 1) (capacity scales with plant productivity).
  • Carnivores sCarn[i]: present only where prey is abundant, ramping with it: sCarn = sHerb > bioCarnPreyMin ? clamp((sHerb − bioCarnPreyMin)/(1 − bioCarnPreyMin) · bioCarnScale, 0, 1) : 0 → concentrated in the richest regions (an energy-pyramid feel, visually distinct from the broader herbivore pattern).
• src/sim/Planet.cpp generate(): call computeBiosphere() after classifyBiomes().

Part B — Config knobs (PlanetTypes.hpp + PlanetIO.cpp)

Add to PlanetConfig + CONFIG_FIELDS + validateConfig:

key	default	meaning
bioVegTempMin	−5 °C	below this, no plant growth
bioVegTempOpt	15 °C	at/above this, temperature isn't limiting
bioVegMoistRef	0.5	normalized moisture at which water isn't limiting
bioHerbProductivity	0.9	herbivore capacity per unit vegetation
bioCarnPreyMin	0.30	min herbivore density to support carnivores
bioCarnScale	1.0	carnivore density ramp above the prey threshold

Part C — Rendering (src/render/)

• Colors.{hpp,cpp}: ColorMode += Vegetation, Herbivores, Carnivores; add vegColor (barren tan → lush green), herbColor (pale → amber/orange), carnColor (pale → red/violet); extend colorModeName.
• Viewer.cpp: recolor() adds the three cases (read the accessors, empty-guarded); refreshView() calls planet.computeBiosphere() after classifyBiomes().
• ViewerInput.cpp: KEY_EIGHT → Vegetation, KEY_NINE → Herbivores, KEY_ZERO → Carnivores (each recolor()). The top-center view-name label already shows the mode.
• ViewerRender.cpp renderHUD: controls line gains 8 veg 9 herbiv 0 carniv.
• Panels.cpp cellInfo(): add a life line — vegetation X% herbivores Y% carnivores Z% (guarded on the arrays being sized).

Verification (headless — extend the src/sim test set with PlanetBiosphere.cpp)

• Vegetation: 0 on ocean & Ice cells; near-0 on Desert; high (>0.6) on warm-wet Forest; all in [0,1]; finite; deterministic.
• Fauna food chain: sHerb correlates with sVeg; sCarn[i] > 0 ⇒ sHerb[i] > bioCarnPreyMin and carnivore-positive cells are a strict subset of herbivore-rich cells; all in [0,1]; deterministic.
• test_logic, biomes+config, climate suites still pass; app builds clean; no save change.
• GUI: 8 lush green continents thinning to barren in deserts/poles/peaks; 9 grazer density following productivity; 0 predators concentrated in the richest belts; cell info shows vegetation/herbivore/carnivore %.

Out of scope (future / Live World)

Time-evolving populations (growth, migration, predator-prey, extinction), seasons, and species/typed organisms — all part of the future Live World real-time simulation that runs the finished planet at hours/days/weeks/months with dynamic weather + life.