novafarma/docs/IMPLEMENTATION_WORKFLOW.md

# 🚀 IMPLEMENTATION WORKFLOW
**Krvava Žetev - Asset Integration**  
**Date:** 2025-12-22  
**Status:** ✅ TSX FILES CREATED - READY FOR TILED IMPORT

---

## ✅ COMPLETED TASKS

### ✓ Phase 1: Asset Organization (DONE)
- [x] **25 TSX tilesets created** across 11 categories
- [x] **Organized into folders:** Characters, Animals, Buildings, DLC, etc.
- [x] **Auto-generated from sprite sheets** (122 total available)
- [x] **Location:** `c:/novafarma/assets/maps/organized_tilesets/`

**Created Categories:**
```
01_Characters_NPCs      (8 TSX files)   ✅
02_Animals_Pets         (4 TSX files)   ✅
04_Environment_Terrain  (1 TSX file)    ✅
05_Crops_Farming        (1 TSX file)    ✅
10_DLC_Dino_World       (1 TSX file)    ✅
11_DLC_Mythical         (1 TSX file)    ✅
13_DLC_Egypt            (2 TSX files)   ✅
14_DLC_Atlantis         (1 TSX file)    ✅
15_DLC_Chernobyl        (1 TSX file)    ✅
18_Monsters_Bosses      (3 TSX files)   ✅
20_Misc_Items           (2 TSX files)   ✅
```

---

## 📋 REMAINING TASKS

### 🎯 TASK 1: Import Tilesets into Tiled Map Editor

**Status:** 🔲 NOT STARTED  
**Estimated Time:** 30 minutes  
**Priority:** ⭐⭐⭐

#### Steps:
1. **Open Tiled Map Editor**
   ```
   Navigate to: C:\Program Files\Tiled\tiled.exe
   (or wherever you installed Tiled)
   ```

2. **Open or Create Map**
   - Option A: Open existing `micro_farm_128x128.tmx`
   - Option B: Create new map: `File → New → New Map...`
     - Orientation: Orthogonal
     - Tile size: 48x48 pixels
     - Map size: 128x128 tiles (or 500x500 for full world)

3. **Add External Tilesets**
   ```
   Map → Add External Tileset...
   Navigate to: c:/novafarma/assets/maps/organized_tilesets/
   ```

4. **Import by Category (in order):**
   - [x] `01_Characters_NPCs/` → Select all 8 TSX files
   - [x] `02_Animals_Pets/` → Select all 4 TSX files
   - [x] `04_Environment_Terrain/` → Import terrain tiles
   - [x] `05_Crops_Farming/` → Import crops
   - [x] `18_Monsters_Bosses/` → Import enemies
   - [x] (Optional) DLC folders for expansion content

5. **Verify Import**
   - Check **Tilesets panel** (right side)
   - Each tileset should show preview tiles
   - No red "missing file" errors

**✅ Success Criteria:**
- All tilesets visible in Tilesets panel
- Can select tiles and place on map
- No errors in Tiled console

---

### 🎯 TASK 2: Setup Sprite Animation Sequences

**Status:** 🔲 NOT STARTED  
**Estimated Time:** 45 minutes  
**Priority:** ⭐⭐⭐

#### Animation Type 1: Character Walk Cycles

**Example: Kai Character**
1. Select `kai_character_2x2_grid` tileset
2. Click on first frame (tile 0)
3. Right-click → **Tile Animation Editor**
4. Add frames for "Down Walk" animation:
   - Frames: 0, 1, 2, 3 (first row)
   - Duration: 150ms per frame
   - Loop: Yes

5. Repeat for other directions:
   - **Left Walk:** Frames 10-13 (row 2)
   - **Right Walk:** Frames 20-23 (row 3)
   - **Up Walk:** Frames 30-33 (row 4)

6. **Repeat for all 8 NPCs:**
   - Ana, Lena, Marija, Ivan, Jakob, Dr. Chen, Dr. Krnic

