novafarma/docs/HYBRID_ABILITY_INTEGRATION.md

🔮 HYBRID ABILITY SYSTEM - Integration Guide

System: HybridAbilitySystem.js (600 LOC)
Phase: 36 - Hybrid Skill
Status: ✅ IMPLEMENTED (23.12.2025)

---

🎯 Overview

The HybridAbilitySystem gives the player (as an Alfa) special abilities to interact with and support zombies. This is a unique system that differentiates Krvava Žetev from other zombie games - you're not fighting zombies, you're leading them!

Core Concept:

• Player has Alfa Energy (separate from mana)
• 4 Abilities mapped to Q, E, R, F keys
• Abilities target zombies (not enemies like magic does)
• Synergy with ZombieSystem for worker management

---

⚡ Abilities

1. Q: Heal Zombies 💚

• Cost: 25 Energy
• Cooldown: 8 seconds
• Range: 150 pixels
• Effect: Heals all zombies in range for +30 HP
• Use Case: Keep your zombie workers alive during combat or after hard work
• Visual: Green particles rising from healed zombies

// Execution
this.hybridAbilitySystem.useAbility('healZombies');
// Heals all zombies within 150px radius

---

2. E: Boost Zombies ⚡

• Cost: 30 Energy
• Cooldown: 15 seconds
• Range: 200 pixels
• Duration: 10 seconds
• Effects:
  • +50% movement speed
  • +30% damage (for guards)
  • +50% work efficiency (for farm/mine/gather tasks)
• Use Case: Speed up farming during harvest, boost guards during invasions
• Visual: Yellow aura around boosted zombies

// Execution
this.hybridAbilitySystem.useAbility('boostZombies');

// ZombieSystem queries the buff
const buff = this.hybridAbilitySystem.getZombieBuff(zombieId);
if (buff && buff.type === 'boost') {
    workSpeed *= buff.efficiencyMultiplier; // +50%
}

---

3. R: Calm Wild Zombies 😌

• Cost: 20 Energy
• Cooldown: 12 seconds
• Range: 250 pixels
• Duration: 15 seconds
• Effects:
  • Reduces aggression by 50 points
  • +50% taming success chance
  • Blue tint on calmed zombies
• Use Case: Tame dangerous zombies safely, calm horde during exploration
• Visual: Blue ripple effect

// Execution
this.hybridAbilitySystem.useAbility('calmWildZombies');

// ZombieSystem checks for calm buff during taming
const buff = this.hybridAbilitySystem.getZombieBuff(zombieId);
if (buff && buff.type === 'calm') {
    tameChance += buff.tamingBonus; // +50%
}

---

4. F: Sense Danger 🔍

• Cost: 15 Energy
• Cooldown: 20 seconds
• Range: 400 pixels (large!)
• Duration: 8 seconds reveal
• Effect: Reveals all enemies in range with red outline
• Use Case: Scout before entering dangerous areas, detect ambushes
• Visual: Red pulse expanding from player

// Execution
this.hybridAbilitySystem.useAbility('senseDanger');
// All enemies within 400px get red tint for 8s

---

🔌 Integration with GameScene.js

1. Import & Initialize

// In GameScene.js
import HybridAbilitySystem from '../systems/HybridAbilitySystem.js';

class GameScene extends Phaser.Scene {
    create() {
        // ... other systems ...
        
        // Initialize Hybrid Abilities
        this.hybridAbilitySystem = new HybridAbilitySystem(this);
        
        // IMPORTANT: Initialize AFTER ZombieSystem
        // (HybridAbilitySystem queries zombieSystem)
    }
    
    update(time, delta) {
        // ... other updates ...
        
        // Update Hybrid Abilities
        if (this.hybridAbilitySystem) {
            this.hybridAbilitySystem.update(time, delta);
        }
    }
}

---

2. ZombieSystem Integration

The ZombieSystem needs to query active buffs when executing tasks:

