novafarma/docs/technical/GLOBAL_WEATHER_INTEGRATION.md

# 🌍 GLOBAL WEATHER SYSTEM - IMPLEMENTATION PLAN

**Created:** Jan 8, 2026 00:43 CET  
**Purpose:** Integrate MasterWeatherSystem into ENTIRE game from start to finish  
**Status:** 🔥 CORE DEFINING FEATURE

---

## 🎯 VISION

**MasterWeatherSystem is active from THE FIRST FRAME of the game.**

- Kai wakes up in basement → **Wind blows her dreads**
- Steps outside → **Grass moves with breeze**
- Enters water → **Ripples spread from footsteps**
- Rain starts → **World gets wet, puddles form**
- Enters tundra → **Blizzard, freezing cold (-6°C!)**
- Volcanic zone → **Fire and smoke everywhere**

**= THE GAME FEELS ALIVE AT ALL TIMES!**

---

## 📦 GLOBAL SETUP

### 1. Create Global Weather Manager

**File:** `src/managers/GlobalWeatherManager.js`

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

export default class GlobalWeatherManager {
    constructor(game) {
        this.game = game;
        this.weatherSystems = new Map();  // One per scene
        this.globalWeatherState = {
            type: 'clear',
            intensity: 0.5,
            windStrength: 1.0
        };
    }
    
    /**
     * Called when scene starts
     */
    createForScene(scene) {
        const weather = new MasterWeatherSystem(scene);
        weather.init();
        
        // Apply global weather state
        weather.setWeather(
            this.globalWeatherState.type,
            this.globalWeatherState.intensity
        );
        
        this.weatherSystems.set(scene.scene.key, weather);
        return weather;
    }
    
    /**
     * Change weather globally (affects all active scenes)
     */
    setGlobalWeather(type, intensity) {
        this.globalWeatherState.type = type;
        this.globalWeatherState.intensity = intensity;
        
        // Update all active scenes
        this.weatherSystems.forEach(weather => {
            weather.setWeather(type, intensity);
        });
    }
    
    /**
     * Cleanup when scene shutdown
     */
    destroyForScene(sceneKey) {
        const weather = this.weatherSystems.get(sceneKey);
        if (weather) {
            weather.destroy();
            this.weatherSystems.delete(sceneKey);
        }
    }
}
```

### 2. Initialize in main.js

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

const gameConfig = {
    // ... phaser config
};

const game = new Phaser.Game(gameConfig);

// Create global weather manager
game.weatherManager = new GlobalWeatherManager(game);

export default game;
```

### 3. Use in EVERY scene

```javascript
// In ANY scene (BasementScene, GrasslandScene, etc.)

class BasementScene extends Phaser.Scene {
    create() {
        // Get weather system from global manager
        this.weather = this.game.weatherManager.createForScene(this);
        
        // Scene-specific weather (optional)
        // this.weather.setBiomeWeather('basement');
        
        // Or use global weather (automatic)
        // Weather is already active!
    }
    
    update(time, delta) {
        this.weather.update(delta);
    }
    
    shutdown() {
        this.game.weatherManager.destroyForScene(this.scene.key);
    }
}
```

**THAT'S IT!** Weather is now in EVERY scene automatically! 🎉

---

## 🎬 SCENE-BY-SCENE INTEGRATION

### **SCENE 1: Basement (Game Start)** 🏚️

**Timing:** 0:00 - 2:00 (first 2 minutes)

```javascript
class BasementScene extends Phaser.Scene {
    create() {
        this.weather = this.game.weatherManager.createForScene(this);
        
        // Basement: still air, minimal wind (enclosed space)
        this.weather.windSystem.setWindStrength(0.2);
        
        // Apply wind to Kai's hair IMMEDIATELY
        const kaiHair = this.add.sprite(kaiX, kaiY, 'kai_dreads');
        this.weather.windSystem.applyWindToSprite(kaiHair, 'hair');
        
        // Hair moves gently (basement has drafts)
        // Player notices hair moving → FIRST impression of alive world!
    }
}
```

**EFFECT:** Player immediately sees Kai's dreads swaying. **Game feels alive from frame 1!**

---

### **SCENE 2: Exit to Surface (First Outdoor)** 🌄

**Timing:** 2:00 - 5:00

```javascript
class SurfaceScene extends Phaser.Scene {
    create() {
        this.weather = this.game.weatherManager.createForScene(this);
        
        // Outdoor: Medium wind (grassland)
        this.weather.setBiomeWeather('grassland');
        
        // Apply to ALL grass sprites
        this.grassTufts = this.add.group();
        for (let i = 0; i < 50; i++) {
            const grass = this.add.sprite(x, y, 'grass');
            this.weather.windSystem.applyWindToSprite(grass, 'grass');
            this.grassTufts.add(grass);
        }
        
        // Apply to trees
        this.trees.children.iterate(tree => {
            // Leaves fall from trees
            this.weather.windSystem.createLeafEmitter(tree.x, tree.y, 0.3);
        });
        
        // Kai dialogue when exits
        this.time.delayedCall(500, () => {
            kai.say("...zunaj je. Veter piha...");
        });
    }
}
```

