novafarma/docs/WORLD_EXPANSION_PLAN.md

# 🌍 MRTVA DOLINA - World Expansion Master Plan
**Version:** 2.0 Alpha  
**Date:** January 5th, 2026  
**Status:** 🚀 READY FOR IMPLEMENTATION

---

## 🎯 **CORE CONCEPT:**

**"From Ruins to Restoration"** - Igralec začne v svetu popolnih ruševin. Vsako mesto je uničeno, zombi prevladujejo, narava je divja. Tvoj cilj: **Obnoviti 27 mest** in postati **Odrešenik Doline**.

---

## 🏚️ **1. SISTEM OBNOV MEST (27 Town Restoration)**

### **Koncept:**
- **Vseh 27 mest se začne kot RUŠEVINE**
- Vsako mesto ima **2 vizualna stanja**: Ruined → Restored
- Vsako mesto zahteva **unikatne surovine** in **quest chain** za obnovo
- Ko obnoviš mesto, se **naselijo prebivalci** (ljudje ali troli)

### **Restoration Faze:**

#### **FAZA 1: Ruševine (Starting State)**
```
- Porušene zgradbe
- Zombi patrole
- Divja narava (trnje, ovire)
- NI trgovcev, NI storitev
```

#### **FAZA 2: Delna Obnova (Mid-game)**
```
- Delno očiščeno
- Začasno obzidje
- Prvi prebivalci se vrnejo
- Osnovna trgovina aktivna
```

#### **FAZA 3: Popolna Obnova (End-game)**
```
- Popolnoma obnovljeno
- Močno obzidje
- Populacija 100%
- Vsi NPC-ji aktivni
- Unikatne nagrade odklenete
```

### **Restoration Requirements Example:**

**Mesto: FROST HAVEN (Frozen Wasteland)**
```javascript
{
  name: "Frost Haven",
  biome: "Frozen Wasteland",
  state: "ruined", // ruined → partial → restored
  
  restoration: {
    phase1: {
      materials: { wood: 500, stone: 1000, iron: 200 },
      quest: "Clear 50 zombies from town",
      reward: "Basic Trading Post unlocked"
    },
    phase2: {
      materials: { steel: 300, gold: 100, magic_crystal: 50 },
      quest: "Build town walls",
      reward: "Frost Haven Citizens return (5 NPCs)"
    },
    phase3: {
      materials: { diamond: 50, legendary_ore: 10, ancient_scroll: 5 },
      quest: "Defeat Ice Tyrant Boss",
      reward: "Legendary Ice Forge + Frost Queen NPC"
    }
  },
  
  citizens: {
    max: 12,
    current: 0,
    types: ["merchant", "blacksmith", "mage", "farmer", "guard"]
  }
}
```

### **Gift System:**
Ko obnoviš mesto, prejmeš **City Gratitude Gift**:
- Rare blueprints
- Unique tools
- Legendary seeds
- Special NPCs (master craftsmen)
- Automation helpers (roboti, priročne ročke)

---

## 🧟 **2. ZOMBI SKAVT (Loyal Companion)**

### **Koncept:**
**Prijazni zombi**, ki si ga "udomačiš" na začetku igre. Namesto da te napade, postane tvoj **raziskovalec in vodič**.

### **Visual Design:**
- Style 32 Dark-Chibi Noir
- **IDENTIFIKACIJA**: Modra ali rdeča rutica okoli vratu
- Red eyes WITH pupils (friendly variant)
- Backpack for carrying items
- Animations: Idle, Walking, Pointing, Digging

### **Leveling System:**

