novafarma/docs/technical/WEATHER_README.md

# 🌦️ WEATHER SYSTEM - QUICK START GUIDE

**Created:** Jan 8, 2026  
**Status:** ✅ READY FOR USE  
**Complexity:** Easy (3 lines of code!)

---

## ⚡ SUPER QUICK START

### 1. Initialize in main.js (ONCE):

```javascript
import GlobalWeatherManager from './managers/GlobalWeatherManager.js';

const game = new Phaser.Game(config);
game.weatherManager = new GlobalWeatherManager(game);
```

### 2. Use in ANY scene:

```javascript
import BaseScene from './scenes/BaseScene.js';

class MyScene extends BaseScene {
    create() {
        // That's it! Weather active!
        this.initWeather('grassland');
        
        // Apply to hair
        this.weather.windSystem.applyWindToSprite(hairSprite, 'hair');
    }
    
    update(time, delta) {
        this.updateWeather(delta);
    }
}
```

**DONE!** Weather works everywhere! 🎉

---

## 📁 FILES

**Core Systems:**
- `src/systems/WindFoliageSystem.js` - Wind + leaves (✅ done)
- `src/systems/MasterWeatherSystem.js` - All weather (✅ done)
- `src/managers/GlobalWeatherManager.js` - Global control (✅ done)

**Helper Classes:**
- `src/scenes/BaseScene.js` - Extend this for auto-weather

**Examples:**
- `src/scenes/examples/BasementScene_EXAMPLE.js` - First scene
- `src/scenes/examples/ALL_BIOMES_WEATHER_EXAMPLES.js` - All biomes

**Documentation:**
- `docs/technical/WEATHER_SYSTEM_INTEGRATION.md` - Full guide
- `docs/technical/GLOBAL_WEATHER_INTEGRATION.md` - Scene-by-scene
- `docs/technical/ADVANCED_VISUAL_SYSTEMS_PLAN.md` - Water systems

---

## 🎯 WHAT YOU GET

✅ **Wind** - Hair, grass, trees move naturally  
✅ **Rain** - Drops fall, puddles form  
✅ **Snow** - Flakes drift, accumulates  
✅ **Fire** - Flames flicker, smoke rises  
✅ **Water** - Ripples spread from footsteps  

**All biome-specific & automatic!**

---

## 🌍 BIOME SETUP

Each biome has preset weather:

```javascript
// Grassland - Tutorial zone
this.initWeather('grassland');  
// → Medium wind, can rain

// Desert - Hot & windy
this.initWeather('desert');
// → Strong wind, sandstorms

// Tundra - FREEZING!
this.initWeather('snow');
this.weather.setWeather('blizzard', 0.9);
// → -6°C feels, heavy snow

// Volcanic - Fire everywhere
this.initWeather('volcanic');
// → Auto-creates fire sources

// Swamp - Wet & murky
this.initWeather('swamp');
this.weather.setWeather('rain', 0.5);
// → Constant drizzle, puddles

// Mountains - EXTREME wind
this.initWeather('mountains');
// → Player gets PUSHED by wind!

// Forest - Peaceful
this.initWeather('forest');
// → Many falling leaves

// Water biomes - Ripples
this.initWeather('cenote');
// → Hair floats underwater
```

---

## 💡 COMMON PATTERNS

### Apply Wind to Hair:
```javascript
const hair = this.add.sprite(x, y, 'kai_dreads');
this.weather.windSystem.applyWindToSprite(hair, 'hair');
// Hair now sways with wind!
```

### Apply Wind to Grass:
```javascript
const grass = this.add.sprite(x, y, 'grass_tuft');
this.weather.windSystem.applyWindToSprite(grass, 'grass');
// Grass now bends with wind!
```

### Tree Drops Leaves:
```javascript
const tree = this.add.sprite(200, 150, 'oak_tree');
this.weather.windSystem.createLeafEmitter(200, 150, 0.3);
// Leaves fall periodically!
```

