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:

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)

this.weather.setBiomeWeather('grassland');
// - Medium wind (1.0)
// - Can have: clear, rain, storm
// - Default: Clear with gentle breeze

Desert

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

Tundra/Snow Zone ❄️

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 💧

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

Mountains 🏔️

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

Forest 🌲

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

Volcanic Zone 🌋

this.weather.setBiomeWeather('volcanic');
// - Turbulent wind (1.2)
// - Constant fire effects
// - Ash rain possible
// - Smoke and heat everywhere

---

⚙️ MANUAL WEATHER CONTROL

Set Specific Weather:

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

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

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

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

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:

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

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

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

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

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

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

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

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)

scene: 'GrasslandScene',
weather: {
    biome: 'grassland',
    default: 'clear',
    wind: 1.0,
    fireCount: 1,  // Campfire
    waterRipples: true
}

2. FOREST

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

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

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

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

scene: 'MountainScene',
weather: {
    biome: 'mountains',
    default: 'storm',
    intensity: 0.8,
    wind: 2.0,  // STRONGEST wind!
    dynamic: true,  // Rapid changes
    lightning: true  // TODO
}

7. VOLCANIC

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:

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

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

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