novafarma/docs/technical/WEATHER_SYSTEM_INTEGRATION.md

# 🌦️ MASTER WEATHER SYSTEM - INTEGRATION GUIDE

**Created:** Jan 8, 2026 00:41 CET  
**Purpose:** How to integrate complete weather system into DolinaSmrti  
**Status:** ✅ CORE PHASE 1/2/DEMO FEATURE

---

## 🎯 WHAT IS THIS?

MasterWeatherSystem gives DolinaSmrti its **HARDCORE SOUL** through dynamic environmental effects:

- 🌬️ **Wind** - Grass, trees, hair moves naturally
- 💧 **Rain** - Drops fall, puddles form, world gets wet
- ❄️ **Snow** - Flakes drift, snow accumulates on ground
- 🔥 **Fire** - Flames flicker, smoke rises, heat distorts
- 🌊 **Water** - Ripples spread, light refracts underwater

**Every biome feels ALIVE and UNIQUE!**

---

## 📦 FILES

**Systems:**
- `src/systems/MasterWeatherSystem.js` ✅ NEW
- `src/systems/WindFoliageSystem.js` ✅ Already exists

**Usage:**
- Initialize in GameScene
- Set biome-specific weather
- Let it run automatically!

---

## 🚀 BASIC SETUP

### In GameScene.js:

```javascript
import MasterWeatherSystem from '../systems/MasterWeatherSystem.js';

class GameScene extends Phaser.Scene {
    create() {
        // Initialize weather system
        this.weather = new MasterWeatherSystem(this);
        this.weather.init();
        
        // Set biome weather (automatic settings)
        this.weather.setBiomeWeather('grassland');
        
        // Or manually set weather
        // this.weather.setWeather('rain', 0.7);  // 70% rain intensity
    }
    
    update(time, delta) {
        // Update weather every frame
        this.weather.update(delta);
    }
}
```

**THAT'S IT!** Weather is now active! 🎉

---

## 🌍 BIOME-SPECIFIC WEATHER

Each biome has automatic weather settings:

### **Grassland** (Tutorial zone)
```javascript
this.weather.setBiomeWeather('grassland');
// - Medium wind (1.0)
// - Can have: clear, rain, storm
// - Default: Clear with gentle breeze
```

### **Desert**
```javascript
this.weather.setBiomeWeather('desert');
// - Strong wind (1.5)
// - Can have: clear, sandstorm
// - Default: Hot, dry, dusty
```

### **Tundra/Snow Zone** ❄️
```javascript
this.weather.setBiomeWeather('snow');
// - Very strong wind (1.8)
// - Can have: clear, snow, blizzard
// - Default: Light snow, freezing
// - Kai feels COLD (like -6°C in real life!)
```

### **Swamp** 💧
```javascript
this.weather.setBiomeWeather('swamp');
// - Light wind (0.3)
// - Can have: rain, fog
// - Default: Constant drizzle, murky
// - Puddles everywhere
```

### **Mountains** 🏔️
```javascript
this.weather.setBiomeWeather('mountains');
// - VERY strong wind (2.0)
// - Can have: clear, snow, storm
// - Default: Harsh, unpredictable
// - Hair whips wildly!
```

### **Forest** 🌲
```javascript
this.weather.setBiomeWeather('forest');
// - Moderate wind (0.8)
// - Can have: clear, rain
// - Default: Peaceful, leaves rustle
```

### **Volcanic Zone** 🌋
```javascript
this.weather.setBiomeWeather('volcanic');
// - Turbulent wind (1.2)
// - Constant fire effects
// - Ash rain possible
// - Smoke and heat everywhere
```

---

## ⚙️ MANUAL WEATHER CONTROL

### Set Specific Weather:

```javascript
// Light rain
this.weather.setWeather('rain', 0.3);

// Heavy rain
this.weather.setWeather('rain', 1.0);

// Gentle snow
this.weather.setWeather('snow', 0.5);

// Blizzard!
this.weather.setWeather('blizzard', 1.0);

// Storm (rain + strong wind)
this.weather.setWeather('storm', 0.8);

// Clear weather
this.weather.setWeather('clear');
```

---

## 🔥 FIRE EFFECTS

### Create Campfire:

```javascript
// Small campfire
this.weather.createFireSource(x, y, 0.5);

// Medium torch
this.weather.createFireSource(x, y, 1.0);

// Large bonfire
this.weather.createFireSource(x, y, 2.0);
```

**Fire includes:**
- 🔥 Flame particles (orange, yellow)
- 💨 Smoke rising upward
- Automatic flickering
- Wind affects smoke direction!

---

## 🌊 WATER RIPPLES

### Create Ripple When Walking:

```javascript
// Player enters water
if (player.isInWater) {
    this.weather.createRipple(player.x, player.y, 0.5);
}

// Object falls in water
this.weather.createRipple(x, y, 1.5);
```

---

