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)

• 25 TSX tilesets created across 11 categories
• Organized into folders: Characters, Animals, Buildings, DLC, etc.
• Auto-generated from sprite sheets (122 total available)
• 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):

   • 01_Characters_NPCs/ → Select all 8 TSX files
   • 02_Animals_Pets/ → Select all 4 TSX files
   • 04_Environment_Terrain/ → Import terrain tiles
   • 05_Crops_Farming/ → Import crops
   • 18_Monsters_Bosses/ → Import enemies
   • (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

/**
 * 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:

   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

/**
 * 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:

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

/**
 * 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

/**
 * 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

/**
 * 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