World Expansion Plan - Towns Scout Raiders - Characters Updated - NPCs Detailed - New Systems Added

docs/game_design/GAME_BIBLE.md

@@ -99,14 +99,20 @@
 **Age:** 17  
 **Role:** Protagonist, Alpha Hybrid, Farmer  
 **Appearance:**
-- Dark forest green thick natural dreadlocks
-- Stretched ear gauges with piercings
-- Facial piercings (nose, lip)
-- Weathered blue jacket over beige shirt
-- Ripped blue jeans with torn knees
-- Dark brown combat boots
+- **Pink and green dreadlocks** (signature look)
+- **Stretched ear gauges** with multiple piercings
+- Facial piercings (nose, lip, eyebrow)
+- **Katana** strapped to back (main weapon)
+- Post-apocalyptic clothing (torn jacket, ripped jeans)
+- Dark combat boots
 - Brown survival backpack
-- Athletic build
+- Athletic, wiry build
+
+**Visual Reference:** `/references/kai/`
+- Style 32 Dark-Chibi Noir
+- Red eyes with dark pupils (human, NOT zombie)
+- Determined expression
+- Survivor aesthetic
 
 **Personality:**
 - Determined, protective of Ana
@@ -134,11 +140,19 @@
 **Age:** 17 (Kai's twin)  
 **Role:** Quest target, cure key  
 **Appearance:**
-- PINK dreadlocks (contrast to Kai's green)
+- **Light blonde hair** (short, practical cut)
+- **Blue eyes WITH pupils** (friendly NPC style)
+- Style 32 Dark-Chibi Noir aesthetic
+- Determined, survival-ready look
 - Adventure vest with pockets
-- Map and research backpack
+- Research backpack with supplies
 - Energetic, bright personality
 
+**Visual Reference:** `/references/ana/`
+- Style 32 Dark-Chibi Noir
+- Strong, capable expression
+- Scientist/survivor hybrid look
+
 **Status:** Missing (alive, held by Viktor Krnić)
 
 **Importance:**
@@ -155,15 +169,22 @@
 ---
 
 ### **3. Gronk** (Companion)
-**Role:** Tamed Troll, Comic Relief, Heavy Muscle  
+**Role:** Kaijev prijatelj, Tamed Troll, Comic Relief  
 **Appearance:**
 - MASSIVE green troll (3m tall)
-- Thick BRIGHT PINK dreadlocks (matches Ana's!)
-- Pink ear gauges + nose ring piercings
+- **Pink dreadlocks** (signature style)
+- **Stretched ear gauges** with piercings
+- Nose ring and facial piercings
+- **Vape** always in hand (essential accessory)
 - Black t-shirt: "TROLL SABBATH" (purple text)
 - Torn baggy black skater pants
 - Pink sneakers
-- Colorful vape (pink smoke)
+- Colorful vape clouds (pink smoke)
+
+**Visual Reference:** `/references/gronk/`
+- Style 32 Dark-Chibi Noir
+- Friendly giant aesthetic
+- Stoner/skater culture vibe
 
 **Personality:**
 - Gentle giant despite size
@@ -210,38 +231,144 @@
 
 ## 🏘️ NPCs & FACTIONS (180+ Characters)
 
-### **Key NPCs (Demo - 4):**
+### **Town NPCs (Core Services):**
 
-**1. Trader NPC**
-- Merchant with goods
-- First NPC you meet
-- Buys wheat, sells seeds/tools
-- Clearly visible eyes, friendly smile
+**1. Ivan Kovač** (Blacksmith) ⚒️
+- **Appearance:** Močan lik (strong build), protective goggles, blacksmith apron
+- **Role:** Tool repair & enchanting services
+- **Services:**
+  - Repairs all 63 tool types (10g per durability point)
+  - Enchanting Table access (Magic Enchanting System)
+  - Sells repair kits and upgrade materials
+- **Location:** Blacksmith building in every restored town
+- **Personality:** Serious craftsman, respects quality work
+- **Visual Reference:** `/references/npcs/ivan_kovac/`
+  - Style 32 Dark-Chibi Noir
+  - Red eyes with dark pupils (friendly NPC)
+  - Muscular, soot-covered from forge work
 
-**2. Blacksmith NPC**
-- Muscular man with apron
-- Hammer and anvil
-- Upgrades tools and weapons
-- Serious but fair expression
+**2. Mayor/Župan** (Town Administrator) 🏛️
+- **Appearance:** Serious lik, long green coat, official sash, old tablet computer
+- **Role:** Town restoration permits & quests
+- **Services:**
+  - Issues permits to restore 27 towns
+  - Tracks restoration progress
+  - Rewards City Gratitude Gifts
+  - Assigns town defense quests
+- **Location:** Town Hall (once restored)
+- **Personality:** Bureaucratic but fair, wants to rebuild civilization
+- **Visual Reference:** `/references/npcs/mayor/`
+  - Style 32 Dark-Chibi Noir
+  - Red eyes with dark pupils (friendly NPC)
+  - Official, authoritative look
 
-**3. Healer/Doctor NPC**
-- Medical bag and robes
-- Sells potions and remedies
-- Kind, concerned facial expression
-- May have Ana clues
+**3. Miro Pravnik** (Lawyer/Odvetnik) ⚖️
+- **Appearance:** Starejši moški (older man), wrinkled brown office suit, rusty briefcase
+- **Role:** Legal services & divorce proceedings
+- **Services:**
+  - Handles legal matters in Mrtva Dolina
+  - Divorce paperwork (NPC relationship system)
+  - Property rights & land ownership
+  - Witness for important contracts
+- **Location:** Law Office in major towns
+- **Personality:** Tired, seen too much, darkly humorous
+- **Visual Reference:** `/references/npcs/miro_pravnik/`
+  - Style 32 Dark-Chibi Noir
+  - Red eyes with dark pupils (friendly NPC)
+  - Worn, weathered professional
 
-**4. Mysterious Traveler NPC**
-- Cloaked figure
-- Gives first Ana clue
-- Mysterious, knowing expression
-- Appears at key story moments
+**4. Arborist/Gozdar** (Tree Planter) 🌲
+- **Appearance:** Work clothes, gardening gloves, seed bags
+- **Role:** Automated tree planting service
+- **Services:**
+  - Automatically plants trees on your farm
+  - Sells rare tree saplings
+  - Forest management advice
+  - Biome-specific tree species
+- **Location:** Farm School building
+- **Personality:** Nature-loving, calm, patient
+- **Visual Reference:** `/references/npcs/arborist/`
+  - Style 32 Dark-Chibi Noir
+  - Red eyes with dark pupils (friendly NPC)
+  - Green-themed clothing, dirt-stained
+
+---
+
+### **Companions & Special NPCs:**
+
+**5. Zombi Skavt** (Zombie Scout) 🧟‍♂️
+- **Appearance:** Friendly zombie with red/blue bandana, small backpack
+- **Role:** Explorer companion, pathfinder
+- **Special:** Levels 1-20, evolves visually at 5/10/15/20
+- **Features:**
+  - Finds shortcuts through biomes
+  - Discovers rare items (Treasure Hunter skill)
+  - Warns of dangers (Danger Sense)
+  - Marks resources on map
+- **Visual Reference:** `/references/companions/zombie_scout/`
+  - Style 32 Dark-Chibi Noir
+  - **Red eyes WITH dark pupils** (friendly variant)
+  - Bandana identifier (blue or red)
+  - Chibi proportions, friendly pose
+
+---
+
+### **Enemies & Raiders:**
+
+**6. Nomadski Roparji** (Nomad Raiders) ⛺
+- **Types:** Desert Nomads, Frost Bandits, Jungle Marauders, Tech Scavengers
+- **Appearance:** Improvised scrap armor, post-apocalyptic gear
+- **Role:** Dynamic threat, farm raiders
+- **Behavior:**
+  - Travel between biomes (no permanent home)
+  - Raid farms when you have 1000+ crops
+  - Ambush caravans (30% chance)
+  - Establish temporary camps (2-3 days)
+- **Visual Reference:** `/references/enemies/nomad_raiders/`
+  - Style 32 Dark-Chibi Noir
+  - Each raider type has biome-specific gear
+  - Hostile appearance, weapons drawn
+
+**7. Troli** (Trolls) 🏰
+- **Types:** Friendly (like Gronk), Wild, Troll King (boss)
+- **Appearance:** Robustni prebivalci (robust builds), various colors
+- **Role:** Town inhabitants (after restoration)
+- **Features:**
+  - Move into restored towns
+  - Provide unique services
+  - Stronger than humans, good defenders
+  - Some tameable as companions
+- **Visual Reference:** `/references/species/trolls/`
+  - Style 32 Dark-Chibi Noir
+  - Massive builds (2-3m tall)
+  - Various skin tones (green, gray, blue)
+
+---
+
+### **NPC Visual Style Rules:**
+
+**ALL friendly NPCs follow these rules:**
+- ✅ **Red eyes WITH dark pupils** (friendly identifier)
+- ✅ Style 32 Dark-Chibi Noir aesthetic
+- ✅ Thick black outlines (4-5px)
+- ✅ Chibi proportions
+- ✅ Clear, expressive faces
+- ✅ Unique identifying features (clothing, accessories)
+
+**Zombies:**
+- ⚪ Weak/Tamed: **White eyes, NO pupils**
+- 🔴 Strong/Wild: **Red eyes, NO pupils**
+- 🧡 Scout: **Red eyes WITH pupils** (special friendly variant)
+
+---
 
 ### **NPC Factions:**
 - **Scavengers:** Neutral survivors
-- **Raiders:** Hostile bandits
+- **Raiders:** Hostile bandits (Nomads)
 - **Cultists:** Zombie worshippers
 - **Field Medics:** Helpers
 - **Scientists:** Pre-outbreak survivors
+- **Town Citizens:** Restored town inhabitants
 
 ### **Total NPCs:** 180 across 27 towns
 - Each with unique dialogue
@@ -557,7 +684,159 @@
 
 ---
 
-### **9. SURVIVAL MECHANICS**
+### **9. TOWN RESTORATION SYSTEM** ✨ NEW
+
+**Concept:** All 27 towns start as RUINED. Restore them to unlock NPCs, services, and unique rewards.
+
+**Restoration Phases:**
+1. **Ruined** (Starting State)
+   - Destroyed buildings
+   - No NPCs
+   - Zombie patrols
+   - No services available
+
+2. **Partially Restored** (Mid-game)
+   - Some buildings repaired
+   - Basic trading post
+   - 1-2 NPCs return
+   - Temporary defenses
+
+3. **Fully Restored** (End-game)
+   - All buildings restored
+   - Full population (8-12 NPCs)
+   - All services active
+   - Strong defenses
+   - Unique legendary rewards
+
+**Restoration Requirements:**
+Each town requires specific resources + quest completion:
+- **Materials**: Wood, Stone, Iron, Steel, Gold
+- **Quest**: Clear zombies, defeat boss, find artifact
+- **Reward**: City Gratitude Gift (blueprints, tools, NPCs)
+
+**Gift System:**
+- **Common**: Basic resources, seeds
+- **Rare**: Special blueprints, automation tools
+- **Legendary**: Unique NPCs (Master Blacksmith), Ultimate tools
+
+**Biome-Specific Architecture:**
+Each biome has unique building styles:
+- **Forest**: Wooden cabins, treehouses
+- **Desert**: Sandstone domes, wind towers
+- **Frozen**: Ice igloos, metal structures
+- **Volcanic**: Obsidian buildings, lava moats
+- **Neon Ruins**: Steel/glass skyscrapers, holograms
+- *(20 unique biome styles total)*
+
+---
+
+### **10. ZOMBIE SCOUT COMPANION** ✨ NEW
+
+**Concept:** A friendly zombie you "tame" early-game who becomes your loyal explorer and guide.
+
+**Visual Design:**
+- Blue or red bandana around neck (friendly identifier)
+- Red eyes WITH dark pupils (friendly NPC variant)
+- Backpack for carrying items
+- Style 32 Dark-Chibi Noir
+
+**Leveling System:**
+- **Max Level**: 20
+- **Experience**: Gained from exploring, finding items
+- **Stats**: Speed, Vision, Carry Capacity, Intelligence
+
+**Skills (4 Trees):**
+
+1. **Shortcuts** (Pathfinding)
+   - Finds hidden paths through biomes
+   - Unlocks at levels: 3, 7, 12, 18
+
+2. **Treasure Hunter** (Item Finding)
+   - +5% rare item drop chance per level
+   - Marks hidden chests on map
+
+3. **Danger Sense** (Warning System)
+   - Warns about nearby enemies
+   - Range: 100px + 50px per level
+
+4. **Resource Scout** (Map Marking)
+   - Marks ore deposits, rare plants, chests
+   - Auto-highlights on minimap
+
+**Evolution Phases:**
+- **Level 5**: Gains lantern (lights dark areas)
+- **Level 10**: Gains armor (can fight weak zombies)
+- **Level 15**: Gains wings (can scout from above)
+- **Level 20**: LEGENDARY form (glowing purple aura)
+
+**Commands:**
+- **Follow**: Scout follows player automatically
+- **Explore**: Send scout to investigate area
+- **Fetch**: Retrieve items from distance
+- **Guard**: Protect farm while away
+
+---
+
+### **11. NOMAD RAIDERS** ✨ NEW
+
+**Concept:** Wandering bandits with NO permanent home. Dynamic threat that raids farms and ambushes caravans.
+
+**Raider Types:**
+
+1. **Desert Nomads** (Medium Threat)
+   - Tan robes, scimitars, camels
+   - Biome: Desert Storm
+   - Loot: Spices, gold, rare seeds
+
+2. **Frost Bandits** (High Threat)
+   - Fur armor, ice weapons
+   - Biome: Frozen Wasteland
+   - Loot: Furs, ice crystals
+
+3. **Jungle Marauders** (Very High)
+   - Tribal masks, poison darts
+   - Biome: Ancient Rainforest
+   - Loot: Rare plants, artifacts
+
+4. **Tech Scavengers** (Extreme)
+   - Cyberpunk gear, laser weapons
+   - Biome: Neon Ruins
+   - Loot: Tech parts, batteries
+
+**Raider Behavior:**
+- **Spawn**: Every 4-7 in-game days
+- **Warning**: Scout can detect 1 day in advance
+- **Camps**: Temporary (2-3 days), random locations
+- **Targets**: Player farm, caravans, restored towns
+
+**Raid Types:**
+
+1. **Farm Raid**
+   - Trigger: You have 1000+ crops stored
+   - Waves: 3 attack waves
+   - Damage: Steal 20% of stored crops
+   - Defense: Build walls, hire guards, set traps
+
+2. **Caravan Ambush**
+   - Trigger: Traveling with valuables
+   - Chance: 30% per trip
+   - Combat: Required
+   - Reward: If you win, take their supplies
+
+**Difficulty Scaling:**
+- **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:**
+- Build farm perimeter walls
+- Hire NPC guards for defense
+- Train zombies to protect farm
+- Scout provides advance warning
+
+---
+
+### **12. SURVIVAL MECHANICS**
 
 **Needs:**
 - **Health** - Combat damage