# ⚙️ KRVAVA ŽETEV - TEHNIČNA SPECIFIKACIJA

**Verzija:** 1.0  
**Datum:** 31.12.2025, 02:50  
**Platform:** PC (Web-based)

---

## 🎮 1. GAME ENGINE & TEHNOLOGIJA

### **Engine:**
- **Phaser 3** (v3.60+)
- JavaScript ES6+
- HTML5 Canvas rendering

### **Languages:**
- **Frontend:** JavaScript (ES6+)
- **Backend:** Python 3.10+ (scripts, automation)
- **Data:** JSON (configuration, assets, maps)

### **Map Editor:**
- **Tiled Map Editor** (.tmx format)
- Tile size: **32×32 pixels**
- Map layers: Terrain, Objects, Collision, Events

---

## 📁 2. FOLDER STRUKTURA

```
/novafarma/
├── assets/
│   └── slike/              # Slovenska struktura!
│       ├── liki/           # Characters
│       │   ├── kai/        # Kai animations
│       │   ├── gronk/
│       │   ├── ana/
│       │   └── npcs/
│       ├── sovrazniki/     # Enemies
│       │   ├── zombiji/
│       │   └── mutanti/
│       ├── biomi/          # Biomes/Terrain
│       │   ├── 01_dolina_farm/
│       │   ├── 02_temni_gozd/
│       │   └── ...
│       ├── zgradbe/        # Buildings
│       ├── predmeti/       # Items
│       │   ├── orodja/
│       │   ├── hrana/
│       │   └── semena/
│       ├── orozje/         # Weapons
│       │   ├── hladno/     # Melee
│       │   └── strelno/    # Ranged
│       ├── rastline/       # Plants
│       │   ├── posevki/    # Crops
│       │   └── drevesa/    # Trees
│       ├── ui/             # User Interface
│       ├── efekti/         # VFX
│       └── cutscene/       # Story scenes
│
├── scripts/
│   ├── master_asset_pipeline.py
│   ├── batch_generation_manifest.py
│   └── ...
│
├── docs/
│   ├── game_design/
│   │   └── GAME_BIBLE.md
│   ├── KRVAVA_ZETEV_COMPLETE_STORY.md
│   ├── MASTER_ASSET_RAZPREDELNICA.md
│   └── ...
│
└── game/
    ├── index.html
    ├── main.js
    ├── scenes/
    ├── entities/
    └── systems/
```

---

## 🖼️ 3. ASSET SPECIFICATIONS

### **Image Formats:**
- **Format:** PNG (32-bit with alpha channel)
- **Compression:** Optimized for web
- **Naming:** `{category}_{name}_{style}_{version}.png`

### **Asset Sizes:**

| TYPE | ORIGINAL | PREVIEW | SPRITE | USAGE |
|------|----------|---------|--------|-------|
| **Characters** | 1024×1024 | 256×256 | 32×32 | Player, NPCs |
| **Enemies** | 1024×1024 | 256×256 | 32×32 | Zombies, Bosses |
| **Buildings** | 1024×1024 | 256×256 | 64×96 | Structures |
| **Terrain** | 1024×1024 | - | 32×32 | Tileable |
| **Items** | 1024×1024 | 256×256 | 32×32 | Inventory |
| **UI** | Variable | - | Actual size | Buttons, Icons |
| **Cutscenes** | 1920×1080 | - | - | Widescreen |

### **Dual Art Style System:**

| STYLE | NAME | DESCRIPTION | SUFFIX |
|-------|------|-------------|--------|
| **Style A** | Cartoon Vector | Bright, friendly, Stardew-like | `_stylea` |
| **Style B** | Gritty Noir | Dark, hand-drawn, Don't Starve-like | `_styleb` |

**Example:** `mec_lesen_stylea.png` vs `mec_lesen_styleb.png`

---

## 🎨 4. ART STYLE GUIDE

### **Style A - Cartoon Vector:**
```
- Bold black outlines (thick)
- Flat colors, vibrant palette
- Cute, stylized proportions
- White background
- Friendly, approachable
```

**Prompt Template:**
```
[Subject], fantasy farming game asset, 
bold cartoon vector art style with thick black outlines, 
flat colors, cute stylized design, 
centered on white background, 
game sprite ready, 1024x1024
```

---

### **Style B - Gritty Noir:**
```
- Bold black outlines (1.4× emphasis)
- Desaturated, muted colors
- High-contrast noir aesthetic
- Black background
- Dark, mature, post-apocalyptic
```

**Prompt Template:**
```
[Subject], gritty noir survival game asset, 
dark hand-drawn 2D stylized indie art style, 
bold black outlines, 
high-contrast desaturated palette, 
warped perspective,
centered on black background, 
game sprite ready, 1024x1024
```

---

## 🗺️ 5. MAP SYSTEM (Tiled)

### **Tile Specifications:**
- **Tile Size:** 32×32 pixels
- **Grid:** Square grid
- **Infinite:** Yes (procedural generation)