```javascript
{
  name: "Scout",
  type: "zombie_companion",
  level: 1, // max 20
  
  stats: {
    speed: 100,           // Movement speed
    vision: 150,          // Detection radius
    carryCapacity: 10,    // Item slots
    intelligence: 50      // Pathfinding quality
  },
  
  skills: {
    shortcuts: {
      level: 1,
      description: "Finds shortcuts through biomes",
      unlockAt: [3, 7, 12, 18] // Better paths at these levels
    },
    
    treasureHunter: {
      level: 1,
      description: "Finds rare items in biomes",
      rareChance: 5, // +5% per level
    },
    
    dangerSense: {
      level: 1,
      description: "Warns about nearby threats",
      range: 100 // +50 pixels per level
    },
    
    resourceScout: {
      level: 1,
      description: "Marks resource nodes on map",
      types: ["ore", "plants", "chests"]
    }
  },
  
  evolution: {
    // Every 5 levels, scout gets visual upgrade
    5: "Scout gains lantern (lights dark areas)",
    10: "Scout gains armor (can fight weak zombies)",
    15: "Scout gains wings (can scout flying)",
    20: "Scout becomes LEGENDARY (glowing aura)"
  }
}
```

### **Gameplay Integration:**
- **Command System**: Right-click to send scout exploring
- **Auto-follow**: Scout follows you and marks dangers
- **Item Retrieval**: Can send scout to fetch items
- **Map Markers**: Scout marks discoveries on map

---

## ⛺ **3. NOMADSKI ROPARJI (Nomad Raiders)**

### **Koncept:**
**Dinamična nevarnost** - roparji, ki **nimajo stalnega doma** in potujejo med biomi. Poskušajo **oropati tvojo kmetijo** ali te napadejo na poti med mesti.

### **Raider Types:**

#### **A) Desert Nomads**
```
Biome: Desert Storm
Appearance: Tan robes, scimitars, camels
Threat: Medium
Loot: Spices, gold, desert seeds
```

#### **B) Frost Bandits**
```
Biome: Frozen Wasteland
Appearance: Fur armor, ice weapons
Threat: High
Loot: Furs, ice crystals, frozen meat
```

#### **C) Jungle Marauders**
```
Biome: Ancient Rainforest
Appearance: Tribal masks, poison darts
Threat: Very High
Loot: Rare plants, ancient artifacts
```

#### **D) Tech Scavengers**
```
Biome: Neon Ruins
Appearance: Cyberpunk gear, laser weapons
Threat: Extreme
Loot: Tech parts, batteries, robots
```

### **Raider Behavior System:**

```javascript
{
  type: "nomad_raiders",
  
  spawn: {
    method: "dynamic", // Not tied to location
    frequency: "4-7 days in-game",
    warning: "Scout can detect 1 day in advance"
  },
  
  camps: {
    temporary: true,
    duration: "2-3 days",
    location: "random biome edge",
    structures: ["tents", "campfire", "loot_chests"]
  },
  
  raids: {
    targets: ["farm", "caravan", "restored_towns"],
    
    farmRaid: {
      trigger: "If you have 1000+ crops stored",
      waves: 3,
      loot_stolen: "20% of stored crops",
      defense: "Build walls, hire guards, set traps"
    },
    
    caravanAmbush: {
      trigger: "Traveling between towns with valuables",
      chance: 30, // 30% per trip
      combat: true,
      loot_dropped: "If you win, take their supplies"
    }
  },
  
  difficulty_scaling: {
    // Raiders get stronger as you progress
    early_game: "2-3 raiders, basic weapons",
    mid_game: "5-8 raiders, steel weapons, traps",
    late_game: "10-15 raiders, magic weapons, siege equipment"
  }
}
```

### **Defense Systems:**
- **Farm Walls**: Build perimeter defenses
- **Guard Towers**: Hire NPC guards
- **Zombie Allies**: Tamed zombies defend your farm
- **Scout Warning**: Get advance notice of raids

---

## 🏗️ **4. BIOMSKA ARHITEKTURA (27 Unique Town Styles)**

### **Koncept:**
Vsak **biom ima unikaten stil** arhitekture. Mesta v gozdu so lesena, mesta v futurističnih biomih imajo stolpnice, puščavska mesta so iz peska.

### **Biome Architecture Styles:**

