# 🗺️ TILED INTEGRATION MASTER PLAN
**Project:** Krvava Žetev / NovaFarma  
**Date:** 2025-12-22  
**Status:** 🚀 READY TO EXECUTE

---

## 📋 OVERVIEW

### Current Asset Status:
- ✅ **122+ sprite sheets** generated  
- ✅ **3,877 individual objects** processed (50% resized)
- ✅ **3,877 TSX files** auto-generated
- ✅ **Base Tiled setup** complete (grass, dirt, water, decorations)
- 🎯 **Next:** Systematic import of all sprite sheets

### Assets Location:
```
c:/novafarma/assets/
├── krvava_zetev_sprites/          (60 sprite sheets)
├── tiled_sprites/                  (180+ objects)
├── topdown_objects/                (7 sprite sheets)
├── narezano_loceno/                (3,877 individual PNG objects)
│   ├── topdown_objects/            (151 objects)
│   ├── krvava_zetev_sprites/       (915 objects)
│   └── tiled_sprites/              (2,811 objects)
└── tilesets_auto/                  (3,877 TSX files)
```

---

## 🎯 PHASE 1: TILESET ORGANIZATION (PRIORITY)

### Category 1: **Characters & NPCs** (8 sprite sheets)
**Purpose:** Main characters, companions, romantic interests

| Asset | Count | Animation | Priority |
|-------|-------|-----------|----------|
| `kai_character_2x2_grid` | 1 | 4-dir walk | ⭐⭐⭐ |
| `ana_character_2x2_grid` | 1 | 4-dir walk | ⭐⭐⭐ |
| `lena_farmer_2x2_grid` | 1 | 4-dir walk | ⭐⭐ |
| `marija_baker_2x2_grid` | 1 | 4-dir walk | ⭐⭐ |
| `ivan_blacksmith_2x2_grid` | 1 | 4-dir walk | ⭐⭐ |
| `jakob_trader_2x2_grid` | 1 | 4-dir walk | ⭐⭐ |
| `dr_chen_doctor_2x2_grid` | 1 | 4-dir walk | ⭐ |
| `dr_krnic_villain_2x2_grid` | 1 | 4-dir walk | ⭐⭐ |

**Tiled Actions:**
1. Create **External Tileset** for each character
2. Set tile size: **96x96px** (2x2 grid on 48px base)
3. Define **4-direction walk animations**:
   - Down (row 1)
   - Left (row 2)
   - Right (row 3)
   - Up (row 4)
4. Group into: `NPCs/Characters/`

---

### Category 2: **Animals & Pets** (12 sprite sheets)
**Purpose:** Farm animals, companions, breeding system

| Asset | Count | Features | Priority |
|-------|-------|----------|----------|
| `farm_animals_family_grid` | 44 | Breeding families | ⭐⭐⭐ |
| `dog_companions_5_breeds` | 5 | Pet system | ⭐⭐ |
| `rare_livestock_animals` | Multiple | Special breeds | ⭐⭐ |
| `cow` / `chicken` / `pig` | 3 | Basic farm animals | ⭐⭐⭐ |

**Tiled Actions:**
1. Import from `narezano_loceno/krvava_zetev_sprites/`
2. Use pre-generated TSX files from `tilesets_auto/`
3. Organize by type: `Animals/Livestock/`, `Animals/Pets/`, `Animals/Wildlife/`
4. Tag breeding pairs and families

---

### Category 3: **Buildings & Upgrades** (18 sprite sheets)
**Purpose:** Progression system (house/barn/storage stages)

| Asset | Count | Stages | Priority |
|-------|-------|--------|----------|
| `house_progression_5_stages` | 5 | Level 1-5 | ⭐⭐⭐ |
| `barn_progression_4_stages` | 4 | Level 1-4 | ⭐⭐⭐ |
| `storage_upgrades_4_stages` | 4 | Level 1-4 | ⭐⭐⭐ |
| `greenhouse_upgrades_stages` | Multiple | Expansions | ⭐⭐ |
| `buildings_ruins_states` | 26 | Damaged/repaired | ⭐⭐ |

**Tiled Actions:**
1. Create tileset group: `Buildings/Progressive/`
2. Create separate layers for each upgrade stage
3. Setup animation sequences for construction
4. Document upgrade paths

---

### Category 4: **Environment & Terrain** (15 sprite sheets)
**Purpose:** Biomes, trees, weather effects

| Asset | Count | Features | Priority |
|-------|-------|----------|----------|
| `biome_terrain_tiles` | 63 | 5 biomes | ⭐⭐⭐ |
| `trees_topdown_pack` | 16 | Various species | ⭐⭐⭐ |
| `tree_growth_oak/pine/cherry/apple` | 4 sets | Growth stages | ⭐⭐⭐ |
| `grass_soil_tileset` | Auto-tile | Terrain | ⭐⭐⭐ |
| `seasonal_vegetation_4_seasons` | 4 sets | Spring/Summer/Fall/Winter | ⭐⭐ |

