novafarma/docs/BIOME_UNLOCKABLES_NPC_VILLAGES.md

# 🗺️🏘️ **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!**