| Biome | Building Material | Roof Style | Color Palette | Special Feature |
|-------|------------------|------------|---------------|-----------------|
| **Temperate Forest** | Wood, stone | Thatched | Brown, green | Treehouses |
| **Frozen Wasteland** | Ice, metal | Flat | White, blue | Igloos |
| **Desert Storm** | Sandstone | Domed | Tan, gold | Wind towers |
| **Ancient Rainforest** | Bamboo, vines | Leaf | Green, brown | Canopy bridges |
| **Volcanic Ashlands** | Obsidian, lava rock | Pointed | Black, red | Lava moats |
| **Toxic Swamp** | Rotted wood | Mossy | Green, purple | Stilts |
| **Crystal Caves** | Crystal shards | Jagged | Purple, cyan | Glowing walls |
| **Neon Ruins** | Steel, glass | Flat | Neon colors | Holograms |
| **Haunted Hollow** | Bone, dark stone | Sharp | Gray, purple | Floating stones |
| **Floating Islands** | Cloud marble | Curved | White, gold | Anti-gravity |

*(20 total biomes, each with unique style)*

### **Building Types per Town:**

```javascript
{
  town_buildings: [
    // CORE (Every town has these)
    "town_hall",          // Main building
    "trading_post",       // Merchant
    "inn",                // Rest/save point
    "blacksmith",         // Crafting
    "general_store",      // Basic items
    
    // BIOME-SPECIFIC (Unique to each biome)
    "unique_service_1",   // e.g., "Ice Forge" in Frozen biome
    "unique_service_2",   // e.g., "Sand Glassworks" in Desert
    "special_landmark",   // Visual centerpiece
    
    // RESTORATION ADDITIONS
    "guard_tower",        // Defense
    "farm_school",        // Teaches new crop types
    "magic_laboratory",   // Enchanting services
    "airship_dock"        // Fast travel (late game)
  ]
}
```

---

## 🎨 **5. ASSET GENERATION PLAN**

### **Total Assets Needed:**

#### **A) TOWN BUILDINGS:**
```
27 towns × 12 building types × 2 states (ruined/restored) = 648 buildings
PLUS variations (damaged, partial) = ~900 building sprites
```

#### **B) ZOMBI SKAVT:**
```
1 base sprite × 4 directions × 3 animations = 12 sprites
+ 4 evolution forms × 12 = 48 total
```

#### **C) NOMAD RAIDERS:**
```
4 raider types × 6 unit variants × 4 directions = 96 sprites
+ 4 camp structures × 2 states = 8 camp sprites
Total: ~110 raider sprites
```

#### **D) GIFT UI:**
```
1 Gift Window UI
6 Gift Box variations (common → legendary)
20 Gift Icon overlays
Total: 27 UI elements
```

### **PHASE 1 Priority (Kickstarter Demo):**

**Generate NOW:**
1. ✅ **3 Sample Towns** (Forest, Desert, Frozen) - Ruined + Restored
   - 3 × 8 core buildings × 2 states = 48 sprites
   
2. ✅ **Zombi Skavt** - Base version
   - 1 × 4 directions × 2 animations = 8 sprites
   
3. ✅ **1 Raider Type** - Desert Nomads
   - 1 × 4 variants × 4 directions = 16 sprites
   - 1 camp set = 4 sprites
   
4. ✅ **Gift System UI** - Basic version
   - 1 window + 3 gift boxes = 4 UI elements

**Total Phase 1:** ~80 sprites

---

## 📊 **6. GAME SYSTEMS INTEGRATION**

### **New Systems to Code:**

#### **A) Town Restoration System**
```javascript
// src/systems/TownRestorationSystem.js

class TownRestorationSystem {
  constructor() {
    this.towns = this.loadTowns(); // 27 towns
    this.currentPhase = {}; // Track each town's phase
  }
  
  restoreTown(townId, materials) {
    // Check if player has required materials
    // Update town visual state
    // Spawn new NPCs
    // Award gifts
    // Update map
  }
  
  calculateProgress(townId) {
    // Return 0-100% restoration progress
  }
  
  getTownGift(townId, phase) {
    // Return unique reward for this town/phase
  }
}
```

#### **B) Zombie Scout System**
```javascript
// src/systems/ZombieScoutSystem.js

class ZombieScoutSystem {
  constructor() {
    this.scout = {
      level: 1,
      experience: 0,
      skills: {},
      position: { x: 0, y: 0 }
    };
  }
  
  commandScout(target) {
    // Send scout to explore area
    // Pathfinding with shortcut detection
  }
  
  levelUp() {
    // Increase stats
    // Unlock new abilities
    // Visual evolution
  }
  
  detectDanger() {
    // Scan area for threats
    // Warn player
  }
}
```

