FINAL DOCS
This commit is contained in:
526
SYSTEMS_OVERVIEW.md
Normal file
526
SYSTEMS_OVERVIEW.md
Normal file
@@ -0,0 +1,526 @@
|
||||
# 🎮 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 ✅
|
||||
Reference in New Issue
Block a user