LifeSimulator/README.md

# 🌿 Ecosystem Life Simulator

An interactive, pixelated ecosystem simulation built with pure **HTML5 Canvas, CSS3, and Vanilla JavaScript (ES Modules)**.

Observe predator-prey dynamics, biological lifecycles, carcass decomposition, floral blooming cycles, seed dispersal, and periodic rainstorms in a living sandbox meadow.

---

## 🌟 Key Features & Mechanics

### 1. 🐑 Sheep Grazing & Herd Behavior
* **Rapid Grazing (Node Removal):** Sheep are ravenous grazers. When a sheep reaches a plant, it instantly consumes and removes the entire plant node from the field. A herd of sheep can sweep through and clear an entire field in moments.
* **Grazing Reach & Hunger:** Sheep continuously search for food whenever hunger drops below 96%, with a configurable grazing reach.
* **Mating & 3-Meal Growth:** Satiated adult sheep seek mates and collide to birth a baby lamb. Baby lambs start at 55% scale and grow larger with each meal until reaching adult size after **3 meals**.
* **Evasion:** Sheep actively detect wolves in their perception radius and flee with a panic speed boost.

### 2. 🐺 Wolf Hunting, Combat Exertion & Population Controls
* **Combat Exertion (Lunge Health Cost):** Wolves expend health every time they deliver an attack bite. Reckless over-hunting without resting or eating inflicts stamina fatigue and damage.
* **Chase Drain:** Wolves expend hunger 50% faster while actively sprinting in hunt mode.
* **Controlled Reproduction:** Wolves require high satiety (86%+) and a long mating cooldown (35s+) to reproduce, preventing runaway wolf swarms from wiping out the sheep population unchecked.
* **Feeding:** Defeating a sheep restores hunger. Wolf pups must eat **3 meals** to mature into adult wolves.

### 3. 💀 Carcass Decay & Soil Enrichment
* **Decay Cycle:** Dead animals leave carcasses that decompose through flesh and skeletal stages before dissolving into rich brown soil mulch.
* **Decay Speed Slider:** Adjust decomposition rate from 0.2x to 3.0x.
* **Floral Blooms:** Fully decomposed remains fertilize the ground and trigger a **lush Flower Tuft** to sprout on the enriched soil.

### 4. 🌸 Flora Dynamics, Seed Dispersal & CPU Guard
* **Max Plant Cap (CPU Guard):** Strict upper ceiling slider (default: 90) preventing plant overpopulation and keeping framerates rock-solid.
* **Low Seed Spread Rate:** Mature, clustered plants have a rare chance (configurable, default 8%) to release an airborne dandelion seed that lands nearby.
* **Moisture & Withering:** Plants lose moisture during dry weather and wither away if unhydrated.
* **Periodic Rain:** Rain showers roll across the meadow periodically (or on demand), reviving all flora to 100% moisture.

### 5. 🎛️ Comprehensive State Sliders & Presets
* **Populations & Caps:**
  * Initial Sheep (2 - 80)
  * Initial Wolves (1 - 20)
  * Initial Plants (5 - 100)
  * Max Plant Cap (20 - 300)
* **Sheep Dynamics:**
  * Sheep Hunger Depletion Rate (0.2 - 3.0/s)
  * Grazing Reach (10 - 35px)
  * Sheep Mating Cooldown (10 - 60s)
* **Wolf Dynamics:**
  * Wolf Lunge Health Cost (0 - 20 HP)
  * Wolf Hunger Rate (0.5 - 3.5/s)
  * Attack Bite Damage (15 - 80)
  * Wolf Mating Cooldown (15 - 80s)
* **Flora & Atmosphere:**
  * Plant Seed Spread Chance (0 - 40%)
  * Plant Withering Speed (0.5 - 6.0/s)
  * Rain Frequency (0 - 100%)
  * Carcass Decay Speed (0.2x - 3.0x)
* **Preset Configuration Tools:**
  * **💾 Save As Defaults:** Saves your customized slider configuration to `localStorage` as your new default baseline.
  * **↺ Reset:** Reverts all sliders to your saved defaults.
  * **📋 Copy JSON:** Copies the current configuration object to your clipboard for sharing or manual tuning.

### 6. 📊 Extinction Event & Analytics
* If all animals perish, an extinction modal appears with an interactive population timeline chart (Sheep, Wolves, Plants) and detailed ecosystem stats.

---

## 📂 Project Architecture

```
LifeSimulator/
├── index.html            # Layout, categorized sliders sidebar, canvas arena, and modal
├── css/
│   └── style.css         # Modern dark theme, glassmorphic cards, custom sliders
├── js/
│   ├── config.js         # Settings, bounds, factory & custom defaults, localStorage
│   ├── state.js          # Population stats, birth/death counters, timeline snapshots
│   ├── particles.js      # Blood spray, eating crumbs, hearts, seeds, and ripples
│   ├── terrain.js        # Decals canvas buffer, blood spots, and carcass decomposition
│   ├── weather.js        # Rain cycles, cloud shadows, raindrops, and hydration
│   ├── entities/
│   │   ├── animal.js     # Base animal class (steering, hunger, mating, baby growth)
│   │   ├── sheep.js      # Sheep AI: rapid grazing, flee wolves, mate, baby growth
│   │   ├── wolf.js       # Wolf AI: multi-bite hunting, lunge health cost, mate
│   │   └── plant.js      # Grass & flower tufts, moisture depletion, regulated seeds
│   ├── ui.js             # Slider bindings, presets, HUD updates, chart rendering
│   ├── simulation.js     # Master simulation loop and entity manager
│   └── main.js           # Entry point and animation frame loop
└── README.md             # Project documentation
```

---

## 🚀 How to Run Locally

```bash
python -m http.server 8080
```
Then open your browser to **`http://localhost:8080`**.