### **Map Layers:**

| LAYER | Z-INDEX | PURPOSE |
|-------|---------|---------|
| **Background** | 0 | Sky, far terrain |
| **Terrain** | 1 | Ground tiles |
| **Decorations** | 2 | Grass, flowers |
| **Collision** | 3 | Walls, obstacles |
| **Objects** | 4 | Buildings, props |
| **Characters** | 5 | NPCs, enemies |
| **Player** | 6 | Kai (always on top) |
| **Effects** | 7 | VFX, particles |
| **UI** | 8 | HUD, menus |

### **Object Properties:**

```json
{
  "name": "zombie_worker",
  "type": "enemy",
  "controllable": true,
  "hp": 40,
  "damage": 0,
  "tasks": ["dig", "plant", "harvest"]
}
```

---

## 🎮 6. GAMEPLAY SYSTEMS

### **A) FARMING SYSTEM**

**Farm Sizes:**
- **8×8** (Start) - Micro farm, 1 tent
- **16×16** (Week 1) - Small farm, shack
- **32×32** (Week 2) - Medium farm, house
- **64×64** (End Game) - Large farm, estate

**Crop Growth:**
```
Stage 1: Seed (0 days)
Stage 2: Sprout (1 day)
Stage 3: Growing (2 days)
Stage 4: Mature (3 days)
Stage 5: Harvestable (4 days)
```

**Automation Tiers:**
- Manual (watering can)
- **Sprinkler 3×3** (covers 9 tiles)
- **Sprinkler 5×5** (covers 25 tiles)
- **Sprinkler 7×7** (covers 49 tiles)
- **Full Auto** (entire farm)

---

### **B) ZOMBIE CONTROL SYSTEM**

**Alpha Hybrid Powers:**
```javascript
class ZombieController {
  maxZombies: level × 2,  // Scales with player level
  commandRange: 500px,     // Telepathic range
  tasks: ['dig', 'plant', 'harvest', 'guard', 'follow'],
  
  controlZombie(zombie) {
    if (this.canControl(zombie)) {
      zombie.faction = 'player';
      zombie.ai = 'commanded';
    }
  }
}
```

**Zombie Features:**
- Sleep in **Grobi** (Graves) → 2× stamina recovery
- Lease to NPCs →  passive income (50 coins/day)
- Death → Decay into fertilizer (+10 soil quality)

---

### **C) COMBAT SYSTEM**

**Stats:**
```
HP (Health Points): 100 base
Stamina: 100 base
Attack Damage: Weapon-dependent
Defense: Armor-dependent
Speed: 100 base (modifiable)
```

**Weapon Types:**

| TYPE | RANGE | DAMAGE | SPEED |
|------|-------|--------|-------|
| **Melee** | 32px | High | Medium |
| **Ranged** | 300px | Medium | Slow |
| **Magic** | 200px | Variable | Medium |

**Combat Mechanics:**
- **Attack:** Click/Tap enemy
- **Dodge Roll:** Spacebar (i-frames)
- **Block:** Hold Shift (50% damage reduction)
- **Critical Hit:** 10% chance, 2× damage

---

### **D) CRAFTING SYSTEM**

**Workstations:**

```json
{
  "campfire": {
    "recipes": ["bread", "cooked_meat"],
    "requirement": "fire"
  },
  "furnace": {
    "recipes": ["iron_bar", "gold_bar"],
    "requirement": "coal"
  },
  "mint": {
    "recipes": ["coin"],
    "requirement": "gold_bar"
  }
}
```

**Recipe Example:**
```json
{
  "bread": {
    "input": {"wheat": 3},
    "output": {"bread": 1},
    "time": 30,  // seconds
    "workstation": "campfire"
  }
}
```

---

### **E) BUILDING RESTORATION**

**Restoration Phases:**

| PHASE | % COMPLETE | VISUAL | FUNCTIONAL |
|-------|------------|--------|------------|
| **Ruined** | 0% | Broken, debris | No |
| **Foundation** | 25% | Base repaired | No |
| **Walls** | 50% | Structure visible | No |
| **Roof** | 75% | Almost complete | No |
| **Complete** | 100% | Pristine | Yes! |

**Material Requirements:**
```json
{
  "gostilna_restoration": {
    "phase1": {"stone": 50, "wood": 30},
    "phase2": {"stone": 100, "wood": 70, "iron": 10},
    "phase3": {"wood": 100, "iron": 20, "nails": 50},
    "phase4": {"wood": 50, "glass": 20}
  }
}
```

---

### **F) NPC SYSTEM**

**NPC Spawn Logic:**
```javascript
class Town {
  npcSlots: 6,  // Max NPCs per town
  
  spawnConditions: {
    "trader": { building: "shop", level: 1 },
    "blacksmith": { building: "smithy", level: 5 },
    "healer": { building: "church", level: 3 }
  },
  
  spawnNPC(type) {
    if (this.meetsCondition(type)) {
      this.npcs.push(new NPC(type));
    }
  }
}
```