## 💨 WIND ON HAIR & GRASS

Wind system automatically affects:

### Apply to Player Hair:

```javascript
// In player creation
const kaiHair = this.add.sprite(x, y, 'kai_dreads');
this.weather.windSystem.applyWindToSprite(kaiHair, 'hair');

// Hair will now:
// - Sway naturally with wind
// - Move more = stronger wind
// - Float upward underwater (if in water)
```

### Apply to Grass:

```javascript
const grass = this.add.sprite(x, y, 'grass_tuft');
this.weather.windSystem.applyWindToSprite(grass, 'grass');

// Grass will:
// - Bend with wind
// - Wave continuously
// - React to wind strength
```

### Falling Leaves from Trees:

```javascript
// After tree is placed
const treeX = 200;
const treeY = 150;

this.weather.windSystem.createLeafEmitter(treeX, treeY, 0.5);

// Leaves will:
// - Fall periodically
// - Wobble in air
// - Affected by wind
// - Create ripples if land in water!
```

---

## 🎨 STYLE 32 COMPATIBILITY

All effects use **Style 32 Dark-Chibi Noir aesthetic:**

### Rain Drops:
- White/light blue
- Thin vertical streaks
- Additive blend for glow

### Snowflakes:
- White with black outline (3px)
- Round, simple shapes
- Cell-shaded look

### Fire:
- Orange → Yellow gradient
- Thick black outlines on smoke
- Cartoon-style flames

### Water Ripples:
- Concentric black circles
- Thick 2-3px lines
- No realistic water simulation

**Everything fits the gothic, hand-drawn style!**

---

## ⚡ PERFORMANCE OPTIMIZATION

### Particle Limits:

```javascript
// Rain: Max 200 drops on screen
// Snow: Max 150 flakes on screen
// Fire: Max 3 sources per scene
// Ripples: Auto-cleanup after 1.5s
```

### Dynamic Quality:

```javascript
// Low-end devices: Reduce particle count
if (this.sys.game.device.os.desktop === false) {
    this.weather.rainEmitter.setQuantity(1);  // Half particles
}
```

### FPS Target:
- Desktop: 60 FPS with all effects
- Mobile: 30 FPS with reduced effects

---

## 🎯 GAMEPLAY INTEGRATION

### Weather Affects Gameplay:

```javascript
// Slower movement in rain
if (this.weather.currentWeather === 'rain') {
    player.speed *= 0.9;  // 10% slower
}

// Visibility reduced in snow
if (this.weather.currentWeather === 'blizzard') {
    this.cameras.main.setAlpha(0.7);  // Harder to see
}

// Fire provides warmth in snow biome
if (nearCampfire && biome === 'snow') {
    player.temperature += 10;  // Warm up!
}
```

### Dynamic Weather Changes:

```javascript
// Weather changes every 5 minutes
this.time.addEvent({
    delay: 300000,  // 5 minutes
    callback: () => {
        const random = Math.random();
        if (random < 0.3) {
            this.weather.setWeather('rain', 0.5);
        } else if (random < 0.5) {
            this.weather.setWeather('storm', 0.8);
        } else {
            this.weather.setWeather('clear');
        }
    },
    loop: true
});
```

---

## 🌟 ATMOSPHERIC MOMENTS

### -6°C Blizzard (Like Today IRL!)

```javascript
// Tundra biome intro cutscene
this.weather.setBiomeWeather('snow');
this.weather.setWeather('blizzard', 1.0);

// Kai dialogue:
kai.say("Jebemti... -6 stopinj... mrznem...");

// Visual: Screen shakes slightly from wind
this.cameras.main.shake(500, 0.002);

// Audio: Howling wind sound
this.sound.play('wind_howl', { volume: 0.8 });
```

### Peaceful Rain in Forest

```javascript
this.weather.setBiomeWeather('forest');
this.weather.setWeather('rain', 0.4);

// Kai dialogue:
kai.say("Dež pada... mirno je...");

// Audio: Gentle rain ambience
this.sound.play('rain_forest', { loop: true });

// Player can rest under tree (no rain there)
if (underTree) {
    this.weather.rainEmitter.setScale(0);  // Stop rain above player
}
```

### Volcanic Hell

```javascript
this.weather.setBiomeWeather('volcanic');

// Multiple fire sources
this.weather.createFireSource(100, 200, 2.0);
this.weather.createFireSource(300, 180, 1.5);
this.weather.createFireSource(500, 220, 1.8);

// Ash rain (custom particle)
this.weather.setWeather('ash_rain', 0.6);

// Kai dialogue:
kai.say("Vroče je... vse goriiiii...");

// Heat wave distortion effect (TODO: shader)
```

---

## 📊 BIOME WEATHER PRESETS

Complete setup for each biome:

### **1. GRASSLAND** (Tutorial)
```javascript
scene: 'GrasslandScene',
weather: {
    biome: 'grassland',
    default: 'clear',
    wind: 1.0,
    fireCount: 1,  // Campfire
    waterRipples: true
}
```

