# 🎮 GAME BIBLE 3: THE TOTAL RECOVERY EDITION 🎮
**Project:** Mrtva Dolina (NovaFarma)
**Version:** 3.0 (Total Recovery)
**Date:** January 16, 2026
**Status:** AA PRE-PRODUCTION READY

---

## 🚨 SYSTEM RECOVERY INDEX (EMERGENCY SCAN)
*All systems confirmed recovered in `EMERGENCY_SYSTEMS_RECOVERY/`*

### 1. 💰 ECONOMY & TRADE
*   **Inventory:** `InventorySystemExpanded.js`, `FullInventoryUI.js` (Storage, Stacking, Filtering)
*   **Shops:** `BakeryShopSystem.js`, `BarberShopSystem.js`, `NPCShopSystem.js`
*   **Zombie Economy:** `ZombieEconomySystem.js` (Rental to NPCs, Brain maintenance)
*   **Black Market:** `DrugEconomySystem.js` (Mushroom trading, hallucination effects)

### 2. 🌍 WORLD & ATMOSPHERE
*   **Time:** `TimeSystem.js` (Day/Night cycle, Season tracking)
*   **Weather:** `MasterWeatherSystem.js` (Rain, Snow, Fog, Storms affecting gameplay)
*   **Noir Vibe:** `VisualEnhancementSystem.js` (Noir Fog, Lighting gradients, Shadows)

### 3. 👥 NPC & SOCIETY (180 TOTAL)
*   **Population:** `NPCPopulationSystem.js` (Tracking all 180 NPCs)
*   **Settlement:** `NPCSettlementSystem.js` (Housing assignments)
*   **Privacy:** `NPCPrivacySystem.js` (NPC schedules, home locking)
*   **Enemies:** `NomadRaiderAI.js` (Raider attacks)

### 4. 🧠 MASTER SYSTEMS
*   **The Brain:** `MasterGameSystemsManager.js` (Coordinates all sub-systems)
*   **The Protector:** `GameManager.js` (Auto-save, Safety checks)
*   **Persistence:** `SaveSystemExpansion.js` (Biome-specific data saving)

---

## 🧬 GAME DNA (CORE VARIABLES)
- `var is_ana_found = false` (Story State)
- `var zombie_labor_count = 0` (Economy State)
- `func start_amnesia_effect()` (Visual State)
- `var current_biom = "Nova Farma"` (World State)

---
# 🎮 DOLINASMRTI - PRODUCTION GAME BIBLE v2.6

**Created:** 06.01.2026 21:30 CET  
**Last Updated:** 12.01.2026 23:50 CET | 💰 **PRICING LOCKED: €10 Early Access / €30 Full Release**  
**Source:** Merged from `generate_assets_full.py` + GAME_BIBLE v1 + Faza 2 + Master Commands + Week 1 + Audio + AI + Advanced + Intro/Aging Marathon + Asset Audit JAN 12  
## 📅 OFFICIAL 10-PHASE RELEASE ROADMAP (LOCKED)

### **Philosophy:**
- **No DLC Policy:** ❌ No paid DLC. ✅ Pay once, get everything forever.
- **Pricing:**
    - **DEMO:** FREE (Hook)
    - **Early Access (Faza 1-2):** €10 (Farm + Town)
    - **Full Release (Faza 10):** €30 (Complete Experience)

### **The 10 Phases:**

#### **1. 🎯 DEMO (Free)**
*   **Focus:** Tutorial, Farming Basics, Intro to Story.
*   **Content:** Farm Map, 2 Crops (Wheat, Carrot), 3-5 Cannabis Seeds (Economy Starter).
*   **Goal:** Hook the player.

#### **2. 🔥 FAZA 1 (Early Access Start - €10)**
*   **Focus:** Farm Completion & Economy.
*   **Content:** 4 Biomes (Grassland, Forest, Desert, Swamp). Full Farming System.
*   **Mechanic:** Zombi Avtomatizacija.

#### **3. ⚡ FAZA 2 (Town Level Up)**
*   **Focus:** Mesto se odpre! (Early Access Content).
*   **Content:** Hipodevil666City, Buildings, NPCs moving in.
*   **System:** **Drug Empire Start** (Dealerji v mestu!), Policijske Racije.
*   **Unlock:** **Gronk**.

#### **4. 🌍 FAZA 3 (First Exploration)**
*   **Focus:** Expanding the World.
*   **New Biomes (4):** Endless Forest, Desert Lite, Swamp, **Witch Forest** (Magic!).
*   **Features:** Portal System.

#### **5. ⛏️ FAZA 4 (Exotic Lands & Drugs)**
*   **Focus:** Extreme Environments & Underground Empire.
*   **Content:** Arctic, Deep Caves (**Mining!**), Volcanic, **Dino Valley** (Tame Dinos!).
*   **Mechanic:** Opium System (Medical vs Black Market).

#### **6. ✨ FAZA 5 (Magical Biomes 1)**
*   **Focus:** High Magic.
*   **Content:** Mythical Highlands, Atlantis.

#### **7. ✨ FAZA 6 (Magical Biomes 2)**
*   **Focus:** Dark Magic.
*   **Content:** Mexican Cenotes, Amazon Apocalypse.

#### **8. ⚔️ FAZA 7 (Boss Rush)**
*   **Focus:** Combat Mastery.
*   **Content:** Arena, Mini-Bosses.

#### **9. 💜 FAZA 8 (Ana's Story)**
*   **Focus:** Narrative Peak.
*   **Content:** Play as Ana (Flashbacks).

#### **10. 🏁 FAZA 9-10 (Endgame & Finale - Full Release €30)**
*   **Focus:** The Cure or The End.
*   **Content:** **Chernobyl Zone**, Viktor, Final Boss (Troll King). **Shotgun Unlock.**



**📊 ASSET STATUS (12.01.2026):**
- **Total Images:** 3,477 PNG/JPG/WEBP files
- **Lines of Code:** 104,439 lines in src/
- **Game Systems:** 188 implemented systems
- **Phaser Scenes:** 18 active scenes
- **Audio:** 12 music tracks + 53 voiceover files



---

## © COPYRIGHT & TRADEMARK INFORMATION

### **Intellectual Property:**
- **Game Title:** "Krvava Žetev" / "DolinaSmrti" / "Bloody Harvest"
- **Original Creator:** David Kotnik
- **Development Studio:** Hipodevil666 Studios™
- **Copyright:** © 2024-2026 David Kotnik. All Rights Reserved.
- **Trademark:** DolinaSmrti™ is a trademark of Hipodevil666 Studios™

### **IP Rights & Usage:**
- All characters, artwork, code, music, story, and game mechanics are the exclusive intellectual property of David Kotnik
- Unauthorized reproduction, distribution, or derivative works are prohibited
- Game concept, design document, and all associated materials are confidential
- This document is for internal production use only

### **Development Credits:**
- **Creator & Lead Developer:** David Kotnik
- **Studio:** Hipodevil666 Studios™
- **Engine:** Phaser 3 (JavaScript/Web)
- **Art Style:** Style 32 Dark-Chibi Noir (Original)
- **Target Platform:** PC (Web-based)
- **Development Start:** 2024
- **Current Version:** Alpha 2.5 (Week 1 Production Ready)

### **Legal Notice:**
This game and all associated materials are protected under Slovenian and international copyright law. Any unauthorized use, reproduction, or distribution may result in legal action. For licensing inquiries, contact: [David Kotnik / Hipodevil666 Studios™]

---

### **Creator's Philosophy & Life Manifest:**

**🎨 My Aesthetic:**
- 😊 Emojis, 💎 Piercings, 🎨 Tattoos, 🌈 Dreadlocks
- 👖 Baggy Pants, 🛹 Longboard, 🛹 Skateboard
- 🎸 Punk Spirit, 🎮 ADHD Energy, ⚡ Creative Chaos

**💭 My Life Motto:**
> *"Življenje gre prehitro mimo - zato uživaj vsako sekundo, kot da je zadnji dan tvojega življenja!"*  
> *("Life goes by too fast - so enjoy every second like it's the last day of your life!")*

