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

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

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

2. Use in ANY scene:

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:

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

const hair = this.add.sprite(x, y, 'kai_dreads');
this.weather.windSystem.applyWindToSprite(hair, 'hair');
// Hair now sways with wind!

Apply Wind to Grass:

const grass = this.add.sprite(x, y, 'grass_tuft');
this.weather.windSystem.applyWindToSprite(grass, 'grass');
// Grass now bends with wind!

Tree Drops Leaves:

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

Create Fire (campfire, torch):

this.weather.createFireSource(x, y, 1.5);
// Flames + smoke!

Create Water Ripple:

this.weather.createRipple(player.x, player.y, 0.5);
// Concentric circles spread!

Change Weather Manually:

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

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

// ❌ Wrong - no weather!
class MyScene extends Phaser.Scene {
    create() {
        // Scene has no weather...
    }
}

DO:

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

---

🔧 DEBUGGING

Check weather status:

// In browser console:
game.weatherManager.debug();

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

Force weather change:

game.weatherManager.setGlobalWeather('blizzard', 1.0);
// All scenes now have blizzard!

Show wind debug:

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:

// 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. 🌦️💀