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

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

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

// 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)

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

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:

// 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) 🌊

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 🌋

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:

// 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:

// 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:

// 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:

// 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:

// 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):

• 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. 🌧️💀