// In ZombieSystem.js executeFarmTask()
executeFarmTask(zombie, delta) {
    // Check for boost buff
    const buff = this.scene.hybridAbilitySystem?.getZombieBuff(zombie.id);
    let efficiencyMultiplier = 1.0;
    
    if (buff && buff.type === 'boost') {
        efficiencyMultiplier = buff.efficiencyMultiplier; // 1.5x
    }
    
    // Apply to work speed
    zombie.taskProgress += (10 * efficiencyMultiplier) * (delta / 1000);
    
    // ... rest of task execution ...
}

Similarly for movement speed in zombie AI:

// In ZombieSystem.js moveTowardsTarget()
moveTowardsTarget(zombie, target) {
    const buff = this.scene.hybridAbilitySystem?.getZombieBuff(zombie.id);
    let speedMultiplier = 1.0;
    
    if (buff && buff.type === 'boost') {
        speedMultiplier = buff.speedMultiplier; // 1.5x
    }
    
    const speed = zombie.speed * speedMultiplier;
    // ... movement logic with boosted speed ...
}

And for damage during guard task:

// In ZombieSystem.js executeGuardTask()
executeGuardTask(zombie, delta) {
    if (zombie.attackTarget) {
        const buff = this.scene.hybridAbilitySystem?.getZombieBuff(zombie.id);
        let damageMultiplier = 1.0;
        
        if (buff && buff.type === 'boost') {
            damageMultiplier = buff.damageMultiplier; // 1.3x
        }
        
        const damage = zombie.damage * damageMultiplier;
        zombie.attackTarget.hp -= damage;
    }
}

---

3. Taming Integration

Check for Calm buff during taming attempts:

// In ZombieSystem.js tameZombie()
tameZombie(zombieId) {
    const zombie = this.zombies.get(zombieId);
    
    // Base taming chance
    let tameChance = this.calculateTameChance(zombie);
    
    // Check for calm buff
    const buff = this.scene.hybridAbilitySystem?.getZombieBuff(zombieId);
    if (buff && buff.type === 'calm') {
        tameChance += buff.tamingBonus; // +0.5 (50%)
        console.log('[ZombieSystem] Calm buff active! +50% taming chance');
    }
    
    // Roll taming
    if (Math.random() < tameChance) {
        // Success!
        zombie.state = 'tamed';
        // ...
    }
}

---

🎮 Player Progression

Ability Unlocks by Level:

Level	Ability	Description
1	Heal Zombies	Starting ability
3	Calm Wild Zombies	Safer taming
5	Boost Zombies	Work efficiency
7	Sense Danger	Enemy detection
10	All abilities fully upgraded	-

XP Sources:

// Player gains Hybrid XP from:
- Zombie levels up: +5 XP
- Zombie dies (inheritance): +2 XP per zombie's final level
- Successful taming: +10 XP (can add in ZombieSystem)
- Quest completion: +50-100 XP

Level Up Logic (TODO):

// In HybridAbilitySystem.js
checkLevelUp() {
    const xpNeeded = this.playerLevel * 100; // 100, 200, 300...
    
    if (this.playerXP >= xpNeeded) {
        this.playerLevel++;
        this.playerXP -= xpNeeded;
        
        // Unlock abilities
        if (this.playerLevel === 3) this.unlockAbility('calmWildZombies');
        if (this.playerLevel === 5) this.unlockAbility('boostZombies');
        if (this.playerLevel === 7) this.unlockAbility('senseDanger');
        
        this.scene.uiSystem?.showMessage(`Hybrid Skill Level Up! Now ${this.playerLevel}`, 0xff00ff);
    }
}

---

🎨 UI Elements

1. Energy Bar (Already Implemented)

• Location: Top-left, below HP/Stamina
• Color: Purple/Pink (Alfa power)
• Size: 200x20 pixels
• Regen: +5 energy/second

2. Ability Icons (TODO - Needs Sprites)

Bottom-Center HUD:
[Q: Heal] [E: Boost] [R: Calm] [F: Sense]
   💚        ⚡         😌        🔍

Each icon shows:
- Ability key (Q/E/R/F)
- Cooldown overlay (if on cooldown)
- Energy cost number
- Locked icon (if not yet unlocked)

3. Quick Implementation:

