527 lines
14 KiB
Markdown
527 lines
14 KiB
Markdown
# 🎮 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 ✅
|