**✅ Success Criteria:**
- 8 characters × 4 directions = 32 walk animations
- Animations play smoothly when previewed

---

#### Animation Type 2: Tree Growth Sequences

**Process:**
1. Import individual tree growth stages (from `narezano_loceno/`)
2. Create animation in Tiled:
   ```
   Stage 1 (Sapling)    → 500ms
   Stage 2 (Young)      → 500ms
   Stage 3 (Mature)     → 500ms
   Stage 4 (Full Grown) → 500ms
   Stage 5 (Harvestable) → Hold (no loop)
   ```

3. **Trees to animate:**
   - Oak tree (5 stages)
   - Pine tree (5 stages)
   - Cherry tree (5 stages)
   - Apple tree (5 stages)

**✅ Success Criteria:**
- 4 tree species with growth animations
- Non-looping (plays once, stops at harvestable)

---

#### Animation Type 3: Crop Growth Sequences

**Crops to Animate:**
- Wheat (6 stages)
- Carrots (5 stages)
- Tomatoes (5 stages)
- Seasonal crops (4 seasons × multiple crops)

**Animation Settings:**
- Duration: 400ms per frame
- Loop: No (stops at harvestable stage)

**✅ Success Criteria:**
- 10+ crop growth animations
- All stages transition smoothly

---

### 🎯 TASK 3: Integrate DLC Content into Separate Biome Maps

**Status:** 🔲 NOT STARTED  
**Estimated Time:** 90 minutes  
**Priority:** ⭐⭐

#### Create 8 DLC Maps:

**1. Dino World Map** (`dlc_dino_world_64x64.tmx`)
```
- Size: 64x64 tiles
- Tilesets: 10_DLC_Dino_World/dinosaurs_animation_strips.tsx
- Features: Dinosaur spawns, prehistoric vegetation
- Biome: Jungle/volcanic
```

**2. Egypt Map** (`dlc_egypt_desert_64x64.tmx`)
```
- Size: 64x64 tiles
- Tilesets: 13_DLC_Egypt/egyptian_structures_pack.tsx
- Features: Pyramids, sphinx, sand dunes
- Biome: Desert
```

**3. Atlantis Map** (`dlc_atlantis_48x48.tmx`)
```
- Size: 48x48 tiles
- Tilesets: 14_DLC_Atlantis/atlantis_objects_pack.tsx
- Features: Underwater ruins, aquatic creatures
- Biome: Ocean/underwater
```

**4-8. Repeat for:**
- Mythical Highlands
- Amazon Apocalypse
- Chernobyl
- Paris Catacombs
- Loch Ness

**For Each DLC Map:**
1. Create new map in Tiled
2. Import DLC-specific tilesets
3. Design unique biome layout
4. Add spawn points (Object Layer)
5. Export to JSON

**✅ Success Criteria:**
- 8 separate DLC maps created
- Each with unique biome theme
- JSON exports ready for Phaser

---

### 🎯 TASK 4: Implement Crafting Recipe System in Game Code

**Status:** 🔲 NOT STARTED  
**Estimated Time:** 2-3 hours  
**Priority:** ⭐⭐⭐

#### Create: `src/systems/RecipeSystem.js`