**NPC Dialogue System:**
```json
{
  "trader_greeting": [
    "Hello, traveler!",
    "What can I get you?",
    "Looking for seeds?"
  ],
  "trader_quest": {
    "title": "First Trade",
    "description": "Buy 10 wheat seeds",
    "reward": 50
  }
}
```

---

## 📊 7. DATA STRUCTURES

### **Player Data:**
```json
{
  "name": "Kai Marković",
  "level": 1,
  "exp": 0,
  "hp": 100,
  "stamina": 100,
  "position": {"x": 400, "y": 300},
  "inventory": [
    {"item": "wooden_sword", "quantity": 1},
    {"item": "wheat_seeds", "quantity": 10}
  ],
  "farm": {
    "size": "8x8",
    "crops": [],
    "animals": []
  },
  "quests": {
    "ana_clues_found": 0,
    "main_story": "act1_start"
  }
}
```

---

### **Enemy Data:**
```json
{
  "basic_zombie": {
    "hp": 50,
    "damage": 5,
    "speed": 50,
    "ai": "chase_player",
    "loot": [
      {"item": "rotten_flesh", "chance": 0.8},
      {"item": "bone", "chance": 0.2}
    ]
  }
}
```

---

### **Building Data:**
```json
{
  "tent": {
    "type": "housing",
    "size": {"width": 64, "height": 64},
    "cost": {"wood": 0},  // Free (starter)
    "capacity": 1,  // 1 player
    "upgradeTo": "shack"
  }
}
```

---

## ⚡ 8. PERFORMANCE OPTIMIZATION

### **Asset Loading:**
- **Lazy Loading:** Load biome assets on-demand
- **Sprite Atlases:** Combine small assets into atlases
- **Compression:** Use TinyPNG for PNG optimization

### **Rendering:**
- **Culling:** Only render visible tiles
- **Object Pooling:** Reuse zombie/enemy instances
- **Batch Rendering:** Group similar sprites

### **Target Performance:**
- **FPS:** 60 (stable)
- **Load Time:** < 5 seconds (initial)
- **RAM Usage:** < 500MB

---

## 🔊 9. AUDIO SYSTEM

### **Sound Categories:**

| CATEGORY | FILES | FORMAT |
|----------|-------|--------|
| **Music** | Ambient tracks | MP3 (128kbps) |
| **SFX** | Combat, farming | WAV (44.1kHz) |
| **Voice** | NPC dialogue | MP3 (VibeVoice TTS) |

### **Volume Levels:**
- Master: 100%
- Music: 70%
- SFX: 80%
- Voice: 90%

---

## 💾 10. SAVE SYSTEM

### **Save Format:** JSON
### **Save Locations:**
- **Browser:** LocalStorage
- **Cloud:** Optional (future)

### **Auto-Save:**
- Every 5 minutes
- On major events (boss defeat, Ana clue found)
- Before/after cutscenes

### **Save Data Structure:**
```json
{
  "version": "1.0",
  "timestamp": "2025-12-31T02:50:00Z",
  "playtime": 1234,  // seconds
  "player": { ... },
  "world": { ... },
  "quests": { ... }
}
```

---

## 🌐 11. DEPLOYMENT

### **Development:**
- Local server: `http://localhost:8000`
- Hot reload: Enabled

### **Production:**
- **Host:** GitHub Pages / Netlify
- **CDN:** Cloudflare (assets)
- **Domain:** TBD

### **Build Process:**
```bash
1. npm run lint        # Code quality
2. npm run test        # Unit tests
3. npm run build       # Minify & bundle
4. npm run deploy      # Upload to host
```

---

## 📈 12. DEVELOPMENT MILESTONES

### **Phase 1: Kickstarter Demo** (Now - March 2025)
- ✅ 400+ core assets
- ✅ Playable 15-20 min demo
- ✅ Trailer video ready

### **Phase 2: Alpha** (March - June 2025)
- 1,500 assets
- All 180 starter NPCs
- 7 biomes playable

### **Phase 3: Beta** (June - Dec 2025)
- 3,000 assets
- All 18 biomes
- Full story (4 endings)

### **Phase 4: Release** (Jan 2026)
- Polish & bug fixes
- Final balancing
- Launch! 🚀

---

## ✅ TEHNIČNA CHECKA

**Engine:** ✅ Phaser 3  
**Maps:** ✅ Tiled (.tmx)  
**Assets:** ✅ Slovenska struktura (`assets/slike/`)  
**Dual Style:** ✅ Style A + Style B  
**Target:** ✅ 3,000 slik  
**Performance:** ✅ 60 FPS target  
**Platform:** ✅ Web (PC primary)  

---

**ZAPISAL:** Antigravity AI  
**DATUM:** 31.12.2025, 02:55  
**STATUS:** ✅ TEHNIČNA SPEC KOMPLETNA!