### Create Fire (campfire, torch):
```javascript
this.weather.createFireSource(x, y, 1.5);
// Flames + smoke!
```

### Create Water Ripple:
```javascript
this.weather.createRipple(player.x, player.y, 0.5);
// Concentric circles spread!
```

### Change Weather Manually:
```javascript
this.weather.setWeather('rain', 0.7);    // 70% rain
this.weather.setWeather('snow', 0.5);    // 50% snow
this.weather.setWeather('blizzard', 1.0); // FULL blizzard!
this.weather.setWeather('clear');        // Clear sky
```

---

## 🚀 DEMO SEQUENCE

### Kickstarter Demo (10 minutes):

```javascript
// 0:00 - Basement wake up
this.initWeather('basement');
this.weather.windSystem.setWindStrength(0.2);  // Gentle draft
// → Hair moves from FRAME 1!

// 2:00 - Exit outside
this.initWeather('grassland');
// → Wind stronger, grass waves, leaves fall

// 4:00 - Rain starts
this.weather.setWeather('rain', 0.3, 5000);
kai.say("Oh... dež pada...");

// 6:00 - Storm!
this.weather.setWeather('storm', 1.0, 2000);
this.cameras.main.shake(1000, 0.005);
kai.say("FUCK! Vihar!");

// 8:00 - Clear again
this.weather.setWeather('clear', 0, 10000);
kai.say("...končno. Mir.");
```

**= Players will be AMAZED!** 🤯

---

## ⚠️ IMPORTANT

**Weather MUST be initialized in EVERY scene!**

**DON'T:**
```javascript
// ❌ Wrong - no weather!
class MyScene extends Phaser.Scene {
    create() {
        // Scene has no weather...
    }
}
```

**DO:**
```javascript
// ✅ Correct - weather active!
class MyScene extends BaseScene {
    create() {
        this.initWeather('grassland');
        // Weather works!
    }
    
    update(time, delta) {
        this.updateWeather(delta);
    }
}
```

---

## 🔧 DEBUGGING

### Check weather status:
```javascript
// In browser console:
game.weatherManager.debug();

// Output:
// Current Weather: rain
// Intensity: 0.7
// Wind Strength: 1.2
// Active Scenes: 2
```

### Force weather change:
```javascript
game.weatherManager.setGlobalWeather('blizzard', 1.0);
// All scenes now have blizzard!
```

### Show wind debug:
```javascript
game.scene.scenes[0].weather.windSystem.showWindDebug();
// Visual wind direction arrows
```

---

## 📊 PERFORMANCE

**Target:** 60 FPS on desktop, 30 FPS mobile

**Optimizations:**
- Particle pooling (max 200 particles)
- Shader-based (low RAM usage)
- Auto quality reduction on low FPS

**If FPS drops:**
```javascript
// Reduce particle count
this.weather.rainEmitter.setQuantity(1);
this.weather.snowEmitter.setQuantity(1);
```

---

## 🎨 STYLE 32 COMPATIBLE

All effects use **Style 32 Dark-Chibi Noir:**
- Thick black outlines (2-3px)
- Simple shapes
- Cell-shaded look
- Gothic aesthetic

**Everything fits the art style!** ✅

---

## 🔥 NEXT STEPS

1. ✅ Read this README
2. ✅ Look at examples in `src/scenes/examples/`
3. ✅ Extend `BaseScene` for your scenes
4. ✅ Call `initWeather()` in `create()`
5. ✅ Apply wind to sprites with `applyWindToSprite()`
6. ✅ Enjoy living, breathing world! 🌦️

---

**Questions? Check full docs:**
- `docs/technical/WEATHER_SYSTEM_INTEGRATION.md`
- `docs/technical/GLOBAL_WEATHER_INTEGRATION.md`

---

*DolinaSmrti - Where weather tells a story.* 🌦️💀