> cat /wizhelp/wizadvanced6

========================================================================
                  Advanced: Plugin Hooks
========================================================================

Using hooks to modify game behavior without changing core code.

AVAILABLE HOOKS:
- on_combat_hit: After damage is calculated
- on_player_death: When a player dies
- on_player_move: When moving between rooms
- on_heartbeat: Every game tick
- on_war_start/on_war_end: War events

COMBAT HIT HOOK:
```python
def on_combat_hit(attacker, target, weapon, damage, **kwargs):
    """Called after each combat hit"""
    # Example: Area damage weapons
    room = kwargs.get('room')
    if weapon and hasattr(weapon, 'area_damage'):
        # Hit everyone nearby
        for uuid, entity in room.inventory.get_items():
            if entity != attacker and entity != target:
                if hasattr(entity, 'is_player') and entity.is_player:
                    entity.take_damage(damage // 2)
                    entity.message("The blast hits you!")
    
    # Return value not used for this hook
```

PLAYER DEATH HOOK:
```python
def on_player_death(player, killer):
    """Called when a player dies"""
    # Example: Drop special items on death
    if player.war_class == 'kamikaze':
        # Create blood item
        blood = Blood(victim_name=player.name)
        room = player.game_state.rooms.get(player._location)
        if room:
            room.inventory.add_item(blood)
            room.broadcast(f"Blood of {player.name} seeps into the ground.")
```

MOVEMENT HOOK:
```python
def on_player_move(player, from_room, to_room):
    """Called when player changes rooms"""
    # Example: Track movement
    if hasattr(player, 'movement_log'):
        player.movement_log.append({
            'from': from_room,
            'to': to_room,
            'time': time.time()
        })
```

REAL EXAMPLE - AOE/DISARM PLUGIN:
```python
def on_combat_hit(attacker, target, weapon, damage, **kwargs):
    """Add area damage and disarm effects"""
    if not weapon:
        return
    
    room = kwargs.get('room')
    if not room:
        return
    
    # Check for area damage
    if hasattr(weapon, 'area_damage_chance'):
        if random.random() < weapon.area_damage_chance:
            # Hit nearby enemies
            for uuid, entity in room.inventory.get_items():
                if entity != attacker and entity != target:
                    if hasattr(entity, 'is_player'):
                        aoe_damage = int(damage * 0.5)
                        entity.take_damage(aoe_damage)
                        entity.message(f"Area damage hits you!")
    
    # Check for disarm
    if hasattr(weapon, 'disarm_chance'):
        if random.random() < weapon.disarm_chance:
            target_weapon = target.wielded_weapon
            if target_weapon:
                # Disarm the target
                target.unwield()
                target.message("Your weapon is knocked away!")
                attacker.message(f"You disarm {target.name}!")
```

PLUGIN SETUP:
```python
def setup_plugin(game_state):
    """Required setup function"""
    return {
        'name': 'Combat Effects',
        'version': '1.0',
        'author': 'YourName',
        'description': 'Adds special combat effects',
        'commands': {},  # No commands
        'hooks': {
            'on_combat_hit': on_combat_hit,
            'on_player_death': on_player_death
        }
    }
```

HOOK TIPS:
- Hooks run AFTER the action occurs
- Don't modify game_state directly
- Use try/except for safety
- Return quickly to avoid lag
- Test thoroughly with wars

========================================================================    

> _