ok

docs/BIOME_UNLOCKABLES_NPC_VILLAGES.md

@@ -0,0 +1,511 @@
+# 🗺️🏘️ **BIOME UNLOCKABLES + NPC VILLAGES - Complete System**
+
+## 🔓 **BIOME-SPECIFIC UNLOCK SYSTEM:**
+
+### **THE RULE:**
+```
+✅ Each biome has UNIQUE content!
+✅ Plants, Seeds, Weapons, Armor, Food, Buildings!
+✅ ONLY available in that biome!
+✅ Must explore to unlock! ✅
+```
+
+---
+
+## 🌍 **20 BIOMES - UNIQUE UNLOCKABLES:**
+
+### **1. DINO VALLEY** 🦖
+
+**UNIQUE PLANTS/SEEDS:**
+```
+- Prehistoric Ferns (decorative!)
+- Giant Mushrooms (food source!)
+- Cycad Palms (wood alternative!)
+- Dino Eggs (hatch → baby dino!)
+```
+
+**UNIQUE WEAPONS:**
+```
+- Bone Axe (primitive, high damage!)
+- Stone Spear (throwable!)
+- Dino Tooth Knife (bleeding effect!)
+- Obsidian Blade (sharp!)
+```
+
+**UNIQUE ARMOR:**
+```
+- Dino Hide Armor (high defense!)
+- Bone Helmet (headbutt attack!)
+- Scale Boots (+speed in grass!)
+- Tooth Necklace (+intimidation!)
+```
+
+**UNIQUE FOOD:**
+```
+- T-Rex Steak (+100 HP! best meat!)
+- Dino Eggs (+50 HP, protein!)
+- Dino Jerky (preserves forever!)
+- Bone Broth (+30 HP + stamina!)
+```
+
+**UNIQUE BUILDINGS:**
+```
+- Primitive Hut (starter shelter!)
+- Bone Fence (decoration + defense!)
+- Stone Altar (ritual site!)
+- Tar Pit Trap (catches dinos!)
+```
+
+---
+
+### **2. CHERNOBYL** ☢️
+
+**UNIQUE PLANTS:**
+```
+- Mutated Grass (glowing green!)
+- Radioactive Flowers (alchemy!)
+- Toxic Mushrooms (poison craft!)
+- Dead Trees (dark aesthetic!)
+```
+
+**UNIQUE WEAPONS:**
+```
+- Lead Pipe (blunt, simple!)
+- Contaminated Axe (+radiation damage!)
+- **SHOTGUN!** (ONLY in Chernobyl!)
+- Makeshift Weapons (scrap metal!)
+```
+
+**UNIQUE ARMOR:**
+```
+- **HAZMAT SUIT** (radiation immune!)
+- Gas Mask (breathing protection!)
+- Lead Vest (radiation shield!)
+- Protective Boots (walk on toxic ground!)
+```
+
+**UNIQUE FOOD:**
+```
+- Canned Food (pre-war, rare!)
+- Military Rations (MRE, sealed!)
+- Radiation Pills (medicine!)
+- Purified Water (rare, essential!)
+```
+
+**UNIQUE BUILDINGS:**
+```
+- Reactor Building (ruin exploration!)
+- Underground Bunker (safe haven!)
+- Military Checkpoint (loot spot!)
+- Decontamination Station (cleanse items!)
+```
+
+---
+
+### **3. MYTHICAL HIGHLANDS** 🏔️✨
+
+**UNIQUE PLANTS:**
+```
+- **Cloud Flowers** (float in air!)
+- Dragon Fruit Trees (magic fruit!)
+- Mythril Ore Veins (legendary metal!)
+- Crystal Mushrooms (glowing!)
+```
+
+**UNIQUE WEAPONS:**
+```
+- **Mythril Sword** (legendary!)
+- Dragon Bone Spear (fire enchant!)
+- Unicorn Horn Lance (holy damage!)
+- Griffin Feather Bow (accuracy+!)
+```
+
+**UNIQUE ARMOR:**
+```
+- **Dragon Scale Armor** (best defense!)
+- Pegasus Wing Cape (glide ability!)
+- Unicorn Hide Boots (+healing!)
+- Mythril Crown (prestige!)
+```
+
+**UNIQUE FOOD:**
+```
+- Dragon Steak (legendary! +100 HP!)
+- Phoenix Egg Omelet (revive buff!)
+- Ambrosia (god food, max HP!)
+- Cloud Bread (fluffy, +fly buff!)
+```
+
+**UNIQUE BUILDINGS:**
+```
+- Sky Temple (worship site!)
+- Dragon's Nest (taming spot!)
+- Crystal Tower (wizard home!)
+- Cloud Platform (floating base!)
+```
+
+---
+
+### **4. ATLANTIS** 🌊
+
+**UNIQUE PLANTS:**
+```
+- **Kelp Forest** (farm underwater!)
+- Coral (decorative, valuable!)
+- Sea Anemones (defense plant!)
+- Underwater Lotus (rare flower!)
+```
+
+**UNIQUE WEAPONS:**
+```
+- Trident (Poseidon's weapon!)
+- Coral Sword (sharp edges!)
+- Harpoon Gun (underwater!)
+- Pearl Staff (magic!)
+```
+
+**UNIQUE ARMOR:**
+```
+- **Diving Suit** (underwater breathing!)
+- Shell Armor (high defense!)
+- Pearl Necklace (+30 sec breath!)
+- Diving Flippers (+swim speed!)
+```
+
+**UNIQUE FOOD:**
+```
+- Kelp Noodles (sushi!)
+- Pearl Oysters (luxury food!)
+- Deep Sea Fish (rare!)
+- Atlantean Bread (waterproof!)
+```
+
+**UNIQUE BUILDINGS:**
+```
+- Underwater Dome (air bubble!)
+- Coral House (natural shelter!)
+- Atlantean Temple (ruins!)
+- Submarine Dock (vehicle!)
+```
+
+---
+
+### **5. WITCH FOREST** 🌑🧙
+
+**UNIQUE PLANTS:**
+```
+- **Shadow Berries** (dark alchemy!)
+- Cursed Mushrooms (poison!)
+- Witch Herbs (potion ingredients!)
+- Haunted Flowers (spooky!)
+```
+
+**UNIQUE WEAPONS:**
+```
+- Witch Staff (magic attacks!)
+- Cursed Dagger (hex effect!)
+- Broom (melee + ride!)
+- Shadow Bow (invisible arrows!)
+```
+
+**UNIQUE ARMOR:**
+```
+- Witch Robe (magic resist!)
+- Pointy Hat (traditional!)
+- Shadow Cloak (stealth!)
+- Cursed Boots (+dark magic!)
+```
+
+**UNIQUE FOOD:**
+```
+- Witch's Brew (potion!)
+- Cursed Apples (risky!)
+- Shadow Soup (dark energy!)
+- Magic Tea (mana restore!)
+```
+
+**UNIQUE BUILDINGS:**
+```
+- Witch Hut (home!)
+- Cauldron Station (brewing!)
+- Dark Altar (rituals!)
+- Enchanted Garden (plants!)
+```
+
+---
+
+## 🏘️ **NPC VILLAGE BUILDING SYSTEM:**
+
+### **HOW IT WORKS:**
+
+```
+PLAYER CAN BUILD VILLAGE FOR NPCs!
+
+REQUIREMENTS:
+- Cleared farmland (24×24 min!)
+- 10,000 gold starting budget
+- Materials (wood, stone, etc.)
+- NPC invitation quests
+
+RESULT: NPCs move in, create village! ✅
+```
+
+---
+
+### **VILLAGE COMPONENTS:**
+
+**1. HOUSING (Required!):**
+```
+[Build NPC Houses]
+
+SMALL HOUSE:
+- Materials: 200 wood, 100 stone
+- Cost: 1,000g
+- Capacity: 1 NPC
+- Build time: 2 days (zombies: 1 day)
+
+MEDIUM HOUSE:
+- Materials: 400 wood, 200 stone
+- Cost: 2,500g
+- Capacity: 2-3 NPCs (family!)
+- Build time: 5 days
+
+LARGE HOUSE:
+- Materials: 800 wood, 400 stone, 100 glass
+- Cost: 5,000g
+- Capacity: 5+ NPCs (mansion!)
+- Build time: 10 days
+
+BUILD 5-10 HOUSES = VILLAGE HOUSING! ✅
+```
+
+---
+
+**2. SHOPS (Services!):**
+```
+[Build Shop Buildings]
+
+GENERAL STORE:
+- Materials: 300 wood, 150 stone, 50 glass
+- Cost: 2,000g
+- NPC: Shopkeeper (sells basics!)
+- Services: Buy/sell items
+
+BLACKSMITH:
+- Materials: 500 iron, 200 stone, 100 coal
+- Cost: 3,000g
+- NPC: Blacksmith (repairs, craft!)
+- Services: Weapon/armor repair, crafting
+
+TAILOR SHOP:
+- Materials: 200 wood, 100 cloth, 50 thread
+- Cost: 1,500g
+- NPC: Tailor (clothing!)
+- Services: Clothes, dyes, blueprints
+
+TAVERN/INN:
+- Materials: 400 wood, 200 stone, 100 glass
+- Cost: 3,500g
+- NPCs: Bartender, Cook
+- Services: Food, drink, sleep (5 rooms!)
+
+CHURCH:
+- Materials: 600 stone, 200 wood, 150 glass
+- Cost: 5,000g
+- NPC: Priest
+- Services: Heal, marriage, blessings
+```
+
+---
+
+**3. INFRASTRUCTURE:**
+
+```
+ROADS:
+- Place stone paths between buildings!
+- Materials: Stone (cheap!)
+- Makes village look organized!
+
+STREET LAMPS:
+- Light up village at night!
+- Materials: 10 iron, 5 glass each
+- Place every 10m!
+
+FOUNTAIN (Center piece!):
+```
+- Materials: 300 stone, 100 water
+- Cost: 1,000g
+- Decoration + water source!
+
+TOWN SQUARE:
+- Open area 16×16
+- Place benches, statues!
+- NPCs gather here!
+```
+
+---
+
+**4. DEFENSES:**
+
+```
+VILLAGE WALL:
+- Materials: 1,000 stone, 500 wood
+- Cost: 5,000g
+- Protects from zombie raids!
+
+GUARD TOWER:
+- Materials: 300 stone, 200 wood
+- Cost: 2,000g
+- NPC: Guard (defense!)
+- Shoots zombies automatically!
+
+GATE:
+- Materials: 200 iron, 100 wood
+- Cost: 1,500g
+- Opens for player/NPCs, blocks zombies!
+```
+
+---
+
+### **VILLAGE PROGRESSION:**
+
+**TIER 1: HAMLET (5 NPCs)**
+```
+Buildings:
+- 3× Small Houses
+- 1× General Store
+- 1× Well
+
+Population: 5 NPCs
+Services: Basic shop
+Cost: ~10,000g
+```
+
+**TIER 2: VILLAGE (15 NPCs)**
+```
+Buildings:
+- 7× Houses (mix)
+- General Store
+- Blacksmith
+- Tavern
+- Roads + Lamps
+
+Population: 15 NPCs
+Services: Shop, repair, food, sleep!
+Cost: ~30,000g
+```
+
+**TIER 3: TOWN (50 NPCs)**
+```
+Buildings:
+- 20× Houses
+- All shops (5+)
+- Church
+- Town Square
+- Wall + Guard Towers
+
+Population: 50 NPCs
+Services: Everything!
+Cost: ~100,000g
+```
+
+**TIER 4: CITY (100+ NPCs!)**
+```
+Buildings:
+- 50+ Houses
+- Multiple shops (10+)
+- Cathedral
+- Market District
+- Full fortification
+
+Population: 100+ NPCs
+Services: MASSIVE economy!
+Cost: ~500,000g!!!
+```
+
+---
+
+### **NPC INVITATION SYSTEM:**
+
+```
+[Build house]
+[House is empty]
+
+[Complete NPC quest]
+QUEST: "Help the Wandering Merchant"
+
+[Quest Complete!]
+NPC: "Thank you! May I live in your village?"
+
+OPTIONS:
+A) "Yes! My village welcomes you!" ✅
+   → NPC moves into empty house!
+   → Opens shop if assigned!
+
+B) "Not yet, maybe later"
+   → NPC waits, can invite later
+
+[NPC MOVES IN!]
+[Village population: +1]
+[New services available!]
+```
+
+---
+
+## 📊 **BIOME UNLOCK PROGRESSION:**
+
+### **EXPLORATION REWARDS:**
+
+```
+DISCOVER BIOME:
+✅ Map reveals area
+✅ Can teleport (if station repaired)
+
+EXPLORE 25% OF BIOME:
+✅ Unlock basic recipes (food, tools)
+✅ 1 NPC invitation quest appears
+
+EXPLORE 50% OF BIOME:
+✅ Unlock advanced recipes (weapons, armor)
+✅ 2 more NPC quests
+✅ Special blueprint drops
+
+EXPLORE 75% OF BIOME:
+✅ Unlock unique buildings
+✅ Boss location revealed
+✅ Rare crafts unlocked
+
+100% COMPLETE BIOME:
+✅ ALL recipes unlocked!
+✅ Master NPC quest (village leader!)
+✅ Biome-themed outfit (cosmetic!)
+✅ Achievement! 🏆
+✅ Permanent +5% stats in that biome!
+```
+
+---
+
+## ✅ **SUMMARY:**
+
+**BIOME UNLOCKS:**
+- Each of 20 biomes = unique content!
+- Plants, weapons, armor, food, buildings!
+- Explore to unlock! (25% → 100%)
+
+**NPC VILLAGES:**
+- Build houses for NPCs!
+- 4 tiers: Hamlet → City!
+- Services: Shops, blacksmith, tavern, church!
+- Defenses: Walls, towers, gates!
+
+**PROGRESSION:**
+- Hamlet: 5 NPCs, 10,000g
+- Village: 15 NPCs, 30,000g
+- Town: 50 NPCs, 100,000g
+- **CITY: 100+ NPCs, 500,000g!!!**
+
+---
+
+**✅ BIOME VARIETY + VILLAGE BUILDING COMPLETE!** 🗺️🏘️
+
+**Next: Consolidate ALL today's systems into FINAL_GAME_CONTENT_IN_OUT.md!**