```javascript
/**
 * RecipeSystem.js
 * Manages crafting recipes, blueprints, and material requirements
 */
export default class RecipeSystem {
    constructor(scene) {
        this.scene = scene;
        this.recipes = new Map();
        this.blueprints = new Map();
        this.unlockedRecipes = new Set();
        
        this.initializeRecipes();
    }
    
    initializeRecipes() {
        // Example recipe structure
        this.addRecipe('wooden_fence', {
            name: 'Wooden Fence',
            category: 'Building',
            materials: [
                { item: 'wood', quantity: 5 },
                { item: 'nails', quantity: 2 }
            ],
            craftTime: 2000, // ms
            unlockLevel: 1,
            blueprint: 'blueprint_fence'
        });
        
        // Add all 50+ recipes from sprite sheets
    }
    
    canCraft(recipeId) {
        const recipe = this.recipes.get(recipeId);
        if (!recipe) return false;
        
        // Check if unlocked
        if (!this.unlockedRecipes.has(recipeId)) return false;
        
        // Check materials
        return this.hasRequiredMaterials(recipe);
    }
    
    craft(recipeId) {
        if (!this.canCraft(recipeId)) return false;
        
        const recipe = this.recipes.get(recipeId);
        this.consumeMaterials(recipe);
        
        // Show crafting UI
        this.scene.uiSystem.showCraftingProgress(recipe);
        
        // Wait for craft time
        this.scene.time.delayedCall(recipe.craftTime, () => {
            this.completeCraft(recipe);
        });
    }
    
    unlockBlueprint(blueprintId) {
        this.unlockedRecipes.add(blueprintId);
        this.scene.events.emit('blueprintUnlocked', blueprintId);
    }
}
```

**Integration Steps:**
1. Create `RecipeSystem.js` in `src/systems/`
2. Add to `GameScene.js`:
   ```javascript
   this.recipeSystem = new RecipeSystem(this);
   ```
3. Create crafting UI panel
4. Load recipe data from JSON
5. Test crafting mechanics

**✅ Success Criteria:**
- Can craft items with materials
- Blueprint unlock system working
- UI shows available recipes
- Materials consumed on craft

---

### 🎯 TASK 5: Add Progression System Logic

**Status:** 🔲 NOT STARTED  
**Estimated Time:** 2-3 hours  
**Priority:** ⭐⭐⭐

#### Create: `src/systems/ProgressionSystem.js`

```javascript
/**
 * ProgressionSystem.js
 * Handles house/barn/storage upgrades (5/4/4 stages)
 */
export default class ProgressionSystem {
    constructor(scene) {
        this.scene = scene;
        this.buildingLevels = {
            house: 1,    // Max: 5
            barn: 1,     // Max: 4
            storage: 1   // Max: 4
        };
        
        this.upgradeRequirements = this.loadUpgradeData();
    }
    
    loadUpgradeData() {
        return {
            house: {
                level2: { wood: 100, stone: 50, gold: 500 },
                level3: { wood: 200, stone: 100, gold: 1500 },
                level4: { wood: 400, stone: 200, gold: 3500 },
                level5: { wood: 800, stone: 400, gold: 7500 }
            },
            barn: {
                level2: { wood: 75, stone: 30, gold: 400 },
                level3: { wood: 150, stone: 75, gold: 1000 },
                level4: { wood: 300, stone: 150, gold: 2500 }
            },
            storage: {
                level2: { wood: 50, stone: 25, gold: 300 },
                level3: { wood: 100, stone: 50, gold: 800 },
                level4: { wood: 200, stone: 100, gold: 2000 }
            }
        };
    }
    
    canUpgrade(buildingType) {
        const currentLevel = this.buildingLevels[buildingType];
        const maxLevel = buildingType === 'house' ? 5 : 4;
        
        if (currentLevel >= maxLevel) return false;
        
        const nextLevelReqs = this.getUpgradeRequirements(buildingType, currentLevel + 1);
        return this.hasResources(nextLevelReqs);
    }
    
    upgrade(buildingType) {
        if (!this.canUpgrade(buildingType)) return false;
        
        const currentLevel = this.buildingLevels[buildingType];
        const nextLevel = currentLevel + 1;
        const requirements = this.getUpgradeRequirements(buildingType, nextLevel);
        
        // Consume resources
        this.consumeResources(requirements);
        
        // Upgrade building
        this.buildingLevels[buildingType] = nextLevel;
        
        // Update sprite
        this.updateBuildingSprite(buildingType, nextLevel);
        
        // Emit event
        this.scene.events.emit('buildingUpgraded', { buildingType, level: nextLevel });
        
        return true;
    }
    
    updateBuildingSprite(buildingType, level) {
        // Use progression sprite sheets (e.g., house_progression_5_stages.tsx)
        // Frame = level - 1
        const buildingSprite = this.scene[`${buildingType}Sprite`];
        if (buildingSprite) {
            buildingSprite.setFrame(level - 1);
        }
    }
}
```

