novafarma/SYSTEMS_OVERVIEW.md

# 🎮 GAME SYSTEMS OVERVIEW
**Complete Technical Breakdown of All Game Systems**  
**Last Updated:** January 4, 2026

---

## 📋 TABLE OF CONTENTS

1. [System Architecture](#system-architecture)
2. [Core Systems](#core-systems)
3. [Town Buildings](#town-buildings)
4. [Automation Systems](#automation-systems)
5. [Social Systems](#social-systems)
6. [Integration Guide](#integration-guide)

---

## 🏗️ SYSTEM ARCHITECTURE

### **Master Game Systems Manager**
Central coordinator for all game systems.

**Location:** `src/systems/MasterGameSystemsManager.js`

**Responsibilities:**
- Initialize all systems on game start
- Coordinate cross-system events
- Manage save/load for all systems
- Orchestrate hourly/daily updates
- Monitor system status

**Key Methods:**
```javascript
initializeSystems()      // Initialize all 9 systems
setupEventListeners()    // Configure cross-system events
update(time, delta)      // Per-frame update loop
onHourChange(hour)       // Hourly update
onDayChange(day)         // Daily update
saveAllSystems()         // Save all system states
loadAllSystems(data)     // Load all system states
```

---

## 💤 1. SLEEP SYSTEM

**File:** `src/systems/SleepSystem.js`  
**Purpose:** Energy regeneration and time management

### **Features**
- **3-Tier Bed System:**
  - Sleeping Bag: 50% energy, 10% nightmare chance
  - Wooden Bed: 90% energy, 20% dream chance
  - King-size Bed: 100% energy, 30% dream chance, partner bonus

- **Dream Mechanics:**
  - 3 positive dreams (+10 mood, +50 XP, +5 loyalty)
  - 3 nightmares (-20 mood, -10 energy, -10 mood)

- **Partner Bonuses:**
  - +50 relationship points when sleeping with spouse
  - King-size bed required for bonus

### **Key Methods**
```javascript
canUseBed(bedType)           // Check requirements
purchaseBed(bedType)         // Buy bed upgrade
sleep()                      // Initiate sleep
wakeUp()                     // Apply effects & restore energy
canSleepNow()               // Check time (8 PM - 2 AM)
```

### **Events**
- `sleepStarted` - Player begins sleeping
- `wakeUp` - Player wakes up, energy restored

---

## 🔨 2. CRAFTING TABLES SYSTEM

**File:** `src/systems/CraftingTablesSystem.js`  
**Purpose:** Recipe management and item creation

### **Features**
- **Small Crafting Table:**
  - Cost: Free (starter)
  - Recipes: 50 basic
  - Speed: 1.0x
  - Categories: tools_wooden, repairs, food_basic, potions_beginner

- **Large Planning Table:**
  - Cost: 5,000g
  - Requires: Met Gronk + "Builder's Vision" quest
  - Recipes: 100+ advanced
  - Speed: 1.5x
  - Categories: All small + expedition_planning, mechanisms, weapons_advanced, gronk_special

### **Recipe Types**
1. **Tools** - Wooden Hoe, Pickaxe, etc.
2. **Repairs** - Ana's Locket cleaning
3. **Food** - Sandwich, Salad
4. **Potions** - Basic Healing (requires alchemy level 1)
5. **Expeditions** - Maps, Supplies (Gronk required)
6. **Mechanisms** - Automated Sprinkler (engineering 3)
7. **Weapons** - Steel Sword (combat 5)
8. **Gronk Special** - Explosives (7+ hearts with Gronk)

### **Key Methods**
```javascript
purchaseLargeTable()         // Unlock advanced crafting
canCraft(recipeId)          // Check requirements
craft(recipeId, quantity)   // Start crafting
update(deltaTime)           // Progress crafting
completeCraft()             // Finish & grant item
```

### **Events**
- `craftingStarted` - Crafting begins
- `craftingCompleted` - Item crafted

---

## 🥖 3. BAKERY SHOP SYSTEM

**File:** `src/systems/BakeryShopSystem.js`  
**Purpose:** Food shop and gift purchasing

### **Features**
- **Products:**
  - Fresh Bread: 50g, +20 energy, +1 heart (everyone)
  - Cake: 200g, +50 energy, +5 hearts
  - Pie: 150g, +40 energy, +3 hearts
  - Cookies: 25g, +10 energy, +1 heart
  - Croissants: 75g, +25 energy, +2 hearts
  - Seasonal: Pumpkin Pie (autumn), Gingerbread (winter)

- **Gift System:**
  - Items can be gifted to NPCs
  - 2x hearts if NPC favors the item
  - Different NPCs favor different foods

- **Bulk Discounts:**
  - 5-9 items: 10% off
  - 10+ items: 20% off

- **Special Events:**
  - Weekly Baking Competition (prizes!)
  - Birthday cake orders (auto-delivery)

### **Key Methods**
```javascript
unlockBakery()              // Build bakery (8,000g)
buyItem(itemId, quantity)   // Purchase item
giftItem(itemId, npcId)     // Gift to NPC
orderBirthdayCake(npcId)    // Order special cake
startBakingCompetition()    // Weekly event
restockInventory()          // Time-based restock
```

### **Schedule**
- **Open Hours:** 6 AM - 8 PM
- **Morning Restock (6 AM):** Bread, Pie, Croissants
- **Afternoon Restock (2 PM):** Cake

---

## 💈 4. BARBER SHOP SYSTEM

**File:** `src/systems/BarberShopSystem.js`  
**Purpose:** Character customization and styling

### **Features**
- **Hairstyles (7):**
  - Default Hair (free)
  - Pink & Green Dreadlocks (500g) - Kai's signature
  - Blue/Purple/Red Mohawk (300g each)
  - Long Hair (400g) - dyeable
  - Ponytail (250g) - dyeable
  - Bald (100g) - reversible for FREE!

- **Piercings (5):**
  - Ear Gauges (200g) - Kai's trademark
  - Nose Ring (150g)
  - Eyebrow Piercing (100g)
  - Lip Ring (150g)
  - Multiple Ear Piercings (50g each, stackable)

- **Hair Dye Colors (9):**
  - Brown (free), Black, Blonde, Red, Blue, Purple, Pink, Green, White
  - Price: 100-250g

- **Special Services:**
  - Zombie Makeover: 1,000g, +20 loyalty
  - NPC Customization: 500g, requires 5+ hearts
  - Saved Looks: 5 slots

### **Key Methods**
```javascript
unlockBarberShop()          // Build shop (6,000g)
changeHairstyle(id)         // Change hair
addPiercing(id)             // Add piercing
removePiercing(id)          // Remove (free)
dyeHair(colorId)            // Dye hair
dyeClothing(part, color)    // Dye clothes (half price)
zombieMakeover(zombieId)    // Style zombie
saveLook(slotIndex)         // Save current appearance
loadLook(slotIndex)         // Load saved look
```

### **Discounts**
- 5+ visits: 10% off all services

---

## ⚖️ 5. LAWYER OFFICE SYSTEM

**File:** `src/systems/LawyerOfficeSystem.js`  
**Purpose:** Marriage legal services and drama

### **Features**
- **Divorce:**
  - Cost: 50,000g + 25% of remaining money
  - With Prenup: 50,000g + 10% of money
  - Consequences:
    - Spouse relationship reset to 0 hearts
    - Spouse moves out
    - Lose married status
    - King-size bed reverts to single

- **Prenuptial Agreement:**
  - Cost: 10,000g
  - Must be purchased BEFORE marriage
  - Reduces divorce money loss from 25% to 10%

- **Marriage Counseling:**
  - Cost: 5,000g
  - Alternative to divorce
  - Complete 3 tasks to save marriage:
    1. Give favorite gift
    2. Date night at favorite location
    3. Deep conversation
  - Success: +5 hearts
  - Failure: -2 hearts

### **Auto-Unlock Trigger**
Office automatically builds when:
- Player is married AND
- Spouse has ≤3 hearts

### **Key Methods**
```javascript
purchasePrenup()            // Buy prenup (before marriage)
initiateDivorce()           // Start divorce process
processDivorce()            // Complete divorce (after confirmation)
startCounseling()           // Begin counseling
completeCounselingTask(id)  // Complete task
canRemarry()                // Check 28-day cooldown
```

### **Relationship Crisis Warnings**
- **Critical (≤3 hearts):** "Marriage in CRISIS!"
- **Warning (≤5 hearts):** "Marriage struggling..."

---

## ⛏️ 6. ZOMBIE MINER AUTOMATION

**File:** `src/systems/ZombieMinerAutomationSystem.js`  
**Purpose:** Passive resource generation through zombie workers

### **Features**
- **Hire Zombie Miners:**
  - Cost: 5,000g each
  - Max: 10 zombies
  - Random names (e.g., "Grumpy Zed", "Dusty Bones")

- **Assignment:**
  - Assign to specific mine (iron_mine, crystal_cavern, etc.)
  - Assign to depth (must have explored that depth first)
  - Each zombie has efficiency (0.5 - 2.0)

- **Loyalty System:**
  - Starts at 50%
  - Decays slowly while working (-1 per hour)
  - Feed zombies to restore loyalty (brain +20, meat +15)
  - Loyalty affects yield (50% loyalty = 0.5x yield, 100% = 1.5x)

- **Leveling:**
  - Gain XP from mining
  - Level up: +1 yield/hour, +0.05 efficiency
  - Max level: unlimited

- **Equipment Upgrades:**
  - Pickaxe Tier (1-5): 3,000g per tier, +25% yield
  - Helmet Lamp: 2,000g, better visibility
  - Oxygen Tank: 2,500g, deeper mining
  - Cart: 4,000g, +50% collection speed

### **Yield Calculation**
```
Base Yield = 5 per hour
+ Depth Bonus (10% per 10 levels)
× Efficiency (0.5 - 2.0)
× Loyalty Factor (0.5 - 1.5)
× Equipment Bonuses
= Final Yield per Hour
```

### **Key Methods**
```javascript
hireZombieMiner()           // Hire new miner
assignZombieMiner(id, mine, depth)  // Assign to mine
unassignZombieMiner(id)     // Return to surface
collectAutomatedYield()     // Collect resources
feedZombieMiner(id, food)   // Restore loyalty
upgradeEquipment(type)      // Upgrade gear
```

### **Automation Collection**
- Passive generation runs in background
- Collect manually (no auto-collection)
- Reminder every 4 hours if 8+ hours uncollected

---

## 🏘️ 7. TOWN GROWTH SYSTEM

**File:** `src/systems/TownGrowthSystem.js`  
**Purpose:** Population expansion and town development

### **Features**
- **Population Slots (20):**
  - Start: 4 NPCs (Kai, Ana, Gronk, Baker)
  - Max: 20 NPCs
  - Each slot has unlock requirement

- **Unlock Requirements (examples):**
  - Slot 5: Farm Level 2
  - Slot 6: 10,000g
  - Slot 7: Quest "Expand Town 1"
  - Slot 9: Build Bakery
  - Slot 10: Build Barbershop
  - Slot 17: Get married
  - Slot 20: Complete "Town Master" quest

- **Town Services:**
  - Market (6 pop)
  - Hospital (8 pop)
  - School (10 pop)
  - Bank (12 pop)
  - Museum (15 pop)
  - Theater (18 pop)

- **5 Discoverable Villages:**
  1. **Severna Vas** (North Village) - 7 NPCs
     - NPCs: Old Fisher, Hunter, Hermit
     - Items: Ancient fishing rod, hunter bow
  
  2. **Vzhodna Stran** (East Village) - 5 NPCs
     - NPCs: Master Smith, Alchemist
     - Items: Master anvil, philosopher stone
  
  3. **Južno Naselje** (South Village) - 6 NPCs
     - NPCs: Trader, Bard
     - Items: Exotic seeds, rare instruments
  
  4. **Zahodna Dolina** (West Village) - 8 NPCs
     - NPCs: Chef, Librarian, Artist
     - Items: Master cookbook, ancient tome
  
  5. **Mystery Village** (Hidden) - 10 NPCs
     - NPCs: Time Keeper, Oracle
     - Items: Time crystal, prophecy scroll
     - Requires special quest to discover

### **Town Status**
- 4-5: Village
- 6-9: Small Town
- 10-14: Growing Town
- 15-17: Prosperous Town
- 18-20: Thriving City

### **Key Methods**
```javascript
checkPopulationUnlocks()    // Check for new slot unlocks
inviteNPC(npcId)            // Invite NPC to town
discoverVillage(villageId)  // Discover village
getTravelDistance(villageId) // Calculate distance
updateTownServices()        // Check service unlocks
updateTownSign()            // Update sign display
```

### **Events**
- `serviceUnlocked` - New service available
- `townSignUpdate` - Town sign needs update

---

## 🏠 8. NPC PRIVACY SYSTEM

**File:** `src/systems/NPCPrivacySystem.js`  
**Purpose:** NPC home interiors and visit mechanics

### **Features**
- **Hobby-Based Home Generation:**
  Each NPC's home is auto-generated based on their hobby:
  - Fisherman: Mounted fish, fishing net, tackle box
  - Baker: Flour workspace, mixing bowls, bread storage
  - Zombie Worker: Brain jar, work bench, miner equipment
  - Alchemist: Alchemy bottles, brewing cauldron, potion shelf
  - Crafter: Workshop, tool rack, blueprint table
  - Reader: Bookshelves, reading chair, writing desk

- **4 Room Types:**
  1. **Living Room** (PUBLIC - 0 hearts)
  2. **Kitchen** (PUBLIC - 0 hearts)
  3. **Bedroom** (PRIVATE - 5 hearts)
  4. **Hobby Room** (FRIENDLY - 3 hearts)

- **Privacy Levels:**
  - PUBLIC (0 hearts): Anyone can enter
  - FRIENDLY (3 hearts): Friends can enter
  - PRIVATE (5 hearts): Close friends only
  - INTIMATE (8 hearts): Very close relationship
  - LOCKED (10 hearts or marriage): Spouse only

- **Visit Effects:**
  - **Frequency:** 3+ visits per day = annoying (-10 points)
  - **Time of Day:**
    - Morning kitchen visit = breakfast together (+5 points)
    - Night bedroom visit = awkward (-5 points)
  - **Room Interest:**
    - Visiting hobby room = shows interest (+10 points)

- **Privacy Violations:**
  - Entering without enough hearts
  - Penalty: -20 to -100 relationship points
  - Player gets kicked out
  - NPC reacts angrily

### **Key Methods**
```javascript
generateNPCHome(npcId)      // Auto-generate home
attemptEntry(npcId, roomId) // Try to enter room
canAccessSpecialRoom(npcId, roomId)  // Check hearts
getVisitStats(npcId)        // Get visit history
```

---

## 🔗 CROSS-SYSTEM INTEGRATION

### **Event Flow**

```
Marriage Complete
    ↓
Lawyer System: Check Auto-Unlock
    ↓
Town Growth: Check Population Unlocks
    ↓
Service Unlocked Event
    ↓
Master Manager: Initialize Service
```

### **Save/Load Flow**

```
Player Saves Game
    ↓
Master Manager: saveAllSystems()
    ↓
Each System: Return state object
    ↓
Master Manager: Combine all states
    ↓
Save to localStorage/server
```

### **Update Loop**

```
Every Frame (60 FPS)
    ↓
Master Manager: update(delta)
    ↓
Sleep System: update(deltaSeconds)
Crafting System: update(deltaSeconds)
Zombie Miners: update(deltaSeconds)
```

---

## 📊 SYSTEM DEPENDENCIES

```
MasterGameSystemsManager
├─── SleepSystem (no dependencies)
├─── CraftingTablesSystem
│    └─── Requires: Player.inventory
├─── BakeryShopSystem
│    ├─── Requires: TimeSystem
│    └─── Requires: NPCSystem
├─── BarberShopSystem
│    ├─── Requires: Player.appearance
│    └─── Requires: ZombieWorkers (for makeover)
├─── LawyerOfficeSystem
│    ├─── Requires: NPCSystem
│    └─── Requires: QuestSystem
├─── ZombieMinerAutomationSystem
│    ├─── Requires: MiningSystem
│    └─── Requires: TimeSystem
├─── TownGrowthSystem
│    ├─── Requires: NPCSystem
│    ├─── Requires: BuildingSystem
│    └─── Requires: QuestSystem
└─── NPCPrivacySystem
     └─── Requires: NPCSystem
```

---

**Created:** January 4, 2026  
**Version:** 1.0  
**Status:** Complete ✅