**Tiled Actions:**
1. Setup **auto-tiling** for terrain (grass/soil)
2. Create growth animation sequences for trees (4-6 stages)
3. Organize by biome: `Terrain/Grassland/`, `Terrain/Forest/`, etc.
4. Create seasonal variants

---

### Category 5: **Crops & Farming** (12 sprite sheets)
**Purpose:** Growth sequences, seasonal crops

| Asset | Count | Stages | Priority |
|-------|-------|--------|----------|
| `crop_growth_all` | Multiple | 5-6 stages each | ⭐⭐⭐ |
| `wheat_growth` | 6 | Seed → harvest | ⭐⭐⭐ |
| `seasonal_crops_grid` | 4 seasons | Season-specific | ⭐⭐ |
| `fruit_trees_growth` | Multiple | Tree crops | ⭐⭐ |

**Tiled Actions:**
1. Create animation sequences: Planted → Growing → Harvestable
2. Duration: ~300-500ms per frame
3. Group by crop type: `Crops/Wheat/`, `Crops/Vegetables/`, `Crops/Fruits/`
4. Tag seasonal requirements

---

### Category 6: **Weapons & Combat** (8 sprite sheets)
**Purpose:** Combat system, weapon types

| Asset | Count | Types | Priority |
|-------|-------|-------|----------|
| `weapons_melee_grid` | 15+ | Swords, axes, hammers | ⭐⭐ |
| `weapons_firearms_modern` | 10+ | Guns, rifles | ⭐⭐ |
| `bows_5_types` | 5 | Ranged weapons | ⭐⭐ |
| `arrows_9_types_elemental` | 9 | Ammo + elemental | ⭐ |

**Tiled Actions:**
1. Import as object layer items
2. Group: `Items/Weapons/Melee/`, `Items/Weapons/Ranged/`
3. Setup drop tables for loot system

---

### Category 7: **Crafting & Blueprints** (6 sprite sheets)
**Purpose:** Recipe system, progression unlocks

| Asset | Count | Features | Priority |
|-------|-------|----------|----------|
| `blueprints_building_unlocks` | Multiple | Progressive unlocks | ⭐⭐⭐ |
| `crafting_recipes_ui_display` | Multiple | Material requirements | ⭐⭐⭐ |
| `legendary_blueprint_golden` | Rare | Special items | ⭐ |

**Tiled Actions:**
1. Create object type: "Blueprint" with properties
2. Add metadata: `requiredLevel`, `materials[]`, `unlockCondition`
3. Organize: `Items/Blueprints/Building/`, `Items/Blueprints/Equipment/`

---

### Category 8: **Transport Systems** (10 sprite sheets)
**Purpose:** Trains, carts, boats, horses

| Asset | Count | Types | Priority |
|-------|-------|-------|----------|
| `train_repairs_3_states` | 3 | Broken → Rideable | ⭐⭐ |
| `horses_breeds_5_types` | 5 | Mounts | ⭐⭐ |
| `cart_wagon_system` | Multiple | Hauling | ⭐⭐ |
| `water_transport_pack` | Multiple | Kayak, SUP, raft | ⭐ |

**Tiled Actions:**
1. Import as interactive objects
2. Add properties: `speed`, `capacity`, `unlockLevel`
3. Create vehicle spawn points on maps

---

### Category 9: **Magic System** (5 sprite sheets)
**Purpose:** Spells, staffs, potions

| Asset | Count | Features | Priority |
|-------|-------|----------|----------|
| `magic_staffs_6_types` | 6 | Elemental powers | ⭐ |
| `spell_effects_animations` | Multiple | VFX | ⭐ |
| `potions_elixirs_grid` | 12+ | Consumables | ⭐ |

**Tiled Actions:**
1. Import spell effects as animated tiles
2. Group: `Items/Magic/Staffs/`, `Items/Magic/Potions/`
3. Add effect properties

---

### Category 10: **DLC Content - 8 Biome Packs** (30+ sprite sheets)
**Purpose:** Separate biome-specific maps

| DLC | Sprites | Priority |
|-----|---------|----------|
| 🦖 **Dino World** | 10+ | ⭐⭐ |
| 🏔️ **Mythical Highlands** | 8+ | ⭐⭐ |
| 🌴 **Amazon Apocalypse** | 6+ | ⭐ |
| 🏜️ **Desert of the Dead (Egypt)** | 8+ | ⭐⭐ |
| 🌊 **Atlantis** | 6+ | ⭐ |
| ☢️ **Chernobyl** | 5+ | ⭐ |
| 💀 **Paris Catacombs** | 4+ | ⭐ |
| 🦕 **Loch Ness** | 3+ | ⭐ |