**🔥 My Philosophy:**
- **Upaj si, če želiš!** (Dare if you want!)
- **Si daj delati piercing!** (Get yourself a piercing!)
- **Ne poslušaj kolegov!** (Don't listen to naysayers!)
- Pravi kolega bo rekel: *"Lej ti, budala stara, spet novi piercing? Paše ti! Takega te mamo radi!"* 😂
  - *(A true friend will say: "Look at you, you old fool, another piercing? It suits you! That's why we love you!")*

**🎯 My Identity:**
> **Jaz sem HIPO, in to je moja mini zgodba.**  
> *(I am HIPO, and this is my mini story.)*

**💪 My Manifest:**
- **"Ne spreminjam se - spreminjaj se sistem, ne jaz!"**  
  *(I don't change - the system changes, not me!)*
- **"Jaz živim svoje ADHD sanje!"**  
  *(I live my ADHD dreams!)*

**🌟 What This Game Represents:**
This game is a reflection of authentic ADHD creativity - chaotic, colorful, passionate, and unapologetically personal. Every piercing, every dreadlock, every skateboard trick is a celebration of individuality. This is not just a game - it's a lifestyle, a statement, a rebellion against conformity.

**Stay weird. Stay creative. Stay YOU.** 🎆

---

**- David "HIPO" Kotnik**  
*Hipodevil666 Studios™*  
*Living ADHD dreams since forever* ⚡🛹💜

---

## 📋 PRODUCTION STATUS LEGEND

| Symbol | Status | Phase |
|--------|--------|-------|
| ✅ | **DONE** - Fully implemented | All Phases |
| 🔄 | **IN PROGRESS** - Partially complete | Phase 1/2 |
| ❌ | **NOT STARTED** - Planned but not implemented | Phase 3+ |
| 🎯 | **DEMO PRIORITY** - Required for Kickstarter demo | Demo Phase |
| 🔥 | **PHASE 1 CRITICAL** - Must have for Alpha 1 | Phase 1 |
| ⚡ | **PHASE 2 ESSENTIAL** - Must have for Alpha 2 | Phase 2 |

---

## 📖 TABLE OF CONTENTS


### **Title:** Krvava Žetev (DolinaSmrti / Bloody Harvest)

### **Genre:** 
- Survival RPG
- Farming Simulator  
- Post-Apocalyptic Adventure
- Story-Driven Exploration

### **Platform:** PC (Web-based, JavaScript/Phaser 3)

### **Target Audience:** 
- Age: 16+ (mature themes)
- Players who enjoy: Stardew Valley, Don't Starve, Project Zomboid
- Story-driven gameplay with emotional depth

### **Unique Selling Points:**
1. **Emotional Twin Bond Story** - Find your lost sister Ana
2. **Zombie Worker Management** - Control zombies, don't fight them all
3. **Gritty Noir Art Style** - Dark, hand-drawn, mature aesthetic
4. **Micro to Macro Farm** - Start with 8×8 plot, grow to empire
5. **180+ NPCs** with deep personalities and quests
6. **20 Biomes** to explore across post-apocalyptic Slovenia
7. **Multiple Endings** based on player choices

---

## 📚 STORY & SETTING

### **Opening (The Truth Kai Doesn't Remember):**
> "My name is... I don't know. I woke up here. I don't remember anything. But something inside me... a feeling... tells me I'm searching for someone."

### **The REAL Incident (Day 0 - What Actually Happened):**
- **2084** - Slovenia, Happy Family Farm
- Kai & Ana Marković - 14-year-old **TWIN SISTERS** (yes, both girls!)
- Living peaceful life with parents Marko & Elena
- **Day 3:** Zombie outbreak begins
- **Day 7:** **Giant Troll King** attacks their farm
  - Parents sacrifice themselves protecting twins
  - Troll King kidnaps Ana, drags her through portal
  - Kai fights back, gets **MASSIVE HEAD TRAUMA** when thrown into wall
  - **FULL AMNESIA** - Kai remembers NOTHING!

### **Present Day (Game Start - Day 7, Hours Later):**

**KAI'S PERSPECTIVE:**
- Wakes up in basement ruins, disoriented
- Severe headache, bloodstain on wall
- **NO MEMORY** of who she is
- Finds ID card: "Kai Marković, Age: 14"
- Finds photos on wall (herself + unknown girl + adults)
- Feels strange pull in chest (Twin Bond - damaged but present)
- **Doesn't know:**
  - She has a twin sister named Ana
  - Parents are dead
  - What happened 3 days ago
  - Why she feels this inexplicable emptiness

**ANA'S PERSPECTIVE** (If playing Ana's Story):
- Wakes up in **Chernobyl Reactor Core - Level 7** (prison cell!)
- **FULL MEMORY** of abduction (traumatic but clear!)
- Remembers:
  - Parents dying to save them
  - Giant Troll King grabbing her
  - Kai's unconscious body (last image before portal closed)
  - **Twin Bond feels weak/damaged** (Kai's amnesia blocking it!)
- **Mission:** Survive captivity, send signals to Kai, prepare escape

### **Twin Bond Mechanic (Both Perspectives):**

**KAI (Amnesia = Broken Bond):**
- Starts with vague "pull" sensation (direction unknown)
- Finding Ana's belongings → **Flashback cutscenes** (memory fragments!)
- Each memory restored → Twin Bond strengthens
- **50/50 memories** unlocked → Full Bond restored!
- Then can sense Ana's exact location

**ANA (Full Memory = One-Way Bond):**
- Can SEND signals to Kai (telepathic beacons)
- Feels when Kai gets close to her items
- Heartbreak: Kai doesn't respond (amnesia!)
- Keeps trying anyway (hope!)

### **Main Antagonist:**
- **Dr. Viktor Krnić** - Mad scientist who **INTENTIONALLY** released virus!
- Orchestrated Giant Troll King attack
- Wants Ana's blood (contains cure component!)
- Holding Ana prisoner in Chernobyl
- **NOT** Viktor's first attempt (hinted he's done this to other families!)

### **GIANT TROLL KING** (FINAL BOSS):
- **NOT Zmaj Volk** - Zmaj Volk is CUT from game! ❌
- Giant Troll King = **Separate entity**
- 5m tall, incredibly powerful
- Under Viktor's control (via dark magic/tech)
- Kidnapped Ana on Day 7
- **Final Battle:** Chernobyl Reactor Core (3-phase boss fight!)
- Can be killed OR freed from control (endings!)

### **The World:**
- **Slovenia Post-Apocalypse** (Valley of Death = Dolina Smrti)
- **20 diverse biomes:**
  - 9 Normal: Grassland, Forest, Swamp, Desert, Mountain, Snow, Wasteland, Tropical, Radioactive
  - 11 Magical: Dino Valley, Mythical Highlands, Endless Forest, Loch Ness, Catacombs, Egyptian Desert, Amazon, Atlantis, Chernobyl, **Mexican Cenotes, Witch Forest**
- **27 explorable towns** (1 per train station!)
- **Scattered biomes** (150km apart!) - Must travel to discover!
- Mix of realistic Slovenia + fantasy anomalies

---

## 👥 MAIN CHARACTERS
**Status:** ✅ **DONE** | 🎯 **DEMO READY** | 🔥 **PHASE 1 COMPLETE**

| Character | Master Reference | Sprites | Status | Phase |
|-----------|-----------------|---------|--------|-------|
| Kai Marković | ✅ Generated | ❌ Not Started | 🔄 Partial | 🎯 DEMO |
| Ana Marković | ✅ Generated | ❌ Not Started | 🔄 Partial | 🎯 DEMO |
| Gronk (Troll) | ✅ Generated | ❌ Not Started | 🔄 Partial | 🎯 DEMO |
| Susi (Dog) | ✅ Generated | ❌ Not Started | 🔄 Partial | 🎯 DEMO |
| Dr. Viktor Krnić | ❌ Not Generated | ❌ Not Started | ❌ Planned | ⚡ Phase 2 |

---

### **1. Kai Marković** (Playable Character - Kai's Story)
**Age:** 14 (NOT 17!)  
**Gender:** FEMALE (twin sister to Ana!)  
**Role:** Protagonist, Alpha Hybrid, Farmer, Memory-Lost Twin  

**Appearance:**
- **Pink and green dreadlocks** (signature look)
- **Stretched ear gauges** with multiple piercings
- Facial piercings (nose, lip, eyebrow)
- **Katana** strapped to back (main weapon)
- Post-apocalyptic clothing (torn jacket, ripped jeans)
- Dark combat boots
- Brown survival backpack
- Athletic, wiry build

**Visual Reference:**  
![Kai Marković](../../assets/references/kai/master_reference.png)

`Location: /assets/references/kai/master_reference.png`

- Style 32 Dark-Chibi Noir
- Red eyes with dark pupils (human, NOT zombie)
- Confused/determined expression (amnesia!)

**Game Role:**
- **Primary Protagonist** - Main playable character
- **Alpha Hybrid** - Can command zombies telepathically  
- **Farmer/Builder** - Rebuilds civilization from scratch
- **Memory Seeker** - Desperate to recover lost identity
- **Sister Savior** - Ultimate goal: Rescue Ana from Chernobyl

**Personality (Before Amnesia):**
- Protective of Ana (twin bond!)
- Brave, sometimes reckless
- Creative problem-solver
- Loved farming with parents
- Tomboy energy, hands-on worker
- Competitive with Ana (friendly rivalry)

**Personality (After Amnesia - Game Start):**
- **COMPLETELY LOST** - doesn't know who she is!
- Driven by instinct (Twin Bond pull)
- Slowly rebuilds identity through memories
- Desperate to understand the emptiness inside
- Relies on muscle memory (farming, combat)
- Suspicious of strangers (trauma response)
- Grows more determined with each memory

**Abilities:**
- **Alpha Hybrid Power:** Control zombies telepathically
  - Command individual zombies
  - Give complex orders (farm, build, defend)
  - Zombie workers become game mechanic
- **Farming Skills:** Muscle memory intact!
  - Planting, harvesting, irrigation
  - Animal care, breeding
  - Crop rotation knowledge
- **Combat:** Learns as game progresses
  - Scythe proficiency (main weapon)
  - Dodge/roll mechanics
  - Zombie summon in battle
- **Crafting & Building:**
  - Tool creation, structure building
  - Recipe memory returns with items
- **Twin Bond (Damaged):**
  - Vague directional pull (strengthens with memories!)
  - Emotional flashbacks when finding Ana's items
  - Full restoration at 50/50 memories

**Character Arc:**
- **Day 7 (Start):** Wakes with NO memory, confused, alone
- **Week 1-10:** Finds 1-20 memories (fragments of childhood)
  - "Wait... I remember this tree..."
  - "Why do I know how to farm?"
- **Week 11-30:** Finds 21-40 memories (remembers Ana's face!)
  - "The girl in the photos... Ana... my sister?!"
  - Twin Bond becomes stronger
- **Week 31-50:** Finds 41-49 memories (remembers parents' death)
  - "No... they died protecting us..."
  - Rage toward Giant Troll King
- **Memory 50/50:** Full memory restored - **EMOTIONAL BREAKDOWN**
  - "ANA! I'M COMING FOR YOU!"
  - Twin Bond fully active
- **Endgame:** Storms Chernobyl to save Ana
  - Final confrontation
  - Cure discovery
  - True ending unlocked

**Voice/Dialogue Style:**
- **Early Game (Confused):**
  - "Who... who am I?"
  - "This place feels... familiar?"
  - Short, uncertain sentences
- **Mid Game (Determined):**
  - "I won't give up. Someone's waiting for me."
  - "These memories... they're mine!"
  - More confident, driven
- **Late Game (Resolved):**
  - "Ana, I remember everything! Hold on!"
  - "I'll tear down Chernobyl to find you!"
  - Fierce, protective, unstoppable

---

### **2. Ana Marković** (Dual Protagonist)
**Age:** 14 (Kai's twin sister!)  
**Gender:** FEMALE  
**Role:** Dual Protagonist (playable!) / Captive Scientist / Cure Key  

**Appearance:**
- **Light blonde hair** (short, practical cut)
- **Blue eyes WITH pupils** (friendly NPC style)
- Style 32 Dark-Chibi Noir aesthetic
- Scientist aesthetic (lab coat over survival clothes)
- Research backpack with supplies

**Visual Reference:**  
![Ana Marković](../../assets/references/ana/master_reference.png)

`Location: /assets/references/ana/master_reference.png`

**Status in Kai's Story:** 
- **Missing** (kidnapped by Giant Troll King)
- **Alive** (held captive in Chernobyl Reactor Level 7)
- Her 50 belongings scattered across world

**Game Role:**
- **Dual Protagonist** - Playable in "Ana's Story" mode
- **Scientist/Researcher** - Working on zombie cure under duress
- **Memory Anchor** - Her items trigger Kai's flashbacks
- **EndGame Key** - Knowledge needed to stop outbreak

**Ana's Story Gameplay:**
- **Playable character** in "Ana's Story" mode!
- Start: Prison cell, Day 7
- **Full memory** (knows everything!)
- Must survive, research, plan escape
- Write 50 diary pages (same ones Kai finds!)
- Send Twin Bond signals to Kai

---

### **3. Gronk** (Companion)
**Role:** Kai's friend, Tamed Troll, Comic Relief, Tank  
**Species:** Alpha Troll (Giant species)  
**Age:** ~200 years old (young for trolls)  

**Appearance:**
- **MASSIVE green troll** (3m tall, 300kg)
- **Pink dreadlocks** (signature style, 30+ locks)
- **Stretched ear gauges** with piercings (5cm diameter)
- **Nose ring** (silver, punk aesthetic)
- **Vape** always in hand (essential accessory, "Bubble Gum" flavor)
- Black t-shirt: **"TROLL SABBATH"** (purple text, metal band reference)
- Torn baggy black skater pants (distressed, street style)
- **Pink sneakers** (size XXXL, custom-made)
- Green skin with darker muscle definition
- Long arms, hunched posture

**Visual Reference:**  
![Gronk Alpha Troll](../../assets/references/gronk/master_reference.png)

`Location: /assets/references/gronk/master_reference.png`

**Game Role:**
- **Tank Companion** - Absorbs damage, protects Kai
- **Strength Worker** - Lifts heavy objects, breaks walls
- **Comic Relief** - ADHD energy, funny dialogue
- **Loyal Friend** - Saved by Kai, eternal gratitude
- **Fast Travel Mount** - Kai can ride on shoulders

**Personality:**
- **Gentle giant** despite terrifying size
- Loves vaping (various flavors: Bubble Gum, Watermelon, Cotton Candy)
- Loyal to Kai after being saved from mind control
- **ADHD-coded** (short attention span, impulsive, energetic)
- Obsessed with pink aesthetic (dreadlocks, shoes, vape)
- Music lover (favorite band: Troll Sabbath)
- Pacifist unless defending Kai
- Surprisingly intelligent despite appearance
- Nostalgic for "old troll ways" (pre-apocalypse raves)

**Abilities:**
- **Incredible Strength:** Lifts boulders (500kg+)
- **Tank/Defender:** High HP, absorbs damage for Kai
- **Wall Breaker:** Can smash through barriers
- **Earthquake Slam:** Special ability (AOE stun)
- **Intimidation:** Scares away weak enemies
- **Foraging:** Finds rare mushrooms (troll knowledge)

**Character Arc:**
- **First Meeting:** Mind-controlled by Dr. Krnić, attacks Kai
- **Liberation:** Kai breaks mind control (Twin Bond power)
- **Gratitude:** Swears eternal loyalty
- **Growth:** Learns to control strength, becomes gentle
- **Endgame:** Helps storm Chernobyl alongside Kai

**Voice/Dialogue Style:**
- Deep rumbling voice (gentle tone)
- "Gronk sorry... Gronk no mean to scare."
- "Pink is best color! Make Gronk happy!"
- "Bubble Gum vape... *puff* ...ahhhh, tasty!"
- Simple grammar, childlike wonder
- Refers to self in third person ("Gronk do this!")

**Favorite Things:**
- Pink anything (obsessed!)
- Vaping (bubble gum flavor #1)
- Troll Sabbath music (plays on old Walkman)
- Kai (best friend!)
- Smashing things (when allowed)
- Rave culture (pre-apocalypse nostalgia)

---

### **4. Susi** (Dog Companion)
**Breed:** Dachshund - Brown with darker spots, long body, floppy ears, cute  
**Abilities:**
- Finds hidden items
- Warns of danger
- Loyal companion

---

### **5. Dr. Viktor Krnić** (Main Antagonist)
**Role:** Mad scientist villain  
**Goal:** Extract cure from Ana's blood (will kill her)  
**Controls:** Giant Troll King, mutant army  
**Final Boss:** Chernobyl reactor showdown

---

## 📊 MASTER ASSET COUNTS

| Category | Count | Status |
|----------|-------|--------|
| **NPCs & Characters** | ~200+ | From script registry |
| **Livestock Animals** | ~150 | From script registry |
| **Wildlife** | ~200 | From script registry |
| **Monsters & Mutants** | ~500 | From script registry |
| **Bosses** | 25 | From script registry |
| **Crops & Plants** | ~500 | With growth stages |
| **Items & Tools** | ~2000 | Multi-tier materials |
| **Buildings** | ~300 | Farm + Town + Special |
| **Biomes** | 20 | 9 Normal + 11 Magical |
| **Environment** | ~800 | Terrain, nature, weather |
| **UI Elements** | ~200 | Buttons, icons, frames |
| **Workstations** | ~100 | Crafting stations |
| **TOTAL ASSETS** | **~13,500+** | Complete production target |

---

## 🏘️ NPCs & FACTIONS
**Status:** ✅ **166/166 BIOME NPCs DONE!** | 🔥 **PHASE 1 COMPLETE** | Generated: 06.01.2026

| NPC Category | Count | Master Refs | Sprites | Status | Phase |
|--------------|-------|-------------|---------|--------|-------|
| **Main Characters** | 4 | ✅ 4/4 | ❌ 0/4 | 🔄 Refs Done | 🎯 DEMO |
| **Verified NPCs** | 13 | ✅ 13/13 | ✅ 22/13 | 🔄 Refs+Sprites (2 NPCs) | 🔥 Phase 1 |
| **Biome NPCs (20 biomes)** | 166 | ✅ 166/166 | ❌ 0/166 | ✅ **100% REFS** | 🔥 Phase 1 |
| **Town NPCs** | ~190 | ❌ 0/190 | ❌ 0/190 | ❌ Not Started | ⚡ Phase 2 |
| **Zombi Skavt (5 stages)** | 5 | ❌ 0/5 | ❌ 0/5 | ❌ Not Started | ⚡ Phase 2 |
| **Nomad Raiders (12 types)** | 12 | ❌ 0/12 | ❌ 0/12 | ❌ Not Started | ⚡ Phase 2 |
| **TOTAL NPCs** | **~390** | **✅ 183/390** | **✅ 22/390** | **🔄 47% Refs + 6% Sprites** | Multiple |

---

### Main Characters (4)

1. **Kai Marković** - Young farmer with pink/green dreadlocks, ear gauges, piercings, katana on back, torn jacket, athletic build, red eyes with pupils
2. **Ana Marković** - Kai's twin sister, blonde hair, blue eyes with dark pupils, scientist explorer outfit, research backpack
3. **Gronk Alpha Troll** - MASSIVE green troll, pink dreadlocks, ear gauges, nose ring, vape in hand, 'TROLL SABBATH' t-shirt, torn pants, pink sneakers
4. **Susi the Dachshund** - Brown with darker spots, long body, floppy ears, cute companion

### Verified NPCs (13)

**Status:** ✅ **13/13 COMPLETE** - All have master references, 2 have full sprite sets (22 sprites total)

From `/references/npcs/` with master_reference.png:

---

#### **1. Ivan Kovač** (Blacksmith)

![Ivan Kovač](../../assets/references/npcs/ivan_kovac/master_reference.png)

`Location: /assets/references/npcs/ivan_kovac/master_reference.png`

**Role:** Town Blacksmith, Weapon/Tool Smith  
**Appearance:**
- Muscular build (strong arms from forging)
- Protective goggles pushed up on forehead
- Blacksmith apron (soot-covered, leather)
- Red eyes with pupils (friendly human)
- Worn work gloves
- Hammer in hand or at belt

**Job:**
- Repairs and crafts metal tools/weapons
- Upgrades equipment (iron → steel → titanium tiers)
- Teaches blacksmithing skills
- Sells metal goods

**Personality:**
- Gruff but kind
- Takes pride in craftsmanship
- Respects hard workers
- Dislikes shoddy work

---

#### **2. Mayor/Župan** (Town Administrator)

![Mayor](../../assets/references/npcs/mayor/master_reference.png)

`Location: /assets/references/npcs/mayor/master_reference.png`

**Role:** Town Mayor, Authority Figure  
**Appearance:**
- Serious authoritative demeanor
- Long green coat with official sash
- Old tablet computer (pre-outbreak tech)
- Red eyes with pupils (friendly human)
- Professional but weathered

**Job:**
- Town management and governance
- Issues building permits
- Quest giver (town restoration)
- Political decisions

**Personality:**
- Serious but fair
- Wants to rebuild civilization
- Pragmatic leader
- Trusts Kai after proving herself

---

#### **3. Kustos** (Museum Curator)

![Kustos](../../assets/references/npcs/kustos/master_reference.png)

`Location: /assets/references/npcs/kustos/master_reference.png`

**Role:** Museum Curator, Historian  
**Appearance:**
- Wise old scholar (60s-70s)
- Thick glasses
- Notebook always in hand
- Examining artifacts
- Red eyes with pupils (friendly human)

**Job:**
- Museum collection management
- Artifact identification
- Historical knowledge
- Quest giver (collect rare items)

**Personality:**
- Knowledge-obsessed
- Gentle, patient teacher
- Excited by discoveries
- Preserves pre-outbreak culture

---

#### **4. Pek** (Baker)

![Pek](../../assets/references/npcs/pek/master_reference.png)

`Location: /assets/references/npcs/pek/master_reference.png`

**Role:** Town Baker, Food Merchant  
**Appearance:**
- Warm friendly smile
- Chef's apron (flour-dusted)
- Baker's hat
- Holding fresh bread
- Red eyes with pupils (friendly human)

**Job:**
- Bakes bread, pastries, cakes
- Sells food items
- Teaches baking recipes
- Daily breakfast quest

**Personality:**
- Cheerful and welcoming
- Generous with samples
- Loves feeding people
- Community-oriented

**Dialogue:**
- "Fresh bread, just out of the oven!"
- "You look hungry! Here, try this!"

---

#### **5. Šivilja** (Tailor)

![Šivilja](../../assets/references/npcs/sivilja/master_reference.png)

`Location: /assets/references/npcs/sivilja/master_reference.png`

**Role:** Tailor, Clothing Designer  
**Appearance:**
- Elegant dress (practical but stylish)
- Measuring tape around neck
- Scissors in hand
- Fabric samples
- Red eyes with pupils (friendly human)

**Job:**
- Crafts and repairs clothing
- Custom outfits (cosmetic upgrades)
- Armor tailoring
- Fashion quests

**Personality:**
- Artistic and creative
- Detail-oriented perfectionist
- Friendly advice giver
- Appreciates good style

---

#### **6. Tehnik** (Engineer)

![Tehnik](../../assets/references/npcs/tehnik/master_reference.png)

`Location: /assets/references/npcs/tehnik/master_reference.png`

**Role:** Engineer, Tech Specialist  
**Appearance:**
- Work coveralls (oil-stained)
- Tool belt loaded with gadgets
- Safety goggles
- Tech gadgets in hands
- Mechanical enhancements (cybernetic hands)
- Red eyes with pupils (friendly human)

**Job:**
- Repairs advanced technology
- Crafts automation systems
- Upgrades farm machinery
- Tech quest giver

**Personality:**
- Logical, analytical
- Loves tinkering
- Excited by new tech
- Problem solver

---

#### **7. Teacher** (Educator)

![Teacher](../../assets/references/npcs/teacher/master_reference.png)

`Location: /assets/references/npcs/teacher/master_reference.png`

**Role:** School Teacher, Knowledge Keeper  
**Appearance:**
- Glasses (reading style)
- Books in arms (always carrying)
- Kind patient expression
- Red eyes with pupils (friendly human)
- Professional educator clothing

**Job:**
- Teaches children (NPC kids)
- Skill training for Kai
- Library management
- Educational quests

**Personality:**
- Patient and kind
- Believes in education's power
- Nurturing, motherly
- Encourages learning

---

#### **8. Priest Jakob** (Church)

![Priest Jakob](../../assets/references/npcs/priest/master_reference.png)

`Location: /assets/references/npcs/priest/master_reference.png`

**Role:** Priest, Spiritual Leader  
**Appearance:**
- Religious robes (simple, worn)
- Holy book in hand
- Peaceful expression
- Ceremonial cross necklace
- Red eyes with pupils (friendly human)

**Job:**
- Church services
- Weddings, funerals
- Spiritual guidance
- Blesses items

**Personality:**
- Peaceful, calm
- Non-judgmental
- Offers comfort
- Faith in humanity

---

#### **9. Miro Pravnik** (Lawyer)

![Miro Pravnik](../../assets/references/npcs/miro_pravnik/master_reference.png)

`Location: /assets/references/npcs/miro_pravnik/master_reference.png`

**Role:** Lawyer, Legal Advisor  
**Appearance:**
- Older man (50s-60s)
- Wrinkled brown office suit
- Rusty briefcase
- Tired weathered expression
- Red eyes with pupils (friendly human)
- Reading glasses

**Job:**
- Legal contracts (land ownership)
- Dispute resolution
- Official documentation
- Quest: Legal cases

**Personality:**
- Cynical but honest
- Tired from outbreak
- Still believes in law
- Dry humor

**Dialogue:**
- "Even now, contracts matter."
- "Read the fine print, always."

---

#### **10. Arborist/Gozdar** (Tree Planter)

![Arborist](../../assets/references/npcs/arborist/master_reference.png)

`Location: /assets/references/npcs/arborist/master_reference.png`

**Role:** Arborist, Environmental Restorer  
**Appearance:**
- Work clothes (green/brown earth tones)
- Gardening gloves (dirt-stained)
- Seed bags at belt
- Calm patient expression
- Red eyes with pupils (friendly human)

**Job:**
- Plants trees (reforestation)
- Seed supplier
- Teaches gardening
- Environmental quests

**Personality:**
- Patient, calm
- Environmentalist
- Loves nature
- Long-term thinker

**Dialogue:**
- "A tree planted today feeds tomorrow."
- "Nature always finds a way."

---

#### **11. Glavni Smetar** (Main Garbage Collector)

![Glavni Smetar](../../assets/references/npcs/glavni_smetar/master_reference.png)

`Location: /assets/references/npcs/glavni_smetar/master_reference.png`

**Role:** Garbage Collector, Recycler  
**Appearance:**
- Work uniform (practical, durable)
- Reflective vest (safety orange)
- Trash equipment (grabber tool)
- Weathered hands from work
- Hardworking expression
- Red eyes with pupils (friendly human)

**Job:**
- Town cleanup
- Recycling materials
- Waste management
- Environmental cleanup quests

**Personality:**
- Hardworking, underappreciated
- Takes pride in cleanliness
- Resourceful (finds uses for "trash")
- Community-minded

**Dialogue:**
- "Someone's gotta keep this place clean!"
- "One person's trash..."

---

#### **12. Electrician** ⚡ (Town Electrician) **NEW!**

![Electrician](../../assets/references/npcs/electrician/master_reference.png)

`Location: /assets/references/npcs/electrician/master_reference.png`

**Role:** Town Electrician, Power Specialist  
**Employment:** 2 Cekini/day  
**Sprites:** ✅ **11 COMPLETE** (idle×4, walk×4, action×2, portrait×1)  
**Generated:** Jan 10, 2026

**Appearance:**
- Dark grey work jumpsuit with reflective orange/yellow strips
- Blonde streak in short messy dark hair
- Tool belt loaded with wrenches, wire coils, electrical multimeter(
- Electrical cable in hand
- Steel-toe work boots
- Slight stubble (tired worker)
- Small ear piercing
- Red eyes (noir aesthetic)

**Job:**
- Generator maintenance (prevents 5% daily breakdown!)
- Power grid repairs (poles, lines)
- UV light repairs (basement farming)
- Electrical system upgrades

**Daily Routine:**
- **10 AM:** Generator inspection
- **2 PM:** Repairs if needed (with VFX!)

**Abilities:**
- Repair generator (restores 100% health)
- Prevent breakdowns (while employed)
- Free repairs for all electrical systems
- Emergency 24/7 service

**Personality:**
- Professional but tired
- Takes job seriously
- Proud of electrical knowledge
- Reliable, never late

**Dialogue:**
- "Generator's running smooth. No problems here."
- "Just did my daily inspection. All systems nominal."
- "Found a loose wire this morning. Fixed it."

---

#### **13. Zombie Statistician** 👔 (Office Zombie) **NEW!**

![Zombie Statistician](../../assets/references/npcs/zombie_statistician/master_reference.png)

`Location: /assets/references/npcs/zombie_statistician/master_reference.png`

**Role:** Population Statistician, Data Keeper  
**Employment:** 1 Cekin/day (CHEAPEST!)  
**Sprites:** ✅ **11 COMPLETE** (idle×4, walk×4, action×2, portrait×1)  
**Generated:** Jan 10, 2026

**Appearance:**
- Pale zombie skin (green tint)
- Thick-rimmed glasses
- Grey office suit (worn, patches)
- Loosened tie
- Clipboard with population statistics (always!)
- Pen in hand or behind ear
- Name tag: "Z. STATISTICIAN"
- Red eyes (noir zombie)
- Professional undead appearance

**Job:**
- Daily population board updates (9 AM sharp!)
- Tracks living population count
- Tracks zombie population count
- Tracks employed workers
- Maintains accurate statistics

**Daily Routine:**
- **9 AM:** Walk to population board
- Update stats with chalk/pen
- Return to idle position
- Professional zombie shuffle

**Personality:**
- Professional despite undeath
- Obsessed with accuracy
- Dedicated to data
- Unceasingly punctual (9 AM always!)
- Surprisingly intelligent zombie

**Dialogue:**
- "Population count: accurate as always."
- "The numbers... they must be precise."
- "32 zombies counted this morning."
- "Statistics show a 2% increase in workers."
- "Even in undeath, I serve the data."

**Unique Trait:**
- First "friendly" zombie employee
- Proves zombies can be civilized workers
- Sets precedent for zombie workforce


### Companions

**Zombi Skavt** - 5 Evolution Stages (Lv 1-20):
- **Base (Lv1-4)**: Friendly zombie with RED or BLUE bandana, small backpack, red eyes WITH dark pupils, chibi zombie, helpful pose
- **Lantern (Lv5-9)**: Gains glowing lantern, bandana, backpack, red eyes with pupils, friendly zombie scout
- **Armored (Lv10-14)**: Light armor plates added, bandana, backpack, lantern, red eyes with pupils, stronger scout
- **Winged (Lv15-19)**: Small wings for flying/scouting, armor, lantern, bandana, red eyes with pupils, advanced scout
- **Legendary (Lv20)**: Glowing purple aura, all upgrades, wings, armor, lantern, bandana, red eyes with pupils, ultimate scout

### Enemies - Nomad Raiders (12 variants)

**4 types × 3 variants each:**

**Desert Nomads** (Medium threat):
- Warrior: Tan robes, scimitar, turban, desert gear, hostile expression
- Archer: Tan robes, bow and arrows, turban, desert gear, ranged enemy
- Brute: Tan robes, heavy club, turban, muscular, desert gear, tank enemy

**Frost Bandits** (High threat):
- Warrior: Fur armor, ice axe, frost gear, white/blue palette, aggressive
- Archer: Fur armor, ice bow, frost gear, white/blue palette, ranged enemy
- Brute: Heavy fur armor, ice hammer, frost gear, massive build, very aggressive

**Jungle Marauders** (Very high threat):
- Warrior: Tribal mask, poison darts, jungle gear, green/brown palette, dangerous
- Archer: Tribal mask, blowgun, poison darts, jungle gear, stealthy
- Brute: Tribal mask, massive club, jungle gear, intimidating build, very dangerous

**Tech Scavengers** (Extreme threat):
- Warrior: Cyberpunk gear, laser sword, neon-themed, menacing
- Archer: Cyberpunk gear, laser rifle, neon-themed, high-tech
- Brute: Heavy cyberpunk armor, plasma cannon, neon-themed, massive tech enemy

### Zombies (4 types)

1. **Basic Zombie** - Slow shambling, torn clothes, white eyes no pupils, weak enemy
2. **Runner Zombie** - Fast aggressive, athletic build, red eyes no pupils, dangerous
3. **Bloater Zombie** - Large swollen, about to explode, toxic green, tank enemy
4. **Worker Zombie** - Controllable by Kai, basic laborer, white eyes no pupils, friendly when controlled

### Species - Trolls

1. **Troll Male Friendly** - Similar build to Gronk, gray or blue skin, work clothes, friendly expression, red eyes with pupils, town inhabitant
2. **Troll Female Friendly** - Slightly smaller than male, different color palette, town clothing, welcoming expression, red eyes with pupils
3. **Troll Wild Enemy** - Hostile variant, ragged clothing, aggressive pose, NO pupils in eyes, enemy variant

### Species - Elves & Fairies

**Vilinci (Elf)** - Specialty crafting, pointed ears, elegant clothes, working on enchantment, magical aura, red eyes with pupils

**Vile (Fairy)** - Tiny fairy with wings, caring for plants, magical sparkles, instant growth ability, red eyes with pupils

### Generic Citizens (6 base templates × 18 biome recolors = 108)

1. **Citizen Male Worker** - Laborer clothing, neutral expression, red eyes with pupils, BASE for biome recolors
2. **Citizen Male Merchant** - Vest trader outfit, friendly expression, red eyes with pupils, BASE for biome recolors
3. **Citizen Female Farmer** - Work dress apron, kind expression, red eyes with pupils, BASE for biome recolors
4. **Citizen Female Shopkeeper** - Professional clothing, welcoming expression, red eyes with pupils, BASE for biome recolors
5. **Citizen Child** - Simple clothes energetic, playful expression, red eyes with pupils, BASE for biome recolors
6. **Citizen Elder** - Simple robes walking stick, wise expression, red eyes with pupils, BASE for biome recolors

---

## 🐾 ANIMALS & CREATURES (109 TOTAL! - COMPLETE CATALOG)
**Status:** 🔄 **99/109 Generated (91%)** | 🔥 **PHASE 1 IN PROGRESS** | Updated: **Jan 8, 2026 01:56 CET**

**Missing:** 10 creatures (7 Chernobyl Mutants, 2 Wild Animals, 1 Farm Animal)

| Category | Total | Generated | Missing | Notes |
|--------------------|-------|-----------|---------|----------|
| **Chernobyl Mutants** | 10 | 3/10 | 7 | 🔥 Phase 1 |
| **Farm Animals** | 10 | 9/10 | 1 | 🔥 Phase 1 |
| **Wild Animals** | 15 | 13/15 | 2 | 🔥 Phase 1 |
| **Dinosaurs** | 15 | 14/15 | 1 | ⚡ Phase 2 |
| **Mythical** | 39 | 39/39 | 0 | ✅ COMPLETE |
| **Bosses** | 24 | 24/24 | 0 | ✅ COMPLETE |

**Next Steps:**
- 🔥 **Phase 1:** Complete Chernobyl Mutants (7 remaining)
- ⚡ **Phase 2:** Start Dinosaurs (15 total)

---

### **1. CHERNOBYL MUTANTS (10 species)** ☢️

**Common Mutants:**
1. **Mutant Wolf** - Pack hunter, 150 HP, glowing green patches
2. **Giant Rat** - Swarms of 10-20, 80 HP, cat-sized!
3. **Mutant Crow** - Flying, 3 eyes, 40 HP
4. **Radiation Spider** - Dog-sized, poison attacks, 100 HP

**Rare Mutants:**
5. **Two-Headed Dog** - Attacks 2 targets, 200 HP, can be tamed!
6. **Radioactive Boar** - Charge attack, 180 HP, produces rad milk if captured
7. **Glowing Deer** - Bioluminescent, 120 HP, beautiful drops!
8. **Mutant Fish** - 3-eyed, catchable, radiation essence drops

**Boss-Tier:**
9. **Mutant Bear** - 500 HP, devastating attacks, LEGENDARY drops!
10. **Radioactive Cow** - 300 HP, CAPTURE for daily rad milk! (10,000g DNA sample!)

---

### **2. FARM ANIMALS (10 species)** 🐄🐔

**Core Livestock:**
1. **Chicken** - Eggs, feathers | Mutant: Three-Headed Chicken (3× eggs!)
2. **Cow** - Milk, beef | Mutant: Extra udders (2× milk!)
3. **Pig** - Truffles, ham | Mutant: Giant Pig (rideable!)
4. **Sheep** - Wool, milk | Mutant: Fire Sheep (fire wool!)
5. **Horse** - Transportation, 35 km/h | Legendary: Undead Horse!

**Additional Livestock:**
6. **Goat** - Milk, cheese, 1,000g
7. **Duck** - Eggs, feathers, water fowl
8. **Rabbit** - Meat, fur, fast breeders!
9. **Donkey** - Cargo carrier, 100km range!
10. **Llama/Alpaca** - Caravan animals (6-animal trains!), wool

---

### **3. WILD ANIMALS (15 species)** 🦊🐻

**Forest Animals:**
1. **Wolf** - Pack predator, 100 HP, can tame babies!
2. **Bear** - Tank, 300 HP, powerful attacks
3. **Wild Boar** - Charge attack, 120 HP
4. **Deer** - Fast, 80 HP, peaceful
5. **Fox** - Quick, 60 HP, sneaky
6. **Squirrel** - Tiny, collectible
7. **Badger** - Underground, aggressive
8. **Hedgehog** - Defensive spines

**Mountain/Sky:**
9. **Eagle** - Flying scout, 70 HP
10. **Owl** - Night hunter, 50 HP
11. **Bat** - Cave dweller, swarm
12. **Lynx** - Stealth predator, 90 HP
13. **Elk** - Large herbivore, 150 HP

**Wetland:**
14. **Frog** - Small, catchable
15. **Snake** - Various types, some venomous

---

### **4. DINOSAURS (15 species - Dino Valley)** 🦖

**Large Carnivores:**
1. **T-Rex** - BOSS! 1,000 HP, king of dinosaurs!
2. **Spinosaurus** - Semi-aquatic, 800 HP
3. **Allosaurus** - Pack hunter, 600 HP
4. **Carnotaurus** - Fast predator, 500 HP

**Medium Carnivores:**
5. **Velociraptor** - Pack, intelligent, 200 HP, tameable!
6. **Dilophosaurus** - Poison spit, 250 HP
7. **Compsognathus** - Tiny! Swarms, 30 HP

**Herbivores:**
8. **Triceratops** - Tank, 700 HP, charging attacks
9. **Stegosaurus** - Tail spikes, 600 HP
10. **Ankylosaurus** - Armored, club tail, 650 HP
11. **Brachiosaurus** - HUGE! 900 HP, gentle giant
12. **Parasaurolophus** - Herd animal, 400 HP
13. **Pachycephalosaurus** - Head-butt attack, 300 HP

**Flying:**
14. **Pterodactyl** - Sky hunter, 150 HP, mountable!

**Babies:**
15. **Baby Dinos** - Cute versions, tameable! (all species)

---

### **5. MYTHICAL CREATURES (39 species)** ✨🐉

#### **MYTHICAL HIGHLANDS (6):**
1. **Dragon** - Fire/Ice/Storm variants, 800 HP, ULTIMATE mount!
2. **Unicorn** - Healing aura, 300 HP, rare!
3. **Pegasus** - Flying horse, 250 HP
4. **Griffin** - Lion/eagle hybrid, 400 HP
5. **Phoenix** - Revives you 1×/day! 300 HP
6. **Yeti** - Mountain giant, 500 HP

#### **ENDLESS FOREST CRYPTIDS (3):**
7. **Bigfoot** - Gentle giant, 400 HP, peaceful
8. **Wendigo** - Hostile spirit, 350 HP, night hunter
9. **Werewolf** - Full moon only! 300 HP, silver weakness

#### **LOCH NESS & CELTIC (6):**
10. **Nessie** - BOSS! Lake monster, 900 HP
11. **Kelpie** - Water horse, 200 HP, shapeshifter
12. **Selkie** - Seal-human, peaceful, trader
13. **Leprechaun** - Gold hoarder, 50 HP, trickster
14. **Banshee** - Wailing spirit, 150 HP, fear attack
15. **Brownie** - House spirit, farm helper

#### **ATLANTIS (4):**
16. **Mermaid** - Male + Female, 150 HP, underwater
17. **Kraken** - BOSS! 1,200 HP, tentacle attacks!
18. **Sea Serpent** - 600 HP, ocean predator
19. **Sea Dragon** - 700 HP, underwater mount

#### **EGYPTIAN DESERT (4):**
20. **Sphinx** - BOSS! 800 HP, riddle giver
21. **Mummy** - Undead, 200 HP, curse attacks
22. **Giant Scarab** - 400 HP, underground
23. **Anubis Guardian** - 500 HP, temple protector

#### **WITCH FOREST (4):**
24. **Baba Yaga** - BOSS! Witch, 700 HP, flying mortar!
25. **Witch** - Various types, 150 HP
26. **Black Cat** - Familiar, 30 HP, magic
27. **Raven** - Magical, 40 HP, scout

#### **MEXICAN CENOTES (2):**
28. **Quetzalcoatl** - BOSS! Feathered serpent, 850 HP
29. **Axolotl** - 6 variants! Tameable, adorable!

#### **AMAZON RAINFOREST (6):**
30. **Giant Anaconda** - BOSS! 50m long! 900 HP
31. **Jaguar** - Apex predator, 250 HP
32. **Piranha** - Swarms, 20 HP each
33. **Poison Dart Frog** - Tiny, deadly, 10 HP
34. **Sloth** - Slow, peaceful, 80 HP
35. **Toucan** - Colorful, 40 HP
36. **Capybara** - Largest rodent, 100 HP, friendly!

#### **🦎 CHUPACABRA (3 VARIANTS!) - ADDED 06.01.2026:**

**37. Mexican Chupacabra** 🇲🇽
- **Location:** Mexican Cenotes biome
- **Appearance:** Reptilian, spines on back, red eyes, gray skin
- **HP:** 250
- **Attack:** Blood drain (life steal!)
- **Behavior:** Night hunter, attacks livestock!
- **Drops:** Chupacabra Fang, Blood Essence
- **Origin:** Original Latin American cryptid

**38. Mutant Chupacabra** ☢️
- **Location:** Chernobyl/Wasteland
- **Appearance:** Hairless, glowing eyes, radiation scars, GREEN drool!
- **HP:** 300
- **Attack:** Blood drain + radiation damage
- **Behavior:** Radioactive predator
- **Drops:** Radioactive Fang, Mutant DNA
- **Origin:** Radiation-mutated variant

**39. Cryptid Chupacabra** 🌲
- **Location:** Endless Forest
- **Appearance:** Mystery cryptid, rarely seen, shadowy
- **HP:** 280
- **Attack:** Stealth blood drain
- **Behavior:** Stealth predator, VERY rare spawn (1% chance!)
- **Drops:** Pure Blood Essence (LEGENDARY!), Cryptid Fur
- **Origin:** Classic cryptozoology version

**Total Mythical Creatures:** 39 (was 36, +3 Chupacabra!)

---

### **6. WORKER CREATURES (6 types)** 🧚⚒️

**1. Vilinci (Elves)**
- Specialty: Crafting
- Auto-crafting, enchanting

**2. Gnomi (Gnomes)**
- Specialty: Mining
- Ore detection, garden help

**3. Vile (Fairies)**
- Specialty: Plant care
- Instant growth, blessings

**4. Bigfoot/Yeti**
- Specialty: Gathering
- Forest/Snow operations

**5. Golem**
- Specialty: Labor
- Construction, defense

**6. Zmaj (Dragon)**
- Specialty: ULTIMATE
- Mount, fire breath, treasure finder

---

### **📊 CREATURE SUMMARY:**

| Category | Count | Tameable? | Notes |
|----------|-------|-----------|-------|
| Chernobyl Mutants | 10 | Some babies | Radioactive, dangerous |
| Farm Animals | 10 | Yes | Breeding, production |
| Wild Animals | 15 | Babies only | Natural ecosystem |
| Dinosaurs | 15 | Babies only | Dino Valley exclusive |
| Mythical Creatures | 39 | Some | Magical, rare (includes 3 Chupacabra!) |
| Worker Creatures | 6 | Yes | Farm helpers |
| Chupacabra Variants | 3 | NO | Blood-drainers, cryptids |
| **TOTAL** | **109** | **Varies** | **Complete bestiary!** |

**NOT INCLUDING BOSSES** (separate section!)

---

## 🏘️ NPCs & FACTIONS

**Basic Farm Animals:**
- **Cows (3)**: Normal (Holstein pattern), Brown, Highland (shaggy hair)
- **Sheep (3)**: Normal (white wool), Black, Merino (extra fluffy)
- **Chickens (3)**: White, Brown, Rooster
- **Pigs (3)**: Normal (pink), Spotted, Wild boar variant
- **Horses (3)**: Brown, White, Black
- **Goats (2)**: Normal, Angora
- **Ducks (2)**: White, Mallard
- **Other (6)**: Goose, Turkey, Farm Rabbit, Llama, Alpaca, Donkey

**Mutant/Magic Variants:**
- Golden Cow, Fire Sheep, Ice Sheep, Golden Fleece Sheep
- Phoenix Chicken, Rainbow Chicken, Three-Headed Chicken
- Giant Pig (rideable), Undead Horse, Unicorn, Pegasus, Golden Goose

### Wildlife (~200 assets)

**Forest Animals:**
Fox (red, arctic), Deer (normal, doe, fawn), Rabbit (wild, arctic), Hedgehog, Squirrel (red, grey), Raccoon, Skunk, Opossum, Beaver, River Otter, Badger, Porcupine, Bears (brown, black, polar), Wolves (grey, white, black), Moose, Elk, Wild Boar

**Birds:**
Owls (barn, great horned, snowy), Eagles (bald, golden), Hawk, Falcon, Crow, Raven, Sparrow, Robin, Bluebird, Cardinal, Woodpecker, Hummingbird, Peacock, Swans (white, black), Pelican, Flamingo, Parrots (green, macaw)

**Insects & Small:**
Butterflies (monarch, blue, yellow), Bees (honey, bumblebee), Dragonfly, Firefly, Ladybug, Grasshopper, Cricket, Caterpillar, Snail, Slug, Worm, Frogs (green, red), Toad, Turtles (box, snapping), Snakes (garden, rattlesnake), Lizard, Gecko

**Aquatic:**
Fish (bass, trout, salmon, tuna, cod, mackerel, carp, catfish, pike, perch, goldfish, koi, clownfish, angelfish, pufferfish, swordfish, golden), Sharks (great white, hammerhead, whale shark), Rays (manta, stingray), Jellyfish (normal, lion's mane), Octopus, Squid, Crabs (red, blue), Lobster, Shrimp, Starfish, Seahorse, Whales (blue, orca), Dolphin, Seal, Walrus, Penguins (emperor, little)

---

## 👹 MONSTERS & MUTANTS (~500 assets)

### Slimes (12 types)
Green, Blue, Red, Yellow, Purple, Black, White, Rainbow, Metal, Gold, King Slime (BOSS), Queen Slime

### Undead
**Zombies (8)**: Farmer, Miner, Villager, Soldier, Knight, Giant, Dog, Crow
**Skeletons (5)**: Basic, Warrior, Archer, Mage, King (BOSS)
**Ghosts (5)**: Basic, Lantern, Wraith, Banshee, Poltergeist

### Humanoid Monsters
**Goblins (4)**: Basic, Warrior, Shaman, Chief
**Orcs (4)**: Basic, Warrior, Shaman, Warlord (BOSS)
**Trolls (4)**: Forest, Cave, Ice, Fire

### Creatures
**Spiders (4)**: Basic, Venomous, Cave, Queen (BOSS)
**Bats (4)**: Normal, Vampire, Fire, Giant
**Elementals (6)**: Fire, Water, Earth, Air, Ice, Lightning
**Golems (6)**: Stone, Iron, Crystal, Wood, Mud, Gold
**Demons (4)**: Imp, Fire, Shadow, Lord (BOSS)
**Dragons (6)**: Baby, Fire, Ice, Earth, Shadow, Ancient (BOSS)

### Mythical
Mimic, Basilisk, Cockatrice, Manticore, Chimera, Hydra, Phoenix, Griffin, Hippogriff, Centaur, Minotaur, Harpy, Siren, Medusa, Cyclops, Kraken (BOSS), Leviathan (BOSS), Werewolf, Vampire, Mummy, Lich, Treant, Will-o-wisp, Mushroom Monster, Plant Monster, Shadow Creature

---

## 👑 BOSSES (25 total)

1. Zombie King
2. Slime Emperor
3. Ancient Tree
4. Elder Dragon
5. Ice Titan
6. Lava Lord
7. Shadow Master
8. Crystal Guardian
9. Spider Empress
10. Kraken
11. Demon Prince
12. Lich King
13. Werewolf Alpha
14. Vampire Lord
15. Mummy Pharaoh
16. Minotaur King
17. Hydra
18. Chimera
19. Giant Troll
20. Orc Warlord
21. Goblin King
22. Elemental Titan
23. Golem Prime
24. Ancient Phoenix
25. Leviathan

---

## 🌍 BIOMES & LOCATIONS (20 Total - COMPLETE!)
**Status:** ✅ **20/20 DEFINED!** | 🔄 **Assets In Progress** | 🔥 **PHASE 1 PRIORITY**

| Biome Category | Count | Design | Assets | Status | Phase |
|----------------|-------|--------|--------|--------|-------|
| **Normal Biomes** | 9 | ✅ 9/9 | 🔄 Partial | 🔄 Design Done | 🔥 Phase 1 |
| **Magical Biomes** | 11 | ✅ 11/11 | ❌ None | 🔄 Design Done | ⚡ Phase 2 |
| **TOTAL BIOMES** | **20** | **✅ 20/20** | **🔄 Partial** | **✅ 100% Designed** | Multiple |

**Production Priority:**
1. 🎯 **DEMO:** Grassland (Tutorial zone) - ❌ **CRITICAL**
2. 🔥 **Phase 1:** Forest, Desert, Swamp
3. ⚡ **Phase 2:** Dino Valley, Mythical Highlands, Mexican Cenotes, Witch Forest
4. ⚡ **Phase 2:** Chernobyl (Final Boss Zone!)

---

### NORMAL BIOMES (9) - 🔥 **PHASE 1**

**1. Grassland (Travnik)** - Home base
- Ground: Lush green grass, Style 32, smooth vector
- Props: Grass variants, flower patches, small rocks

**2. Forest (Gozd)** - Dense trees
- Ground: Dark green grass with moss
- Props: Moss patches, mushrooms (red/brown), dense bushes, fallen logs

**3. Desert** - Sandy wasteland
- Ground: Golden yellow sand
- Props: Sand dunes, cacti (small/large), brown rocks, bleached skulls

**4. Mountain** - Rocky peaks
- Ground: Grey stone
- Props: Large boulders, sharp rock formations, snow patches

**5. Swamp (Močvirje)** - Foggy wetlands
- Ground: Dark brown murky mud
- Props: Murky water puddles, dead trees, hanging vines, fog effects

**6. Snow (Frozen Tundra/Arktika)** - Ice and blizzards
- Ground: Pristine white snow
- Props: Ice tiles, frozen trees, snowdrifts, icicles

**7. Wasteland** - Ruins and rubble
- Ground: Cracked grey earth
- Props: Rubble piles, scrap metal, broken machinery

**8. Tropical (Beach)** - Palm trees, coconuts
- Ground: Light golden beach sand
- Props: Palm trees, coconuts, seashells, clear blue water

**9. Radioactive Zone** - Glowing toxic
- Ground: Sickly green glow
- Props: Glowing rocks, mutant plants, barrels (toxic waste symbol), toxic puddles

### ANOMALOUS BIOMES (9) - Portal-locked

**10. Dino Valley** - Prehistoric
- Ground: Ancient green grass
- Props: Prehistoric cycad trees, large ferns, dinosaur footprints, fossils, cracked eggs

**11. Mythical Highlands** - Magical
- Ground: Purple mystic grass
- Props: Magical trees (glowing leaves), blue crystals, floating rocks with runes, rainbows

**12. Endless Forest (WITCH FOREST!)** - Cryptids
- Ground: Dark mysterious grass
- Props: Ancient massive trees, thick mystery fog, cryptid footprints, hidden trail markers

**13. Loch Ness** - Scottish highlands
- Ground: Heather moorland
- Props: Scottish pine trees, purple heather flowers, dark loch water, castle ruins

**14. Catacombs** - Underground undead
- Ground: Ancient stone floor
- Props: Scattered bones, stone tombs, skulls, dusty urns

**15. Egyptian Desert** - Pyramids
- Ground: Golden sand
- Props: Massive sand dunes, hieroglyph carved stones, golden scarabs, pyramid stone blocks

**16. Amazon Rainforest** - Piranhas & AXOLOTLS!
- Ground: Dense jungle undergrowth
- Props: Massive jungle trees, thick hanging vines, exotic pink flowers, tribal totem poles, piranha-filled rivers, pink axolotls

**17. Atlantis** - Underwater & AXOLOTLS!
- Ground: Ocean floor sand
- Props: Colorful coral reefs, ancient ruins (columns), giant pearls in oysters, flowing seaweed, rising bubble streams, blue glowing axolotls

**18. Chernobyl (FINAL ZONE!)** - Nuclear
- Ground: Contaminated grey earth
- Props: Reactor ruins, abandoned buildings (broken windows), radioactive waste barrels, Soviet propaganda posters (faded), hazmat warning signs

**19. Mexican Cenotes 🇲🇽** - Mayan underwater caves
- Ground: Limestone cave floor, crystal clear water
- Props: Mayan pyramid (small), temple ruins, stone altars, underground passages, jade deposits, cenote water (pure), axolotls (6 color variants!), stalactites/stalagmites
- NPCs (8-12): Mayan Priest, Villagers (5), Archaeologists (2), Diver, Cenote Guide, Shaman, Jade Merchant
- Boss: **Quetzalcoatl** (flying feathered serpent god!)
- Features: Crystal clear cenote diving, axolotl sanctuary, Mayan culture, ancient secrets

**20. Witch Forest 🧙** - Dark magic forest
- Ground: Cursed earth, dark grass
- Props: Witch huts (5), **Baba Yaga's Hut (walking on chicken legs!)**, dark altars (2), hanging cages, cauldron areas, ritual circles, dark herbs (5 types), cursed gems (3), poison mushrooms (6 types)
- NPCs (6-10): **Baba Yaga (BOSS!)**, Witches (3 types: hostile/neutral), Black Cat (familiar NPC - talks!), Cursed Knight, Lost Child (ghost), Potion Seller, Herbalist
- Boss: **Baba Yaga** (flies in mortar, magic attacks!)
- Special: **Baba Yaga's walking chicken-leg hut!**, Dark atmosphere, cursed areas, poison swamps, magical fog
- Reward: **Broomstick** (magical flight!) from defeating Baba Yaga

---

## 🌾 CROPS & PLANTS (~500 assets with growth stages)
**Status:** 🔄 **80/80 HARVESTED COMPLETE** | ✅ **Jan 7, 2026**

### Basic Crops (80 types) - ✅ **HARVESTED VERSIONS DONE!**

Each crop will have:
- 1 seed packet (❌ TODO)
- 4 growth stages: sprout, growing, maturing, ready (❌ TODO)
- 1 harvested product ✅ **DONE - 80/80!**

**Grains (6)**: Wheat, Corn, Rice, Barley, Oats, Rye

**Root Vegetables (7)**: Potato, Carrot, Onion, Garlic, Turnip, Radish, Beet

**Fruiting Vegetables (7)**: Tomato, Pepper, Eggplant, Cucumber, Zucchini, Pumpkin, Squash

**Leafy Greens (6)**: Lettuce, Cabbage, Spinach, Kale, Broccoli, Cauliflower

**Berries (7)**: Strawberry, Blueberry, Raspberry, Blackberry, Grape, Melon, Watermelon

**Flowers (8)**: Sunflower, Tulip, Rose, Lily, Daisy, Lavender, Poppy

**Industrial (7)**: Cotton, Flax, Hemp, Tobacco, Coffee, Tea, Cocoa

**Tree Fruits (8)**: Apple, Orange, Lemon, Peach, Pear, Cherry, Plum, Banana

**Tropical (6)**: Pineapple, Coconut, Mango, Papaya, Kiwi, Avocado

**Spices (6)**: Hop, Ginger, Turmeric, Vanilla, Cinnamon, Black Pepper

**Hot Peppers (4)**: Chili, Jalapeno, Habanero, Ghost Pepper

**Herbs (8)**: Basil, Mint, Oregano, Thyme, Rosemary, Sage, Parsley, Cilantro

**Mushrooms (4)**: Button, Shiitake, Oyster, Truffle

### Trees (23/44 done - 52%)

**Base Species (11):** Oak, Maple, Pine, Birch, Willow, Cherry Blossom, Apple, Orange, Lemon, Palm, Bamboo  
**Status:** ✅ **11 Base + 12 Variants = 23 TOTAL** | Generated: Jan 7, 2026

**Still Needed:** 21 seasonal variants (each tree needs 4 seasons total)

---

## ⚔️ ITEMS & TOOLS (~2000 assets)

### Tools (9 types × 9 materials = 81)

**Types**: Axe, Pickaxe, Hoe, Shovel, Scythe, Hammer, Sickle, Saw, Chisel
**Materials**: Wood, Stone, Copper, Iron, Steel, Gold, Diamond, Mythril, Adamantine

### Weapons (10 types × 9 materials = 90)

### ⚔️ **COMBAT & WEAPONS (MEDIEVAL FANTASY)**

**Philosophy:** Game is fantasy-focused. No modern guns (Pistol/Rifle ❌) except ONE special case.

#### **🚫 BANNED WEAPONS:**
❌ Pistol, Rifle, SMG, Sniper, RPG, Ray Gun.

#### **🔫 THE ONLY GUN: SHOTGUN (Chernobyl Exclusive)**
- **Unlock:** Found in Chernobyl Military Checkpoint (Late Game).
- **Ammo:** Shells (Expensive Crafting: Gunpowder + Iron + Brass).
- **Stats:** High spread damage, slow reload (2 shots).
- **Use:** Emergency defense against hordes.

#### **🏹 RANGED ARSENAL (21 Arrow Types)**
**Bows:** Primitive -> Hunting -> Longbow -> Compound -> Enchanted -> Elven -> Phoenix -> **Dragon Bow**.

**Arrows (Craftable):**
1.  **Basic:** Wood, Stone, Iron, Steel, Mythril.
2.  **Elemental:** Fire (Burn), Ice (Freeze), Lightning (Chain), Poison (DoT), Explosive (Area), Shadow (Blind), Holy (vs Undead), Nature (Root).
3.  **Special:** Grappling (Climb), Teleport (Blink), Healing (Ally), Vampire (Life Steal), Tracking (Auto-Aim), Drill (Pierce Armor), Rainbow (Random).

---

### 🧠 **MEMORY & TWIN BOND SYSTEM (DEEP DIVE)**

#### **1. FARMING AS THERAPY (Passive Recovery) ✅**
*Action = 5% Chance of Memory Flashback.*
- **Planting:** Remembers Father's gardening lessons. (+XP)
- **Watering:** Remembers Ana's science facts. (+Crop Speed)
- **Harvesting:** Remembers Mother's harvest festival. (+HP)

#### **2. STORY FLASHBACKS (The 6 Pillars) ✅**
*Unlocking these strengthens the Twin Bond.*
1.  **Twin Bond Discovery (Lvl 5):** Hospital scene, doctors realize twins share pain.
2.  **First Protection (Clues 5/50):** Playground fight, young Kai protects Ana.
3.  **Mother's Last Words (Lvl 15):** Outbreak Day 3, Mother sacrifices herself.
4.  **The Kidnapping (Lvl 25):** Troll King attack, Kai is knocked out, Ana taken.
5.  **Dr. Krnić's Plan (Clues 35/50):** Security footage, Krnić reveals he MADE the virus.
6.  **Ana's Final Message (Clues 50/50):** Video diary from Chernobyl ("I'm alive... Come get me.").

---

### ⚙️ **CORE SYSTEMS (CODE IMPLEMENTED)**

#### **1. MICRO FARM SYSTEM (`MicroFarmSystem.js`) ✅**
- **Start:** 8x8 Tile Grid (Locked by fog/overlay).
- **Expansion:** Pay Gold to unlock 2x2 sections (North, South, East, West).
- **Land Types:** Grass (Free), Forest (Needs Axe), Rocky (Needs Pickaxe), Swamp (Needs Drainage).

#### **2. ZOMBIE WORKER AI (`ZombieWorkerSystem.js` & `ZombieEconomySystem.js`) ✅**
- **Roles:** Farmer (Water/Harvest), Miner (Stone), Clearer (Trees), **Sanitation (Clean City)**.
- **Universal Lending:** Rent Zombies to **ANY** town NPC (Baker, Tailor, Teacher...) for profit.
- **Payment:** Earn **Gold** OR **Rare Gifts** (*Kai's Hidden Photo, Ancient Dye, Rare Seed Pack, Mystical Paint, Family Heirloom*).
- **City Sanitation:** Zombies scrub graffiti & pick up trash -> Boosts City Happiness.
- **Maintenance:** Workers consume **Brains** (Fuel). Low Brains = Slow/Grumbling.

#### **3. ZOMBIE SCOUT EVOLUTION (`ZombieScoutLevelingSystem.js`) ✅**
*The Scout is a full RPG Companion.*
- **Level Cap:** 1-20. Gathers XP from Combat, Digging, and Quests.
- **Level 20:** Evolves into **"Scout Commander"** (Larger, Stronger, New Skin).
- **Skill Tree:**
    - **Combat:** *Claw Swipe* (Dmg), *Leap Attack* (Jump Dmg), *Undead Resilience* (Tank).
    - **Digging:** *Speed Dig* (Fast), *Treasure Sense* (See buried loot).
    - **Utility:** *Pack Mule* (+10 Inv Slots), *Night Vision*, *Scout Sprint*.

#### **4. VISUAL & ACCESSIBILITY (`VisualEnhancementSystem.js`) ✅**
- **Animated Textures:** Water flow (4-frame wave), Fire flickering, Tree rustling.
- **Atmosphere:** Multi-layered **Noir Fog**, Rain/Snow particles, Dynamic Lightning (Radial gradients).
- **Typewriter Effect:** Dynamic text reveal with "ADHD Mode" (Instant/Fast/Normal speeds).
- **Lighting:** Torches flicker (0.4-0.6 alpha), Day/Night cycle shadows.

#### **5. MASTER SYSTEM ARCHITECTURE (`MasterGameSystemsManager.js`) 👑**
*Center of Operation. Coordinates 15+ sub-systems.*
- **Cross-System Events:** Marriage unlocks Lawyer; Building Bakery unlocks Food Orders.
- **Automation:** Checks Zombie Miners every 4 hours for yield collection.
- **State Management:** Handles saving/loading for EVERY system in one JSON object.

#### **6. THE SILENT PROTECTOR (`GameManager.js`) 💾**
*Never loose progress.*
- **Auto-Save Triggers:** Scene Change, Aging Up, Memory Found, Gronk Level Up.
- **Safety:** Periodic 5-minute backup saves.
- **Visuals:** Spinning Longboard icon when saving.

#### **7. CORE CODE VARIABLES (GAME DNA) 🧬**
*The heartbeat of the logic.*
- `var is_ana_found = false` (Story State: Twin Bond active?)
- `var zombie_labor_count = 0` (Economy: Total active undead workers)
- `func start_amnesia_effect()` (Visuals: The Blur/Fog state on wakeup)
- `var current_biom = "Nova Farma"` (World: Tracks location across 18 biomes)

#### **8. ANIMAL COMPANION AI (`WorkerCreaturesSystem.js`) 🦉🦇**
*Alpha Hybrid powers control nature.*
- **Night Owl:** Spawns at 00:00. Scouting + Gift Drops.
- **Bat Swarm:** Spawns at Dusk. Resource Gathering + Radar.
- **T-Rex:** *Deprecated AI (Removed per user request).*

#### **9. THE 4 ENDINGS (`MainQuestAnaSystem.js`) 🎬**
1.  **Sacrifice:** Kai dies to save Ana.
2.  **Survival:** Both live but the town falls.
3.  **Ascension:** Kai becomes the Zombie King.
4.  **UTOPIA (True Ending):** Save Ana + 180 NPCs rescued.

---

### 🔮 **MYSTERY & STORY MECHANICS (RECOVERED LOGIC)**

#### **1. AGING SYSTEM (Protagonists Only) ⏳**
*Only **Kai & Ana** physically age as the game progresses (Years 2038-2042).*
- **Visuals:** Sprites get older, scars heal/fade, hair grows.
- **Effect:** Stats change slightly (Strength up, Speed down) as they mature.

#### **2. THE GHOST TRINITY (3 Distinct Types) 👻**
1.  **Ghost Parents:** Benevolent spirits that guide Kai to story clues (Non-hostile).
2.  **Drug Hallucinations:** Visual distortions caused by "Zombie Drugs"/Mushrooms. (False realities).
3.  **Graveyard Spirits:** Restless NPC souls in the Church Graveyard (Hostile/Neutral).

#### **3. TWIN BOND: PULSE & DE-BLUR 🧠**
*Revised Logic: No magic attacks.*
- **Twin Pulse:** Screen shakes/vibrates when near a Memory Clue or Ana's location.
- **Amnesia De-Blur:** The world starts **BLURRED**. Finding memories (Flashbacks) permanently **clears the vision** (De-Blur effect).

#### **4. GRONK'S VAPE MECHANICS 💨**
*Not just a skin - a Gameplay Utility.*
- **Supervisor Mode:** Gronk leans on fences & vapes while watching Zombies farm.
- **Smoke Signals:** Gronk uses vape clouds to signal safe paths or hidden items.
- **Vape Shield:** Creates a temporary smoke screen to hide from zombies.
- **Chill Zone:** Vape cloud regenerates Stamina for nearby allies.

#### **5. INTRO SEQUENCE: "THE AWAKENING" 🎬**
- **Visuals:** Complete Blur -> Eye Blink effect -> Slow focus.
- **Audio:** Muffled sounds -> Ringing -> Sharp reality.
- **Context:** Kai wakes up with total Amnesia; the player must "unlock" his sight.

---

### 🏗️ **TOWN RESTORATION LOGIC (`TownRestorationLogic.js`) ✅**
*Building restoration directly unlocks specific NPCs & mechanics.*

| Building | Unlocked NPC | Mechanic / Benefit |
|----------|-------------|--------------------|
| **Hospital** 🏥 | **Dr. Ana** | Unlocks Healing & Med Kits. |
| **Police Station** 🚓 | **Sheriff/Guard** | Unlocks Patrols & Security. |
| **Mayor's Office** 🏛️ | **Župan (Mayor)** | Unlocks Elections & City Management. |
| **Church** ⛪ | **Župnik (Priest)** | Unlocks Blessings & Graveyard Access. |
| **School** 🏫 | **Učitelj (Teacher)** | Unlocks Education Buffs. |
| **Tech Workshop** ⚙️ | **Tehnik** | Unlocks Electronics Crafting. |
| **Tailor Shop** 🧵 | **Šivilja** | Unlocks Armor/Clothing Upgrades. |
| **Bakery** 🥖 | **Pek (Baker)** | Unlocks High-Energy Food. |
| **Museum** 🏛️ | **Kustos** | Unlocks Lore & Artifact Collection. |

#### **2. GLOBAL RESTORATION SCOPE (27 TOWNS / 150 BUILDINGS)**
*The project spans 18 Biomes. Restoring towns unlocks global bonuses.*
- **Key Towns:** Hope Valley (Start), Forest Grove, Desert Oasis, Frozen Harbor, Volcanic Refuge, Coastal Bay, Mountain Peak, Swamp Village, Crystal City, Atlantis.
- **Endgame Goal:** Rescue all **180 NPCs**.

#### **3. RESTORATION MILESTONES 🏆**
- **10 NPCs:** Unlock `Community Center`.
- **25 NPCs:** Unlock `Town Festivals`.
- **50 NPCs:** Unlock `Town Guard` (Security).
- **100 NPCs:** Unlock `Major City Project` (Skyscrapers).
- **180 NPCs:** **UTOPIA ENDING** (True Pacifist Win).

#### **4. POLICE & DRUG ENFORCEMENT SYSTEMS (DETAILED) 👮♂️🚨**

**1. Sistem licenciranja (Legalizacija) 📜**
*Ko Captain Luka opazi, da žanješ >10 enot marihuane:*
- **Legalna pot (€50):** Plačaš licenco.
    - ✅ Mir pred racijami.
    - ✅ Zombiji lahko prosto prodajajo.
    - ✅ Cene izdelkov +20%.
- **Ilegalna pot (€0):** Ne plačaš nič. Tveganje racij.

**2. Racije in nadzor (Raid System) 🚔**
*Če nimaš licence:*
- **10% Možnost racije:** Ob vsaki žetvi v bunkerju.
- **Kazni:** Zaplemba celotne zaloge + €30 kazni + Padec reputacije.
- **Lov na Zombije:** Policija lahko aretira "Runnerje" (izgubiš zombija in denar).

**3. Čiščenje mesta in varnost 🧹🛡️**
*Vloga Policije v Fazi 2:*
- **Horde Control:** Preprečujejo vdor zombijev v center.
- **NON-LETHAL ONLY:** Policisti nimajo pištol ❌🔫.
    - Uporabljajo gumijevke (batons) in taserje.
    - **EDINO OROŽJE:** Shotgun (najdeš ga le ti v Černobilu).


### Armor (6 pieces × 7 materials = 42)

**Pieces**: Helmet, Chestplate, Leggings, Boots, Gloves, Shield
**Materials**: Leather, Chainmail, Iron, Steel, Gold, Diamond, Dragon

### Arrows (10 types)

Normal, Fire, Ice, Lightning, Poison, Explosive, Healing, Silver, Gold, Diamond

### Potions (19 types)

Health (Small/Medium/Large), Mana (Small/Medium/Large), Stamina, Speed, Strength, Defense, Invisibility, Fire Resistance, Cold Resistance, Poison Cure, Regeneration, Luck, Night Vision, Water Breathing, Slow Fall

### Gems & Minerals (12 types × 2 = 24)

Ruby, Emerald, Sapphire, Diamond, Amethyst, Topaz, Opal, Pearl, Jade, Onyx, Quartz, Obsidian
(Each as gem + ore)

### Metals (8 types × 2 = 16)

Copper, Iron, Gold, Silver, Platinum, Mythril, Adamantine, Titanium
(Each as ore + bar)

### Food (29 prepared items)

Bread, Cheese, Butter, Milk, Egg, Bacon, Sausage, Apple Pie, Cherry Pie, Pumpkin Pie, Fish Cooked, Meat Cooked, Salad, Soup, Stew, Sandwich, Pizza, Cake, Cookie, Strawberry Jam, Blueberry Jam, Red Wine, White Wine, Beer, Juice, Honey, Sugar, Flour, Salt, Pepper, Oil

### Crafting Materials (26 types)

Wood Plank, Wood Stick, Stone Brick, Clay, Glass, Leather, Cloth, Rope, String, Nail, Screw, Gear, Spring, Chain, Feather, Bone, Horn, Fur, Scale, Slime Gel, Ectoplasm, Magic Dust, Fairy Dust, Dragon Scale, Unicorn Hair, Phoenix Feather

---

## 🏛️ BUILDINGS & STRUCTURES (~300 assets)
**Status:** 🔄 **6 Farm Buildings Complete** | ✅ **Jan 7, 2026**

### Farm Buildings (11) - ✅ **6/11 MASTER REFERENCES DONE!**

**COMPLETED:** Farmhouse (gothic cottage), Barn (weathered red), Silo (rusted metal), Shed (dark wood), Well (stone with bucket), Windmill (broken blades)

### Production Buildings (9)

Blacksmith, Carpenter Shop, Tailor Shop, Bakery, Butcher, Brewery, Winery, Apothecary, Jewelry Shop

### Town Buildings (15)

House (Small/Medium/Large), Inn, Tavern, General Store, Town Hall, Church, School, Library, Museum, Hospital, Bank, Barracks, Watchtower

### Decorative (10)

Well (Stone/Wood), Fountain, Hero Statue, Goddess Statue, Gazebo, Bridge (Wood/Stone), Dock, Lighthouse

### Fences & Gates (6)

Wooden Fence, Stone Wall, Iron Fence, Hedge Fence, Wooden Gate, Iron Gate

### Storage (6)

Wooden Chest, Iron Chest, Gold Chest, Barrel, Crate, Cabinet

---

## 🌲 ENVIRONMENT & TERRAIN (~800 assets)

### Ground Tiles (16)

Grass (light, dark, dry, snow), Dirt (path, tilled), Stone path, Cobblestone, Sand, Gravel, Mud, Snow, Ice, Water (shallow, deep), Lava

### Nature Objects (13)

Rocks (small, medium, large, moss), Fallen log, Old stump, Bushes (green, berry, flower), Tall grass, Reeds, Cattails, Lily pad, Coral, Seaweed

### Flowers (8 colors)

Red, Blue, Yellow, Purple, White, Pink, Orange, Mixed patch

### Mushrooms (6 types)

Red (spotted), Brown (edible), Blue (magic), Purple (poisonous), Glowing (bioluminescent), Giant

### Cave Elements (6)

Stalactite, Stalagmite, Blue Crystal, Red Crystal, Green Crystal, Cave Moss (glowing)

### Weather/Sky (10)

White Cloud, Rain Cloud, Storm Cloud, Rainbow, Sun, Full Moon, Crescent Moon, Stars

---

## 👔 CLOTHING & ARMOR (~100 assets)
**Status:** ✅ **6 Worker Clothing Complete** | ✅ **Jan 7, 2026**

### Worker Clothing (6) - ✅ **MASTER REFERENCES DONE!**

**COMPLETED:**
- Farmer shirt (torn, patched, gothic)
- Farmer pants (weathered, holes)
- Work boots (muddy, heavy)
- Straw hat (worn, dark)
- Leather gloves (stitched)
- Work apron (stained, pockets)

**TODO:**
- Armor sets (light, medium, heavy)
- Weather-specific clothing
- Biome-specific outfits
- Accessories (scarves, belts, badges)

---

## 🖥️ UI ELEMENTS (~200 assets)

### Buttons (12)

Play, Pause, Stop, Menu, Settings, Close, Confirm, Cancel, Arrow (Left/Right/Up/Down)

### Icons (12)

Health (red heart), Mana (blue orb), Stamina (lightning), Gold (coin stack), Inventory (bag), Map (scroll), Quest (exclamation), Achievement (star), Mail (envelope), Settings (gear), Save (floppy), Load (folder)

### Status Effects (6)

Poison (green skull), Burn (flames), Freeze (snowflake), Stun (stars), Buff (arrow up), Debuff (arrow down)

### Frames & Panels (5)

Frame (Wood/Stone/Gold), Panel (Wood/Parchment)

### Cursors (6)

Normal (pointer), Interact (hand), Attack (sword), Dig (shovel), Plant (seed), Water (droplet)

---

## 🎨 ART STYLE & VISUAL IDENTITY
**Status:** ✅ **LOCKED & APPROVED** | 🔥 **CRITICAL FOR ALL ASSETS**

### 📐 **MASTER STYLE: "Style 32 (Dark-Chibi Noir)"**

**Official Style Name:** Dark-Chibi Noir  
**Style Code:** Style 32  
**Influence:** Gothic + Chibi + Post-Apocalyptic + Punk  
**Lock Date:** 30.12.2025  
**Status:** ✅ **100% LOCKED - NO CHANGES ALLOWED!**

---

### 🎯 **CORE STYLE ELEMENTS** (From Master References)

**Analyzed from uploaded reference + 18 generated master references**

#### **1. CHARACTER PROPORTIONS (Chibi)**
- ✅ **Head-to-body ratio:** 1:1.5 to 1:2 (large head, small body)
- ✅ **Body:** Short, stubby limbs (2-3 head heights total)
- ✅ **Eyes:** HUGE, expressive (1/3 of face!)
- ✅ **Hands/Feet:** Small, simplified (3-4 fingers visible)
- ✅ **Overall:** Cute but DARK aesthetic

**Reference:** Ana character shows perfect chibi proportions!

#### **2. LINE ART & OUTLINING**
- ✅ **Outline thickness:** 3-4px black outlines (THICK!)
- ✅ **Line quality:** Clean vector-style lines (smooth, no rough edges)
- ✅ **Line color:** Pure black (#000000)
- ✅ **Interior lines:** 1-2px for details (thinner than outline)
- ✅ **Consistency:** ALL characters must have same line weight

#### **3. COLOR PALETTE (Gothic + Noir)**

**Primary Colors:**
- ✅ **Dark blues:** #2C3E50, #34495E (clothing, shadows)
- ✅ **Grays:** #7F8C8D, #95A5A6 (metals, stone)
- ✅ **Deep reds:** #C0392B, #E74C3C (eyes, accents!)
- ✅ **Muted greens:** #27AE60, #16A085 (nature, hair)
- ✅ **Blacks:** #2C2C2C, #1C1C1C (outlines, shadows)

**Gothic Elements:**
- ✅ **Purple accents:** #8E44AD, #9B59B6 (magic, special items)
- ✅ **Blood red:** #8B0000 (danger, horror elements)
- ✅ **Bone white:** #F5F5DC (skulls, undead)
- ✅ **Midnight black:** #0A0A0A (night scenes, void)

**Lighting Style:**
- ✅ High contrast (dark shadows + bright highlights)
- ✅ Rim lighting (light edge around characters)
- ✅ Dramatic lighting (from above or side, not flat)

#### **4. EYE STYLE (CRITICAL!)**

**Human/Friendly NPCs:**
- ✅ **Red eyes with DARK PUPILS** (Kai, Ana, NPCs)
- ✅ Pupils visible and centered
- ✅ White sclera (eye whites)
- ✅ Highlights in eyes (2-3 white dots)
- ✅ Expression: Friendly, alive, human

**Zombies/Enemies:**
- ✅ **White eyes NO pupils** (pure white or yellow)
- ✅ OR **Red eyes NO pupils** (hostile zombies)
- ✅ No highlights (dead, soulless look)
- ✅ Expression: Empty, dead, hostile

**Controlled Zombies:**
- ✅ **Eyes CHANGE when controlled:** White → Red WITH pupils!
- ✅ Visual feedback for player!

#### **5. CLOTHING & TEXTURE**

**Post-Apocalyptic Details:**
- ✅ **TORN CLOTHING:** Rips, holes, patches visible
- ✅ **WEATHERED:** Dirt stains, wear marks
- ✅ **PRACTICAL:** Backpacks, pockets, utility
- ✅ **PUNK ELEMENTS:** Piercings, gauges, patches

**Gothic Details:**
- ✅ **Stitches:** Visible on patches (Frankenstein-style)
- ✅ **Straps & Buckles:** Leather, metal clasps
- ✅ **Crosses & Symbols:** Subtle gothic iconography
- ✅ **Cloaks & Hoods:** Dramatic flowing fabric

**Texture Style:**
- ✅ Cell-shaded (flat colors with sharp shadow edges)
- ✅ NO gradients (or very minimal)
- ✅ Patterns: Hatching for shadows, NOT soft gradients

#### **6. FACIAL FEATURES (Gothic-Punk)**

**Piercings & Modifications:**
- ✅ **Ear gauges** (Kai, Gronk - signature!)
- ✅ **Facial piercings** (eyebrow, nose, lip)
- ✅ **Tattoos** (optional, minimal)

**Hair Styles:**
- ✅ **Dreadlocks** (Kai, Gronk - chunky, stylized!)
- ✅ **Messy/Spiked** (post-apocalyptic, not perfect)
- ✅ **Unnatural colors** OK! (green, pink, purple)

**Expression:**
- ✅ Exaggerated anime-style emotions
- ✅ Large mouth (1/4 of face when open)
- ✅ Eyebrows expressive (thick, dramatic)

#### **7. BACKGROUND & ENVIRONMENT**

**Biome Aesthetic:**
- ✅ **Dark atmosphere** (low light, shadows everywhere)
- ✅ **Decay & Ruins** (broken buildings, overgrown)
- ✅ **Muted colors** (desaturated compared to characters)
- ✅ **Depth:** 3 layers (foreground, mid, background)

**Gothic Architecture:**
- ✅ **Pointed arches** (churches, castles)
- ✅ **Crumbling stone** (weathered, ancient)
- ✅ **Overgrown** (vines, moss, nature reclaiming)
- ✅ **Tombstones & Crosses** (graveyard aesthetic)

#### **8. SPECIAL EFFECTS**

**Magic/Energy:**
- ✅ **Glowing effects:** Purple, blue, green auras
- ✅ **Particle effects:** Sparkles, dust motes
- ✅ **Fire:** Stylized, cartoon flames (NOT realistic)

**Blood/Gore:**
- ✅ **Stylized blood:** Dark red, NOT realistic
- ✅ **Minimal gore:** Suggest violence, don't show graphic detail
- ✅ **16+ Rating:** Dark but not gratuitous

---

### 📸 **GENERATED MASTER REFERENCES (246 TOTAL PNG FILES! 🔥)**

**Status:** ✅ 246 reference images generated across all categories!

**Last Count:** 06.01.2026 22:14 CET

---

#### **📊 BREAKDOWN BY CATEGORY:**

| Category | Count | Location | Status |
|----------|-------|----------|--------|
| **Biome NPCs (Total)** | **166** | `assets/references/npcs/[biome]/` | ✅ 100% Complete! |
| **Wild Animals** | 13 | `assets/references/creatures/wild_animals/` | 🔄 87% (13/15) |
| **Farm Animals** | 6 | `assets/references/creatures/farm_animals/` | 🔄 60% (6/10) |
| **Chernobyl Mutants** | 3 | `assets/references/creatures/chernobyl_mutants/` | 🔄 30% (3/10) |
| **Nomad Raiders** | 8 | `assets/references/enemies/nomad_raiders/` | 🔄 67% (8/12) |
| **Zombies** | 2 | `assets/references/enemies/zombies/` | 🔄 50% (2/4) |
| **Main Characters** | 3 | `assets/references/main_characters/` | ✅ 75% (3/4) |
| **Companions** | 4 | `assets/references/companions/` | ✅ 100% (4/4) |
| **Species** | 6 | `assets/references/species/` | ✅ 100% (6/6) |
| **Trees** | 11 | `assets/references/trees/` | 🔄 Partial |
| **Buildings** | 8 | `assets/references/buildings/` | 🔄 Partial |
| **Approved NPCs** | 11 | `assets/references/npcs/npc_style_approved/` | ✅ 11/11 |
| **Bugs** | 2 | `assets/references/bugs/` | ✅ 2 bugs |
| **OTHER** | 3 | Root directory | Misc |
| **TOTAL PNG FILES** | **246** | Full `assets/references/` tree | **🔥 MASSIVE!** |

---

#### **🏘️ BIOME NPC BREAKDOWN (166 total!):**

| Biome | NPCs Generated | Status |
|-------|----------------|--------|
| **Atlantis** | 17 | ✅ Complete |
| **Loch Ness** | 15 | ✅ Complete |
| **Mythical Highlands** | 12 | ✅ Complete |
| **Egyptian Desert** | 12 | ✅ Complete |
| **Amazon Rainforest** | 12 | ✅ Complete |
| **Tropical** | 10 | ✅ Complete |
| **Mexican Cenotes** | 10 | ✅ Complete |
| **Witch Forest** | 8 | ✅ Complete |
| **Dino Valley** | 8 | ✅ Complete |
| **Desert** | 8 | ✅ Complete |
| **Chernobyl** | 8 | ✅ Complete |
| **Grassland** | 7 | ✅ Complete |
| **Mountain** | 6 | ✅ Complete |
| **Forest** | 6 | ✅ Complete |
| **Catacombs** | 6 | ✅ Complete |
| **Snow/Arctic** | 5 | ✅ Complete |
| **Endless Forest** | 5 | ✅ Complete |
| **Wasteland** | 4 | ✅ Complete |
| **Swamp** | 4 | ✅ Complete |
| **Radioactive** | 3 | ✅ Complete |
| **TOTAL BIOME NPCs** | **166** | ✅ **100% DONE!** |

---

#### **✅ MAIN CHARACTERS (3/4 - 75%):**

1. ✅ **Kai Marković** (`assets/references/main_characters/kai/master_reference.png`) - **FOUND!** 🎉
2. ✅ **Ana Marković** (`assets/references/main_characters/ana/`) - 2 files
3. ✅ **Gronk Alpha Troll** (`assets/references/main_characters/gronk/`) - 2 files
4. ❌ **Susi (promoted to main!)** - Is in companions!

**Status:** Main 3 characters DONE! ✅

---

#### **✅ VERIFIED NPCs (13/13 - 100%):**

1. ✅ Ivan Kovač (Blacksmith) - `npcs/ivan_kovac/`
2. ✅ Mayor/Župan - `npcs/mayor/`
3. ✅ Kustos (Museum) - `npcs/kustos/`
4. ✅ Pek (Baker) - `npcs/pek/`
5. ✅ Šivilja (Tailor) - `npcs/sivilja/`  
6. ✅ Tehnik (Engineer) - `npcs/tehnik/`
7. ✅ Teacher - `npcs/teacher/`
8. ✅ Priest Jakob - `npcs/priest/`
9. ✅ Miro Pravnik (Lawyer) - `npcs/miro_pravnik/`
10. ✅ Arborist/Gozdar - `npcs/arborist/`
11. ✅ Glavni Smetar - `npcs/glavni_smetar/`
12. ✅ **Electrician** ⚡ - `npcs/electrician/` - **11 SPRITES ✅ Jan 10, 2026**
13. ✅ **Zombie Statistician** 👔 - `npcs/zombie_statistician/` - **11 SPRITES ✅ Jan 10, 2026**

**Status:** ALL verified NPCs generated + 2 with FULL sprite sets! ✅

---

### 🎉 **INCREDIBLE PROGRESS!**

**246 PNG FILES = 246 MASTER REFERENCES!**

This is **1.8% of total 13,500 target** BUT represents:
- ✅ **100% of ALL 166 Biome NPCs!** (MASSIVE!)
- ✅ **11/11 Core NPCs** (100%)
- ✅ **22/109 Creatures** (20%)
- ✅ **Trees, buildings, species** started!

**Estimated Value:** 246 images × $0.012 = **~$2.95 generated!**  
**Google Quota Used:** 246 of daily 1000 limit

---

### 🖌️ **GOTHIC STYLE ENHANCEMENTS** (Optional Layer)

**When to Use Gothic Elements:**

1. **✅ Witch Forest Biome:**
   - Baba Yaga's hut (walking on chicken legs!)
   - Dark altars, ritual circles
   - Cursed gems, poison mushrooms
   - Black cats, ravens (familiars)

2. **✅ Catacombs Biome:**
   - Skulls, bones, tombs
   - Gothic arches, crumbling stone
   - Candlelight, lanterns
   - Mummies, ancient undead

3. **✅ Chernobyl (Final Zone):**
   - Soviet gothic architecture
   - Abandoned reactor (industrial gothic)
   - Hazmat suits (modern horror)
   - Radiation glow (green eerie light)

4. **✅ Bosses:**
   - Giant Troll King (gothic armor, dark crown)
   - Baba Yaga (flying mortar, witch aesthetic)
   - Dr. Krnić (mad scientist, gothic lab)

**Gothic Textures to Add:**
- ✅ Stone carvings (gargoyles, faces)
- ✅ Wrought iron (fences, gates)
- ✅ Stained glass (broken, colorful)
- ✅ Candlelight (flickering, warm)
- ✅ Cobwebs (corners, abandoned areas)

---

### 🎮 **STYLE CONSISTENCY RULES**

**MANDATORY for ALL assets:**

1. ✅ **Thick black outlines** (3-4px)
2. ✅ **Chibi proportions** (1:1.5 to 1:2)
3. ✅ **Red eyes with pupils** (friendly) OR **White/Red eyes no pupils** (enemies)
4. ✅ **Cell-shaded coloring** (flat with hard shadows)
5. ✅ **Dark-Chibi Noir palette** (muted, gothic colors)
6. ✅ **Post-apocalyptic details** (torn clothes, wear, dirt)
7. ✅ **Gothic accents** (when appropriate for biome/character)
8. ✅ **512x512px PNG** with alpha transparency
9. ✅ **Front-facing** for master references
10. ✅ **Centered** with 10px margin

**❌ FORBIDDEN:**
- ❌ Realistic art style (NO photorealism!)
- ❌ Soft gradients (keep sharp shadows!)
- ❌ Thin outlines (must be THICK!)
- ❌ Bright pastel colors (keep it DARK!)
- ❌ Perfect/clean characters (must show wear!)

---

### 📋 **GENERATION PROMPT TEMPLATE**

**For NPCs:**
```
[Character Name], [role], Style 32 Dark-Chibi Noir, 
chibi proportions, thick black outlines, red eyes with dark pupils,
post-apocalyptic clothing (torn, weathered), 
[specific details: piercings, hair, outfit],
gothic accents, dark atmosphere,
512x512px PNG, front-facing, alpha transparency
```

**For Enemies:**
```
[Enemy Name], Style 32 Dark-Chibi Noir,
chibi proportions, thick black outlines, white eyes NO pupils,
hostile pose, [specific features],
dark colors, gothic horror elements,
512x512px PNG, front-facing, alpha transparency
```

---

**Status:** ✅ Style guide LOCKED and MANDATORY for all future assets!

---

## ⚒️ WORKSTATIONS (~100 assets)

Anvil, Forge, Furnace, Kiln, Loom, Spinning Wheel, Workbench, Crafting Table, Alchemy Table, Enchanting Table, Cooking Pot, Oven, Wine Press, Oil Press, Flour Mill, Sawmill, Tanning Rack, Drying Rack, Fermenter, Distiller, Beehive, Butter Churn, Cheese Press, Seed Maker, Recycler

---

## 📊 PRODUCTION SUMMARY
**Last Updated:** 06.01.2026 22:50 CET

### 📈 OVERALL PROGRESS (Updated Jan 8, 04:00 CET)

| Category | Total | Complete | In Progress | Not Started | % Done |
|----------|-------|----------|-------------|-------------|--------|
| **Master References** | 13,500 | ~246 | 0 | ~13,254 | 1.8% |
| **NPCs** | 388 | 181 | 0 | 207 | 46.6% |
| **Creatures** | 109 | 99 | 0 | 10 | 90.8% |
| **Bosses** | 24 | 0 | 0 | 24 | 0% |
| **Biomes (Design)** | 20 | 20 | 0 | 0 | 100% ✅ |
| **Biomes (Assets)** | 20 | 0 | 0 | 20 | 0% |
| **Character Animations** | 52 | 52 | 0 | 0 | 100% ✅ |
| **Demo Assets** | 292 | 157 | 0 | 135 | 54% |
| **Sprites (All Phases)** | ~50,000 | ~300 | 0 | ~49,700 | 0.6% |

**🎉 CHARACTER ANIMATIONS COMPLETE! (Jan 8, 2026)**
- Kai: 20/20 frames (idle, walk, dig, swing)
- Ana: 10/10 frames (idle, walk)
- Gronk: 10/10 frames (idle, walk)
- Susi: 12/12 frames (idle, run, bark)

**Note:** Master References include duplicates (_nobg versions). Will be cleaned tomorrow to ~120-130 unique files.

---

### ⚙️ GAME SYSTEMS & MECHANICS

**Total Systems:** **174** (Massive!)  
**Latest Update:** Jan 10, 2026 - Week 1 Systems Complete  
**Location:** `/src/systems/`

---

#### 🎯 **WEEK 1 SYSTEMS (NEW - Jan 10, 2026)**

| System | Status | Lines | Phase | Description |
|--------|--------|-------|-------|-------------|
| **ResourceLogisticsSystem** | ✅ DONE | 351 | 🔥 Phase 1 | Auto-pickup, storage, depots, UI, VFX |
| **CityManagementSystem** | ✅ DONE | 552 | 🔥 Phase 1 | Population tracking, Zombie Statistician NPC |
| **BuildingUpgradeSystem** | ✅ DONE | 705 | 🔥 Phase 1 | Generator, Electrician NPC, power grid |

**TOTAL:** 1,608 lines coded (Jan 10, 2026)

---

#### � **FARMING SYSTEMS (15)**

| System | Status | Description |
|--------|--------|-------------|
| FarmingSystem.js | ✅ | Core farming mechanics |
| MicroFarmSystem.js | ✅ | 8x8 starter farm |
| MicroFarmExpansionSystem.js | ✅ | Farm growth mechanics |
| FarmAutomationSystem.js | ✅ | Automated farming |
| CropGrowthSeasonSystem.js | ✅ | Seasonal crop cycles |
| PerennialCropSystem.js | ✅ | Long-term crops |
| AnimalsSeedsSystem.js | ✅ | Animal/seed management |
| BugCatchingSystem.js | ✅ | Insect collection |
| FishingSystem.js | ✅ | Fishing mechanics |
| CookingSystem.js | ✅ | Food preparation |
| MesojedkeSystem.js | ✅ | Carnivorous plants |
| SlimesDogsSystem.js | ✅ | Pet slimes/dogs |
| AnimalBreedingSystem.js | ✅ | Animal reproduction |
| BreedingSystem.js | ✅ | Breeding mechanics |
| BreedingUISystem.js | ✅ | Breeding interface |

---

#### 👥 **NPC & DIALOGUE SYSTEMS (12)**

| System | Status | Description |
|--------|--------|-------------|
| NPCPopulationSystem.js | ✅ | NPC spawning/management |
| NPCSpawner.js | ✅ | Dynamic NPC spawning |
| NPCShopSystem.js | ✅ | NPC merchant system |
| NPCPrivacySystem.js | ✅ | NPC privacy mechanics |
| NPCSettlementSystem.js | ✅ | NPC town building |
| DialogueSystem.js | ✅ | Conversation system |
| GrokCharacterSystem.js | ✅ | Gronk companion AI |
| NomadRaiderAI.js | ✅ | Enemy NPC behavior |
| ZombieCommunicationSystem.js | ✅ | Talk to zombies! |
| ZombieWorkerSystem.js | ✅ | Zombie labor force |
| SmartZombieSystem.js | ✅ | Intelligent zombies |
| ZombieSystem.js | ✅ | Core zombie mechanics |

---

#### ⚔️ **COMBAT & DEFENSE SYSTEMS (10)**

| System | Status | Description |
|--------|--------|-------------|
| DefenseSystem.js | ✅ | Base defense |
| BossBattlesSystem.js | ✅ | Boss fights |
| BossArenaSystem.js | ✅ | Arena mechanics |
| GiantTrollKingBoss.js | ✅ | Final boss AI |
| HordeWaveSystem.js | ✅ | Wave defense |
| FarmRaidSystem.js | ✅ | Farm attacks |
| HybridAbilitySystem.js | ✅ | Special abilities |
| HybridSkillSystem.js | ✅ | Skill tree |
| SkillTreeSystem.js | ✅ | Progression tree |
| MagicSystem.js | ✅ | Magic mechanics |

---

#### 🗺️ **WORLD & BIOME SYSTEMS (15)**

| System | Status | Description |
|--------|--------|-------------|
| BiomeSystem.js | ✅ | 20 biome generator |
| ChunkManager.js | ✅ | Chunk loading (500x500 world) |
| TerrainSystem.js | ✅ | Terrain generation |
| Flat2DTerrainSystem.js | ✅ | 2D flat terrain |
| TransitionSystem.js | ✅ | Biome transitions |
| RiverSystem.js | ✅ | River generation |
| LakeSystem.js | ✅ | Lake generation |
| OceanSystem.js | ✅ | Ocean mechanics |
| StructureSystem.js | ✅ | World structures |
| StructureInteractionSystem.js | ✅ | Structure use |
| PyramidSystem.js | ✅ | Pyramid dungeons |
| PortalNetworkSystem.js | ✅ | Fast travel |
| PortalRepairSystem.js | ✅ | Portal fixing |
| MiningDungeonsSystem.js | ✅ | Procedural mines |
| FogOfWarSystem.js | ✅ | Map exploration |

---

#### 🏙️ **TOWN & BUILDING SYSTEMS (18)**

| System | Status | Description |
|--------|--------|-------------|
| BuildingSystem.js | ✅ | Building placement |
| BuildSystem.js | ✅ | Construction mechanics |
| BuildingRestorationSystem.js | ✅ | Ruin restoration |
| BuildingVisualsSystem.js | ✅ | Building graphics |
| TownRestorationSystem.js | ✅ | Town rebuilding |
| TownRestorationLogic.js | ✅ | Restoration logic |
| TownGrowthSystem.js | ✅ | Town expansion |
| CityGratitudeSystem.js | ✅ | Citizen happiness |
| ElectionSystem.js | ✅ | Politics/voting |
| ChurchSystem.js | ✅ | Church mechanics |
| BarberShopSystem.js | ✅ | Haircuts! |
| BakeryShopSystem.js | ✅ | Bakery shop |
| LawyerOfficeSystem.js | ✅ | Legal system |
| MuseumEvolutionSystem.js | ✅ | Museum growth |
| SchoolBuffSystem.js | ✅ | Education bonuses |
| WorkstationSystem.js | ✅ | Crafting stations |
| CraftingTablesSystem.js | ✅ | Crafting UI |
| ExpansionSystem.js | ✅ | Territory expansion |

---

#### 💰 **ECONOMY & TRADING SYSTEMS (10)**

| System | Status | Description |
|--------|--------|-------------|
| DrugEconomySystem.js | ✅ | Drug trade mechanics |
| ZombieEconomySystem.js | ✅ | Zombie currency |
| MintingSystem.js | ✅ | NFT/crypto mechanics |
| GemDropSystem.js | ✅ | Gem collection |
| CourierSystem.js | ✅ | Package delivery |
| ShopSystem (NPCShopSystem) | ✅ | NPC shops |
| LootSystem.js | ✅ | Loot drops |
| CollectionSystem.js | ✅ | Item collecting |
| AlbumCollectionSystem.js | ✅ | Album/cards |
| RecipeSystem.js | ✅ | Recipe discovery |

---

#### 📦 **INVENTORY & CRAFTING SYSTEMS (8)**

| System | Status | Description |
|--------|--------|-------------|
| InventorySystem.js | ✅ | Player inventory |
| InventorySystemExpanded.js | ✅ | Extended inventory |
| FullInventoryUI.js | ✅ | Full UI (24 slots) |
| CraftingSystem.js | ✅ | Item crafting |
| CraftingTiersSystem.js | ✅ | Craft progression |
| ToolSystem.js | ✅ | Tool management |
| MagicEnchantingSystem.js | ✅ | Item enchanting |
| StarterChestSystem.js | ✅ | Starting items |

---

#### 🎯 **QUEST & STORY SYSTEMS (10)**

| System | Status | Description |
|--------|--------|-------------|
| QuestSystem.js | ✅ | Quest mechanics |
| QuestSystemExpanded.js | ✅ | Extended quests |
| StoryQuestSystem.js | ✅ | Main story |
| MainQuestAnaSystem.js | ✅ | Ana rescue quest |
| AnaClueSystem.js | ✅ | Ana's 50 items |
| LandmarkQuestSystem.js | ✅ | Exploration quests |
| TwinBondSystem.js | ✅ | Twin telepathy |
| TwinBondUISystem.js | ✅ | Bond UI |
| ProgressionSystem.js | ✅ | Player progression |
| LegacySystem.js | ✅ | Legacy mechanics |

---

#### 🌦️ **WEATHER &ENVIRONMENT SYSTEMS (8)**

| System | Status | Description |
|--------|--------|-------------|
| WeatherSystem.js | ✅ | Weather effects |
| MasterWeatherSystem.js | ✅ | Advanced weather |
| WeatherEnhancementsSystem.js | ✅ | Enhanced effects |
| BiomeMusicSystem.js | ✅ | Biome soundtracks |
| DynamicEnvironmentAudio.js | ✅ | Ambient sounds |
| WindFoliageSystem.js | ✅ | Wind + foliage |
| WaterPhysicsSystem.js | ✅ | Water mechanics |
| WaterRipplesSystem.js | ✅ | Water ripples |

---

#### 🎨 **VISUAL & PARTICLE SYSTEMS (10)**

| System | Status | Description |
|--------|--------|-------------|
| LightingSystem.js | ✅ | Day/night lighting |
| ParticleEffects.js | ✅ | Particle system |
| ParticleEnhancementsSystem.js | ✅ | Enhanced particles |
| VFXSystem.js | ✅ | Visual effects |
| VisualEffectsSystem.js | ✅ | Effect library |
| VisualEnhancementSystem.js | ✅ | Graphics polish |
| UIPolishSystem.js | ✅ | UI effects |
| UIGraphicsSystem.js | ✅ | UI rendering |
| ParallaxSystem.js | ✅ | Parallax backgrounds |
| CameraSystem.js | ✅ | Camera controls |

---

#### 🔊 **AUDIO SYSTEMS (7)**

| System | Status | Description |
|--------|--------|-------------|
| SoundManager.js | ✅ | Audio manager |
| AudioLoader.js | ✅ | Audio file loading |
| AudioTriggerSystem.js | ✅ | Event sounds |
| VoiceoverSystem.js | ✅ | Voice acting |
| CinematicVoiceSystem.js | ✅ | Cutscene voices |
| VisualSoundCueSystem.js | ✅ | Deaf accessibility |
| LocalizationSystem.js | ✅ | Language support |

---

#### ♿ **ACCESSIBILITY SYSTEMS (7)**

| System | Status | Description |
|--------|--------|-------------|
| AccessibilitySystem.js | ✅ | Master accessibility |
| ADHDAutismSupportSystem.js | ✅ | ADHD/Autism support |
| DyslexiaSupportSystem.js | ✅ | Dyslexia tools |
| MotorAccessibilitySystem.js | ✅ | Motor support |
| ScreenReaderSystem.js | ✅ | Screen reader |
| InputRemappingSystem.js | ✅ | Custom controls |
| VisualSoundCueSystem.js | ✅ | Visual audio cues |

---

#### 👨‍👩‍👧 **SOCIAL & FAMILY SYSTEMS (6)**

| System | Status | Description |
|--------|--------|-------------|
| MarriageRomanceSystem.js | ✅ | Marriage system |
| ChildrenFamilySystem.js | ✅ | Children mechanics |
| GenerationalGameplaySystem.js | ✅ | Multi-generation |
| CharacterCustomizationSystem.js | ✅ | Character editor |
| MultiplayerSystem.js | ✅ | Multiplayer |
| MultiplayerSocialSystem.js | ✅ | Social features |

---

#### 🚂 **TRANSPORT & MOUNT SYSTEMS (4)**

| System | Status | Description |
|--------|--------|-------------|
| TransportSystem.js | ✅ | Transportation |
| VehicleSystem.js | ✅ | Vehicles |
| MountSystem.js | ✅ | Animal mounts |
| ScooterRepairSystem.js | ✅ | Scooter fixing |

---

#### ⛏️ **MINING & AUTOMATION SYSTEMS (5)**

| System | Status | Description |
|--------|--------|-------------|
| MiningSystem.js | ✅ | Mining mechanics |
| MiningDungeonsSystem.js | ✅ | Procedural mines |
| ZombieMinerAutomationSystem.js | ✅ | Zombie miners |
| AutomationSystem.js | ✅ | General automation |
| AutomationTierSystem.js | ✅ | Automation tiers |
| WorkerCreaturesSystem.js | ✅ | Worker AI |

---

#### 💾 **SAVE & MANAGEMENT SYSTEMS (6)**

| System | Status | Description |
|--------|--------|-------------|
| SaveSystem.js | ✅ | Save/load |
| SaveManager.js | ✅ | Save management |
| SaveSystemExpansion.js | ✅ | Extended saves |
| PlaytimeTrackerSystem.js | ✅ | Playtime stats |
| LeaderboardSystem.js | ✅ | Online leaderboards |
| SteamIntegrationSystem.js | ✅ | Steam achievements |

---

#### 🎮 **UI & INPUT SYSTEMS (8)**

| System | Status | Description |
|--------|--------|-------------|
| TutorialSystem.js | ✅ | Tutorial popups |
| CentralPopupSystem.js | ✅ | Notification system |
| StatsSystem.js | ✅ | Player stats |
| UnifiedStatsPanel.js | ✅ | Debug stats |
| InteractionSystem.js | ✅ | Interaction prompts |
| TimeSystem.js | ✅ | In-game clock |
| SleepSystem.js | ✅ | Sleep mechanics |
| StaminaSystem.js | ✅ | Energy system |

---

#### 🎯 **SPECIAL MECHANICS (12)**

| System | Status | Description |
|--------|--------|-------------|
| MapRevealSystem.js | ✅ | Map discovery |
| PathfindingSystem.js | ✅ | AI pathfinding |
| WorldEventSystem.js | ✅ | Random events |
| AchievementTriggers.js | ✅ | Achievements |
| GraveSystem.js | ✅ | Death/graves |
| BlueprintSystem.js | ✅ | Building blueprints |
| ZombieScoutLevelingSystem.js | ✅ | Scout progression |
| ZombieScoutSkills.js | ✅ | Scout abilities |
| BiomeEnemySystem.js | ✅ | Biome enemies |
| MasterGameSystemsManager.js | ✅ | System orchestration |
| TechnicalPerformanceSystem.js | ✅ | Performance monitoring |
| PlatformSupportSystem.js | ✅ | Cross-platform |

---

#### 🎬 **ANTIGRAVITY ENGINE (1)**

| System | Status | Description |
|--------|--------|-------------|
| Antigravity.js | ✅ | Core game engine integration |

---

### 📊 **SYSTEMS SUMMARY**

**Total Systems:** **178** (+4 NEW Jan 10!)  
**Status Distribution:**
- ✅ Implemented: 178 (100%)
- Week 1 NEW: 3 systems (1,608 lines)
- Audio & Accessibility NEW: 4 systems (1,073 lines)
- Total Code: ~260,000+ lines estimated

**Category Breakdown:**
- 🌾 Farming: 15
- 👥 NPCs: 12
- ⚔️ Combat: 10
- 🗺️ World: 15
- 🏙️ Town: 18
- 💰 Economy: 10
- 📦 Inventory: 8
- 🎯 Quest: 10
- 🌦️ Weather: 8
- 🎨 Visual: 10
- 🔊 Audio: **11** (+4 NEW!)
- ♿ Accessibility: 7
- 👨‍👩‍👧 Social: 6
- 🚂 Transport: 4
- ⛏️ Mining: 5
- 💾 Save: 6
- 🎮 UI/Input: 8
- 🎯 Special: 12
- 🎬 Engine: 1
- 🎬 **Scenes: 1** (NEW!)

**NEW SYSTEMS (Jan 10, 2026):**
1. **SplashScene.js** - Hipodevil666 Studios™ branding (146 lines)
2. **EnhancedAudioSystem.js** - Complete audio integration (354 lines)
3. **DynamicTypewriterSystem.js** - NO voice recording needed! (302 lines)
4. **audio_optimizer.py** - .wav → .ogg converter (149 lines)

**Accessibility Grade:** **AAA+**
- Visual indicators for deaf players
- Xbox haptic feedback
- 4 typing speeds (ADHD instant mode!)
- Skip everything controls
- Multi-sensory design (Audio + Visual + Haptic)

**This is a MASSIVE game!** 🎆

---

## 🎭 ADVANCED SYSTEMS (DESIGNED - JAN 10, 2026)

### **Future Features Roadmap**

Four major advanced game systems have been fully designed for future implementation. These systems add emotional depth, replayability, and premium value while maintaining the noir aesthetic.

---

### **1. 🎭 GENERATIONAL AGING SYSTEM**

**Concept:** Kai and Ana age visually throughout the game (30+ year search for Ana)

#### **Three Life Stages:**

**Young Kai (Age 25-29):**
- Full dreadlocks (dark with pink/green streaks)
- All piercings (2 ears, eyebrow)
- Baggy punk style, band shirts
- Lean, athletic build
- Movement: 120% speed
- Health: 100 HP
- **Sprite Requirements:** Full set (~40 sprites)

**Adult Kai (Age 30-39):**
- Dreadlocks maintained (slightly matted)
- **ALL piercings remain** (HIPO: identity never changes!)
- More practical clothing (cargo pants, work jacket)
- Muscular from survival
- Optional family (wife + child NPCs)
- Movement: 100% speed
- Health: 150 HP
- Wisdom: Standard
- **Quest Note:** Ana search continues even with family!
- **Sprite Requirements:** Full set + family (~50 sprites)

**Elder Kai (Age 40+):**
- **Grey/silver dreadlocks** (dignified, maintained)
- **ALL piercings STILL present!**
- Full grey beard
- Weathered but strong
- Baggy pants always (punk grandpa!)
- Possible grandchildren NPCs (16-20)
- Movement: 80% speed (wiser, not weaker)
- Health: 200 HP (resilient veteran)
- Wisdom: +50% (better crafting/negotiation)
- **Special Quest:** "Grandpa's Promise" - grandchildren join Ana search
- **Sprite Requirements:** Full set + grandchildren (~60 sprites)

**Ana Aging:**
- When found, Ana ages to match Kai's current stage
- If Kai is Elder, Ana is also Elder (twin synchronization)
- Lab coat remains (scientist identity)
- Emotional reunion regardless of age

**Total Sprite Requirements:** ~250 new sprites (3 Kai sets, 3 Ana sets)

---

### **2. 🎬 INTRO VIDEO & FLASHBACK EXPANSION**

**Concept:** Emotional intro sequence with blur-to-clear effects on happy memories

#### **Intro Sequence (3 Scenes):**

**Scene 1: Happy Memories (Blurred → Clear)**
1. Longboard with father (ocean pier, sunny day)
   - Blur clears when father says "Pojdi, sin!" (Go, son!)
2. Dreadlocks at barbershop (pink streak being added)
   - Blur clears on mirror reflection smile
3. Twin moment with Ana (university lab)
   - **CLEAREST shot** (most important memory)
   - Ana in lab coat, both laughing

**Scene 2: The Apocalypse (Sharp, No Blur - Harsh Reality)**
1. Father zombie bite (silhouette)
2. Virus spread (news footage style)
3. Ana captured (military van)
   - Last view: Ana crying in window

**Scene 3: The Search (Time-Lapse Aging)**
- Year 1: Young Kai (hopeful)
- Year 5: Kai fighting (determined)
- Year 10: Adult Kai with child (still searching)
- Year 15: Elder Kai grey dreads (never giving up)
- Final frame: "30 years later..."

#### **In-Game Flashback System:**

**Type 1: Memory Fragment** (2-3 seconds)
- Quick blur effect
- Voice line from past
- Screen shimmer
- Returns to gameplay

**Type 2: Full Flashback** (Playable cutscene)
- Playable sequence as young Kai
- Clear visuals (no blur)
- Learn new info about Ana
- Optional objectives

**Type 3: Dream Sequence** (Sleep system)
- Triggers when Kai sleeps
- Blur-to-clear reveals clues
- Symbolic noir imagery
- Wakes with new quest marker

**Triggers:** Finding Ana's items, visiting locations, Kai's birthday

---

### **3. 👻 GHOST QUEST (PARENTS)**

**Concept:** After Ana found, parents' ghosts appear in Noir-Neon style to guide Kai to closure

#### **Activation Conditions:**
1. ✅ Ana must be rescued (main quest complete)
2. ✅ Cure distributed (world saved)
3. ✅ Returns to home town ruins
4. ✅ Night time (23:00-04:00)

#### **Ghost Design (Noir-Neon Aesthetic):**

**Father Ghost:**
- 50% translucent
- **Neon cyan outline** (glowing edges)
- Noir shadow beneath
- Ghostly longboard visible
- Hover animation (no walking)
- Gentle glow pulse (1.5s cycle)

**Mother Ghost:**
- 50% translucent
- **Neon magenta outline** (warm love)
- Holds ghostly flowers
- Warm smile despite death
- Reaches toward Kai (can't touch)
- Gentle glow pulse

#### **Quest Phases:**

**Phase 1: First Encounter** (Home Ruins)
- Blur effect starts (dreamlike)
- Ghosts appear with cyan/magenta glow
- Father explains they've been watching
- Quest Marker: "Follow the Spirits"

**Phase 2: Journey to Death Site**
- Ghosts lead across map (slow movement)
- Environmental storytelling:
  - Blood stains (old)
  - Broken barricades
  - Father's broken longboard
  - Mother's wilted flowers
- Ambient: Somber piano

**Phase 3: The Pier** (Death Location)
- Same pier from intro memory!
- Flashback shows zombie attack
- Parents' last stand protecting Kai & Ana
- Ghosts become 100% visible for this scene

**Phase 4: Closure** (Unmarked Grave)
- Kai places flowers, longboard, items
- Dialog choice (Thank/Wish/Proud)
- Ghosts fade to white light
- Sunrise over ocean
- Peace achieved

#### **Rewards:**
- **Ghostly Longboard**: Cyan glow mount (fast travel)
- **Mother's Blessing**: +20% health regen (permanent)
- **Family Photo**: Unlocks secret ending variant
- **Achievement**: "Closure" (15G)

**Sprite Requirements:** 16 ghost sprites (father 8, mother 8)
**Audio:** 10 AI voice phrases (ethereal filter)

---

### **4. 🎁 SPECIAL EDITION GRONK HELPER**

**Concept:** Premium companion for early adopters (Buyer #1-20) and streamers

#### **License Activation:**

**Early Adopter Check:**
```javascript
if (buyerNumber >= 1 && buyerNumber <= 20) {
    activateGronk('early_adopter', buyerNumber);
    // Golden crown appears on Gronk
}
```

**Streamer Mode Detection:**
```javascript
if (detectStreamerMode()) { 
    // Detects: OBS, Streamlabs, Twitch Studio
    activateGronk('streamer');
    // "🔴 LIVE" indicator appears
}
```

#### **Gronk Companion Features:**

**Abilities:**
1. **Auto-Gather**: Resources within 10-tile radius
2. **Combat Assist**: Smash attack (AOE damage)
3. **Vape Boost**: +50% speed for 30s (5min cooldown)
4. **Emotional Support**: +10% XP when nearby

**Visual:**
- Chibi Gronk (Style 32 Dark-Chibi Noir)
- Pink vape always visible
- Follows Kai (2 tiles behind)
- Can't die (respawns if "defeated")

**Random Dialog:**
- "Pink is best color, Kai agree?"
- "Gronk help find Ana! No give up!"
- "System no change Gronk OR Kai!"

#### **Special Edition Exclusives:**

**Early Adopter Perks (First 20 Buyers):**
- **Golden crown** on Gronk (tiny, visible)
- "Founder" title in-game
- Exclusive dialog: "Kai one of first! Gronk proud!"
- Founder-only Discord role

**Streamer Mode Bonuses:**
- "🔴 LIVE" indicator on Gronk
- Twitch chat integration (Gronk reads chat!)
- Subscriber alerts = Gronk dialog
- Donation triggers special emotes

#### **Customization (Unlockable):**

**Vape Flavors:**
- Bubble Gum (speed boost) - default
- Cotton Candy (health regen)
- Watermelon (stamina boost)
- Blue Raspberry (night vision)

**Outfits:**
- Punk Gronk (studded jacket)
- Formal Gronk (tiny tux)
- Beach Gronk (hawaiian shirt)
- Winter Gronk (beanie, scarf)

**Piercings:**
- Add piercings to Gronk (like Kai!)
- Earrings, nose ring, eyebrow pierce
- Found via "Piercing Kits" in-game

**Sprite Requirements:** 20+ Gronk companion sprites

---

### 📊 **ADVANCED SYSTEMS SUMMARY**

**Total Design:** 4 major systems  
**Sprites Required:** ~290 new  
**Code Estimate:** ~2,000 lines  
**Audio Required:** 10 ghost voices + SFX  
**API Required:** License server  

**Status:** ✅ Full design complete  
**Document:** `ADVANCED_SYSTEMS_DESIGN.md` (1,100+ lines)  
**Next Phase:** Reference image creation → Sprite generation  

---

### 📸 **REFERENCE IMAGES REQUIRED**

#### **Priority for Next Session:**

1. **Odrasli Kai (Adult - Family Man)**
   - Age 30-39
   - Beard, more tattoos
   - ALL piercings still present!
   - Still on longboard
   - More serious expression
   
2. **Stari Kai (Elder - Punk Grandpa)**
   - Grey/silver dreadlocks
   - ALL piercings still present!
   - Baggy pants always (punk identity)
   - Full grey beard
   - Wise, dignified, still fierce
   
3. **Otac (Father - Alive Version)**
   - 40s, warm smile
   - Longboard in hand
   - Ocean pier background
   - Pre-ghost reference
   - (Agent adds neon-cyan effect later)
   
4. **Mati (Mother - Alive Version)**
   - 40s, gentle smile
   - Holding flowers
   - Caring expression
   - Pre-ghost reference
   - (Agent adds neon-magenta effect later)

**All in Style 32 Dark-Chibi Noir!**

---

### 🛠️ TECHNOLOGIES & TOOLS

#### ✅ **CONFIRMED TECHNOLOGIES**

| Technology | Purpose | Status |
|------------|---------|--------|
| **Phaser 3** | Game Engine | ✅ Implemented |
| **JavaScript** | Core Language | ✅ In Use |
| **Tiled** | Map Editor | ✅ In Use |
| **Google Imagen 3** | Asset Generation | ✅ Active (Quota: 1000/day) |
| **ComfyUI** | Image Processing | ✅ Ready (Local) |
| **Edge TTS** | Voice Generation | ✅ Ready |
| **Python** | Automation Scripts | ✅ In Use |
| **Flask** | Asset Manager Backend | ✅ Implemented |
| **Electron** | Desktop App | ✅ Implemented |

#### 🎨 **ART & AUDIO PIPELINE**

| Tool/Process | Purpose | Status |
|--------------|---------|--------|
| **Style 32 (Dark-Chibi Noir)** | Master Art Style | ✅ Locked |
| **Master Reference Pipeline** | Character consistency | ✅ Active |
| **Dialogue Portrait Automation** | Auto-crop portraits | ✅ Done (Python) |
| **Background Removal** | Transparency processing | ✅ Ready |
| **Asset Manager App** | Asset organization | ✅ v1.0 Complete |
| **Placeholder Audio** | Sound FX placeholder | ✅ Python script ready |
| **Localized TTS** | Multi-language voice | ✅ Edge TTS ready |

---

### 🎯 PHASE BREAKDOWN (EPISODIC MODEL)

**Structure:** 10 Episodes (Fazas) released over time.
**Pricing:** Demo (Free) -> Early Access (Ep 1-2) -> Full Game (Ep 10).

---

#### **🎮 DEMO (Free Trial)**
**Goal:** Hook the player, show mechanics, limit progress.

**🌍 Map & Scope:**
- **Restricted:** Home Farm Only (8x8 Micro Plot).
- **Megla:** Invisible walls/fog prevent leaving the farm.

**🔨 Restrictions (The "Tantalizer" Nerf):**
- **Housing:** Sleeping Bag -> Tent -> **Small Shack (MAX)**. Cannot build Mansion.
- **Tools:** **Wood Tier Only** (break fast).
- **Yields:** 1 Seed = 1 Crop + 1 Seed (No massive profit).
- **Trees:** 1 Tree = 1 Log + 1 Sapling (Slow resource gain).
- **Sleep:** No automatic bed. Must craft Tent/Shack to save/sleep.

**🎒 Starter Kit (Free):**
- 1x Wooden Axe, Pickaxe, Hoe, Watering Can.
- 1x Torch, 1x Bread.
- 2x Wheat Seeds, 2x Carrot Seeds.
- **3x Cannabis Seeds** (Taste of the economy!).

**🧟 Characters & Story:**
- **Zombi Statističar:** Stands at gate. Holds sign "Population: 0". Explains you need full game to build town.
- **Quest:** Intro (Amnesia), Control First Zombie ("DIG" command), Find Ana's Bracelet.

---

#### **🔥 EPISODE 1: FAZA 1 (Early Access Start)**
**Goal:** Establish Base, First Biomes, Survival.

**🌍 Map & Scope:**
- **Unlocked Biomes (4):** Grassland (Base), Dark Forest, Desert, Swamp.
- **Bugs/Insects:** Catching enabled immediately (nets).

**🎁 Paid Starter Kit (Premium):**
- **Reinforced Tools** (Iron/Steel).
- **Automatic Sleeping Bag** (Don't need to craft first bed).
- 10x Wheat, 10x Carrot, 5x Potato Seeds.
- **10x Cannabis Seeds**.
- More Food (5 Bread).

**🏆 First 40 Players Bonus (Early Adopter):**
- **INSTANT GRONK:** Gronk appears Day 1 (no quest needed).
- **Roles:**
  - **Builder:** Helps build structures 2x faster.
  - **Carrier:** Huge inventory, carries items to sell.

**🏗️ Systems Unlocked:**
- **Basement Lvl 1:** Zombie Containment Cell (Capture zombies).
- **Basement Lvl 2:** **Grow Room** (Indoor Cannabis/Mushroom farm).
- **Night Delivery:**
  - 🦉 **Owls:** Deliver Packages/Rewards.
  - 🦇 **Bats:** Deliver Quests/Letters.
- **Combat:** Bows & Arrows key.

---

#### **⚡ EPISODE 2: FAZA 2 (Town Restoration)**
**Goal:** Rebuild Civilization, Town Management, Crime.

**🌍 Map & Scope:**
- **Town Unlocked:** The main Hub town becomes accessible.
- **Surrounding Biomes:** Gradual expansion.

**🏘️ BUILD-TO-SPAWN Mechanic:**
*NPCs do not appear randomly. You must build their workplace to summon them.*
1. **Build Big Generator** (Needs Fuel!) -> Spawns **Električar**.
2. **Build Police Station** -> Spawns **Sheriff** (No Gun, Baton/Jail only).
3. **Build Bakery** -> Spawns **Pek** (Baker).
4. **Build School** -> Spawns **Teacher**.
5. **Build Town Hall** -> Spawns **Župan** (Mayor) -> Enables **ORDER** (Before this: Chaos).

**💡 Advanced Systems:**
- **Generator Fuel:** Must keep adding Bio-Fuel/Gas to Big Generator or lights go out (Zombies attack!).
- **Immigration Board:**
  - Managed by Zombi Statističar.
  - Donate Resources -> Build Racial Housing -> **Elves/Gnomes/Axolotls move in!**
  - Real-time Population Counter.
- **City Walls & Watchtowers:** Passive defense.

**💊 Crime & Police System:**
- **Zombie Drug Dealer:**
  - Produce Drugs in Basement Lvl 3 (Lab).
  - Send **Zombie Runner** to town to sell (Stealth).
- **Police Risks:**
  - Sheriff **RAIDS** your basement if suspicion is high.
  - Sheriff **ARRESTS** your Zombie Dealer (You lose the zombie + stash).
  - *Note:* Police do NOT have guns. They use batons/tasers.

**🏛️ Politics:**
- **Town Hall:** Unlocks laws and taxes.
- **Elections:** Mayor is usually set (The "Mayor" NPC), but ensures stability.

---

---

### 📋 CRITICAL PATH TO DEMO

**IMMEDIATE BLOCKERS (🚨 URGENT!):**

1. **Grassland Biome Assets** 🔴
   - Ground tiles (grass, dirt, stone path)
   - Trees (Oak, Pine) - 4 seasons each
   - Props (rocks, bushes, flowers)
   - Farm plot tiles
   - **Estimated:** 150 assets

2. **Character Sprite Sheets** 🔴  
   - Kai (idle, walk, dig, swing) - 20 sprites minimum
   - Ana (idle, walk) - 10 sprites minimum
   - Gronk (idle, walk) - 10 sprites minimum  
   - Susi (idle, walk, run) - 12 sprites minimum
   - **Estimated:** 52 sprites

3. **Basic Zombie** 🔴
   - Idle, walk, attack animations
   - **Estimated:** 15 sprites

4. **Farm Objects** 🔴
   - Farmhouse (small)
   - Barn (small)  
   - Fence sections
   - Crop plots (tilled soil)
   - **Estimated:** 25 assets

**TOTAL FOR DEMO:** ~242 assets (out of 13,500!)

---

### 🔐 DATA INTEGRITY

**Sources Merged:**
- ✅ `scripts/generate_assets_full.py` - Complete 13,500+ asset registry
- ✅ `docs/game_design/GAME_BIBLE.md` v1 - Story, mechanics, systems
- ✅ `SESSION_REPORT_2026_01_06` - Latest generation status
- ✅ `BIOME_MASTER_SPREADSHEET.md` - Biome breakdown
- ✅ `NPC_GENERATION_LIST.md` - Complete NPC registry

**Confirmations:**
- ✅ **Cyclops** - Present in mythical creatures
- ✅ **Minotaur** - Present in mythical creatures
- ✅ **Giant Troll** - Present as boss #19
- ✅ **Zmaj Volk** - Removed from game ❌
- ✅ **Kai & Ana** - 14 years old (NOT 17!)
- ✅ **Giant Troll King** - Final boss ✓
- ✅ **20 Biomes** - Mexican Cenotes + Witch Forest added
- ✅ **109 Creatures** - Including 3 Chupacabra variants

---

## 🎬 JAN 10 2026 ULTRA MARATHON UPDATE

**Session Date:** 10. Januar 2026 (Petek)  
**Duration:** 21+ HOURS! (00:00 - 05:13 CET)  
**Git Commits:** 47 total  
**Status:** ✅ LEGENDARY SUCCESS - INTRO & AGING SYSTEMS COMPLETE

### **PRODUCTION ADDITIONS:**

**📸 Reference Images Generated: 29 Total**

**Aging System References (9):**
- `/assets/references/aging_system/adult_kai_family_man.png` - Age 35, beard, tied dreads
- `/assets/references/aging_system/elder_kai_punk_grandpa.png` - Age 50+, grey dreads, punk grandpa
- `/assets/references/aging_system/mlada_ana_twin_prisoner.png` - Young Ana, twin DNA, RED EYES
- `/assets/references/aging_system/odrasla_ana_scientist.png` - Age 35, scientist, lab coat
- `/assets/references/aging_system/starejsa_ana_mentor.png` - Age 60+, mentor, grey streaks
- `/assets/references/aging_system/otac_punk_father.png` - Father, age 45, RED EYES, gauges
- `/assets/references/aging_system/mati_punk_mother.png` - Mother, age 45, RED EYES, dreads
- `/assets/references/aging_system/ghost_otac_cyan.png` - Ghost father, neon cyan, 50% transparent
- `/assets/references/aging_system/ghost_mati_magenta.png` - Ghost mother, neon magenta, 50% transparent

**Intro Sequence Shots (20):**
- `/assets/references/intro_shots/kai_ana_twins_childhood.png` - Twin bond, childhood
- `/assets/references/intro_shots/kai_adult_35_timelapse.png` - Adult aging timelapse
- `/assets/references/intro_shots/kai_elder_50_timelapse.png` - Elder aging timelapse
- `/assets/references/intro_shots/otac_longboard_pier.png` - Father+son bonding moment
- `/assets/references/intro_shots/virus_xnoir_microscope.png` - Neon green virus visualization
- `/assets/references/intro_shots/zombie_silhouettes_panic.png` - Zombie outbreak chaos
- `/assets/references/intro_shots/kai_bedroom_wakeup.png` - Current day bedroom, survivor aesthetic
- `/assets/references/intro_shots/ana_memory_flash_purple.png` - VHS glitch amnesia fragment
- `/assets/references/intro_shots/ana_barbershop_dreads.png` - Ana getting hair styled
- `/assets/references/intro_shots/birthday_cake_rd.png` - Family birthday celebration
- `/assets/references/intro_shots/parents_transparent_ghosts.png` - Parents fading (30% opacity)
- `/assets/references/intro_shots/ana_taken_military.png` - Ana separation trauma
- `/assets/references/intro_shots/kai_alone_basement.png` - Kai survival Day 01
- `/assets/references/intro_shots/kai_young_timelapse.png` - Current Kai (age 25)
- `/assets/references/intro_shots/chaos_streets_apocalypse.png` - City destruction
- `/assets/references/intro_shots/gronk_doorway_silhouette.png` - Gronk entrance, vape smoke
- `/assets/references/intro_shots/family_portrait_complete.png` - All 4 family members
- `/assets/references/intro_shots/virus_city_aerial.png` - Aerial city infection (88%)
- `/assets/references/intro_shots/kai_first_dreads_family.png` - Kai's first dreads, RED EYES DNA
- `/assets/references/intro_shots/family_portrait_punk_complete.png` - Complete punk family, RED EYES

**📚 Documentation Created: 2,000+ Lines**

- `/docs/game_design/INTRO_SEQUENCE_DESIGN.md` (900+ lines)
  - Version A: 60-second cinematic timeline (6 phases)
  - Version B: 30-45 second fast-cut timeline (3 phases)
  - Complete JavaScript implementation guides
  - Audio timeline specifications
  - Visual effects technical specs
  - Typewriter text script (Slovenian)

- `/assets/references/aging_system/README.md` (200+ lines)
  - Memory vs Reality concept documentation
  - Dual Ana system usage guide
  - Twin DNA markers
  - Narrative notes and emotional impact

- `/TASK_AGING_REFERENCE_GENERATION.md` (400+ lines)
  - Complete workflow for aging references
  - Validation checklists
  - DNK preservation rules
  - File organization standards

- `/SESSION_DNEVNIK_JAN_10_2026_INTRO_AGING_MARATHON.md` (500+ lines)
  - Complete 21+ hour session documentation
  - Timeline breakdown
  - All achievements listed
  - Technical specifications

---

### **NEW GAME SYSTEMS ESTABLISHED:**

**1. GENERATIONAL AGING SYSTEM**

**Concept:** Characters age through 3 distinct life stages over decades of searching for Ana.

**Life Stages:**
- **Young (25):** Current age, full energy, survivor beginnings
- **Adult (35):** Experienced, beard/mature features, more tattoos, muscular
- **Elder (50+):** Grey hair, full wisdom, punk grandpa/grandma, mentor role

**Critical DNA Preservation Rules:**
- ✅ Piercings NEVER removed (identity permanent!)
- ✅ Dreadlocks evolve (color, length, style) but NEVER disappear
- ✅ RED EYES permanent across all ages (family DNA)
- ✅ Punk attitude maintained (rebellion against time!)
- ✅ Tattoos accumulate over time (life story on skin)

**Characters with Aging:**
- **Kai:** Young → Adult (beard, tied dreads) → Elder (grey dreads, "WISDOM NOT WEAKNESS")
- **Ana (Twin Version):** Young (prisoner) → Adult (scientist) → Elder (mentor)
- **Parents:** Appear as middle-aged (45) in happy memories, then as ghosts

**Gameplay Impact:**
- Aging happens during time-skip cutscenes (decades pass searching for Ana)
- Each life stage = different sprite sets (~250+ sprites needed)
- Stats change with age (strength peaks at Adult, wisdom peaks at Elder)
- Different dialogues/reactions from NPCs based on age

---

**2. MEMORY vs REALITY SYSTEM (Ana Dual Version)**

**Philosophical Concept:** Kai's amnesia creates two versions of Ana in his mind.

**Original Ana (Memory/Flashbacks):**
- **Appearance:** Purple/lavender skin, pure magenta hair (no green streaks)
- **Personality:** Cute, slightly spoiled younger sister
- **Usage:** Intro flashbacks, blur-to-clear memories, dream sequences
- **Reference:** `/assets/references/main_characters/ana/master_reference_nobg.png`
- **Narrative Role:** "How Kai remembers his little sister before apocalypse"

**Nova Twin Ana (Reality/Game):**
- **Appearance:** SAME skin tone as Kai, pink AND green dreadlocks, RED EYES
- **Personality:** Fierce scientist, transformed survivor, twin DNA evident
- **Usage:** Main game when Ana is found, all aging stages, present-day reality
- **References:** `/assets/references/aging_system/mlada_ana_twin_prisoner.png` (and aging stages)
- **Narrative Role:** "Who Ana BECAME - apocalypse transformed her into Kai's mirror"

**The "Aha!" Recognition Moment:**
```
INTRO: Shows purple cute Ana (memory)
GAME: Ana found with pink/green dreads and RED EYES
KAI: "Wait... those eyes... that smirk... IT'S HER! My twin!"
RESULT: Amnesia fog clears completely, full memory restored
```

**Recognition Triggers:**
- 🔴 **RED EYES** - Instant DNA match (most obvious!)
- 😏 **Arrogant smirk** - Childhood personality trait preserved
- 🤘 **Specific hand gesture** - Twin habit only they share
- 🗣️ **Voice tone** - Twin resonance, familiar cadence
- 💪 **Fighting stance** - Taught by same mentor (father)

**Narrative Significance:**
- Shows how apocalypse changes people but core identity remains
- "System no change me" - Ana's transformation was CHOICE, not forced
- Twin bond transcends physical appearance
- Memory distortion vs reality = powerful storytelling

---

**3. GHOST QUEST SYSTEM**

**Concept:** Dead parents return as neon spirits to guide Kai to truth.

**Ghost Appearance:**

**Ghost Otac (Cyan):**
- 50% transparent with NEON CYAN outline and rim lighting
- VHS scanline glitch effect (broken memory aesthetic)
- Still holding ghostly longboard skateboard (glowing cyan)
- Sad but peaceful expression - protective even in death
- Reference: `/assets/references/aging_system/ghost_otac_cyan.png`

**Ghost Mati (Magenta):**
- 50% transparent with NEON MAGENTA outline and rim lighting
- VHS scanline glitch effect
- Holding ghostly flowers (glowing magenta)
- The Clash shirt visible through transparency
- Sad but loving expression
- Reference: `/assets/references/aging_system/ghost_mati_magenta.png`

**Quest Trigger:**
- Ghosts appear ONLY after Ana is rescued (not before!)
- Before rescue: Just unclear shadows/mist in fog
- After rescue: Full neon ghost manifestation

**Quest Mechanics:**
- Ghosts don't speak much (silent guidance)
- Float/hover toward location where they died
- Player must follow ghost trail through wasteland
- Lead to final truth about X-Noir virus origin and zombie attack
- Quest completion = emotional closure for Kai

**Haptic Feedback (Xbox Controller):**
- When ghosts near Kai: Controller STOPS aggressive zombie vibration
- Switches to gentle rhythmic pulse (60 BPM heartbeat)
- Creates comfort feeling, not fear
- Signifies: "Parents are here, you're safe"

**Narrative Purpose:**
- Resolves amnesia mystery (what happened to parents?)
- Shows death but maintains dignity (punk ghosts!)
- "They died protecting us" revelation
- Final goodbye/closure moment
- Strengthens theme: Love transcends death

---

**4. FAMILY DNA SYSTEM (RED EYES)**

**Genetic Marker Concept:** RED EYES = Family blood connection

**Who Has RED EYES:**
- ✅ **Otac (Father)** - RED EYES (genetic source)
- ✅ **Mati (Mother)** - RED EYES (genetic match)
- ✅ **Kai** - RED EYES (inherited from both parents)
- ❌ **Ana** - Different eyes (purple skin, different genetic origin?)

**Visual Recognition:**
- All 3 family members (Father, Mother, Kai) have matching RED EYES
- Most obvious when together (family portraits, barbershop scene)
- References: `kai_first_dreads_family.png`, `family_portrait_punk_complete.png`

**Narrative Questions Raised:**
- Why does Ana NOT have red eyes if she's Kai's twin?
- Multiple Ana theories:
  1. **Adopted twin** (different biological origin)
  2. **Genetic experiment** (explains transformation ability)
  3. **Chimera DNA** (two genetic sources merged)
- This mystery can be revealed later in game!

**Punk Transformation Scene:**
- Young Kai gets first dreadlocks at barbershop (age ~8-10)
- Father and Mother watch proudly
- ALL THREE have RED EYES clearly visible
- Shows: "This is where Kai got his punk DNA - from family!"
- Bonding moment: Becoming punk family TOGETHER

**Recognition Power:**
- When Kai sees Ana's RED EYES (twin version), instant recognition
- "Those eyes... they're like mine... FAMILY!"
- Visual DNA proof more powerful than words

---

**5. INTRO SEQUENCE SYSTEM (Dual Timeline)**

**Purpose:** 30-60 second cinematic opening that establishes entire narrative

**Version A: 60-Second Cinematic Timeline**

**Phase 1 (0:00-0:10): Happy Family**
- Shots: Otac longboard, Ana barbershop, birthday cake, family portraits
- Text: *"Nekoč so bile barve resnične..."* (Once colors were real...)
- Audio: Light lo-fi music, children's laughter, ocean waves
- Mood: Warm, nostalgic, golden hour lighting

**Phase 2 (0:10-0:20): The Bond**
- Shots: Kai & Ana twins holding hands, matching DNA visible
- Text: *"Imel sem njo. Imela sva vse."* (I had her. We had everything.)
- Audio: Gentle heartbeat (80 BPM), emotional music continues
- Mood: CLEAREST shot (0 blur) - most important memory!

**Phase 3 (0:20-0:35): The Collapse**
- Shots: X-Noir virus, zombie outbreak, chaos streets, panic
- Text: *"Potem je prišel X-Noir. In svet se je zlomil."* (Then came X-Noir. World broke.)
- Audio: Fast punk rock, sirens, screams, chaos soundscape
- Mood: RED/GREEN color saturation, heavy VHS glitch

**Phase 4 (0:35-0:45): The Loss**
- Shots: Parents becoming transparent (30% opacity), Ana taken by military, Kai alone
- Text: *"Starša sta postala senci... Ana je izginila v temi."* (Parents became shadows... Ana vanished.)
- Audio: Distortion, sudden silence, single heartbeat
- Mood: Dark, traumatic, heavy blur

**Phase 5 (0:45-0:55): Passage of Time** ⭐ **AGING MONTAGE!**
- Shots: Fast cuts - Young Kai → Adult Kai (beard) → Elder Kai (grey dreads)
- Text: *"Leta so postala megla. Obraz se je spremenil... cilj nikoli."* (Years became fog. Face changed... goal never.)
- Audio: Deep noir synth, clock ticking, time-passing whoosh
- Mood: Timelapse blur effect, showcases AGING SYSTEM!

**Phase 6 (0:55-1:00): Amnesia Wake-Up**
- Shots: Maximum blur → Kai's bedroom → Ana memory flash → Gronk entrance
- Text: *"Kdo sem? ... Kje je Ana?"* (Who am I? ... Where is Ana?)
- Audio: Breathing, heartbeat normalizing, vape hiss, Gronk voice: *"No, končno si buden."*
- Mood: VHS filter fades out, transition to gameplay

**Skip Option:**
- After 5 seconds, displays: `[Hold X to face reality]`
- Pressing X skips entire intro, jumps to gameplay
- Saves intro completion flag for returning players

**Version B: 30-45 Second Fast-Cut Timeline**
- 3 phases instead of 6 (Happy → Collapse → Amnesia)
- Faster cuts (3-5 seconds per shot)
- ADHD-friendly energy, rapid impact
- Best for demo/testing, less asset-heavy

**Technical Requirements:**
- 20 intro shot images (all generated! ✅)
- 3 music tracks (happy lo-fi, punk chaos, dark ambient)
- 20+ SFX files (laughter, sirens, heartbeat, vape, etc.)
- VHS scanline shader (custom Phaser PostFX)
- Blur post-processing pipeline
- Typewriter text system (existing DynamicTypewriterSystem)

**Implementation Status:**
- ✅ All 20 reference images generated
- ✅ Complete design document (900+ lines)
- ✅ JavaScript structure provided
- ❌ IntroScene.js not coded yet (~500 lines needed)
- ❌ Audio tracks not sourced yet
- ❌ VHS shader not implemented yet

---

### **ASSET PRODUCTION STATS:**

**Images Generated This Session:**
- Aging System: 9 images
- Intro Shots: 20 images
- **Total:** 29 images (~25MB total, high quality)

**Documentation Written:**
- INTRO_SEQUENCE_DESIGN.md: 900+ lines
- Aging README: 200+ lines
- Task workflow: 400+ lines
- Session Journal: 500+ lines
- **Total:** 2,000+ lines of production documentation

**Git Activity:**
- Commits: 47 in single session
- Files created: 32 new files
- Files modified: Multiple updates to existing references

**Time Investment:**
- Session duration: 21 hours 13 minutes
- Images per hour: ~1.4 images/hour
- Documentation per hour: ~95 lines/hour
- Commits per hour: ~2.2 commits/hour

---

### **STYLE CONSISTENCY VERIFICATION:**

**All 29 Images Follow Style 32 Dark-Chibi Noir:**
- ✅ Thick black outlines (2-3px), cel-shaded rendering
- ✅ Chibi proportions (2:1 head to body ratio)
- ✅ Neon magenta and cyan rim lighting
- ✅ High contrast noir atmospheric lighting
- ✅ VHS grain texture (where appropriate)
- ✅ Scanline glitch effects (memory/ghost shots)
- ✅ Emotional storytelling through composition

**Quality Standards:**
- Average file size: 800KB+ per image (high resolution)
- DNA consistency maintained across all characters
- Facial features match master references
- RED EYES clearly visible where required
- Piercings, gauges, tattoos accurate to lore

---

### **PRODUCTION READY STATUS:**

**✅ COMPLETE & READY:**
- Aging System References (all 3 life stages for Kai & Ana)
- Ghost Parents (both cyan and magenta versions)
- Intro Sequence Design (2 complete timeline versions)
- All 20 Intro Cinemat Shots (full coverage)
- Family DNA System (RED EYES documented)
- Memory vs Reality Concept (dual Ana system)

**🔄 IN PROGRESS:**
- Sprite generation from aging references (~250+ needed)
- IntroScene.js JavaScript implementation

**❌ NOT STARTED:**
- Audio track sourcing/creation (3 music tracks)
- SFX library compilation (20+ effects)
- VHS shader development (custom PostFX)
- Aging system gameplay integration

---

### **UPDATED GAME NARRATIVE:**

**Core Story Enhancement:**

The intro sequence now provides complete emotional foundation:
1. **Happy Past:** Family was whole, punk, loving (before = colors)
2. **Tragic Loss:** X-Noir virus destroys world, parents die, Ana taken (darkness comes)
3. **Time Passage:** DECADES of searching, Kai ages but never gives up (fog years)
4. **Amnesia Fog:** Kai remembers purple Ana, searches for "little sister" (fragmented memory)
5. **Recognition:** Finds twin Ana with pink/green dreads and RED EYES (reality revealed!)
6. **Ghost Closure:** Parents guide to truth as neon spirits (love transcends death)

**Thematic Reinforcement:**
- **"System no change me!"** - Kai's punk identity survives aging (grey dreads at 50+!)
- **Family DNA** - RED EYES connect three generations visually
- **Memory distortion** - Amnesia creates dual Ana (narrative innovation)
- **Dignity in aging** - Elder Kai is PUNK GRANDPA, not weak old man
- **Love transcends** - Parents return as ghosts to protect/guide

---

### **TECHNICAL INTEGRATION NOTES:**

**For Future Implementation:**

1. **Aging System:**
   - Trigger aging during time-skip cutscenes (dialogue: "10 years passed...")
   - Swap character sprite sheets based on age variable
   - Update stats: `if (age >= 35) { wisdom += 20; strength -= 5; }`
   - Different NPC dialogues: "You're looking older, friend..." vs "Young traveler..."

2. **Intro Sequence:**
   - Create new `IntroScene.js` in `/src/scenes/`
   - Load all 20 intro shots in `preload()`
   - Implement phase system with `time.delayedCall()` timing
   - Add blur/glitch PostFX pipelines
   - Integrate DynamicTypewriterSystem for text overlays
   - Skip handler: `input.keyboard.on('keydown-X', () => scene.start('GameScene'))`

3. **Ghost Quest:**
   - Trigger check: `if (anaRescued && !ghostQuestComplete)`
   - Ghost sprites: Use ghost references, apply 50% alpha in code
   - Movement: Ghosts float toward `deathLocation` coordinates
   - Player follows, proximity check triggers lore reveals
   - Quest completion: Play final memory cutscene, unlock achievement

4. **Memory vs Reality:**
   - Flashback scenes: Use original purple Ana sprite
   - Present game: Use twin Ana sprites with RED EYES
   - Recognition scene: Crossfade between both versions with particle effect
   - Dialogue trigger: Ana does specific gesture → Kai: "That move... only she does that!"

---

### **CREATOR NOTES:**

**David's Reflection on 21-Hour Marathon:**

> "This was the longest single session I've ever done. 21+ hours straight, generating 29 images and writing 2,000+ lines of documentation. Why? Because this intro and aging system are the HEART of the game.
>
> The 'Memory vs Reality' concept for Ana is personal - it's about how trauma distorts memory, how people change but core identity remains. The RED EYES family DNA is visual storytelling at its best - you don't need dialogue to show Kai's connection to his parents.
>
> And the aging system... man, this is important. Kai searches for DECADES. Most games would just time-skip and ignore it. Not here. We SHOW the years. We show grey dreads at 50+. We show a punk grandpa who NEVER removed his piercings. Because that's the message: **'System no change me!'**
>
> The intro is designed to make players CRY in 60 seconds. Happy family → Virus destroys everything → Parents die → Ana taken → Decades pass → Still searching.
>
> This game is my life philosophy in pixels: Stay weird. Stay punk. Never let the system win."

**Production Philosophy:**
- Quality over speed (21 hours for 29 images = careful, thoughtful work)
- Narrative depth over shallow gameplay
- Visual DNA storytelling (RED EYES, piercings, dreads)
- Representation matters (punk aging with dignity!)
- ADHD energy channeled into creative marathon

---

## 🔒 **UPDATED STATUS: ZABETONIRAN!**

**Previous Update:** 06.01.2026 21:41 CET (Epic Marathon +53 sprites)  
**Current Update:** 10.01.2026 05:13 CET (Ultra Marathon +29 references +2,000 docs)

**Git Commit:** `3a120c32` (RED EYES DNA - Family Connection Complete!)  
**Date:** 10.01.2026 05:10 CET  
**New Files:** 32 created in this session  
**Backups:** Multiple commits, full Git history preserved ✅

**This is the MASTER game bible**. Use this for all future development!

All data is locked, tracked, and version-controlled. Nothing will be lost! 💪

---

**END OF PRODUCTION GAME BIBLE v2.4 (Updated Jan 10, 2026)**