**✅ Success Criteria:**
- Buildings upgrade through all stages
- Sprites change visually per stage
- Resources consumed correctly
- UI shows upgrade button when affordable

---

### 🎯 TASK 6: Implement Blueprint Unlock Mechanics

**Status:** 🔲 NOT STARTED  
**Estimated Time:** 1-2 hours  
**Priority:** ⭐⭐

#### Add to `RecipeSystem.js`:

```javascript
unlockBlueprint(blueprintId, method = 'find') {
    if (this.unlockedRecipes.has(blueprintId)) {
        console.warn(`Blueprint ${blueprintId} already unlocked`);
        return false;
    }
    
    this.unlockedRecipes.add(blueprintId);
    
    // Show unlock notification
    this.scene.uiSystem.showNotification({
        title: 'Blueprint Unlocked!',
        message: `You unlocked: ${this.getRecipeName(blueprintId)}`,
        icon: `blueprint_${blueprintId}`,
        duration: 3000
    });
    
    // Save to local storage
    this.saveUnlocks();
    
    // Emit event
    this.scene.events.emit('blueprintUnlocked', { blueprintId, method });
    
    return true;
}

/**
 * Unlock methods:
 * - 'find': Discover in world as loot
 * - 'level': Unlock at certain player level
 * - 'quest': Reward from NPC quest
 * - 'buy': Purchase from trader
 */
findBlueprint(x, y) {
    // Check if player is near blueprint object
    const blueprint = this.scene.blueprintObjects.find(bp => {
        return Phaser.Math.Distance.Between(x, y, bp.x, bp.y) < 50;
    });
    
    if (blueprint) {
        this.unlockBlueprint(blueprint.recipeId, 'find');
        blueprint.destroy(); // Remove from world
    }
}
```

**✅ Success Criteria:**
- Blueprints can be found in world
- Level-up unlocks work
- Quest rewards unlock recipes
- Visual notification on unlock

---

### 🎯 TASK 7: Add Transport System

**Status:** 🔲 NOT STARTED  
**Estimated Time:** 3-4 hours  
**Priority:** ⭐⭐

#### Create: `src/systems/TransportSystem.js`

```javascript
/**
 * TransportSystem.js
 * Handles trains, carts, boats, horses
 */
export default class TransportSystem {
    constructor(scene) {
        this.scene = scene;
        this.vehicles = new Map();
        this.currentVehicle = null;
        
        this.vehicleStats = {
            horse: { speed: 200, capacity: 0 },
            cart: { speed: 120, capacity: 100 },
            train: { speed: 300, capacity: 500, requiresTrack: true },
            kayak: { speed: 150, capacity: 20, waterOnly: true },
            sup: { speed: 100, capacity: 5, waterOnly: true }
        };
    }
    
    mount(vehicleType) {
        if (this.currentVehicle) {
            console.warn('Already mounted on vehicle');
            return false;
        }
        
        const stats = this.vehicleStats[vehicleType];
        if (!stats) return false;
        
        // Change player speed
        this.scene.player.setMaxVelocity(stats.speed);
        
        // Change player sprite
        this.scene.player.setTexture(`player_on_${vehicleType}`);
        
        // Update UI
        this.scene.uiSystem.showVehicleUI(vehicleType, stats);
        
        this.currentVehicle = vehicleType;
        this.scene.events.emit('vehicleMounted', vehicleType);
        
        return true;
    }
    
    dismount() {
        if (!this.currentVehicle) return;
        
        // Restore player speed
        this.scene.player.setMaxVelocity(100);
        
        // Restore player sprite
        this.scene.player.setTexture('player');
        
        // Hide vehicle UI
        this.scene.uiSystem.hideVehicleUI();
        
        this.currentVehicle = null;
        this.scene.events.emit('vehicleDismounted');
    }
    
    canUseVehicle(vehicleType, tile) {
        const stats = this.vehicleStats[vehicleType];
        
        // Check water-only vehicles
        if (stats.waterOnly && !tile.properties.isWater) {
            return false;
        }
        
        // Check train tracks
        if (stats.requiresTrack && !tile.properties.hasTrack) {
            return false;
        }
        
        return true;
    }
}
```