#### **C) Nomad Raider System**
```javascript
// src/systems/NomadRaiderSystem.js

class NomadRaiderSystem {
  constructor() {
    this.activeRaiders = [];
    this.camps = [];
    this.nextRaidTime = this.calculateNextRaid();
  }
  
  spawnRaiders(biome) {
    // Create raider group
    // Set patrol path
    // Establish temporary camp
  }
  
  checkRaidConditions() {
    // Farm wealth threshold
    // Player location (caravan)
    // Time since last raid
  }
  
  executeRaid(target) {
    // Launch attack
    // Combat logic
    // Loot calculation
  }
}
```

---

## 🗺️ **7. WORLD MAP UPDATES**

### **Map Markers:**

```javascript
{
  markers: {
    // TOWNS (27)
    town_ruined: "🏚️ Gray icon, no name",
    town_partial: "🏘️ Yellow icon, name visible",
    town_restored: "🏰 Green icon, full info",
    
    // RAIDERS
    raider_camp: "⛺ Red icon, temporary",
    raider_patrol: "🔴 Moving red dot",
    
    // SCOUT DISCOVERIES
    shortcut: "➡️ Blue path",
    treasure: "💎 Yellow star",
    danger: "⚠️ Orange warning",
    resource: "📦 Green box"
  }
}
```

---

## 📝 **8. IMPLEMENTATION CHECKLIST**

### **CODE:**
- [ ] Create `TownRestorationSystem.js`
- [ ] Create `ZombieScoutSystem.js`
- [ ] Create `NomadRaiderSystem.js`
- [ ] Create `GiftRewardSystem.js`
- [ ] Update `GameScene.js` - integrate new systems
- [ ] Update `MapScene.js` - new markers
- [ ] Create `TownUI.js` - restoration interface
- [ ] Create `ScoutUI.js` - command interface

### **ASSETS:**
- [ ] Generate 48 town building sprites (3 towns × 8 buildings × 2 states)
- [ ] Generate 8 Zombi Skavt sprites (base form)
- [ ] Generate 20 Raider sprites (1 type)
- [ ] Generate 4 camp structure sprites
- [ ] Generate 4 Gift UI elements
- [ ] Organize into folders:
  ```
  assets/slike 🟢/
    ├── towns/
    │   ├── forest/
    │   ├── desert/
    │   └── frozen/
    ├── companions/
    │   └── zombie_scout/
    ├── raiders/
    │   └── desert_nomads/
    └── ui/
        └── gifts/
  ```

### **DATA:**
- [ ] Create `town_registry.json` - All 27 towns
- [ ] Create `raider_types.json` - All raider variants
- [ ] Create `gift_catalog.json` - All possible rewards
- [ ] Create `scout_skills.json` - Skill tree data

### **DOCUMENTATION:**
- [ ] Update Game Bible with new systems
- [ ] Create Town Restoration Guide
- [ ] Create Scout Training Manual
- [ ] Create Raider Defense Tactics Guide

---

## 🎯 **SUCCESS CRITERIA:**

**Kickstarter Demo Ready When:**
1. ✅ 3 towns show clear Ruined → Restored transformation
2. ✅ Zombi Skavt is playable and useful
3. ✅ 1 raider encounter is scripted and functional
4. ✅ Gift system awards players for restoration
5. ✅ All new assets visible in asset browser
6. ✅ Deep code scan shows 0 errors

---

## 🚀 **TIMELINE:**

**Phase 1 (Today):** Generate assets + code foundations (6 hours)  
**Phase 2 (Tomorrow):** Integration + testing (4 hours)  
**Phase 3 (Day 3):** Polish + demo recording (2 hours)

**TOTAL:** 12 hours to Kickstarter-ready expansion

---

**Status:** 🟢 **READY TO START GENERATION**

**Next Command:** Generate Phase 1 assets (80 sprites)