**EFFECT:** 
- Wind suddenly stronger (player FEELS the transition indoors → outdoors)
- Grass waves everywhere
- Leaves fall from trees
- **Atmospheric impact = MAXIMUM!**

---

### **SCENE 3-10: All Biomes** 🌍

Each biome has unique weather **automatically:**

```javascript
// Forest Scene
class ForestScene extends Phaser.Scene {
    create() {
        this.weather = this.game.weatherManager.createForScene(this);
        this.weather.setBiomeWeather('forest');
        
        // Auto-sets:
        // - Moderate wind (0.8)
        // - Can rain
        // - Many falling leaves
    }
}

// Desert Scene
class DesertScene extends Phaser.Scene {
    create() {
        this.weather = this.game.weatherManager.createForScene(this);
        this.weather.setBiomeWeather('desert');
        
        // Auto-sets:
        // - Strong wind (1.5)
        // - Sandstorms possible
        // - Heat distortion (TODO)
    }
}

// Tundra Scene (HARDCORE!)
class TundraScene extends Phaser.Scene {
    create() {
        this.weather = this.game.weatherManager.createForScene(this);
        this.weather.setBiomeWeather('snow');
        this.weather.setWeather('blizzard', 0.8);
        
        // Kai dialogue
        kai.say("Jebemti... MRZNEMMM... -6 stopinj...");
        
        // Camera shake from wind
        this.cameras.main.shake(5000, 0.003);
        
        // Hair whips WILDLY
        this.weather.windSystem.setWindStrength(2.5);
    }
}
```

---

### **SCENE 11: Water Biomes (Cenotes, Atlantis)** 🌊

```javascript
class CenoteScene extends Phaser.Scene {
    create() {
        this.weather = this.game.weatherManager.createForScene(this);
        this.weather.setBiomeWeather('cenote');  // Custom biome
        
        // Water everywhere
        this.waterZones = [
            { x: 0, y: 300, width: 800, height: 200 }
        ];
        
        // Player enters water
        this.physics.add.overlap(player, waterZone, () => {
            // Ripples!
            this.weather.createRipple(player.x, player.y, 0.5);
            
            // Hair floats upward (buoyancy)
            this.weather.windSystem.windAffectedLayers.forEach(layer => {
                if (layer.sprite === player.hairLayer) {
                    layer.buoyantMode = true;
                }
            });
            
            // Kai dialogue
            if (!this.saidWaterLine) {
                kai.say("Voda je... čist? Wow...");
                this.saidWaterLine = true;
            }
        });
        
        // Underwater caustics (light patterns on floor)
        // TODO: Implement WaterCausticsSystem
    }
}
```

**EFFECT:**
- Ripples with EVERY step
- Hair floats upward underwater
- Caustics shimmer on floor
- **Players will screenshot this!**

---

### **SCENE 12: Volcanic Zone** 🌋

```javascript
class VolcanicScene extends Phaser.Scene {
    create() {
        this.weather = this.game.weatherManager.createForScene(this);
        this.weather.setBiomeWeather('volcanic');
        
        // Fire EVERYWHERE
        this.weather.createFireSource(100, 200, 2.5);
        this.weather.createFireSource(300, 180, 2.0);
        this.weather.createFireSource(500, 220, 3.0);
        this.weather.createFireSource(700, 190, 1.8);
        
        // Ash rain
        this.weather.setWeather('ash_rain', 0.6);
        
        // Heat ripples (TODO: shader)
        // Screen distortion effect
        
        // Kai dialogue
        kai.say("Vroče kot v peklu...");
    }
}
```

**EFFECT:**
- Fires flicker everywhere
- Smoke rises constantly
- Ash falls like snow
- **Oppressive, dangerous atmosphere**

---

## 🎮 GAMEPLAY INTEGRATION

### Player Movement Affected by Weather:

```javascript
// In Player.js update()

update(delta) {
    let speedModifier = 1.0;
    
    // Rain slows movement
    if (this.scene.weather.currentWeather === 'rain') {
        speedModifier *= 0.9;  // 10% slower
    }
    
    // Snow/blizzard slows more
    if (this.scene.weather.currentWeather === 'blizzard') {
        speedModifier *= 0.7;  // 30% slower
        this.temperature -= delta * 0.01;  // Getting cold!
    }
    
    // Strong wind pushes player
    if (this.scene.weather.windSystem.wind.strength > 1.5) {
        this.body.velocity.x += this.scene.weather.windSystem.wind.strength * 5;
    }
    
    this.setVelocity(this.velocity.x * speedModifier, this.velocity.y * speedModifier);
}
```