**✅ Success Criteria:**
- Can mount/dismount vehicles
- Speed changes based on vehicle
- Water vehicles only work on water
- Trains follow tracks

---

### 🎯 TASK 8: Magic System Integration

**Status:** 🔲 NOT STARTED  
**Estimated Time:** 2-3 hours  
**Priority:** ⭐

#### Create: `src/systems/MagicSystem.js`

```javascript
/**
 * MagicSystem.js
 * Spell casting, staffs, potions, elemental effects
 */
export default class MagicSystem {
    constructor(scene) {
        this.scene = scene;
        this.spells = new Map();
        this.equippedStaff = null;
        this.mana = 100;
        this.maxMana = 100;
        
        this.initializeSpells();
    }
    
    initializeSpells() {
        this.addSpell('fireball', {
            name: 'Fireball',
            manaCost: 20,
            damage: 50,
            element: 'fire',
            range: 200,
            cooldown: 2000
        });
        
        // Add all spells from magic_staffs_6_types.tsx
    }
    
    castSpell(spellId, targetX, targetY) {
        const spell = this.spells.get(spellId);
        if (!spell) return false;
        
        // Check mana
        if (this.mana < spell.manaCost) {
            this.scene.uiSystem.showError('Not enough mana!');
            return false;
        }
        
        // Consume mana
        this.mana -= spell.manaCost;
        
        // Create spell projectile
        const projectile = this.scene.physics.add.sprite(
            this.scene.player.x,
            this.scene.player.y,
            `spell_${spell.element}`
        );
        
        // Aim at target
        this.scene.physics.moveTo(projectile, targetX, targetY, 300);
        
        // Add particle effects
        this.scene.particleSystem.createSpellEffect(spell.element, projectile);
        
        // Handle collision
        this.scene.physics.add.overlap(projectile, this.scene.enemies, (proj, enemy) => {
            enemy.takeDamage(spell.damage);
            proj.destroy();
        });
        
        return true;
    }
}
```

**✅ Success Criteria:**
- Can equip staffs
- Cast spells with mana cost
- Elemental effects visible
- Potions restore mana/health

---

### 🎯 TASK 9: Breeding/Family Mechanics for Animals

**Status:** 🔲 NOT STARTED  
**Estimated Time:** 2-3 hours  
**Priority:** ⭐⭐

#### Create: `src/systems/BreedingSystem.js`