// In HybridAbilitySystem.js createUI()
createAbilityIcons() {
    const abilities = ['healZombies', 'calmWildZombies', 'boostZombies', 'senseDanger'];
    const keys = ['Q', 'R', 'E', 'F'];
    const startX = 400; // Center bottom
    const y = 550;
    
    abilities.forEach((abilityId, index) => {
        const ability = this.abilities[abilityId];
        const x = startX + (index * 70);
        
        // Background
        const bg = this.scene.add.rectangle(x, y, 60, 60, 
            this.unlockedAbilities.has(abilityId) ? 0x444444 : 0x222222);
        bg.setStrokeStyle(2, 0xffffff);
        bg.setScrollFactor(0);
        bg.setDepth(1000);
        
        // Key label
        const keyText = this.scene.add.text(x, y - 20, keys[index], {
            fontSize: '14px',
            color: '#ffffff'
        }).setOrigin(0.5).setScrollFactor(0).setDepth(1001);
        
        // Energy cost
        const costText = this.scene.add.text(x, y + 20, ability.energyCost, {
            fontSize: '12px',
            color: '#ff00ff'
        }).setOrigin(0.5).setScrollFactor(0).setDepth(1001);
        
        this.abilityIcons.set(abilityId, { bg, keyText, costText });
    });
}

---

🧪 Testing Checklist

Basic Functionality:

• Energy bar displays and updates correctly
• Abilities can be triggered with Q/E/R/F keys
• Energy is consumed on ability use
• Energy regenerates over time
• Cooldowns work (can't spam abilities)

Ability Effects:

• Heal: Zombies regain HP when in range
• Boost: Zombies work faster, move faster, deal more damage
• Calm: Wild zombies become peaceful, easier to tame
• Sense: Enemies are revealed with red outline

Integration:

• ZombieSystem queries buffs during task execution
• Boosted zombies complete tasks 50% faster
• Calm buff increases taming success rate
• Player gains XP from zombie level ups

Visual Feedback:

• Heal shows green particles
• Boost shows yellow aura
• Calm shows blue ripple
• Sense shows red pulse
• Floating text appears on heal

---

💡 Design Notes

Why Separate from MagicSystem?

1. Different resource: Alfa Energy vs. Mana
2. Different targets: Zombies vs. Enemies
3. Different playstyle: Support/control vs. Damage/combat
4. Thematic separation: Hybrid virus powers vs. Magic staffs

Balance Considerations:

• Energy costs prevent spamming (25-30 energy = can only use 3-4 times before depleting)
• Cooldowns force strategic usage (can't just heal constantly)
• Range limits require positioning (get close to zombies to help them)
• Duration limits on buffs (10-15s) mean timing matters

Future Expansions:

• More abilities at Level 10+: Mass resurrection, Zombie frenzy, Alfa roar
• Ability upgrades: Reduce costs, increase range, longer duration
• Combo system: Use 2 abilities in sequence for bonus effect
• Passive aura: Zombies near player get ambient bonuses

---

📁 File Structure

src/systems/
├── HybridAbilitySystem.js (600 LOC) ✅ COMPLETE
├── ZombieSystem.js (900 LOC) ✅ COMPLETE
├── MagicSystem.js (750 LOC) ✅ COMPLETE
└── ... (other systems)

Integration points:
- GameScene.js (initialization)
- ZombieSystem.js (buff queries)
- UISystem.js (energy bar, ability icons)

---

🚀 Next Steps

1. ✅ Phase 36 Abilities: COMPLETE!
2. ⏸️ Dialogue System (zombie speech) - Need implementation
3. ⏸️ Player XP/Level UI - Need UI for skill tree
4. ⏸️ Ability Icon Sprites - Need asset generation

Phase 36 Status: ~70% COMPLETE (up from 50%)

• ✅ Alfa mechanics (ZombieSystem)
• ✅ Hybrid Abilities (HybridAbilitySystem) 🎉
• ⏸️ Dialogue system
• ⏸️ Skill tree UI

---

Created: 23.12.2025 02:08
System: HybridAbilitySystem (600 LOC)
Integration: ~20% coverage increase for Phase 36!