**Tiled Actions:**
1. Create **separate TMX maps** for each DLC
2. Import DLC-specific creatures, structures, items
3. Use from: `narezano_loceno/krvava_zetev_sprites/`
4. Document unlock conditions

---

## 🛠️ PHASE 2: ANIMATION SETUP

### Priority Animations:

#### 1. **Tree Growth Sequence**
```
tree_growth_oak_stage_1.tsx  (sapling)
tree_growth_oak_stage_2.tsx  (young)
tree_growth_oak_stage_3.tsx  (mature)
tree_growth_oak_stage_4.tsx  (full grown)
tree_growth_oak_stage_5.tsx  (harvestable)
```
**Duration:** 500ms per frame, Loop: No

#### 2. **Crop Growth Sequence**
```
wheat_stage_1 → wheat_stage_6
carrots_stage_1 → carrots_stage_5
```
**Duration:** 400ms per frame, Loop: No

#### 3. **Character Walk Cycles**
```
kai_down_walk: frames 0-3
kai_left_walk: frames 4-7
kai_right_walk: frames 8-11
kai_up_walk: frames 12-15
```
**Duration:** 150ms per frame, Loop: Yes

---

## 📐 PHASE 3: MAP STRUCTURE

### Recommended Map Hierarchy:

```
maps/
├── main_world_500x500.tmx         (Main game world)
│   ├── Layers:
│   │   ├── 01_Terrain              (Auto-tile grass/soil)
│   │   ├── 02_Water                (Rivers, lakes)
│   │   ├── 03_Paths                (Dirt roads)
│   │   ├── 04_Decorations_Low      (Rocks, flowers)
│   │   ├── 05_Buildings            (Structures)
│   │   ├── 06_Decorations_Tall     (Trees)
│   │   ├── 07_Objects              (Interactive items)
│   │   └── 08_Collision            (Collision boxes)
│
├── starter_farm_16x16.tmx          (Starting area)
├── town_map_32x32.tmx              (NPC hub)
│
├── dlc_dino_world_64x64.tmx
├── dlc_atlantis_48x48.tmx
├── dlc_egypt_64x64.tmx
└── ...
```

---

## ⚡ PHASE 4: IMPLEMENTATION STEPS

### Step 1: Prepare Workspace **(5 min)**
- [ ] Open Tiled Map Editor
- [ ] Navigate to project folder: `c:/novafarma/`
- [ ] Create new folder: `assets/maps/organized_tilesets/`

### Step 2: Import Core Tilesets **(30 min)**
- [ ] Characters (8 tilesets) → `Map → Add External Tileset`
- [ ] Animals (12 tilesets)
- [ ] Buildings (18 tilesets)
- [ ] Environment (15 tilesets)

### Step 3: Setup Animations **(45 min)**
- [ ] Tree growth sequences (4 species × 5 stages)
- [ ] Crop growth (10+ crops × 5-6 stages)
- [ ] Character walks (8 NPCs × 4 directions)

### Step 4: Create Base Maps **(60 min)**
- [ ] `main_world_500x500.tmx` with biomes
- [ ] `starter_farm_16x16.tmx` tutorial area
- [ ] Export all to JSON for Phaser integration

### Step 5: DLC Maps **(90 min)**
- [ ] Create 8 separate DLC maps
- [ ] Import DLC-specific assets
- [ ] Setup spawn points and loot tables

### Step 6: Integration Testing **(30 min)**
- [ ] Export maps to JSON
- [ ] Test in Phaser game
- [ ] Verify animations play correctly
- [ ] Check collision layers

---

## 📊 ESTIMATED TIME

| Phase | Duration | Priority |
|-------|----------|----------|
| Phase 1: Organization | 2-3 hours | ⭐⭐⭐ |
| Phase 2: Animations | 1-2 hours | ⭐⭐⭐ |
| Phase 3: Map Creation | 2-3 hours | ⭐⭐⭐ |
| Phase 4: DLC Maps | 2-3 hours | ⭐⭐ |
| **TOTAL** | **7-11 hours** | - |

**Recommendation:** Break into 3-4 work sessions of 2-3 hours each.

---

## 🎯 SUCCESS CRITERIA

✅ All 122 sprite sheets imported  
✅ Animation sequences configured  
✅ At least 3 playable maps created  
✅ JSON exports working in Phaser  
✅ Collision layers functional  
✅ DLC content separated  

---

## 🚀 READY TO START?

**Next Action:** Choose a starting point:
1. **Quick Win:** Import characters & create starter farm (30 min)
2. **Full System:** Follow Phase 1-6 systematically (7-11 hours)
3. **DLC Focus:** Create one complete DLC map first (2 hours)

---

**STATUS:** ✅ PLAN COMPLETE - READY FOR EXECUTION