```javascript
/**
 * BreedingSystem.js
 * Animal breeding, family trees, baby growth
 */
export default class BreedingSystem {
    constructor(scene) {
        this.scene = scene;
        this.animals = new Map();
        this.breedingPairs = new Map();
        
        this.breedingCooldown = 86400000; // 24 hours in ms
    }
    
    canBreed(animal1, animal2) {
        // Must be same species
        if (animal1.species !== animal2.species) return false;
        
        // Must be opposite genders
        if (animal1.gender === animal2.gender) return false;
        
        // Must be adults
        if (animal1.age < 'adult' || animal2.age < 'adult') return false;
        
        // Check cooldown
        if (animal1.lastBred && Date.now() - animal1.lastBred < this.breedingCooldown) {
            return false;
        }
        
        return true;
    }
    
    breed(animal1, animal2) {
        if (!this.canBreed(animal1, animal2)) return null;
        
        // Create baby
        const baby = this.createBaby(animal1, animal2);
        
        // Update parent data
        animal1.lastBred = Date.now();
        animal2.lastBred = Date.now();
        
        // Show notification
        this.scene.uiSystem.showNotification({
            title: 'Baby Born!',
            message: `Your ${animal1.species}s had a baby!`,
            icon: 'baby_' + animal1.species
        });
        
        // Update family tree
        this.updateFamilyTree(animal1, animal2, baby);
        
        return baby;
    }
    
    createBaby(parent1, parent2) {
        const baby = {
            id: this.generateId(),
            species: parent1.species,
            age: 'baby', // baby → young → adult
            gender: Math.random() > 0.5 ? 'male' : 'female',
            parents: [parent1.id, parent2.id],
            birthDate: Date.now(),
            sprite: null
        };
        
        // Create sprite (use children_5_growth_stages.tsx)
        baby.sprite = this.scene.add.sprite(
            parent1.sprite.x + 20,
            parent1.sprite.y,
            `${parent1.species}_baby`
        );
        
        // Setup growth timer (baby → young → adult)
        this.setupGrowthTimer(baby);
        
        this.animals.set(baby.id, baby);
        return baby;
    }
    
    setupGrowthTimer(animal) {
        // Baby → Young (2 days)
        this.scene.time.delayedCall(172800000, () => {
            animal.age = 'young';
            animal.sprite.setTexture(`${animal.species}_young`);
        });
        
        // Young → Adult (5 days)
        this.scene.time.delayedCall(432000000, () => {
            animal.age = 'adult';
            animal.sprite.setTexture(`${animal.species}_adult`);
        });
    }
}
```

**✅ Success Criteria:**
- Animals can breed (male + female)
- Babies spawn with growth stages
- Family tree tracking works
- UI shows breeding status

---

## 📊 PROGRESS TRACKER

| Task | Status | Time | Priority |
|------|--------|------|----------|
| 1. Import Tilesets | 🔲 | 30 min | ⭐⭐⭐ |
| 2. Setup Animations | 🔲 | 45 min | ⭐⭐⭐ |
| 3. DLC Maps | 🔲 | 90 min | ⭐⭐ |
| 4. Crafting System | 🔲 | 2-3 hrs | ⭐⭐⭐ |
| 5. Progression System | 🔲 | 2-3 hrs | ⭐⭐⭐ |
| 6. Blueprint Unlocks | 🔲 | 1-2 hrs | ⭐⭐ |
| 7. Transport System | 🔲 | 3-4 hrs | ⭐⭐ |
| 8. Magic System | 🔲 | 2-3 hrs | ⭐ |
| 9. Breeding System | 🔲 | 2-3 hrs | ⭐⭐ |

**Total Estimated Time:** 14-21 hours

---

## 🎯 RECOMMENDED WORKFLOW

### Session 1: Tiled Import (1 hour)
- ✅ TSX files created
- [ ] Import into Tiled
- [ ] Setup character animations
- [ ] Create starter map

### Session 2: Crafting & Progression (3 hours)
- [ ] Implement RecipeSystem
- [ ] Implement ProgressionSystem
- [ ] Test building upgrades
- [ ] Test crafting UI

### Session 3: Transport & Magic (4 hours)
- [ ] Implement TransportSystem
- [ ] Implement MagicSystem
- [ ] Add vehicle sprites
- [ ] Test spell effects

### Session 4: Breeding & DLC (4 hours)
- [ ] Implement BreedingSystem
- [ ] Create 8 DLC maps
- [ ] Test animal families
- [ ] Export all maps to JSON

---

## ✅ NEXT STEPS

1. **Open Tiled Map Editor**
2. **Import TSX files from:** `c:/novafarma/assets/maps/organized_tilesets/`
3. **Follow TASK 1 instructions above**
4. **Report progress or issues**

---

**STATUS:** ✅ READY TO PROCEED WITH TASK 1