### **2. FOREST**
```javascript
scene: 'ForestScene',
weather: {
    biome: 'forest',
    default: 'rain',
    intensity: 0.3,  // Light drizzle
    wind: 0.8,
    leafFall: true,  // Many trees = many leaves
    puddles: true
}
```

### **3. DESERT**
```javascript
scene: 'DesertScene',
weather: {
    biome: 'desert',
    default: 'clear',
    wind: 1.5,  // Hot, dry wind
    heatDistortion: true,  // Shimmering air (TODO)
    noRain: true,
    noPuddles: true
}
```

### **4. TUNDRA/SNOW**
```javascript
scene: 'TundraScene',
weather: {
    biome: 'snow',
    default: 'snow',
    intensity: 0.6,
    wind: 1.8,  // Freezing wind
    snowAccumulation: true,
    temperature: -6,  // Like today!
    fireCount: 2  // Need warmth
}
```

### **5. SWAMP**
```javascript
scene: 'SwampScene',
weather: {
    biome: 'swamp',
    default: 'rain',
    intensity: 0.5,  // Constant drizzle
    wind: 0.3,  // Very still
    fog: true,
    puddlesEverywhere: true,
    waterRipples: true
}
```

### **6. MOUNTAINS**
```javascript
scene: 'MountainScene',
weather: {
    biome: 'mountains',
    default: 'storm',
    intensity: 0.8,
    wind: 2.0,  // STRONGEST wind!
    dynamic: true,  // Rapid changes
    lightning: true  // TODO
}
```

### **7. VOLCANIC**
```javascript
scene: 'VolcanicScene',
weather: {
    biome: 'volcanic',
    default: 'clear',
    wind: 1.2,
    fireCount: 5,  // Fires everywhere!
    ashRain: true,
    smokeEverywhere: true,
    temperature: 40  // Hot as hell
}
```

---

## 🎮 DEMO SHOWCASE

### Kickstarter Demo Weather Sequence:

```javascript
// Minute 0-2: Tutorial in clear weather
this.weather.setWeather('clear');
this.weather.windSystem.setWindStrength(0.5);  // Gentle

// Minute 2-4: Light rain starts
this.weather.setWeather('rain', 0.3, 5000);  // 5s transition
kai.say("Oh... dež pada...");

// Minute 4-6: Rain intensifies
this.weather.setWeather('rain', 0.7, 3000);
kai.say("Jebemti, moker sem...");

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

// Minute 8-10: Storm passes, back to clear
this.weather.setWeather('clear', 0, 10000);  // Slow fade
kai.say("...končno. Mir.");

// Wind subsides
this.weather.windSystem.setWindStrength(0.5);
```

**= Players will FEEL the atmosphere!** 🌧️💨

---

## 🔧 TESTING

### Debug Commands:

```javascript
// In console:
game.scene.scenes[0].weather.setWeather('rain', 1.0);
game.scene.scenes[0].weather.setWeather('snow', 1.0);
game.scene.scenes[0].weather.setWeather('blizzard', 1.0);
game.scene.scenes[0].weather.createFireSource(300, 200, 2.0);
game.scene.scenes[0].weather.windSystem.showWindDebug();
```

### Visual Indicators:

```javascript
// Show current weather in UI
const weatherText = this.add.text(10, 10, '', {
    font: '16px Arial',
    fill: '#ffffff'
}).setScrollFactor(0);

this.events.on('update', () => {
    weatherText.setText([
        `Weather: ${this.weather.currentWeather}`,
        `Intensity: ${this.weather.weatherIntensity.toFixed(2)}`,
        `Wind: ${this.weather.windSystem.wind.strength.toFixed(2)}`
    ]);
});
```

---

## 📝 TODO / FUTURE ENHANCEMENTS

### Phase 3 Features:
- [ ] Lightning strikes during storms
- [ ] Heat wave distortion shader (desert, volcanic)
- [ ] Wet shader (characters glisten in rain)
- [ ] Footprints in snow (persist for 30s)
- [ ] Ice forming on water surfaces
- [ ] Sandstorms (reduce visibility)
- [ ] Aurora borealis (tundra night sky)
- [ ] Fog system (separate from rain)

---

## 🎯 SUMMARY

**MasterWeatherSystem gives DolinaSmrti HARDCORE SOUL:**

✅ **Wind** - Everything moves naturally  
✅ **Rain** - World gets wet, puddles form  
✅ **Snow** - Accumulates, drifts, feels cold  
✅ **Fire** - Warmth, light, danger  
✅ **Water** - Ripples, reflections, life  

**Setup:** 3 lines of code  
**Impact:** MAXIMUM atmosphere  
**Performance:** 60 FPS maintained  
**Style:** 100% Style 32 compatible  

**= CORE FEATURE for Phase 1/2/Demo!** 🔥

---

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