### Stamina Drain in Bad Weather:

```javascript
// In StaminaSystem.js

update(delta) {
    let drainRate = 1.0;
    
    if (this.scene.weather.currentWeather === 'blizzard') {
        drainRate *= 2.0;  // Exhaust faster in cold
    }
    
    if (this.scene.weather.currentWeather === 'storm') {
        drainRate *= 1.5;  // Fighting wind is tiring
    }
    
    this.stamina -= drainRate * delta * 0.01;
}
```

### Health Effects:

```javascript
// Hypothermia in tundra
if (biome === 'tundra' && !nearFire) {
    this.temperature -= delta * 0.02;
    
    if (this.temperature < 20) {
        this.health -= delta * 0.05;  // Freezing to death!
        
        // UI warning
        this.showWarning("MRZNEM! POTREBUJEM TOPLOTO!");
    }
}

// Warmth from campfire
if (nearFire) {
    this.temperature += delta * 0.05;
}
```

---

## 🎬 CUTSCENE INTEGRATION

### Weather Changes During Story Moments:

```javascript
// Ana's memory triggers storm
this.events.on('ana_memory_trigger', () => {
    // Sky darkens
    this.cameras.main.setBackgroundColor('#222222');
    
    // Storm starts
    this.game.weatherManager.setGlobalWeather('storm', 0.9);
    
    // Thunder sound
    this.sound.play('thunder');
    
    // Camera shake
    this.cameras.main.shake(1000, 0.01);
    
    // Kai dialogue
    kai.say("...Ana... kje SI?!");
    
    // After memory, weather clears
    this.time.delayedCall(10000, () => {
        this.game.weatherManager.setGlobalWeather('clear', 0);
    });
});
```

---

## 📊 PERFORMANCE MONITORING

### FPS Tracker:

```javascript
// In main scene
this.fpsMeter = this.add.text(10, 10, '', { font: '16px Arial' });

this.events.on('update', () => {
    const fps = this.game.loop.actualFps.toFixed(1);
    this.fpsMeter.setText(`FPS: ${fps}`);
    
    // Auto-reduce quality if FPS drops
    if (fps < 30) {
        this.weather.rainEmitter.setQuantity(1);  // Half particles
        this.weather.snowEmitter.setQuantity(1);
    }
});
```

---

## 🌟 PLAYER REACTIONS (Expected)

### First Basement Exit:
**Player:** "Oh! Dreads se premikajo! To je sick!"

### First Rain:
**Player:** "Wow... drops actually fall... in puddles form!"

### Tundra Blizzard:
**Player:** "Fuck... I can barely see... this is hardcore!"

### Volcanic Zone:
**Player:** "Everything is on fire... this is insane!"

### Water Cenote:
**Player:** "The ripples... the hair floating... SO GOOD!"

**= VIRAL POTENTIAL! Players will SHARE this!** 📸

---

## 🎯 IMPLEMENTATION TIMELINE

### **Phase 1 (This Week):**
- [x] MasterWeatherSystem.js created
- [ ] GlobalWeatherManager.js
- [ ] Integrate into BasementScene (game start)
- [ ] Integrate into GrasslandScene (tutorial)
- [ ] Test wind on hair + grass

### **Phase 2 (Next Week):**
- [ ] Integrate into all 20 biomes
- [ ] Add biome-specific weather presets
- [ ] Rain + puddles system
- [ ] Snow + accumulation
- [ ] Fire sources

### **Phase 3 (Month 1):**
- [ ] Water displacement shader
- [ ] Caustics system
- [ ] Heat distortion
- [ ] Lightning
- [ ] Gameplay effects (movement, stamina, health)

### **Phase 4 (Month 2):**
- [ ] Cutscene weather integration
- [ ] Dynamic weather changes
- [ ] Performance optimization
- [ ] Mobile support

---

## 📝 CHECKLIST

**Before Kickstarter Demo:**
- [ ] Wind works in basement (first frame!)
- [ ] Grass moves in grassland
- [ ] Leaves fall from trees
- [ ] Rain creates puddles
- [ ] Snow accumulates in tundra
- [ ] Fire flickers in volcanic
- [ ] Water ripples when walking
- [ ] Hair floats underwater
- [ ] 60 FPS maintained
- [ ] Works on all platforms

---

## 🔥 FINAL NOTES

**MasterWeatherSystem is NOT optional.**

**It's THE SOUL of DolinaSmrti.**

From the moment Kai opens her eyes in that basement...  
To the moment she stands in a blizzard looking for Ana...  
To the moment she lights a campfire to survive the cold...

**THE WEATHER IS THERE.**

**THE WORLD FEELS ALIVE.**

**THE GAME HAS A SOUL.**

---

*DolinaSmrti - Where every raindrop matters.* 🌧️💀